@smartmemory/compose 0.4.1 → 0.5.1

package/lib/fluid/portfolio.js

@@ -0,0 +1,255 @@
+/**
+ * lib/fluid/portfolio.js — the cross-product aggregator (COMP-FOH FOH-7).
+ *
+ * WHAT THIS IS, AND WHAT IT DELIBERATELY IS NOT
+ * ---------------------------------------------
+ * A consumer-side aggregator that sits ABOVE the provider seam and fans a single
+ * question out across N independently-configured products.
+ *
+ * It is **not** a `FluidProvider` and must not be registered as one. A provider
+ * implies a store, and this has none; and putting fan-out below the seam would
+ * place it under per-workspace capability semantics, where "does this support
+ * recall" stops having a single answer. Members may use different providers —
+ * that is the point of aggregating above the seam rather than below it.
+ *
+ * PARTIALITY IS THE NORMAL CASE
+ * -----------------------------
+ * With N independently-configured products reached over N connections, some
+ * subset being unavailable is the expected steady state, not an error path. The
+ * contract is therefore that **every absent source is NAMED**: a portfolio answer
+ * that quietly covers three products when the user declared five is worse than
+ * no answer, because nothing in it looks wrong.
+ *
+ * The one thing that is an error is EVERY member failing. An empty result set
+ * and a total outage must never be presented identically.
+ */
+
+import { parsePortfolioConfig } from './factory.js';
+import { getFluidWorkspaceId } from '../maya-config.js';
+import { fluidProviderFor } from './factory.js';
+import { KIND, SEMANTIC_CAP } from './provider.js';
+
+/**
+ * Per-member deadline.
+ *
+ * Explicit, and not inherited: the colleague composer's 35s `withDeadline` wraps
+ * only its three findings calls, so there is no ambient whole-turn bound to sit
+ * inside (blueprint C2). A portfolio turn costs one round trip per member with no
+ * server-side batching, so an unbounded member holds the whole turn open.
+ */
+export const MEMBER_DEADLINE_MS = 20_000;
+
+/** How many records a storage-only member contributes when it cannot search. */
+const LISTED_FALLBACK_LIMIT = 25;
+
+/**
+ * @typedef {object} PortfolioSource
+ * @property {string} id    the declared label
+ * @property {string} root  the member's absolute root — carried because two
+ *   products can hold the same handle, and the id alone is a name the user chose
+ *   while the root is what actually disambiguates
+ * @property {import('./provider.js').RecallHit[]} hits
+ * @property {boolean} [listedNotSearched] true when the member could not search
+ *   and these are its records listed, never a synthesized query result
+ */
+
+/**
+ * Construct one provider per declared member, concurrently.
+ *
+ * A member that cannot be opened is an omission, never a thrown turn: the whole
+ * point is that one broken product does not silence the others.
+ *
+ * @param {string} cwd the declaring root
+ * @returns {Promise<{sources: Array<{id, root, provider}>, omissions: string[]}>}
+ */
+export async function openPortfolio(cwd) {
+  const config = parsePortfolioConfig(cwd);
+  if (!config) return { sources: [], omissions: [], declared: 0 };
+
+  const settled = await Promise.allSettled(
+    config.members.map(async (m) => ({ ...m, provider: await fluidProviderFor(m.root) })),
+  );
+
+  const sources = [];
+  const omissions = [];
+  settled.forEach((outcome, i) => {
+    const member = config.members[i];
+    if (outcome.status === 'fulfilled') sources.push(outcome.value);
+    else omissions.push(`${member.id} misconfigured: ${reasonOf(outcome.reason)}`);
+  });
+  return { sources, omissions, declared: config.members.length };
+}
+
+/**
+ * Ask every member the same question.
+ *
+ * @param {{sources: Array<{id, root, provider}>, omissions: string[]}} portfolio
+ * @param {string} query
+ * @param {{deadlineMs?: number, limit?: number}} [opts]
+ * @returns {Promise<{sources: PortfolioSource[], omissions: string[]}>}
+ */
+export async function recallAcrossPortfolio(portfolio, query, opts = {}) {
+  const deadlineMs = opts.deadlineMs ?? MEMBER_DEADLINE_MS;
+  const omissions = [...portfolio.omissions];
+
+  const settled = await Promise.allSettled(
+    portfolio.sources.map((source) => withDeadline(askOne(source, query, opts), deadlineMs, source.id)),
+  );
+
+  const sources = [];
+  settled.forEach((outcome, i) => {
+    const source = portfolio.sources[i];
+    if (outcome.status === 'rejected') {
+      omissions.push(`${source.id} ${classify(outcome.reason)}`);
+      return;
+    }
+    const { hits, listedNotSearched, omission } = outcome.value;
+    if (omission) omissions.push(omission);
+    sources.push({
+      id: source.id,
+      root: source.root,
+      hits,
+      ...(listedNotSearched ? { listedNotSearched: true } : {}),
+    });
+  });
+
+  // An empty answer and a total outage must not look the same. This is the one
+  // partiality that is NOT the normal case.
+  const declared = portfolio.declared ?? portfolio.sources.length;
+  if (!sources.length && declared > 0) {
+    const err = new Error(
+      `compose: every portfolio member failed — ${omissions.join('; ')}`,
+    );
+    err.code = 'PORTFOLIO_ALL_FAILED';
+    err.omissions = omissions;
+    throw err;
+  }
+
+  return { sources, omissions };
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+/**
+ * One member's contribution.
+ *
+ * A member that cannot search is not skipped and is not faked: it contributes
+ * what it genuinely has — its records, listed — flagged as such, plus a named
+ * omission. Returning its list as if it were a query result would be the silent
+ * substitution this feature exists to avoid.
+ */
+async function askOne(source, query, opts) {
+  const { provider, id } = source;
+  // The DECLARED constant, never a bare string: `has()` is a plain Set lookup
+  // on `capabilities()`, and the FOH-7 live-fire (2026-09-06) found `'recall'`
+  // here against a provider declaring `'RECALL'` — every member, SmartMemory
+  // included, silently took the listed-not-searched path and the suite stayed
+  // green because its stubs replaced `has()` outright.
+  const canRecall = typeof provider.has === 'function' ? provider.has(SEMANTIC_CAP.RECALL) : true;
+
+  if (!canRecall) {
+    const records = await provider.listRecords({ kind: KIND.IDEA });
+    // BY RECENCY, before the limit. `listRecords` returns the local provider's
+    // storage order (cluster, then handle number), so slicing it directly hands
+    // back a product's OLDEST ideas — an established product would omit its
+    // newest decisions every time, which is the worst possible subset to show
+    // for a question about what was recently decided.
+    const recent = [...records].sort((a, b) =>
+      String(b.updated_at ?? '').localeCompare(String(a.updated_at ?? '')));
+    return {
+      hits: recent.slice(0, opts.limit ?? LISTED_FALLBACK_LIMIT).map((record) => ({
+        handle: record.handle,
+        // Null, never 0: this member did not rank anything, and 0 would read as
+        // "ranked, and terrible" (see RecallHit in provider.js).
+        score: null,
+        record,
+      })),
+      listedNotSearched: true,
+      omission: `${id} cannot search (no recall capability) — listed its records instead`,
+    };
+  }
+
+  const hits = await provider.recall(query, opts.limit ? { limit: opts.limit } : {});
+  return { hits: hits ?? [], listedNotSearched: false, omission: null };
+}
+
+/** Reject after `ms`, naming the member so the omission can name it too. */
+function withDeadline(promise, ms, id) {
+  let timer;
+  const bell = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      const err = new Error(`did not answer within ${ms}ms`);
+      err.code = 'PORTFOLIO_MEMBER_TIMEOUT';
+      err.memberId = id;
+      reject(err);
+    }, ms);
+  });
+  return Promise.race([promise, bell]).finally(() => clearTimeout(timer));
+}
+
+const reasonOf = (err) => String(err?.message ?? err ?? 'unknown').slice(0, 160);
+
+/**
+ * Turn a failure into the omission's reason class.
+ *
+ * The vocabulary reuses wording the cockpit already uses ("SmartMemory
+ * unreachable", `RecallTab.jsx:29`) rather than coining a parallel one, and the
+ * 403 branch depends on `scopeError` being retained on the error — see the
+ * blueprint's D1.
+ */
+function classify(err) {
+  if (err?.code === 'PORTFOLIO_MEMBER_TIMEOUT') return `unreachable: ${reasonOf(err)}`;
+  const status = typeof err?.status === 'number' ? err.status : null;
+  if (status === 403 || status === 401) {
+    const scope = err?.scopeError;
+    if (scope === 'not-a-member') return 'unauthorized: not a member of that workspace';
+    if (scope === 'missing-scope') return 'unauthorized: the key lacks the required scope';
+    return 'unauthorized: reason undetermined';
+  }
+  if (status === 0 || /ECONNREFUSED|ENOTFOUND|fetch failed|network/i.test(reasonOf(err))) {
+    return `unreachable: ${reasonOf(err)}`;
+  }
+  return `unavailable: ${reasonOf(err)}`;
+}
+
+/**
+ * Refuse a portfolio where any member's fluid workspace is the colleague's own.
+ *
+ * The existing guard (`lib/maya-identity.js`) compares Maya's identity claim
+ * against ONE configured workspace — the declaring root's. A portfolio adds N
+ * more workspaces the turn will read from, and none of them was checked: the
+ * shallow-binding isolation this protects is not a property of the declaring
+ * root, it is a property of every workspace the turn touches. Without it a
+ * member configured at Maya's own workspace reaches a successful chat, which is
+ * the isolation failure the declaring-root check exists to prevent, arriving
+ * through a door that check does not cover.
+ *
+ * Deliberately NOT member-vs-member: two declared products may legitimately
+ * share a workspace, and refusing that would be our policy rather than a
+ * required invariant.
+ *
+ * @param {string} cwd the declaring root
+ * @param {string|null} identityWorkspaceId Maya's own verified workspace
+ * @throws {Error} code PORTFOLIO_WORKSPACE_COLLISION
+ */
+export function assertMemberWorkspacesDistinct(cwd, identityWorkspaceId) {
+  if (!identityWorkspaceId) return;
+  const config = parsePortfolioConfig(cwd);
+  if (!config) return;
+
+  const collisions = config.members
+    .filter((m) => getFluidWorkspaceId(m.root) === identityWorkspaceId)
+    .map((m) => m.id);
+
+  if (collisions.length) {
+    const err = new Error(
+      `compose: portfolio member(s) ${collisions.join(', ')} are configured at the colleague's own ` +
+      `workspace (${identityWorkspaceId}) — a turn cannot read the memory it is writing from`,
+    );
+    err.code = 'PORTFOLIO_WORKSPACE_COLLISION';
+    err.collisions = collisions;
+    throw err;
+  }
+}

package/lib/fluid/record-shape.js

@@ -204,6 +204,13 @@ export function normalizeRecord(record) {
     cluster_order: record.cluster_order ?? null,
     tags: Array.isArray(record.tags) ? [...record.tags] : [],
     source: record.source ?? null,
+    // Hand-authored field lines the markdown parser did not recognise. Carried
+    // verbatim so the upgrade path is LOSSLESS: this shape is an allowlist, so
+    // a field absent here is deleted from the user's ideabox by the first
+    // render after migration, silently and with no way back
+    // (COMP-IDEABOX-MIGRATE-DIALECT). `effort` and `impact` were rescued from
+    // exactly this fate one slice earlier; this is the general case they left.
+    extra_fields: Array.isArray(record.extra_fields) ? [...record.extra_fields] : [],
     links: Array.isArray(record.links) ? record.links.map((l) => ({ ...l })) : [],
     killed: record.killed ? { ...record.killed } : null,
     discussion: Array.isArray(record.discussion) ? record.discussion.map((d) => ({ ...d })) : [],

package/lib/fluid/render-ideabox.js

@@ -16,11 +16,12 @@
  */
 
 import { randomUUID } from 'node:crypto';
-import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
 import { withDirLock } from '../dir-lock.js';
 import { toMarkdownDate } from './ideabox-dates.js';
+import { readPreamble } from './ideabox-preamble.js';
 import { KIND } from './provider.js';
 
 // Says only what is true. The cockpit's write path is NOT on the store yet
@@ -31,7 +32,20 @@ const BANNER = [
   '     Projection of the fluid-store idea records (COMP-PLAN-IDEA-UNIFY).',
   '     Edits here are overwritten on the next render. Change ideas with',
   '     `compose ideabox add|pri|kill|discuss|promote`, then `compose ideabox',
-  '     render` if this file ever looks stale. -->',
+  '     render` if this file ever looks stale.',
+  // The heading and introduction come from a DIFFERENT file, and nothing in the
+  // document says so. Someone correcting the title here loses it on the next
+  // render with no clue where it went — the one edit this file invites that has
+  // no visible home (COMP-IDEABOX-MIGRATE-DIALECT FU-4 follow-up).
+  '     The title and introduction above are not generated: they live in',
+  '     `<this file>.preamble.md`. Edit them THERE, not here.',
+  // The inverse rule, and nothing said it. Everything else in this file is
+  // generated output whose hand edits are discarded on the next render; the
+  // sidecar is the one input, so ITS hand edits are canon and are kept
+  // untouched forever. Two files side by side following opposite rules, with
+  // only one of them stated, is a trap for the next person to edit either.
+  '     That file is the opposite of this one: it is yours, nothing',
+  '     regenerates it, and what you write there is kept. -->',
 ];
 
 const PREAMBLE = [
@@ -85,6 +99,19 @@ function renderIdea(record) {
   if (record.source) out.push(`**Source:** ${record.source}`);
   if (record.body) out.push(`**Idea:** ${record.body}`);
 
+  // Unrecognised hand-authored fields. The two serializers put these in
+  // DIFFERENT slots and the projection has to match whichever one will read it
+  // back: `serializeIdea` emits them after `**Idea:**` and before the trailing
+  // known fields (`lib/ideabox.js`), while `serializeKilledIdea` emits them
+  // after `**Killed:**`. Using the live slot for both meant a killed idea
+  // carrying a custom field reordered the file on every write, so the
+  // projection stopped being a fixed point of the serializer — the property the
+  // whole cutover rests on. Killed ideas are emitted further down, next to
+  // `**Killed:**`.
+  if (!record.killed) {
+    for (const extra of record.extra_fields ?? []) out.push(extra);
+  }
+
   // `Promoted to:` is emitted BEFORE `Maps to:`, which reads backwards and is
   // deliberate. The legacy parser knows `Maps to` and does not know `Promoted
   // to`, so the latter lands in `_extraLines` — and the legacy serializer emits
@@ -112,6 +139,9 @@ function renderIdea(record) {
   // discussed — which is most of the ones anyone would want to kill.
   if (record.status === 'killed' && record.killed) {
     out.push(`**Killed:** ${toMarkdownDate(record.killed.at)} — ${record.killed.reason}`);
+    // The killed serializer's slot for unrecognised fields: immediately after
+    // `**Killed:**`, before the discussion block.
+    for (const extra of record.extra_fields ?? []) out.push(extra);
   }
 
   if (record.discussion?.length) {
@@ -132,8 +162,14 @@ function renderIdea(record) {
  * @param {Array<object>} data.clusters
  * @returns {string}
  */
-export function renderIdeabox({ ideas, clusters }) {
-  const lines = [...BANNER, '', ...PREAMBLE, '', '## Ideas', ''];
+export function renderIdeabox({ ideas, clusters, preamble = null }) {
+  // A project's own title and introduction, when it has one. The default
+  // PREAMBLE is a template, and using it unconditionally deleted the heading and
+  // prose an upgrading project had written for itself — the migration kept every
+  // idea and silently rewrote the document around them
+  // (COMP-IDEABOX-MIGRATE-DIALECT, Codex review finding 4).
+  const preambleLines = preamble && preamble.length ? preamble : PREAMBLE;
+  const lines = [...BANNER, '', ...preambleLines, '', '## Ideas', ''];
   // The legacy serializer emits a placeholder comment when the file contains no
   // `###` grouping heading at all, and the projection has to match it byte for
   // byte or `serialize(parse(projection))` stops being the identity. That state
@@ -203,14 +239,44 @@ export function renderIdeabox({ ideas, clusters }) {
  * Read the records from a provider and render.
  * @param {import('./provider.js').FluidProvider} provider
  */
-export async function renderIdeaboxFrom(provider) {
+export async function renderIdeaboxFrom(provider, { preamble = null, outPath = null } = {}) {
   const [ideas, clusters] = await Promise.all([
     provider.listRecords({ kind: KIND.IDEA }),
     provider.listRecords({ kind: KIND.CLUSTER }),
   ]);
-  return renderIdeabox({ ideas, clusters });
+  // The project's own heading and introduction, captured at migration into a
+  // tracked sibling of the ideabox (FU-4). NOT read from the destination —
+  // `<ideabox>.preamble.md` is a different file; see the note below. `outPath`
+  // names which ideabox's sidecar to read, not a file to read from. An explicit
+  // `preamble` still wins, and a project with no sidecar gets the standard
+  // template exactly as before.
+  const captured = preamble ?? (outPath ? readPreamble(outPath) : null);
+  return renderIdeabox({
+    ideas,
+    clusters,
+    preamble: captured ? captured.split('\n') : null,
+  });
 }
 
+/**
+ * STILL NOT READ FROM THE DESTINATION (FU-4, resolved 2026-09-07).
+ *
+ * Carrying the existing file's preamble forward would have preserved a
+ * project's own title and introduction through migration, but it makes the
+ * DESTINATION authoritative, and `render` is documented as the way back from
+ * any hand edit (`lib/ideabox-cli.js`). Reading the file we are about to repair
+ * means a hand-corrupted heading survives the repair. Both behaviours are
+ * legitimate and they were mutually exclusive while the preamble lived only in
+ * the markdown.
+ *
+ * So it no longer lives only there. `importIdeabox` captures it at migration
+ * into a tracked SIBLING of the ideabox, `<ideabox>.preamble.md`
+ * (`ideabox-preamble.js`), and the renderer reads THAT. A sibling is a
+ * different file, so the projection stays a function of the records plus the
+ * sidecar and never of its own output: a hand edit to the heading is discarded
+ * by the next render exactly as a hand edit to an idea is.
+ */
+
 /**
  * Render and write atomically (temp + rename), following the roadmap-gen
  * pattern — a half-written projection of canonical data is worse than none.
@@ -234,16 +300,78 @@ export async function renderIdeaboxFrom(provider) {
  * which is the documented state of that provider rather than a new gap.
  */
 export async function writeIdeaboxProjection(provider, outPath) {
+  // THE SINGLE DOOR.
+  //
+  // Every projection write replaces the user's ideabox wholesale, so every
+  // projection write is a potential erasure — and the migration gate that
+  // prevents it used to be applied caller-by-caller. It was on the CLI render
+  // and absent from the HTTP render, which meant a button in the cockpit could
+  // do what the equivalent command refused to
+  // (COMP-IDEABOX-MIGRATE-DIALECT, Codex review finding 1). Guarding each
+  // caller is a list that has to stay complete forever; guarding the boundary
+  // they all pass through is a fact. It goes here.
+  //
+  // Idempotent for the ordinary case: after a normal mutation the store is
+  // ahead of the file, which the gate reads as already-migrated and returns
+  // without work.
+  //
+  // DELIBERATELY OUTSIDE `withDirLock`, and it must stay there. The gate can
+  // import, importing calls `provider.createRecord`, and that takes this same
+  // lock — which is a non-reentrant `mkdirSync` lock (`lib/dir-lock.js`). Moving
+  // this call under the lock to close the read-then-write window deadlocks every
+  // migration: measured, it fails after the full 30s lock timeout rather than
+  // completing.
+  //
+  // The window that leaves — the file changing between this check and the
+  // replacement below — is closed by `publishProjection` re-running the gate's
+  // PURE assessment inside the lock (FU-3). That is the shape the deadlock
+  // forces: the decision moves under the lock, the execution stays outside it.
+  const { ensureIdeaboxMigrated } = await import('./ideabox-migrate.js');
+  await ensureIdeaboxMigrated(provider, outPath);
+
   return provider.lockPath
     ? withDirLock(provider.lockPath, () => publishProjection(provider, outPath))
     : publishProjection(provider, outPath);
 }
 
 async function publishProjection(provider, outPath) {
+  // THE SECOND LOOK, INSIDE THE LOCK.
+  //
+  // The gate above ran before this lock was acquired, so the file it approved
+  // is not necessarily the file about to be replaced: an editor saving a new
+  // idea while a migration runs had it destroyed, because the projection was
+  // built from records made out of the OLDER document
+  // (COMP-IDEABOX-MIGRATE-DIALECT FU-3).
+  //
+  // Re-ASSESSING rather than comparing a hash captured at gate time. A hash
+  // comparison cannot tell an edit from an ordinary concurrent render: two
+  // legitimate writers (the CLI and the REST API) each re-read the records, and
+  // whichever lands second would refuse for no reason. The assessment asks the
+  // question that actually matters — is this file still consistent with the
+  // store? — so a concurrent render assesses as `none` and proceeds, while a
+  // hand-added idea assesses as a stray and stops the write.
+  //
+  // Safe under the lock because the assessment is pure and takes no lock: it
+  // reads `listRecords`, `readEvents` and the markdown, and `renderIdeaboxFrom`
+  // below already performs the first of those under this same lock.
+  const { assessIdeabox, IdeaboxChangedUnderLock } = await import('./ideabox-migrate.js');
+  // The exact bytes the assessment below is about to approve. Re-read
+  // immediately before the rename — see the note there.
+  const approved = existsSync(outPath) ? readFileSync(outPath, 'utf8') : null;
+  const assessment = await assessIdeabox(provider, outPath);
+  if (assessment.action === 'refuse') throw assessment.error;
+  if (assessment.action !== 'none') {
+    // `import` here means the store and the file diverged after the gate
+    // approved them — records deleted concurrently, or an interrupted migration
+    // resumable from its manifest. Either way the write is abandoned rather
+    // than replacing a document this pass never checked.
+    throw new IdeaboxChangedUnderLock(outPath, `the store and the file now need ${assessment.action}`);
+  }
+
   // Rendered BEFORE the destination is touched, so a render that refuses (an
   // idea naming a cluster that does not exist) leaves the previous good file
   // exactly where it was rather than replacing it with a partial view.
-  const markdown = await renderIdeaboxFrom(provider);
+  const markdown = await renderIdeaboxFrom(provider, { outPath });
   mkdirSync(dirname(outPath), { recursive: true });
   // randomUUID, not pid: two renders from one process must not collide on the
   // temp name, and a recycled pid must not adopt a stranded file. Cleaned up on
@@ -252,6 +380,24 @@ async function publishProjection(provider, outPath) {
   const tmp = join(dirname(outPath), `.ideabox.md.tmp.${randomUUID()}`);
   try {
     writeFileSync(tmp, markdown, 'utf8');
+    // THE LOCK DOES NOT COORDINATE THE PERSON.
+    //
+    // The assessment above closed the window between the gate and the lock, but
+    // not the window inside the lock: reading the records and rendering them
+    // takes time, and a human saving a new idea in that moment never acquires
+    // this lock — nothing invites them to. Their whole idea was still lost, one
+    // step later than before.
+    //
+    // So the destination is compared against ITSELF, over milliseconds, with
+    // the lock held. That is not the gate-time fingerprint this deliberately
+    // does not use: the lock serializes every render Compose performs, so no
+    // legitimate concurrent render can change this file between the two reads,
+    // and none can be refused by this check. Only a writer outside the lock —
+    // which means a person with the file open — trips it.
+    const current = existsSync(outPath) ? readFileSync(outPath, 'utf8') : null;
+    if (current !== approved) {
+      throw new IdeaboxChangedUnderLock(outPath, 'it was saved from outside compose mid-write');
+    }
     renameSync(tmp, outPath);
   } catch (err) {
     rmSync(tmp, { force: true });

package/lib/fluid/smartmemory-provider.js

@@ -959,6 +959,12 @@ export class SmartMemoryFluidProvider extends FluidProvider {
       cluster_order: input.cluster_order ?? null,
       tags: input.tags ?? [],
       source: input.source ?? null,
+      // Unrecognised hand-authored markdown fields, carried verbatim. This
+      // literal is one of FOUR places the record's fields are enumerated (the
+      // contract, `record-shape.js`, and both providers); a field missing from
+      // any one of them is silently dropped on write
+      // (COMP-IDEABOX-MIGRATE-DIALECT).
+      extra_fields: input.extra_fields ?? [],
       links: input.links ?? [],
       killed: input.killed ?? null,
       discussion: input.discussion ?? [],

package/lib/gate-prompt.js

@@ -136,28 +136,32 @@ export class GateInputUnavailableError extends Error {
  *
  * @param {import('node:readline').Interface} rl
  * @param {string} question
- * @param {{ armGuard?: boolean, deadlineMs?: number }} [opts]
+ * @param {{ armGuard?: boolean, deadlineMs?: number, signal?: AbortSignal }} [opts]
  * @returns {Promise<string>}
  */
-export function ask(rl, question, { armGuard = false, deadlineMs = GATE_NONINTERACTIVE_TIMEOUT_MS } = {}) {
-  if (!armGuard) {
+export function ask(rl, question, { armGuard = false, deadlineMs = GATE_NONINTERACTIVE_TIMEOUT_MS, signal } = {}) {
+  if (!armGuard && !signal) {
     return new Promise(resolve => rl.question(question, resolve));
   }
   return new Promise((resolve, reject) => {
     let settled = false;
     const onEnd = () => finish(() => reject(new GateInputUnavailableError('stdin was closed before a decision')));
-    const timer = setTimeout(
+    const onAbort = () => finish(() => reject(signal.reason));
+    const timer = armGuard ? setTimeout(
       () => finish(() => reject(new GateInputUnavailableError(`no input arrived within ${Math.round(deadlineMs / 1000)}s`))),
       deadlineMs,
-    );
+    ) : null;
     function finish(act) {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
       rl.input.removeListener('end', onEnd);
+      signal?.removeEventListener('abort', onAbort);
       act();
     }
-    rl.input.once('end', onEnd);
+    if (armGuard) rl.input.once('end', onEnd);
+    if (signal?.aborted) { onAbort(); return; }
+    signal?.addEventListener('abort', onAbort, { once: true });
     rl.question(question, answer => finish(() => resolve(answer)));
   });
 }
@@ -230,7 +234,8 @@ function drawGatePanel(out, gateDispatch, { artifact, gateExtras } = {}) {
  * @param {object}   [options.gateExtras]  - { fromPhase, toPhase } for panel display
  * @returns {Promise<{ outcome: string, rationale: string }>}
  */
-export async function promptGate(gateDispatch, { input, output, artifact, askAgent, gateExtras, nonInteractive, timeoutMs } = {}) {
+export async function promptGate(gateDispatch, { input, output, artifact, askAgent, gateExtras, nonInteractive, timeoutMs, signal } = {}) {
+  signal?.throwIfAborted();
   if (nonInteractive) {
     return { outcome: 'approve', rationale: 'auto-approved (--all mode)' };
   }
@@ -247,6 +252,7 @@ export async function promptGate(gateDispatch, { input, output, artifact, askAge
   const askGuard = {
     armGuard: input === undefined && !process.stdin.isTTY,
     deadlineMs: timeoutMs ?? GATE_NONINTERACTIVE_TIMEOUT_MS,
+    signal,
   };
 
   try {
@@ -312,6 +318,7 @@ export async function promptGate(gateDispatch, { input, output, artifact, askAge
           const answer = await askAgent(trimmed, artifact);
           rl.output.write(`\n  ${answer}\n`);
         } catch (err) {
+          if (signal?.aborted) throw err;
           rl.output.write(`  (agent error: ${err.message})\n`);
         }
         notes.push(trimmed);