convention: an agent's commit names the session that made it

Three agents committed to this repository in one night and `git log` could not tell
them apart. `Co-Authored-By` says "an agent", which stopped being useful the moment
there was more than one.

So a trailer carrying the transcript id — not the session name, because names are
renamed by restarts and two sessions were renamed in a single night while their
transcript ids survived. The transcript holds the reasoning a commit message
cannot: what was considered and dropped, what was measured, what the owner decided.
A commit that names its session is one whose "why" is still answerable later.

The precondition is not built and is now a todo: an agent cannot reliably discover
its own transcript id. No environment variable carries it and the only exposure is
a background task's output path, so learning who you are means starting a job you
do not need. `commanderBlock` already hands a commander its id, so the mechanism
exists for one case and wants generalising.

Until then: an agent that knows its id adds the trailer, one that does not leaves it
out rather than guessing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043

CLAUDE.md

@@ -361,6 +361,28 @@ withholding the commit until it is good.
 
 Commit messages: simple lowercase, no prefixes.
 
+**An agent's commit names the session that made it.** A trailer, below `Co-Authored-By`:
+
+```
+Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043
+```
+
+The transcript id, not the session name — names are not stable. On 2026-08-23 one session was
+`platform-e2` and then `platform-18`, and another `platform-59` then `platform-72`, both renamed by a
+restart in a single night. The transcript id survived both.
+
+Why it earns a line in every commit: three agents committed to this repository in one night and `git log`
+could not tell them apart. `Co-Authored-By` says "an agent", which stopped being useful the moment there was
+more than one. And the transcript holds the reasoning a commit message cannot — the arguments considered and
+dropped, what was measured, what the owner decided and why. A commit that names its session is a commit
+whose "why" is still answerable in six months.
+
+**The precondition, and it is not built yet:** an agent cannot reliably discover its own transcript id. The
+only exposure is that a background task's output path contains it, which means starting a job to learn who
+you are. `commanderBlock` already hands a commander its id in the preamble, so the mechanism exists —
+`todo/agent-coordination/` carries giving it to every session. Until then, an agent that knows its id should
+add the trailer and one that does not should leave it out rather than guess.
+
 ## Frontend route conventions (apply to EVERY new dashboard route)
 
 Worked examples: `/soulseek`, `/music`, `/chat`.

todo/agent-coordination/an-agent-cannot-learn-its-own-session-id.md

@@ -0,0 +1,36 @@
+---
+id: agent-coordination/an-agent-cannot-learn-its-own-session-id
+title: 'An agent cannot learn its own transcript id, so it cannot sign its own work'
+theme: agent-coordination
+status: open
+created: 2026-08-23
+date_source: stated
+order: 2
+---
+
+**An agent has no reliable way to find out its own transcript id**, which blocks the commit convention in
+`CLAUDE.md` — "an agent's commit names the session that made it."
+
+Searched on 2026-08-23. No environment variable carries it. `~/.claude/sessions/` is keyed on process id, not
+transcript. The only exposure found is indirect: a background task's output path contains it
+(`/tmp/claude-1000/<project>/<transcript-id>/tasks/<id>.output`), so an agent can learn who it is by starting
+a job it does not need and reading the path back. That works and it is absurd.
+
+**The mechanism already exists for one case.** `commanderBlock` in `api/command-hq/commander-block.ts` hands
+a commander its own transcript id, because a commander needs it to write its pid and spawned records. So the
+platform knows the id at turn time and can already put it in a preamble — it just does that for commanders
+only.
+
+What to build: give every session its own id the same way. One line in whatever preamble a session already
+receives, phrased as a fact rather than an instruction.
+
+Two things to get right:
+
+- **The transcript id, never the session name.** Names are renamed by restarts — two sessions were renamed
+  in one night on 2026-08-23 — and a commit trailer naming something that no longer exists is worse than no
+  trailer.
+- **It unblocks more than the trailer.** The delegation problem in this theme is keyed on transcript ids too,
+  and a manager cannot record "I am X" in a delegation row it cannot name itself in.
+
+Until it lands: an agent that happens to know its id adds the trailer, and one that does not leaves it out
+rather than guessing.