@volter/supercode-orchestrator 0.5.207 → 0.5.208

package/board/ztrack.mjs

@@ -1,3 +1,4 @@
+import { fillReadableIds, validateReadableId } from './readable-id.mjs';
 // The document is card state. One SQLite file beside it keeps the runtime tables the engine speaks
 // and an index of the document's card spans. ADR 0001 and 0003.
 // All markdown interpretation belongs to ztrack's public codec and kanban preset.
@@ -18,7 +19,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { existsSync, linkSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
-import { actorOf, CARD_NUMBERS, contention, raiseCardNumbers, event, json, now, principalOf, storageFault, STORAGE_TRIES, unreadable } from './store.mjs';
+import { actorOf, boardKey, CARD_NUMBERS, contention, raiseCardNumbers, event, json, now, principalOf, storageFault, STORAGE_TRIES, unreadable } from './store.mjs';
 import { GitDocument } from './git-document.mjs';
 import { unimported } from './legacy-store.mjs';
 import { noteStep, recordSlow } from '@volter/supercode-harness-sdk/slow-log';
@@ -104,9 +105,10 @@ const ARCHIVE_LINES = 2000;
 // document changed while it was read (readSnapshot).
 const SNAPSHOT_TRIES = 8;
 const isArchive = (role) => role === 'archived' || String(role ?? '').startsWith('archived:');
-// The open document's record of the numbers the board has given (numberMark), and a task line's number (`- [ ] #2836 c3`).
-const NUMBER_MARK = /^The board has given card numbers up to #(\d+)\.[ \t]*$/m;
-const TASK_NUMBER = /^\s*[-*] \[[ xX]\]\s+#(\d+)\s+[a-z]+\d+\s/gm;
+// The open document's record of the numbers the board has given (numberMark: its key, its number), and a task line's
+// number (`- [ ] VO-2836 c3`); either written keyed, or with `#` as before a board read its numbers with a key.
+const NUMBER_MARK = /^The board has given card numbers up to (?:#|([A-Z][A-Z0-9]+)-)(\d+)\.[ \t]*$/m;
+const TASK_NUMBER = /^\s*[-*] \[[ xX]\]\s+(?:#|[A-Z][A-Z0-9]+-)(\d+)\s+[a-z]+\d+\s/gm;
 
 const BOARD_TABLES = `
 CREATE TABLE IF NOT EXISTS board_state (key TEXT PRIMARY KEY, value TEXT NOT NULL);
@@ -136,7 +138,7 @@ export function openZtrackBoard(marker, { create = false, document = null, decla
   }
   const config = JSON.parse(read(marker));
   const backing = new ZtrackBoard({ ...config, seed, marker, init, root, slug, held, readOnly });
-  return { db: backing.db, tx: (fn) => backing.tx(fn), publishPending: () => backing.git?.publishPending(), unimported: () => backing.unimported(), close: () => backing.close(), document: backing.path,
+  return { db: backing.db, snapshot: (path) => backing.snapshot(path), tx: (fn) => backing.tx(fn), publishPending: () => backing.git?.publishPending(), unimported: () => backing.unimported(), close: () => backing.close(), document: backing.path,
     documentsChanged: () => backing.documentsChanged(), documentsUnwatched: (unwatched) => { backing.unwatched = unwatched; }, saidOnOpen: () => backing.sayLate() };
 }
 
@@ -213,7 +215,7 @@ class ZtrackBoard {
     }
     // A board's first open in this process recovers what its store accepted and derives what git owes for it (tx), so
     // a board that is only read, or whose owner runs no round, still finishes an earlier process's commit.
-    if (seed || this.git?.underived) this.tx(() => {});
+    if (seed || this.git?.underived || this.get('rebuild_from_documents') || !this.get('task_identities_written') || !this.get('readable_ids_written')) this.tx(() => {});
   }
 
   // A listing's view, taken once at its open and kept until its close: the store's rows as of one read transaction, and
@@ -267,7 +269,7 @@ class ZtrackBoard {
   // state, so a rotation committed but not yet written is still a document of the board).
   get docs() {
     let rotated = [];
-    try { rotated = this.conn ? this.get('archives', []) : []; } catch { rotated = []; }
+    try { rotated = this.conn ? this.get('archives', []) : this.rebuildArchives ?? []; } catch { rotated = []; }
     // recorded by file name, beside the document, so a board moved with its documents still finds them
     return [...this.baseDocs, ...rotated.map(({ role, name }) => ({ role, path: resolve(dirname(this.path), name) }))];
   }
@@ -276,6 +278,14 @@ class ZtrackBoard {
   board() { return { root: this.root, slug: this.slug, label: this.slug, db: this.db }; }
   close() { this.closed = true; this.git?.release(); this.dropOverlay(); this.conn.close(); }
 
+  // Import pending document edits through the backing, then copy the committed
+  // projection outside its write wrapper: SQLite forbids VACUUM inside a tx.
+  snapshot(path) {
+    if (this.active || this.readOnly) throw new Error('board export needs a writable backing outside a transaction');
+    this.tx(() => {});
+    this.conn.prepare('VACUUM INTO ?').run(path);
+  }
+
   statement(sql) {
     let statement = this.statements.get(sql);
     if (!statement) {
@@ -351,6 +361,8 @@ class ZtrackBoard {
 
   // A board created from the previous runtime store imports its rows once; the old file stays as it was.
   create(legacy) {
+    const named = `${basename(this.path)}.archive-`;
+    this.rebuildArchives = existsSync(dirname(this.path)) ? readdirSync(dirname(this.path)).filter(name => name.startsWith(named) && name.endsWith('.md')).sort().map(name => ({ role: `archived:${name.slice(named.length, -3)}`, name })) : [];
     const tmp = `${this.file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
     const db = new DatabaseSync(tmp);
     try {
@@ -362,6 +374,13 @@ class ZtrackBoard {
         this.init(db, { fresh: true });
         db.exec(BOARD_TABLES);
         if (has('runtime_rows')) this.importRuntime(db, old, legacy);
+        // Runtime history is retained, but an old cache is never the current document state. Persist the recovery
+        // marker before installing the store so a crash/reopen also finishes this first full reconciliation.
+        db.prepare('INSERT OR REPLACE INTO board_state VALUES (?, ?)').run('archives', JSON.stringify(this.rebuildArchives));
+        if (!this.seed) {
+          db.prepare('INSERT OR REPLACE INTO board_state VALUES (?, ?)').run('rebuild_from_documents', 'true');
+          db.prepare('INSERT OR REPLACE INTO board_state VALUES (?, ?)').run('published', '{}');
+        }
       } finally { old?.close(); }
       db.close();
     } catch (error) {
@@ -564,14 +583,25 @@ class ZtrackBoard {
         }
         if (this.seed) this.seedRows();
         timedStep('board tx snapshot', () => this.snapshotHeld());
+        fillReadableIds(this.db);
         const result = timedStep('board tx body', () => fn(this.db));
+        fillReadableIds(this.db);
         if (this.contended) throw RETRY;
-        // The first write made with a codec that renders numbers (numbersRendered) after the store numbered its cards
-        // (store.mjs layOutNumbers) writes every card of the open document again, with its number in its heading and each
-        // open subtask's on its task line; a card made since is written with its number when it is made.
-        if (this.numbersRendered && !this.stateText('numbers_written')) {
+        // The first write made with a codec that renders keyed numbers (numbersRendered) once the store numbered its
+        // cards (store.mjs layOutNumbers) writes every card of the open document again, with its keyed number in its
+        // heading and each open subtask's on its task line, and again whenever the board's key changes (a renamed home);
+        // a card made since is written with its number when it is made. `numbers_written` is the key last written.
+        if (this.numbersRendered && (this.numberForm === 'keyed' ? this.get('numbers_written') !== this.cardKey : !this.get('numbers_written'))) {
           this.statement('INSERT INTO temp.board_touched SELECT value FROM json_each(?)').run(JSON.stringify(this.entries('open').filter((e) => e.id).map((e) => nativeId(e.id))));
-          this.put('numbers_written', true);
+          this.put('numbers_written', this.numberForm === 'keyed' ? this.cardKey : true);
+        }
+        if (!this.get('readable_ids_written')) {
+          this.conn.exec('INSERT INTO temp.board_touched SELECT id FROM main.tasks');
+          this.put('readable_ids_written', true);
+        }
+        if (!this.get('task_identities_written')) {
+          this.conn.exec('INSERT INTO temp.board_touched SELECT DISTINCT subtask_of FROM main.supercode_cards WHERE subtask_of IS NOT NULL');
+          this.put('task_identities_written', true);
         }
         const files = timedStep('board tx render', () => this.render());
         const intent = files.length ? randomBytes(16).toString('hex') : null;
@@ -797,7 +827,7 @@ class ZtrackBoard {
   // while its card was not rendered, as under a recorded refusal): it takes the store's value, and the card's
   // render writes that back into its lines (t_f3f102db).
   checkControls(plan, resolveRef) {
-    if (!this.one('SELECT 1 FROM main.tasks LIMIT 1')) return;
+    if (this.get('rebuild_from_documents') || !this.one('SELECT 1 FROM main.tasks LIMIT 1')) return;
     let fields = [];
     try { fields = workflowFor(this.root).params.document_control_fields ?? []; } catch { /* no home policy */ }
     if (!fields.length) return;
@@ -856,9 +886,17 @@ class ZtrackBoard {
       this.dropOverlay();
       this.conn.exec('CREATE TEMP TABLE tasks AS SELECT * FROM main.tasks; CREATE TEMP TABLE supercode_cards AS SELECT * FROM main.supercode_cards; CREATE TEMP TABLE task_links AS SELECT * FROM main.task_links');
       this.conn.exec(TASK_SUMMARY_INDEX_SQL.replace(TASK_SUMMARY_INDEX, `temp.${TASK_SUMMARY_INDEX}`));
+      this.conn.exec("CREATE UNIQUE INDEX temp.supercode_open_readable_ids ON tasks(readable_id) WHERE status NOT IN ('done','cancelled','archived')");
       this.overlay = true; this.statements.clear();
     }
-    const initial = !overlay && !this.one('SELECT 1 FROM main.tasks LIMIT 1');
+    const rebuilding = !overlay && this.get('rebuild_from_documents');
+    const initial = !overlay && (rebuilding || !this.one('SELECT 1 FROM main.tasks LIMIT 1'));
+    if (rebuilding) {
+      if (plan.errors.size) throw new Error(`cannot rebuild board from invalid documents: ${[...plan.errors].map(([id, why]) => `${id}: ${why}`).join('; ')}`);
+      // The imported cache can predate cards added, edited or removed in the documents. Keep its history, not its
+      // obsolete card state. Every document was re-read, including unchanged archive spans.
+      for (const { id } of this.statement('SELECT id FROM main.tasks').all()) if (!plan.rows.has(id)) plan.remove.add(id);
+    }
     const by = 'document-editor';
     const events = [];
     const fingerprintOf = (id) => {
@@ -875,6 +913,7 @@ class ZtrackBoard {
     // heading or task line says, and hands out none at or below any number the documents name. Any other import keeps
     // the store's numbers: a number typed into a heading or pasted with a section changes nothing.
     if (initial) {
+      if (rebuilding) this.conn.exec(`DELETE FROM ${CARD_NUMBERS}`);
       this.numberFromHeadings([...plan.numbers].filter(([id]) => plan.rows.has(id)));
       raiseCardNumbers(this.conn, this.documentNumbers().highest);
     }
@@ -884,6 +923,10 @@ class ZtrackBoard {
       const oldState = this.one(`SELECT * FROM ${schema}.supercode_cards WHERE task_id = ?`, id) ?? {};
       this.replace(schema, 'tasks', { ...oldTask, ...rows.task }, 'id');
       this.replace(schema, 'supercode_cards', { ...oldState, ...rows.state }, 'task_id');
+      if (rebuilding && ENDED.has(rows.state.stage ?? rows.task.status) && oldTask.current_run_id) {
+        this.statement("UPDATE main.task_runs SET ended_at = COALESCE(ended_at, ?), status = 'reclaimed', outcome = COALESCE(outcome, 'reclaimed') WHERE id = ? AND ended_at IS NULL").run(now(), oldTask.current_run_id);
+        this.statement('UPDATE main.tasks SET current_run_id = NULL, claim_lock = NULL, claim_expires = NULL, worker_pid = NULL WHERE id = ?').run(id);
+      }
       this.statement(`DELETE FROM ${schema}.task_links WHERE child_id = ?`).run(id);
       for (const b of json(rows.state.blocked_by, []).filter((b) => b.kind === 'card')) this.statement(`INSERT OR IGNORE INTO ${schema}.task_links (parent_id, child_id) VALUES (?, ?)`).run(b.id, id);
       const after = fingerprintOf(id);
@@ -894,7 +937,11 @@ class ZtrackBoard {
     }
     for (const id of plan.checked) this.errors.delete(id);
     for (const [id, reason] of plan.errors) this.errors.set(id, reason);
+    // A read overlays new document cards before the owner commits them. Give that
+    // connection-local view the same names as the subsequent write.
+    fillReadableIds(this.conn);
     if (overlay) return;
+    if (rebuilding) this.drop('rebuild_from_documents');
     for (const id of plan.errors.keys()) this.refused.add(this.one('SELECT subtask_of FROM main.supercode_cards WHERE task_id = ?', id)?.subtask_of ?? id);
     for (const [tid, { key, sources }] of plan.tasks) this.statement('INSERT OR REPLACE INTO main.board_tasks (id, key, sources) VALUES (?, ?, ?)').run(tid, key, sources?.length ? JSON.stringify(sources) : null);
     for (const id of [...plan.checked, ...plan.rows.keys()]) if (!plan.errors.has(id)) this.statement('DELETE FROM main.board_errors WHERE id = ?').run(id);
@@ -941,7 +988,7 @@ class ZtrackBoard {
     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) || RUN_OUTPUT.has(k)));
-    const task = { ...meta, ...runtime, id, title: card.title, body: stored.body,
+    const task = { ...meta, ...runtime, id, title: card.title, readable_id: meta.readable_id == null ? old.readable_id ?? null : validateReadableId(meta.readable_id), 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 };
     const state = { task_id: id, workspace_anchor: workspace?.[2] ?? null, stage: card.status, machine: card.machine ?? null, subtask_of: parent,
@@ -950,6 +997,7 @@ class ZtrackBoard {
       // carried it (or edited without it) is not an unarchive. Saying `archived: false` of an archived card is.
       paused: card.paused ? JSON.stringify(card.paused) : null, every: card.every ?? null,
       archived: (meta.archived ?? card.archived) === undefined ? Number(this.one('SELECT archived FROM main.supercode_cards WHERE task_id = ?', id)?.archived ?? 0) : ((meta.archived ?? card.archived) ? 1 : 0) };
+    if (!state.archived && !ENDED.has(card.status)) task.status = card.paused ? 'paused' : card.relations?.length ? 'blocked' : card.status;
     return { task, state };
   }
 
@@ -958,17 +1006,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')}`;
-      // 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);
+      // The native identity and declared state travel with the line. Runtime history stays in the store, joined by
+      // this same identity, including when that store was rebuilt from a cache older than the subtask.
+      const stored = this.one('SELECT * FROM main.tasks WHERE id = ?', tid);
+      const storedState = 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 } : {}),
+      const taskCard = { ...(storedState ? { paused: json(storedState.paused, null) ?? undefined, every: storedState.every || undefined } : {}), ...task.metadata?.card,
         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 ?? [],
+        assignee: task.metadata && 'assignee' in task.metadata ? task.metadata.assignee : stored?.assignee ?? card.assignee,
+        machine: task.metadata && 'machine' in task.metadata ? 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, task.number];
@@ -1156,9 +1204,13 @@ 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');
-      // 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).
+      // Keep the identity-to-number binding and declared state durable with its line; a stale runtime cache cannot
+      // supply these for a newer subtask. Run output, clocks and active claims remain the runtime store's.
       card.acceptanceCriteria.push({ sources: json(stored?.sources, undefined) ?? undefined, id: key, ...this.numberOf(r.id), status: ENDED.has(status) ? 'passed' : 'pending', evidence: [], text: match?.[2] ?? r.title,
+        metadata: { id: r.id, status, assignee: r.assignee, machine: s.machine,
+          properties: Object.fromEntries(Object.entries(r).filter(([k, v]) => declared(k, v))),
+          card: { priority: r.priority ?? 0, workspace: r.workspace_kind + (r.workspace_kind !== 'scratch' && (s.workspace_anchor ?? r.workspace_path) ? `:${s.workspace_anchor ?? r.workspace_path}` : ''),
+            branch: r.branch_name || undefined, paused: json(s.paused, null) ?? undefined, every: s.every || undefined } },
         ...(task.body ? { brief: task.body } : {}), lines: task.acceptance,
         waitingOn: messages[0]?.id,
         blockedBy: blocks.filter((block) => block !== messages[0]).map((block) => {
@@ -1172,27 +1224,36 @@ class ZtrackBoard {
     return { id: card.id, ...this.numberOf(id), title: card.title, status: card.status, ...(card.assignee ? { assignee: card.assignee } : {}), body: serialized.body };
   }
 
-  // A card's number, shown first in its heading (`## #42 t_… — …`): the store's (store.mjs layOutNumbers). An edit to a
-  // heading's number changes nothing; a store made again from its documents takes it back (numberFromHeadings). A card's
-  // record keeps the key where the document codec reads it, after the id.
+  // A card's number, shown first in its heading with its board's key (`## VO-42 t_… — …`): the store's (store.mjs
+  // layOutNumbers, boardKey). An edit to a heading's number changes nothing; a store made again from its documents takes
+  // it back (numberFromHeadings). A card's record keeps the number and key where the document codec reads them, after
+  // the id.
   numberOf(id) {
     if (!this.numbersRendered) return {};
     const number = this.one(`SELECT number FROM main.${CARD_NUMBERS} WHERE task_id = ?`, id)?.number;
-    return number ? { number } : {};
+    return number ? { number, ...(this.numberForm === 'keyed' ? { key: this.cardKey } : {}) } : {};
   }
 
-  // Whether the document codec (@volter/ztrack) writes a card's number in its heading and a subtask's on its task
-  // line. One that does not renders, reads and indexes cards as it always did; the open document is written with the
-  // numbers by the first write made with one that does (tx), whichever was installed first.
-  get numbersRendered() {
-    if (this._numbersRendered === undefined) {
-      try {
-        const task = this.preset.serializeKanbanCard({ id: 't-00000000', title: 'number', summary: '', status: 'todo', body: '', acceptanceCriteria: [{ id: 'c1', number: 2, status: 'pending', evidence: [], text: 'number' }] }).body;
-        this._numbersRendered = this.codec.renderBoardCard({ id: 't_00000000', number: 1, title: 'number', status: 'todo', body: '' }, 2).startsWith('## #1 t_00000000 ') && task.includes('- [ ] #2 c1 number');
-      } catch { this._numbersRendered = false; }
+  /** The board's key (store.mjs boardKey). */
+  get cardKey() { return this._cardKey ??= boardKey(this.root, this.slug); }
+
+  // How the document codec (@volter/ztrack) writes a card's number in its heading and a subtask's on its task line:
+  // `keyed` (`VO-42`), `plain` (`#42`, a codec from before numbers were keyed), or null (none). One that writes none
+  // renders, reads and indexes cards as it always did; the open document is written with the numbers in the codec's form
+  // by the first write made with it (tx), whichever was installed first.
+  get numberForm() {
+    if (this._numberForm === undefined) {
+      const writes = (key, mark) => {
+        try {
+          const task = this.preset.serializeKanbanCard({ id: 't-00000000', title: 'number', summary: '', status: 'todo', body: '', acceptanceCriteria: [{ id: 'c1', number: 2, ...(key ? { key } : {}), status: 'pending', evidence: [], text: 'number' }] }).body;
+          return this.codec.renderBoardCard({ id: 't_00000000', number: 1, ...(key ? { key } : {}), title: 'number', status: 'todo', body: '' }, 2).startsWith(`## ${mark}1 t_00000000 `) && task.includes(`- [ ] ${mark}2 c1 number`);
+        } catch { return false; }
+      };
+      this._numberForm = writes('KB', 'KB-') ? 'keyed' : writes(null, '#') ? 'plain' : null;
     }
-    return this._numbersRendered;
+    return this._numberForm;
   }
+  get numbersRendered() { return this.numberForm !== null; }
 
   // Give each card the number its document gives it (its heading, or its task line), where no other card holds that
   // number and the card has none yet; the numbers' high-water mark rises with them, so none is handed out again. Only
@@ -1200,7 +1261,12 @@ class ZtrackBoard {
   numberFromHeadings(numbers, db = this.conn) {
     if (!numbers.length) return;
     const give = db.prepare(`INSERT INTO ${CARD_NUMBERS} (number, task_id) SELECT ?, ? WHERE NOT EXISTS (SELECT 1 FROM ${CARD_NUMBERS} WHERE task_id = ? OR number = ?)`);
-    for (const [id, number] of numbers) give.run(number, id, id, number);
+    const holder = db.prepare(`SELECT task_id FROM ${CARD_NUMBERS} WHERE number = ?`);
+    for (const [id, number] of numbers) {
+      const other = holder.get(number)?.task_id;
+      if (other && other !== id) throw new Error(`cannot rebuild card numbers: ${number} names both ${other} and ${id}`);
+      give.run(number, id, id, number);
+    }
     raiseCardNumbers(db);
   }
 
@@ -1216,7 +1282,7 @@ class ZtrackBoard {
     for (const path of [this.path, this.archive, ...rotated]) {
       const text = lf(read(path));
       for (const line of text.matchAll(TASK_NUMBER)) highest = Math.max(highest, Number(line[1]));
-      if (path === this.path) highest = Math.max(highest, Number(NUMBER_MARK.exec(text)?.[1] ?? 0));
+      if (path === this.path) highest = Math.max(highest, Number(NUMBER_MARK.exec(text)?.[2] ?? 0));
       let records = [];
       try { ({ records } = this.codec.inspectBoardDocument(text, path)); } catch { continue; }
       for (const record of records) {
@@ -1234,16 +1300,17 @@ class ZtrackBoard {
   numberMark() {
     const given = Number(this.one('SELECT seq FROM main.sqlite_sequence WHERE name = ?', CARD_NUMBERS)?.seq ?? 0);
     if (!given) return null;
-    const line = `The board has given card numbers up to #${given}.`;
+    const keyed = this.numberForm === 'keyed';
+    const line = (top) => `The board has given card numbers up to ${keyed ? `${this.cardKey}-` : '#'}${top}.`;
     const first = this.entries('open')[0];
     if (first && first.id === null) {
       const text = this.texts([first])[0].text;
       const said = NUMBER_MARK.exec(text);
-      if (said && Number(said[1]) >= given) return null;
-      const next = said ? text.replace(NUMBER_MARK, line) : `${text.replace(/\n*$/, '')}\n\n${line}\n\n`;
+      if (said && (keyed ? said[1] === this.cardKey : said[1] === undefined) && Number(said[2]) >= given) return null;
+      const next = said ? text.replace(NUMBER_MARK, line(Math.max(given, Number(said[2])))) : `${text.replace(/\n*$/, '')}\n\n${line(given)}\n\n`;
       return { index: 0, entry: { cid: null, id: null, level: 0, len: next.length, rec: null, text: next } };
     }
-    const text = `${line}\n\n`;
+    const text = `${line(given)}\n\n`;
     return { prepend: true, entry: { cid: null, id: null, level: 0, len: text.length, rec: null, text } };
   }
 

package/codex-pane-resume.mjs

@@ -0,0 +1 @@
+export { projectCodexPaneResume } from '@volter/supercode-teams/codex-pane-resume';

package/connection.mjs

@@ -1,5 +1,5 @@
 // The kit's connection coordinator. Module manifests and programs belong to their application publisher.
-import { chmodSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { createHash, randomBytes } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -7,7 +7,15 @@ import { spawn } from 'node:child_process';
 import { fromContext } from '@volter/teams/context';
 import { supercodeHome } from '@volter/teams/home';
 
+// RH2's modules, each its own program under --modules-root.
 export const MODULE_APPS = ['arcs-rooms','orchestration-rh2'];
+// supercode's Workplace service's registrations (supercode ADR 0041 decision 3; runhuman-2 ADR 0055 decision 3): one program,
+// sdk/teams/workplace/main.mjs, hosts them all, each with its own credentials on both sides. Their manifests ship here, so an
+// organization's file selects them by these names and `rh2 apply-org` reads them with --modules-root SERVICE_REGISTRATIONS.
+export const SERVICE_APPS = ['agents','cards','machines'];
+export const SERVICE_REGISTRATIONS = fileURLToPath(new URL('../teams/workplace/registrations/', import.meta.url));
+export const SERVICE_PROGRAM = fileURLToPath(new URL('../teams/workplace/main.mjs', import.meta.url));
+const SERVICE_TOKENS = { agents: ['AGENTS_WORKPLACE_TOKEN','AGENTS_TEAMS_TOKEN'], cards: ['CARDS_WORKPLACE_TOKEN','CARDS_TEAMS_TOKEN'], machines: ['MACHINES_WORKPLACE_TOKEN','MACHINES_TEAMS_TOKEN'] };
 export function privateJson(path, value) {
   mkdirSync(dirname(path),{recursive:true,mode:0o700});
   const pending=`${path}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
@@ -16,37 +24,30 @@ export function privateJson(path, value) {
 export async function connectionCall(record, side, method, path, body, token) {
   const origin=side==='teams'?record.teams.server:record.origin;
   // Registration, consent, exchange and renewal have receiver-staged random values in their bodies:
-  // their digest is one operation's key, retained on a retry. A lease refresh is a new operation even
-  // with the same keys/results. Keep its key in custody until an answer is received.
-  const lease=side==='teams'&&method==='POST'&&path.endsWith('/issuer-keyring');
-  let operationKey;
-  if(lease){
-    const digest=createHash('sha256').update(JSON.stringify(body)).digest('hex');
-    if(record.issuerKeyOperation?.digest!==digest)record.issuerKeyOperation={digest,key:`connect-${randomBytes(24).toString('hex')}`};
-    operationKey=record.issuerKeyOperation.key;
-    privateJson(connectionPath(record.root,record.id),record);
-  }
+  // their digest is one operation's key, retained on a retry.
   const began=Date.now();
-  const response=await fetch(`${origin}${path}`,{method,redirect:'manual',signal:AbortSignal.timeout(path.endsWith('issuer-checks')?30000:9000),
+  const response=await fetch(`${origin}${path}`,{method,redirect:'manual',signal:AbortSignal.timeout(9000),
     headers:{accept:'application/json',...(token?{authorization:`Bearer ${token}`} : {}),
       ...(side==='rh2'?{origin:record.origin,'x-rh2-organization':record.organization}:{}),
       ...(body===undefined?{}:{'content-type':'application/json'}),
-      ...(['POST','PATCH','DELETE'].includes(method)?{'idempotency-key':operationKey??`connect-${createHash('sha256').update(`${method}\n${path}\n${JSON.stringify(body)}`).digest('hex')}`}:{})},
+      ...(['POST','PATCH','DELETE'].includes(method)?{'idempotency-key':`connect-${createHash('sha256').update(`${method}\n${path}\n${JSON.stringify(body)}`).digest('hex')}`}:{})},
     ...(body===undefined?{}:{body:JSON.stringify(body)})});
   const text=await response.text();
   record.calls??=[];record.calls.push({side,method,path,status:response.status,ms:Date.now()-began,bytes:Buffer.byteLength(text)});record.calls=record.calls.slice(-200);
-  let payload;try{payload=JSON.parse(text);}catch{throw new Error(`${side} ${method} ${path}: invalid JSON (${response.status})`);}
+  let payload;try{payload=text===''&&response.status===204?{}:JSON.parse(text);}catch{throw new Error(`${side} ${method} ${path}: invalid JSON (${response.status})`);}
   if(!response.ok)throw Object.assign(new Error(`${side} ${method} ${path}: ${payload.error?.code??response.status}`),{code:payload.error?.code,status:response.status});
-  if(lease){delete record.issuerKeyOperation;privateJson(connectionPath(record.root,record.id),record);}
   return payload;
 }
 export function connectionPath(root,id){return join(root,'apps','connections',id,'connection.json');}
 export function generateModuleConfig(root, record, grant) {
+  if(SERVICE_APPS.includes(grant.name))return generateServiceConfig(root,record,grant);
   const folder=dirname(connectionPath(root,record.id)), dir=join(folder,grant.name);
   mkdirSync(dir,{recursive:true,mode:0o700});
   const custody=join(dir,'credentials.env'), configPath=join(dir,'config.json');
   writeFileSync(custody,`RH2_TOKEN=${grant.rh2.accessToken}\n${grant.teams?`TEAMS_TOKEN=${grant.teams.credential.token}\n`:''}`,{mode:0o600});chmodSync(custody,0o600);
-  const config={rh2:{baseUrl:record.origin,issuer:record.issuer,organization:record.organization,principalId:grant.rh2.principalId,tokenEnv:'RH2_TOKEN'},
+  // The arcs module seats card agents by resolving them in the registration that provides them: the connection's agents.
+  const agents=record.grants.find(g=>g.name==='agents'&&g.clientId), cards=record.grants.find(g=>g.name==='cards'&&g.rh2);
+  const config={rh2:{baseUrl:record.origin,issuer:record.issuer,organization:record.organization,principalId:grant.rh2.principalId,tokenEnv:'RH2_TOKEN',...(agents?{agentsRegistration:agents.clientId}:{}),...(cards?{cardsPrincipalId:cards.rh2.principalId}:{})},
     teams:{server:record.teams.server,team:record.teams.team,source:record.source,tokenEnv:'TEAMS_TOKEN'},
     envFile:custody,stateFile:join(dir,'state.json'),defaultFloor:record.floor,
     source:{key:`connection-${record.scope}`,namespace:`cx${record.scope}`,name:`${record.organization} / ${record.source}`,home:root,...(record.teamsContext?{teamsContext:record.teamsContext}:{}),...(process.env.SUPERCODE_BIN?{program:process.env.SUPERCODE_BIN}:{}),harness:record.harness??'hermes'},
@@ -56,6 +57,30 @@ export function generateModuleConfig(root, record, grant) {
     origin:record.origin,organizationId:record.organization,principalId:grant.rh2.principalId,installationId:grant.rh2.installationId,expiresAt:grant.rh2.expiresAt});
   return configPath;
 }
+/** The Workplace service's config and custody, written from the connection alone (no hand-written config): every installed
+ * service registration's credentials, ids and state, and the home's registry entry for `grant`. One config serves all. */
+export function generateServiceConfig(root, record, grant) {
+  const folder=dirname(connectionPath(root,record.id)), dir=join(folder,'service');
+  mkdirSync(dir,{recursive:true,mode:0o700});
+  const custody=join(dir,'credentials.env'), configPath=join(dir,'config.json');
+  const held=Object.fromEntries(record.grants.filter(g=>SERVICE_APPS.includes(g.name)&&g.rh2&&g.teams).map(g=>[g.name,g]));
+  writeFileSync(custody,Object.entries(held).map(([name,g])=>`${SERVICE_TOKENS[name][0]}=${g.rh2.accessToken}\n${SERVICE_TOKENS[name][1]}=${g.teams.credential.token}\n`).join(''),{mode:0o600});chmodSync(custody,0o600);
+  const agents=held.agents;
+  if(agents){
+    const section=name=>({registration:held[name].clientId,principal:held[name].rh2.principalId,tokenEnv:SERVICE_TOKENS[name][0],teamsTokenEnv:SERVICE_TOKENS[name][1],stateFile:join(dir,`${name}.state.json`)});
+    const config={
+      teams:{server:record.teams.server,team:record.teams.team,installation:agents.teams.installation.id,source:record.source,tokenEnv:SERVICE_TOKENS.agents[1]},
+      rh2:{baseUrl:record.origin,organization:record.organization,registration:agents.clientId,...(record.issuer!==record.origin?{issuer:record.issuer}:{}),tokenEnv:SERVICE_TOKENS.agents[0],principal:agents.rh2.principalId},
+      source:{namespace:`cx${record.scope}`},envFile:custody,stateFile:join(dir,'agents.state.json'),
+      ...(record.webhook?{webhook:record.webhook}:{}),
+      ...(held.cards?{cards:section('cards')}:{}),...(held.machines?{machines:section('machines')}:{}),
+    };
+    privateJson(configPath,config);
+  }
+  privateJson(join(root,'apps',`${grant.name}.${record.id}.json`),{app:grant.name,connection:record.id,configPath,program:SERVICE_PROGRAM,
+    origin:record.origin,organizationId:record.organization,principalId:grant.rh2.principalId,installationId:grant.rh2.installationId,expiresAt:grant.rh2.expiresAt});
+  return configPath;
+}
 export function startConnectionRunner(root,id) {
   const recordPath=connectionPath(root,id);
   if(!existsSync(recordPath)||!connectionCanRun(JSON.parse(readFileSync(recordPath,'utf8'))))return null;
@@ -63,12 +88,18 @@ export function startConnectionRunner(root,id) {
   const child=spawn(process.execPath,[fileURLToPath(new URL('./bin/connection-runner.mjs',import.meta.url)),'--root',root,'--connection',id],{detached:true,stdio:['ignore',fd,fd],env:process.env});
   closeSync(fd);child.unref();return child.pid;
 }
-export function connectionCanRun(record){return record.preparing===false&&record.paused===false&&typeof record.connectedAt==='string';}
+export function connectionCanRun(record){return record.preparing===false&&record.paused===false&&typeof record.connectedAt==='string'&&!record.disconnectedAt;}
 export async function connectWorkplace(flags) {
-  if(!flags.root||!flags['ticket-file']||!flags['modules-root']||!flags.source)throw new Error('connect needs --root, --ticket-file, --modules-root and --source (one board event source)');
+  if(!flags.root||!flags['ticket-file']||!flags.source)throw new Error('connect needs --root, --ticket-file and --source (one board event source)');
   const root=resolve(flags.root), ticket=JSON.parse(readFileSync(flags['ticket-file'],'utf8'));
   if(!/^[0-9a-f]{24}$/.test(ticket.scope??''))throw new Error('connection ticket needs a source namespace; apply to a new private output path');
-  if(ticket.version!==1||!Array.isArray(ticket.grants)||!ticket.grants.length||ticket.grants.some(g=>!MODULE_APPS.includes(g.name))||new Set(ticket.grants.map(g=>g.name)).size!==ticket.grants.length)throw new Error('unsupported or duplicate connection modules');
+  if(ticket.version!==1||!Array.isArray(ticket.grants)||!ticket.grants.length||ticket.grants.some(g=>!MODULE_APPS.includes(g.name)&&!SERVICE_APPS.includes(g.name))||new Set(ticket.grants.map(g=>g.name)).size!==ticket.grants.length)throw new Error(`unsupported or duplicate connection apps (connect takes ${[...MODULE_APPS,...SERVICE_APPS].join(', ')})`);
+  const names=ticket.grants.map(g=>g.name);
+  // The service is the agents registration's host: its other registrations run only inside it.
+  if(names.some(name=>name!=='agents'&&SERVICE_APPS.includes(name))&&!names.includes('agents'))throw new Error('cards and machines run in the Workplace service, which the agents registration hosts: select agents too');
+  if(names.some(name=>MODULE_APPS.includes(name))&&!flags['modules-root'])throw new Error(`--modules-root names where ${names.filter(name=>MODULE_APPS.includes(name)).join(' and ')} are`);
+  if(Boolean(flags['webhook-url'])!==Boolean(flags['webhook-listen']))throw new Error('--webhook-url and --webhook-listen go together: where the Workplace sends the agents registration\'s events, and the loopback address the service listens on');
+  const moduleRoot=flags['modules-root']?resolve(flags['modules-root']):null;
   // An explicit local credential input is useful for an owned stack; a normal connect uses its existing Teams context.
   let teams,owner;
   if(flags['teams-token-file']){
@@ -86,9 +117,13 @@ export async function connectWorkplace(flags) {
   const path=connectionPath(root,id),prior=existsSync(path)?JSON.parse(readFileSync(path,'utf8')):null;
   if(!prior&&!(Date.parse(ticket.expiresAt)>Date.now()))throw new Error('connection ticket expired; apply the organization file again');
   const record=prior??{version:1,id,scope:ticket.scope,teamsContext:flags.context??process.env.SUPERCODE_CONTEXT,origin:ticket.origin,issuer:ticket.issuer,organization:ticket.organization,teams,source:flags.source,
-    selection:ticket.grants.map(g=>g.name),moduleRoot:resolve(flags['modules-root']),floor:flags.floor??ticket.floor??'Work',alertRole:flags['alert-role']??'admin',grants:[]};
+    selection:ticket.grants.map(g=>g.name),moduleRoot,...(flags['webhook-url']?{webhook:{url:flags['webhook-url'],listen:flags['webhook-listen']}}:{}),floor:flags.floor??ticket.floor??'Work',alertRole:flags['alert-role']??'admin',grants:[]};
   record.root=root;
-  if(prior&&(record.source!==flags.source||record.moduleRoot!==resolve(flags['modules-root'])||record.selection.join(',')!==ticket.grants.map(g=>g.name).join(',')))throw new Error('the existing connection has different module/source settings; use a new connection ticket before replacing it');
+  if(prior?.disconnectedAt)throw new Error('this connection was disconnected; apply the organization file again for a new ticket');
+  // The service's event address is part of the connection: a different one is a new connection, never silently dropped.
+  const webhook=flags['webhook-url']?{url:flags['webhook-url'],listen:flags['webhook-listen']}:undefined;
+  if(prior&&webhook&&JSON.stringify(prior.webhook??null)!==JSON.stringify(webhook))throw new Error('the existing connection has a different --webhook-url/--webhook-listen; use a new connection ticket before replacing it');
+  if(prior&&(record.source!==flags.source||(record.moduleRoot??null)!==moduleRoot||record.selection.join(',')!==ticket.grants.map(g=>g.name).join(',')))throw new Error('the existing connection has different module/source settings; use a new connection ticket before replacing it');
   const lock=join(dirname(path),'runner.lock');
   if(prior&&existsSync(lock)) {
     const running=JSON.parse(readFileSync(lock,'utf8'));
@@ -106,7 +141,8 @@ export async function connectWorkplace(flags) {
   for(const selected of ticket.grants){
     let grant=record.grants.find(g=>g.name===selected.name);
     if(grant && JSON.stringify([grant.manifest,grant.teamsManifest,grant.rooms])!==JSON.stringify([selected.manifest,selected.teamsManifest,selected.rooms]))throw new Error('existing connection consent differs from the ticket');
-    if(!grant){grant={name:selected.name,rooms:selected.rooms,manifest:selected.manifest,teamsManifest:selected.teamsManifest};record.grants.push(grant);privateJson(path,record);}
+    if(!grant){grant={name:selected.name,clientId:selected.clientId,rooms:selected.rooms,manifest:selected.manifest,teamsManifest:selected.teamsManifest};record.grants.push(grant);privateJson(path,record);}
+    if(SERVICE_APPS.includes(grant.name)&&!selected.teamsManifest)throw new Error(`${grant.name}: its Teams manifest is missing from the ticket (apply with --modules-root naming ${SERVICE_REGISTRATIONS})`);
     if(!grant.rh2){
       const recovering=typeof grant.redemption==='string';
       grant.redemption??=randomBytes(32).toString('base64url');privateJson(path,record);
@@ -136,13 +172,13 @@ export async function connectWorkplace(flags) {
       grant.teams=await connectionCall(record,'teams','POST','/api/v1/apps/token',{app_id:grant.registration.id,app_secret:grant.registration.secret,code:grant.consent.code,redirect_url:selected.teamsManifest.redirect_urls[0],credential_token:grant.stagedCredential});privateJson(path,record);
       delete grant.consent;delete grant.registration.secret;privateJson(path,record);
     }
-    generateModuleConfig(root,record,grant);
+    if(!SERVICE_APPS.includes(grant.name))generateModuleConfig(root,record,grant);
   }
-  if(!record.issuerRegistration){record.issuerStagedSecret??=`sca_${randomBytes(32).toString('base64url')}`;privateJson(path,record);record.issuerRegistration=(await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/apps`,{name:`Workplace issuer (${id.slice(0,8)})`,description:'Installation-scoped outbound delegated trust',actions:['delegation.sessions','delegation.surfaces','delegation.notices','delegation.machines'],event_kinds:[],redirect_urls:['http://127.0.0.1/connected'],issuer:record.issuer,outbound_issuer:true,secret:record.issuerStagedSecret},owner)).data;privateJson(path,record);}
+  // The service's config names every one of its registrations, so it is written once all of them hold credentials.
+  for(const grant of record.grants.filter(g=>SERVICE_APPS.includes(g.name)))generateServiceConfig(root,record,grant);
+  if(!record.issuerRegistration){record.issuerStagedSecret??=`sca_${randomBytes(32).toString('base64url')}`;privateJson(path,record);record.issuerRegistration=(await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/apps`,{name:`Workplace issuer (${id.slice(0,8)})`,description:'The Workplace as a delegated issuer, verified against its JWKS',actions:['delegation.sessions','delegation.surfaces','delegation.notices','delegation.machines'],event_kinds:[],redirect_urls:['http://127.0.0.1/connected'],issuer:record.issuer,secret:record.issuerStagedSecret},owner)).data;privateJson(path,record);}
   if(!record.issuerConsent&&!record.issuerCredential){record.issuerStagedCode??=`sci_${randomBytes(32).toString('base64url')}`;privateJson(path,record);record.issuerConsent=(await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/apps/${record.issuerRegistration.id}/installations`,{redirect_url:'http://127.0.0.1/connected',state:id,code:record.issuerStagedCode},owner)).data;privateJson(path,record);}
   if(!record.issuerCredential){record.issuerStagedCredential??=newInstallationToken();privateJson(path,record);record.issuerCredential=await connectionCall(record,'teams','POST','/api/v1/apps/token',{app_id:record.issuerRegistration.id,app_secret:record.issuerStagedSecret,code:record.issuerStagedCode,redirect_url:'http://127.0.0.1/connected',credential_token:record.issuerStagedCredential});privateJson(path,record);delete record.issuerConsent;delete record.issuerRegistration.secret;privateJson(path,record);}
-  const keys=(await connectionCall(record,'rh2','GET','/.well-known/jwks.json')).keys;
-  await connectionCall(record,'teams','POST',`/api/v1/teams/${encodeURIComponent(teams.team)}/app-installations/${record.issuerCredential.installation.id}/issuer-keyring`,{keys,results:[]},record.issuerCredential.credential.token);
   privateJson(join(dirname(path),'standing.json'),[]);
   record.connectedAt??=new Date().toISOString();
   record.preparing=false;record.paused=Boolean(flags['no-start']);privateJson(path,record);
@@ -150,4 +186,37 @@ export async function connectWorkplace(flags) {
   return {connection:id,root,modules:record.grants.map(g=>g.name),runner:pid,calls:record.calls.map(({side,method,path,status,ms,bytes})=>({side,method,path,status,ms,bytes}))};
 }
 
+/** Undo a connection with its own credentials, no admin needed (runhuman-2 ADR 0055 decision 3): its runner stops, every
+ * installation it holds leaves both sides by itself (each Workplace installation through its own uninstall door, each
+ * Teams installation and the issuer's by deleting itself), and the home's registry entries go. The registrations stay, as
+ * consented apps with no installation; an admin deregisters them. The custody record stays, marked disconnected, for
+ * audit; it can never run again. */
+export async function disconnectWorkplace(flags) {
+  if(!flags.root||!flags.connection)throw new Error('disconnect needs --root and --connection (the id connect printed)');
+  const root=resolve(flags.root), path=connectionPath(root,flags.connection);
+  if(!existsSync(path))throw new Error(`no connection ${flags.connection} in ${root}`);
+  const record=JSON.parse(readFileSync(path,'utf8'));record.root=root;
+  record.paused=true;privateJson(path,record);
+  const lock=join(dirname(path),'runner.lock');
+  if(existsSync(lock)){
+    const running=JSON.parse(readFileSync(lock,'utf8'));
+    try{process.kill(running.pid,'SIGTERM');}catch(error){if(error.code!=='ESRCH')throw error;}
+    for(let waited=0;waited<20000;waited+=250){try{process.kill(running.pid,0);}catch{break;}await new Promise(done=>setTimeout(done,250));}
+  }
+  const team=`/api/v1/teams/${encodeURIComponent(record.teams.team)}`, left=[];
+  const leave=async(name,side,method,door,token)=>{
+    try{await connectionCall(record,side,method,door,side==='rh2'?{}:undefined,token);left.push({name,side,left:true});}
+    catch(error){if(error.status===404||error.code==='installation-unknown'){left.push({name,side,left:true,already:true});}else left.push({name,side,left:false,code:error.code??error.status??error.message});}
+    privateJson(path,record);
+  };
+  for(const grant of record.grants){
+    if(grant.teams?.installation?.id)await leave(grant.name,'teams','DELETE',`${team}/app-installations/${encodeURIComponent(grant.teams.installation.id)}`,grant.teams.credential.token);
+    if(grant.rh2?.installationId)await leave(grant.name,'rh2','POST',`/api/v3/automation/installations/${encodeURIComponent(grant.rh2.installationId)}/uninstall`,grant.rh2.accessToken);
+    const entry=join(root,'apps',`${grant.name}.${record.id}.json`);if(existsSync(entry))unlinkSync(entry);
+  }
+  if(record.issuerCredential?.installation?.id)await leave('issuer','teams','DELETE',`${team}/app-installations/${encodeURIComponent(record.issuerCredential.installation.id)}`,record.issuerCredential.token);
+  record.disconnectedAt=new Date().toISOString();record.left=left;privateJson(path,record);
+  return {connection:record.id,root,left,registrations:[...record.grants.map(g=>g.registration?.id).filter(Boolean),record.issuerRegistration?.id].filter(Boolean)};
+}
+
 export function newInstallationToken(){return `sct_cred_${randomBytes(16).toString('hex')}.${randomBytes(32).toString('base64url')}`;}

package/index.d.ts

@@ -131,7 +131,7 @@ export function agentScope(context?: string): {server: string; org: string; prin
 /** The identity a run starts as without asking Teams; `identity.synced` is false until Teams has its declaration, made later under the same id. */
 /** A local agent: its daemon-minted id, retained intent and assignments. */
 export type LocalAgent = {identity: AgentIdentity; intended: ReturnType<typeof resolveAgentProfile>; assignment: string; assignments: Array<Record<string, unknown>>; org: string};
-export function localCardAgent(options: {root: Path; org: string; server: string; profiles: Record<string, Profile>; profile: string; card: string; role: string; sponsor?: string | null; machine?: string | null; starterSession?: string | null}): LocalAgent & {synced: false};
+export function localCardAgent(options: {root: Path; org: string; server: string; profiles: Record<string, Profile>; profile: string; card: string; role: string; handle?: string | null; readableId?: string | null; machine?: string | null; starterSession?: string | null}): LocalAgent & {synced: false};
 export function localProfileAgent(options: {root: Path; org: string; server: string; profiles: Record<string, Profile>; profile: string; machine?: string | null; agent?: string | null; declarations?: Record<string, unknown>}): LocalAgent & {synced: false};
 export function localForkAgent(options: {root: Path; org: string; server: string; profiles: Record<string, Profile>; parent: string; session: string; name: string; key: string}): LocalAgent;
 /** Hand this home's agent declarations and ends to this machine's daemon, which declares and ends them in Teams. Answers what could not be handed on. */
@@ -349,6 +349,10 @@ export class AgentMailboxBridge {
 }
 
 export class Orchestrator {
+  /** Private local preparation only: no hosted runtime or provider process. */
+  prepareMainPane(options: {directory: string; name: string; resume?: import('@volter/supercode-harness-sdk').SessionLocator | null}): Promise<{
+    ran: string; program: 'codex'; profile: string; cwd: string; arguments: string[]; env: Record<string,string>;
+  }>;
   constructor(o: {
     state: OrchestratorState;
     vault?: Vault;
@@ -485,7 +489,7 @@ export interface OrchestrationImported {
 
 /** Our folder, strict, through `harness.v1.orchestration.load`; the vault is read out of the home's own `.env`. */
 export function load(root: Path): Promise<{ state: OrchestratorState; vault: Vault }>;
-/** Our folder, canonical and byte-stable, through `harness.v1.orchestration.save`. Sends no secret. */
+/** Runtime persistence through `harness.v1.orchestration.save`. Leaves workflow.yaml untouched; sends no secret. */
 export function save(state: OrchestratorState, root?: Path): Promise<void>;
 /** Another harness's home as a state value; `vault_keys` names the `.env` keys it would need. */
 export function compile(from: 'hermes' | 'openclaw', home: Path): Promise<{ state: OrchestratorState; vault_keys: string[] }>;