@awebai/oats 0.69.22 → 0.69.23

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 (54) hide show
  1. package/bin/oats.mjs +131 -23
  2. package/docs/capabilities.md +12 -2
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +206 -228
  5. package/docs/design/2026-11-19-sandboxes.md +878 -0
  6. package/docs/design/README.md +3 -0
  7. package/docs/desktop-cli-api.md +416 -72
  8. package/docs/desktop.md +60 -17
  9. package/docs/implementation.md +1 -1
  10. package/docs/integrations.md +3 -3
  11. package/docs/knowledge-capability-authoring.md +10 -7
  12. package/docs/knowledge-reference/acceptance.md +21 -19
  13. package/docs/knowledge-reference/adoption.md +18 -4
  14. package/docs/knowledge-reference/model.md +11 -9
  15. package/docs/knowledge-reference/package-craft.md +2 -2
  16. package/docs/knowledge-reference/proposal.md +117 -0
  17. package/docs/knowledge-reference/provider-mapping.md +10 -10
  18. package/docs/knowledge-reference/reader-capture.md +26 -22
  19. package/docs/knowledge-theory.md +1 -1
  20. package/docs/knowledge.md +5 -5
  21. package/docs/official-catalog.md +4 -4
  22. package/docs/packages.md +13 -13
  23. package/docs/release-notes/v0.69.23.md +231 -0
  24. package/docs/servers.md +10 -6
  25. package/docs/souls-and-instances.md +51 -22
  26. package/docs/tui.md +4 -3
  27. package/docs/upgrading.md +12 -5
  28. package/docs/workspaces.md +2 -2
  29. package/lib/argv.mjs +6 -2
  30. package/lib/capability-contract.mjs +2 -2
  31. package/lib/command-flags.mjs +39 -2
  32. package/lib/core.mjs +25 -14
  33. package/lib/instance-board.mjs +337 -0
  34. package/lib/instance-events.mjs +48 -10
  35. package/lib/instance-lifecycle.mjs +19 -15
  36. package/lib/instance-listing.mjs +18 -10
  37. package/lib/instance-related-work.mjs +143 -0
  38. package/lib/kernel-features.mjs +4 -1
  39. package/lib/servers.mjs +123 -13
  40. package/package-catalog.json +3 -3
  41. package/package.json +1 -1
  42. package/packages/client/deployment-data.mjs +4 -2
  43. package/packages/client/deployment-panel.mjs +2 -1
  44. package/packages/client/instance-tree.mjs +34 -4
  45. package/packages/client/keymap.mjs +5 -0
  46. package/packages/client/mail-contract.mjs +130 -0
  47. package/packages/client/panel-views.mjs +7 -7
  48. package/packages/client/related-work.mjs +84 -0
  49. package/packages/client/remote-roster.mjs +4 -3
  50. package/packages/client/workspace-cli.mjs +13 -2
  51. package/skills/oats-getting-started/SKILL.md +11 -8
  52. package/docs/knowledge-reference/harvester.md +0 -109
  53. package/lib/instance-same-work.mjs +0 -67
  54. package/packages/client/same-work.mjs +0 -49
@@ -0,0 +1,337 @@
1
+ /** The agent's board (feature instance-board, `boardApi: 1`): the facts an agent keeps in view for its
2
+ * person (`oats instance board set|unset`) and the questions it asks them (`oats instance board ask`, closed
3
+ * with `ask --clear`). Agent-reported, display only: the kernel routes no answer and acts on nothing here.
4
+ * The contract is docs/desktop-cli-api.md "The agent's board".
5
+ *
6
+ * ONE HOME FILE, `<home>/.oats-board.json`, kernel-owned (KERNEL_HOME_NAME_PREFIXES, the retire receipts,
7
+ * the manifest schema), written atomically at mode 0600 under a short lock (`.oats-board.lock`), so that
8
+ * parallel writes of one agent never lose one. The file:
9
+ * { boardApi: 1, asked: <n>, facts: { <key>: { label, value, unit, link, at, seq, history: [{ value, at }] } },
10
+ * questions: [{ id, question, options, context, since, session }] }
11
+ * `asked` numbers the default ids (`q<n>`), never reused while the home lives; `seq` keeps the facts in the
12
+ * order first set (a key such as "1" would otherwise lead a JSON object). A reader takes a regular file
13
+ * only, without following a link, up to FILE_MAX bytes; a file that is not a valid board in every part
14
+ * reads as an empty board, never an error; no file reads as null.
15
+ *
16
+ * FACTS persist across sessions until unset or the home is retired. QUESTIONS are per session: each records
17
+ * the session it was asked in (the id of the incarnation's latest kernel session boundary, `launched`,
18
+ * `restarted` or `stopped`: lib/instance-events.mjs liveSession), and is live only while that is still the
19
+ * current session, read with proof: where the log's bounded read cannot show the current session (a tail
20
+ * with no boundary), no question is live. One that is not live is not shown, and a write drops it.
21
+ *
22
+ * THE CLAIM. While a question is live, the home holds the waiting claim of producer `oats.board`, reason
23
+ * `attention` (it holds no scheduled wake), message the oldest live question, bound to the session the write
24
+ * read (setWaiting `session`): a boundary written meanwhile ends it with the question. Every write sets the
25
+ * claim to what the board's questions say after it, so the write that fails to record it is repaired by the
26
+ * next, and a retry of the same command is no change to the board.
27
+ *
28
+ * THE ROW BOUND. The row value (`boardRow`: facts without history, questions without context) is at most
29
+ * ROW_MAX bytes as UTF-8 JSON: a write that would pass it is refused (E_BOARD_FULL), and a file whose row
30
+ * passes it is not a valid board. Every client can rely on the bound per row. Dependency-free. */
31
+ import { lstatSync, rmSync } from "node:fs";
32
+ import { join } from "node:path";
33
+ import { readFileHead } from "./bounded-read.mjs";
34
+ import { withDirLock } from "./dir-lock.mjs";
35
+ import { REFUSED_TEXT } from "./refused-text.mjs";
36
+ import { liveSession, setWaiting } from "./instance-events.mjs";
37
+ import { BOARD_API } from "./kernel-features.mjs";
38
+ import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
39
+
40
+ /** The record's version, the command answer's and the probe's (defined beside the features, which the
41
+ * probe reads without loading this module). */
42
+ export { BOARD_API };
43
+ /** The home file and its lock, kernel-owned. */
44
+ export const BOARD_FILE = ".oats-board.json";
45
+ export const BOARD_LOCK = ".oats-board.lock";
46
+ /** The producer of the board's waiting claim. */
47
+ export const BOARD_PRODUCER = "oats.board";
48
+ /** The bounds (code points, except ROW_MAX and FILE_MAX in bytes, LINK_MAX in ASCII characters). */
49
+ export const BOARD_LIMITS = Object.freeze({ facts: 12, questions: 9, options: { min: 2, max: 4 }, history: 20, key: 16, label: 40, value: 80, unit: 16, option: 60, question: 200, context: 2000, link: 512 });
50
+ export const ROW_MAX = 8192;
51
+ /** A file larger than this is not a board: 12 facts with 20 values each, and 9 contexts, fit well inside it. */
52
+ const FILE_MAX = 256 * 1024;
53
+ /** How long a write waits for another write of the same board. */
54
+ const LOCK_WAIT_MS = 5000;
55
+ /** A fact's key and a question's id. */
56
+ export const BOARD_KEY_RE = /^[a-z0-9][a-z0-9-]{0,15}$/;
57
+
58
+ const boardError = (code, message, details) => Object.assign(new Error(message), { code, ...(details ? { details } : {}) });
59
+ const points = (s) => [...s].length;
60
+ const validTime = (at) => typeof at === "string" && Number.isFinite(Date.parse(at));
61
+ /** One line of 1 to `max` code points, with none of the kernel's refused characters (REFUSED_TEXT). */
62
+ const lineOk = (s, max) => typeof s === "string" && s.length > 0 && points(s) <= max && !REFUSED_TEXT.test(s);
63
+ /** A context: 1 to BOARD_LIMITS.context code points; newlines (LF) allowed, every other refused character not. */
64
+ const contextOk = (s) => typeof s === "string" && s.length > 0 && points(s) <= BOARD_LIMITS.context && s.split("\n").every((l) => !REFUSED_TEXT.test(l));
65
+ /** An absolute `https:` URL of at most BOARD_LIMITS.link printable ASCII characters, with a host. */
66
+ export function linkOk(s) {
67
+ if (typeof s !== "string" || s.length > BOARD_LIMITS.link || !/^https:\/\/[\x21-\x7e]+$/.test(s)) return false;
68
+ try { const u = new URL(s); return u.protocol === "https:" && u.hostname.length > 0; } catch { return false; }
69
+ }
70
+ const TEXT_RULE = "one line with no control character, line separator, bidi control (U+202A-202E, U+2066-2069), U+200B, U+2060, U+FEFF or tag character";
71
+
72
+ // ---------- reading ----------
73
+
74
+ /** A stored fact, or null when any part of it is not one. */
75
+ function readFact(key, f) {
76
+ if (typeof key !== "string" || !BOARD_KEY_RE.test(key) || !f || typeof f !== "object" || Array.isArray(f)) return null;
77
+ const { label, value, unit = null, link = null, at, seq, history } = f;
78
+ if (!lineOk(label, BOARD_LIMITS.label) || !lineOk(value, BOARD_LIMITS.value) || !validTime(at) || !Number.isSafeInteger(seq) || seq < 0) return null;
79
+ if (unit !== null && !lineOk(unit, BOARD_LIMITS.unit)) return null;
80
+ if (link !== null && !linkOk(link)) return null;
81
+ if (!Array.isArray(history) || history.length < 1 || history.length > BOARD_LIMITS.history) return null;
82
+ if (!history.every((h) => h && typeof h === "object" && lineOk(h.value, BOARD_LIMITS.value) && validTime(h.at))) return null;
83
+ return { key, label, value, unit, link, at, seq, history: history.map((h) => ({ value: h.value, at: h.at })) };
84
+ }
85
+ /** A stored question, or null when any part of it is not one. */
86
+ function readQuestion(q) {
87
+ if (!q || typeof q !== "object" || Array.isArray(q)) return null;
88
+ const { id, question, options, context = null, since, session = null } = q;
89
+ if (typeof id !== "string" || !BOARD_KEY_RE.test(id) || !lineOk(question, BOARD_LIMITS.question) || !validTime(since)) return null;
90
+ if (session !== null && !(typeof session === "string" && session.length <= 128)) return null;
91
+ if (!Array.isArray(options) || options.length < BOARD_LIMITS.options.min || options.length > BOARD_LIMITS.options.max || !options.every((o) => lineOk(o, BOARD_LIMITS.option))) return null;
92
+ if (context !== null && !contextOk(context)) return null;
93
+ return { id, question, options: [...options], context, since, session };
94
+ }
95
+ const EMPTY = () => ({ asked: 0, facts: [], questions: [] });
96
+ /** The board document of `home`: `{ asked, facts: [...] in first-set order, questions: [...] in the order
97
+ * asked }`, every question kept (live or not); null for no file (nothing at the name, or a home that can't
98
+ * be read, so nothing shows one); EMPTY for anything that is not a valid
99
+ * board in every part (not a regular file, a link, over FILE_MAX, not JSON, another boardApi, a fact or a
100
+ * question out of its rules, too many, a repeated id, a row over ROW_MAX). Never throws. */
101
+ export function readBoardDocument(home) {
102
+ // No entry that can be seen at the name is no board: absent, or a home whose directory can't be read
103
+ // (mode 000), where nothing shows a file is there.
104
+ try { lstatSync(join(home, BOARD_FILE)); } catch { return null; }
105
+ let bytes, size;
106
+ try { ({ bytes, size } = readFileHead(join(home, BOARD_FILE), FILE_MAX + 1)); }
107
+ catch { return EMPTY(); }
108
+ if (size > FILE_MAX) return EMPTY();
109
+ let doc;
110
+ try { doc = JSON.parse(bytes.toString("utf8")); } catch { return EMPTY(); }
111
+ if (!doc || typeof doc !== "object" || Array.isArray(doc) || doc.boardApi !== BOARD_API) return EMPTY();
112
+ const { asked = 0, facts = {}, questions = [] } = doc;
113
+ if (!Number.isSafeInteger(asked) || asked < 0 || !facts || typeof facts !== "object" || Array.isArray(facts) || !Array.isArray(questions)) return EMPTY();
114
+ const keys = Object.keys(facts);
115
+ if (keys.length > BOARD_LIMITS.facts || questions.length > BOARD_LIMITS.questions) return EMPTY();
116
+ const read = keys.map((k) => readFact(k, facts[k]));
117
+ const asks = questions.map(readQuestion);
118
+ if (read.includes(null) || asks.includes(null) || new Set(asks.map((q) => q.id)).size !== asks.length) return EMPTY();
119
+ const out = { asked, facts: read.sort((x, y) => x.seq - y.seq), questions: asks };
120
+ return rowBytes(out) > ROW_MAX ? EMPTY() : out;
121
+ }
122
+
123
+
124
+ /** The row value of a document (its questions already the live ones): what `oats status --json` and
125
+ * `oats server roster --json` rows carry as `board`. */
126
+ export function boardRow(doc) {
127
+ return {
128
+ facts: doc.facts.map((f) => ({ key: f.key, label: f.label, value: f.value, unit: f.unit, link: f.link, at: f.at })),
129
+ questions: doc.questions.map((q) => ({ id: q.id, question: q.question, options: [...q.options], hasContext: q.context !== null, since: q.since })),
130
+ };
131
+ }
132
+ /** The inspect value (`oats inspect --home <h> --board`): the row's, with each fact's history and each
133
+ * question's context. */
134
+ export function boardDetail(doc) {
135
+ const row = boardRow(doc);
136
+ return {
137
+ facts: row.facts.map((f, i) => ({ ...f, history: doc.facts[i].history.map((h) => ({ ...h })) })),
138
+ questions: row.questions.map((q, i) => ({ ...q, context: doc.questions[i].context })),
139
+ };
140
+ }
141
+ const rowBytes = (doc) => Buffer.byteLength(JSON.stringify(boardRow(doc)), "utf8");
142
+
143
+ /** The live board of a stored document (`stored`: readBoardDocument's): its questions only the ones asked
144
+ * in the current session, and none when that session can't be proved (an unknown incarnation, a log tail
145
+ * with no boundary). `s`: the home's liveSession. null stays null. */
146
+ function liveOf(stored, s) {
147
+ if (stored === null || !stored.questions.length) return stored;
148
+ if (s.incarnation === null || !s.sessionKnown) return { ...stored, questions: [] };
149
+ return { ...stored, questions: stored.questions.filter((q) => q.session === s.session) };
150
+ }
151
+ /** `session`: the home's liveSession when the caller has read it (the status rows), else it is read here,
152
+ * only when the file holds a question. */
153
+ const liveDocument = (home, { session, meta } = {}) => {
154
+ const stored = readBoardDocument(home);
155
+ if (stored === null || !stored.questions.length) return stored;
156
+ return liveOf(stored, session ?? liveSession(home, meta !== undefined ? { meta } : {}));
157
+ };
158
+
159
+ /** `board` on a status row: null for a home with no board file, else the row value of its live board.
160
+ * Never throws: a board that cannot be read is an empty one. */
161
+ export function readBoardRow(home, options) {
162
+ try { const doc = liveDocument(home, options); return doc === null ? null : boardRow(doc); }
163
+ catch { return { facts: [], questions: [] }; }
164
+ }
165
+ /** `instance.board` on `oats inspect --home <h> --board`: as readBoardRow, with history and context. */
166
+ export function readBoardDetail(home) {
167
+ try { const doc = liveDocument(home); return doc === null ? null : boardDetail(doc); }
168
+ catch { return { facts: [], questions: [] }; }
169
+ }
170
+
171
+ /** The READ rule for a `board` another kernel reports (a remote roster row): the row value exactly as this
172
+ * kernel would write it, every fact and question within its rules and the whole within ROW_MAX, or an
173
+ * empty board. null stays null. */
174
+ export function readRemoteBoard(board) {
175
+ if (board === null) return null;
176
+ const empty = { facts: [], questions: [] };
177
+ if (!board || typeof board !== "object" || Array.isArray(board) || !Array.isArray(board.facts) || !Array.isArray(board.questions)) return empty;
178
+ if (board.facts.length > BOARD_LIMITS.facts || board.questions.length > BOARD_LIMITS.questions) return empty;
179
+ const facts = board.facts.map((f, i) => (f && typeof f === "object" ? readFact(f.key, { ...f, seq: i, history: [{ value: f.value, at: f.at }] }) : null));
180
+ const questions = board.questions.map((q) => (q && typeof q === "object" && typeof q.hasContext === "boolean" ? readQuestion({ ...q, context: q.hasContext ? "x" : null, session: null }) : null));
181
+ if (facts.includes(null) || questions.includes(null) || new Set(facts.map((f) => f.key)).size !== facts.length || new Set(questions.map((q) => q.id)).size !== questions.length) return empty;
182
+ const doc = { asked: 0, facts, questions };
183
+ return rowBytes(doc) > ROW_MAX ? empty : boardRow(doc);
184
+ }
185
+
186
+ // ---------- writing ----------
187
+
188
+ /** The checks of one fact's fields, as the CLI gives them → the fields, or E_BAD_ARGS naming the first. */
189
+ function checkFact({ key, label, value, unit, link }) {
190
+ if (typeof key !== "string" || !BOARD_KEY_RE.test(key)) throw boardError("E_BAD_ARGS", `the key must match ${BOARD_KEY_RE.source} (a lowercase letter or digit, then up to 15 lowercase letters, digits or hyphens)`);
191
+ if (label === undefined) throw boardError("E_BAD_ARGS", "--label is required");
192
+ if (value === undefined) throw boardError("E_BAD_ARGS", "--value is required");
193
+ for (const [name, v, max] of [["label", label, BOARD_LIMITS.label], ["value", value, BOARD_LIMITS.value], ["unit", unit, BOARD_LIMITS.unit]]) {
194
+ if (v !== undefined && !lineOk(v, max)) throw boardError("E_BAD_ARGS", `--${name} must be ${TEXT_RULE}, of 1 to ${max} characters`);
195
+ }
196
+ if (link !== undefined && !linkOk(link)) throw boardError("E_BAD_ARGS", `--link must be an absolute https: URL of at most ${BOARD_LIMITS.link} printable ASCII characters`);
197
+ return { key, label, value, unit: unit ?? null, link: link ?? null };
198
+ }
199
+ /** The checks of one question → its fields, or E_BAD_ARGS naming the first. */
200
+ function checkQuestion({ question, options, id, context }) {
201
+ if (question === undefined) throw boardError("E_BAD_ARGS", "the question is required: oats instance board ask <question> --option <text> --option <text>");
202
+ if (!lineOk(question, BOARD_LIMITS.question)) throw boardError("E_BAD_ARGS", `the question must be ${TEXT_RULE}, of 1 to ${BOARD_LIMITS.question} characters`);
203
+ if (!Array.isArray(options) || options.length < BOARD_LIMITS.options.min || options.length > BOARD_LIMITS.options.max) throw boardError("E_BAD_ARGS", `a question takes ${BOARD_LIMITS.options.min} to ${BOARD_LIMITS.options.max} --option (got ${Array.isArray(options) ? options.length : 0})`);
204
+ for (const o of options) if (!lineOk(o, BOARD_LIMITS.option)) throw boardError("E_BAD_ARGS", `each --option must be ${TEXT_RULE}, of 1 to ${BOARD_LIMITS.option} characters`);
205
+ if (id !== undefined && !BOARD_KEY_RE.test(id)) throw boardError("E_BAD_ARGS", `--id must match ${BOARD_KEY_RE.source}`);
206
+ if (context !== undefined && !contextOk(context)) throw boardError("E_BAD_ARGS", `the context must be 1 to ${BOARD_LIMITS.context} characters, with no control character but newline (LF), line separator, bidi control (U+202A-202E, U+2066-2069), U+200B, U+2060, U+FEFF or tag character`);
207
+ return { question, options: [...options], id, context: context ?? null };
208
+ }
209
+
210
+ /** The file's bytes for a document. */
211
+ function serialize(doc) {
212
+ const facts = {};
213
+ for (const f of doc.facts) facts[f.key] = { label: f.label, value: f.value, unit: f.unit, link: f.link, at: f.at, seq: f.seq, history: f.history };
214
+ return JSON.stringify({ boardApi: BOARD_API, asked: doc.asked, facts, questions: doc.questions }) + "\n";
215
+ }
216
+
217
+ /** One read-modify-write of `home`'s board, under its lock. `change(doc, now)` (doc: the live board, an
218
+ * empty one for no file) returns `{ changed, ...answer }` and may change `doc`; a change is checked against
219
+ * the bounds and written, and then the claim is set to what the questions say. → the answer with `board`,
220
+ * the row value after it. The caller holds the right to change the home. */
221
+ function updateBoard(home, change, { now = () => new Date() } = {}) {
222
+ const path = join(home, BOARD_FILE), lock = join(home, BOARD_LOCK);
223
+ return withDirLock(lock, "oats instance board", () => {
224
+ const stored = readBoardDocument(home);
225
+ // The session, read once under the lock: what the questions are judged by, what a new one records, and
226
+ // what the claim is bound to.
227
+ const s = liveSession(home);
228
+ const live = liveOf(stored, s);
229
+ const doc = live === null ? EMPTY() : { ...live, facts: [...live.facts], questions: [...live.questions] };
230
+ const out = change(doc, now().toISOString(), s.sessionKnown ? s.session : undefined);
231
+ // A question a session boundary ended is dropped by any write: a change, or one that only prunes.
232
+ const pruned = stored !== null && stored.questions.length !== doc.questions.length;
233
+ const written = out.changed || pruned;
234
+ if (written) {
235
+ if (doc.facts.length > BOARD_LIMITS.facts) throw boardError("E_BOARD_FULL", `the board holds at most ${BOARD_LIMITS.facts} facts: unset one first (oats instance board unset <key>); nothing was changed`);
236
+ if (doc.questions.length > BOARD_LIMITS.questions) throw boardError("E_BOARD_FULL", `at most ${BOARD_LIMITS.questions} questions are open at once: clear one you have read first (oats instance board ask --clear <id>); nothing was changed`);
237
+ const bytes = rowBytes(doc);
238
+ if (bytes > ROW_MAX) throw boardError("E_BOARD_FULL", `the board would be ${bytes} bytes on a status row, over its ${ROW_MAX}-byte bound: shorten it, or unset a fact or clear a question first; nothing was changed`, { bytes, max: ROW_MAX });
239
+ // What stands at the name, never followed: a directory there is no one's work (the name is kernel-owned),
240
+ // and a rename cannot replace it.
241
+ let standing = null;
242
+ try { standing = lstatSync(path); } catch (e) { if (e?.code !== "ENOENT") throw e; }
243
+ if (standing?.isDirectory()) rmSync(path, { force: true, recursive: true });
244
+ writeThroughPrivateFile(path, `${path}.tmp-${process.pid}`, serialize(doc), 0o600);
245
+ }
246
+ // Under the lock, so that two writes set the claim in the order they wrote the board.
247
+ syncClaim(home, doc, s, out);
248
+ const { changed, ...rest } = out;
249
+ return { ...rest, changed, board: stored === null && !written ? null : boardRow(doc) };
250
+ }, { retryMs: LOCK_WAIT_MS, busy: (why) => boardError("E_BOARD_BUSY", `the board of ${home} is being written by another oats process (${why}); retry; if no oats process is writing it, remove ${lock}; nothing was changed`, { lock }) });
251
+ }
252
+
253
+ /** Set the `oats.board` claim to what the live questions say: the oldest one's text while any is open, none
254
+ * otherwise. setWaiting writes only a change. A write it refuses is E_EVENTS_FAILED, after the board was
255
+ * written: the next board command repairs it. */
256
+ function syncClaim(home, doc, s, out) {
257
+ // Only a question of the proved session is live (liveOf), so a claim is set only for one.
258
+ const oldest = s.sessionKnown ? doc.questions.find((q) => q.session === s.session) : undefined;
259
+ try {
260
+ setWaiting(home, oldest ? { producer: BOARD_PRODUCER, waiting: true, reason: "attention", message: oldest.question, session: s.session } : { producer: BOARD_PRODUCER, waiting: false });
261
+ } catch (e) {
262
+ const what = out.id !== undefined ? `question ${out.id}` : `fact ${out.key}`;
263
+ throw boardError(e.code || "E_EVENTS_FAILED", `the board was written (${what}), but its needs-input claim was not: ${e.message}; run the same board command again to repair it (it changes nothing on the board)`, { ...(out.id !== undefined ? { id: out.id } : { key: out.key }) });
264
+ }
265
+ }
266
+
267
+ /** `oats instance board set <key>`: upsert one fact. A set that changes nothing writes nothing; a new value
268
+ * joins the key's history (its last BOARD_LIMITS.history values). → `{ key, changed, board }`. */
269
+ export function setBoardFact(home, fields, options) {
270
+ const fact = checkFact(fields);
271
+ return updateBoard(home, (doc, now) => {
272
+ const i = doc.facts.findIndex((f) => f.key === fact.key);
273
+ const old = i >= 0 ? doc.facts[i] : null;
274
+ if (old && old.label === fact.label && old.value === fact.value && old.unit === fact.unit && old.link === fact.link) return { key: fact.key, changed: false };
275
+ if (!old && doc.facts.length >= BOARD_LIMITS.facts) throw boardError("E_BOARD_FULL", `the board holds at most ${BOARD_LIMITS.facts} facts: unset one first (oats instance board unset <key>); nothing was changed`);
276
+ const history = old ? (old.value === fact.value ? old.history : [...old.history, { value: fact.value, at: now }].slice(-BOARD_LIMITS.history)) : [{ value: fact.value, at: now }];
277
+ const next = { ...fact, at: now, seq: old ? old.seq : Math.max(-1, ...doc.facts.map((f) => f.seq)) + 1, history };
278
+ if (old) doc.facts[i] = next; else doc.facts.push(next);
279
+ return { key: fact.key, changed: true };
280
+ }, options);
281
+ }
282
+
283
+ /** `oats instance board unset <key>`: remove one fact and its history. → `{ key, changed, board }`. */
284
+ export function unsetBoardFact(home, key, options) {
285
+ if (typeof key !== "string" || !BOARD_KEY_RE.test(key)) throw boardError("E_BAD_ARGS", `the key must match ${BOARD_KEY_RE.source}`);
286
+ return updateBoard(home, (doc) => {
287
+ const i = doc.facts.findIndex((f) => f.key === key);
288
+ if (i < 0) return { key, changed: false };
289
+ doc.facts.splice(i, 1);
290
+ return { key, changed: true };
291
+ }, options);
292
+ }
293
+
294
+ /** `oats instance board ask <question>`: open one question. Its id is `--id`, else `q<n>` (n numbered per
295
+ * home, never reused while it lives). The same question asked again under an open id is no change, so a
296
+ * retry is safe; a different one under an open id is refused. → `{ id, changed, board }`. */
297
+ export function askBoardQuestion(home, fields, options) {
298
+ const ask = checkQuestion(fields);
299
+ return updateBoard(home, (doc, now, session) => {
300
+ // No question is asked where the session can't be proved: it could never be live.
301
+ if (session === undefined) throw boardError("E_BOARD_FAILED", `the instance's current session can't be read from its events log (its last 4 MiB hold no session boundary), so a question would never show; use oats instance attention --message instead; nothing was changed`);
302
+ const same = (q) => q.question === ask.question && q.context === ask.context && q.options.length === ask.options.length && q.options.every((o, i) => o === ask.options[i]);
303
+ const open = ask.id !== undefined ? doc.questions.find((q) => q.id === ask.id) : doc.questions.find(same);
304
+ if (open) {
305
+ if (same(open)) return { id: open.id, changed: false };
306
+ throw boardError("E_BAD_ARGS", `question ${ask.id} is open with other text: clear it first (oats instance board ask --clear ${ask.id}), or ask under another --id; nothing was changed`);
307
+ }
308
+ if (doc.questions.length >= BOARD_LIMITS.questions) throw boardError("E_BOARD_FULL", `at most ${BOARD_LIMITS.questions} questions are open at once: clear one you have read first (oats instance board ask --clear <id>); nothing was changed`);
309
+ let id = ask.id;
310
+ if (id === undefined) {
311
+ const taken = new Set(doc.questions.map((q) => q.id));
312
+ let n = doc.asked;
313
+ do { n += 1; id = `q${n}`; } while (taken.has(id));
314
+ // q<n> is a key of at most 16 characters: past q999999999999999 there is no default id.
315
+ if (!BOARD_KEY_RE.test(id)) throw boardError("E_BOARD_FULL", "no default id is left on this board (they reached q999999999999999): ask with --id <id>; nothing was changed");
316
+ doc.asked = n;
317
+ } else {
318
+ // An explicit q<n> moves the count past it, so a default id never repeats it.
319
+ const n = /^q([1-9][0-9]{0,14})$/.exec(id);
320
+ if (n) doc.asked = Math.max(doc.asked, Number(n[1]));
321
+ }
322
+ doc.questions.push({ id, question: ask.question, options: ask.options, context: ask.context, since: now, session });
323
+ return { id, changed: true };
324
+ }, options);
325
+ }
326
+
327
+ /** `oats instance board ask --clear <id>`: close one question; an id that is not open is no change.
328
+ * → `{ id, changed, board }`. */
329
+ export function clearBoardQuestion(home, id, options) {
330
+ if (typeof id !== "string" || !BOARD_KEY_RE.test(id)) throw boardError("E_BAD_ARGS", `--clear takes the id of an open question (${BOARD_KEY_RE.source})`);
331
+ return updateBoard(home, (doc) => {
332
+ const i = doc.questions.findIndex((q) => q.id === id);
333
+ if (i < 0) return { id, changed: false };
334
+ doc.questions.splice(i, 1);
335
+ return { id, changed: true };
336
+ }, options);
337
+ }
@@ -25,7 +25,9 @@
25
25
  *
26
26
  * Producers write claims as `waiting` rows through `setWaiting` (the CLI's
27
27
  * `oats instance waiting` and `oats instance attention`): data
28
- * `{waitingOnYou, reason?, message?}`, appended only on a change. A claim
28
+ * `{waitingOnYou, reason?, message?, session?}`, appended only on a change; `session`
29
+ * (the board's claim, lib/instance-board.mjs) binds a positive claim to the session it was
30
+ * derived in, so it never counts in another (claimsOf). A claim
29
31
  * authorizes nothing; it may only withhold an automated keystroke: a scheduled
30
32
  * wake holds on a live `permission`, `question` or unknown-reason claim
31
33
  * (waitingHold). Every other reader takes it as evidence for display.
@@ -41,6 +43,7 @@
41
43
  * one home's, so its `home` is the address that was asked about, and a consumer
42
44
  * that checks "the rows' home is the home I asked for" keeps holding. */
43
45
  import { appendFileSync, closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync } from "node:fs";
46
+ import { createHash } from "node:crypto";
44
47
  import { basename, dirname, isAbsolute, join, resolve } from "node:path";
45
48
  import { REFUSED_TEXT, safeText } from "./refused-text.mjs";
46
49
 
@@ -85,6 +88,12 @@ function cutToUnits(text, max) {
85
88
  * incarnation's latest one is not live. */
86
89
  export const WAITING_BOUNDARY_KINDS = ["launched", "restarted", "stopped"];
87
90
  const sessionBoundary = (r) => (r.producer ?? "kernel") === "kernel" && WAITING_BOUNDARY_KINDS.includes(r.kind);
91
+ /** The id of the session a boundary row begins, or null for no boundary: what a session-bound claim
92
+ * (setWaiting `session`) and a board question (lib/instance-board.mjs) record. `<kind>@<at>#<digest of
93
+ * its data>`: two boundaries of one millisecond are told apart by what they record (a launch's
94
+ * `startId`, a stop's receipt), never by their place in a bounded read, and the same row written
95
+ * again (a start boundary repaired into the other log, recordStartBoundary) is the same session. */
96
+ const sessionIdOf = (r) => (r ? `${r.kind}@${r.at}#${createHash("sha256").update(JSON.stringify(r.data ?? null)).digest("hex").slice(0, 16)}` : null);
88
97
  /** The closed set of reasons a positive claim carries. A claim authorizes nothing; it may only
89
98
  * withhold an automated keystroke. `attention` never marks a screen an Enter answers: a producer
90
99
  * that wants one uses `question`, and review catches that. */
@@ -232,6 +241,10 @@ function append(a, event, { workspaceOnly = false, incarnation, at } = {}) {
232
241
  return { ok: results.some((r) => r.ok), row, results };
233
242
  }
234
243
 
244
+ /** Whether a read of one log holds the whole log: it was absent, or read in full (not a tail, not
245
+ * refused). */
246
+ const wholeRead = (log) => log.source.status === "ok" || log.source.status === "absent";
247
+
235
248
  /** Bounded, descriptor-safe read of one log: lstat → regular file only → read
236
249
  * at most the last MAX_BYTES. Returns rows plus the source's integrity facts, and
237
250
  * `lastTorn`: where the last torn row sat, as the index in `rows` of the row after it
@@ -300,8 +313,10 @@ function admit(home, reads) {
300
313
  * unknown stays unknown, it never resurrects an earlier incarnation's
301
314
  * positive. A row older than the incarnation's latest kernel session
302
315
  * boundary belongs to an ended session and is not a claim at all, nor is a
303
- * row whose producer is neither `kernel` nor a valid producer id. */
304
- function claimsOf(rows, incarnation) {
316
+ * row whose producer is neither `kernel` nor a valid producer id. `complete`:
317
+ * whether every log read was whole (wholeRead); a session-bound row needs it,
318
+ * or a boundary of the incarnation in the rows, to count (below). */
319
+ function claimsOf(rows, incarnation, { complete }) {
305
320
  const claims = new Map();
306
321
  if (incarnation === null) return claims;
307
322
  const current = rows.filter((r) => r.incarnation === incarnation);
@@ -309,8 +324,14 @@ function claimsOf(rows, incarnation) {
309
324
  // millisecond keep their append order, and a claim appended before the
310
325
  // boundary in that millisecond is still before it.
311
326
  const boundary = current.findLastIndex(sessionBoundary);
327
+ const session = sessionIdOf(current[boundary]);
312
328
  for (const r of current.slice(boundary + 1)) {
313
329
  if (!r.data || typeof r.data.waitingOnYou !== "boolean") continue;
330
+ // A session-bound row (setWaiting `session`) counts only in the session it names, and only where
331
+ // the read proves the current session: a boundary of the incarnation in the rows, or a whole read
332
+ // (with none, the first session). One appended after a boundary its writer had not seen, or read
333
+ // where the current boundary may have fallen out of a tail, says nothing. Unbound rows are as before.
334
+ if (Object.hasOwn(r.data, "session") && (r.data.session !== session || (boundary < 0 && !complete))) continue;
314
335
  const p = r.producer ?? "kernel";
315
336
  // A row the read rule refuses (a hand-edited log: its producer, its time) says nothing.
316
337
  const claim = readWaitingClaim({ since: r.at, producer: p, reason: r.data.reason, message: r.data.message });
@@ -344,7 +365,7 @@ export function readEvents(given, { limit = 200, since = null, asked } = {}) {
344
365
  const { home, instance, incarnation, homeLog, workspaceLog } = address;
345
366
  const a = readLog(homeLog, "home"), b = readLog(workspaceLog, "workspace");
346
367
  const { rows, foreign } = admit(home, [a, b]);
347
- const claims = claimsOf(rows, incarnation);
368
+ const claims = claimsOf(rows, incarnation, { complete: wholeRead(a) && wholeRead(b) });
348
369
  const waitingClaims = [...claims.values()];
349
370
  const positive = positiveOf(claims);
350
371
  const filtered = since ? rows.filter((r) => r.at > since) : rows;
@@ -374,11 +395,26 @@ export function readEvents(given, { limit = 200, since = null, asked } = {}) {
374
395
  * or a session boundary writes goes to both. `meta`: the home's record, when the caller has just
375
396
  * read it (lib/instance-listing.mjs listInstances), so that one read parses it once. */
376
397
  export function liveWaiting(home, { meta } = {}) {
398
+ return liveSession(home, { meta }).waitingOnYou;
399
+ }
400
+
401
+ /** The instance's current session as one read of its log shows it (liveWaiting's read):
402
+ * `{ incarnation, session, sessionKnown, waitingOnYou }`. `session` is the id of the incarnation's
403
+ * latest kernel session boundary (`launched`, `restarted`, `stopped`; `<kind>@<at>`), null when the
404
+ * read holds none. `sessionKnown` says whether the read proves it: false when the log was read as a
405
+ * tail (its last MAX_BYTES) that holds no boundary of this incarnation, where an earlier one may
406
+ * have been cut off. A board question counts only in the session it was asked in
407
+ * (lib/instance-board.mjs). An unknown incarnation is `{ incarnation: null, session: null,
408
+ * sessionKnown: false, waitingOnYou: null }`. */
409
+ export function liveSession(home, { meta } = {}) {
377
410
  const a = addressOf(home, meta);
378
- if (a.incarnation === null) return null;
411
+ if (a.incarnation === null) return { incarnation: null, session: null, sessionKnown: false, waitingOnYou: null };
379
412
  let log = readLog(a.homeLog, "home");
380
413
  if (log.source.status === "absent") log = readLog(a.workspaceLog, "workspace");
381
- return waitingShape(positiveOf(claimsOf(admit(a.home, [log]).rows, a.incarnation)));
414
+ const rows = admit(a.home, [log]).rows;
415
+ const boundary = rows.filter((r) => r.incarnation === a.incarnation).findLast(sessionBoundary);
416
+ const sessionKnown = !!boundary || wholeRead(log);
417
+ return { incarnation: a.incarnation, session: sessionIdOf(boundary), sessionKnown, waitingOnYou: waitingShape(positiveOf(claimsOf(rows, a.incarnation, { complete: wholeRead(log) }))) };
382
418
  }
383
419
 
384
420
  /** What holds a scheduled wake at this home: null (no hold), `{claimReason, producer}` (a claim), or
@@ -403,7 +439,7 @@ export function waitingHold(given) {
403
439
  if (status === "tail" && boundary < 0) return unreadable(`the ${path} events log's tail holds no session boundary`);
404
440
  if (log.lastTorn > boundary) return unreadable(`the ${path} events log has a torn row in this session`);
405
441
  }
406
- const claims = [...claimsOf(admit(a.home, logs).rows, a.incarnation).values()].filter((c) => c.waiting && c.reason !== "attention");
442
+ const claims = [...claimsOf(admit(a.home, logs).rows, a.incarnation, { complete: logs.every(wholeRead) }).values()].filter((c) => c.waiting && c.reason !== "attention");
407
443
  const newest = claims.sort((x, y) => x.since.localeCompare(y.since)).at(-1);
408
444
  return newest ? { claimReason: newest.reason, producer: newest.producer } : null;
409
445
  }
@@ -420,13 +456,15 @@ const waitingError = (code, message) => Object.assign(new Error(message), { code
420
456
  * E_SESSION_UNKNOWN; a write either log refused is E_EVENTS_FAILED (a retry
421
457
  * repairs it). The answer's `home` is the home as the caller spelled it; the row
422
458
  * records the real path. Evidence, not authority: nothing else is touched. */
423
- export function setWaiting(given, { producer, waiting, reason, message } = {}) {
459
+ export function setWaiting(given, { producer, waiting, reason, message, session } = {}) {
424
460
  if (typeof producer !== "string" || !WAITING_PRODUCER_RE.test(producer)) throw waitingError("E_BAD_ARGS", `--producer must match ${WAITING_PRODUCER_RE.source}`);
425
461
  if (producer === "kernel") throw waitingError("E_BAD_ARGS", "--producer kernel is reserved for the kernel's own events");
426
462
  if (typeof waiting !== "boolean") throw waitingError("E_BAD_ARGS", "waiting must be set or clear");
427
463
  if (waiting) {
428
464
  if (!WAITING_REASONS.includes(reason)) throw waitingError("E_BAD_ARGS", `--reason must be one of ${WAITING_REASONS.join(", ")}`);
429
465
  if (message !== undefined && !validWaitingMessage(message)) throw waitingError("E_BAD_ARGS", `--message must be one line of 1 to ${WAITING_MESSAGE_MAX} characters with no control character, line separator, bidi control (U+202A-202E, U+2066-2069), U+200B, U+2060, U+FEFF or tag character`);
466
+ // A session-bound claim (in-process only: the board's) names the session it was derived in.
467
+ if (session !== undefined && session !== null && typeof session !== "string") throw waitingError("E_BAD_ARGS", "session must be a session id or null");
430
468
  } else {
431
469
  if (reason !== undefined) throw waitingError("E_BAD_ARGS", "--reason is for set, not clear");
432
470
  if (message !== undefined) throw waitingError("E_BAD_ARGS", "--message is for set, not clear");
@@ -435,11 +473,11 @@ export function setWaiting(given, { producer, waiting, reason, message } = {}) {
435
473
  const { home, incarnation } = a;
436
474
  if (incarnation === null) throw waitingError("E_SESSION_UNKNOWN", `${given} is not an instance home (no readable instance.json)`);
437
475
  const live = [readLog(a.homeLog, "home"), readLog(a.workspaceLog, "workspace")]
438
- .map((log) => { const c = claimsOf(admit(home, [log]).rows, incarnation).get(producer); return c?.waiting ? c : null; });
476
+ .map((log) => { const c = claimsOf(admit(home, [log]).rows, incarnation, { complete: wholeRead(log) }).get(producer); return c?.waiting ? c : null; });
439
477
  const agrees = (c) => (waiting ? !!c && c.reason === reason && c.message === (message ?? null) : !c);
440
478
  const answer = (changed, claim) => answered(a, { eventsApi: EVENTS_API, instance: a.instance, home, producer, changed, waitingOnYou: waitingShape(claim) });
441
479
  if (live.every(agrees)) return answer(false, waiting ? live[0] : null);
442
- const data = waiting ? { waitingOnYou: true, reason, ...(message !== undefined ? { message } : {}) } : { waitingOnYou: false };
480
+ const data = waiting ? { waitingOnYou: true, reason, ...(message !== undefined ? { message } : {}), ...(session !== undefined ? { session } : {}) } : { waitingOnYou: false };
443
481
  const res = append(a, { producer, kind: "waiting", data }, { incarnation });
444
482
  const failed = (res.results || []).filter((r) => !r.ok);
445
483
  if (!res.ok || failed.length) throw waitingError("E_EVENTS_FAILED", `could not record the waiting claim in ${failed.map((r) => `${r.path} (${r.reason})`).join(", ") || res.reason}; retry to complete it`);
@@ -21,7 +21,7 @@ import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
21
21
  import { INSTANCE_COLOR_API, INSTANCE_COLORS, writeInstanceColor } from "./instance-color.mjs";
22
22
  import { INSTANCE_BACKGROUND_API, writeInstanceBackground } from "./instance-background.mjs";
23
23
  import { INSTANCE_PIN_API, writeInstancePin } from "./instance-pin.mjs";
24
- import { sameWorkOf, writeSameWork } from "./instance-same-work.mjs";
24
+ import { relatedWorkBinding, relatedWorkHeld, writeRelatedWork } from "./instance-related-work.mjs";
25
25
  import { resolveInstance } from "./instance-address.mjs";
26
26
  export { resolveInstance } from "./instance-address.mjs";
27
27
 
@@ -110,23 +110,27 @@ export function setInstancePin(ctx, root, name, { home, pinned }) {
110
110
  return { instancePinApi: INSTANCE_PIN_API, instance: name, home: me.home, pinned, changed };
111
111
  }
112
112
 
113
- /** `oats instance same-work <instance> on|off` (feature instance-same-work, awebai/oats#1577): bind the flag
114
- * of the home `name` resolves to to its recorded parent (`on`), or remove it (`off`). Addressed, and refused
115
- * beside a retire or in a quarantined home, exactly as setInstanceColor is. `on` needs a recorded
116
- * `parentInstance` (E_BAD_ARGS without one) and rebinds a record bound to an old parent; the same parent
117
- * again writes nothing. `off` succeeds whatever stands there, parent or none. → `{ instance, sameWork }`,
118
- * the rule (sameWorkOf) read after the write. */
119
- export function setInstanceSameWork(ctx, root, name, { home, on }) {
120
- if (typeof on !== "boolean") throw oatsError("E_BAD_ARGS", "instance same-work takes on or off");
113
+ /** `oats instance related-work <instance> on|off` (feature instance-related-work), and its deprecated alias
114
+ * `oats instance same-work` (feature instance-same-work): bind the flag of the home
115
+ * `name` resolves to to its recorded parent, else to its recorded sibling (`on`, relatedWorkBinding), or
116
+ * remove it (`off`). Addressed, and refused beside a retire or in a quarantined home, exactly as
117
+ * setInstanceColor is. `on` needs a recorded `parentInstance` or `siblingInstance` (E_BAD_ARGS with
118
+ * neither) and rebinds a record bound to an old relation; the same binding again writes nothing. `off`
119
+ * succeeds whatever stands there, binding or none. → `{ instance, relatedWork, sameWork }`, the rule
120
+ * (relatedWorkHeld) read after the write: `relatedWork` whether it holds, `sameWork` whether it holds as a
121
+ * parent binding (the old verb's answer, for an older client). */
122
+ export function setInstanceRelatedWork(ctx, root, name, { home, on }) {
123
+ if (typeof on !== "boolean") throw oatsError("E_BAD_ARGS", "instance related-work takes on or off");
121
124
  const me = resolveTarget(ctx, root, name, { home });
122
125
  if (existsSync(join(me.home, ".oats-rollback-incomplete.json"))) throw oatsError("E_INSTANCE_RETIRING", `${me.home} is a quarantined home (or a spawn still in progress); finish its retirement (oats retire); the flag was not changed`);
123
126
  if (existsSync(retirePendingMarkerPath(me.home))) throw oatsError("E_INSTANCE_RETIRING", `${name} is being retired; the flag was not changed`);
124
- refuseBesideRetire("instance same-work", me.home);
125
- const recorded = targetRecord(me.home)?.parentInstance;
126
- const parent = typeof recorded === "string" && recorded !== "" ? recorded : null;
127
- if (on && parent === null) throw oatsError("E_BAD_ARGS", `${name} has no parent instance: same work is declared against a recorded parent; the flag was not changed`);
128
- writeSameWork(me.home, on ? parent : null);
129
- return { instance: name, sameWork: sameWorkOf(me.home, parent) };
127
+ refuseBesideRetire("instance related-work", me.home);
128
+ const lineage = targetRecord(me.home) ?? {};
129
+ const binding = relatedWorkBinding(lineage);
130
+ if (on && binding === null) throw oatsError("E_BAD_ARGS", `${name} would record no parent or sibling instance: related work is declared against a recorded parent or sibling; the flag was not changed`);
131
+ writeRelatedWork(me.home, on ? binding : null);
132
+ const held = relatedWorkHeld(me.home, lineage);
133
+ return { instance: name, relatedWork: held !== null, sameWork: !!held?.parent };
130
134
  }
131
135
 
132
136
  /** Every instance under the roots whose recorded parent chain reaches `name`,
@@ -8,7 +8,8 @@ import { readFileSync, readdirSync, lstatSync, existsSync, statSync, openSync, c
8
8
  import { join, dirname, resolve, basename } from "node:path";
9
9
  import { noteRuntimeName } from "./deprecation.mjs";
10
10
  import { createSessionPaneInspector, AGENT_PANE_OPTION } from "./session-input.mjs";
11
- import { liveWaiting, validWaitingMessage } from "./instance-events.mjs";
11
+ import { liveSession, validWaitingMessage } from "./instance-events.mjs";
12
+ import { readBoardRow } from "./instance-board.mjs";
12
13
  import { processLiveness } from "./worktree-hooks.mjs";
13
14
  import { shownHolder } from "./claim.mjs";
14
15
  import { isInstant as isInstantString, readRetireState } from "./retire-state.mjs";
@@ -16,7 +17,7 @@ import { herdrInstanceRemoved, oatsError } from "./errors.mjs";
16
17
  import { readInstanceColor } from "./instance-color.mjs";
17
18
  import { readInstanceBackground } from "./instance-background.mjs";
18
19
  import { readInstancePin } from "./instance-pin.mjs";
19
- import { sameWorkOf } from "./instance-same-work.mjs";
20
+ import { relatedWorkHeld } from "./instance-related-work.mjs";
20
21
  import { readSpawnedBy } from "./spawned-by.mjs";
21
22
  import { sessionEndOf } from "./session-end.mjs";
22
23
  import { identityHolderState, recordSeen } from "./session-seen.mjs";
@@ -345,15 +346,17 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
345
346
  // its home log); null otherwise, and null means unknown. Pane liveness is
346
347
  // already observed in the batch; still require the independent receipt
347
348
  // to agree before showing a claim, just as session inspect does.
348
- let waitingOnYou = liveness.running === true ? liveWaiting(home, record.state === "record" ? { meta: record.meta } : {}) : null;
349
+ const recordMeta = record.state === "record" ? { meta: record.meta } : {};
350
+ const session = liveness.running === true ? liveSession(home, recordMeta) : undefined;
351
+ let waitingOnYou = session ? session.waitingOnYou : null;
349
352
  if (waitingOnYou) {
350
353
  try { const s = instanceSessionTarget(home); if (!s.target) waitingOnYou = null; }
351
354
  catch { waitingOnYou = null; }
352
355
  }
353
- // `retire` is only ever the value read above, and `background`, `pinned` and `sameWork` the home's own
356
+ // `retire` is only ever the value read above, and `background`, `pinned`, `relatedWork` and `board` the home's own
354
357
  // records (below): a record that carries any of them (hand-edited, or copied from a row) never stands in
355
- // for it.
356
- const { retire: _recordedRetire, background: _recordedBackground, pinned: _recordedPinned, sameWork: _recordedSameWork, ...recorded } = meta;
358
+ // for it. Nor does a `sameWork` key, the flag's old name (below).
359
+ const { retire: _recordedRetire, background: _recordedBackground, pinned: _recordedPinned, relatedWork: _recordedRelatedWork, sameWork: _recordedSameWork, board: _recordedBoard, ...recorded } = meta;
357
360
  // `spawnedBy` (feature spawn-attribution) is the record's own, read in place by its rule (lib/spawned-by.mjs):
358
361
  // a malformed one is null, and a home spawned before the feature has no key.
359
362
  if (Object.hasOwn(recorded, "spawnedBy")) recorded.spawnedBy = readSpawnedBy(recorded.spawnedBy);
@@ -365,10 +368,15 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
365
368
  // null, after the record so that nothing in instance.json stands in for it.
366
369
  // Feature instance-pin: `pinned: true` while the home holds a valid pin (lib/instance-pin.mjs), absent
367
370
  // otherwise, never false.
368
- // Feature instance-same-work: `sameWork: true` only while the home's flag is bound to the parent
369
- // its readable record names (lib/instance-same-work.mjs sameWorkOf); absent otherwise, never false.
370
- const sameWork = record.state === "record" && sameWorkOf(home, meta.parentInstance);
371
- return { ...recorded, ...claims, home, instance: e.name, ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(readInstancePin(home) ? { pinned: true } : {}), ...(sameWork ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
371
+ // Feature instance-related-work: `relatedWork: true` only while the home's flag is bound to the relation
372
+ // its record still has (lib/instance-related-work.mjs relatedWorkHeld); absent otherwise, never false.
373
+ // Feature instance-same-work, the compatibility layer: `sameWork: true` beside it for a parent binding
374
+ // only, as an older client reads it; absent otherwise.
375
+ const related = record.state === "record" ? relatedWorkHeld(home, meta) : null;
376
+ // Feature instance-board: the agent's board (lib/instance-board.mjs), null for a home with no board
377
+ // file: its facts, and the questions of its current session, by the same read of the log as the claim.
378
+ const board = readBoardRow(home, { session, ...recordMeta });
379
+ return { ...recorded, ...claims, home, instance: e.name, ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(readInstancePin(home) ? { pinned: true } : {}), ...(related ? { relatedWork: true } : {}), ...(related?.parent ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, board, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
372
380
 
373
381
  });
374
382
  };