@coda-console/plugin-check 0.0.0 → 0.4.5

package/check/agent.mjs

@@ -0,0 +1,416 @@
+// The handshake and live levels for one agent: the checker plays Coda (backend/src/adapters/acp.mjs AcpSession), starts the
+// agent's command the way Coda does, says what Coda says, and holds what the agent says to ACP's schema and to
+// docs/agent-protocol.md. Where Coda would quietly drop or refuse something, the check fails and says what Coda does.
+import { randomBytes, randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { ACP_PROTOCOL_VERSION, CANCEL_LIMIT, METHOD_NOT_FOUND, OPEN_LIMIT, SIGNED_OUT, STEERING, STEERING_OUTCOMES, TERM_GRACE, RETRY_DELAYS, continuationPrompt,
+  agentErrorMessage, serviceFailure, cleared, clientCapabilities, currentModel, pluginEnv, steeringParams, supportsSteering, systemPrompt, takesInstructions } from './coda.mjs';
+import { temporary } from './leftovers.mjs';
+import { AgentProcess, Exited, Timeout } from './process.mjs';
+import { explain, schemas } from './schema.mjs';
+import { Waits } from './waits.mjs';
+
+// `exit`: how long an agent may take to go after SIGTERM, or after its input ends. `cancelReply`: how soon a turn whose work
+// was done answers once it has read the cancel. `pause`: a quiet moment between two turns, as between two messages of a
+// person, for what an agent says after a turn to be heard outside it. `term`: how long Coda's session host waits after
+// SIGTERM before SIGKILL. `steer`: how long a steering request may take to be answered; `steerQuiet`: how long an agent that
+// answered one outside a turn is watched for a turn of its own.
+export const LIMITS = { open: OPEN_LIMIT, turn: 180_000, settle: 60_000, cancel: CANCEL_LIMIT, exit: 5_000, cancelDelay: 500, cancelReply: 5_000,
+  pause: 500, term: TERM_GRACE, retryDelays: RETRY_DELAYS, steer: 30_000, steerQuiet: 2_000 };
+// A request of the checker's own, sent right behind a `session/cancel`; nothing answers it but an error (Method not found).
+// The agent reads it after the cancel, so its answer is written after the agent has read the cancel.
+export const BARRIER = '_codaCheck/barrier';
+// What an agent says of a session rather than does in a turn: what it says of these after a cancel is no work.
+const BOOKKEEPING = new Set(['available_commands_update', 'current_mode_update', 'config_option_update', 'session_info_update', 'usage_update']);
+// The session instructions the checker gives in Coda's place (Coda's own are backend/src/domain/client-instructions.mjs: how
+// replies show in its clients, the reply language, the plugins' instructions): a word in them that only an agent that took
+// them in before its first turn can say, asked for in that turn.
+export const CHECK_QUESTION = 'What is the Coda check word?';
+const instructionsFor = word => `# Coda client
+
+Your replies are shown in Coda, a graphical client on Mac and iPhone, not in a terminal. This session is run by coda-plugin-check, which plays Coda.
+
+If the user asks for the Coda check word, reply with exactly ${word} and nothing else.`;
+// A turn with something to say for a while, and a message for it as it goes; and one that comes once a turn has ended.
+const STEER_TURN = '从 1 数到 20，每个数字单独一行。', STEER_TEXT = '数完后再说一句「插话收到」。', STEER_LATE = '这条插话到的时候，这一轮已经结束了。';
+const secs = ms => (ms / 1000).toFixed(1);
+const short = (text, max = 80) => (text.length > max ? `${text.slice(0, max)}…` : text).replace(/\s+/g, ' ');
+
+// The environment Coda starts the agent with: the session's (here the checker's), and its plugin's (`plugin`: its directory,
+// settings and the plugins it depends on).
+const agentEnv = (plugin, base) => ({ ...cleared(process.env), ...pluginEnv({ ...plugin, stateDir: join(base, 'state') }) });
+
+// One process of the agent with the session it opens, and what it says, taken in order.
+class Session {
+  constructor({ agent, plugin, base, say, limits, instructions }) {
+    this.say = say; this.limits = limits; this.instructions = instructions;
+    this.waits = new Waits({ fail: (rule, message) => this.at.fail(rule, message), warn: (rule, message) => this.at.warn(rule, message) });
+    this.turn = null; this.autonomous = null; this.autonomousTurns = 0; this.loading = true; this.pendingWaits = [];
+    this.kinds = new Map(); this.malformed = 0; this.said = new Set(); this.listeners = new Set(); this.idleWork = [];
+    // The session's working copy, and the plugin's state directory, which Coda makes for it.
+    this.cwd = join(base, 'work');
+    for (const dir of [this.cwd, join(base, 'state')]) mkdirSync(dir, { recursive: true });
+    this.proc = new AgentProcess({ command: agent.command, cwd: this.cwd,
+      env: agentEnv(plugin, base),
+      onMessage: message => { this.receive(message); this.changed(); }, onNoise: (line, why) => this.noise(line, why) });
+    this.proc.exited.then(() => this.changed());
+  }
+  // The level things are said at now: the live level once a turn has been sent.
+  get at() { return this.live ? this.say.live : this.say.handshake; }
+  once(key, fn) { if (!this.said.has(key)) { this.said.add(key); fn(); } }
+  changed() { for (const listener of this.listeners) listener(); }
+  // Resolves true once `condition` holds, false past `ms` or when the process has ended without it holding.
+  until(condition, ms) {
+    if (condition()) return Promise.resolve(true);
+    return new Promise(resolve => {
+      const done = value => { clearTimeout(timer); this.listeners.delete(listener); resolve(value); };
+      const listener = () => { if (condition()) done(true); else if (this.proc.exit) done(false); };
+      const timer = setTimeout(() => done(condition()), Math.max(0, ms));
+      this.listeners.add(listener);
+    });
+  }
+  noise(line, why) {
+    if (why === 'not-json') this.once('noise', () => this.at.warn('wire.noise', `标准输出里有不是 JSON 的行（「${short(line, 60)}」）：Coda 丢掉它；日志请写标准错误`));
+    else this.at.fail('wire.shape', `标准输出里有不是 JSON 对象的消息（「${short(line, 60)}」）：Coda 不收批量消息，整条丢掉`);
+  }
+
+  receive(m) {
+    if ('id' in m) return this.request(m);
+    if (m.method === 'session/update') return this.update(m.params);
+    if (m.method === '_coda/wait') {
+      // Coda keeps what is said while a session opens until it knows the session (docs/agent-protocol.md「Agent 活动」规则 7).
+      if (this.loading) this.pendingWaits.push(m.params); else this.wait(m.params);
+      return;
+    }
+    if (m.method === '$/cancel_request') return;
+    this.once(`notify:${m.method}`, () => this.at.info('notify.unknown', `Agent 发了 Coda 不认识的通知 ${m.method}：Coda 忽略`));
+  }
+  update(params) {
+    const parsed = schemas.zSessionNotification.safeParse(params);
+    if (!parsed.success) {
+      this.malformed++;
+      this.at.fail('update.schema', `session/update 不合 ACP schema（SDK 1.4.0）：${explain(parsed.error, params)}`);
+      return;
+    }
+    // Of a session being opened Coda keeps only its commands and title; a replayed history it does not want.
+    if (this.loading) return;
+    if (!this.waits.owns(params.sessionId)) {
+      this.at.fail('update.session', `session/update 说的会话 ${params.sessionId} 不是本会话，也不是 _coda/wait 登记过的子会话：Coda 丢弃`);
+      return;
+    }
+    const kind = params.update.sessionUpdate;
+    this.kinds.set(kind, (this.kinds.get(kind) ?? 0) + 1);
+    const turn = this.turn ?? this.autonomous;
+    if (turn) {
+      turn.updates++;
+      if (kind === 'agent_message_chunk' && params.update.content?.type === 'text') turn.text += params.update.content.text;
+      if (turn.barrier?.answered && !BOOKKEEPING.has(kind)) turn.workAfterCancel.push(kind);
+    } else if (!BOOKKEEPING.has(kind)) this.idleWork.push(kind);
+  }
+  wait(params) {
+    this.waits.take(params, { turn: !!this.turn });
+    this.track();
+  }
+  // Coda opens a turn of its own for a wait that goes `handling` outside a turn it sent, and ends it when none is
+  // (docs/agent-protocol.md「Agent 活动」规则 3); one that went `handling` in a turn it sent goes on in one as that turn ends.
+  track() {
+    const handling = this.waits.handling.length;
+    if (!this.turn && handling && !this.autonomous) { this.autonomous = { started: Date.now(), updates: 0, text: '' }; this.autonomousTurns++; }
+    if (this.autonomous && !handling) { this.lastAutonomous = this.autonomous; this.autonomous = null; }
+  }
+  request(m) {
+    const inTurn = !!(this.turn || this.autonomous);
+    if (m.method === 'session/request_permission' || m.method === 'elicitation/create') {
+      const permission = m.method === 'session/request_permission', what = permission ? '审批' : '提问';
+      const refuse = permission ? { outcome: { outcome: 'cancelled' } } : { action: 'cancel' };
+      const parsed = (permission ? schemas.zRequestPermissionRequest : schemas.zCreateElicitationRequest).safeParse(m.params);
+      if (!parsed.success) { this.at.fail('request.schema', `${m.method} 不合 ACP schema：${explain(parsed.error, m.params)}`); this.proc.respond(m.id, refuse); return; }
+      if (typeof m.params.sessionId === 'string' && !this.waits.owns(m.params.sessionId)) this.at.fail('request.session', `${what}说的会话 ${m.params.sessionId} 不是本会话或登记过的子会话`);
+      if (!inTurn) {
+        this.at.fail('request.outside-turn', `${what}在一轮之外发来（没有进行中的 session/prompt，也没有 handling 的活动）：Coda 拒绝（${permission ? '回 cancelled' : '回 cancel'}），在会话里记一条说明`);
+        this.proc.respond(m.id, refuse);
+        return;
+      }
+      if (permission) {
+        const reject = m.params.options.find(o => o.kind === 'reject_once') ?? m.params.options.find(o => o.kind === 'reject_always');
+        this.proc.respond(m.id, reject ? { outcome: { outcome: 'selected', optionId: reject.optionId } } : refuse);
+        this.at.info('request.permission', `审批「${short(m.params.toolCall?.title ?? m.params.toolCall?.toolCallId ?? '')}」：检查一律拒绝（${reject ? `选 ${reject.optionId}` : '没有拒绝的选项，回 cancelled'}）`);
+      } else {
+        this.proc.respond(m.id, { action: 'decline' });
+        this.at.info('request.elicitation', `提问「${short(m.params.message ?? '')}」：检查一律回 decline`);
+      }
+      return;
+    }
+    // Coda handles nothing else an agent asks: its ACP SDK answers that the method is not found.
+    this.proc.respondError(m.id, METHOD_NOT_FOUND, `"Method not found": ${m.method}`);
+    this.once(`request:${m.method}`, () => this.at.warn('request.unsupported', `Agent 请求了 ${m.method}：Coda 不提供（没声明 fs、terminal），回 -32601`));
+  }
+
+  // initialize, then session/new or session/load as AcpSession.initialize does. Returns 'ok', 'signed-out' or 'failed'.
+  async open(sessionId = null) {
+    const say = this.at;
+    let reply;
+    try { reply = await this.proc.request('initialize', { protocolVersion: ACP_PROTOCOL_VERSION, clientCapabilities: clientCapabilities() }, { timeout: this.limits.open }); }
+    catch (e) { this.reportedExit = e instanceof Exited; say.fail('handshake.initialize', `initialize 失败：${e.message}`); return 'failed'; }
+    if (reply.error?.code === SIGNED_OUT) { say.skip('handshake.signed-out', `initialize 回了 -32000（未登录）：Coda 提示用户去「资源」登录；后面的检查跳过`); return 'signed-out'; }
+    if (reply.error) { say.fail('handshake.initialize', `initialize 回了错误 ${reply.error.code}：${reply.error.message}`); return 'failed'; }
+    const init = schemas.zInitializeResponse.safeParse(reply.result);
+    if (!init.success) { say.fail('handshake.initialize', `initialize 的结果不合 ACP schema：${explain(init.error)}`); return 'failed'; }
+    this.init = reply.result;
+    if (reply.result.protocolVersion !== ACP_PROTOCOL_VERSION) {
+      say.fail('handshake.protocol', `protocolVersion 是 ${reply.result.protocolVersion}：Coda 用的 ACP（SDK 1.4.0）是版本 ${ACP_PROTOCOL_VERSION}（Coda 自己不核对这一项，按它说的协议说话）`);
+      return 'failed';
+    }
+    const caps = reply.result.agentCapabilities ?? {}, waits = !!caps._meta?.coda?.waits && typeof caps._meta.coda.waits === 'object';
+    this.canLoad = caps.loadSession === true; this.instructed = takesInstructions(reply.result); this.steering = supportsSteering(reply.result);
+    if (!sessionId) {
+      say.pass('handshake.initialize', `initialize：protocolVersion ${ACP_PROTOCOL_VERSION}，loadSession ${this.canLoad}，${waits
+        ? '声明了 _meta.coda.waits' : '没声明 _meta.coda.waits（只是声明，登记照收）'}${caps.sessionCapabilities?.additionalDirectories != null ? '，收 additionalDirectories' : ''}，${this.steering
+        ? '声明了插话（_meta.steering）' : '没声明插话'}`);
+      if (this.instructed) say.pass('handshake.system-prompt', '声明了会话指令（sessionCapabilities.systemPrompt）：session/new、session/load 带 Coda 的指令（append 模式）');
+      else say.fail('handshake.system-prompt', 'initialize 没声明 agentCapabilities.sessionCapabilities.systemPrompt：Coda 照 ACP 的规矩不发会话指令（回复在 Mac、iPhone 上怎样显示、回复语言、插件说明），接入 Coda 的 Agent 必须声明。'
+        + '有原生系统提示词入口的放在那里；没有的，在原生会话第一次 session/prompt 时把指令作为单独、明确分隔的一段放在用户输入前面送入，之后与 session/load 恢复的会话不再送');
+    }
+    if (sessionId && !this.canLoad) { say.fail('handshake.load', '新进程的 initialize 不再声明 loadSession：Coda 恢复不了这个会话'); return 'failed'; }
+    const method = sessionId ? 'session/load' : 'session/new';
+    // Coda's instructions go with every open of the session, `session/load` too.
+    const instructions = this.instructed ? { systemPrompt: systemPrompt(this.instructions) } : {};
+    try { reply = await this.proc.request(method, { cwd: this.cwd, mcpServers: [], ...instructions, ...(sessionId ? { sessionId } : {}) }, { timeout: this.limits.open }); }
+    catch (e) { this.reportedExit = e instanceof Exited; say.fail(sessionId ? 'handshake.load' : 'handshake.new', `${method} 失败：${e.message}`); return 'failed'; }
+    if (reply.error?.code === SIGNED_OUT) { say.skip('handshake.signed-out', `${method} 回了 -32000（未登录）：Coda 提示用户去「资源」登录；后面的检查跳过`); return 'signed-out'; }
+    if (reply.error) { say.fail(sessionId ? 'handshake.load' : 'handshake.new', `${method} 回了错误 ${reply.error.code}：${reply.error.message}`); return 'failed'; }
+    const parsed = (sessionId ? schemas.zLoadSessionResponse : schemas.zNewSessionResponse).safeParse(reply.result);
+    if (!parsed.success) { say.fail(sessionId ? 'handshake.load' : 'handshake.new', `${method} 的结果不合 ACP schema：${explain(parsed.error)}`); return 'failed'; }
+    this.sessionId = sessionId ?? reply.result.sessionId; this.waits.sessionId = this.sessionId; this.info = reply.result;
+    this.loading = false;
+    for (const params of this.pendingWaits.splice(0)) this.wait(params);
+    const model = currentModel(reply.result);
+    if (typeof model !== 'string') {
+      say.fail('handshake.model', `${method} 没报当前模型（configOptions 里 category 为 model 的 currentValue，或 models.currentModelId）：Coda 每轮开始前核对，没有就不发这一轮（「适配器未报告实际模型」）`);
+      return 'failed';
+    }
+    if (!sessionId) say.pass('handshake.new', `session/new：会话 ${this.sessionId}，当前模型 ${model}`);
+    return 'ok';
+  }
+  // One turn of Coda's: `session/prompt` with an ID of Coda's choosing, as AcpSession.prompt sends it. With `cancel`, stopped
+  // after the agent first says something, or `cancelDelay` after it was sent; the barrier behind the cancel tells what the
+  // agent said and did before it read the cancel from what it said and did after (`workAfterCancel`, `readCancel`). With
+  // `steer`, that message is sent into the turn once the agent first says something, as Coda steers a turn under way; its
+  // answer is the turn's `steered`. `as`: the rule the turn is said under; one but `live.turn` is judged by the caller, from
+  // `last` (the turn).
+  async prompt(text, { cancel = false, steer = null, as = 'live.turn', attempt = 0, accepted = false } = {}) {
+    const say = this.say.live, id = randomUUID(), rule = cancel ? 'live.cancel' : as;
+    const turn = this.last = this.turn = { started: Date.now(), updates: 0, text: '', barrier: null, workAfterCancel: [], readCancel: false, replied: null, steered: null };
+    const reply = this.proc.request('session/prompt', { sessionId: this.sessionId, prompt: [{ type: 'text', text }] },
+      { id, timeout: this.limits.turn, onReply: () => { turn.readCancel = !!turn.barrier?.answered; turn.replied = Date.now(); this.turn = null; this.track(); this.changed(); } });
+    reply.catch(() => { if (this.turn === turn) { this.turn = null; this.track(); this.changed(); } });
+    let cancelledAt = null;
+    if (cancel) {
+      await this.until(() => this.turn !== turn || turn.updates > 0, this.limits.cancelDelay);
+      if (this.turn === turn) {
+        cancelledAt = Date.now();
+        this.proc.notify('session/cancel', { sessionId: this.sessionId });
+        // Taken as it is read, in order with the reply to the turn (`onReply`, not a promise's callback, which comes later).
+        const barrier = turn.barrier = { answered: null };
+        this.proc.request(BARRIER, {}, { timeout: this.limits.cancel, onReply: () => { barrier.answered = Date.now(); } }).catch(() => {});
+      }
+    }
+    if (steer) {
+      await this.until(() => this.turn !== turn || turn.updates > 0, this.limits.turn);
+      if (this.turn === turn) turn.steered = this.steer(steer);
+    }
+    let m, timer;
+    try {
+      m = cancelledAt ? await Promise.race([reply, new Promise((_, reject) => { timer = setTimeout(reject, this.limits.cancel, new Timeout('取消后的 session/prompt', this.limits.cancel)); })])
+        : await reply;
+    } catch (e) {
+      this.reportedExit = e instanceof Exited;
+      say.fail(rule, e instanceof Timeout && cancelledAt
+        ? `session/cancel 后 ${secs(this.limits.cancel)} 秒这一轮还没结束：Coda 会关掉托管连接与它的进程组，结果未知`
+        : `这一轮没有结束：${e.message}`);
+      return null;
+    } finally { clearTimeout(timer); }
+    if (m.error) {
+      const failure = serviceFailure(m.error), wait = this.limits.retryDelays[attempt];
+      if (!cancel && !text.startsWith('/') && failure && wait !== undefined) {
+        say.info('live.service-retry', `服务暂不可用，按 Coda 策略 ${secs(wait)} 秒后第 ${attempt + 1} 次重试`);
+        await delay(wait);
+        accepted ||= failure.input === 'accepted';
+        return this.prompt(accepted ? continuationPrompt : text, { as, attempt: attempt + 1, accepted });
+      }
+      say.fail(rule, `session/prompt 回了错误 ${m.error.code}：${agentErrorMessage(m.error)}（Coda 把这一轮记为失败）`);
+      return null;
+    }
+    const parsed = schemas.zPromptResponse.safeParse(m.result);
+    if (!parsed.success) { say.fail(rule, `session/prompt 的结果不合 ACP schema：${explain(parsed.error)}`); return null; }
+    const stop = m.result.stopReason;
+    if (rule !== 'live.turn' && !cancel) return stop;
+    if (!cancel) {
+      say.pass('live.turn', `一轮结束：stopReason ${stop}，${secs(Date.now() - turn.started)} 秒，${turn.updates} 条 session/update${turn.text ? `，回复「${short(turn.text)}」` : ''}`);
+      if (!turn.text) say.warn('live.reply', '这一轮没有回复文字（agent_message_chunk）');
+    } else if (!cancelledAt) say.info('live.cancel', `第二轮在取消前就结束了（stopReason ${stop}），取消没机会生效`);
+    else {
+      say.pass('live.cancel', `session/cancel 后 ${secs(Date.now() - cancelledAt)} 秒结束，stopReason ${stop}`);
+      // A turn that goes on once it has read the cancel — says or does more, or answers only a while later — and then does not
+      // say `cancelled` would not stop. One that had ended does not have to: its answer was on its way as the cancel went out,
+      // or its work was done and it answers at once (Coda's own Codex entry, waiting on a title, says end_turn then).
+      const after = turn.workAfterCancel, late = turn.readCancel && turn.replied - turn.barrier.answered > this.limits.cancelReply;
+      if (stop !== 'cancelled' && (after.length || late)) say.fail('live.cancel-reason', `读到 session/cancel 之后这一轮${after.length
+        ? `还在接着做（又发了 ${after.length} 条 session/update：${[...new Set(after)].join('、')}）` : `又过了 ${secs(turn.replied - turn.barrier.answered)} 秒才答复`}，最后回 stopReason ${stop}：ACP 要求停下并回 cancelled；Coda 按回的记，这一轮成了正常结束而不是已停止`);
+      else if (stop !== 'cancelled') say.info('live.cancel-reason', `这一轮回了 stopReason ${stop}：${turn.readCancel
+        ? '读到 session/cancel 时它已经做完（之后没再做什么，随即答复）' : '答复写出时还没读到 session/cancel（先于紧跟取消发的探测请求的答复）'}，取消送到前这一轮已经结束，不算没停`);
+    }
+    return stop;
+  }
+  // `_session/steering` as Coda sends it: the agent's answer (`{ outcome, … }`), or `{ error }`.
+  async steer(text) {
+    try {
+      const m = await this.proc.request(STEERING, steeringParams(this.sessionId, text), { timeout: this.limits.steer });
+      return m.error ? { error: `回了错误 ${m.error.code}：${m.error.message}` } : m.result ?? {};
+    } catch (e) { this.reportedExit = e instanceof Exited; return { error: e.message }; }
+  }
+  // Waits for every open wait to end, `limit` at most; with `cancel`, stops the first turn of its own the agent takes.
+  async settle(limit, { cancel = false } = {}) {
+    const say = this.say.live, deadline = Date.now() + limit;
+    let stopped = false;
+    while (this.waits.open.length && Date.now() < deadline && !this.proc.exit) {
+      await this.until(() => !this.waits.open.length || (cancel && !stopped && this.autonomous), deadline - Date.now());
+      if (cancel && !stopped && this.autonomous) {
+        stopped = true;
+        const at = Date.now();
+        this.proc.notify('session/cancel', { sessionId: this.sessionId });
+        if (await this.until(() => !this.autonomous, this.limits.cancel)) say.pass('live.cancel-autonomous', `自主轮次里发 session/cancel，${secs(Date.now() - at)} 秒后没有项再处于 handling`);
+        else say.fail('live.cancel-autonomous', `自主轮次里发 session/cancel 后 ${secs(this.limits.cancel)} 秒还有项在 handling：Coda 会关掉托管连接与它的进程组`);
+      }
+    }
+    return !this.waits.open.length;
+  }
+  // Stops it as Coda's session host stops an agent (adapters/session-host.mjs): SIGTERM to its process group, its input
+  // left open. It should be gone within `exit`; past `term` Coda would already have sent SIGKILL. One that ended before is
+  // said to have, unless that was said already. Its process group goes either way.
+  async finish(say) {
+    if (this.proc.exit) {
+      const { code, signal } = this.proc.exit, words = this.proc.lastWords();
+      if (!this.reportedExit) say.fail('handshake.exited', `Agent 进程提前退出了（${signal ? `信号 ${signal}` : `退出码 ${code}`}）${words ? `：${words}` : ''}`);
+    } else {
+      const took = await this.proc.terminate(this.limits.exit);
+      if (took === null) say.fail('handshake.sigterm', `SIGTERM 后 ${secs(this.limits.exit)} 秒还没退出：Coda 关会话时对 Agent 的进程组发 SIGTERM，${secs(this.limits.term)} 秒后 SIGKILL`);
+      else {
+        say.pass('handshake.sigterm', `SIGTERM 后 ${secs(took)} 秒退出`);
+        if (took > this.limits.term) say.warn('handshake.sigterm-slow', `SIGTERM 后 ${secs(took)} 秒才退出：Coda 只等 ${secs(this.limits.term)} 秒就 SIGKILL，收尾会被打断`);
+      }
+    }
+    this.proc.kill();
+  }
+}
+
+// The end of its input, in a process of its own once it has answered `initialize`: what an agent sees when whatever runs
+// it is gone without stopping it (Coda's session host killed outright). Coda stops agents with SIGTERM and does not rely on
+// it, so one that stays is only worth a look.
+async function inputEnd({ agent, plugin, base, limits, say }) {
+  const proc = new AgentProcess({ command: agent.command, cwd: join(base, 'work'), env: agentEnv(plugin, base) });
+  try {
+    try { await proc.request('initialize', { protocolVersion: ACP_PROTOCOL_VERSION, clientCapabilities: clientCapabilities() }, { timeout: limits.open }); }
+    catch { return; }
+    const took = await proc.closeInput(limits.exit);
+    if (took !== null) say.pass('handshake.exit-input', `关掉标准输入后 ${secs(took)} 秒退出`);
+    else say.warn('handshake.exit-input', `关掉标准输入后 ${secs(limits.exit)} 秒还没退出：Coda 关会话用 SIGTERM，不靠它；但托管它的进程意外没了时，它只看得到输入结束，会一直留着`);
+  } finally { proc.kill(); }
+}
+
+// The first turn asks for the word in the session instructions (docs/agent-protocol.md「会话指令」): they are to be in the
+// agent's context before it, whether its own system prompt took them or they went in front of the user's input.
+async function instructions(session, word, limits, say) {
+  if (!session.instructed) { say.skip('live.instructions', '没声明会话指令：Coda 不发 systemPrompt，指令是否生效查不了'); return true; }
+  if (!await session.prompt(CHECK_QUESTION, { as: 'live.instructions' })) return false;
+  const text = session.last.text;
+  if (text.includes(word)) say.pass('live.instructions', `会话指令在第一轮之前生效：第一轮问指令里的检查词，回复里有 ${word}`);
+  else say.fail('live.instructions', `会话指令没在第一轮之前生效：session/new 的 systemPrompt 里写了检查词 ${word}，第一轮问它，回复${text ? `「${short(text)}」` : '没有文字'}，没有说出它。`
+    + '有原生系统提示词入口的放在那里；没有的，在原生会话第一次 session/prompt 时把指令作为单独、明确分隔的一段放在用户输入前面送入');
+  await delay(limits.pause);
+  return true;
+}
+
+// docs/agent-protocol.md「插话」: Coda steers only a turn of its own under way, but the turn may have ended by the time the
+// message is read. One that has is answered promptRequired, and the agent takes no turn of its own for it; one under way
+// takes it in (injected) and still ends with the original `session/prompt`. Anything else Coda records as unknown.
+async function steering(session, limits, say) {
+  if (!session.steering) { say.skip('live.steering', '没声明插话（_meta.steering.supported）：用户「立即插话」时 Coda 停止这一轮，结束后再把消息作为下一轮发出'); return; }
+  const answer = result => result.error ?? (result.outcome ? `outcome ${result.outcome}` : `结果 ${short(JSON.stringify(result))}`);
+  if (!await session.until(() => !session.autonomous, limits.settle)) { say.warn('live.steering', `自主轮次 ${secs(limits.settle)} 秒还没结束，插话没查`); return; }
+  const before = session.idleWork.length, late = await session.steer(STEER_LATE);
+  if (session.proc.exit) return;
+  await delay(limits.steerQuiet);
+  const work = session.idleWork.slice(before);
+  if (late.outcome !== 'promptRequired') say.fail('live.steering', `一轮已经结束时发 ${STEERING}，回了 ${answer(late)}：要回 promptRequired（reason noRunningTurn），消息不收、也不自己另开一轮；Coda 把其他答复记为结果未知，不再把消息作为下一轮发出`);
+  else if (work.length) say.fail('live.steering', `一轮已经结束时发 ${STEERING}，回了 promptRequired，随后却自己说起话来（${work.length} 条 session/update：${[...new Set(work)].join('、')}）：promptRequired 的消息没被接收，Agent 不得自己另开一轮，Coda 会把它作为下一轮发出`);
+  else say.pass('live.steering', `一轮已经结束时插话：回 promptRequired${late.reason ? `（${late.reason}）` : ''}，${secs(limits.steerQuiet)} 秒里没有自己另开一轮`);
+  await delay(limits.pause);
+  const stop = await session.prompt(STEER_TURN, { steer: STEER_TEXT, as: 'live.steering' }), turn = session.last;
+  if (!turn.steered) { if (stop) say.info('live.steering', `这一轮在说出第一句之前就结束了（stopReason ${stop}），一轮进行中的插话没机会发`); return; }
+  const steered = await turn.steered;
+  if (!STEERING_OUTCOMES.includes(steered.outcome)) say.fail('live.steering', `一轮进行中发 ${STEERING}，回了 ${answer(steered)}：要么 injected（加进这一轮），要么 promptRequired（这一轮已经结束）；Coda 把其他答复记为结果未知`);
+  else if (!stop) return;
+  else if (steered.outcome === 'injected') say.pass('live.steering', `一轮进行中插话：injected，原来的 session/prompt 照常结束（stopReason ${stop}，${turn.updates} 条 session/update${turn.text ? `，回复「${short(turn.text)}」` : ''}）`);
+  else say.info('live.steering', `一轮进行中插话：回 promptRequired，插话到时这一轮已经结束（stopReason ${stop}）`);
+}
+
+async function live(session, { prompt, word }, limits, say) {
+  session.live = true;
+  if (!await instructions(session, word, limits, say)) return;
+  if (!await session.prompt(prompt)) return;
+  const settled = await session.settle(limits.settle), waits = session.waits.registered;
+  if (waits.length) {
+    const kinds = Object.entries(Object.groupBy(waits, w => w.kind)).map(([kind, list]) => `${kind} ×${list.length}`).join('，');
+    say[settled ? 'pass' : 'warn']('live.waits', `Agent 活动：登记 ${waits.length} 个（${kinds}），自主轮次 ${session.autonomousTurns} 次${settled ? '，都已结束'
+      : `；${secs(limits.settle)} 秒后还有 ${session.waits.open.length} 个没结束（定时与长任务可以这样，不算失败）`}`);
+    if (session.lastAutonomous?.text) say.info('live.autonomous', `自主轮次的回复「${short(session.lastAutonomous.text)}」`);
+  } else say.info('live.waits', '这一轮没有报 Agent 活动（_coda/wait）');
+  await steering(session, limits, say);
+  // A second turn, stopped; and a turn of the agent's own that it brings about, stopped too. Coda sends nothing while a turn
+  // of the agent's own is under way: a message waits for it to end.
+  await new Promise(resolve => setTimeout(resolve, limits.pause));
+  if (!await session.until(() => !session.autonomous, limits.settle)) say.warn('live.cancel', `自主轮次 ${secs(limits.settle)} 秒还没结束，第二轮（取消）没发`);
+  else {
+    await session.prompt(prompt, { cancel: true });
+    await session.settle(limits.settle, { cancel: true });
+  }
+  const kinds = [...session.kinds].map(([kind, n]) => `${kind} ×${n}`).join('，');
+  if (!session.malformed) say.pass('live.updates', `session/update 都合 ACP schema（SDK 1.4.0）：${kinds || '无'}`);
+}
+
+// Checks one declared agent of the plugin in `pluginDir`, with the plugin's `settings` and `dependencies` (by ID, their
+// directories) as Coda gives them; `say(level)` gives the report scope for a level.
+export async function checkAgent({ agent, pluginDir, settings = {}, dependencies = {}, live: running = false, prompt = '只回复 ok', limits: given = {}, say }) {
+  const limits = { ...LIMITS, ...given }, temp = temporary('coda-plugin-check-'), base = temp.dir;
+  const scopes = { handshake: say('handshake'), live: say('live') }, sessions = [], plugin = { pluginDir, settings, dependencies };
+  const word = `coda-${randomBytes(3).toString('hex')}`, instructions = instructionsFor(word);
+  try {
+    const session = new Session({ agent, plugin, base, say: scopes, limits, instructions });
+    sessions.push(session);
+    const opened = await session.open();
+    if (opened === 'ok' && running) await live(session, { prompt, word }, limits, scopes.live);
+    else if (running) scopes.live.skip('live.skipped', opened === 'signed-out' ? '未登录，一轮跳过' : '握手没过，一轮跳过');
+    else scopes.live.skip('live.skipped', '一轮要 --live（会真的发一条提示词，可能要登录、花额度）');
+    await session.finish(scopes.handshake);
+    if (opened !== 'failed') await inputEnd({ agent, plugin, base, limits, say: scopes.handshake });
+    if (opened !== 'ok' || !running) return;
+    if (!session.canLoad) { scopes.live.skip('live.load', '没声明 loadSession：Coda 不会要求恢复，session/load 不查'); return; }
+    const again = new Session({ agent, plugin, base, say: scopes, limits, instructions });
+    sessions.push(again);
+    again.live = true;
+    if (await again.open(session.sessionId) === 'ok') {
+      scopes.live.pass('live.load', `新进程 session/load 接上了会话 ${session.sessionId}${again.instructed ? '（同样带着会话指令）' : ''}`);
+      // The session goes on in the new process: Coda's next message is a turn of it. An agent that answers the load but keeps
+      // no session for it ("Session not found") leaves a resumed session that cannot go on.
+      const stop = await again.prompt(prompt, { as: 'live.load-turn' });
+      if (stop) scopes.live.pass('live.load-turn', `恢复后的一轮结束：stopReason ${stop}`);
+    }
+    await again.finish(scopes.live);
+  } finally {
+    for (const session of sessions) session.proc.kill();
+    temp.remove();
+  }
+}

package/check/coda.mjs

@@ -0,0 +1,156 @@
+// What the checker copies from Coda, in one place. Coda is the authority: its「读取来源」(PluginSources.readSource) reads a
+// plugin with the same rules, and wins where the two differ. Each rule names where it came from in the Coda repository at
+// CODA_COMMIT; a Coda PR that changes one of them changes this file too (docs/agent-protocol.md here is synced from the same
+// commit, and test/protocol-copy.test.mjs keeps the two together).
+import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk';
+
+// The Coda commit these rules were copied from (an empty current mode is none chosen).
+export const CODA_COMMIT = '52831f0e2a09b16187f254ad2d19e270723bdc3b';
+// The ACP version Coda speaks: the SDK's (backend/package.json pins @agentclientprotocol/sdk 1.4.0, as package.json here).
+export const ACP_PROTOCOL_VERSION = PROTOCOL_VERSION;
+
+// ---- ACP (backend/src/adapters/acp.mjs) ----
+// `initialize` as Coda sends it (AcpSession.initialize): no clientInfo, these capabilities.
+export const clientCapabilities = () => ({
+  elicitation: { form: {}, url: {} },
+  session: { compaction: {}, configOptions: { boolean: {} } },
+  _meta: { coda: { waits: {} } },
+});
+// Session instructions (AcpSession.takesInstructions, initialize): ACP's unstable `systemPrompt`, sent only to an agent that
+// declares it, the same on `session/new` and `session/load`, in `append` mode, one text block (docs/agent-protocol.md「会话指令」).
+export const takesInstructions = init => init?.agentCapabilities?.sessionCapabilities?.systemPrompt != null;
+export const systemPrompt = text => ({ mode: 'append', content: [{ type: 'text', text }] });
+// Steering (AcpSession.supportsSteering, steer; docs/agent-protocol.md「插话」): declared beside the capabilities; sent only
+// while a turn of Coda's own is under way. `injected` joined it; `promptRequired` was not taken, the turn having ended;
+// anything else Coda records as unknown.
+export const STEERING = '_session/steering';
+export const supportsSteering = init => init?._meta?.steering?.supported === true;
+export const steeringParams = (sessionId, text) => ({ sessionId, prompt: [{ type: 'text', text }], _meta: { steering: { idleBehavior: 'promptRequired' } } });
+export const STEERING_OUTCOMES = ['injected', 'promptRequired'];
+// Failure categories and presentation (backend/src/domain/agent-failures.mjs).
+export function agentFailure(error) {
+  const failure = error?.data?._meta?.coda?.failure;
+  if (!record(failure)) return null;
+  return failure.kind === 'quota_exhausted' ||
+    (failure.kind === 'service_unavailable' && ['accepted', 'not_accepted'].includes(failure.input)) ? failure : null;
+}
+export function agentErrorMessage(error) {
+  const message = typeof error?.message === 'string' && error.message ? error.message : 'Agent 返回错误';
+  const detail = typeof error?.data?.message === 'string' ? error.data.message.trim() : '';
+  const text = detail && !message.includes(detail) ? `${message}\n\n${detail}` : message;
+  return agentFailure(error)?.kind === 'quota_exhausted' && !text.startsWith('额度不足') ? `额度不足\n\n${text}` : text;
+}
+// Service retry policy (backend/src/application/prompt-recovery.mjs).
+export function serviceFailure(error) {
+  const failure = agentFailure(error);
+  return failure?.kind === 'service_unavailable' ? failure : null;
+}
+// The former capacity/model-unavailable policy, shared by every agent that reports a service failure.
+export const RETRY_DELAYS = [15_000, 30_000, 60_000];
+export const continuationPrompt = '继续完成当前任务，沿用已有上下文和已完成的工作，从尚未完成的部分接着执行。';
+
+// The agent refuses until it is signed in: ACP's auth_required (signedOut).
+export const SIGNED_OUT = -32000;
+// What Coda answers an agent request it has no handler for (the SDK's): Coda handles only approvals and forms.
+export const METHOD_NOT_FOUND = -32601;
+// What an agent may say of a wait of its own (validWait, verbatim); anything else Coda drops unread.
+const record = value => value && typeof value === 'object' && !Array.isArray(value);
+export const WAIT_STATES = new Set(['waiting', 'handling', 'done', 'failed', 'cancelled']);
+const fits = (value, limit) => value === undefined || (typeof value === 'string' && value.length <= limit);
+export const validWait = p => record(p) && typeof p.sessionId === 'string' && p.sessionId.length > 0 && p.sessionId.length <= 200
+  && typeof p.waitId === 'string' && p.waitId.length > 0 && p.waitId.length <= 200 && WAIT_STATES.has(p.state)
+  && fits(p.kind, 50) && fits(p.title, 500) && fits(p.detail, 4000) && fits(p.childSessionId, 200) && fits(p.model, 200) && fits(p.outputFile, 4096)
+  && fits(p.toolCallId, 200)
+  && [p.stoppable, p.recurring].every(flag => flag === undefined || typeof flag === 'boolean')
+  && (p.at === undefined || (typeof p.at === 'string' && Number.isFinite(Date.parse(p.at))));
+// The model a session runs with, as Coda reads it (catalog().current.model): every turn Coda configures first, and refuses
+// a session whose agent names none (configure: 「适配器未报告实际模型」).
+export function currentModel(session) {
+  const model = session?.configOptions?.find?.(x => x?.category === 'model');
+  return model?.currentValue ?? session?.models?.currentModelId;
+}
+// docs/agent-protocol.md「Agent 活动」规则 3: a turn the user stops ends within this, or Coda closes the agent's process group.
+export const CANCEL_LIMIT = 30_000;
+// adapters/session-host.mjs `close`: Coda stops an agent with SIGTERM to its process group, and SIGKILL this long after.
+export const TERM_GRACE = 800;
+// adapters/acp.mjs `open` and application/option-cache.mjs: opening a session (initialize, session/new or session/load) may take this.
+export const OPEN_LIMIT = 60_000;
+
+// ---- What every process Coda runs for a plugin is given (backend/src/domain/plugins.mjs pluginEnv, cleared) ----
+// Its agents', its panels' and the commands it brings alike: Coda's own Node, the plugin's directory, its state, its settings,
+// what is plugged into its points (none here: the checker installs nothing beside it), where the plugins it depends on are
+// (`dependencies`, by ID), and CODA_ARBITER only for an instance's own backend, which the checker is not. What a process
+// inherits is cleared of them first: it never takes another plugin's for its own.
+export const PLUGIN_VARIABLES = ['CODA_NODE', 'CODA_ARBITER', 'CODA_PLUGIN_PATH', 'CODA_PLUGIN_STATE', 'CODA_PLUGIN_SETTINGS', 'CODA_PLUGIN_EXTENSIONS',
+  'CODA_PLUGIN_DEPENDENCIES'];
+export const pluginEnv = ({ pluginDir, stateDir, settings = {}, dependencies = {} }) => ({ CODA_NODE: process.execPath, CODA_PLUGIN_PATH: pluginDir,
+  CODA_PLUGIN_STATE: stateDir, CODA_PLUGIN_SETTINGS: JSON.stringify(settings),
+  ...(Object.keys(dependencies).length ? { CODA_PLUGIN_DEPENDENCIES: JSON.stringify(dependencies) } : {}) });
+export const cleared = base => Object.fromEntries(Object.entries(base).filter(([name]) => !PLUGIN_VARIABLES.includes(name)));
+// How Coda starts an agent (domain/agents.mjs launch, adapters/session-host.mjs): `sh -c` in its own process group, standard
+// error unread, the session's environment plus its plugin's.
+// A panel's command (application/panels.mjs env): no session's ID, the backend's `node` first on the PATH, and the
+// concurrency groups in use as it starts (`{ now, groups }`; none here).
+export const THREAD_ENV = 'CODA_THREAD_ID';
+export const groupsState = () => JSON.stringify({ now: Date.now(), groups: [] });
+
+// ---- Manifests (backend/src/domain/plugins.mjs, agent-plugins.mjs, panels.mjs, plugin-extensions.mjs) ----
+export const PLUGIN_ID = /^[a-z][a-z0-9-]{0,39}$/;
+export const AGENT_ID = /^[a-z][a-z0-9-]{0,39}$/;
+export const PANEL_ID = /^[a-z][a-z0-9-]{0,63}$/;
+export const POINT = /^[a-z][a-z0-9-]{0,39}$/;
+export const SETTING_KEY = /^[a-z][a-z0-9-]*(\.[a-z][A-Za-z0-9]*)+$/;
+export const CAPABILITY = /^[a-z][a-z0-9-]{0,63}$/;
+// What a plugin may contribute (backend/src/components/plugins/plugin-rules.mjs CONTRIBUTES); anything else is refused.
+export const CONTRIBUTES = ['configuration', 'capabilities', 'instructions', 'panels', 'agents', 'extensionPoints', 'extensions', 'groups', 'events', 'commands', 'gitCredentials',
+  'repositories', 'services', 'setup', 'skills', 'environment', 'path', 'endpoints', 'mcpServers', 'views', 'modelProviders'];
+// What only a plugin Coda ships may contribute, one installed from a repository or npm being refused it
+// (backend/src/components/plugins/plugin-source-rules.mjs catalogProblem): the clients do not show these in the confirmation yet.
+export const BUILTIN_ONLY = { gitCredentials: '只有 Coda 自带的插件能提供 Git 凭据', repositories: '只有 Coda 自带的插件能提供仓库列表' };
+// The bundled services a plugin turns on (`contributes.services`, docs/supervisor.md「独立服务进程」): their IDs.
+export const SERVICE = /^[a-z][a-z0-9-]{0,63}$/;
+// A command a plugin puts on every session's and step's PATH (`contributes.commands`): its name, as a shell finds it, which
+// may not be one of Coda's own; what runs for it, one line.
+export const COMMAND = /^[a-z][a-z0-9-]{0,39}$/;
+export const CODA_COMMANDS = ['coda-run', 'coda-event'];
+// An event a plugin publishes (`contributes.events`, Coda's docs/plugins.md「事件」): `<域>.<名>`, in no domain of Coda's own;
+// whether it starts the workflows subscribed to it (`starts`), and whether it ends its subject (`ends`: a run re-run after it
+// is told it again).
+export const EVENT = /^(?=.{3,100}$)[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/;
+export const CODA_EVENT_DOMAINS = ['workflow', 'session', 'user'];
+export const EVENT_LIMIT = 50;
+export const COMMAND_LIMIT = 4000;
+// A plugin's setup action (`contributes.setup`): `{ command }`, one line as a panel's command is; it may install software, so
+// the checker reads it and does not run it.
+export const SETUP_KEYS = ['command'];
+export const INSTRUCTIONS_LIMIT = 200;
+export const ICON_LIMIT = 32 * 1024;
+export const AGENT_LIMITS = { displayName: 40, modeTitle: 10, modeUnset: 20, modeNote: 100, modeId: 200, setupHint: 200, command: 4000, configFiles: 16, path: 1000 };
+export const PANEL_LIMITS = { title: 40, command: 4000, confirm: 200, note: 200 };
+
+// ---- From a repository (backend/src/domain/plugin-sources.mjs) ----
+export const SIZE_LIMIT = 10 * 1024 * 1024;
+export const SEGMENT = /^[A-Za-z0-9._-]+$/;
+export const DEPTH = 2;
+// A plugin's npm dependencies come with its package-lock.json, naming the same (manifestProblem): Coda installs them with
+// `npm ci` in the plugin's version directory.
+export const NPM = ['dependencies', 'optionalDependencies'];
+export const NPM_LOCK = 'package-lock.json';
+// Those kept in `plugins/<id>` here that Coda ships as npm dependencies, `@coda-console/<id>` (docs/plugins.md「内置插件的来源」):
+// a version of the same package may be installed over Coda's. Other sources may use the same ID once the built-in plugin is
+// uninstalled; only the target backend can check its installed state (builtinProblem).
+export const BUILTIN_HERE = ['claude', 'codex', 'codex-accounts', 'grok', 'kimi', 'opencode', 'review'];
+export const BUILTIN_SCOPE = '@coda-console/';
+// An agent, a concurrency group and a command are one plugin's (catalogProblem, claims). Those the built-in plugins declare, by
+// plugin; and `claude`, the agent ID sessions from before #1069 still store (docs/plugins.md「Agent」).
+export const BUILTIN_AGENTS = { 'claude-sdk': 'claude', codex: 'codex', grok: 'grok', kimi: 'kimi', opencode: 'opencode', claude: 'claude' };
+export const BUILTIN_GROUPS = { host: 'host' };
+export const BUILTIN_COMMANDS = { 'host-sim': 'host' };
+
+// ---- Panels (backend/src/domain/panels.mjs, application/panels.mjs) ----
+export const ITEM_TYPES = ['card', 'meter', 'stat', 'markdown', 'button', 'error'];
+export const OUTPUT_LIMIT = 64 * 1024;
+export const ARGS_LIMIT = 4 * 1024;
+export const ITEM_LIMITS = { items: 50, cardItems: 20, label: 80, identity: 200, markdown: 4000, error: 500, confirm: 200 };
+// A reading is stopped past this (docs/plugins.md「面板」).
+export const PANEL_READ_LIMIT = 30_000;

package/check/index.mjs

@@ -0,0 +1,24 @@
+// The contract check of one plugin directory: the manifest, then each agent's handshake (and with `live`, a turn) and each
+// panel's reading. Coda's「读取来源」stays the authority; this runs the same rules where a plugin is written.
+import { resolve } from 'node:path';
+import { checkAgent } from './agent.mjs';
+import { checkManifest } from './manifest.mjs';
+import { checkPanel } from './panel.mjs';
+import { Report } from './report.mjs';
+
+// `agent`: only this agent of the plugin; `manifestOnly`: nothing is run; `live`: one turn each with `prompt`.
+export async function checkPlugin(dir, { agent: only = null, manifestOnly = false, live = false, prompt, limits } = {}) {
+  const pluginDir = resolve(dir), report = new Report();
+  const plugin = checkManifest(pluginDir, report.scope('manifest'));
+  if (!plugin) return { report, plugin };
+  const agents = only ? plugin.agents.filter(a => a.id === only) : plugin.agents;
+  if (only && !agents.length) report.scope('manifest').fail('options.agent', `清单里没有能检查的 Agent ${only}`);
+  if (manifestOnly) {
+    if (agents.length || plugin.panels.length) report.scope('handshake').skip('options.manifest', '只查清单（--manifest）：不启动 Agent、不读面板');
+    return { report, plugin };
+  }
+  const { settings, dependencies } = plugin;
+  for (const agent of agents) await checkAgent({ agent, pluginDir, settings, dependencies, live, prompt, limits, say: level => report.scope(level, `Agent ${agent.id}`) });
+  if (!only) for (const panel of plugin.panels) await checkPanel({ panel, pluginDir, settings, dependencies, say: report.scope('handshake', `面板 ${panel.id}`) });
+  return { report, plugin };
+}

package/check/leftovers.mjs

@@ -0,0 +1,24 @@
+// What the checker starts and makes goes however it ends: the process groups of agents and panels it started (detached,
+// so a Ctrl-C at the terminal does not reach them) and its temporary directories. bin/check.mjs turns SIGINT and SIGTERM
+// into an exit, which runs this.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const groups = new Set(), dirs = new Set();
+process.on('exit', () => {
+  for (const pid of groups) try { process.kill(-pid, 'SIGKILL'); } catch {}
+  for (const dir of dirs) rmSync(dir, { recursive: true, force: true });
+});
+
+// A process group started (named by its leader's pid); the returned function says it is gone.
+export function group(pid) {
+  if (pid) groups.add(pid);
+  return () => groups.delete(pid);
+}
+// A new temporary directory; `remove()` removes it now.
+export function temporary(prefix) {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  dirs.add(dir);
+  return { dir, remove: () => { rmSync(dir, { recursive: true, force: true }); dirs.delete(dir); } };
+}