bareloop 0.50.0 → 0.52.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.
@@ -0,0 +1,220 @@
1
+ // The carry note's store (M1, F258): the run-level record behind src/carrynote.js. It captures the worker's read-class tool
2
+ // calls AT THE SOURCE (the same seam the handoff note uses: the worker's tool objects, result SUMMARIES only, never file
3
+ // content), reads the run's edits from the WORKING TREE (git diff against the run's start commit, never the spine), renders
4
+ // the note and persists its state under `<workdir>/.smoke/carry/state.json` (an arbiter book: the worker's fs.deny covers
5
+ // `.smoke`, so it cannot read it; the gate audit, spine and bridges live there too). The switch is `carryNote` in
6
+ // config.json (absent = on; only `false` turns it off), read once per run by the engine's caller.
7
+ import { execFile } from 'node:child_process';
8
+ import { promisify } from 'node:util';
9
+ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
10
+ import { isAbsolute, join, relative, resolve } from 'node:path';
11
+ import { SMOKE_STORE } from './kinds.js';
12
+ import { isHandoffExcluded } from './handoff.js';
13
+ import { redactSecrets } from './validate.js';
14
+ import { render, HUNK_LINES } from './carrynote.js';
15
+ import { readConfig } from './config.js';
16
+
17
+ const exec = promisify(execFile);
18
+ export const CARRY_DIR = 'carry';
19
+ /** the next prompt of a retried step / fix try carries this when the previous ask's check failed */
20
+ export const RED_MARKER = /Previous attempt failed (this step's checks|the verification):/;
21
+
22
+ /**
23
+ * The ONE setting: `carryNote` in config.json, read exactly like `learningHints` (src/learnstore.js `learningHintsOn`).
24
+ * Absent = on; only an explicit `false` turns it off. An unreadable config reads as OFF (the safe side).
25
+ * @param {string} [home]
26
+ * @returns {boolean}
27
+ */
28
+ export function carryNoteOn(home) {
29
+ const c = readConfig({ home });
30
+ return c.problem === null && c.config.carryNote !== false;
31
+ }
32
+
33
+ const lineCount = (/** @type {string} */ s) => (s === '' ? 0 : s.split('\n').length - (s.endsWith('\n') ? 1 : 0));
34
+ const clip = (/** @type {unknown} */ s, n = 200) => redactSecrets(String(s ?? '')).slice(0, n);
35
+
36
+ /**
37
+ * The run's edits from the working tree against the start commit: tracked (git diff) plus untracked (no diff exists).
38
+ * Arbiter books / .git / .bareloop are excluded. Never throws; [] on any git failure.
39
+ * @param {string} workdir @param {string|null} base
40
+ * @returns {Promise<{path: string, lines: number, hunks: string[]}[]>}
41
+ */
42
+ export async function workingEdits(workdir, base) {
43
+ if (!base) return [];
44
+ const g = (/** @type {string[]} */ a) => exec('git', ['-c', 'core.quotepath=false', ...a], { cwd: workdir, maxBuffer: 1 << 26 });
45
+ const out = [];
46
+ try {
47
+ const { stdout: names } = await g(['diff', '--name-only', '-z', base]);
48
+ for (const p of names.split('\0').filter(Boolean)) {
49
+ if (isHandoffExcluded(p)) continue;
50
+ const { stdout } = await g(['diff', '-U1', '--no-color', '--no-ext-diff', base, '--', `:(literal)${p}`]);
51
+ if (/^(Binary files .* differ|GIT binary patch)$/m.test(stdout)) { out.push({ path: p, lines: 0, hunks: ['(binary file changed)'] }); continue; }
52
+ const body = stdout.split('\n').filter((l) => !/^(diff --git|index |--- |\+\+\+ |new file mode|deleted file mode)/.test(l));
53
+ out.push({ path: p, lines: body.filter((l) => /^[+-]/.test(l)).length, hunks: body.slice(0, HUNK_LINES * 2) });
54
+ }
55
+ const { stdout: un } = await g(['ls-files', '--others', '--exclude-standard', '-z']);
56
+ for (const p of un.split('\0').filter(Boolean)) {
57
+ if (isHandoffExcluded(p)) continue;
58
+ try {
59
+ const abs = resolve(workdir, p);
60
+ if (!statSync(abs).isFile() || statSync(abs).size > 262144) continue;
61
+ const text = readFileSync(abs, 'utf8');
62
+ if (text.includes('\0')) continue;
63
+ const ls = text.split('\n'); if (ls.at(-1) === '') ls.pop();
64
+ out.push({ path: p, lines: ls.length, hunks: ls.slice(0, HUNK_LINES * 2).map((l) => '+' + l) });
65
+ } catch { /* unreadable: not shown */ }
66
+ }
67
+ } catch { return out; }
68
+ return out;
69
+ }
70
+
71
+ /**
72
+ * Order edits oldest to newest by when they last changed: a file's recency is the latest settled ask whose `changed`
73
+ * list names it; a file in no `changed` list is oldest. Ties keep their incoming (alphabetical) order. PURE.
74
+ * @param {{path: string}[]} edits @param {{changed?: string[]}[]} settled asks settled so far, oldest first
75
+ */
76
+ export function orderEditsByRecency(edits, settled) {
77
+ const last = (/** @type {string} */ p) => { for (let i = settled.length - 1; i >= 0; i--) if ((settled[i].changed ?? []).includes(p)) return i; return -1; };
78
+ return edits.map((e, k) => ({ e, k, r: last(e.path) })).sort((a, b) => a.r - b.r || a.k - b.k).map((x) => x.e);
79
+ }
80
+
81
+ /**
82
+ * Run-level store. Asks are sequential, so "the current ask" is one counter.
83
+ * @param {{workdir: string, emit: (type: string, rec: any) => void, strikeLimit?: number, resume?: boolean}} o
84
+ */
85
+ export function createCarryStore({ workdir, emit, strikeLimit, resume = false }) {
86
+ workdir = resolve(workdir);
87
+ const dir = join(workdir, SMOKE_STORE, CARRY_DIR);
88
+ const stateFile = join(dir, 'state.json');
89
+ /** @type {string|null} */
90
+ let base = null;
91
+ let n = 0;
92
+ /** @type {any[]} */ let events = [];
93
+ /** @type {any[]} one per WORK ask (step/fix): {n, kind, step, iteration, bounded, red, changed, startSnap} */
94
+ let asks = [];
95
+ let loaded = false;
96
+ if (resume && existsSync(stateFile)) {
97
+ try { const s = JSON.parse(readFileSync(stateFile, 'utf8')); n = s.n ?? 0; events = s.events ?? []; asks = s.asks ?? []; base = s.base ?? null; loaded = true; } catch { /* a bad file starts empty */ }
98
+ }
99
+ const save = () => {
100
+ try { mkdirSync(dir, { recursive: true }); writeFileSync(stateFile, JSON.stringify({ n, base, events, asks })); } catch { /* a record, never a verdict: a failed save never breaks a run */ }
101
+ };
102
+ const rel = (/** @type {string} */ p) => (isAbsolute(p) ? relative(workdir, p) : p).split('\\').join('/') || '.';
103
+ const diskLines = (/** @type {string} */ r, /** @type {string|undefined} */ fallback) => { try { return lineCount(readFileSync(resolve(workdir, r), 'utf8')); } catch { return fallback === undefined ? null : lineCount(fallback); } };
104
+
105
+ /** Wrap the worker's read-class tools in place; records tool, args and a result SUMMARY - never file content. @param {{name: string, execute: Function}[]} tools */
106
+ const wrapTools = (tools) => {
107
+ for (const t of tools) {
108
+ const inner = t.execute;
109
+ if (t.name === 'shell_read') {
110
+ t.execute = async (/** @type {any} */ args) => {
111
+ const r = await inner(args);
112
+ try {
113
+ if (typeof r === 'string' && typeof args?.path === 'string') {
114
+ const p = rel(args.path);
115
+ const dirRead = /^dir /.test(r);
116
+ events.push({ ask: n, tool: 'read', path: p, ...(dirRead ? { dir: true } : { lines: diskLines(p, r) }) });
117
+ }
118
+ } catch { /* never break the worker */ }
119
+ return r;
120
+ };
121
+ } else if (t.name === 'ctx_get') {
122
+ t.execute = async (/** @type {any} */ args) => {
123
+ const r = await inner(args);
124
+ try {
125
+ if (typeof r === 'string' && typeof args?.path === 'string' && !/^(ctx_get failed|no chunk|stale)/.test(r)) {
126
+ const p = rel(args.path);
127
+ const a = Number(args.startLine); const b = Number(args.endLine);
128
+ events.push({ ask: n, tool: 'get', path: p, lines: diskLines(p, undefined), range: Number.isFinite(a) && Number.isFinite(b) ? [a, b] : null });
129
+ }
130
+ } catch { /* never break the worker */ }
131
+ return r;
132
+ };
133
+ } else if (t.name === 'shell_grep') {
134
+ t.execute = async (/** @type {any} */ args) => {
135
+ const r = await inner(args);
136
+ try {
137
+ const hits = Array.isArray(r?.hits) ? r.hits : null;
138
+ events.push({
139
+ ask: n, tool: 'grep', pattern: clip(args?.pattern), scope: rel(String(args?.path ?? '.')),
140
+ ...(hits ? { matches: hits.length, firstMatches: hits.slice(0, 3).map((/** @type {any} */ h) => `${rel(String(h.file))}:${h.line}`) } : {}),
141
+ });
142
+ } catch { /* never break the worker */ }
143
+ return r;
144
+ };
145
+ } else if (t.name === 'ctx_recall') {
146
+ t.execute = async (/** @type {any} */ args) => {
147
+ const r = await inner(args);
148
+ try {
149
+ if (typeof r === 'string') {
150
+ /** @type {string[]} */ const hitPaths = []; /** @type {string[]} */ const hitRanges = [];
151
+ for (const line of r.split('\n')) {
152
+ const m = /^([^\t]+)\t[^\t]*\t[^\t]*\tlines (\d+-\d+)$/.exec(line);
153
+ if (m) { hitPaths.push(m[1]); hitRanges.push(`${m[1]} ${m[2]}`); }
154
+ }
155
+ events.push({ ask: n, tool: 'recall', query: clip(args?.query), hitPaths: [...new Set(hitPaths)], hitRanges });
156
+ }
157
+ } catch { /* never break the worker */ }
158
+ return r;
159
+ };
160
+ }
161
+ }
162
+ };
163
+
164
+ const snapOf = (/** @type {{path: string, lines: number}[]} */ edits) => Object.fromEntries(edits.map((e) => [e.path, e.lines]));
165
+ const tryLabel = (/** @type {any} */ a) => (a.kind === 'fix' ? `fix loop try ${a.iteration}` : `step "${a.step}" try ${a.iteration}`);
166
+ const endedOf = (/** @type {any} */ a) => a.boundedText || (a.red ? 'Its check failed.' : 'Its check passed.');
167
+
168
+ /**
169
+ * Called at the start of EVERY ask (scout and drafter included, so their finds feed the store).
170
+ * Returns the note text for step/fix asks, '' otherwise.
171
+ * @param {{phase: string, iteration: number|string|undefined, prompt: string}} o
172
+ */
173
+ const beginAsk = async ({ phase, iteration, prompt }) => {
174
+ n++;
175
+ const work = phase === 'fix' || phase.startsWith('step:');
176
+ if (!work) { save(); return ''; }
177
+ const edits = await workingEdits(workdir, base);
178
+ const prev = asks[asks.length - 1];
179
+ if (prev && prev.red === undefined) {
180
+ // settle the previous work ask: red = this prompt says the last attempt failed; changed = files whose changed-line count moved
181
+ prev.red = RED_MARKER.test(prompt);
182
+ const now = snapOf(edits);
183
+ prev.changed = [...new Set([...Object.keys(now), ...Object.keys(prev.startSnap)])].filter((p) => now[p] !== prev.startSnap[p]).sort();
184
+ for (const e of events) if (e.ask === prev.n) e.noFix = prev.changed.length === 0 && prev.red;
185
+ }
186
+ const kind = phase === 'fix' ? 'fix' : 'step';
187
+ const step = kind === 'step' ? phase.slice('step:'.length) : null;
188
+ const settled = asks.filter((a) => a.red !== undefined);
189
+ const lt = settled[settled.length - 1];
190
+ const notes = {
191
+ lastTry: lt ? { step: lt.step, kind: lt.kind, n: lt.iteration, of: lt.kind === 'step' ? strikeLimit : undefined, ended: endedOf(lt), changed: lt.changed } : null,
192
+ lastCheck: null, // the failed check's text is already in the prompt today; one copy
193
+ events: events.map((e) => ({ ...e })),
194
+ edits: orderEditsByRecency(edits, settled),
195
+ earlier: settled.slice(0, -1).map((a) => `${tryLabel(a)}: ${endedOf(a)} ${a.changed.length ? `Changed ${a.changed.join(', ')}.` : 'Changed nothing.'}`),
196
+ lastAsk: lt ? lt.n : undefined,
197
+ };
198
+ asks.push({ n, kind, step, iteration, startSnap: snapOf(edits) });
199
+ const hasAny = notes.events.length || edits.length || notes.earlier.length || notes.lastTry;
200
+ if (!hasAny) { save(); return ''; }
201
+ const r = render(/** @type {any} */ (notes));
202
+ emit('carry-note', { phase, iteration, chars: r.text.length, capped: r.capped, sections: r.sections }); // counts only
203
+ save();
204
+ return r.text;
205
+ };
206
+
207
+ /** Called when the ask returns (finally). @param {{bounded?: {iteration: any, cause: string}|undefined, iteration: any, rounds: number}} o */
208
+ const endAsk = ({ bounded, iteration, rounds }) => {
209
+ const a = asks[asks.length - 1];
210
+ if (!a || a.n !== n) return;
211
+ if (bounded && bounded.iteration === iteration) {
212
+ a.boundedText = bounded.cause === 'rounds' ? `Ran out of calls (${rounds} of ${rounds}).`
213
+ : bounded.cause === 'wall' ? 'Stopped by the wall clock.'
214
+ : bounded.cause === 'denied' ? 'Stopped after repeated denied calls.' : 'Output cut at the token limit.';
215
+ }
216
+ save();
217
+ };
218
+
219
+ return { wrapTools, beginAsk, endAsk, setBase: (/** @type {string|null|undefined} */ b) => { if (!base && b) base = b; }, loaded: () => loaded, _state: () => ({ n, events, asks, base }) };
220
+ }
package/src/config.js CHANGED
@@ -10,6 +10,7 @@
10
10
  // Shape (unknown fields are kept, never dropped):
11
11
  // { "monthlyLimitUsd": <number > 0>, // absent = no limit, no check
12
12
  // "learningHints": true|false, // absent = true (ON by default; only false turns it off): the planner is handed cross-run learnings (src/learn.js); the tally is kept either way
13
+ // "carryNote": true|false, // absent = true (ON by default; only false turns it off): a step/fix worker is handed a code-written, facts-only note of what earlier workers of the same run looked at, searched and changed (src/carrynote.js); off = the worker prompt is exactly as before
13
14
  // "keys": { "<ENV NAME>": { "shape": "<shape id>", "baseUrl": "http(s)://…", "legacyMaxTokens": true|false } },
14
15
  // "models": { "<ENV NAME>": [ { "model": "<id>", "use": true|false, "inPerM": n, "outPerM": n } ] } }
15
16
  // An older file's `keys.<ENV>.{name,priceInPerM,priceOutPerM}` is tolerated and read as ONE model
@@ -130,6 +131,7 @@ export function modelsProblem(list) {
130
131
  function docProblem(doc) {
131
132
  // monthlyLimitUsd is NOT judged here: `monthlyLimitOf` (src/monthly.js) owns its read-time sentence
132
133
  if (doc.learningHints !== undefined && typeof doc.learningHints !== 'boolean') return 'learningHints must be true or false';
134
+ if (doc.carryNote !== undefined && typeof doc.carryNote !== 'boolean') return 'carryNote must be true or false';
133
135
  if (doc.keys !== undefined) {
134
136
  if (doc.keys === null || typeof doc.keys !== 'object' || Array.isArray(doc.keys)) return 'keys must be an object of key variable names';
135
137
  for (const [env, row] of Object.entries(doc.keys)) {
@@ -158,7 +160,7 @@ function docProblem(doc) {
158
160
  * `keys` merges per key variable name, then per field; `models.<ENV>` is REPLACED WHOLE (`null`
159
161
  * clears it). Validated before anything is written; nothing is written on a refusal.
160
162
  *
161
- * Patch fields understood: `monthlyLimitUsd` (finite > 0), `learningHints` (true | false), `keys.<ENV>.{shape,baseUrl,legacyMaxTokens}`,
163
+ * Patch fields understood: `monthlyLimitUsd` (finite > 0), `learningHints` (true | false), `carryNote` (true | false), `keys.<ENV>.{shape,baseUrl,legacyMaxTokens}`,
162
164
  * `models.<ENV>` (a list judged by {@link modelsProblem}). The first write of a row's `models` list
163
165
  * removes that row's older `name` / `priceInPerM` / `priceOutPerM` in the SAME write (never two
164
166
  * sources); a retired top-level `anthropicBalanceNote` is dropped on any write. Any other field is
@@ -179,6 +181,7 @@ export function updateConfig(patch, opts = {}) {
179
181
  throw new ConfigError('monthlyLimitUsd must be a number above 0 (remove the limit to have none)');
180
182
  }
181
183
  if (k === 'learningHints' && typeof v !== 'boolean') throw new ConfigError('learningHints must be true or false');
184
+ if (k === 'carryNote' && typeof v !== 'boolean') throw new ConfigError('carryNote must be true or false');
182
185
  next[k] = v;
183
186
  }
184
187
  delete next.anthropicBalanceNote;
package/src/handoff.js ADDED
@@ -0,0 +1,100 @@
1
+ // The handoff note (F253): a map of the files earlier workers in THIS run read, appended to the next step/fix
2
+ // worker's first prompt. Code-written only, never a model; names files, never carries their content.
3
+ // The switch is the signed spec's `handoffNote` (absent = on, only `false` turns it off; see src/job.js).
4
+ import { readFileSync, statSync } from 'node:fs';
5
+ import { isAbsolute, relative, resolve } from 'node:path';
6
+ import { isArbiterBook } from './kinds.js';
7
+
8
+ /** The one cap on a note, in characters. */
9
+ export const HANDOFF_CAP = 8000;
10
+ export const HANDOFF_HEADING = '== Files earlier workers in this run read (a map only; contents are not included; line ranges as ctx_recall prints them) ==';
11
+ /** Per-entry symbol-map cap, so one huge file cannot eat the whole note. */
12
+ const ENTRY_MAP_CAP = 500;
13
+
14
+ /**
15
+ * Is this repo-relative path off limits to a note: outside the job root, an arbiter book (the one list,
16
+ * `isArbiterBook`: .smoke — spine, attempt-diff, bridges — .litectx, the gate audit), or inside `.git` / `.bareloop`.
17
+ * @param {string} rel
18
+ */
19
+ export function isHandoffExcluded(rel) {
20
+ if (rel === '' || rel === '..' || rel.startsWith('../') || isAbsolute(rel)) return true;
21
+ if (isArbiterBook(rel) !== null) return true;
22
+ return rel.split('/').some((seg) => seg === '.git' || seg === '.bareloop');
23
+ }
24
+
25
+ /**
26
+ * Wrap the worker's read-class tools (the real names come from the caller: shell_read, ctx_get) so a call that
27
+ * reached `execute` (the gate already allowed it) and returned a file's text is reported to `onRead`.
28
+ * Wraps in place: tool objects are fresh per worker.
29
+ * @param {{name: string, execute: Function}[]} tools
30
+ * @param {string[]} names
31
+ * @param {(absPath: string) => void} onRead
32
+ * @param {string} workdir
33
+ */
34
+ export function trackReads(tools, names, onRead, workdir) {
35
+ for (const t of tools) {
36
+ if (!names.includes(t.name)) continue;
37
+ const inner = t.execute;
38
+ t.execute = async (/** @type {any} */ args) => {
39
+ const r = await inner(args);
40
+ if (typeof r === 'string' && typeof args?.path === 'string' && !/^ctx_get failed/.test(r)) {
41
+ const abs = isAbsolute(args.path) ? args.path : resolve(workdir, args.path);
42
+ try { if (statSync(abs).isFile()) onRead(abs); } catch { /* not a file: nothing was read */ }
43
+ }
44
+ return r;
45
+ };
46
+ }
47
+ }
48
+
49
+ /**
50
+ * Run-level store of the paths earlier workers read. Newest read last; a re-read moves a path to newest.
51
+ * In memory only: a resumed leg starts empty (the first ask of a resumed leg gets no note, later asks do).
52
+ * @param {{workdir: string}} o
53
+ */
54
+ export function createHandoffStore({ workdir }) {
55
+ /** @type {Set<string>} insertion order = oldest first */
56
+ const paths = new Set();
57
+ /** @param {Iterable<string>} absPaths */
58
+ const absorb = (absPaths) => {
59
+ for (const a of absPaths) {
60
+ const rel = relative(workdir, a).split('\\').join('/');
61
+ if (isHandoffExcluded(rel)) continue;
62
+ paths.delete(rel);
63
+ paths.add(rel);
64
+ }
65
+ };
66
+ /**
67
+ * @param {{getNode?: (rel: string) => any}} [o] `getNode`: the LiteCtx index's node for a path (its `chunks`)
68
+ * @returns {{text: string, paths: number}} text '' when nothing was read; else heading + body, length <= HANDOFF_CAP
69
+ */
70
+ const render = ({ getNode = () => null } = {}) => {
71
+ if (paths.size === 0) return { text: '', paths: 0 };
72
+ const lineCount = (/** @type {string} */ rel) => { try { return readFileSync(resolve(workdir, rel), 'utf8').split('\n').length; } catch { return null; } };
73
+ const entries = [...paths].map((rel) => {
74
+ const n = lineCount(rel);
75
+ let node = null;
76
+ try { node = getNode(rel); } catch { node = null; }
77
+ // Fresh index only: a node whose last chunk ends past the file's current end is stale — fall back to the count.
78
+ const named = (node?.chunks ?? []).filter((/** @type {any} */ c) => c.symbol);
79
+ const fresh = n !== null && named.every((/** @type {any} */ c) => c.endLine <= n);
80
+ let map = '';
81
+ let more = 0;
82
+ for (let i = 0; fresh && i < named.length; i++) {
83
+ const c = named[i];
84
+ const piece = `${c.symbol} ${c.startLine}-${c.endLine}`;
85
+ if ((map ? map.length + 2 : 0) + piece.length > ENTRY_MAP_CAP) { more = named.length - i; break; }
86
+ map += (map ? ', ' : '') + piece;
87
+ }
88
+ return `- ${rel}${n === null ? '' : ` (${n} lines)`}${map ? `: ${map}` : ''}${more ? `, +${more} more` : ''}`;
89
+ });
90
+ const wrap = (/** @type {string[]} */ es, /** @type {number} */ dropped) => `${HANDOFF_HEADING}\n${dropped ? `[trimmed: ${dropped} older path(s)]\n` : ''}${es.join('\n')}`;
91
+ let dropped = 0;
92
+ let out = wrap(entries, 0);
93
+ while (out.length > HANDOFF_CAP && dropped < entries.length) {
94
+ dropped++;
95
+ out = wrap(entries.slice(dropped), dropped);
96
+ }
97
+ return { text: out, paths: entries.length - dropped };
98
+ };
99
+ return { absorb, render, size: () => paths.size };
100
+ }
package/src/job.js CHANGED
@@ -170,7 +170,7 @@ export const CONDITION_KEYS = Object.freeze(['providerPath', 'closeVerbosity', '
170
170
  // `steps` stays in the field list ONLY so a retired spec reds by name
171
171
  // (`shape-retired`) instead of falling through to a generic unknown-field —
172
172
  // the operator gets told what happened, not just that something is wrong.
173
- const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'baseUrl', 'conditions', 'cadence', 'trigger', 'budgetUsd', 'maxWallMs', 'closeTimeoutMs', 'model', 'thinking', 'judge', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', 'closeDecl', 'checks', 'tools', 'jobLines', 'inputs'];
173
+ const JOB_FIELDS = ['schema', 'job', 'description', 'provider', 'baseUrl', 'conditions', 'cadence', 'trigger', 'budgetUsd', 'maxWallMs', 'closeTimeoutMs', 'model', 'thinking', 'handoffNote', 'judge', 'writeScope', 'steps', 'escalation', 'goal', 'verdictType', 'close', 'closeDecl', 'checks', 'tools', 'jobLines', 'inputs'];
174
174
  /** the exact fields of a signed `judge` override — nested objects red unknown
175
175
  * keys too, because no smuggling level exists in a signed spec */
176
176
  const JUDGE_FIELDS = ['provider', 'model'];
@@ -349,6 +349,11 @@ export function validateJob(input, { shellCapUsd = 2 } = {}) {
349
349
  if (spec.thinking !== undefined && typeof spec.thinking !== 'boolean') {
350
350
  red('invalid-value', 'thinking', 'true or false — the job\'s "Thinking on" tick (absent = off)');
351
351
  }
352
+ // THE HANDOFF NOTE (src/handoff.js): a declared job condition, signed like `thinking`. A boolean; ABSENT = on (an old spec keeps its
353
+ // bytes, so its hash), only an explicit `false` turns the note off. The switch is hashed; the note's text never is.
354
+ if (spec.handoffNote !== undefined && typeof spec.handoffNote !== 'boolean') {
355
+ red('invalid-value', 'handoffNote', 'true or false (absent = on): whether the next step/fix worker is handed a map of the files earlier workers read');
356
+ }
352
357
 
353
358
  // JUDGE — PRD item 32.1 (hamr, 2026-09-10: the judge "defaults to whatever
354
359
  // llm is used and can be overriden"). OPTIONAL, and the OVERRIDE half: absent,