From e0f914d510c081db45cafaf4fe5c8f7b65e46fec Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 14 Jun 2026 22:07:00 -0500 Subject: docs(ai): require an epoch on the tail of helper-agent ids A helper agent's session-context file is .ai/session-context.d/.org. A bare, reused id like "codex" makes the next run resolve to the previous run's leftover anchor, which it then mistakes for a crash to recover or clobbers. That bit on 2026-06-13: a codex run left codex.org for the next session to clean up. The fix is a convention, not a resolver change. The spawner appends an epoch on the tail (host.project.runtime.) so each run gets a fresh anchor. The epoch can't be minted inside session-context-path, since that resolver runs many times per session and must return the same path each call. I documented it in protocols.org, the wrap-up recommended-shape note, and the resolver header. --- .ai/scripts/session-context-path | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to '.ai/scripts/session-context-path') diff --git a/.ai/scripts/session-context-path b/.ai/scripts/session-context-path index 8cc56f6..670a610 100755 --- a/.ai/scripts/session-context-path +++ b/.ai/scripts/session-context-path @@ -10,6 +10,14 @@ # instead of clobbering the singleton. The id is sanitized to filename-safe # characters so a stray value can't escape the .d/ directory. # +# The id must be unique per run; the spawner appends an epoch on the tail +# (recommended shape host.project.runtime.) so a re-run of the same +# logical agent gets a fresh anchor instead of resolving to a prior run's +# leftover. The epoch is never minted here: this resolver is called many times +# per session and must return the same path each call, so it can't generate a +# new value. See protocols.org "Agent-scoped path". A bare, reused id (just +# "codex") is the bug that motivated this note. +# # Workflows call this to resolve the path; both startup (existence check) and # wrap-up (rename source) read/write through it. Callers should fall back to # .ai/session-context.org if this script isn't present yet (older checkouts -- cgit v1.2.3