mandrel 2.124.0 → 2.126.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/.agents/docs/agentrc-reference.json +1 -0
  2. package/.agents/docs/configuration.md +2 -0
  3. package/.agents/docs/runbooks/dispatch-board.md +199 -0
  4. package/.agents/docs/runbooks/dispatch.md +219 -0
  5. package/.agents/docs/runbooks/session-titles.md +52 -0
  6. package/.agents/schemas/agentrc.schema.json +60 -0
  7. package/.agents/scripts/acceptance-eval.js +11 -2
  8. package/.agents/scripts/dispatch.js +411 -0
  9. package/.agents/scripts/lib/child-detached.js +48 -0
  10. package/.agents/scripts/lib/child-exec.js +11 -0
  11. package/.agents/scripts/lib/config/delivery-routing.js +15 -12
  12. package/.agents/scripts/lib/config/temp-paths.js +26 -0
  13. package/.agents/scripts/lib/config-settings-schema-delivery.js +45 -0
  14. package/.agents/scripts/lib/dispatch/environments.js +135 -0
  15. package/.agents/scripts/lib/dispatch/launch-cloud.js +164 -0
  16. package/.agents/scripts/lib/dispatch/launch-local.js +77 -0
  17. package/.agents/scripts/lib/dispatch/liveness.js +21 -0
  18. package/.agents/scripts/lib/dispatch/record.js +54 -0
  19. package/.agents/scripts/lib/dispatch/status.js +329 -0
  20. package/.agents/scripts/lib/dispatch/targets.js +101 -0
  21. package/.agents/scripts/lib/dispatch/verdict.js +207 -0
  22. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  23. package/.agents/scripts/lib/observability/source-classifier.js +2 -0
  24. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +2 -0
  25. package/.agents/scripts/lib/orchestration/story-handoff.js +6 -0
  26. package/.agents/scripts/lib/orchestration/story-stage-publish.js +147 -0
  27. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  28. package/.agents/scripts/lib/story-body/story-body.js +5 -2
  29. package/.agents/scripts/session-title.js +187 -0
  30. package/.agents/scripts/single-story-confirm-merge.js +7 -0
  31. package/.agents/scripts/single-story-init.js +3 -0
  32. package/.agents/workflows/helpers/audit-lens-core.md +4 -0
  33. package/.agents/workflows/helpers/deliver-light.md +4 -1
  34. package/.agents/workflows/helpers/qa-core.md +2 -0
  35. package/.agents/workflows/mandrel-deliver.md +7 -3
  36. package/.agents/workflows/mandrel-orchestrate.md +2 -0
  37. package/.agents/workflows/mandrel-plan.md +4 -0
  38. package/README.md +8 -0
  39. package/bin/mandrel.js +35 -13
  40. package/docs/CHANGELOG.md +27 -0
  41. package/lib/cli/dispatch.js +28 -0
  42. package/lib/cli/ui/accounts.js +81 -0
  43. package/lib/cli/ui/assignee-filter.js +91 -0
  44. package/lib/cli/ui/board-model.js +399 -0
  45. package/lib/cli/ui/board.css +578 -0
  46. package/lib/cli/ui/board.html +84 -0
  47. package/lib/cli/ui/board.js +755 -0
  48. package/lib/cli/ui/log-tail.js +89 -0
  49. package/lib/cli/ui/panel-model.js +100 -0
  50. package/lib/cli/ui/preferences.js +136 -0
  51. package/lib/cli/ui/request-guard.js +108 -0
  52. package/lib/cli/ui/server.js +230 -0
  53. package/lib/cli/ui/sources.js +258 -0
  54. package/lib/cli/ui/story-detail.js +99 -0
  55. package/lib/cli/ui.js +124 -0
  56. package/package.json +1 -1
@@ -52,6 +52,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
52
52
  'deliver-run.js',
53
53
  'diagnose-friction.js',
54
54
  'diagnose.js',
55
+ 'dispatch.js',
55
56
  'drain-pending-cleanup.js',
56
57
  'evidence-gate.js',
57
58
  'file-ci-gap.js',
@@ -79,6 +80,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
79
80
  'review-dispositions-report.js',
80
81
  'role-scope-guard.js',
81
82
  'run-tests.js',
83
+ 'session-title.js',
82
84
  'single-story-close.js',
83
85
  'single-story-confirm-merge.js',
84
86
  'single-story-init.js',
@@ -23,6 +23,7 @@ import {
23
23
  releaseStoryLease,
24
24
  } from '../single-story-lease-guard.js';
25
25
  import { createStoryProgress } from '../story-progress.js';
26
+ import { publishStagePhase } from '../story-stage-publish.js';
26
27
  import { createPhaseTimer } from './phase-timer.js';
27
28
  import { parsePrNumber } from './phases/code-review.js';
28
29
  import { runConfirmMergePhase } from './phases/confirm-merge.js';
@@ -520,6 +521,7 @@ async function finishPhase(ctx, deps) {
520
521
 
521
522
  /** Each phase extends the shared context; a non-null return ends the run. */
522
523
  const CLOSE_PIPELINE = Object.freeze([
524
+ publishStagePhase('close'),
523
525
  loadStoryPhase,
524
526
  graphqlPreflightPhase,
525
527
  resolveBasePhase,
@@ -110,6 +110,7 @@ import {
110
110
  scanDuplicationRescore,
111
111
  } from './story-close/duplication-close-rescore.js';
112
112
  import { createStoryProgress, handoffStepName } from './story-progress.js';
113
+ import { publishDeliveryStage } from './story-stage-publish.js';
113
114
  import {
114
115
  STATE_LABELS,
115
116
  transitionTicketState,
@@ -1997,6 +1998,11 @@ export async function runStoryHandoff(
1997
1998
  stage: 'handoff',
1998
1999
  config,
1999
2000
  });
2001
+ await publishDeliveryStage({
2002
+ provider: () => createProviderFn(config),
2003
+ storyId,
2004
+ stage: 'handoff',
2005
+ });
2000
2006
  const ctx = {
2001
2007
  storyId,
2002
2008
  cwd,
@@ -0,0 +1,147 @@
1
+ /**
2
+ * The delivery stage a Story has reached, published as one `delivery-stage`
3
+ * structured comment on the Story issue so a tool on another machine can show
4
+ * progress for a run it cannot see locally.
5
+ *
6
+ * Advisory only, like the local story-progress record: nothing decides on
7
+ * it, one attempt with no retry, and any failure is logged at debug and
8
+ * swallowed, so no delivery result changes because of it.
9
+ */
10
+
11
+ import { Logger } from '../Logger.js';
12
+ import { findStructuredComment } from './ticketing/reads.js';
13
+ import { upsertStructuredComment } from './ticketing/state.js';
14
+
15
+ const DELIVERY_STAGE_TYPE = 'delivery-stage';
16
+ const DELIVERY_STAGES = Object.freeze([
17
+ 'build',
18
+ 'check',
19
+ 'handoff',
20
+ 'close',
21
+ 'merge',
22
+ ]);
23
+
24
+ const RECORD_RE = /```json\n(\{[^\n]*"kind":"delivery-stage"[^\n]*\})\n```/;
25
+
26
+ const HISTORY_LIMIT = 10;
27
+
28
+ /** The comment body: a one-line summary, then the machine block. */
29
+ function formatDeliveryStageBody(fields) {
30
+ const record = { kind: DELIVERY_STAGE_TYPE, ...fields };
31
+ return `Delivery stage: **${fields.stage}** (Story #${fields.storyId}).\n\n\`\`\`json\n${JSON.stringify(record)}\n\`\`\``;
32
+ }
33
+
34
+ const isEntry = (e) =>
35
+ DELIVERY_STAGES.includes(e?.stage) && typeof e?.at === 'string';
36
+
37
+ const historyOf = (raw) =>
38
+ (Array.isArray(raw) ? raw : [])
39
+ .filter(isEntry)
40
+ .map((e) => ({ stage: e.stage, at: e.at }));
41
+
42
+ /** The entries before `stage`, seeded from a pre-history record's own stage. */
43
+ function priorHistory(previous) {
44
+ if (!previous) return [];
45
+ if (previous.history.length > 0) return previous.history;
46
+ return [{ stage: previous.stage, at: previous.updatedAt }];
47
+ }
48
+
49
+ /**
50
+ * The stage record a comment body carries, or `null` for any other comment.
51
+ * Exported for readers that list an issue's comments.
52
+ *
53
+ * @public
54
+ * @param {unknown} body
55
+ * @returns {object|null} The record; `history` is `[]` on an older one.
56
+ */
57
+ export function parseDeliveryStage(body) {
58
+ const match = typeof body === 'string' ? RECORD_RE.exec(body) : null;
59
+ if (!match) return null;
60
+ let record;
61
+ try {
62
+ record = JSON.parse(match[1]);
63
+ } catch {
64
+ return null;
65
+ }
66
+ const { storyId, stage, prNumber, updatedAt } = record;
67
+ const valid =
68
+ Number.isInteger(storyId) &&
69
+ DELIVERY_STAGES.includes(stage) &&
70
+ (prNumber === null || Number.isInteger(prNumber)) &&
71
+ typeof updatedAt === 'string';
72
+ return valid
73
+ ? {
74
+ kind: DELIVERY_STAGE_TYPE,
75
+ storyId,
76
+ stage,
77
+ prNumber,
78
+ updatedAt,
79
+ history: historyOf(record.history),
80
+ }
81
+ : null;
82
+ }
83
+
84
+ /**
85
+ * Publish `stage` for `storyId`, skipping the write when the comment already
86
+ * names it. Never throws.
87
+ *
88
+ * @param {{ storyId: number, stage: string, prNumber?: number|null,
89
+ * provider: object|(() => object)|null|undefined, now?: () => Date,
90
+ * debug?: (msg: string) => void }} args `provider` may be a thunk so a
91
+ * provider that fails to build is swallowed too; a missing one skips.
92
+ * @returns {Promise<'published'|'unchanged'|'skipped'>}
93
+ */
94
+ export async function publishDeliveryStage({
95
+ storyId,
96
+ stage,
97
+ prNumber = null,
98
+ provider,
99
+ now = () => new Date(),
100
+ debug = (msg) => Logger.debug(msg),
101
+ }) {
102
+ try {
103
+ const resolved = typeof provider === 'function' ? provider() : provider;
104
+ if (!resolved) return 'skipped';
105
+ const existing = await findStructuredComment(
106
+ resolved,
107
+ storyId,
108
+ DELIVERY_STAGE_TYPE,
109
+ );
110
+ const previous = parseDeliveryStage(existing?.body);
111
+ if (previous?.stage === stage) return 'unchanged';
112
+ const updatedAt = now().toISOString();
113
+ const body = formatDeliveryStageBody({
114
+ storyId,
115
+ stage,
116
+ prNumber: Number.isInteger(prNumber) && prNumber > 0 ? prNumber : null,
117
+ updatedAt,
118
+ history: [...priorHistory(previous), { stage, at: updatedAt }].slice(
119
+ -HISTORY_LIMIT,
120
+ ),
121
+ });
122
+ await upsertStructuredComment(resolved, storyId, DELIVERY_STAGE_TYPE, body);
123
+ return 'published';
124
+ } catch (err) {
125
+ debug(
126
+ `[story-stage] ${stage} not published for Story #${storyId}: ${err?.message ?? err}`,
127
+ );
128
+ return 'skipped';
129
+ }
130
+ }
131
+
132
+ /**
133
+ * A pipeline phase `(ctx, deps)` that publishes `stage` and never ends the run.
134
+ *
135
+ * @param {string} stage
136
+ * @returns {(ctx: { storyId: number }, deps: { provider: object }) => Promise<null>}
137
+ */
138
+ export function publishStagePhase(stage) {
139
+ return async (ctx, deps) => {
140
+ await publishDeliveryStage({
141
+ provider: deps.provider,
142
+ storyId: ctx.storyId,
143
+ stage,
144
+ });
145
+ return null;
146
+ };
147
+ }
@@ -65,6 +65,8 @@ export const STRUCTURED_COMMENT_TYPES = Object.freeze([
65
65
  'plan-rewrite',
66
66
  // Opt-in per-Story close outcome record, upserted on every close attempt.
67
67
  'story-outcome',
68
+ // The delivery stage a Story has reached, upserted on each stage entry.
69
+ 'delivery-stage',
68
70
  ]);
69
71
 
70
72
  export const WAVE_TYPE_PATTERN = WAVE_MARKER_RE;
@@ -125,7 +125,7 @@ const WIDE_MARKER_LINE_RE = /^>\s*\*\*Wide:\*\*/;
125
125
  const AUTHORED_MARKER_LINE_RE = /^\s*>\s*🏷️\s+Authored with Mandrel\b/;
126
126
  const META_BLOCK_RE = /<!--\s*meta:[\s\S]*?-->/;
127
127
  // Provenance and plan-story markers persist appends after the last section
128
- // can land in a path list; a whole-line comment is never a path bullet.
128
+ // can land in any list; a whole-line comment is never a list entry.
129
129
  const WHOLE_LINE_COMMENT_RE = /^\s*<!--.*-->\s*$/;
130
130
 
131
131
  /**
@@ -447,7 +447,10 @@ function parsePathEntrySection(lines, warnings) {
447
447
  * @returns {string[]}
448
448
  */
449
449
  function parseTextListSection(lines) {
450
- return lines.map((l) => stripListMarker(l)).filter(Boolean);
450
+ return lines
451
+ .filter(isNotCommentLine)
452
+ .map((l) => stripListMarker(l))
453
+ .filter(Boolean);
451
454
  }
452
455
 
453
456
  /**
@@ -0,0 +1,187 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * The one place a session title is built. Workflows cite it with an event and
5
+ * apply the printed title through the host (runbooks/session-titles.md); they
6
+ * never compose a title inline.
7
+ *
8
+ * Exit codes: 0 a title (or `apply: false` when disabled), 2 a usage error.
9
+ */
10
+
11
+ import { parseArgs } from 'node:util';
12
+ import { runAsCli } from './lib/cli-utils.js';
13
+ import { getDeliveryRouting } from './lib/config/delivery-routing.js';
14
+ import { resolveConfig } from './lib/config-resolver.js';
15
+
16
+ const MAX_TITLE = 48;
17
+
18
+ /** event → glyph, fixed verb, and the one input it takes (null: none). */
19
+ const EVENTS = Object.freeze({
20
+ 'plan-seed': { glyph: '○', verb: '', input: 'summary' },
21
+ 'plan-ticket': { glyph: '○', verb: 'Planning', input: 'ids' },
22
+ planned: { glyph: '○', verb: 'Planned', input: 'ids' },
23
+ deliver: { glyph: '◐', verb: 'Delivery', input: 'ids' },
24
+ 'deliver-prompt': { glyph: '◐', verb: '', input: 'summary' },
25
+ delivered: { glyph: '●', verb: 'Delivered', input: 'ids' },
26
+ blocked: { glyph: '⊗', verb: 'Blocked', input: 'ids' },
27
+ orchestrate: { glyph: '◐', verb: 'Orchestrating', input: null },
28
+ audit: { glyph: '◐', verb: 'Audit', input: 'lens' },
29
+ audited: { glyph: '●', verb: 'Audit', input: 'lens' },
30
+ qa: { glyph: '◐', verb: 'QA', input: 'summary' },
31
+ 'qa-done': { glyph: '●', verb: 'QA', input: 'summary' },
32
+ });
33
+
34
+ const INPUTS = ['ids', 'summary', 'lens'];
35
+
36
+ const HELP = `Usage: node .agents/scripts/session-title.js --event <name> [--ids <id,id,...> | --summary "<text>" | --lens <name>] [--json]
37
+
38
+ Builds the host session title for a workflow event and prints one JSON object:
39
+ {"title": "<string>", "apply": true}, or {"title": null, "apply": false,
40
+ "reason": "disabled"} when delivery.routing.sessionTitles is false. How a
41
+ title is applied: .agents/docs/runbooks/session-titles.md.
42
+
43
+ Events (input → title):
44
+ ${Object.entries(EVENTS)
45
+ .map(
46
+ ([name, { glyph, verb, input }]) =>
47
+ ` ${name.padEnd(15)}${(input ? `--${input}` : '(none)').padEnd(11)}${[glyph, verb, input && `<${input}>`].filter(Boolean).join(' ')}`,
48
+ )
49
+ .join('\n')}
50
+
51
+ Flags:
52
+ --event The workflow event (required).
53
+ --ids Comma-separated ids; a leading # is dropped.
54
+ --summary Free text; control characters stripped, whitespace collapsed.
55
+ --lens The audit lens name.
56
+ --json Accepted for symmetry; output is always JSON.
57
+ --help Show this message.
58
+ `;
59
+
60
+ class UsageError extends Error {}
61
+
62
+ /**
63
+ * @param {string} raw
64
+ * @returns {string}
65
+ */
66
+ function formatIds(raw) {
67
+ const ids = raw
68
+ .split(',')
69
+ .map((id) => id.trim().replace(/^#/, ''))
70
+ .filter((id) => id !== '');
71
+ if (ids.length === 0) throw new UsageError('--ids needs at least one id');
72
+ const bad = ids.find((id) => !/^\d+$/.test(id));
73
+ if (bad !== undefined) throw new UsageError(`non-numeric id: ${bad}`);
74
+ if (ids.length <= 3) return ids.map((id) => `#${id}`).join(' ');
75
+ const nums = ids.map(Number);
76
+ return `#${Math.min(...nums)}–#${Math.max(...nums)} (${ids.length})`;
77
+ }
78
+
79
+ /**
80
+ * @param {string} raw
81
+ * @param {string} flag
82
+ * @returns {string}
83
+ */
84
+ function cleanText(raw, flag) {
85
+ const text = raw
86
+ .replace(/\s+/g, ' ')
87
+ .replace(/\p{Cc}/gu, '')
88
+ .replace(/ +/g, ' ')
89
+ .trim();
90
+ if (text === '') throw new UsageError(`--${flag} is empty`);
91
+ return text;
92
+ }
93
+
94
+ /**
95
+ * Cap the title at MAX_TITLE characters, cutting only the free text.
96
+ *
97
+ * @param {string} prefix glyph plus fixed verb
98
+ * @param {string} text
99
+ * @returns {string}
100
+ */
101
+ function fit(prefix, text) {
102
+ if (!text) return prefix;
103
+ const head = `${prefix} `;
104
+ const budget = MAX_TITLE - [...head].length;
105
+ const chars = [...text];
106
+ if (chars.length <= budget) return head + text;
107
+ return `${head}${chars
108
+ .slice(0, budget - 1)
109
+ .join('')
110
+ .trimEnd()}…`;
111
+ }
112
+
113
+ /**
114
+ * @param {{ event?: string, ids?: string, summary?: string, lens?: string }} values
115
+ * @returns {string}
116
+ */
117
+ function buildTitle(values) {
118
+ const spec = EVENTS[values.event];
119
+ if (!spec) {
120
+ throw new UsageError(
121
+ values.event ? `unknown event: ${values.event}` : '--event is required',
122
+ );
123
+ }
124
+ const given = INPUTS.filter((name) => values[name] !== undefined);
125
+ const expected = spec.input ? [spec.input] : [];
126
+ if (given.join() !== expected.join()) {
127
+ throw new UsageError(
128
+ `${values.event} takes ${spec.input ? `--${spec.input}` : 'no input'}`,
129
+ );
130
+ }
131
+ const prefix = [spec.glyph, spec.verb].filter(Boolean).join(' ');
132
+ if (!spec.input) return prefix;
133
+ const raw = values[spec.input];
134
+ const text =
135
+ spec.input === 'ids' ? formatIds(raw) : cleanText(raw, spec.input);
136
+ return fit(prefix, text);
137
+ }
138
+
139
+ /**
140
+ * @param {{ argv?: string[] }} [args]
141
+ * @param {{
142
+ * resolveConfigImpl?: typeof resolveConfig,
143
+ * stdout?: { write: (s: string) => unknown },
144
+ * stderr?: { write: (s: string) => unknown },
145
+ * }} [deps]
146
+ * @returns {Promise<number>} exit code
147
+ */
148
+ export async function runSessionTitle(
149
+ { argv = process.argv.slice(2) } = {},
150
+ {
151
+ resolveConfigImpl = resolveConfig,
152
+ stdout = process.stdout,
153
+ stderr = process.stderr,
154
+ } = {},
155
+ ) {
156
+ let title;
157
+ try {
158
+ const { values } = parseArgs({
159
+ args: argv,
160
+ options: {
161
+ event: { type: 'string' },
162
+ ids: { type: 'string' },
163
+ summary: { type: 'string' },
164
+ lens: { type: 'string' },
165
+ json: { type: 'boolean', default: false },
166
+ },
167
+ strict: true,
168
+ allowPositionals: false,
169
+ });
170
+ title = buildTitle(values);
171
+ } catch (err) {
172
+ stderr.write(`[session-title] ${err.message}\n\n${HELP}`);
173
+ return 2;
174
+ }
175
+ const enabled = getDeliveryRouting(resolveConfigImpl()).sessionTitles;
176
+ const result = enabled
177
+ ? { title, apply: true }
178
+ : { title: null, apply: false, reason: 'disabled' };
179
+ stdout.write(`${JSON.stringify(result)}\n`);
180
+ return 0;
181
+ }
182
+
183
+ runAsCli(import.meta.url, () => runSessionTitle(), {
184
+ source: 'session-title',
185
+ usage: HELP,
186
+ propagateExitCode: true,
187
+ });
@@ -44,6 +44,7 @@ import {
44
44
  NEXT_COMMANDS,
45
45
  terminalFromWaitOutcome,
46
46
  } from './lib/orchestration/story-deliver-terminal.js';
47
+ import { publishDeliveryStage } from './lib/orchestration/story-stage-publish.js';
47
48
  import { PROJECT_ROOT } from './lib/project-root.js';
48
49
  import { createProvider } from './lib/provider-factory.js';
49
50
  import { confirmAndLand } from './lib/single-story/confirm-and-land.js';
@@ -454,6 +455,12 @@ export async function runConfirmMerge({
454
455
  storyBranch,
455
456
  gh: ctx.gh,
456
457
  });
458
+ await publishDeliveryStage({
459
+ provider: ctx.provider,
460
+ storyId,
461
+ stage: 'merge',
462
+ prNumber,
463
+ });
457
464
  if (prNumber == null) return await confirmWithoutPr(ctx);
458
465
  const withPr = { ...ctx, prNumber };
459
466
  return wait ? await resumeMergeWait(withPr) : await probeMergeOnce(withPr);
@@ -49,6 +49,7 @@ import {
49
49
  } from './lib/orchestration/single-story-lease-guard.js';
50
50
  import { handleRemoteVerificationFailure } from './lib/orchestration/story-init-remote.js';
51
51
  import { composeStoryInitResult } from './lib/orchestration/story-init-result.js';
52
+ import { publishDeliveryStage } from './lib/orchestration/story-stage-publish.js';
52
53
  import {
53
54
  STATE_LABELS,
54
55
  transitionTicketState,
@@ -763,6 +764,8 @@ export async function runSingleStoryInit({
763
764
  await rollbackClaimOnInitFailure(provider, storyId, config);
764
765
  throw err;
765
766
  }
767
+ // Every mutation has landed: the Story is now in its build stage.
768
+ await publishDeliveryStage({ provider, storyId, stage: 'build' });
766
769
  }
767
770
 
768
771
  // Every path gets the checklist; `buildStoryChecklist` never throws.
@@ -304,6 +304,10 @@ start an arbitrary dev server, and do not fall back to a static-only claim
304
304
  dressed as a runtime one — name the skip and let the static findings stand on
305
305
  their own.
306
306
 
307
+ ## Session title {#session-title}
308
+
309
+ The top-level caller, never an `auditor` subagent, titles the session `node .agents/scripts/session-title.js --event audit --lens <lens>` when the lens starts and `--event audited --lens <lens>` once its report is written ([runbook](../../docs/runbooks/session-titles.md)).
310
+
307
311
  ## Execution strategy {#execution-strategy}
308
312
 
309
313
  A lens is a self-contained, read-only unit of work — exactly the shape a
@@ -72,6 +72,8 @@ is not being loosened.
72
72
 
73
73
  ## Procedure
74
74
 
75
+ Title the session `node .agents/scripts/session-title.js --event deliver-prompt --summary "<3–6 words>"` as the path starts ([runbook](../../docs/runbooks/session-titles.md)).
76
+
75
77
  1. **Predict + gate.** Form the predicted footprint (new files, edited files)
76
78
  and record the reason you are taking this path, then run the gate — it
77
79
  documents every flag itself, so run it with `--help` rather than guessing:
@@ -84,7 +86,8 @@ is not being loosened.
84
86
 
85
87
  Branch on `action` in the JSON envelope:
86
88
  - **`proceed-light`** — the receipt Story is authored; read `storyId` and
87
- `nextCommands`, then continue to step 2. The diff backstop in step 4 is
89
+ `nextCommands`, retitle the session `--event deliver --ids <storyId>`,
90
+ then continue to step 2. The diff backstop in step 4 is
88
91
  what bounds the actual change.
89
92
  - **escalation** — no `action` to branch on: the gate emits an
90
93
  **`escalated` terminal envelope** instead (exit 2), attended or not.
@@ -56,6 +56,8 @@ resolves to an empty record), `consoleAllowlist` (default `[]`), and
56
56
 
57
57
  ## Session & ledger (temp/qa/)
58
58
 
59
+ Title the session `node .agents/scripts/session-title.js --event qa --summary "<surface>"` when it starts and `--event qa-done` with the same summary at the `/mandrel-plan` hand-off ([runbook](../../docs/runbooks/session-titles.md)).
60
+
59
61
  Resolve the session and its ledger path **once**, up front, via
60
62
  [`qa-session.js`](../../scripts/lib/qa/qa-session.js):
61
63
 
@@ -76,7 +76,8 @@ to an attended run.
76
76
  Stories first — **announce it**. It hard-errors (exit 1) on an id that is
77
77
  neither a Story nor an Epic, on an Epic with no open children, or on edges
78
78
  it cannot read — a missing gate would co-dispatch against an unlanded
79
- blocker.
79
+ blocker. Then title the session `node .agents/scripts/session-title.js --event deliver --ids <ids>` with the
80
+ ids as typed (the Epic id for an Epic), again on a resume ([runbook](../docs/runbooks/session-titles.md)).
80
81
 
81
82
  2. **Announce (N>1).** Present the resolved order and proceed — do not wait
82
83
  for confirmation; the operator can interject mid-run to change it.
@@ -115,7 +116,8 @@ to an attended run.
115
116
  - **2 / 3 / 4** — `cycleError` / `wedged` / `blocked`: stop the loop and
116
117
  route per reference. **4** is the protocol's HITL pause
117
118
  ([`instructions.md` § 1.J](../instructions.md)) — surface it and wait for
118
- the operator; never poll. A CI red the session can fix leaves its Story
119
+ the operator; never poll. On exit 4, a `blocked` envelope or any HITL
120
+ pause, title the session `--event blocked --ids <blocked ids>`. A CI red the session can fix leaves its Story
119
121
  at `agent::closing`, so it never reaches exit 4.
120
122
 
121
123
  4. **Land what the workers hand back** (§ Closing what the workers hand back —
@@ -123,7 +125,9 @@ to an attended run.
123
125
  **per-run epilogue (N>1)**:
124
126
  `node .agents/scripts/plan-run-epilogue.js --stories 101,102`; N=1 has none
125
127
  ([reference](helpers/deliver-reference.md)). Every close rolls its container
126
- Epic up from its children.
128
+ Epic up from its children. With every Story landed (an N=1 `landed`
129
+ envelope, an N>1 `done: true`), title the session `--event delivered` with
130
+ the step 1 ids.
127
131
 
128
132
  5. **Correct what the change invalidated.** If a memory you recalled this
129
133
  session is now wrong — a trap this landed, a budget it moved — fix that entry
@@ -43,6 +43,8 @@ annotation, which the inventory already carries.
43
43
 
44
44
  ## Start — record authority before the first sweep
45
45
 
46
+ Title the session `node .agents/scripts/session-title.js --event orchestrate` ([runbook](../docs/runbooks/session-titles.md)).
47
+
46
48
  1. Ask the operator which actions this run may take unattended, using the
47
49
  host's question idiom (`.agents/instructions.md` § 1.A), offering each
48
50
  action with its default:
@@ -51,6 +51,8 @@ node .agents/scripts/plan-context.js --seed "<seed>"
51
51
  # or: --seed-file <path> | --tickets 123,456 | --amends #<id>
52
52
  ```
53
53
 
54
+ **Title the session** ([runbook](../docs/runbooks/session-titles.md)): `node .agents/scripts/session-title.js --event plan-seed --summary "<3–6 words>"` in seed / seed-file mode, `--event plan-ticket --ids <ids>` in tickets / amends mode.
55
+
54
56
  It writes the envelope and **`stories.template.json`** (step 2's skeleton) to
55
57
  `<tempRoot>/plan-<slug>/` and prints a digest naming both; `--out` overrides
56
58
  the path. Persist auto-discovers the envelope from `--plan-dir` and derives
@@ -159,6 +161,8 @@ is the **terminal** flip after receipts land; stdout is pure JSON. Tickets mode
159
161
  rewrites a one-for-one source in place, else comments on and closes each
160
162
  source id ([ref](helpers/plan-reference.md)).
161
163
 
164
+ After a clean persist, title the session `node .agents/scripts/session-title.js --event planned --ids <ids>`: the Epic id when one was created or adopted, else the created Story ids ([runbook](../docs/runbooks/session-titles.md)).
165
+
162
166
  ## Constraints
163
167
 
164
168
  - `/mandrel-plan` never starts delivery — its Stories land via
package/README.md CHANGED
@@ -81,6 +81,14 @@ unplanned work: it authors a receipt Story on the fly and escalates to
81
81
  The full process — labels, state, review, troubleshooting — is in
82
82
  [`docs/SDLC.md`](docs/SDLC.md).
83
83
 
84
+ ### The dispatch board
85
+
86
+ `npx mandrel ui` serves a local board on `http://127.0.0.1:4319/` that shows
87
+ every Story's column and environment, and dispatches, resumes or stops a
88
+ delivery when you drag a card (the same actions as `mandrel dispatch`). It is
89
+ bound to your machine and guarded by a per-run token; see the
90
+ [dispatch board runbook](.agents/docs/runbooks/dispatch-board.md).
91
+
84
92
  ## Audits
85
93
 
86
94
  The `/audit-*` workflows are read-only lenses that examine the codebase along