feat(native): export session markers and point doctrine at the shadow #996

Merged

coilysiren merged 1 commit from aos/claude/native-session-markers into main

2026-08-11 21:43:53 +00:00

coilyco-ops commented

2026-08-11 21:15:01 +00:00

Owner

A native session had no way to tell it was already isolated. AOS exported no session marker, and AOS_REPO_ROOT names the canonical checkout, so AGENTS.md told agents to hand-make a worktree in the resolved temporary directory instead.

That location is not durable. Four such worktrees have already been emptied by an OS temp purge (acompose-evals-240, aos-native-ui-236, claude-native-ui-surfaces, and one codex infrastructure session): directory skeletons with zero files and a missing gitdir, which Git reports as prunable. Committed work survived because linked worktrees share the canonical object store. Uncommitted work in them left no trace.

Changes

Export AOS_NATIVE_SESSION and AOS_NATIVE_SESSION_PROJECTS, from the linked-worktree path only. A launch that links no worktree stays in the canonical checkout, where the isolation claim would be false, so it leaves both unset and the pair stays a truthful answer.
Rewrite the AGENTS.md rules around the shadow: a new short section states the markers and the commit-durable / tree-purgeable asymmetry, and the foreign-work rule now scopes itself to sessions without a shadow.
Move mechanics to docs/native-session-shadow.md, and point hand-made worktrees at the platform cache rather than the temporary directory.

The documentation-layout cap on AGENTS.md is deliberate back-pressure, so this displaces rather than extends: mechanics moved to docs and the foreign-work section was compressed. AGENTS.md lands at 287/290 lines and 25997/26000 chars. That char headroom is thin enough to be worth a look.

Verification

ward aos-fmt, ward aos-build, ward aos-lint, ward aos-test (full suite green), and pre-commit run --all-files all pass. New test TestNativeLaunchExportsSessionMarkers asserts both markers match the session lease.

A native session had no way to tell it was already isolated. AOS exported no session marker, and `AOS_REPO_ROOT` names the canonical checkout, so AGENTS.md told agents to hand-make a worktree in the resolved temporary directory instead. That location is not durable. Four such worktrees have already been emptied by an OS temp purge (`acompose-evals-240`, `aos-native-ui-236`, `claude-native-ui-surfaces`, and one codex infrastructure session): directory skeletons with zero files and a missing gitdir, which Git reports as `prunable`. Committed work survived because linked worktrees share the canonical object store. Uncommitted work in them left no trace. ## Changes - Export `AOS_NATIVE_SESSION` and `AOS_NATIVE_SESSION_PROJECTS`, from the linked-worktree path only. A launch that links no worktree stays in the canonical checkout, where the isolation claim would be false, so it leaves both unset and the pair stays a truthful answer. - Rewrite the AGENTS.md rules around the shadow: a new short section states the markers and the commit-durable / tree-purgeable asymmetry, and the foreign-work rule now scopes itself to sessions without a shadow. - Move mechanics to `docs/native-session-shadow.md`, and point hand-made worktrees at the platform cache rather than the temporary directory. The documentation-layout cap on AGENTS.md is deliberate back-pressure, so this displaces rather than extends: mechanics moved to docs and the foreign-work section was compressed. AGENTS.md lands at 287/290 lines and 25997/26000 chars. That char headroom is thin enough to be worth a look. ## Verification `ward aos-fmt`, `ward aos-build`, `ward aos-lint`, `ward aos-test` (full suite green), and `pre-commit run --all-files` all pass. New test `TestNativeLaunchExportsSessionMarkers` asserts both markers match the session lease.

coilyco-ops added 1 commit

2026-08-11 21:15:01 +00:00

feat(native): export session markers and point doctrine at the shadow

ci / ward-doctor (pull_request) Successful in 14s

Details

ci / aos-cli-tests (pull_request) Successful in 31s

Details

ci / gate (pull_request) Successful in 55s

Details

db385b08cd

A native session had no way to tell it was already isolated. AOS exported no
session marker, and AOS_REPO_ROOT names the canonical checkout, so doctrine
told agents to hand-make a worktree in the temporary directory instead. Four
such worktrees have already been emptied by an OS temp purge, leaving directory
skeletons with a missing gitdir.

Export AOS_NATIVE_SESSION and AOS_NATIVE_SESSION_PROJECTS from the linked-
worktree path only, so the pair is a truthful answer to whether the agent is
isolated. Rewrite the AGENTS.md rules around the shadow and move the mechanics
to docs/native-session-shadow.md, displacing rather than extending the base per
the documentation-layout cap rationale.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops requested review from coilysiren

2026-08-11 21:15:01 +00:00