aios/AGENT_TASK_IDENTITY_OVERLAY_DEPLOYMENT.md

Agent execution requirements: V2R1C6 task identity overlay

Required result

The Agent must return one of:

• READY_FOR_CODE_AUTHORING
• BLOCKED
• FAILED

The Agent may not report success until the task branch, isolated worktree and task writer are independently verified.

This stage is not a production deployment. It must not modify main, V2R1C5, tags, Registry, Production Baseline or production services.

Fixed authority

task_id: V2R1C6_TASK_SCOPED_WRITER_PROVISIONING
repository: aios/aios
base_ref: refs/heads/main
base_oid: 875d41c3101093149414292067fd700dc214d4d3
target_branch: agent/v2r1c6-mainline-reconciliation-20260805
owner_identity: aiman
one_time_use: true
maximum_ttl_seconds: 900
production_change_authorized: false
tag_change_authorized: false
baseline_change_authorized: false
main_write_authorized: false

1. Verify package

Verify the externally supplied package against the published SHA-256 values and then verify every entry in MANIFEST.sha256.

Do not synthesize a missing archive. Use either the verified ZIP or TAR.GZ.

Required checks:

package_hash_match: true
manifest_entries_match: true
unit_tests_pass: true
smoke_tests_pass: true
py_compile_pass: true

2. Create root-owned staging

Extract to a fresh directory such as:

/var/lib/aios-gitops/staging/v2r1c6-task-identity-overlay-<nonce>

Requirements:

owner: root
group: root
directory_mode: "0700"
files_not_world_writable: true
symlinks_rejected: true

Do not overwrite the active runtime tree.

3. Re-run target-host tests

From the staging root:

python3 -m unittest discover -s tests -v
python3 scripts/smoke_authorized_task_writer_provisioning.py
python3 scripts/smoke_owner_authorization_broker.py
python3 scripts/smoke_task_identity_overlay.py
python3 -m py_compile \
  active-runtime/app/authorized_task_writer_provisioning.py \
  active-runtime/app/owner_authorization_broker.py \
  active-runtime/app/task_identity_overlay.py \
  active-runtime/app/aios_authorized_task_writer_api.py \
  active-runtime/app/aios_owner_authorization_broker_api.py \
  active-runtime/app/aios_task_identity_overlay_api.py \
  active-runtime/app/aios_task_identity_overlay_cli.py \
  scripts/call_task_identity_overlay.py

Any failure is BLOCKED; do not proceed.

4. Prestart Git and production freeze checks

Read from the authority repository:

git --git-dir=/data/aios-gitops/repo.git rev-parse refs/heads/main
git --git-dir=/data/aios-gitops/repo.git \
  show-ref --verify --quiet \
  refs/heads/agent/v2r1c6-mainline-reconciliation-20260805
git --git-dir=/data/aios-gitops/repo.git rev-parse refs/tags/V2R1C5
git --git-dir=/data/aios-gitops/repo.git rev-parse 'refs/tags/V2R1C5^{}'

Expected:

main_oid: 875d41c3101093149414292067fd700dc214d4d3
target_branch_exists: false
V2R1C5_tag_oid: 9e65bd59baea392294c0f253046d3ab116f63145
V2R1C5_peeled_target: aa60e891547abd7e215af7cf2bf3f21fd23541da

Read Baseline and require:

version: V2R1C5
status: PRODUCTION_DEPLOYED
target_oid: aa60e891547abd7e215af7cf2bf3f21fd23541da
evidence_closure_oid: 5e2cf8276f5093f3352b9a3252c701a44c5ab807

If main has drifted, return:

STATUS: MANUAL_OWNER_REVIEW_REQUIRED
REASON: AUTHORIZED_BASE_OID_DRIFT

If the target branch already exists at another OID, return:

STATUS: MANUAL_OWNER_REVIEW_REQUIRED
REASON: EXISTING_BRANCH_OID_CONFLICT

Do not delete, reset or force-push the branch.

5. Discover active secret references

The overlay does not read or modify gitops.tokens, but its issuer must compare the new random secret against all active bearer secret references.

Discover references without printing secret contents. At minimum include the currently active ChatGPT/GitOps bearer secret reference and any other bearer files consumed by the active API.

Pass them as a comma-separated list in:

AIOS_GITOPS_IDENTITY_OVERLAY_COLLISION_SECRET_REFS

Evidence must contain only paths and SHA-256 match counts, not token values.

If active secret references cannot be enumerated, return:

STATUS: BLOCKED
REASON: ACTIVE_SECRET_REFERENCE_SET_UNRESOLVED

6. Install the transient systemd service

Use the provided template:

deploy/systemd/aios-v2r1c6-task-identity-overlay.service.example

Substitute only:

• verified root-owned staging directory;
• verified active secret-ref path list.

Do not change task ID, repository, base OID, target branch or denied capabilities.

The service must listen only on:

127.0.0.1:19864

Before start, run:

systemd-analyze verify \
  /etc/systemd/system/aios-v2r1c6-task-identity-overlay.service

Then:

sudo systemctl daemon-reload
sudo systemctl start aios-v2r1c6-task-identity-overlay.service

Confirm:

curl --fail --silent http://127.0.0.1:19864/healthz

Expected:

service: aios-task-identity-overlay
status: active
global_token_registry_used: false
loopback_only: true

Do not expose the port externally.

7. Issue the one-time overlay

Use the root-only CLI. The authorization assertion is an audit label for this already approved Owner task; it must not be described as an external signed event.

Example:

sudo env \
  PYTHONPATH=<staging>/active-runtime/app \
  AIOS_GITOPS_IDENTITY_OVERLAY_STATE_ROOT=/var/lib/aios-gitops/task-identity-overlays \
  AIOS_GITOPS_IDENTITY_OVERLAY_SECRET_ROOT=/run/aios-gitops/task-identity-overlays \
  AIOS_GITOPS_IDENTITY_OVERLAY_TASK_ID=V2R1C6_TASK_SCOPED_WRITER_PROVISIONING \
  AIOS_GITOPS_IDENTITY_OVERLAY_OWNER_IDENTITY=aiman \
  AIOS_GITOPS_IDENTITY_OVERLAY_BASE_REF=refs/heads/main \
  AIOS_GITOPS_IDENTITY_OVERLAY_BASE_OID=875d41c3101093149414292067fd700dc214d4d3 \
  AIOS_GITOPS_IDENTITY_OVERLAY_TARGET_BRANCH=agent/v2r1c6-mainline-reconciliation-20260805 \
  AIOS_GITOPS_IDENTITY_OVERLAY_COLLISION_SECRET_REFS=<verified-secret-ref-list> \
  python3 <staging>/active-runtime/app/aios_task_identity_overlay_cli.py \
    issue \
    --ttl-seconds 900 \
    --authorization-assertion-ref owner-session:V2R1C6:approved-20260806 \
    --operator-identity <audited-agent-identity> \
    --result-json /run/aios-gitops/v2r1c6-overlay-issued.json

The result must contain:

status: OVERLAY_ACTIVE
idempotent: false
overlay_id: present
secret_ref: under /run/aios-gitops/task-identity-overlays
expires_at: within 900 seconds

It must not contain a token.

Verify:

secret_file_mode: "0600"
metadata_contains_raw_token: false
token_hash_unique_across_configured_secret_refs: true

8. Negative tests

Before the valid request:

1. No Authorization header must return HTTP 401.
2. A random wrong bearer must return HTTP 401.
3. A request with production_change_authorized=true must be rejected.
4. A request with another base OID or branch must be rejected.
5. The valid overlay must remain ACTIVE after pre-auth request-validation failures.

Do not use the global Owner or ChatGPT bearer credential for this endpoint.

9. Send the valid request

Use:

deploy/v2r1c6-task-writer-authorization-request.json

Use the provided client so the bearer is not placed in argv, shell history or logs:

sudo python3 <staging>/scripts/call_task_identity_overlay.py \
  --secret-ref <secret_ref_from_issue_result> \
  --request-json <staging>/deploy/v2r1c6-task-writer-authorization-request.json \
  --url http://127.0.0.1:19864/api/governance/owner-authorizations \
  --result-json /var/lib/aios-gitops/v2r1c6-overlay-provision-result.json

Required result:

http_status: 200
status: READY_FOR_CODE_AUTHORING
owner_authorization_consumed: true
grant_consumed: true
identity_overlay_consumed: true
identity_overlay_secret_removed: true
branch: agent/v2r1c6-mainline-reconciliation-20260805
branch_oid: 875d41c3101093149414292067fd700dc214d4d3

The result must not include:

• bearer token;
• private key;
• signer secret;
• raw signature;
• credential value.

10. Independent acceptance

Verify the branch:

git --git-dir=/data/aios-gitops/repo.git \
  rev-parse refs/heads/agent/v2r1c6-mainline-reconciliation-20260805

It must equal:

875d41c3101093149414292067fd700dc214d4d3

Verify worktree evidence returned by the provisioner:

branch: agent/v2r1c6-mainline-reconciliation-20260805
head_oid: 875d41c3101093149414292067fd700dc214d4d3
detached_head: false
worktree_clean: true
writer_status: active
writes_enabled: true
allowed_routes:
  - POST /api/commit-file
allow_main_write: false
allow_tag_write: false
allow_baseline_write: false
allow_force_push: false

Run policy negative tests against the task writer and require explicit policy denials for:

• main write;
• another branch;
• tag create/update;
• Baseline write;
• force push;
• branch delete.

Network errors, 404, 500 and stopped-service failures do not count as policy denials.

11. Stop and clean up the overlay

After READY_FOR_CODE_AUTHORING:

sudo systemctl stop aios-v2r1c6-task-identity-overlay.service
sudo systemctl disable aios-v2r1c6-task-identity-overlay.service || true
sudo rm -f /etc/systemd/system/aios-v2r1c6-task-identity-overlay.service
sudo systemctl daemon-reload

Verify:

overlay_listener_stopped: true
overlay_secret_removed: true
global_token_registry_unchanged: true
disabled_owner_record_unchanged: true
active_chatgpt_bot_record_unchanged: true
audit_metadata_retained: true

The root-owned staging directory may be retained until the code is committed, then removed after checksum-confirmed repository integration.

12. Commit the developed code through the task writer

Only after writer acceptance, use POST /api/commit-file to commit the verified package contents to:

agent/v2r1c6-mainline-reconciliation-20260805

Commit in reviewable groups:

1. authorized task-writer bridge;
2. Owner authorization broker;
3. task identity overlay;
4. tests, docs, OpenAPI and deployment templates.

Do not include:

• package archives;
• runtime tokens;
• /run or /var/lib state;
• test result files containing host paths;
• secret references containing values;
• generated credentials.

Run the complete 40-test suite from the branch after commits.

13. Protected PR

Create a protected PR from:

agent/v2r1c6-mainline-reconciliation-20260805

to:

main

The PR must state:

• this change closes Owner authorization bootstrap gaps;
• the overlay is localhost-only and one-time;
• the global token registry is not modified;
• no production release is authorized;
• V2R1C5 tag and Baseline remain unchanged.

The Agent must not merge without the repository's normal protected review.

14. Required Agent report

STATUS:
  READY_FOR_CODE_AUTHORING | BLOCKED | FAILED

PACKAGE:
  zip_sha256:
  tar_gz_sha256:
  manifest_entries:
  manifest_matched:

TESTS:
  unit_total:
  unit_passed:
  smoke_bridge:
  smoke_broker:
  smoke_overlay:
  py_compile:

PRESTART:
  main_oid:
  target_branch_previously_absent:
  V2R1C5_tag_oid:
  V2R1C5_peeled_target:
  baseline_unchanged:

OVERLAY:
  overlay_id:
  status:
  secret_ref:
  secret_file_mode:
  token_hash_unique:
  global_registry_used: false
  listener:
  expires_at:
  consumed:
  secret_removed:

NEGATIVE_TESTS:
  unauthenticated_401:
  wrong_token_401:
  production_capability_denied:
  wrong_base_denied:
  wrong_branch_denied:

OWNER_AUTHORIZATION:
  event_id:
  reference:
  consumed:

GRANT:
  approval_plan_id:
  grant_id:
  grant_digest_sha256:
  signature_valid:
  consumed:

BRANCH:
  name:
  oid:
  base_oid:
  ref_exists:
  worktree_path:
  worktree_clean:

WRITER:
  status:
  writes_enabled:
  allowed_branch:
  allowed_base_oid:
  allowed_routes:
  main_write_denied:
  tag_write_denied:
  baseline_write_denied:
  force_push_denied:

REPOSITORY_INTEGRATION:
  commits:
  tests_after_commit:
  protected_pr:
  merged: false

POSTCHECK:
  main_unchanged:
  V2R1C5_tag_unchanged:
  baseline_unchanged:
  global_token_registry_unchanged:
  overlay_listener_stopped:
  overlay_secret_removed:

SECRETS:
  plaintext_logged: false
  plaintext_committed: false

BLOCKERS:

GOVERNANCE:
  force_push_used: false
  tag_rewritten: false
  direct_main_push: false
  secrets_committed: false
  owner_approval_respected: true

Fail-closed conditions

Return BLOCKED and stop on any of:

• authoritative main OID drift;
• target branch conflict;
• inability to enumerate active secret references;
• secret hash collision;
• overlay not bound to the exact task/base/branch;
• non-loopback listener;
• raw secret in result or logs;
• Owner Authorization Broker event not created;
• signer/validator/provisioner failure;
• grant not consumed;
• branch OID mismatch;
• writer exposes main/tag/Baseline/force-push permissions;
• V2R1C5 tag or Baseline changes.

Never fall back to the shared gitops-write-bot.token, a wildcard credential, manual gitops.tokens edits or a direct Git ref write.