@bridge4dev/runner 0.51.0 → 0.53.0

package/dist/adapters/claude.js

@@ -5,7 +5,7 @@ import { AsyncQueue } from '../async-queue.js';
 import { log } from '../log.js';
 import { mcpConfigPath } from '../paths.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';
@@ -180,6 +180,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). */
@@ -1207,21 +1210,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 +1729,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 +1749,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);

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). */
@@ -284,6 +287,12 @@ class CodexSession {
                     sessionId: this.spec.sessionId,
                 });
             }
+            // Before the thread, not after: a model this CLI no longer offers is
+            // refused by `thread/start` itself, and the pin is stored — so the same
+            // session would fail again on every relaunch (#374).
+            await this.dropModelTheCliNoLongerHas();
+            if (this.stopped)
+                return;
             const thread = await this.openThread();
             if (this.stopped)
                 return;
@@ -799,17 +808,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);
@@ -924,19 +923,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;
@@ -962,7 +949,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,
         });
     }
@@ -1915,6 +1905,93 @@ class CodexSession {
         };
         this.emit({ type: 'capabilities', capabilities });
     }
+    /**
+     * A pinned model the installed CLI does not have is dropped before it can
+     * fail the session (#374).
+     *
+     * The pin is chosen from a catalogue that was measured the last time an agent
+     * ran on this machine, and the CLI moves underneath it: codex 0.153.4 gained
+     * `gpt-6-astra` and lost `gpt-5.3-codex-spark`, so a machine that had not run
+     * a session since the update was offering — and storing — a model that no
+     * longer exists. `turn/start` does not warn about that, it refuses, and since
+     * the pin is persisted the refusal repeats on every relaunch.
+     *
+     * Asked of `model/list` rather than recognised in an error message: matching
+     * on text is what the retry rules were explicitly moved away from in 0.44.1,
+     * because the wording is the vendor's to change.
+     *
+     * A probe that itself fails changes nothing. Diagnosing the start must not be
+     * able to prevent it — an unreachable `model/list` on a CLI that would have
+     * accepted the model would otherwise cost the user their choice.
+     */
+    async dropModelTheCliNoLongerHas() {
+        const pinned = this.model;
+        if (!pinned)
+            return;
+        let known;
+        try {
+            known = await this.probeModelIds();
+        }
+        catch (error) {
+            log.warn('codex: could not check the pinned model — leaving it alone', {
+                sessionId: this.spec.sessionId,
+                error: describe(error),
+            });
+            return;
+        }
+        // Only a COMPLETE list can convict a model. An empty answer means this build
+        // does not really implement `model/list`; a truncated one means the answer
+        // continues on a page we did not ask for. Both must read as «no verdict»,
+        // or the check invents an absence and takes the user's choice away.
+        if (!known.complete || known.ids.size === 0)
+            return;
+        if (known.ids.has(pinned))
+            return;
+        delete this.model;
+        // Said out loud, because the session is about to run on a different model
+        // than the one that was picked — silently substituting it would be worse
+        // than the failure this replaces.
+        this.notice('warn', `This server's codex no longer offers ${pinned} — starting on the agent's own default instead.`);
+        // Cleared everywhere, not just here: the API stores the pin and hands it
+        // back in the next relaunch descriptor, so a pin dropped only in memory
+        // comes back on the next restart (the same trap as QA-100 MAJOR-5).
+        //
+        // What the column ends up holding is «nothing pinned» only until the thread
+        // opens: the capabilities frame right after it reports `currentModel`, and
+        // with no pin that is the thread's own model. Either way the invariant the
+        // clearing exists for holds — what is stored is a model this CLI has.
+        this.emit({ type: 'settings', model: null });
+        if (this.effort) {
+            // The level was chosen for a model that is not there. Keeping it would
+            // apply «Ultra» to whatever the CLI defaults to, which may not have it.
+            delete this.effort;
+            this.emit({ type: 'settings', effort: null });
+        }
+    }
+    /**
+     * Every model id this CLI knows, for the pin check only — including the ones
+     * `listModels()` filters out of the PICKER.
+     *
+     * `hidden` means «do not offer this», not «this does not exist»: codex ships
+     * internal entries like `codex-auto-review` that way, and a pin is not an
+     * offer. Judging a stored pin by the picker's list would delete a model the
+     * CLI still accepts.
+     *
+     * `complete` is false when the answer is paged, and a paged answer proves
+     * nothing about what is missing.
+     */
+    async probeModelIds() {
+        const result = asRecord(await this.client.request('model/list', { limit: 50 }, 15_000));
+        const data = Array.isArray(result['data']) ? result['data'] : [];
+        const ids = new Set();
+        for (const entry of data) {
+            const row = asRecord(entry);
+            const id = str(row['id']) ?? str(row['model']);
+            if (id)
+                ids.add(id);
+        }
+        return { ids, complete: !str(result['nextCursor']) };
+    }
     async listModels() {
         const result = asRecord(await this.client.request('model/list', { limit: 50 }, 15_000));
         const data = Array.isArray(result['data']) ? result['data'] : [];

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).
  *
@@ -406,9 +450,16 @@ export type AgentEvent = {
 } | {
     type: 'capabilities';
     capabilities: AgentCapabilities;
-} | {
+}
+/**
+ * `model: null` — the pin is GONE, not merely unchanged: the installed CLI
+ * stopped offering it (#374). Spelled like `effort: null` and read the same
+ * way by the API, which clears the stored column instead of handing the dead
+ * pin back in the next descriptor.
+ */
+ | {
     type: 'settings';
-    model?: string;
+    model?: string | null;
     mode?: AgentMode;
     effort?: string | null;
 } | {

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>;

package/dist/checkpoints.js

@@ -362,6 +362,16 @@ function decodeMeta(message) {
                 ? { agentSession: parsed['agentSession'] }
                 : {}),
             ...(typeof parsed['messageSeq'] === 'number' ? { messageSeq: parsed['messageSeq'] } : {}),
+            // A whitelist, so a key absent from THIS list is a key that was written
+            // and is never read again. The mark is the whole point of #310, and a
+            // silently dropped mark reads exactly like «the folder was quiet».
+            ...(Array.isArray(parsed['busySessions'])
+                ? {
+                    busySessions: parsed['busySessions']
+                        .filter((id) => typeof id === 'string')
+                        .slice(0, MAX_BUSY_SESSIONS),
+                }
+                : {}),
         };
     }
     catch {
@@ -379,6 +389,8 @@ export async function createCheckpoint(input) {
     try {
         const store = await ensureStore(worktreePath);
         const indexFile = tempIndexFile(sessionId, 'create');
+        // Both ends of the shutter — see `CreateCheckpointInput.busySessions`.
+        const busyBefore = input.busySessions?.() ?? [];
         const built = await buildIndex(store, worktreePath, indexFile);
         if (built.tooLarge) {
             fs.rmSync(indexFile, { force: true });
@@ -386,6 +398,7 @@ export async function createCheckpoint(input) {
         }
         const { headSha, included, excluded: skippedFiles, byteCount } = built;
         const tree = await gitStore(store, worktreePath, indexFile, 'write-tree');
+        const busySessions = [...new Set([...busyBefore, ...(input.busySessions?.() ?? [])])].slice(0, MAX_BUSY_SESSIONS);
         const stagedPaths = splitZ(await gitIn(worktreePath, 'diff', '--cached', '--name-only', '-z')).filter((file) => !isSecretPath(path.join(worktreePath, file)));
         const meta = {
             kind,
@@ -397,6 +410,9 @@ export async function createCheckpoint(input) {
             ...(input.agentAnchor ? { agentAnchor: input.agentAnchor } : {}),
             ...(input.agentSession ? { agentSession: input.agentSession } : {}),
             ...(input.messageSeq === undefined ? {} : { messageSeq: input.messageSeq }),
+            // Written only when non-empty: an empty array in every ordinary record
+            // would be noise in a commit message that is read by eye during support.
+            ...(busySessions.length > 0 ? { busySessions } : {}),
         };
         const commit = await gitStore(store, worktreePath, indexFile, 'commit-tree', tree, '-m', encodeMeta(meta));
         const ordinal = await nextOrdinal(store, worktreePath, sessionId);
@@ -466,6 +482,15 @@ async function currentTree(store, worktreePath, indexFile) {
         headSha: built.headSha,
     };
 }
+/**
+ * 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 const MAX_BUSY_SESSIONS = 10;
 const MAX_PREVIEW_ENTRIES = 5_000;
 /** What a rewind to this checkpoint would do, without doing any of it. */
 export async function previewRewind(input) {
@@ -538,6 +563,13 @@ export async function previewRewind(input) {
         checkpointHeadSha: record.headSha,
         treeOid: tree,
         ...(blockedReason ? { blockedReason } : {}),
+        // Presence, not length (gotcha 433): the KEY is the warning, the ids are a
+        // courtesy that may resolve to no names at all. A marked point whose list
+        // came back empty would otherwise look trustworthy here while `applyRewind`
+        // went on refusing it.
+        ...(record.busySessions !== undefined
+            ? { untrustedFiles: { sessions: record.busySessions } }
+            : {}),
         ...(commitsSince.length ? { commitsSince } : {}),
         ...(total > MAX_PREVIEW_ENTRIES ? { truncated: true, totalChanges: total } : {}),
     };
@@ -574,6 +606,12 @@ export async function applyRewind(input) {
     if (preview.blockedReason) {
         throw new Error(rewindBlockMessage(preview.blockedReason));
     }
+    // #310. Before the safety point, not after: taking one is a write into the
+    // folder, and refusing afterwards would leave a restore point nobody asked
+    // for behind every refusal.
+    if (preview.untrustedFiles) {
+        throw new Error(UNTRUSTED_FILES_MESSAGE);
+    }
     const MOVED = 'The working tree changed while you were looking at it — open the preview again';
     // The whole state, not just the deletions (QA-120 B1). `read-tree --reset -u`
     // writes the RESTORE list as well, and that list is recomputed HERE — so a
@@ -586,7 +624,12 @@ export async function applyRewind(input) {
     if (expected.length !== echoed.length || expected.some((p, i) => p !== echoed[i])) {
         throw new Error(MOVED);
     }
-    const safetyResult = await createCheckpoint({ worktreePath, sessionId, kind: 'SAFETY' });
+    const safetyResult = await createCheckpoint({
+        worktreePath,
+        sessionId,
+        kind: 'SAFETY',
+        ...(input.busySessions ? { busySessions: input.busySessions } : {}),
+    });
     if (!safetyResult.created) {
         throw new Error(safetyResult.reason === 'too-large'
             ? 'The working tree is too large to take a safety point — the rewind was not started'
@@ -617,6 +660,12 @@ export async function applyRewind(input) {
         rewoundToKind: record.kind,
     };
 }
+/**
+ * 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 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 function rewindBlockMessage(reason) {
     switch (reason) {
         case 'head-moved':