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
@@ -0,0 +1,411 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * Dispatch a Story's delivery to a named environment, resume or stop it, or
5
+ * read the board. `mandrel dispatch` calls {@link runDispatch} too, so both
6
+ * share one implementation, one envelope and one set of exit codes.
7
+ *
8
+ * Exit codes: 0 success, 2 a refusal (`{ ok: false, reason, detail }`),
9
+ * 1 the command itself could not run.
10
+ */
11
+
12
+ import { parseArgs } from 'node:util';
13
+
14
+ import { runAsCli } from './lib/cli-utils.js';
15
+ import { resolveConfig } from './lib/config-resolver.js';
16
+ import { parseBlockedBy } from './lib/dependency-parser.js';
17
+ import {
18
+ agentStateOf,
19
+ commandFor,
20
+ computeLoads,
21
+ ENV_LABEL_COLOR,
22
+ environmentOf,
23
+ envLabel,
24
+ resolveEnvironments,
25
+ } from './lib/dispatch/environments.js';
26
+ import { launchCloud } from './lib/dispatch/launch-cloud.js';
27
+ import { launchLocal, stopLocal } from './lib/dispatch/launch-local.js';
28
+ import {
29
+ readRecord,
30
+ removeRecord,
31
+ writeRecord,
32
+ } from './lib/dispatch/record.js';
33
+ import {
34
+ buildStatus,
35
+ DEFAULT_DONE_LIMIT,
36
+ DONE_LIMITS,
37
+ fetchBoard,
38
+ renderStatus,
39
+ } from './lib/dispatch/status.js';
40
+ import {
41
+ dryRunFields,
42
+ launchedFields,
43
+ launcherFor,
44
+ launchFailureFields,
45
+ releasesLabel,
46
+ stoppedFields,
47
+ } from './lib/dispatch/targets.js';
48
+ import { decide } from './lib/dispatch/verdict.js';
49
+ import { gh as defaultGh } from './lib/gh-exec.js';
50
+ import { AGENT_LABELS, TYPE_LABELS } from './lib/label-constants.js';
51
+ import {
52
+ normalizeOperatorHandle,
53
+ releaseLease,
54
+ } from './lib/orchestration/ticket-lease.js';
55
+ import { transitionTicketState } from './lib/orchestration/ticketing.js';
56
+ import { PROJECT_ROOT } from './lib/project-root.js';
57
+ import { createProvider } from './lib/provider-factory.js';
58
+
59
+ const DISPATCH_USAGE = `Usage: mandrel dispatch --env <name> <storyId>
60
+ mandrel dispatch --resume [--env <name>] <storyId>
61
+ mandrel dispatch --stop <storyId>
62
+ mandrel dispatch --status [--json] [--done-limit <n>]
63
+ (or: node .agents/scripts/dispatch.js with the same flags)
64
+
65
+ Starts an agent::ready Story's delivery in a named environment
66
+ (delivery.environments; one implicit "local" environment when unset),
67
+ labelling the Story env::<name> as the claim. The launched command is the
68
+ environment's argv with {id} replaced by the Story id and {sessionId} by a
69
+ fresh UUID, started detached without a shell; its output goes to
70
+ <tempRoot>/dispatch/story-<id>.log.
71
+ A claude-cloud environment instead fires its Claude Code routine once with
72
+ the payload "mandrel-deliver <id>" and posts the session URL on the Story.
73
+
74
+ Flags:
75
+ --env <name> Environment to dispatch to (required for a dispatch).
76
+ --resume Relaunch an agent::blocked Story in the environment its
77
+ label names; changes no agent::* label.
78
+ --stop Stop the recorded process, release the lease, return the
79
+ Story to agent::ready and remove its env:: label. The
80
+ branch and worktree are kept. A cloud session is not
81
+ stopped: archive it at the printed session URL.
82
+ --status Print environments, load and every Story's column.
83
+ --json With --status, emit the read model as JSON.
84
+ --done-limit <n>
85
+ With --status, how many Done Stories to show, most
86
+ recently closed first: 10, 20 (default), 50 or 100.
87
+ Any other value exits 2.
88
+ --dry-run Print the verdict and the argv (or the cloud request,
89
+ Authorization redacted); write and start nothing.
90
+ --help Show this message.
91
+
92
+ stdout is one JSON envelope. Exit 0 on success, 2 on a refusal
93
+ ({ ok: false, reason, detail }), 1 when the command could not run or a
94
+ cloud fire failed (reason launch-failed, rate-limited or
95
+ launch-unconfirmed).
96
+ `;
97
+
98
+ /** A usage error that exits 2, like a refusal: its envelope is `{ ok, reason, detail }`. */
99
+ class UsageRefusal extends Error {
100
+ constructor(reason, detail) {
101
+ super(detail);
102
+ this.reason = reason;
103
+ }
104
+ }
105
+
106
+ /** A usage refusal exits 2; anything else means the command could not run. */
107
+ function failureResult(err) {
108
+ if (err instanceof UsageRefusal) {
109
+ return {
110
+ code: 2,
111
+ envelope: { ok: false, reason: err.reason, detail: err.message },
112
+ };
113
+ }
114
+ return {
115
+ code: 1,
116
+ envelope: { ok: false, error: err?.message ?? String(err) },
117
+ };
118
+ }
119
+
120
+ function doneLimitOf(raw) {
121
+ if (raw === undefined) return DEFAULT_DONE_LIMIT;
122
+ if (!DONE_LIMITS.map(String).includes(raw)) {
123
+ throw new UsageRefusal(
124
+ 'invalid-done-limit',
125
+ `--done-limit must be one of ${DONE_LIMITS.join(', ')} (see --help)`,
126
+ );
127
+ }
128
+ return Number(raw);
129
+ }
130
+
131
+ const STORY_ID_RE = /^[1-9]\d*$/;
132
+
133
+ function usageError(message) {
134
+ return new Error(`${message} (see --help)`);
135
+ }
136
+
137
+ /**
138
+ * @param {string[]} argv
139
+ * @returns {{ mode: 'dispatch'|'resume'|'stop'|'status', envName: string|null,
140
+ * storyId: number|null, json: boolean, dryRun: boolean, help: boolean,
141
+ * doneLimit: number }}
142
+ */
143
+ function parseDispatchArgv(argv) {
144
+ const { values, positionals } = parseArgs({
145
+ args: argv,
146
+ options: {
147
+ env: { type: 'string' },
148
+ resume: { type: 'boolean', default: false },
149
+ stop: { type: 'boolean', default: false },
150
+ status: { type: 'boolean', default: false },
151
+ json: { type: 'boolean', default: false },
152
+ 'done-limit': { type: 'string' },
153
+ 'dry-run': { type: 'boolean', default: false },
154
+ help: { type: 'boolean', short: 'h', default: false },
155
+ },
156
+ allowPositionals: true,
157
+ strict: true,
158
+ });
159
+ const base = {
160
+ envName: values.env ?? null,
161
+ json: values.json,
162
+ dryRun: values['dry-run'],
163
+ help: values.help,
164
+ };
165
+ if (values.help) return { ...base, mode: 'status', storyId: null };
166
+ base.doneLimit = doneLimitOf(values['done-limit']);
167
+ const modes = ['resume', 'stop', 'status'].filter((m) => values[m]);
168
+ if (modes.length > 1) {
169
+ throw usageError(`--${modes.join(' and --')} are mutually exclusive`);
170
+ }
171
+ const mode = modes[0] ?? 'dispatch';
172
+ if (mode === 'status') return { ...base, mode, storyId: null };
173
+ if (positionals.length !== 1 || !STORY_ID_RE.test(positionals[0])) {
174
+ throw usageError('exactly one positive integer Story id is required');
175
+ }
176
+ if (mode === 'dispatch' && !base.envName) {
177
+ throw usageError('--env <name> is required to dispatch');
178
+ }
179
+ return { ...base, mode, storyId: Number(positionals[0]) };
180
+ }
181
+
182
+ async function openDependencies(provider, body) {
183
+ const unmet = [];
184
+ for (const id of parseBlockedBy(body ?? '')) {
185
+ const dep = await provider.getTicket(id);
186
+ if (String(dep?.state ?? '').toLowerCase() === 'open') unmet.push(id);
187
+ }
188
+ return unmet;
189
+ }
190
+
191
+ /** Everything `decide` needs about one Story, read live. */
192
+ async function gatherVerdictInput({ ctx, mode, storyId, envName }) {
193
+ const { provider, environments } = ctx;
194
+ const story = await provider.getTicket(storyId);
195
+ const isEpic = (story.labels ?? []).includes(TYPE_LABELS.EPIC);
196
+ const children = isEpic
197
+ ? (await provider.getSubTickets(storyId)).map((c) => c.id)
198
+ : [];
199
+ const target = envName ?? environmentOf(story.labels);
200
+ const held = environments.some((e) => e.name === target)
201
+ ? await provider.listTicketsByLabel({
202
+ state: 'open',
203
+ labels: envLabel(target),
204
+ })
205
+ : [];
206
+ return {
207
+ action: mode,
208
+ story,
209
+ envName,
210
+ environments,
211
+ loads: computeLoads(environments, held),
212
+ unmetDependencies: await openDependencies(provider, story.body),
213
+ children,
214
+ operator: ctx.operator,
215
+ };
216
+ }
217
+
218
+ async function launch({ ctx, verdict, storyId }) {
219
+ const { provider, deps, config } = ctx;
220
+ const environment = ctx.environments.find(
221
+ (e) => e.name === verdict.environment,
222
+ );
223
+ const label = envLabel(environment.name);
224
+ if (verdict.applyLabel) {
225
+ await provider.ensureLabels([
226
+ {
227
+ name: label,
228
+ color: ENV_LABEL_COLOR,
229
+ description: `Held by delivery environment "${environment.name}".`,
230
+ },
231
+ ]);
232
+ await provider.updateTicket(storyId, { labels: { add: [label] } });
233
+ }
234
+ const head = {
235
+ action: verdict.action,
236
+ storyId,
237
+ environment: environment.name,
238
+ };
239
+ let record;
240
+ try {
241
+ record = await launcherFor(
242
+ environment,
243
+ deps,
244
+ )({
245
+ storyId,
246
+ environment,
247
+ cwd: ctx.cwd,
248
+ config,
249
+ provider,
250
+ });
251
+ } catch (err) {
252
+ if (releasesLabel(verdict.applyLabel, err)) {
253
+ await provider.updateTicket(storyId, { labels: { remove: [label] } });
254
+ }
255
+ return { ok: false, ...head, ...launchFailureFields(err) };
256
+ }
257
+ deps.writeRecordImpl(record, { config });
258
+ return { ok: true, ...head, ...launchedFields(record) };
259
+ }
260
+
261
+ async function stop({ ctx, verdict, storyId, story }) {
262
+ const { provider, deps, config, operator } = ctx;
263
+ const record = deps.readRecordImpl(storyId, { config });
264
+ if (record?.pid) deps.stopImpl(record.pid);
265
+ if (operator) {
266
+ await deps.releaseLeaseImpl({ provider, ticketId: storyId, operator });
267
+ }
268
+ if (agentStateOf(story.labels) !== AGENT_LABELS.READY) {
269
+ await deps.transitionImpl(provider, storyId, AGENT_LABELS.READY, {
270
+ config,
271
+ });
272
+ }
273
+ await provider.updateTicket(storyId, {
274
+ labels: { remove: [envLabel(verdict.environment)] },
275
+ });
276
+ deps.removeRecordImpl(storyId, { config });
277
+ return {
278
+ ok: true,
279
+ action: 'stop',
280
+ storyId,
281
+ environment: verdict.environment,
282
+ pid: record?.pid ?? null,
283
+ ...stoppedFields(record),
284
+ };
285
+ }
286
+
287
+ function dryRunEnvelope({ ctx, verdict, storyId }) {
288
+ const envelope = {
289
+ ok: true,
290
+ action: verdict.action,
291
+ storyId,
292
+ environment: verdict.environment,
293
+ dryRun: true,
294
+ };
295
+ if (verdict.action === 'stop') return envelope;
296
+ const environment = ctx.environments.find(
297
+ (e) => e.name === verdict.environment,
298
+ );
299
+ return { ...envelope, ...dryRunFields(environment, storyId, commandFor) };
300
+ }
301
+
302
+ async function act(ctx, args) {
303
+ const input = await gatherVerdictInput({ ctx, ...args });
304
+ const verdict = decide(input);
305
+ if (!verdict.ok) return { code: 2, envelope: verdict };
306
+ const step = { ctx, verdict, storyId: args.storyId, story: input.story };
307
+ if (args.dryRun) return { code: 0, envelope: dryRunEnvelope(step) };
308
+ const envelope = args.mode === 'stop' ? await stop(step) : await launch(step);
309
+ // A failed cloud fire is the command failing: exit 1.
310
+ return { code: Number(!envelope.ok), envelope };
311
+ }
312
+
313
+ async function status(ctx, { json, doneLimit }) {
314
+ const board = await ctx.deps.fetchBoardImpl({
315
+ provider: ctx.provider,
316
+ gh: ctx.deps.gh,
317
+ config: ctx.config,
318
+ doneLimit,
319
+ });
320
+ const model = buildStatus({
321
+ environments: ctx.environments,
322
+ ...board,
323
+ operator: ctx.operator,
324
+ doneLimit,
325
+ });
326
+ return json
327
+ ? { code: 0, envelope: model }
328
+ : { code: 0, text: renderStatus(model) };
329
+ }
330
+
331
+ /**
332
+ * The shared entry: parse, decide, act, and write one envelope to stdout.
333
+ *
334
+ * @param {string[]} argv
335
+ * @param {{
336
+ * config?: object, provider?: object, gh?: object, cwd?: string,
337
+ * write?: (s: string) => void,
338
+ * resolveConfigImpl?: typeof resolveConfig,
339
+ * createProviderImpl?: typeof createProvider,
340
+ * launchImpl?: typeof launchLocal, stopImpl?: typeof stopLocal,
341
+ * launchCloudImpl?: typeof launchCloud, fetchImpl?: typeof fetch,
342
+ * env?: Record<string, string|undefined>,
343
+ * fetchBoardImpl?: typeof fetchBoard,
344
+ * transitionImpl?: typeof transitionTicketState,
345
+ * releaseLeaseImpl?: typeof releaseLease,
346
+ * writeRecordImpl?: typeof writeRecord, readRecordImpl?: typeof readRecord,
347
+ * removeRecordImpl?: typeof removeRecord,
348
+ * }} [overrides]
349
+ * @returns {Promise<number>} The exit code.
350
+ */
351
+ export async function runDispatch(argv, overrides = {}) {
352
+ const deps = {
353
+ write: (s) => process.stdout.write(s),
354
+ resolveConfigImpl: resolveConfig,
355
+ createProviderImpl: createProvider,
356
+ launchImpl: launchLocal,
357
+ stopImpl: stopLocal,
358
+ launchCloudImpl: (args) =>
359
+ launchCloud(args, { fetchImpl: deps.fetchImpl, env: deps.env }),
360
+ env: process.env,
361
+ fetchBoardImpl: fetchBoard,
362
+ transitionImpl: transitionTicketState,
363
+ releaseLeaseImpl: releaseLease,
364
+ writeRecordImpl: writeRecord,
365
+ readRecordImpl: readRecord,
366
+ removeRecordImpl: removeRecord,
367
+ gh: defaultGh,
368
+ cwd: PROJECT_ROOT,
369
+ ...overrides,
370
+ };
371
+ let result;
372
+ try {
373
+ const args = parseDispatchArgv(argv);
374
+ if (args.help) {
375
+ deps.write(DISPATCH_USAGE);
376
+ return 0;
377
+ }
378
+ const config = deps.config ?? deps.resolveConfigImpl({ cwd: deps.cwd });
379
+ const ctx = {
380
+ deps,
381
+ config,
382
+ cwd: deps.cwd,
383
+ provider: deps.provider ?? deps.createProviderImpl(config),
384
+ environments: resolveEnvironments(config, deps.env),
385
+ operator: normalizeOperatorHandle(config?.github?.operatorHandle),
386
+ };
387
+ result =
388
+ args.mode === 'status' ? await status(ctx, args) : await act(ctx, args);
389
+ } catch (err) {
390
+ result = failureResult(err);
391
+ }
392
+ deps.write(result.text ?? `${JSON.stringify(result.envelope, null, 2)}\n`);
393
+ return result.code;
394
+ }
395
+
396
+ /**
397
+ * `runDispatch` with the caller's working directory as the default `cwd`:
398
+ * the `mandrel dispatch` entry, whose package root is not the project.
399
+ *
400
+ * @param {string[]} argv
401
+ * @param {Parameters<typeof runDispatch>[1]} [overrides]
402
+ */
403
+ export function runDispatchFromCwd(argv, overrides = {}) {
404
+ return runDispatch(argv, { cwd: process.cwd(), ...overrides });
405
+ }
406
+
407
+ runAsCli(import.meta.url, () => runDispatch(process.argv.slice(2)), {
408
+ source: 'dispatch',
409
+ usage: DISPATCH_USAGE,
410
+ propagateExitCode: true,
411
+ });
@@ -0,0 +1,48 @@
1
+ /**
2
+ * The detached half of the child-process surface; `child-exec.js` owns the
3
+ * `node:child_process` import and injects `spawn` as `run`.
4
+ */
5
+
6
+ import { closeSync, openSync } from 'node:fs';
7
+
8
+ /**
9
+ * Start `file` detached and unreferenced, stdout and stderr appended to
10
+ * `logPath`, so it outlives this process. Resolves with the pid once the
11
+ * child has spawned; rejects on a spawn error (e.g. ENOENT).
12
+ *
13
+ * @param {string} file
14
+ * @param {string[]} args
15
+ * @param {{ logPath: string, cwd?: string, run: Function, open?: Function, close?: Function }} opts
16
+ * @returns {Promise<{ pid: number }>}
17
+ */
18
+ export function detachChild(file, args, opts) {
19
+ const { logPath, cwd, run, open = openSync, close = closeSync } = opts;
20
+ const fd = open(logPath, 'a');
21
+ return new Promise((resolve, reject) => {
22
+ let settled = false;
23
+ const settle = (fn, value) => {
24
+ if (settled) return;
25
+ settled = true;
26
+ close(fd);
27
+ fn(value);
28
+ };
29
+ let child;
30
+ try {
31
+ child = run(file, args, {
32
+ cwd,
33
+ detached: true,
34
+ shell: false,
35
+ stdio: ['ignore', fd, fd],
36
+ windowsHide: true,
37
+ });
38
+ } catch (err) {
39
+ settle(reject, err);
40
+ return;
41
+ }
42
+ child.once('error', (err) => settle(reject, err));
43
+ child.once('spawn', () => {
44
+ child.unref();
45
+ settle(resolve, { pid: child.pid });
46
+ });
47
+ });
48
+ }
@@ -12,6 +12,7 @@
12
12
  import { execFile, execFileSync, spawn, spawnSync } from 'node:child_process';
13
13
  import { promisify } from 'node:util';
14
14
 
15
+ import { detachChild } from './child-detached.js';
15
16
  import { streamChild } from './child-stream.js';
16
17
 
17
18
  const MIB = 1024 * 1024;
@@ -170,6 +171,16 @@ export async function spawnCaptureNullableAsync(file, args, opts = {}) {
170
171
  export const spawnStreamAsync = (file, args, opts = {}) =>
171
172
  streamChild(file, args, { spawnImpl: spawn, ...opts });
172
173
 
174
+ /**
175
+ * Start a child detached, output appended to a log; see `child-detached.js`.
176
+ *
177
+ * @param {string} file
178
+ * @param {string[]} args
179
+ * @param {{ logPath: string, cwd?: string }} opts
180
+ */
181
+ export const spawnDetached = (file, args, opts) =>
182
+ detachChild(file, args, { run: spawn, ...opts });
183
+
173
184
  /**
174
185
  * `status=null` is printed verbatim: it means the child was killed.
175
186
  *
@@ -11,17 +11,20 @@ export const DELIVERY_ROUTING_DEFAULTS = Object.freeze({
11
11
  ceremonyProfile: 'standard',
12
12
  /** Land through merge in one close; opt out with `--no-wait-merge`. */
13
13
  closeAndLand: true,
14
+ /** Retitle the host session with a state glyph (`session-title.js`). */
15
+ sessionTitles: true,
14
16
  });
15
17
 
18
+ const CEREMONY_PROFILES = ['minimal', 'standard', 'strict'];
19
+
16
20
  /**
17
21
  * @param {unknown} value
18
22
  * @returns {'minimal'|'standard'|'strict'}
19
23
  */
20
24
  function normalizeCeremonyProfile(value) {
21
- if (value === 'minimal' || value === 'standard' || value === 'strict') {
22
- return value;
23
- }
24
- return DELIVERY_ROUTING_DEFAULTS.ceremonyProfile;
25
+ return CEREMONY_PROFILES.includes(value)
26
+ ? value
27
+ : DELIVERY_ROUTING_DEFAULTS.ceremonyProfile;
25
28
  }
26
29
 
27
30
  /**
@@ -32,19 +35,19 @@ function normalizeCeremonyProfile(value) {
32
35
  * roleScopedAgents: boolean,
33
36
  * ceremonyProfile: 'minimal'|'standard'|'strict',
34
37
  * closeAndLand: boolean,
38
+ * sessionTitles: boolean,
35
39
  * }}
36
40
  */
37
41
  export function getDeliveryRouting(config) {
38
42
  const routing = config?.delivery?.routing ?? config?.routing ?? config ?? {};
43
+ const flag = (key) =>
44
+ typeof routing[key] === 'boolean'
45
+ ? routing[key]
46
+ : DELIVERY_ROUTING_DEFAULTS[key];
39
47
  return {
40
- roleScopedAgents:
41
- typeof routing.roleScopedAgents === 'boolean'
42
- ? routing.roleScopedAgents
43
- : DELIVERY_ROUTING_DEFAULTS.roleScopedAgents,
48
+ roleScopedAgents: flag('roleScopedAgents'),
44
49
  ceremonyProfile: normalizeCeremonyProfile(routing.ceremonyProfile),
45
- closeAndLand:
46
- typeof routing.closeAndLand === 'boolean'
47
- ? routing.closeAndLand
48
- : DELIVERY_ROUTING_DEFAULTS.closeAndLand,
50
+ closeAndLand: flag('closeAndLand'),
51
+ sessionTitles: flag('sessionTitles'),
49
52
  };
50
53
  }
@@ -210,6 +210,32 @@ export function storyProgressPath(sid, config) {
210
210
  );
211
211
  }
212
212
 
213
+ /**
214
+ * `<tempRoot>/dispatch/story-<id>.log`: a dispatched delivery's output.
215
+ *
216
+ * @param {number} sid
217
+ * @param {object} [config]
218
+ * @returns {string}
219
+ */
220
+ export function dispatchLogPath(sid, config) {
221
+ return path.join(
222
+ anchorTempRoot(tempRootFrom(config)),
223
+ 'dispatch',
224
+ `story-${storyId(sid)}.log`,
225
+ );
226
+ }
227
+
228
+ /**
229
+ * The dispatch record (`pid`, `argv`, …) beside {@link dispatchLogPath}.
230
+ *
231
+ * @param {number} sid
232
+ * @param {object} [config]
233
+ * @returns {string}
234
+ */
235
+ export function dispatchRecordPath(sid, config) {
236
+ return dispatchLogPath(sid, config).replace(/\.log$/, '.json');
237
+ }
238
+
213
239
  const runId = (id) => {
214
240
  if (!Number.isInteger(id) || id <= 0) {
215
241
  throw new Error(`[temp-paths] runId must be a positive integer; got ${id}`);
@@ -307,6 +307,12 @@ const ROUTING_SCHEMA = {
307
307
  'When true (default), single-story-close lands through merge in one close. Opt out per-run with --no-wait-merge.',
308
308
  default: DELIVERY_ROUTING_DEFAULTS.closeAndLand,
309
309
  },
310
+ sessionTitles: {
311
+ type: 'boolean',
312
+ description:
313
+ 'When true (default), plan, deliver, orchestrate, audit and QA runs retitle the top-level host session with a state glyph (○ planning, ◐ in progress, ● done, ⊗ blocked) via session-title.js, on hosts that expose a session-title tool. False makes session-title.js answer apply: false, so no step renames anything.',
314
+ default: DELIVERY_ROUTING_DEFAULTS.sessionTitles,
315
+ },
310
316
  agentModels: {
311
317
  type: 'object',
312
318
  description:
@@ -558,6 +564,44 @@ const TEMP_RETENTION_SCHEMA = {
558
564
  additionalProperties: false,
559
565
  };
560
566
 
567
+ const ENVIRONMENT_CAPACITY = { type: 'integer', minimum: 1 };
568
+
569
+ const ENVIRONMENTS_SCHEMA = {
570
+ type: 'object',
571
+ description:
572
+ 'Named delivery environments for `mandrel dispatch`, keyed by name (lowercase letters, digits and hyphens, at most 31 characters). `target` is where the delivery runs and `capacity` how many Stories may hold the environment at once (default 1). A `local` entry may set `command`, the argv started for a Story with `{id}` replaced by the Story id and `{sessionId}` by a fresh UUID per launch (default `["claude", "-p", "/mandrel-deliver {id}", "--session-id", "{sessionId}", "--name", "◐ Delivery #{id}", "--output-format", "stream-json", "--verbose"]`), spawned without a shell. A `claude-cloud` entry fires a Claude Code routine instead: it requires `routine` (the routine id, `trig_…`) and `tokenEnv` (the NAME of the environment variable holding the routine token, never the token) and takes no `command`. Unset, one implicit `local` environment with capacity 1 is used. `.agentrc.local.json` adds or overrides an entry through the usual merge.',
573
+ propertyNames: { pattern: '^[a-z0-9][a-z0-9-]{0,30}$' },
574
+ additionalProperties: {
575
+ oneOf: [
576
+ {
577
+ type: 'object',
578
+ properties: {
579
+ target: { const: 'local' },
580
+ capacity: ENVIRONMENT_CAPACITY,
581
+ command: {
582
+ type: 'array',
583
+ minItems: 1,
584
+ items: { type: 'string', minLength: 1 },
585
+ },
586
+ },
587
+ required: ['target'],
588
+ additionalProperties: false,
589
+ },
590
+ {
591
+ type: 'object',
592
+ properties: {
593
+ target: { const: 'claude-cloud' },
594
+ capacity: ENVIRONMENT_CAPACITY,
595
+ routine: { type: 'string', pattern: '^trig_[A-Za-z0-9_]+$' },
596
+ tokenEnv: { type: 'string', pattern: '^[A-Z][A-Z0-9_]*$' },
597
+ },
598
+ required: ['target', 'routine', 'tokenEnv'],
599
+ additionalProperties: false,
600
+ },
601
+ ],
602
+ },
603
+ };
604
+
561
605
  export const DELIVERY_SCHEMA = {
562
606
  type: 'object',
563
607
  description:
@@ -581,6 +625,7 @@ export const DELIVERY_SCHEMA = {
581
625
  handoff: HANDOFF_SCHEMA,
582
626
  orchestrate: ORCHESTRATE_SCHEMA,
583
627
  routing: ROUTING_SCHEMA,
628
+ environments: ENVIRONMENTS_SCHEMA,
584
629
  },
585
630
  additionalProperties: false,
586
631
  };