@volter/supercode-orchestrator 0.5.2 → 0.5.4

package/board/dispatch.mjs

@@ -154,10 +154,10 @@ function unpublishedAlive(session) {
 /** Native activity comes from the machine's harness discovery, not catalogue age. */
 function nativeSessions(machine, harness) {
   if (offlineMachine(machine)) throw unavailable(`native liveness unavailable: machine ${normalMachine(machine)} is offline`);
-  const args = normalMachine(machine) === localMachine()
-    ? ['teams', 'rpc', 'sessions.discover', JSON.stringify({ harnesses: [harness], limit: 2000 })]
-    : ['discover', '--on', machine, '--harness', harness, '--limit', '2000'];
-  const result = sc(args, { timeout: 120_000 });
+  // This machine's discovery is its harness door, as every other harness read here is; another machine's is supercode's fleet arm
+  const result = normalMachine(machine) === localMachine()
+    ? doorOn(machine, 'harness.v1.sessions.discover', { harnesses: [harness], limit: 2000 }, { timeout: 120_000 })
+    : sc(['discover', '--on', machine, '--harness', harness, '--limit', '2000'], { timeout: 120_000 });
   const page = result.code === 0 ? lastJson(result.stdout) : null;
   if (!Array.isArray(page?.sessions)) throw unavailable(`native liveness unavailable on ${machine}: ${(result.stderr || result.stdout).trim().slice(-300)}`);
   return page.sessions;
@@ -1516,9 +1516,12 @@ export function requestAdoption(board, id, who, { workspace = null, assignee = n
   });
 }
 
+/** How long a requested adoption waits for its session to appear in the fleet before it fails. */
+const ADOPTION_LISTING_WINDOW_S = 180;
+
 /** Adoptions the manager requested and no tick has answered yet, completed from this tick's fleet reading. */
 export function completeAdoptions(board, fleet, settings, report, lanes = null) {
-  const pending = view(board, db => db.prepare(`SELECT e.task_id, e.payload FROM task_events e WHERE e.kind = 'dispatch_held'
+  const pending = view(board, db => db.prepare(`SELECT e.task_id, e.payload, e.created_at FROM task_events e WHERE e.kind = 'dispatch_held'
     AND json_extract(e.payload, '$.reason') = 'adoption requested'
     AND e.id = (SELECT MAX(id) FROM task_events l WHERE l.task_id = e.task_id AND l.kind IN ('dispatch_held','dispatch_released','session_adopted','adoption_failed'))`).all());
   for (const row of pending) {
@@ -1528,6 +1531,12 @@ export function completeAdoptions(board, fleet, settings, report, lanes = null)
       (report.adopted ??= []).push([row.task_id, got.address]);
     } catch (error) {
       const message = String(error.message).slice(-400);
+      // A session opened moments before its adoption is asked may not be in the fleet's published set yet: the
+      // card stays held and each tick looks again, until the window closes
+      if (error.notListed && Date.now() / 1000 - Number(row.created_at) < ADOPTION_LISTING_WINDOW_S) {
+        report.queued.push([row.task_id, `adoption of ${asked.session} waits: ${message}`]);
+        continue;
+      }
       tx(board, db => event(db, row.task_id, 'adoption_failed', { session: asked.session, error: message }));
       report.failed.push([row.task_id, `adoption of ${asked.session}: ${message}`]);
     }
@@ -1538,7 +1547,7 @@ function adoptSession(board, id, who, { workspace = null, ttl, assignee = null,
   fleet ??= observeFleet();
   if (!fleet.ok) throw new Error(`supercode could not read the fleet: ${fleet.error}`);
   const found = fleet.sessions.find((s) => s.address === who || s.address.endsWith(`:${who}`) || s.name === who);
-  if (!found) throw new Error(`the fleet lists no live session ${who}`);
+  if (!found) throw Object.assign(new Error(`the fleet lists no live session ${who}`), { notListed: true });
   const [, host, harness, sessionId] = found.address.split(':');
   if (!HARNESSES[harness]) throw new Error(`${found.address} is ${harness}; the board keeps and resumes ${Object.keys(HARNESSES).join(' and ')} sessions`);
   const native = found.pane ? null : nativeReading(nativeSessions(host, harness), { session_id: sessionId, harness });

package/board/git-document.mjs

@@ -0,0 +1,97 @@
+// THE BOARD DOCUMENT IN GIT (company RFC 0025 decision 3; ADR 0001 points 2 and 3): when the board's document lives in a
+// git checkout and the board says so (`"commit": true` in its ztrack.json), each write the manager does not make (its
+// `"manager"`) is committed with its doer as author and pushed, after the checkout has taken what others pushed. People edit the document both here
+// (through the board's verbs) and as pages (Git Notes, where an edit is a pull request under their own account): a pull
+// request merged on the remote reaches the board before its next write, and a write that raced one takes it in a merge,
+// the two texts of a board document merged by ztrack's own document merge, in which a hand edit wins its cards. Nothing
+// either side wrote is dropped; a merge that cannot be made stops the push and says why, leaving both texts in the
+// checkout's history.
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename, dirname, relative } from 'node:path';
+
+const git = (cwd, args, input) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'pipe'], ...(input === undefined ? {} : { input }), timeout: 120_000 });
+const quiet = (cwd, args) => { try { return git(cwd, args); } catch { return null; } };
+// Another board process (or the manager's own git) may hold git's index for a moment: its index.lock is waited out, not
+// raced. The board keeps no lock of its own (ADR 0003).
+const indexed = (cwd, args) => {
+  for (let attempt = 0; ; attempt++) {
+    try { return git(cwd, args); } catch (error) {
+      if (attempt >= 20 || !/index\.lock/.test(String(error.stderr ?? error.message))) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 250);
+    }
+  }
+};
+
+export class GitDocument {
+  constructor(paths, merge) {
+    this.paths = paths;
+    this.cwd = dirname(paths[0]);
+    this.root = quiet(this.cwd, ['rev-parse', '--show-toplevel'])?.trim() ?? null;
+    this.merge = merge; // (base, theirs, ours, path) => text | null, ztrack's mergeBoardDocument
+  }
+
+  get usable() { return this.root !== null; }
+  rel(path) { return relative(this.root, path); }
+  branch() { return git(this.root, ['rev-parse', '--abbrev-ref', 'HEAD']).trim(); }
+
+  // Before a write: take what was pushed, so a merged pull request's edit is the document the write starts from.
+  pull() {
+    if (!this.usable) return;
+    const branch = this.branch();
+    if (quiet(this.root, ['fetch', '--quiet', 'origin', branch]) === null) return; // offline: the next write tries again
+    const behind = Number(git(this.root, ['rev-list', '--count', `HEAD..origin/${branch}`]).trim());
+    if (behind === 0) return;
+    const dirty = git(this.root, ['status', '--porcelain', '--', ...this.paths.map((path) => this.rel(path))]).trim();
+    if (dirty) return; // a write in progress publishes first and takes what was pushed after
+    this.integrate(branch, 'board');
+  }
+
+  // After a write: commit the board documents as their doer, then push, taking anything pushed meanwhile.
+  commit(doer, message) {
+    if (!this.usable) return;
+    // Only documents that exist or are tracked: the archive is written when a card first ends, and a pathspec naming a
+    // file git does not know fails the whole commit.
+    const files = this.paths.map((path) => this.rel(path)).filter((file) => quiet(this.root, ['ls-files', '--error-unmatch', file]) !== null || readable(`${this.root}/${file}`));
+    if (!files.length) return;
+    indexed(this.root, ['add', '--', ...files]);
+    if (!git(this.root, ['diff', '--cached', '--name-only', '--', ...files]).trim()) return;
+    const who = doer || 'board';
+    indexed(this.root, ['-c', `user.name=${who}`, '-c', 'user.email=board@supercode.invalid', 'commit', '--quiet', '--author', `${who} <board@supercode.invalid>`, '-m', message, '--', ...files]);
+    const branch = this.branch();
+    for (let attempt = 0; attempt < 3; attempt++) {
+      if (quiet(this.root, ['push', '--quiet', 'origin', `HEAD:${branch}`]) !== null) return;
+      if (quiet(this.root, ['fetch', '--quiet', 'origin', branch]) === null) throw new Error('the board documents were committed here but could not be pushed: the remote did not answer');
+      this.integrate(branch, who);
+    }
+    throw new Error('the board documents were committed here but the push was refused three times');
+  }
+
+  // Take what was pushed with a merge: it works beside the other edits in this checkout (the manager's own files), which
+  // a rebase refuses. A board document both sides changed is merged by the board's own document merge; any other
+  // conflict leaves the checkout as it was and says so.
+  integrate(branch, who) {
+    const merged = (() => { try { git(this.root, ['-c', `user.name=${who}`, '-c', 'user.email=board@supercode.invalid', 'merge', '--no-edit', '--quiet', `origin/${branch}`]); return true; } catch (error) { return String(error.stderr ?? error.message); } })();
+    if (merged === true) return;
+    const conflicted = git(this.root, ['diff', '--name-only', '--diff-filter=U']).trim().split('\n').filter(Boolean);
+    if (!conflicted.length) {
+      quiet(this.root, ['merge', '--abort']);
+      throw new Error(`what was pushed could not be taken: ${merged.trim().split('\n')[0]}`);
+    }
+    for (const file of conflicted) {
+      const path = `${this.root}/${file}`;
+      // In a merge, stage 2 is this checkout's text and stage 3 the pushed one.
+      const stage = (n) => quiet(this.root, ['show', `:${n}:${file}`]) ?? '';
+      const text = this.paths.some((own) => this.rel(own) === file) ? this.merge(stage(1), stage(3), stage(2), path) : null;
+      if (text === null) {
+        quiet(this.root, ['merge', '--abort']);
+        throw new Error(`${basename(file)} could not be merged with what was pushed; nothing was pushed, and this checkout is as it was`);
+      }
+      writeFileSync(path, text);
+      indexed(this.root, ['add', '--', file]);
+    }
+    indexed(this.root, ['-c', `user.name=${who}`, '-c', 'user.email=board@supercode.invalid', 'commit', '--quiet', '--no-edit']);
+  }
+}
+
+function readable(path) { try { readFileSync(path); return true; } catch { return false; } }

package/board/ztrack.mjs

@@ -10,9 +10,10 @@
 import { createRequire } from 'node:module';
 import { createHash, randomBytes } from 'node:crypto';
 import { existsSync, linkSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { basename, dirname, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
-import { actorOf, event, json, now, setActor } from './store.mjs';
+import { actorOf, event, json, now, principalOf, setActor } from './store.mjs';
+import { GitDocument } from './git-document.mjs';
 import { fire, statusOf, storedStatus, workflowFor } from './workflow.mjs';
 import { completionPhase, inspectCompletionEvidence, withCompletionEvidence } from './ci.mjs';
 
@@ -24,6 +25,11 @@ const quote = (s) => `"${String(s).replaceAll('"', '""')}"`;
 const nativeId = (id) => /^t-[a-f0-9]+$/.test(id) ? id.replace('t-', 't_') : id;
 const RUNTIME = new Set(['claim_lock', 'claim_expires', 'worker_pid', 'last_heartbeat_at', 'current_run_id', 'consecutive_failures', 'last_failure_error', 'block_recurrences', 'session_id', 'workspace_path']);
 const CARD_MAIN = new Set(['id', 'title', 'body', 'status', 'assignee', 'priority', 'workspace_kind', 'workspace_path', 'branch_name']);
+// What a run left on a card (its result, who and when): the runtime store's, never the document's (company RFC 0025
+// decision 4; ADR 0001 point 1). A document edit keeps the store's values.
+const RUN_OUTPUT = new Set(['result', 'created_by', 'created_at', 'started_at', 'completed_at', 'idempotency_key']);
+const declared = (key, value) => value != null && !RUNTIME.has(key) && !CARD_MAIN.has(key) && !RUN_OUTPUT.has(key) && !(key === 'goal_mode' && value === 0);
+const ENDED = new Set(['done', 'cancelled']);
 const CLOCKS = new Set(['since', 'after_fired', 'next_run_at', 'workspace_root']);
 const atomic = (path, text) => { const tmp = `${path}.${process.pid}.tmp`; writeFileSync(tmp, text, { mode: 0o600 }); renameSync(tmp, path); };
 const sleep = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
@@ -63,10 +69,16 @@ export function openZtrackBoard(marker, { create = false, document = null, seed
 }
 
 class ZtrackBoard {
-  constructor({ document, seed, marker, init, root, slug, compatPath }) {
+  constructor({ document, seed, marker, init, root, slug, compatPath, commit = false, manager = null }) {
     this.path = resolve(dirname(marker), document);
     this.archive = `${this.path}.archive.md`;
     this.docs = [{ role: 'open', path: this.path }, { role: 'archived', path: this.archive }];
+    // `"commit": true` in the board's ztrack.json: the documents live in a git checkout, and each write is committed as
+    // its doer and pushed, after taking what was pushed (git-document.mjs; company RFC 0025 decision 3).
+    // `"manager"`: the board's manager (its principal or session address), whose writes it commits itself as part of its
+    // own work; the backing commits only the writes the manager does not make.
+    this.manager = manager;
+    this.git = commit ? new GitDocument([this.path, this.archive], (base, theirs, ours, path) => { try { return this.codec.mergeBoardDocument(base, theirs, ours, path)?.text ?? null; } catch { return null; } }) : null;
     this.seed = seed; this.root = root; this.slug = slug; this.init = init; this.compatPath = compatPath;
     this.file = `${marker}.board.db`;
     mkdirSync(dirname(this.path), { recursive: true });
@@ -321,6 +333,8 @@ class ZtrackBoard {
   // ------------------------------------------------------------------ writes
 
   tx(fn) {
+    // A pull request merged on the remote (a page edited in Git Notes) is in the document before this write reads it.
+    try { this.git?.pull(); } catch (error) { process.stderr.write(`board: ${error.message}\n`); }
     if (this.active) return fn(this.db);
     for (let attempt = 0; ; attempt++) {
       const hermes = this.seed ? null : this.prepareHermes();
@@ -358,7 +372,13 @@ class ZtrackBoard {
         throw error;
       } finally { this.active = false; }
       this.seed = null;
-      if (outcome.intent) this.publish(outcome);
+      if (outcome.intent) {
+        this.publish(outcome);
+        // Committed as the session (or person) whose act this write was, and pushed.
+        const byManager = this.manager !== null && (actorOf() === this.manager || principalOf() === this.manager);
+        if (!byManager) try { this.git?.commit(actorOf(), `board: ${outcome.files.map((file) => basename(file.path)).join(', ')} written for ${actorOf() ?? 'the board'}`); }
+        catch (error) { process.stderr.write(`board: ${error.message}\n`); }
+      }
       this.exportFollowing();
       return outcome.result;
     }
@@ -468,7 +488,10 @@ class ZtrackBoard {
         subtasks.push(tid);
       }
       plan.subtasks.set(id, subtasks);
-      for (const old of this.statement('SELECT task_id FROM main.supercode_cards WHERE subtask_of = ?').all(id)) if (!subtasks.includes(old.task_id)) this.planRemoval(plan, old.task_id);
+      // An ended subtask is kept in the archive document, not in its card's text: its absence there is no removal.
+      for (const old of this.statement('SELECT s.task_id, s.stage, t.status FROM main.supercode_cards s LEFT JOIN main.tasks t ON t.id = s.task_id WHERE s.subtask_of = ?').all(id)) {
+        if (!subtasks.includes(old.task_id) && !ENDED.has(old.stage ?? old.status)) this.planRemoval(plan, old.task_id);
+      }
     }
     // A task ref (`<arc>:c3`) names a subtask by its key; resolve it once every key is known.
     const keyed = new Map([...plan.tasks].map(([tid, { key }]) => [key, tid]));
@@ -663,11 +686,13 @@ class ZtrackBoard {
 
   // A card's rows from its parsed document form. Run fields and clocks stay the table's.
   cardRows(id, card, parent = null) {
-    const meta = card.metadata ?? {};
+    // An ended subtask kept in the archive document names its card (`subtask_of`); it is not a column of the task.
+    const { subtask_of: declaredParent, ...meta } = card.metadata ?? {};
+    parent ??= declaredParent ? nativeId(declaredParent) : null;
     const stored = this.preset.serializeKanbanCard({ ...card, acceptanceCriteria: [], relations: [], metadata: undefined, paused: undefined, every: undefined, workspace: undefined, branch: undefined, machine: undefined, priority: undefined });
     const workspace = /^(scratch|dir|worktree)(?::(.*))?$/.exec(card.workspace ?? 'scratch');
     const old = this.one('SELECT * FROM main.tasks WHERE id = ?', id) ?? {};
-    const runtime = Object.fromEntries(Object.entries(old).filter(([k]) => RUNTIME.has(k)));
+    const runtime = Object.fromEntries(Object.entries(old).filter(([k]) => RUNTIME.has(k) || RUN_OUTPUT.has(k)));
     const task = { ...meta, ...runtime, id, title: card.title, body: stored.body,
       status: card.status, assignee: card.assignee ?? null, created_at: meta.created_at ?? old.created_at ?? now(), priority: card.priority ?? 0,
       workspace_kind: workspace?.[1] ?? 'scratch', workspace_path: runtime.workspace_path ?? (/^(\/|~|[A-Za-z]:[\\/])/.test(workspace?.[2] ?? '') ? workspace[2] : null), branch_name: card.branch ?? null };
@@ -685,10 +710,17 @@ class ZtrackBoard {
     return card.acceptanceCriteria.map((task) => {
       const key = `${id}:${task.id}`;
       const tid = task.metadata?.id ?? this.one('SELECT id FROM main.board_tasks WHERE key = ?', key)?.id ?? `t_${randomBytes(4).toString('hex')}`;
-      const taskCard = { ...task.metadata?.card, id: tid, title: `${task.id} ${task.text}`, body: task.metadata?.body ?? '',
-        status: task.status === 'passed' ? (task.metadata?.status === 'cancelled' ? 'cancelled' : 'done') : (['done', 'cancelled'].includes(task.metadata?.status) ? 'todo' : task.metadata?.status ?? 'todo'),
-        metadata: task.metadata?.properties ?? {}, assignee: task.metadata?.assignee ?? card.assignee,
-        machine: task.metadata?.machine ?? card.machine, acceptanceCriteria: [], acceptance: task.lines ?? [],
+      // A task line carries its brief and its tick; what else the subtask holds is the store's (an older document's
+      // `metadata:` line is still read).
+      const stored = task.metadata ? null : this.one('SELECT * FROM main.tasks WHERE id = ?', tid);
+      const storedState = task.metadata ? null : this.one('SELECT * FROM main.supercode_cards WHERE task_id = ?', tid);
+      const was = task.metadata?.status ?? storedState?.stage ?? stored?.status;
+      const taskCard = { ...task.metadata?.card, ...(storedState ? { paused: json(storedState.paused, null) ?? undefined, every: storedState.every || undefined } : {}),
+        id: tid, title: `${task.id} ${task.text}`, body: task.metadata?.body ?? task.brief ?? '',
+        status: task.status === 'passed' ? (was === 'cancelled' ? 'cancelled' : 'done') : (ENDED.has(was) ? 'todo' : was ?? 'todo'),
+        metadata: task.metadata?.properties ?? Object.fromEntries(Object.entries(stored ?? {}).filter(([k, v]) => declared(k, v))),
+        assignee: task.metadata?.assignee ?? stored?.assignee ?? card.assignee,
+        machine: task.metadata?.machine ?? storedState?.machine ?? card.machine, acceptanceCriteria: [], acceptance: task.lines ?? [],
         relations: (task.blockedBy ?? []).map((b) => ({ type: 'blocked-by', issueId: b.ac && /^(?:[ma]-[0-9a-f]{6,}|t_[0-9a-f]+)$/.test(b.ac) ? b.ac : b.ac ? `${nativeId(b.issue)}:${b.ac}` : nativeId(b.issue) })) };
       if (task.waitingOn) taskCard.relations.push({ type: 'blocked-by', issueId: task.waitingOn });
       return [tid, taskCard, key, task.sources];
@@ -731,6 +763,22 @@ class ZtrackBoard {
       const at = where.get(id);
       if (!task) { if (at) edits[at.role].push({ index: at.index, remove: true }); continue; }
       const role = state.archived || ['done', 'cancelled'].includes(state.stage ?? task.status) ? 'archived' : 'open';
+      // Its ended subtasks: each its own entry in the archive document while the card is open (the open document lists
+      // only what is still to do); back in the card's own text once the card has ended.
+      for (const sub of this.statement('SELECT t.* FROM main.tasks t JOIN main.supercode_cards s ON s.task_id = t.id WHERE s.subtask_of = ?').all(id)) {
+        const subState = this.one('SELECT * FROM main.supercode_cards WHERE task_id = ?', sub.id) ?? {};
+        const subAt = where.get(sub.id);
+        if (role !== 'open' || !ENDED.has(subState.stage ?? sub.status)) { if (subAt) edits[subAt.role].push({ index: subAt.index, remove: true }); continue; }
+        const subRecord = this.subtaskRecord(sub.id, sub, subState, id, where);
+        const subRec = hash(JSON.stringify(subRecord));
+        if (subAt?.role === 'archived' && subAt.entry.rec === subRec) continue;
+        let subText;
+        try { subText = this.codec.renderBoardCard(subRecord, subAt?.role === 'archived' ? subAt.entry.level : 2, this.docOf('archived').path); }
+        catch (error) { this.errors.set(sub.id, error.message); continue; }
+        const subEntry = { cid: null, id: subRecord.id, level: subAt?.role === 'archived' ? subAt.entry.level : 2, len: subText.length, rec: subRec, text: subText };
+        if (subAt?.role === 'archived') edits.archived.push({ index: subAt.index, entry: subEntry });
+        else { if (subAt) edits[subAt.role].push({ index: subAt.index, remove: true }); edits.archived.push({ entry: subEntry }); }
+      }
       const record = this.recordOf(id, task, state, where);
       const rec = hash(JSON.stringify(record));
       if (at?.role === role && at.entry.rec === rec) continue;
@@ -794,16 +842,23 @@ class ZtrackBoard {
     const keyOf = (x) => this.one('SELECT key FROM main.board_tasks WHERE id = ?', x)?.key ?? null;
     const parse = (record) => this.preset.KanbanRootSchema.parse(this.preset.parseKanban([record])).issues[0];
     const parsed = parse({ id: fileId(id), title: row.title, status: c.stage ?? row.status, assignee: row.assignee || undefined, body: row.body ?? '' });
-    const metadata = Object.fromEntries(Object.entries(row).filter(([k, v]) => !RUNTIME.has(k) && !CARD_MAIN.has(k) && v != null));
+    const metadata = Object.fromEntries(Object.entries(row).filter(([k, v]) => declared(k, v)));
     if (c.archived) metadata.archived = true;
     if (json(c.blocked_by, []).length) metadata.blocked_by = json(c.blocked_by, []);
     const card = { ...parsed, metadata, priority: row.priority ?? 0, workspace: row.workspace_kind + (row.workspace_kind !== 'scratch' && (c.workspace_anchor ?? row.workspace_path) ? `:${c.workspace_anchor ?? row.workspace_path}` : ''),
       branch: row.branch_name || undefined, machine: c.machine || undefined, paused: json(c.paused, null) ?? undefined, every: c.every || undefined,
       // Task lines left in a stored body (create and specify file them as subtasks) stay in its Tasks, before its subtasks.
       relations: json(c.blocked_by, []).map((b) => ({ type: 'blocked-by', issueId: fileId(b.id) })), acceptanceCriteria: [...(parsed.acceptanceCriteria ?? [])] };
-    const rows = this.statement('SELECT t.* FROM main.tasks t JOIN main.supercode_cards s ON s.task_id = t.id WHERE s.subtask_of = ? ORDER BY t.created_at, t.id').all(id);
+    // An open card lists its open subtasks; its ended ones are kept in the archive document (subtaskRecord), so the open
+    // document stays readable and small. An ended card keeps all of them.
+    const cardEnded = c.archived || ENDED.has(c.stage ?? row.status);
+    const all = this.statement('SELECT t.* FROM main.tasks t JOIN main.supercode_cards s ON s.task_id = t.id WHERE s.subtask_of = ? ORDER BY t.created_at, t.id').all(id);
+    const rows = all.filter((r) => cardEnded || !ENDED.has(this.one('SELECT stage FROM main.supercode_cards WHERE task_id = ?', r.id)?.stage ?? r.status));
     const states = new Map(rows.map((r) => [r.id, this.one('SELECT * FROM main.supercode_cards WHERE task_id = ?', r.id)]));
     const keys = new Map(), taken = new Set(card.acceptanceCriteria.map((task) => task.id));
+    // An ended subtask, kept in the archive, still holds its key: a new one never takes it, so a line can never be bound
+    // back to a finished subtask by a reused key.
+    for (const r of all) { if (rows.includes(r)) continue; const key = keyOf(r.id)?.split(':').at(-1) ?? /^([a-z]+\d+)\s/.exec(r.title)?.[1]; if (key) taken.add(key); }
     for (const r of rows) { const key = keyOf(r.id)?.split(':').at(-1) ?? /^([a-z]+\d+)\s/.exec(r.title)?.[1]; if (key && !taken.has(key)) { keys.set(r.id, key); taken.add(key); } }
     for (const r of rows) {
       if (keys.has(r.id)) continue;
@@ -818,10 +873,10 @@ class ZtrackBoard {
       const task = parse({ id: r.id, title: r.title, status, body: r.body ?? '' });
       const blocks = json(s.blocked_by, []);
       const messages = blocks.filter((block) => block.kind === 'message');
-      card.acceptanceCriteria.push({ sources: json(stored?.sources, undefined) ?? undefined, id: key, status: ['done', 'cancelled'].includes(status) ? 'passed' : 'pending', evidence: [], text: match?.[2] ?? r.title,
-        metadata: { id: r.id, status, body: task.body, assignee: r.assignee, machine: s.machine,
-          properties: Object.fromEntries(Object.entries(r).filter(([k, v]) => !RUNTIME.has(k) && !CARD_MAIN.has(k) && v != null)),
-          card: { paused: json(s.paused, null) ?? undefined, every: s.every || undefined, archived: s.archived ? true : undefined } }, lines: task.acceptance,
+      // A subtask is its line and its brief (its body, as Markdown under it); its id, status words, assignee and run
+      // output stay in the store (company RFC 0025 decision 4).
+      card.acceptanceCriteria.push({ sources: json(stored?.sources, undefined) ?? undefined, id: key, status: ENDED.has(status) ? 'passed' : 'pending', evidence: [], text: match?.[2] ?? r.title,
+        ...(task.body ? { brief: task.body } : {}), lines: task.acceptance,
         waitingOn: messages[0]?.id,
         blockedBy: blocks.filter((block) => block !== messages[0]).map((block) => {
           const target = keyOf(block.id);
@@ -834,6 +889,16 @@ class ZtrackBoard {
     return { id: card.id, title: card.title, status: card.status, ...(card.assignee ? { assignee: card.assignee } : {}), body: serialized.body };
   }
 
+  // An ended subtask's own record in the archive document: its title and brief, and the card it belongs to.
+  subtaskRecord(id, task, state, parentId, where) {
+    const fileId = (x) => where.get(x)?.entry.id ?? x;
+    const parsed = this.preset.KanbanRootSchema.parse(this.preset.parseKanban([{ id: fileId(id), title: task.title, status: state.stage ?? task.status, assignee: task.assignee || undefined, body: task.body ?? '' }])).issues[0];
+    const metadata = { subtask_of: fileId(parentId), ...Object.fromEntries(Object.entries(task).filter(([k, v]) => declared(k, v))) };
+    const card = { ...parsed, metadata, machine: state.machine || undefined, relations: [] };
+    const serialized = this.preset.serializeKanbanCard(card);
+    return { id: card.id, title: card.title, status: card.status, ...(card.assignee ? { assignee: card.assignee } : {}), body: serialized.body };
+  }
+
   // ------------------------------------------------------------------ migration from a SQLite board
 
   indexForSeed() {

package/gates.mjs

@@ -68,6 +68,9 @@ export function scriptTimeoutSeconds(profile, env = process.env) {
 function scriptEnv() {
   const env = {};
   for (const k of ['PATH', 'HOME', 'LANG', 'LC_ALL', 'TZ', 'TMPDIR', 'USER', 'SHELL']) if (process.env[k] !== undefined) env[k] = process.env[k];
+  // A script's `supercode` is the one this daemon runs, as an agent worker's is: its folder leads PATH
+  const own = process.env.SUPERCODE_BIN ? dirname(process.env.SUPERCODE_BIN) : null;
+  if (own) env.PATH = [own, ...(env.PATH ?? '').split(':').filter(dir => dir && dir !== own)].join(':');
   return env;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-orchestrator",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "type": "module",
   "description": "The orchestrator runtime over the Volter Harness ontology: one typed operational model whose folder is its serialization, read and written through the harness orchestration doors (docs/ORCHESTRATOR-IR.md)",
   "exports": {
@@ -25,9 +25,9 @@
   },
   "dependencies": {
     "@volter/supercode-harness-sdk": "^0.3.41",
-    "@volter/ztrack": "^2.4.21",
+    "@volter/ztrack": "^2.4.23",
     "yaml": "^2.9.0",
-    "@volter/teams": "0.2.1"
+    "@volter/teams": "0.2.2"
   },
   "devDependencies": {
     "@chat-adapter/state-memory": "4.39.0",