pi-braid 0.43.27 → 0.43.29

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.
package/CHANGELOG.md CHANGED
@@ -96,6 +96,61 @@ record; the tag scheme above applies unchanged.
96
96
  note that a clean disable releases it, because a refusal an operator cannot act on
97
97
  is a support ticket.
98
98
 
99
+ ## Core — 0.43.29 (2026-11-06: the journal pointer names the intent that is still open)
100
+
101
+ - **A line count cannot tell a pending install from forty closed outcomes.** The
102
+ session-start pointer was built from the number of journal lines, so a project
103
+ holding a handoff printed the same sentence as a project holding a finished
104
+ week. It now reads the journal, selects the entries whose `kind` is `intent`
105
+ and whose `status` is `open`, and names up to three of them with their age in
106
+ hours, `+N more open` beyond that, under a 480-character ceiling: the intent
107
+ whose `expires_at` has passed is printed as `EXPIRED` with the same age, and
108
+ the sentence asks for what ending it takes.
109
+
110
+ - **Nothing open means nothing new, and a broken line is not a crash.** With no
111
+ open intent the pointer is byte-identical to the sentence the old code
112
+ produced, which the fixture asserts in full rather than by substring. A line
113
+ that is not JSON, an entry without `kind`, and an unparseable `expires_at` are
114
+ skipped, so a hand-edited journal still yields the count.
115
+
116
+ - **Measured on a journal that already had handoffs waiting.** Against this
117
+ machine's own project journal the pointer printed three intents 72 hours old,
118
+ which is the class of thing the old sentence hid. Twelve fixtures cover the
119
+ named, expired, overflowing, closed-only and malformed cases; the planted
120
+ revert disables the selection and eight of them redden; the core chain reports
121
+ 343 fixtures passed and placement reports 0 hits with 269 excluded.
122
+
123
+ ## Core — 0.43.28 (2026-11-06: the queue is read from the registry, not remembered by the seat)
124
+
125
+ - **A registry that records what a worker does but not where it sits in a queue
126
+ makes the seat the queue.** The entry now carries `priority` (lower runs
127
+ sooner, unranked last) and `dependsOn`, admission refuses an unknown id, a
128
+ self-dependency and an edge that would close a loop (the refusal prints the
129
+ loop), and `update-worker` may move a rank but never a dependency, because a
130
+ worker that gains a dependency after it started is a second unit of work
131
+ wearing the first one's id.
132
+
133
+ - **`blocked` is computed, never stored.** A row waiting on an id that has not
134
+ delivered reports `blocked` with the blocking ids named, while the stored
135
+ lifecycle status is reported beside it and never overwritten. Satisfaction is
136
+ `merged` or `completed` and nothing else: a worker that closed, errored,
137
+ stalled or was caught false-done did not deliver the thing the next one waits
138
+ for. A closed row still satisfies its dependents, so the listing reads
139
+ satisfaction against the whole registry before it filters.
140
+
141
+ - **The listing is actionable order and the old registry still loads.** Rows
142
+ with no unsatisfied dependency come first by rank, ties by admission time and
143
+ id, and blocked rows follow with a `blocked-by:` marker. A registry written by
144
+ 0.43.27 has neither field, normalizes to unranked and wait-free on read, and
145
+ writes nothing back.
146
+
147
+ - **Measured before the merge.** 17 fixtures in the new file, red and green
148
+ around every refusal; the planted revert disables cycle detection and two of
149
+ them redden; the core chain reports 343 fixtures passed; placement reports 0
150
+ hits with 269 excluded; and the satisfaction rule was re-derived outside the
151
+ suite on one registry built by hand, where a dependency in `closed`, `error`,
152
+ `stalled` or `false-done` blocks its dependent and `merged` releases it.
153
+
99
154
  ## Core — 0.43.27 (2026-11-05: the ship list stays as it was, and a dropped promise is a failed gate)
100
155
 
101
156
  - **A case nobody listens to is not a passing case.** Half the fixtures here
package/build-info.json CHANGED
@@ -1,9 +1,9 @@
1
1
  {
2
2
  "name": "pi-braid",
3
- "version": "0.43.27",
4
- "sha": "ad2a5b832b4b8f03ef2bc7eeffcb090eac793a35",
5
- "shaShort": "ad2a5b83",
3
+ "version": "0.43.29",
4
+ "sha": "25a90502b8016505c7e7af5be4b9cff9d1577e6c",
5
+ "shaShort": "25a90502",
6
6
  "branch": "detached",
7
7
  "dirty": false,
8
- "packedAt": "2026-11-05T18:36:49.717Z"
8
+ "packedAt": "2026-11-06T12:50:48.597Z"
9
9
  }
@@ -0,0 +1,64 @@
1
+ /**
2
+ * What the session-start journal pointer says about work still open.
3
+ *
4
+ * The pointer used to be built from a line count alone, so a journal holding a
5
+ * pending install and a journal holding forty closed outcomes printed the same
6
+ * sentence: the seat beginning the day could not tell that something was
7
+ * waiting for it. Naming the open intents costs a sentence in the first prompt
8
+ * of every session, so the whole text keeps a fixed ceiling and gives up detail
9
+ * in a fixed order instead of growing with the journal.
10
+ *
11
+ * Reading is line-level: an entry counts when its `kind` is `intent` and its
12
+ * `status` is `open`. The digest printer derives a subject's status across
13
+ * supersession chains and stays the authority on the full program, so a name
14
+ * here can be an intent a later line retired; against this project's journal
15
+ * when the pointer was written, five of the seven open-status intents were
16
+ * already retired that way. The trade is deliberate and the digest is where a
17
+ * seat confirms what is live: naming work already closed costs a line of
18
+ * attention, while hiding an install nobody was told about is the failure this
19
+ * pointer exists to repair. Honoring the journal's own `supersedes` edges is
20
+ * what would narrow it, and that is one line of selection, not one of wording.
21
+ */
22
+ /** Ceiling for the whole pointer text. A line delivered into every session is
23
+ * paid for by every turn that follows it, so the cost is per session, not per
24
+ * journal entry. */
25
+ export declare const JOURNAL_PRIOR_BUDGET = 480;
26
+ /** What the pointer needs from the handler: the line count it always printed,
27
+ * and the path it names. */
28
+ export interface JournalPointerFacts {
29
+ count: number;
30
+ journalFile: string;
31
+ }
32
+ /** One intent whose `status` says `open`. */
33
+ export interface OpenIntent {
34
+ subject: string;
35
+ /** Whole hours since the entry's own `at`; null when that stamp is unusable,
36
+ * which is reported as no age rather than as a guess. */
37
+ ageHours: number | null;
38
+ /** The entry's `expires_at`, kept only when it parses. A broken stamp is a
39
+ * missing detail, never a reason to hide the intent behind it. */
40
+ expiresAt: string | null;
41
+ expired: boolean;
42
+ }
43
+ /**
44
+ * The journal lines that name open work.
45
+ *
46
+ * Anything unreadable is skipped: a line that is not JSON, a value that is not
47
+ * an object, an entry without a usable `subject`, and an `expires_at` that does
48
+ * not parse (the stamp is dropped, the intent is not). A journal is written by
49
+ * a different process and edited by hand, so a reader that throws on the first
50
+ * malformed line would take the whole session-start bundle down with it.
51
+ */
52
+ export declare function selectOpenIntents(journalText: string, now: Date): OpenIntent[];
53
+ /**
54
+ * The journal pointer, complete: the sentence this step has always printed,
55
+ * extended with what is open.
56
+ *
57
+ * With nothing open the result is the original text byte for byte. With work
58
+ * open the count-and-path sentence is kept and the digest printer is restated
59
+ * in its short form: with a 91-character journal path the long form plus one
60
+ * expired intent is 527 characters against the 480 ceiling, and the sentence
61
+ * that motivates reading the journal is the one with room to yield.
62
+ */
63
+ export declare function journalPriorText(facts: JournalPointerFacts, journalText: string, now: Date): string;
64
+ //# sourceMappingURL=open-intents.d.ts.map
@@ -0,0 +1,183 @@
1
+ /**
2
+ * What the session-start journal pointer says about work still open.
3
+ *
4
+ * The pointer used to be built from a line count alone, so a journal holding a
5
+ * pending install and a journal holding forty closed outcomes printed the same
6
+ * sentence: the seat beginning the day could not tell that something was
7
+ * waiting for it. Naming the open intents costs a sentence in the first prompt
8
+ * of every session, so the whole text keeps a fixed ceiling and gives up detail
9
+ * in a fixed order instead of growing with the journal.
10
+ *
11
+ * Reading is line-level: an entry counts when its `kind` is `intent` and its
12
+ * `status` is `open`. The digest printer derives a subject's status across
13
+ * supersession chains and stays the authority on the full program, so a name
14
+ * here can be an intent a later line retired; against this project's journal
15
+ * when the pointer was written, five of the seven open-status intents were
16
+ * already retired that way. The trade is deliberate and the digest is where a
17
+ * seat confirms what is live: naming work already closed costs a line of
18
+ * attention, while hiding an install nobody was told about is the failure this
19
+ * pointer exists to repair. Honoring the journal's own `supersedes` edges is
20
+ * what would narrow it, and that is one line of selection, not one of wording.
21
+ */
22
+ /** Ceiling for the whole pointer text. A line delivered into every session is
23
+ * paid for by every turn that follows it, so the cost is per session, not per
24
+ * journal entry. */
25
+ export const JOURNAL_PRIOR_BUDGET = 480;
26
+ /** Named intents in the text; the rest are counted. Three subjects are about as
27
+ * many as a reader can carry into the work they were about to start. */
28
+ const NAMED_INTENT_LIMIT = 3;
29
+ /** Longest subject rendered. The journal writer admits slugs up to 64
30
+ * characters, so one hostile line would otherwise spend the budget alone. */
31
+ const SUBJECT_LIMIT = 32;
32
+ const HOUR_MS = 3_600_000;
33
+ const DIGEST_COMMAND = "packages/core/scripts/check-journal.mjs --digest";
34
+ /** The closing sentence of the pointer when nothing is open. Shown to every
35
+ * session, so it keeps its exact words. */
36
+ const DIGEST_POINTER = `Read the open program before acting (digest printer: ${DIGEST_COMMAND}), so a decision gets superseded, not rediscovered.`;
37
+ /** The same printer, said shorter: naming what is open already answers the
38
+ * question the long form motivates, and the room it frees is what pays for
39
+ * the names. */
40
+ const DIGEST_POINTER_SHORT = `Full program: ${DIGEST_COMMAND}.`;
41
+ const CLOSE_SINGLE = "Run the install it names, or close it with the reason it will not run.";
42
+ const CLOSE_PLURAL = "Run the install each names, or close it with the reason it will not run.";
43
+ /**
44
+ * The journal lines that name open work.
45
+ *
46
+ * Anything unreadable is skipped: a line that is not JSON, a value that is not
47
+ * an object, an entry without a usable `subject`, and an `expires_at` that does
48
+ * not parse (the stamp is dropped, the intent is not). A journal is written by
49
+ * a different process and edited by hand, so a reader that throws on the first
50
+ * malformed line would take the whole session-start bundle down with it.
51
+ */
52
+ export function selectOpenIntents(journalText, now) {
53
+ const open = [];
54
+ for (const line of journalText.split("\n")) {
55
+ if (!line.trim())
56
+ continue;
57
+ const entry = parseEntry(line);
58
+ if (!entry)
59
+ continue;
60
+ if (entry.kind !== "intent" || entry.status !== "open")
61
+ continue;
62
+ const subject = typeof entry.subject === "string" ? entry.subject.trim() : "";
63
+ if (!subject)
64
+ continue;
65
+ const writtenAt = typeof entry.at === "string" ? Date.parse(entry.at) : Number.NaN;
66
+ const expiresAt = typeof entry.expires_at === "string" ? Date.parse(entry.expires_at) : Number.NaN;
67
+ open.push({
68
+ subject,
69
+ ageHours: Number.isNaN(writtenAt)
70
+ ? null
71
+ : Math.max(0, Math.floor((now.getTime() - writtenAt) / HOUR_MS)),
72
+ expiresAt: Number.isNaN(expiresAt) ? null : entry.expires_at,
73
+ expired: !Number.isNaN(expiresAt) && expiresAt < now.getTime(),
74
+ });
75
+ }
76
+ // The intent whose window already closed is the one a reader has to act on,
77
+ // so it is named before the rest; journal order stands inside each group.
78
+ return [...open.filter((intent) => intent.expired), ...open.filter((intent) => !intent.expired)];
79
+ }
80
+ /**
81
+ * The journal pointer, complete: the sentence this step has always printed,
82
+ * extended with what is open.
83
+ *
84
+ * With nothing open the result is the original text byte for byte. With work
85
+ * open the count-and-path sentence is kept and the digest printer is restated
86
+ * in its short form: with a 91-character journal path the long form plus one
87
+ * expired intent is 527 characters against the 480 ceiling, and the sentence
88
+ * that motivates reading the journal is the one with room to yield.
89
+ */
90
+ export function journalPriorText(facts, journalText, now) {
91
+ const intro = journalIntro(facts);
92
+ const open = selectOpenIntents(journalText, now);
93
+ if (open.length === 0)
94
+ return `${intro} ${DIGEST_POINTER}`;
95
+ // Detail is given up in order of what a reader needs it for: the name of a
96
+ // waiting install, then the moment its window closes, then the standing
97
+ // pointer to the full program, then the count alone. Dropping the names to
98
+ // keep the pointer would save the cheaper fact and hide the dearer one.
99
+ const ladder = [
100
+ `${intro} ${describeOpen(open, "stamped")} ${DIGEST_POINTER_SHORT}`,
101
+ `${intro} ${describeOpen(open, "plain")} ${DIGEST_POINTER_SHORT}`,
102
+ `${intro} ${describeOpen(open, "stamped")}`,
103
+ `${intro} ${describeOpen(open, "plain")}`,
104
+ `${intro} ${countedSentence(open)} ${DIGEST_POINTER_SHORT}`,
105
+ `${intro} ${countedSentence(open)}`,
106
+ `${intro} ${open.length} open intent${open.length === 1 ? "" : "s"}.`,
107
+ ];
108
+ // Richest description that fits. The last rung is printed rather than
109
+ // dropped when nothing fits: a journal path long enough to spend the ceiling
110
+ // alone is a reason to say less, never a reason to leave a pending install
111
+ // unmentioned.
112
+ return ladder.find((text) => text.length < JOURNAL_PRIOR_BUDGET) ?? ladder[ladder.length - 1];
113
+ }
114
+ function journalIntro({ count, journalFile }) {
115
+ return (`The project journal holds ${count} entr${count === 1 ? "y" : "ies"} at ${journalFile} -- ` +
116
+ `what earlier seats decided and why, readable without their sessions.`);
117
+ }
118
+ function describeOpen(open, detail) {
119
+ if (detail === "counted")
120
+ return countedSentence(open);
121
+ const withStamp = detail === "stamped";
122
+ return open.length === 1 ? singleSentence(open[0], withStamp) : listSentence(open, withStamp);
123
+ }
124
+ /** One open intent reads as a sentence: a list of one is a fragment, and the
125
+ * instruction that follows it addresses a single install. */
126
+ function singleSentence(intent, withStamp) {
127
+ const opening = intent.expired
128
+ ? "One intent is still open and EXPIRED"
129
+ : "One intent is still open";
130
+ return `${opening}: ${named(intent)}${roundStamp(intent, withStamp)}. ${CLOSE_SINGLE}`;
131
+ }
132
+ function listSentence(open, withStamp) {
133
+ const items = open.slice(0, NAMED_INTENT_LIMIT).map((intent) => listItem(intent, withStamp));
134
+ const rest = open.length - Math.min(open.length, NAMED_INTENT_LIMIT);
135
+ const more = rest > 0 ? `; +${rest} more open` : "";
136
+ return `Open intents: ${items.join("; ")}${more}. ${CLOSE_PLURAL}`;
137
+ }
138
+ /** The expired marker stays in the lean form: it is the fact a reader acts on,
139
+ * while the exact moment is one the digest can restate. */
140
+ function listItem(intent, withStamp) {
141
+ const expired = intent.expired ? ", EXPIRED" : "";
142
+ if (!withStamp || intent.expiresAt === null)
143
+ return `${named(intent)}${expired}`;
144
+ return intent.expired
145
+ ? `${named(intent)}, EXPIRED (expires_at ${intent.expiresAt})`
146
+ : `${named(intent)}, expires ${intent.expiresAt}`;
147
+ }
148
+ /** In the single sentence the opening clause already carries the EXPIRED word,
149
+ * so this adds the moment alone. */
150
+ function roundStamp(intent, withStamp) {
151
+ if (!withStamp || intent.expiresAt === null)
152
+ return "";
153
+ return intent.expired ? ` (expires_at ${intent.expiresAt})` : ` (expires ${intent.expiresAt})`;
154
+ }
155
+ function countedSentence(open) {
156
+ const expired = open.filter((intent) => intent.expired).length;
157
+ const ages = open
158
+ .map((intent) => intent.ageHours)
159
+ .filter((hours) => hours !== null);
160
+ const oldest = ages.length > 0 ? `, oldest ${Math.max(...ages)}h old` : "";
161
+ const lapsed = expired > 0 ? `, ${expired} EXPIRED` : "";
162
+ const count = `${open.length} open intent${open.length === 1 ? "" : "s"} in this journal`;
163
+ return `${count}${oldest}${lapsed}. ${open.length === 1 ? CLOSE_SINGLE : CLOSE_PLURAL}`;
164
+ }
165
+ function named(intent) {
166
+ const age = intent.ageHours === null ? "" : ` ${intent.ageHours}h old`;
167
+ return `"${clipSubject(intent.subject)}"${age}`;
168
+ }
169
+ function clipSubject(subject) {
170
+ return subject.length <= SUBJECT_LIMIT ? subject : `${subject.slice(0, SUBJECT_LIMIT - 1)}…`;
171
+ }
172
+ function parseEntry(line) {
173
+ try {
174
+ const value = JSON.parse(line);
175
+ if (value === null || typeof value !== "object" || Array.isArray(value))
176
+ return null;
177
+ return value;
178
+ }
179
+ catch {
180
+ return null;
181
+ }
182
+ }
183
+ //# sourceMappingURL=open-intents.js.map
@@ -36,6 +36,7 @@ import { isProjectSignalShown, markProjectSignalShown, reconstructShownSignalsFr
36
36
  import { episodesFilePath, semanticMemoryFilePath, AGENT, braidDir, journalFilePath, tagsSlugFromCwd, } from "../../../lib/config/braid-paths.js";
37
37
  import { projectSlugFromCwd } from "../../memory/scratchpad/persistence.js";
38
38
  import { readResumeScratchpadState } from "../resume-state.js";
39
+ import { journalPriorText } from "./open-intents.js";
39
40
  const log = createLogger("enforcement:session-start-discoverability");
40
41
  /**
41
42
  * Register the SESSION_START discoverability handler.
@@ -201,21 +202,20 @@ export function registerSessionStartDiscoverability(pi) {
201
202
  // 7. The owner-input journal. The path comes from the constant the
202
203
  // writer appends through, never a hand-built shape: two spellings for
203
204
  // one file is how the scratchpad pointer armed itself against a file
204
- // nothing writes (see step 1).
205
+ // nothing writes (see step 1). The text is composed in `open-intents`,
206
+ // which also names the intents whose status says open: a journal holding
207
+ // a pending install printed the same count sentence as one holding forty
208
+ // closed outcomes, so the seat could not see that work was waiting.
205
209
  try {
206
210
  const slug = projectSlugFromCwd(cwd);
207
211
  const journalFile = journalFilePath(slug);
208
212
  if (existsSync(journalFile)) {
209
- const count = readFileSync(journalFile, "utf-8")
210
- .split("\n")
211
- .filter((line) => line.trim()).length;
213
+ const journalText = readFileSync(journalFile, "utf-8");
214
+ const count = journalText.split("\n").filter((line) => line.trim()).length;
212
215
  if (count > 0) {
213
216
  signals.push({
214
217
  type: "journal_prior",
215
- text: `The project journal holds ${count} entr${count === 1 ? "y" : "ies"} at ${journalFile} -- ` +
216
- `what earlier seats decided and why, readable without their sessions. ` +
217
- `Read the open program before acting (digest printer: packages/core/scripts/check-journal.mjs --digest), ` +
218
- `so a decision gets superseded, not rediscovered.`,
218
+ text: journalPriorText({ count, journalFile }, journalText, new Date()),
219
219
  });
220
220
  }
221
221
  }
@@ -18,6 +18,9 @@ import { execFileSync } from "node:child_process";
18
18
  import { Type } from "typebox";
19
19
  import { createLogger } from "../../lib/core/logger.js";
20
20
  import { acquireLock, releaseLock, getConflicts, getAllLocks, createWorkerBranch, deleteWorkerBranch, getDiff, getCurrentBranch, findRepoRoot, branchExists, gitAvailable, worktreeForBranch, scanAddedLinesForSlop, registerWorker, updateWorker, closeWorker, recordWorkerMerge, readWorkers, checkWorker, parseWorkerStatus, parseWorkerOutcome, decideAdmission, recordAdmissionRefusal, resolveRequestId, computeWorkerStats, workerEffectEvidenceForEntry, locateResultSchema, readPopulationStamps, populationRefusalDetail, WORKER_EFFECT_EVIDENCE_FLAG, WORKER_SPECS, WORKER_OUTCOMES, WORKER_STATUSES, WORKER_STATUS_LAYERS, } from "../../lib/orchestrator/index.js";
21
+ // The queue-fact readers come from their module directly: the barrel above is
22
+ // one way into the library, not the only one, and it does not re-export these.
23
+ import { normalizeDependsOn, orderWorkerRows, validateDependencies, } from "../../lib/orchestrator/workers.js";
21
24
  const log = createLogger("orchestrator");
22
25
  // Helpers
23
26
  /**
@@ -313,7 +316,23 @@ function textResult(text, details = {}) {
313
316
  /** One-line registry listing for a worker entry. */
314
317
  function workerLine(entry) {
315
318
  const closed = entry.closedAt ? ` closed=${entry.closedAt}` : "";
316
- return ` ${entry.workerId} spec=${entry.spec} status=${entry.status} pane=${entry.pane ?? "-"} session=${entry.workerSession ?? "-"} output=${entry.outputFile ?? "-"} branch=${entry.branch ?? "-"}${closed}`;
319
+ // Printed only when the row carries one: an unranked, wait-free row keeps the
320
+ // line it had before the queue facts existed.
321
+ const priority = typeof entry.priority === "number" ? ` priority=${entry.priority}` : "";
322
+ const dependsOn = Array.isArray(entry.dependsOn) && entry.dependsOn.length > 0
323
+ ? ` depends-on=${entry.dependsOn.join(", ")}`
324
+ : "";
325
+ return ` ${entry.workerId} spec=${entry.spec} status=${entry.status} pane=${entry.pane ?? "-"} session=${entry.workerSession ?? "-"} output=${entry.outputFile ?? "-"} branch=${entry.branch ?? "-"}${closed}${priority}${dependsOn}`;
326
+ }
327
+ /**
328
+ * One listing entry: the row line, plus the ids holding it after it, indented
329
+ * under the row so the marker can never be read as a row of its own.
330
+ */
331
+ function workerListLine(row) {
332
+ const line = workerLine(row.entry);
333
+ if (row.blockedBy.length === 0)
334
+ return line;
335
+ return `${line}\n blocked-by: ${row.blockedBy.join(", ")}`;
317
336
  }
318
337
  /**
319
338
  * Render the fleet statistics as the block `list-workers` appends when stats
@@ -339,6 +358,8 @@ function formatCheckVerdict(verdict) {
339
358
  return [
340
359
  `Worker ${verdict.workerId}`,
341
360
  `status: ${verdict.status}`,
361
+ `storedStatus: ${verdict.storedStatus}`,
362
+ `blockedBy: ${verdict.blockedBy.length > 0 ? verdict.blockedBy.join(", ") : "-"}`,
342
363
  `reason: ${verdict.reason}`,
343
364
  `outputFile: ${verdict.outputFile ?? "-"} (${age})`,
344
365
  `sessionGrowthAgeSec: ${verdict.sessionGrowthAgeSec ?? "-"}`,
@@ -457,6 +478,20 @@ const orchestrateTool = {
457
478
  status: Type.Optional(Type.String({
458
479
  description: "Lifecycle status for update-worker (see the tool description).",
459
480
  })),
481
+ priority: Type.Optional(
482
+ // `{ anyOf: [{ type: "number" }, { type: "null" }] }` written as its own
483
+ // keywords: the builder's named constructors have no null literal, and the
484
+ // schema this hand-built object emits is plain JSON Schema.
485
+ Type.Unsafe({
486
+ anyOf: [{ type: "number" }, { type: "null" }],
487
+ description: "Queue rank: lower runs sooner; null is unranked, which sorts after every ranked row. " +
488
+ "spawn-worker/register-worker record it at admission; update-worker changes or clears it.",
489
+ })),
490
+ dependsOn: Type.Optional(Type.Array(Type.String(), {
491
+ description: "Worker ids this row waits for (spawn-worker/register-worker only: dependencies are fixed at admission). " +
492
+ "Refused when an id is unknown, is this worker's own id, or would close a loop; a refused admission writes nothing. " +
493
+ "check-worker reports `blocked`, naming these ids, while any of them is not merged or completed.",
494
+ })),
460
495
  phase: Type.Optional(Type.String({
461
496
  description: "update-worker: checkpoint phase the worker is in (e.g. impl, gates). Requires lastStep; the registry stamps the time.",
462
497
  })),
@@ -498,7 +533,7 @@ const orchestrateTool = {
498
533
  })),
499
534
  }),
500
535
  execute: async (_id, params, _signal, _onUpdate, _ctx) => {
501
- const { action, workerId, slug, files, branch, baseBranch, cwd: explicitCwd, spec, outputFile, pane, workspace, workerSession, status, phase, lastStep, requestId, outcome, gates, includeClosed, includeStats, liveStatus, } = params;
536
+ const { action, workerId, slug, files, branch, baseBranch, cwd: explicitCwd, spec, outputFile, pane, workspace, workerSession, status, priority, dependsOn, phase, lastStep, requestId, outcome, gates, includeClosed, includeStats, liveStatus, } = params;
502
537
  const repoRoot = resolveCwd(explicitCwd, files);
503
538
  switch (action) {
504
539
  case "spawn-worker": {
@@ -518,8 +553,16 @@ const orchestrateTool = {
518
553
  // live row for one worker. A different request, or the same id
519
554
  // describing different work, is refused with both ids named.
520
555
  const effectiveRequestId = resolveRequestId(workerId, requestId);
521
- const existing = readWorkers(projectCwd).workers[workerId];
522
- const decision = decideAdmission(existing, effectiveRequestId, { spec, files });
556
+ const registryAtSpawn = readWorkers(projectCwd);
557
+ const existing = registryAtSpawn.workers[workerId];
558
+ // Dependencies are part of what the work is, so a retry carries the same
559
+ // set; changing them under the same request id is different work.
560
+ const dependsOnIds = normalizeDependsOn(dependsOn);
561
+ const decision = decideAdmission(existing, effectiveRequestId, {
562
+ spec,
563
+ files,
564
+ dependsOn: dependsOnIds,
565
+ });
523
566
  if (decision.action === "reuse" && decision.entry) {
524
567
  return textResult(reuseReport(decision.entry, effectiveRequestId), {
525
568
  entry: decision.entry,
@@ -533,6 +576,12 @@ const orchestrateTool = {
533
576
  recordAdmissionRefusal(workerId, effectiveRequestId, projectCwd);
534
577
  throw new Error(`spawn-worker: ${decision.reason}.`);
535
578
  }
579
+ // A dependency that cannot be satisfied refuses the spawn before a
580
+ // branch or a lock exists, so a refused spawn leaves nothing to undo.
581
+ const dependencyRefusal = validateDependencies(workerId, dependsOnIds, registryAtSpawn);
582
+ if (dependencyRefusal) {
583
+ throw new Error(`spawn-worker: ${dependencyRefusal.message}.`);
584
+ }
536
585
  const conflicts = filesHeldByOthers(files, workerId, repoRoot);
537
586
  if (conflicts.length > 0) {
538
587
  return textResult(`CONFLICT: ${conflicts.length} file(s) already locked by other workers:\n${conflictLines(conflicts)}\n\nResolve conflicts before spawning this worker.`);
@@ -553,6 +602,8 @@ const orchestrateTool = {
553
602
  files,
554
603
  branch: branchName,
555
604
  outputFile,
605
+ priority,
606
+ dependsOn: dependsOnIds,
556
607
  requestId: effectiveRequestId,
557
608
  }, projectCwd);
558
609
  }
@@ -620,6 +671,8 @@ When the worker signals completion, use orchestrate action=verify-and-merge to r
620
671
  files,
621
672
  branch,
622
673
  outputFile,
674
+ priority,
675
+ dependsOn,
623
676
  pane,
624
677
  workerSession,
625
678
  requestId,
@@ -643,6 +696,8 @@ When the worker signals completion, use orchestrate action=verify-and-merge to r
643
696
  files,
644
697
  branch,
645
698
  outputFile,
699
+ priority,
700
+ dependsOn,
646
701
  pane,
647
702
  workerSession,
648
703
  requestId,
@@ -653,6 +708,12 @@ When the worker signals completion, use orchestrate action=verify-and-merge to r
653
708
  if (!workerId) {
654
709
  throw new Error("update-worker requires workerId");
655
710
  }
711
+ if (dependsOn !== undefined) {
712
+ throw new Error("update-worker: dependencies are fixed at admission — dependsOn is admitted by " +
713
+ "spawn-worker/register-worker only. A worker that gains a dependency after it " +
714
+ "started is a second unit of work wearing the first one's id; close the entry and " +
715
+ "admit it again.");
716
+ }
656
717
  const patch = {};
657
718
  if (pane !== undefined)
658
719
  patch.pane = pane;
@@ -668,6 +729,8 @@ When the worker signals completion, use orchestrate action=verify-and-merge to r
668
729
  patch.files = files;
669
730
  if (status !== undefined)
670
731
  patch.status = parseWorkerStatus(status);
732
+ if (priority !== undefined)
733
+ patch.priority = priority;
671
734
  if (phase !== undefined || lastStep !== undefined) {
672
735
  if (!phase || !lastStep) {
673
736
  throw new Error("update-worker: a checkpoint needs both phase and lastStep (the last completed step within that phase).");
@@ -716,7 +779,10 @@ When the worker signals completion, use orchestrate action=verify-and-merge to r
716
779
  counts.set(entry.status, (counts.get(entry.status) ?? 0) + 1);
717
780
  const closedCount = all.filter((entry) => entry.closedAt).length;
718
781
  const byStatus = WORKER_STATUSES.map((s) => `${s}=${counts.get(s) ?? 0}`).join(" ");
719
- const lines = shown.map(workerLine).join("\n");
782
+ // Actionable order over the rows being shown, with satisfaction read
783
+ // against every row: a closed dependency still counts as delivered.
784
+ const ordered = orderWorkerRows(shown, registry);
785
+ const lines = [...ordered.ready, ...ordered.blocked].map(workerListLine).join("\n");
720
786
  return textResult(`Workers (${repoRoot ?? process.cwd()}):\n${lines}\ncounts: total=${all.length} live=${all.length - closedCount} closed=${closedCount} | ${byStatus}${statsSuffix}`, details);
721
787
  }
722
788
  case "close-worker": {