@erclx/canon 5.70.0 → 5.71.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [5.71.0](https://github.com/erclx/canon/compare/v5.70.0...v5.71.0) (2026-10-27)
+
+
+### Features
+
+* **markdown:** read colon lists as labels ([#2797](https://github.com/erclx/canon/issues/2797)) ([f733a5f](https://github.com/erclx/canon/commit/f733a5f8d74e63cf5e257557a4d227b3478ca04a))
+* **tasks:** name the sessions behind a task on a Sessions line ([#2799](https://github.com/erclx/canon/issues/2799)) ([acf80c4](https://github.com/erclx/canon/commit/acf80c4ce9d2c1adbc3e1ea2dfde433a08d46b4e))
+
 ## [5.70.0](https://github.com/erclx/canon/compare/v5.69.0...v5.70.0) (2026-10-27)
 
 

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.70.0",
+  "version": "5.71.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/git-pr/references/task-number.md

@@ -29,6 +29,19 @@ The verb resolves the board at the main worktree root in-process, the root `sess
 - A line already reading as a list of `#NNN` entries takes the new number appended, reported as `appended`, so a task shipped in slices keeps every pull request
 - The same write drops this branch from the `Pending branch:` line `canon tasks outcome` wrote, which lets the merge-time archive close the task
 
+## Record the session
+
+Beside the number, name this session on the same task's `Sessions:` line. It is the one record that covers a hand-launched worker, which no dispatcher saw start. Read the id from the roster's own row for the caller, then hand it to the verb under the same plan:
+
+```bash
+id=$(canon sessions list --self --json | jq -r '.sessions[0].sessionId // empty')
+[ -n "$id" ] && canon tasks session "$id" --plan feature-<slug> --json
+```
+
+- A dispatched worker is already listed, since its dispatcher recorded it at launch, and the verb reports `unchanged` rather than writing it twice
+- An empty `id` means the roster could not name the caller, so skip the write and report that no session was recorded
+- Skip the same three refusals as the number below, and report `bad-input` or `no-name`, since either is a defect in this call
+
 ## Refusals
 
 Skip silently when the record is `ok: false` and `reason` is `no-board`, `no-match`, or `ambiguous`, meaning no board, no task naming the plan, or more than one. A guessed write would compound each, since a wrong match archives the wrong task unattended once the branch merges. Report any other refusal rather than swallowing it.

package/claude/skills/markdown-craft/references/markdown.md

@@ -134,6 +134,7 @@ A bullet's punctuation follows its sentence count, and a list opens unannounced.
 
 - Do not use em dashes (`—`) or semicolons (`;`). Rewrite or restructure the sentence to avoid them. A colon or a comma standing where the dash was is the same sentence, so split it or rewrite it.
 - Do not use a colon to join two clauses in the middle of a sentence. A colon belongs after a label or at the end of a line introducing a list.
+- The check misses a clause colon in a list of colon items, but it is wrong.
 - Do not use parenthetical asides in prose (`the config (which is optional) controls...`). Split into its own sentence or drop it. Parentheses in rule definitions for grouping examples are fine.
 
 ## Language

package/claude/skills/role-orchestrator/references/orchestrator-cloud-launch.md

@@ -86,6 +86,7 @@ The readout is the text `Created cloud session: <title>`, unanchored since a ter
 - On a failed create, report the typescript's last lines and fall back to the human-launch line in `orchestrator-dispatch.md`
 - The wrapper is a stopgap any change to the interactive create screen breaks, which is why the readout fails loudly instead of guessing
 - Record `session` beside the row's branch in this pass's launched record, since that and the pull request list are the only readings that know it exists
+- Name it on the row's task with `canon tasks session "$session" <task> --name cloud-<project>-<slug> --json`, since a cloud worker has no board and the roster never lists it
 - Report the dispatch as the local shape does, naming the row, the plan, the repository, and the session id in place of a session name
 
 ## Recognize the pull request

package/claude/skills/role-orchestrator/references/orchestrator-launch.md

@@ -1,6 +1,6 @@
 ---
 title: Orchestrator launch runbook
-description: The launch every dispatch kind shares, being the build, cloud build, review-address, planning, and talk templates, the session name and controller id each carries, why the command sits at position zero, and what the brief may carry
+description: The launch every dispatch kind shares, being the build, cloud build, review-address, and planning templates with a pointer to the talk variant, the session name and controller id each carries, why the command sits at position zero, and what the brief may carry
 ---
 
 Run this once `orchestrator-dispatch.md` has cleared a row, or from its planning or review-address shape below when that runbook's checks do not bind. The model each template names comes from `## Pick the model` in that runbook.
@@ -79,6 +79,10 @@ The prompt carries pointers and standing context, and stops there. The branch an
 
 Report the dispatch as loudly as the human-launch line it replaces, naming the branch, the model, the task, and the session name, so a person reading the transcript can follow what fired without watching it happen.
 
+### Record the worker on its task
+
+Once a build or review-address launch returns, run `canon tasks session <worker-id> <task> --json` with the sessionId the launch output carries. On `no-name`, the worker already exited, so rerun with `--name` and the name passed to `-n`.
+
 ## Dispatch to a cloud worker
 
 Read `${CLAUDE_SKILL_DIR}/references/orchestrator-cloud-launch.md` when `orchestrator-dispatch.md` picked cloud for the row. It holds the prompt that carries the plan as text and announces over GitHub, the create under `script`, and the readout that refuses to record a missing session id.
@@ -137,25 +141,7 @@ Hold all planning of a row any talk session has said by message it is planning,
 
 ## Dispatch a talk session
 
-A planner or worker the operator will talk with takes the same launch as its cold shape above, with a `-talk` suffix on its name and one sentence added to its brief. A cold session works alone and reports back, and a talk session stays open after its plan or pull request lands so the operator can keep shaping the row.
-
-```bash
-claude --bg --model <model> -n "planner-<project>-<slug>-talk" "Run /canon:role-planner, then /canon:plan-feature <task>. This is a talk session: the operator will talk with you here, so run your role's talk clause, and message your controller when the operator ends the conversation. Your controller is the session whose sessionId is <dispatcher-id>. ..."
-claude --bg --model <model> -n "worker-<project>-<slug>-talk" "/canon:auto-ship <plan>
-This is a talk session: the operator will talk with you here, so run your role's talk clause, and message your controller when the operator ends the conversation. Your controller is the session whose sessionId is <dispatcher-id>. ..."
-```
-
-The ellipsis stands for the rest of the cold template's message clauses, unchanged. The build variant keeps `/canon:auto-ship <plan>` at position zero with nothing before it, per the rule above.
-
-- Keep the role prefix and add the suffix, since `orchestrator-handoff.md` separates dispatched sessions by `worker-` and `planner-` and a new prefix reads as a hand launch
-- A talk session is retired only on the operator's word, stated once in `orchestrator-handoff.md`, so do not restate it in a launch report
-- Reviewers get no talk shape, since a reviewer's pass holds no operator dialogue
-
-### Recording the talk session
-
-Read the session's `sessionId` off the launch output, carry it in this session's own context, and write it into the map's `## Talk sessions held open` at the next handoff. The client can rename a session and drop the suffix, so the id is the durable marker and the suffix is only for display.
-
-The map exists only once the handoff writes it, so this session's own launches, read with the prior map, are what the first wind-down reads talk sessions from.
+Read `${CLAUDE_SKILL_DIR}/references/orchestrator-talk-launch.md` when the operator will talk with a planner or worker rather than leave it to report back. It states the `-talk` name suffix, the one sentence the brief adds, and where the session's id is kept for the handoff.
 
 ## Hand launch
 

package/claude/skills/role-orchestrator/references/orchestrator-reviewer-launch.md

@@ -21,6 +21,16 @@ claude --bg --model <model> -n "reviewer-<project>-<number>" "Run /canon:role-re
 - Append the cross-branch facts after the controller clause, per `### What the brief may carry` in `orchestrator-launch.md`
 - Check `canon sessions list --json` for a live `reviewer-<project>-<number>` before launching, and message it instead when one holds the pull request
 
+### Record the reviewer on the task
+
+A reviewer writes no task file, so this session names it on the task the pull request closes, through the sessionId the launch output carries:
+
+```bash
+canon tasks session <reviewer-id> <task> --json
+```
+
+Record the UI reviewer below the same way after its launch. A `no-name` refusal means the reviewer exited before the read, so rerun with `--name` and the name the launch passed to `-n`.
+
 ### The channel clauses
 
 The channel clauses restate what `role-reviewer` holds, so a reviewer whose plugin cache predates that body still sends the dispatch itself. The worker reads the reviewer's sessionId off that message and sends its re-review request back to it, since a reviewer holds the trunk branch and no branch lookup finds it.

package/claude/skills/role-orchestrator/references/orchestrator-talk-launch.md

@@ -0,0 +1,30 @@
+---
+title: Orchestrator talk launch
+description: The talk variant of the planning and build launches, being the name suffix, the one added brief sentence, and where the talk session's id is recorded for the handoff
+---
+
+Run this when the operator wants to talk with a planner or worker rather than leave it to report back. The rules every launch shares stay in `orchestrator-launch.md`.
+
+# Talk launch
+
+## The launch
+
+A planner or worker the operator will talk with takes the same launch as its cold shape in `orchestrator-launch.md`, with a `-talk` suffix on its name and one sentence added to its brief. A cold session works alone and reports back, and a talk session stays open after its plan or pull request lands so the operator can keep shaping the row.
+
+```bash
+claude --bg --model <model> -n "planner-<project>-<slug>-talk" "Run /canon:role-planner, then /canon:plan-feature <task>. This is a talk session: the operator will talk with you here, so run your role's talk clause, and message your controller when the operator ends the conversation. Your controller is the session whose sessionId is <dispatcher-id>. ..."
+claude --bg --model <model> -n "worker-<project>-<slug>-talk" "/canon:auto-ship <plan>
+This is a talk session: the operator will talk with you here, so run your role's talk clause, and message your controller when the operator ends the conversation. Your controller is the session whose sessionId is <dispatcher-id>. ..."
+```
+
+The ellipsis stands for the rest of the cold template's message clauses, unchanged. The build variant keeps `/canon:auto-ship <plan>` at position zero with nothing before it, per `### Position zero` in `orchestrator-launch.md`.
+
+- Keep the role prefix and add the suffix, since `orchestrator-handoff.md` separates dispatched sessions by `worker-` and `planner-` and a new prefix reads as a hand launch
+- A talk session is retired only on the operator's word, stated once in `orchestrator-handoff.md`, so do not restate it in a launch report
+- Reviewers get no talk shape, since a reviewer's pass holds no operator dialogue
+
+## Recording the talk session
+
+Read the session's `sessionId` off the launch output, carry it in this session's own context, and write it into the map's `## Talk sessions held open` at the next handoff. The client can rename a session and drop the suffix, so the id is the durable marker and the suffix is only for display.
+
+The map exists only once the handoff writes it, so this session's own launches, read with the prior map, are what the first wind-down reads talk sessions from.

package/claude/skills/task-board/references/tasks-record-lines.md

@@ -0,0 +1,40 @@
+---
+title: Task record lines reference
+description: The lines a verb writes on a task below its origin lines, being the Pull request line that lets a merge close its task, the Pending branch marker that holds that merge back, and the Sessions line naming who worked it
+---
+
+# Task record lines reference
+
+Applies to the lines a task carries under its origin lines that no session writes by hand. Each one has a `canon tasks` verb as its writer, and this file fixes what each line means and who calls that verb.
+
+This is an attribute standard. It governs lines inside a task file rather than a file of its own, so it carries no template.
+
+## Scope
+
+Governs the `Pull request:`, `Pending branch:`, and `Sessions:` lines.
+
+Does not govern:
+
+- The task file's layout, filename, format, origin lines, and archiving: `tasks.md`
+- The `Declined:` line: `tasks-decline.md`
+
+## The `Pull request:` line
+
+`Pull request:` lists every pull request that shipped part of the task as bare numbers, oldest first and comma-separated, as in `Pull request: #NNN, #NNN`. It is not an origin, so a task without one is well-formed, and `git-pr` appends to it when a pull request opens.
+
+The line lets a merge close its own task. `canon tasks archive --pull-request <n>` finds the task by any listed number and archives it only on the last.
+
+- One pull request, one task. Two tasks naming the same number refuse to archive rather than both moving.
+- `Pending branch: <branch>` holds that merge back while a branch that ticked an outcome waits on its own number
+- `canon tasks outcome` writes that line, skipping it when the branch's pull request is already listed, and `canon tasks pull-request` clears it
+
+## The `Sessions:` line
+
+`Sessions:` names each session that built or reviewed the task, by roster name and full sessionId, as in `Sessions: <name> (<sessionId>), <name> (<sessionId>)`. A retro or a regression hunt reaches each transcript through `canon sessions export <sessionId>`, which takes the full id alone. It is not an origin either.
+
+- `canon tasks session <sessionId> <task>` writes it, or `--plan <slug>` in place of the stem, so it is never hand-edited
+- The verb reads the name off the live roster. A session that already exited takes `--name`, and so does a cloud session's `session_` id, since the roster never lists one.
+- The id is the key. A repeat call for a listed id keeps the name first recorded, so two callers recording one worker write it once.
+- The dispatcher records each worker and reviewer it launches, and `git-pr` records the session opening the pull request, which covers a hand launch
+
+The line sits below the origin, `Pull request:`, and `Pending branch:` lines. `canon tasks validate` reports a line that does not parse as name and id pairs as `sessions-misshapen`.

package/claude/skills/task-board/references/tasks.md

@@ -29,6 +29,7 @@ Governs the task files under `.canon/tasks/`: folder layout, filenames, frontmat
 Does not govern:
 
 - **`tasks-decline.md`**: the declined folder, the `Declined:` line, and what declining does to a plan and a board row
+- **`tasks-record-lines.md`**: the `Pull request:`, `Pending branch:`, and `Sessions:` lines a verb writes below the origin lines
 - **`board.md`**: execution order, readiness groups, the backlog, and the generated index beside the tasks
 - **`plan.md`**: the plan file a task cites, its sections, and its answer contract
 - **`versioning.md`**: phase-label format and which surfaces a label may appear on
@@ -112,6 +113,7 @@ Groundwork: [<slug>](../groundwork/<slug>/)
 Intake: [<slug>](../intake/<slug>/)
 Issue: #NNN
 Pull request: #NNN
+Sessions: <name> (<sessionId>)
 
 Why this task exists and what it depends on.
 
@@ -165,15 +167,9 @@ Three rules cover the line itself:
 - Use `Intake:` rather than `Groundwork:` for an intake pass, so the line records which kind of pass produced the task
 - `Intake:` names the folder rather than an item, and item numbers belong in the task's `## Findings`
 
-### The `Pull request:` line
+### The lines a verb writes
 
-`Pull request:` lists every pull request that shipped part of the task as bare numbers, oldest first and comma-separated, as in `Pull request: #NNN, #NNN`. It is not an origin, so a task without one is well-formed, and `git-pr` appends to it when a pull request opens.
-
-The line lets a merge close its own task. `canon tasks archive --pull-request <n>` finds the task by any listed number and archives it only on the last.
-
-- One pull request, one task. Two tasks naming the same number refuse to archive rather than both moving.
-- `Pending branch: <branch>` holds that merge back while a branch that ticked an outcome waits on its own number
-- `canon tasks outcome` writes that line, skipping it when the branch's pull request is already listed, and `canon tasks pull-request` clears it
+`Pull request:` and `Sessions:` are not origins, so a task without them is well-formed. A verb writes each, and `${CLAUDE_SKILL_DIR}/references/tasks-record-lines.md` fixes what they mean and who calls the verb.
 
 ## What goes in
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.70.0",
+  "version": "5.71.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/commands/markdown.ts

@@ -167,7 +167,9 @@ export function register(program: Command): void {
         '',
         'A mid-sentence colon and a heading with a capital after its first word',
         'report the same way. A proper noun is the one case the second cannot',
-        'tell from title case, and the first is sometimes right.',
+        'tell from title case, and the first is sometimes right. A list whose',
+        'every item opens on a lead and a colon reads each lead as a label, and so',
+        'does a lead made only of code spans, links, commas, and and, or, to.',
         '',
         'Length reports a whole document past the ceiling and never exits 2.',
         'The Document ceiling gate stage owns that verdict, since this audit also',
@@ -842,6 +844,9 @@ function reportColons(reports: readonly FileReport[]): void {
   logInfo(
     'A colon followed by more text in a prose line, outside a label, a code span, and a link.',
   )
+  logInfo(
+    'A list where every item opens on a lead and a colon reads each lead as a label.',
+  )
   logInfo(
     'A heading, a table row, a fenced block, and a line-final colon are excluded. This never fails a run.',
   )

package/src/commands/tasks.ts

@@ -57,7 +57,10 @@ import {
   type RecordRefused,
   type RecordSelector,
   recordPullRequest,
+  recordSession,
+  type SessionOutcome,
 } from '@/tasks/record'
+import { resolveSessions } from '@/sessions/resolve'
 import {
   type BoardGroup,
   type Finding,
@@ -142,6 +145,13 @@ interface PullRequestCommandOptions {
   readonly root?: string
 }
 
+interface SessionCommandOptions {
+  readonly json?: boolean
+  readonly plan?: string
+  readonly name?: string
+  readonly root?: string
+}
+
 interface PlanLinkCommandOptions {
   readonly add?: boolean
   readonly waiting?: string
@@ -617,6 +627,63 @@ export function register(program: Command): void {
       },
     )
 
+  tasks
+    .command('session')
+    .description('Record a session that worked a task on its Sessions: line')
+    .argument(
+      '<sessionId>',
+      'Full sessionId, as canon sessions list --json carries it',
+    )
+    .argument('[task]', 'Task filename stem, as in v28.1-trigger-escalation')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--plan <slug>', 'Select the task whose Plan line names this plan')
+    .option(
+      '--name <name>',
+      'Name to record, read off the live roster when omitted',
+    )
+    .option('--json', 'Emit a machine-readable record on stdout')
+    .option('--root <path>', 'Board root, defaulting to the main worktree')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Refusals, read off `reason`:',
+        '  no-board   the repository holds no `.canon/tasks/` board',
+        '  no-match   no task matches the selector',
+        '  ambiguous  more than one task matches the selector',
+        '  bad-input  an id that is not a full sessionId, or an empty name',
+        '  no-name    the roster lists no live session with the id, and no',
+        '             --name was passed',
+        '',
+        'Exit codes:',
+        '  0  the session was added, appended, or already listed',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'It writes Sessions: <name> (<sessionId>) below the origin, Pull',
+        'request:, and Pending branch: lines, and appends to the line when one',
+        'exists. The id is the key, so a session already listed is reported',
+        'unchanged under the name it was first recorded with. A cloud',
+        'session_ id is accepted, and takes --name since the roster never',
+        'lists it. Safe from a linked worktree, since it resolves the board',
+        'root in-process.',
+        '',
+        'Examples:',
+        '  canon tasks session 0b1c2d3e-4f50-6172-8394-a5b6c7d8e9f0 v28.1-trigger-escalation',
+        '  canon tasks session 0b1c2d3e-4f50-6172-8394-a5b6c7d8e9f0 --plan task-sessions-line --json',
+        '  canon tasks session session_01AbC v28.1-trigger-escalation --name cloud-canon-a',
+        '',
+      ].join('\n'),
+    )
+    .action(
+      async (
+        sessionId: string,
+        task: string | undefined,
+        opts: SessionCommandOptions,
+      ) => {
+        process.exitCode = await runSession(sessionId, task, opts)
+      },
+    )
+
   tasks
     .command('plan-link')
     .description("Write or correct a task's Plan: line to point at a plan")
@@ -1259,6 +1326,72 @@ async function runPullRequest(
   return reportPullRequest(outcome, emitJson, root)
 }
 
+async function runSession(
+  sessionId: string,
+  task: string | undefined,
+  opts: SessionCommandOptions,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+  const selector = selectorFor(task, opts.plan)
+
+  if ('ok' in selector) {
+    return reportRecord(
+      'canon tasks session',
+      selector,
+      emitJson,
+      process.cwd(),
+    )
+  }
+
+  const root = opts.root ?? (await mainWorktreeRoot())
+  const name = opts.name ?? (await rosterName(sessionId))
+  const outcome = await recordSession(root, selector, sessionId, name)
+
+  return reportSession(outcome, emitJson, root)
+}
+
+/** The live roster's name for an id, or undefined once the session has exited. */
+async function rosterName(sessionId: string): Promise<string | undefined> {
+  const report = await resolveSessions()
+  if (report.kind === 'absent') return undefined
+
+  return report.sessions.find((session) => session.sessionId === sessionId)
+    ?.name
+}
+
+function reportSession(
+  outcome: SessionOutcome,
+  emitJson: boolean,
+  root: string,
+): number {
+  if (!outcome.ok) {
+    return reportRecord('canon tasks session', outcome, emitJson, root)
+  }
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: true,
+        root,
+        task: outcome.stem,
+        path: relative(root, outcome.path),
+        sessionId: outcome.sessionId,
+        name: outcome.name,
+        action: outcome.action,
+      })}\n`,
+    )
+    return 0
+  }
+
+  intro('canon tasks session')
+  logStep(outcome.action === 'unchanged' ? 'Already recorded' : 'Recorded')
+  logInfo(`${outcome.stem} names ${outcome.name} (${outcome.sessionId})`)
+  if (outcome.action !== 'unchanged') logAdd(relative(root, outcome.path))
+  outro()
+
+  return 0
+}
+
 const RENAME_PATTERN = /^Branch: renamed refs\/heads\/(.+) to refs\/heads\//
 
 /**

package/src/markdown/colons.ts

@@ -22,8 +22,14 @@ const QUOTE_MARKER = /^(?:\s*>\s?)+/
 /** A colon followed by whitespace and more text, ruling out `10:30` and a scheme. */
 const COLON = /:(?=\s+\S)/g
 
+/** A colon followed by whitespace, which a masked code span leaves behind. */
+const LABEL_COLON = /:\s/
+
 const BOLD_LABEL = /^(\*\*|__)[^*_]+\1$/
 
+/** What may stand in a lead once its code spans and links are masked. */
+const CONNECTIVE = /\b(?:and|or|to)\b|,/g
+
 /** Blanks a span while holding its width, so a column stays where it was. */
 function blank(match: string): string {
   return ' '.repeat(match.length)
@@ -32,14 +38,74 @@ function blank(match: string): string {
 /**
  * Whether the text before a line's first colon is a label rather than a
  * clause: the lead of a list item, or a prefix that is only emphasis and a
- * masked code span.
+ * masked code span. A list item's lead also reads as a label at any length
+ * when only code spans, links, commas, and `and`, `or`, or `to` stand in it,
+ * which is a file entry naming several paths.
  */
 function isLabel(prefix: string, listItem: boolean): boolean {
   if (BOLD_LABEL.test(prefix.trim())) return true
 
   const words = prefix.replace(/[*_]/g, ' ').trim()
   if (words === '') return true
-  return listItem && words.split(/\s+/).length <= 4
+  if (!listItem) return false
+  if (words.replace(CONNECTIVE, ' ').trim() === '') return true
+  return words.split(/\s+/).length <= 4
+}
+
+interface Entry {
+  readonly line: BodyLine
+  readonly masked: string
+  readonly start: number
+  /** Width of the quote marker and the item's own leading whitespace. */
+  readonly indent: number
+  readonly quote: string
+  readonly isItem: boolean
+  /** Matches at or past the content start, the only ones a line can report. */
+  readonly colons: readonly RegExpExecArray[]
+  /** A colon stands past the content start, even with only a masked span after it. */
+  readonly labelColon: boolean
+  /** Items sharing one list at one indent, shared by reference. */
+  group?: Entry[]
+}
+
+/**
+ * Collects consecutive items at one indent into a list. A blank line, a
+ * heading, or a change of quote depth ends every open list, and a deeper child
+ * neither joins its parent's list nor ends it.
+ */
+function groupItems(entries: readonly Entry[]): void {
+  const open = new Map<number, Entry[]>()
+  let quote = ''
+
+  for (const entry of entries) {
+    if (entry.line.fenced) continue
+
+    const empty = entry.masked.slice(entry.quote.length).trim() === ''
+    if (entry.quote !== quote || empty || HEADING.test(entry.line.text)) {
+      open.clear()
+    }
+    quote = entry.quote
+    if (!entry.isItem) continue
+
+    for (const level of open.keys()) {
+      if (level > entry.indent) open.delete(level)
+    }
+
+    const group = open.get(entry.indent) ?? []
+    open.set(entry.indent, group)
+    group.push(entry)
+    entry.group = group
+  }
+}
+
+/** Whether the item sits in a list of two or more where every item has a colon. */
+function uniform(entry: Entry): boolean {
+  const group = entry.group
+  return (
+    group !== undefined &&
+    group.length >= 2 &&
+    group.every((item) => item.labelColon)
+  )
 }
 
 /**
@@ -47,30 +113,50 @@ function isLabel(prefix: string, listItem: boolean): boolean {
  *
  * A heading, a table row, a fence, a code span, a link, and a line-final colon
  * are left alone, and so is the first colon of a list item or of a line opening
- * on a bold or code label. The measure is advisory, because a colon is
- * sometimes right and the corpus count shows a gate would be a sweep nobody
- * asked for.
+ * on a bold or code label, and of every item in a list where each one carries a
+ * colon. The measure is advisory, because a colon is sometimes right and the
+ * corpus count shows a gate would be a sweep nobody asked for.
  */
 export function findColons(lines: readonly BodyLine[]): ColonFinding[] {
-  const found: ColonFinding[] = []
-
-  for (const line of lines) {
-    if (line.fenced || HEADING.test(line.text) || TABLE_ROW.test(line.text)) {
-      continue
-    }
-
+  const entries: Entry[] = lines.map((line) => {
     const masked = maskDisplayed(line.text.replace(LINK, blank))
     const quote = QUOTE_MARKER.exec(masked)?.[0] ?? ''
     const marker = LIST_MARKER.exec(masked.slice(quote.length))?.[0] ?? ''
     const start = quote.length + marker.length
-    let labelled = false
+    const skipped =
+      line.fenced || HEADING.test(line.text) || TABLE_ROW.test(line.text)
+
+    return {
+      line,
+      masked,
+      start,
+      indent: quote.length + marker.length - marker.trimStart().length,
+      quote: quote.replace(/\s/g, ''),
+      isItem: !skipped && marker !== '',
+      labelColon: !skipped && LABEL_COLON.test(masked.slice(start)),
+      colons: skipped
+        ? []
+        : [...masked.matchAll(COLON)].filter((match) => match.index >= start),
+    }
+  })
+
+  groupItems(entries)
 
-    for (const match of masked.matchAll(COLON)) {
-      if (match.index < start) continue
+  const found: ColonFinding[] = []
+
+  for (const entry of entries) {
+    const { line, masked, start } = entry
+    let labelled = false
 
+    for (const match of entry.colons) {
       if (!labelled) {
         labelled = true
-        if (isLabel(masked.slice(start, match.index), marker !== '')) continue
+        if (
+          isLabel(masked.slice(start, match.index), entry.isItem) ||
+          (entry.isItem && uniform(entry))
+        ) {
+          continue
+        }
       }
 
       found.push({

package/src/tasks/archive.ts

@@ -325,6 +325,57 @@ export function readPendingBranches(text: string): readonly string[] {
     .filter((entry) => entry.length > 0)
 }
 
+/**
+ * A local session's full sessionId, or the `session_` id a cloud create reads
+ * out. Only the full form reaches `canon sessions export`, so a short prefix is
+ * refused rather than written.
+ */
+const SESSION_ID_SOURCE =
+  '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|session_[A-Za-z0-9]+'
+
+export const SESSION_ID_PATTERN = new RegExp(`^(?:${SESSION_ID_SOURCE})$`)
+
+export const SESSIONS_PREFIX = 'Sessions:'
+
+/**
+ * One entry is a name and its parenthesized id, and the parse keys on that
+ * trailing id, so a roster name carrying a comma or its own parentheses still
+ * reads as one entry.
+ */
+const SESSION_ENTRY_PATTERN = new RegExp(
+  `(.+?) \\((${SESSION_ID_SOURCE})\\)(?:, |$)`,
+  'y',
+)
+
+export interface SessionEntry {
+  readonly name: string
+  readonly sessionId: string
+}
+
+/**
+ * Reads the `Sessions:` line `canon tasks session` writes. A line that does not
+ * parse whole reads as naming none, the way `readPullRequest` reads a line
+ * carrying anything besides its list.
+ */
+export function readSessions(text: string): readonly SessionEntry[] {
+  const line = text
+    .split('\n')
+    .find((entry) => entry.startsWith(SESSIONS_PREFIX))
+  if (line === undefined) return []
+
+  const body = line.slice(SESSIONS_PREFIX.length).trim()
+  const entries: SessionEntry[] = []
+  const pattern = new RegExp(SESSION_ENTRY_PATTERN)
+
+  while (pattern.lastIndex < body.length) {
+    const match = pattern.exec(body)
+    if (!match) return []
+    entries.push({ name: match[1], sessionId: match[2] })
+  }
+
+  return entries
+}
+
 /** A markdown link on a `Plan:` line, its target captured. */
 const PLAN_LINK_PATTERN = /\[[^\]]*\]\(([^)]+)\)/g
 
@@ -514,7 +565,8 @@ export function declineLine(reason: string, by: string, date: string): string {
 /**
  * Lines a `Declined:` line anchors after, mirroring `record.ts`'s
  * `ORIGIN_PREFIXES` with `Pull request:` folded in, since a decline can follow
- * a pull request that never merged.
+ * a pull request that never merged. `Sessions:` joins them, since the sessions
+ * that worked a task sit above whatever ended it.
  */
 const DECLINE_ANCHOR_PREFIXES = [
   'Plan:',
@@ -522,6 +574,7 @@ const DECLINE_ANCHOR_PREFIXES = [
   'Intake:',
   'Issue:',
   'Pull request:',
+  SESSIONS_PREFIX,
 ] as const
 
 function lastAnchorLine(lines: readonly string[]): number | undefined {

package/src/tasks/record.ts

@@ -15,6 +15,9 @@ import {
   readPendingBranches,
   readPlanTargets,
   readPullRequest,
+  readSessions,
+  SESSION_ID_PATTERN,
+  SESSIONS_PREFIX,
   tasksDir,
 } from '@/tasks/archive'
 import { checkWaiting, type LinkPromotion, promoteOnLink } from '@/tasks/board'
@@ -34,6 +37,9 @@ const ORIGIN_PREFIXES = ['Plan:', 'Groundwork:', 'Intake:', 'Issue:'] as const
  *
  * `several-plans` answers a `Plan:` line that already links more than one plan.
  * `plan-link` cannot know which link to drop, so it writes nothing.
+ *
+ * `no-name` answers a session id the roster no longer lists, called with no
+ * name, since an id written alone reads as nobody to the next reader.
  */
 export const RECORD_REFUSALS = [
   'no-board',
@@ -44,6 +50,7 @@ export const RECORD_REFUSALS = [
   'no-plan',
   'several-plans',
   'bad-input',
+  'no-name',
 ] as const
 
 export type RecordRefusal = (typeof RECORD_REFUSALS)[number]
@@ -88,6 +95,18 @@ export interface PlanRecorded {
 
 export type PlanOutcome = PlanRecorded | RecordRefused
 
+export interface SessionRecorded {
+  readonly ok: true
+  readonly stem: string
+  readonly path: string
+  readonly sessionId: string
+  /** The name the line carries for the id, which a repeat call never renames. */
+  readonly name: string
+  readonly action: Exclude<LineAction, 'corrected'>
+}
+
+export type SessionOutcome = SessionRecorded | RecordRefused
+
 export interface OutcomesClosed {
   readonly ok: true
   readonly stem: string
@@ -228,6 +247,47 @@ export function clearPendingBranch(
   return { text: lines.join('\n'), changed: true }
 }
 
+/**
+ * Names a session on the `Sessions:` line, keyed on the id, so a dispatcher
+ * and `git-pr` recording the same worker write it once. The line sits below
+ * every other line a task carries above its outcomes, so a pull request
+ * recorded later lands above it.
+ */
+export function writeSessionsLine(
+  text: string,
+  name: string,
+  sessionId: string,
+): { readonly text: string; readonly action: SessionRecorded['action'] } {
+  const entry = `${name} (${sessionId})`
+  const lines = text.split('\n')
+  const existing = lines.findIndex((line) => line.startsWith(SESSIONS_PREFIX))
+
+  if (existing !== -1) {
+    if (lines[existing].includes(`(${sessionId})`)) {
+      return { text, action: 'unchanged' }
+    }
+    lines[existing] = `${lines[existing].trimEnd()}, ${entry}`
+    return { text: lines.join('\n'), action: 'appended' }
+  }
+
+  const line = `${SESSIONS_PREFIX} ${entry}`
+  const anchor = lastOriginLine(lines, [
+    ...ORIGIN_PREFIXES,
+    'Pull request:',
+    PENDING_PREFIX,
+  ])
+  if (anchor !== undefined) {
+    lines.splice(anchor + 1, 0, line)
+    return { text: lines.join('\n'), action: 'added' }
+  }
+
+  const heading = lines.findIndex((entry) => entry.startsWith('# '))
+  if (heading === -1) return { text: `${line}\n${text}`, action: 'added' }
+
+  lines.splice(heading + 1, 0, '', line)
+  return { text: lines.join('\n'), action: 'added' }
+}
+
 export type PlanLineWrite =
   | {
       readonly ok: true
@@ -566,6 +626,64 @@ export async function recordPlan(
   }
 }
 
+/**
+ * Records a session that worked a task on its `Sessions:` line. The caller
+ * resolves `name` from the roster or takes it from `--name`, and an undefined
+ * name refuses rather than writing a bare id. The id is checked first, since a
+ * malformed one is a caller defect and every later check would hide it.
+ */
+export async function recordSession(
+  root: string,
+  selector: RecordSelector,
+  sessionId: string,
+  name: string | undefined,
+): Promise<SessionOutcome> {
+  if (!SESSION_ID_PATTERN.test(sessionId)) {
+    return refuse(
+      'bad-input',
+      `Not a full sessionId: ${sessionId}. Pass the whole id canon sessions list --json carries.`,
+      [sessionId],
+    )
+  }
+
+  if (name === undefined) {
+    return refuse(
+      'no-name',
+      `No live session carries ${sessionId}, so its name cannot be read. Pass --name.`,
+      [sessionId],
+    )
+  }
+
+  const trimmed = name.trim()
+  if (trimmed.length === 0 || /[\r\n]/.test(trimmed)) {
+    return refuse('bad-input', 'A session name is one non-empty line.', [name])
+  }
+
+  const opened = await openTask(root, selector)
+  if ('ok' in opened) return opened
+
+  const { stem, path } = opened
+  const written = writeSessionsLine(
+    await readFile(path, 'utf8'),
+    trimmed,
+    sessionId,
+  )
+  if (written.action !== 'unchanged') await writeFile(path, written.text)
+
+  const listed = readSessions(written.text).find(
+    (entry) => entry.sessionId === sessionId,
+  )
+
+  return {
+    ok: true,
+    stem,
+    path,
+    sessionId,
+    name: listed?.name ?? trimmed,
+    action: written.action,
+  }
+}
+
 /**
  * Marks the named outcomes `[x]` in place. `task-complete` runs this against a
  * board it can read and cannot edit from a linked worktree, and the positions

package/src/tasks/validate.ts

@@ -10,7 +10,9 @@ import {
   readPendingBranches,
   readPlanTargets,
   readPullRequest,
+  readSessions,
   resolveLivePlan,
+  SESSIONS_PREFIX,
   tasksDir,
 } from '@/tasks/archive'
 import {
@@ -66,6 +68,7 @@ export const FINDING_KINDS = [
   'blocker-settled',
   'blocker-unresolved',
   'blocker-declined',
+  'sessions-misshapen',
 ] as const
 
 export type FindingKind = (typeof FINDING_KINDS)[number]
@@ -841,6 +844,39 @@ async function planDisagreement(
   }
 }
 
+/**
+ * Reports a `Sessions:` line that does not parse as name and id pairs, since
+ * the reader takes such a line as naming nobody and a retro would find the
+ * sessions gone. A row whose task file is gone is left to `task-unresolved`.
+ */
+async function checkSessions(
+  rows: readonly BoardRow[],
+  dir: string,
+): Promise<Finding[]> {
+  const found = await Promise.all(
+    rows.map(async (row): Promise<Finding | undefined> => {
+      if (!row.stem) return undefined
+      const file = join(dir, `${row.stem}.md`)
+      if (!existsSync(file)) return undefined
+
+      const text = await readFile(file, 'utf8')
+      const line = text
+        .split('\n')
+        .find((entry) => entry.startsWith(SESSIONS_PREFIX))
+      if (line === undefined || readSessions(text).length > 0) return undefined
+
+      return {
+        kind: 'sessions-misshapen',
+        group: row.group,
+        subject: row.stem,
+        message: `carries "${line}", which does not read as name (sessionId) pairs, so no session it names can be recovered. Rewrite it through canon tasks session.`,
+      }
+    }),
+  )
+
+  return found.filter((finding): finding is Finding => finding !== undefined)
+}
+
 /**
  * Tests the claim a group name makes about a plan. `## Needs a plan` says none
  * is live and `## Up next` says one is written, and neither group has a `Plan`
@@ -1638,6 +1674,7 @@ export async function validateBoard(
     ...checkMapping(rows, backlog, dir),
     ...(await groupRuleFindings(rows, root)),
     ...(await checkPlanAgreement(rows, dir, root)),
+    ...(await checkSessions(rows, dir)),
     ...(await checkStaleTouches(rows, root)),
     ...checkCellWidth(rows),
     ...checkOrdering(rows),