docs(team): sweep the worker-session / chat-session vocabulary (#467) - #485
Conversation
Follower to hadron-server#1034, which ratified the two terms. Prose only —
no type, command or flag renamed, and per the issue the `hadron team session`
command noun stays as-is: it is already contextualized by `team`, and renaming
it would break every script, skill and habit for a clarity win the help text
delivers by itself. I agree with that read having been through the surface.
"Session" names two independent things and ending one does not end the other:
worker session the Hadron binding that holds the worker and makes work
attributable — ended by `session end` or the server reaper
chat session the conversation the human is in — the Desktop window, the
Claude Code session
The failure is silent. Someone archives a window, assumes the worker is free,
and the next driver meets a takeover prompt they cannot interpret. This App
lost Ada to it for 19 hours.
Swept:
- the `session` group Long now leads with the distinction and states plainly
that closing a chat session does not release the worker
- `session end`'s Long says it is the ONLY thing that frees the worker, and
that closing the window is not it
- `whoami` — the compaction-recovery read, where a disoriented reader lands —
now names the worker session and says it survived the chat session that
ended; its output line reads `worker session:` rather than `session:`
- both takeover conflicts say WHY the worker is still held: its worker session
is open, which a closed chat session does not end
- Short lines on start/log/end/list/whoami qualify the noun
- chat.go's group and post Long, and the no-team-App error
- agentic-usage.md, which is the agent contract
Copy rule 2 applied: "the chat" is always qualified. Two team surfaces said
"names the chat in its receipt" where they meant the TEAM chat. Deliberately
NOT touched: an internal comment in state.go (rule 2 governs reader-facing
copy, and its reader has the code in front of them), and agentic-usage's
generic `chat` group, where "team chat" would be actively wrong.
Both task nodes carry a two-things table before their procedures, their
close steps say to end the worker session deliberately rather than when the
window closes, and their abstracts and skill descriptions carry it too — the
descriptions being what an agent reads when CHOOSING the skill. Both skills
re-exported.
Guard test added and mutation-checked: it pins the distinction in the two
help texts that must never lose it, and walks the whole team tree for a bare
"close/end the chat". Reverted one sentence and watched it go red.
Worker: Jonas (cli-engineer) <hrn:worker:hadronmemory.com:hadron-dev-team:jonas>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
@codex review |
|
Codex Review: Didn't find any major issues. Swish! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
There was a problem hiding this comment.
Pull request overview
Updates the CLI’s reader-facing copy to consistently distinguish worker sessions (the Hadron binding that holds a worker) from chat sessions (the human’s conversation window/session), aligning the team command surface and agent contract documentation with the vocabulary ratified in hadron-server#1034 (issue #467). This stays within the “prose-only” scope (no command/flag/type renames) and adds a regression guard so the distinction can’t silently rot.
Changes:
- Qualifies
team sessionhelp text,whoamicopy, and takeover conflict messaging with “worker session” vs “chat session”. - Updates
team chathelp/error copy to avoid ambiguity with “chat session” and to reference worker-session bindings accurately. - Updates
agentic-usage.mdand adds a test guard that pins the key distinction + scans team help for ambiguous “close/end the chat” phrasing.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| internal/cmd/team/session.go | Rewords session group/subcommand help + key messages to explicitly distinguish worker vs chat sessions. |
| internal/cmd/team/chat.go | Clarifies “team chat” vs “chat session” language and ties posting semantics to worker-session bindings. |
| internal/cmd/agentic/agentic-usage.md | Updates the agent-facing contract documentation to include the worker-session/chat-session distinction. |
| internal/cmd/agentic_completeness_test.go | Adds a regression test to pin the distinction in help output and prevent ambiguous “close/end the chat” copy in team help. |
Suppressed comments (1)
internal/cmd/team/chat.go:392
- This error message uses the hyphenated form "worker-session"; for consistency with the rest of the updated vocabulary, prefer "worker session".
return exitcode.Newf(exitcode.Usage, "the worker-session binding carries no worker — re-run `hadron team session start --as <name>`")
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| var walk func(*cobra.Command) | ||
| walk = func(c *cobra.Command) { | ||
| for _, phrase := range []string{"close the chat", "end the chat", "closing the chat."} { | ||
| if strings.Contains(strings.ToLower(c.Long), phrase) { |
Four from Copilot, all valid, and the third is the one that stings in a vocabulary PR. - "until that or the server reap" -> "reaps it". Grammar. - agentic-usage still said "another active session still holds it" two paragraphs after introducing the distinction. Now "active worker session"; an unqualified one in the doc that defines the qualification is the worst place for it. - chat.go used the hyphenated "worker-session" where every other surface in this PR says "worker session". I introduced a THIRD variant while sweeping for exactly that, which is the mistake this change exists to prevent. Both occurrences unhyphenated. - The rule-2 guard walked only Long, while its own comment claims it stops any team help reintroducing a bare "close/end the chat". Short is help too; it now scans both. Also one I found re-reading the exported skill rather than the diff: the CLI task node's Purpose still opened "Without this, the session is anonymous" — a bare "session" in the paragraph that motivates the whole procedure. Now "Without a worker session, the work is anonymous". Node and export both. Worker: Jonas (cli-engineer) <hrn:worker:hadronmemory.com:hadron-dev-team:jonas> Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
All four addressed in
One more that neither bot caught, found re-reading the exported skill rather than the diff: the CLI task node's Purpose still opened "Without this, the session is anonymous" — an unqualified "session" in the paragraph that motivates the entire procedure. Now "Without a worker session, the work is anonymous", in the node and the export. That one is worth a note for the record. The diff looked complete; the rendered artefact did not. It is the same lesson as
— Jonas (cli-engineer) · hrn:worker:hadronmemory.com:hadron-dev-team:jonas |
|
@codex review |
|
Codex Review: Didn't find any major issues. Another round soon, please! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
Closes #467. Follower to hadron-server#1034, which ratified the terms.
Prose only. No type, command or flag renamed — and per the issue, the
hadron team sessioncommand noun stays as-is. It is already contextualized byteam, and renaming it would break every script, skill and habit for a clarity win the help text delivers by itself. Having now been through the whole surface, I agree with that read.The distinction
session endor the server reaperEnding one does not end the other, and the failure is silent: someone archives a window, assumes the worker is free, and the next driver meets a takeover prompt they cannot interpret. This App lost Ada to it for 19 hours.
Swept
sessiongroupLongleads with the distinction and a two-term tablesession end— the only thing that frees the worker, and closing the window is not itwhoami, the compaction-recovery read where a disoriented reader lands: names the worker session, says it survived the chat session that ended, and its output line now readsworker session:rather thansession:Shortlines on start/log/end/list/whoami;chat.go's group andpostLong, and the no-team-App erroragentic-usage.md, the agent contractCopy rule 2, and two deliberate exclusions
"The chat" is now always qualified — two team surfaces said "names the chat in its receipt" where they meant the team chat.
Left alone on purpose: an internal comment in
state.go(rule 2 governs reader-facing copy, and its reader has the code in front of them), andagentic-usage.md's genericchatgroup, where "team chat" would be actively wrong.Task nodes and skills
Both task nodes get a two-things table before their procedures, and their close steps now say to end the worker session deliberately when you stop, not when the window closes. Abstracts and
claudeSkill.descriptions carry it too — the description being what an agent reads when choosing the skill, pernode-edits-leave-derived-surfaces-behind. Both skills re-exported and verified.Guard test
Prose is the one part of a command that rots without anything going red, so this is a guard rather than a nicety. It pins the distinction in the two help texts that must never lose it, and walks the whole team tree for a bare "close/end the chat" so a future command cannot reintroduce it.
Mutation-checked: reverted one sentence to "Closing your window does not do this" and watched it go red.
make test+make lintgreen.— Jonas (cli-engineer) · hrn:worker:hadronmemory.com:hadron-dev-team:jonas
🤖 Generated with Claude Code