@bridge4dev/runner 0.52.0 → 0.54.0

package/dist/adapters/claude.js

@@ -1,16 +1,21 @@
 import { query, } from '@anthropic-ai/claude-agent-sdk';
+import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { AsyncQueue } from '../async-queue.js';
 import { log } from '../log.js';
 import { mcpConfigPath } from '../paths.js';
+import { lowerPriority } from '../process-priority.js';
+import { cageSpawn, releaseSessionScope } from '../session-cage.js';
 import { evaluateToolUse, maskSecrets, maskString, } from '../policy.js';
-import { availableModes, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
+import { availableModes, cardDescription, DIRECT_BRANCH_RULE, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
 import { percentFromUtilization, RATE_WINDOW_MINUTES, rateWindowKey } from './rate-limits.js';
 import { applyUsagePercentages, parseUsageText, probeUsageText } from './claude-usage.js';
 import { claudeExecutableOption, sessionClaudePath } from '../agent-binary.js';
 /** How often `/usage` may be read. Free, but still a process. */
 const USAGE_PROBE_INTERVAL_MS = 3 * 60 * 1000;
+/** Same 2KB the SDK keeps: enough for the CLI's last words, not a log sink. */
+const STDERR_TAIL_LIMIT = 2048;
 import { answerSummary, answerValue, discussMessage, invalidationMessage, mirrorOptions, newAskId, MAX_OPTIONS, MAX_QUESTIONS, OPTION_TEXT_LIMIT, QUESTION_TEXT_LIMIT, } from './questions.js';
 // Claude adapter over the Agent SDK. Three live-verified gotchas (plan §2):
 //  1. Bare tool names in `allowedTools` auto-approve BEFORE canUseTool — we
@@ -180,6 +185,9 @@ function systemAppendFor(spec) {
         '- The user is not in a terminal, but they DO answer: when you need a decision, use the AskUserQuestion tool. It is rendered as a card in the DevBridge dashboard and the call waits — however long it takes — until a human answers it. Only ask in plain text if the tool is unavailable.',
         '- Never decide for the user when you asked them a question. If the tool comes back saying the question was withdrawn, stop and wait rather than guessing.',
         '- Never print secrets (tokens, API keys, private keys) in your output.',
+        // #361 п. 5 — only where the folder is shared. Layer 1 asks about these
+        // commands anyway; this is so the agent learns the rule before a card.
+        ...(spec.workMode === 'DIRECT' ? [DIRECT_BRANCH_RULE] : []),
     ].join('\n');
 }
 /** DevBridge's own rules, then whatever this workspace adds (session 13). */
@@ -290,6 +298,17 @@ class ClaudeSession {
     mcpConfigFile = null;
     /** Set when the write failed and the key went into argv after all. */
     mcpFallbackNotice = null;
+    /**
+     * The last few KB the CLI wrote to stderr, kept because we spawn it ourselves.
+     *
+     * The SDK's own spawn keeps this tail and appends it to the error it throws
+     * when the process dies (`. stderr: …`); a custom `spawnClaudeCodeProcess`
+     * gets no such service, and that text is load-bearing here — «no conversation
+     * found» and «No message found with message.uuid» reach `classifyRunError`
+     * exactly that way. Keeping our own copy is what makes the priority hook cost
+     * nothing diagnostically.
+     */
+    stderrTail = '';
     /** Guards against overlapping capability probes. */
     capabilitiesInFlight = false;
     /**
@@ -505,6 +524,12 @@ class ClaudeSession {
             // bundled binary, exactly as before. After C3 this pins the system
             // `claude`, which is the file the card measures and the button installs.
             ...claudeExecutableOption(),
+            // Stage 1a of the host-resources plan: the CLI, and therefore everything
+            // it starts, is spawned at nice 10 so the daemon that supervises it keeps
+            // the processor. The SDK has no post-spawn hook — replacing the spawn is
+            // the only way in, which is why `spawnAgentProcess` has to re-create the
+            // one thing the default spawn did for us (the stderr tail).
+            spawnClaudeCodeProcess: (spawnOptions) => this.spawnAgentProcess(spawnOptions),
             /**
              * Everything the machine's own Claude has (owner's call, 2026-07-30).
              *
@@ -620,6 +645,75 @@ class ClaudeSession {
         // model's window) from the moment the process is up.
         this.refreshContextUsage();
     }
+    /**
+     * Start the Claude CLI ourselves, one notch below the daemon.
+     *
+     * The SDK offers no «after spawn» callback, so the only place to renice the
+     * process is a spawn we own. Two things the default spawn did have to be done
+     * here, and neither is optional:
+     *
+     *  - **stderr must be read.** With `stdio: 'pipe'` and nobody draining it, the
+     *    CLI blocks on a full pipe after ~64KB — a session that hangs for no
+     *    visible reason. That is a worse outcome than anything nice(2) can buy.
+     *  - **the tail must be kept**, because the SDK appends it to the error it
+     *    throws on process death and `classifyRunError` reads that text. Without
+     *    it, «the resume id is unknown» comes back as a bare exit code and the
+     *    supervisor's recovery never fires.
+     *
+     * `signal` is the SDK's own forwarded abort, not the caller's: it fires only
+     * after stdin EOF and the ~2s grace, so handing it to `spawn()` kills a CLI
+     * that already had its chance to shut down cleanly.
+     */
+    spawnAgentProcess(options) {
+        // The same hook carries stage 2: the CLI, and everything it starts, goes
+        // into this session's own cgroup with its own memory ceiling. On a machine
+        // where the cage was not proved to work `cageSpawn` hands the command back
+        // untouched, and the renice below is the whole of the containment — which
+        // is exactly the state of every machine before this release.
+        const caged = cageSpawn({
+            id: this.spec.sessionId,
+            command: options.command,
+            args: options.args,
+        });
+        const child = spawn(caged.command, caged.args, {
+            cwd: options.cwd,
+            env: { ...options.env, ...caged.env },
+            stdio: ['pipe', 'pipe', 'pipe'],
+            signal: options.signal,
+            windowsHide: true,
+        });
+        // `systemd-run --scope` execs into the same pid and nice survives `exec`,
+        // so this still lands on the CLI itself.
+        lowerPriority(child.pid);
+        // Read `Result` and clear the unit once the process is gone. Only an
+        // `exit` listener: stdout belongs to the SDK, and attaching a reader to it
+        // here would put the stream in flowing mode and steal the conversation.
+        child.on('exit', () => {
+            void releaseSessionScope(caged.unit, this.spec.sessionId);
+        });
+        // `setEncoding` puts a StringDecoder on the stream, so a multi-byte
+        // character split across two reads survives — the same reason `verify.ts`
+        // decodes rather than `toString`s.
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => this.appendStderr(chunk));
+        // A read error on stderr is not a session error: the process itself is
+        // still on stdout, which is where the conversation lives.
+        child.stderr.on('error', (error) => {
+            log.debug('claude: stderr read failed', { error: String(error) });
+        });
+        return child;
+    }
+    appendStderr(chunk) {
+        if (!chunk)
+            return;
+        const next = this.stderrTail + chunk;
+        this.stderrTail = next.length > STDERR_TAIL_LIMIT ? next.slice(-STDERR_TAIL_LIMIT) : next;
+    }
+    /** What the CLI said on its way out, in the SDK's own wording. */
+    stderrSuffix() {
+        const tail = this.stderrTail.trim();
+        return tail ? `. stderr: ${tail}` : '';
+    }
     /**
      * Write this session's MCP config to a 0600 file and return its path, or null
      * if anything went wrong (the caller then keeps the old inline shape).
@@ -1207,21 +1301,10 @@ class ClaudeSession {
         for (const [requestId, pending] of [...this.pending]) {
             if (!pending.fromPolicy)
                 continue;
-            const verdict = evaluateToolUse(pending.toolName, pending.input, {
-                trustMode: this.spec.trustMode,
-                mode: this.mode,
-                ...(this.spec.agentAutoCommit === undefined
-                    ? {}
-                    : { agentAutoCommit: this.spec.agentAutoCommit }),
-                ...(this.spec.agentPromptFile ? { agentPromptFile: this.spec.agentPromptFile } : {}),
-                // The fourth entry point into `evaluateToolUse`, and it was the one
-                // that did not carry the git policy (QA-134 MINOR-1). Safe direction —
-                // without the fields everything resolves to «refused» and this function
-                // only ever releases — but a project that allows `git clean` would have
-                // left a parked card unreleased in Claude while Codex released it.
-                ...(this.spec.gitPolicy ?? {}),
-                worktreePath: this.spec.cwd,
-            });
+            // The fourth entry point into `evaluateToolUse`, and the one that was
+            // once assembled by hand without the git policy (QA-134 MINOR-1). All
+            // four read the same builder now, so a field can only be forgotten once.
+            const verdict = evaluateToolUse(pending.toolName, pending.input, policyContextFor(this.spec, this.mode));
             if (verdict.decision !== 'allow')
                 continue;
             this.emit({
@@ -1737,21 +1820,7 @@ class ClaudeSession {
             });
             return this.waitForAnswer(opts, toolName);
         }
-        const verdict = evaluateToolUse(toolName, input, {
-            trustMode: this.spec.trustMode,
-            // Ticket #156: the missing argument. Everything else in this object was
-            // already here; the session's own mode was not, so «Auto» decided nothing.
-            mode: this.mode,
-            ...(this.spec.agentAutoCommit === undefined
-                ? {}
-                : { agentAutoCommit: this.spec.agentAutoCommit }),
-            ...(this.spec.agentPromptFile ? { agentPromptFile: this.spec.agentPromptFile } : {}),
-            // Session 18. Spread WHOLE rather than field by field: `resolveGitPolicy`
-            // gives every absent field its safe reading, and an object assembled here
-            // with three of the four would be a fourth place to get a polarity wrong.
-            ...(this.spec.gitPolicy ?? {}),
-            worktreePath: this.spec.cwd,
-        });
+        const verdict = evaluateToolUse(toolName, input, policyContextFor(this.spec, this.mode));
         if (verdict.decision === 'allow') {
             return { behavior: 'allow', updatedInput: input };
         }
@@ -1771,7 +1840,12 @@ class ClaudeSession {
             requestId: opts.requestId,
             toolName,
             title: opts.title ?? `Allow ${toolName}?`,
-            ...(opts.description ? { description: opts.description } : {}),
+            // The policy's own sentence first: it is the reason this card exists, and
+            // without it the person is asked to approve a command with no hint of
+            // what the runner objected to (#361 п. 5).
+            ...(cardDescription(verdict, opts.description)
+                ? { description: cardDescription(verdict, opts.description) }
+                : {}),
             input: truncateInput(input),
         });
         return this.waitForAnswer(opts, toolName, input);
@@ -2364,7 +2438,11 @@ class ClaudeSession {
             }
         }
         catch (error) {
-            const message = maskString(String(error instanceof Error ? error.message : error));
+            // The stderr tail rides along because we spawn the CLI ourselves now (see
+            // `spawnAgentProcess`) — the SDK used to add it and cannot any more. This
+            // catch IS the process falling over, which is the only case the SDK
+            // appended it to as well.
+            const message = maskString(String(error instanceof Error ? error.message : error) + this.stderrSuffix());
             const code = errorCode(message);
             this.emit({
                 type: 'error',

package/dist/adapters/codex-protocol.d.ts

@@ -30,6 +30,13 @@ export interface AppServerOptions {
     args: string[];
     cwd?: string;
     env: Record<string, string>;
+    /**
+     * Whose session this app-server belongs to — the name of its cgroup cage
+     * (`session-cage.ts`). Required rather than optional: a spawn with no id
+     * cannot be caged, and a session running outside the cage while everything
+     * reports that the cage is on is the one failure this feature must not have.
+     */
+    sessionId: string;
     onNotification: (method: string, params: Record<string, unknown>) => void;
     onServerRequest: (request: ServerRequest) => void;
     /** Fired once when the child is gone — the session's end-of-stream signal. */
@@ -47,6 +54,10 @@ export declare class AppServerClient {
     private nextId;
     private stdoutBuffer;
     private exited;
+    /** The scope this process runs in, or null when the machine has no cage. */
+    private readonly scopeUnit;
+    /** Has the far end said anything at all? Reads the start window — see below. */
+    private sawOutput;
     constructor(opts: AppServerOptions);
     get pid(): number | undefined;
     get alive(): boolean;

package/dist/adapters/codex-protocol.js

@@ -1,5 +1,7 @@
 import { spawn } from 'node:child_process';
 import { log } from '../log.js';
+import { lowerPriority } from '../process-priority.js';
+import { cageSpawn, killedBeforeExec, releaseSessionScope } from '../session-cage.js';
 export class RpcError extends Error {
     code;
     method;
@@ -36,15 +38,32 @@ export class AppServerClient {
     nextId = 1;
     stdoutBuffer = '';
     exited = false;
+    /** The scope this process runs in, or null when the machine has no cage. */
+    scopeUnit;
+    /** Has the far end said anything at all? Reads the start window — see below. */
+    sawOutput = false;
     constructor(opts) {
         this.opts = opts;
-        this.child = spawn(opts.command, opts.args, {
+        // `codex app-server` is the root of everything this session will run, so
+        // this is where the cage goes: the scope holds the whole tree below it, and
+        // the ceiling is per session rather than per machine.
+        const caged = cageSpawn({ id: opts.sessionId, command: opts.command, args: opts.args });
+        this.scopeUnit = caged.unit;
+        this.child = spawn(caged.command, caged.args, {
             ...(opts.cwd ? { cwd: opts.cwd } : {}),
-            env: opts.env,
+            env: { ...opts.env, ...caged.env },
             stdio: ['pipe', 'pipe', 'pipe'],
         });
+        // Before a single byte of protocol, and still worth doing inside a scope:
+        // nice is inherited at fork AND across `exec`, so renicing `systemd-run`
+        // renices the app-server it turns into. On a machine with no cage this is
+        // the only containment there is.
+        lowerPriority(this.child.pid);
         this.child.stdout.setEncoding('utf8');
-        this.child.stdout.on('data', (chunk) => this.onStdout(chunk));
+        this.child.stdout.on('data', (chunk) => {
+            this.sawOutput = true;
+            this.onStdout(chunk);
+        });
         this.child.stderr.setEncoding('utf8');
         this.child.stderr.on('data', (chunk) => opts.onStderr?.(chunk));
         this.child.on('error', (error) => {
@@ -67,6 +86,25 @@ export class AppServerClient {
         if (this.exited)
             return;
         this.exited = true;
+        if (killedBeforeExec({
+            code: info.code,
+            signal: info.signal,
+            sawOutput: this.sawOutput,
+            caged: this.scopeUnit !== null,
+        })) {
+            // Not a silent death of the agent. Starting a scope takes 0.07–2.5 s (up
+            // to 2741 ms on a loaded machine), and a stop inside that window signals
+            // `systemd-run` before it has exec'd — so the process that got SIGTERM
+            // was the wrapper, and `codex app-server` never existed. Said plainly
+            // here, because from the outside it is indistinguishable from a crash
+            // with an empty stdout.
+            log.warn('codex: the session was stopped before its process started', {
+                unit: this.scopeUnit,
+            });
+        }
+        // Read the cause, THEN let systemd forget the unit: `Result=oom-kill` is
+        // only readable while the failed scope is still there (`session-cage.ts`).
+        void releaseSessionScope(this.scopeUnit, this.opts.sessionId);
         this.opts.onExit(info);
     }
     failAll(error) {

package/dist/adapters/codex.js

@@ -5,7 +5,7 @@ import { RUNNER_VERSION } from '../version.js';
 import { repairCodexAuth } from './codex-home.js';
 import { AppServerClient, asRecord, num, RpcError, RpcTimeoutError, str, } from './codex-protocol.js';
 import { truncate } from './claude.js';
-import { availableModes, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
+import { availableModes, cardDescription, DIRECT_BRANCH_RULE, MODE_REFUSED_TEXT, MODE_WITHDRAWN_TEXT, policyContextFor, DEVBRIDGE_MCP_SERVER_NAME, } from './types.js';
 import { clampPercent, rateWindowKeyFromMinutes } from './rate-limits.js';
 import { answerSummary, invalidationMessage, mirrorOptions, newAskId, MAX_OPTIONS, MAX_QUESTIONS, OPTION_TEXT_LIMIT, QUESTION_TEXT_LIMIT, } from './questions.js';
 // Codex adapter over `codex app-server` (stage C). The normalized AgentEvent
@@ -83,6 +83,9 @@ function systemAppendFor(spec) {
         '- If DevBridge MCP tools are available and the task mentions tickets: fetch the ticket first, set its status to IN_PROGRESS when you start and READY_FOR_REVIEW when your implementation is complete, and leave a short summary comment.',
         '- The user is not in a terminal: if you need a decision, use your question tool or ask in plain text and end your turn.',
         '- Never print secrets (tokens, API keys, private keys) in your output.',
+        // #361 п. 5 — only where the folder is shared. Layer 1 asks about these
+        // commands anyway; this is so the agent learns the rule before a card.
+        ...(spec.workMode === 'DIRECT' ? [DIRECT_BRANCH_RULE] : []),
     ].join('\n');
 }
 /** DevBridge's own rules, then whatever this workspace adds (session 13). */
@@ -217,6 +220,10 @@ class CodexSession {
                 command: CODEX_BIN,
                 args: ['app-server'],
                 cwd: spec.cwd,
+                // Names this session's cgroup cage (`session-cage.ts`). Not part of
+                // `wiring`: an injected client is a scripted object with no process
+                // under it, and there is nothing to cage.
+                sessionId: spec.sessionId,
                 ...wiring,
             });
         if (this.modeRefusedAtLaunch) {
@@ -805,17 +812,7 @@ class CodexSession {
         for (const [requestId, pending] of [...this.approvals]) {
             if (!pending.policy)
                 continue;
-            const verdict = evaluateToolUse(pending.policy.tool, pending.policy.input, {
-                trustMode: this.spec.trustMode,
-                mode: this.mode,
-                ...(this.spec.agentAutoCommit === undefined
-                    ? {}
-                    : { agentAutoCommit: this.spec.agentAutoCommit }),
-                ...(this.spec.agentPromptFile ? { agentPromptFile: this.spec.agentPromptFile } : {}),
-                // Session 18 — spread whole; see the note in the Claude adapter.
-                ...(this.spec.gitPolicy ?? {}),
-                worktreePath: this.spec.cwd,
-            });
+            const verdict = evaluateToolUse(pending.policy.tool, pending.policy.input, policyContextFor(this.spec, this.mode));
             if (verdict.decision !== 'allow')
                 continue;
             this.approvals.delete(requestId);
@@ -930,19 +927,7 @@ class CodexSession {
         const enriched = this.describeApproval(request);
         const verdict = enriched.forceAsk
             ? { decision: 'ask', reason: 'details unavailable' }
-            : evaluateToolUse(enriched.policyTool, enriched.policyInput, {
-                trustMode: this.spec.trustMode,
-                // Ticket #156, the same missing argument as in the Claude adapter —
-                // both bridges call one policy, so both have to hand it the mode.
-                mode: this.mode,
-                ...(this.spec.agentAutoCommit === undefined
-                    ? {}
-                    : { agentAutoCommit: this.spec.agentAutoCommit }),
-                ...(this.spec.agentPromptFile ? { agentPromptFile: this.spec.agentPromptFile } : {}),
-                // Session 18 — spread whole; see the note in the Claude adapter.
-                ...(this.spec.gitPolicy ?? {}),
-                worktreePath: this.spec.cwd,
-            });
+            : evaluateToolUse(enriched.policyTool, enriched.policyInput, policyContextFor(this.spec, this.mode));
         if (verdict.decision === 'allow') {
             this.client.respond(request.id, { decision: 'accept' });
             return;
@@ -968,7 +953,10 @@ class CodexSession {
             requestId,
             toolName: enriched.toolName,
             title: enriched.title,
-            ...(enriched.description ? { description: enriched.description } : {}),
+            // See the note in the Claude adapter — one policy, two bridges, one card.
+            ...(cardDescription(verdict, enriched.description)
+                ? { description: cardDescription(verdict, enriched.description) }
+                : {}),
             input: enriched.input,
         });
     }

package/dist/adapters/types.d.ts

@@ -1,4 +1,4 @@
-import type { AgentGitPolicy, TrustMode } from '../policy.js';
+import type { AgentGitPolicy, PolicyContext, PolicyDecision, TrustMode } from '../policy.js';
 export interface McpConfig {
     url: string;
     token: string;
@@ -256,6 +256,16 @@ export interface SessionSpec {
      * part `agentAutoCommit` does not do.
      */
     gitPolicy?: AgentGitPolicy;
+    /**
+     * Does this session work in the project folder itself (`DIRECT`) or in a
+     * worktree of its own (`BRANCH`)? Same reason to be here as
+     * `agentPromptFile`: it lands in `PolicyContext` and answers the same
+     * question — may this Bash call go through (#361 п. 5, ADR 0004).
+     *
+     * It also decides one line of the system prompt, which `agentPromptFile`
+     * does not do.
+     */
+    workMode?: 'DIRECT' | 'BRANCH';
     mode?: AgentMode;
     model?: string;
     effort?: string;
@@ -278,6 +288,40 @@ export interface SessionSpec {
     mcp?: McpConfig;
     maxBudgetUsd?: number;
 }
+/**
+ * The one place a `SessionSpec` becomes a `PolicyContext`.
+ *
+ * There are four entry points into `evaluateToolUse` — two per adapter — and
+ * every one of them used to assemble this object by hand. QA-134 MINOR-1 is
+ * what that costs: one of the four had been written before the git policy
+ * existed and never learned about it, so a project that allowed `git clean`
+ * left a parked card unreleased in Claude while Codex released it. The next
+ * field to be added would have had four chances to be forgotten; now it has
+ * one place to be added.
+ *
+ * Optional fields are spread rather than set to `undefined`, because
+ * `resolveGitPolicy` and its neighbours read «absent» as a decision.
+ */
+export declare function policyContextFor(spec: SessionSpec, mode: AgentMode | undefined): PolicyContext;
+/**
+ * What the permission card should say under its title.
+ *
+ * The policy's explanation first, the tool's own description after it: the
+ * person is answering «may this run», and «why are you asking me» is the half
+ * that was missing (#361 п. 5). Returns undefined when there is nothing to add.
+ */
+export declare function cardDescription(verdict: PolicyDecision, own: string | undefined): string | undefined;
+/**
+ * The one sentence of the system prompt that only DIRECT sessions get
+ * (#361 п. 5, ADR 0004).
+ *
+ * A constant rather than a line in each adapter, because the two
+ * `systemAppendFor` texts are already two hand-synced copies of each other and
+ * a third divergence was not worth having. Layer 1 asks about these commands
+ * anyway — this exists so the agent does not have to learn the rule by walking
+ * into a card.
+ */
+export declare const DIRECT_BRANCH_RULE = "- This session works directly in the project folder, which other sessions and people share. Stay on the current branch: do not `git checkout <branch>` or `git switch` here. To put a file back use `git checkout -- <path>` or `git restore <path>`.";
 /**
  * One question inside an agent's question call (session 12).
  *

package/dist/adapters/types.js

@@ -33,6 +33,59 @@ export const MODE_WITHDRAWN_TEXT = 'This project was just set to Strict trust, s
 export function availableModes(trustMode) {
     return trustMode === 'STRICT' ? AGENT_MODES.filter((mode) => mode !== 'full') : [...AGENT_MODES];
 }
+/**
+ * The one place a `SessionSpec` becomes a `PolicyContext`.
+ *
+ * There are four entry points into `evaluateToolUse` — two per adapter — and
+ * every one of them used to assemble this object by hand. QA-134 MINOR-1 is
+ * what that costs: one of the four had been written before the git policy
+ * existed and never learned about it, so a project that allowed `git clean`
+ * left a parked card unreleased in Claude while Codex released it. The next
+ * field to be added would have had four chances to be forgotten; now it has
+ * one place to be added.
+ *
+ * Optional fields are spread rather than set to `undefined`, because
+ * `resolveGitPolicy` and its neighbours read «absent» as a decision.
+ */
+export function policyContextFor(spec, mode) {
+    return {
+        trustMode: spec.trustMode,
+        // Ticket #156: the session's own mode. For four sessions it was missing
+        // here, so «Auto» moved a value that the function deciding whether to ask
+        // had never heard of.
+        ...(mode ? { mode } : {}),
+        ...(spec.agentAutoCommit === undefined ? {} : { agentAutoCommit: spec.agentAutoCommit }),
+        ...(spec.agentPromptFile ? { agentPromptFile: spec.agentPromptFile } : {}),
+        ...(spec.workMode ? { workMode: spec.workMode } : {}),
+        // Session 18. Spread WHOLE rather than field by field: `resolveGitPolicy`
+        // gives every absent field its safe reading, and an object assembled here
+        // with three of the four would be a fourth place to get a polarity wrong.
+        ...(spec.gitPolicy ?? {}),
+        worktreePath: spec.cwd,
+    };
+}
+/**
+ * What the permission card should say under its title.
+ *
+ * The policy's explanation first, the tool's own description after it: the
+ * person is answering «may this run», and «why are you asking me» is the half
+ * that was missing (#361 п. 5). Returns undefined when there is nothing to add.
+ */
+export function cardDescription(verdict, own) {
+    const parts = [verdict.explain, own].filter((part) => Boolean(part));
+    return parts.length > 0 ? parts.join('\n\n') : undefined;
+}
+/**
+ * The one sentence of the system prompt that only DIRECT sessions get
+ * (#361 п. 5, ADR 0004).
+ *
+ * A constant rather than a line in each adapter, because the two
+ * `systemAppendFor` texts are already two hand-synced copies of each other and
+ * a third divergence was not worth having. Layer 1 asks about these commands
+ * anyway — this exists so the agent does not have to learn the rule by walking
+ * into a card.
+ */
+export const DIRECT_BRANCH_RULE = '- This session works directly in the project folder, which other sessions and people share. Stay on the current branch: do not `git checkout <branch>` or `git switch` here. To put a file back use `git checkout -- <path>` or `git restore <path>`.';
 /**
  * The name our MCP server is registered under inside an agent session.
  *

package/dist/checkpoints.d.ts

@@ -44,6 +44,21 @@ export interface CheckpointRecord {
     agentSession?: string;
     /** Feed seq of the user message this point sits in front of. */
     messageSeq?: number;
+    /**
+     * Other sessions that were mid-turn in this FOLDER while the snapshot was
+     * taken (#310).
+     *
+     * A DIRECT session shares its working tree with every other session on the
+     * same project, so a point taken while a neighbour was writing files holds
+     * half of that neighbour's work — rewinding files to it would throw away
+     * whatever they did after the shutter and before the shutter closed. The
+     * conversation is still safe to rewind, and that is the whole distinction.
+     *
+     * Absent means «the folder was quiet», which is also what every record
+     * written before this release means — those were only ever taken in a quiet
+     * folder, because a busy one refused to take them at all.
+     */
+    busySessions?: string[];
 }
 export interface CreateCheckpointInput {
     worktreePath: string;
@@ -53,6 +68,18 @@ export interface CreateCheckpointInput {
     messageSeq?: number;
     agentAnchor?: string;
     agentSession?: string;
+    /**
+     * Who else is working in this folder — asked as a QUESTION, not handed as an
+     * answer (#310).
+     *
+     * A getter, because the honest reading is «while the snapshot was being
+     * taken», and taking it is not instantaneous: `buildIndex` walks the tree and
+     * `write-tree` hashes it. Called at both ends and unioned, so a neighbour who
+     * started or stopped in between is still counted. It cannot be recorded
+     * afterwards either — the metadata is the commit message, and a commit's
+     * message cannot be appended to once it exists.
+     */
+    busySessions?: () => string[];
 }
 export type CreateCheckpointResult = {
     created: true;
@@ -97,6 +124,20 @@ export interface RewindPreview {
     /** The change is larger than the dialog can honestly list — see `blockedReason`. */
     truncated?: boolean;
     totalChanges?: number;
+    /**
+     * This point was taken while somebody else was working in the folder, so its
+     * FILES cannot be trusted — only the conversation can be rewound to it (#310).
+     *
+     * Deliberately not a `blockedReason`: that field is a closed enum on the API
+     * and a new member would be rejected there, and in the dialog it hides the
+     * «History only» button — which is the one thing that still works here.
+     *
+     * The presence of the key carries the warning; the ids are a courtesy that
+     * may resolve to no names at all (gotcha 433).
+     */
+    untrustedFiles?: {
+        sessions: string[];
+    };
 }
 /**
  * Take a restore point for this worktree.
@@ -106,6 +147,15 @@ export interface RewindPreview {
  */
 export declare function createCheckpoint(input: CreateCheckpointInput): Promise<CreateCheckpointResult>;
 export declare function listCheckpoints(worktreePath: string, sessionId: string): Promise<CheckpointRecord[]>;
+/**
+ * How many neighbour ids a restore point carries (#310).
+ *
+ * The same number as the API's schema and the runner's event: the mark itself
+ * is the warning, the names are a courtesy, and a folder with eleven busy
+ * sessions is not eleven times more dangerous than one with ten. Gotcha 433 —
+ * a cap on a courtesy must degrade, never reject.
+ */
+export declare const MAX_BUSY_SESSIONS = 10;
 /** What a rewind to this checkpoint would do, without doing any of it. */
 export declare function previewRewind(input: {
     worktreePath: string;
@@ -152,7 +202,19 @@ export declare function applyRewind(input: {
      * that is doing nothing wrong. Present ⇒ checked.
      */
     expectedTreeOid?: string;
+    /**
+     * Who else is working in this folder — for the SAFETY point this rewind takes
+     * on its way out (#310). Same getter, same reason as in
+     * {@link CreateCheckpointInput}.
+     */
+    busySessions?: () => string[];
 }): Promise<ApplyRewindResult>;
+/**
+ * Said when the files of a restore point cannot be trusted (#310). Its own
+ * sentence rather than a `blockedReason`, for the reason written on
+ * `RewindPreview.untrustedFiles`.
+ */
+export declare const UNTRUSTED_FILES_MESSAGE = "The files at this restore point cannot be trusted: another session was working in this folder when it was taken. Only the conversation can be rewound to it.";
 export declare function rewindBlockMessage(reason: NonNullable<RewindPreview['blockedReason']>): string;
 /** Drop every restore point of one session (session deleted or purged). */
 export declare function dropCheckpoints(worktreePath: string, sessionId: string): Promise<void>;