@bridge4dev/runner 0.52.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). */
@@ -805,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);
@@ -930,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;
@@ -968,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,
         });
     }

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

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':

package/dist/git.d.ts

@@ -1,8 +1,42 @@
+/**
+ * Why git stopped, in a sentence a person can act on.
+ *
+ * `git worktree add` prints its progress to stderr as carriage-return-overwritten
+ * frames, so a process killed mid-checkout leaves «Updating files: 1% (51/2693)»
+ * as the last thing anybody sees — a number, with no verb. The real cause lives
+ * on the error object (`killed`, `signal`, `code`) and nobody was reading it
+ * (#360). Keep the last progress frame, because «how far did it get» is the one
+ * useful thing in it, and put the cause in front of it.
+ */
+export declare function describeGitFailure(error: unknown, context?: {
+    timeoutMs?: number;
+}): string;
+/** What went wrong while building the session's workplace, in one machine-readable word. */
+export type WorktreePrepareCode = 'worktree_prepare_failed' | 'branch_taken' | 'worktree_cleanup_failed';
+/**
+ * A preparation failure that already knows its own fork point.
+ *
+ * The fork point matters precisely BECAUSE preparation failed: without it the
+ * API keeps `base_sha = null` for the session's whole life, and «Continue» can
+ * never prove that the branch it is about to adopt is the empty one this very
+ * session created a moment ago (#360, plan Р6).
+ */
+export declare class WorktreePrepareError extends Error {
+    readonly code: WorktreePrepareCode;
+    readonly baseBranch?: string;
+    readonly baseSha?: string;
+    constructor(message: string, code: WorktreePrepareCode, base?: {
+        baseBranch?: string;
+        baseSha?: string;
+    });
+}
 export interface PathValidation {
     ok: boolean;
     exists: boolean;
     isGitRepo: boolean;
     branch?: string;
+    /** The repository's own main branch, as this machine can see it without the network. */
+    defaultBranch?: string;
     error?: string;
 }
 /**
@@ -16,6 +50,23 @@ export interface PathValidation {
  * '/opt/ids'». That sentence is true and unactionable.
  */
 export declare function validateWorkspacePath(workspacePath: string): Promise<PathValidation>;
+/**
+ * The repository's main branch, read locally (ADR 0004).
+ *
+ * `origin/HEAD` is the honest answer and it is already on disk — set by `clone`,
+ * refreshed by `git remote set-head`. Never asked over the network: this runs
+ * inside a 4-second probe budget, and a repository whose origin is unreachable
+ * must still bind.
+ */
+export declare function remoteDefaultBranch(workspacePath: string): Promise<string | null>;
+/**
+ * `main`, then `master`, and only if the repository really has one.
+ *
+ * The order and the list are one decision, not two: `gitops.ts` asks the same
+ * question when «Apply» has no pinned base, and two copies would drift the day
+ * somebody adds `develop` to one of them (ADR 0004).
+ */
+export declare function firstConventionalBranch(workspacePath: string): Promise<string | null>;
 export declare function sessionShortId(sessionId: string): string;
 export declare function sessionWorktreePath(sessionId: string): string;
 /**
@@ -69,6 +120,19 @@ export declare function ensureSessionWorktree(workspacePath: string, sessionId:
     requireExistingBranch?: boolean;
     plan?: BranchPlan;
 }): Promise<SessionWorktree>;
+/**
+ * Delete a session branch that provably carries no commits (#360).
+ *
+ * Shares its safety rungs with {@link deleteSessionBranch} — prune, then the
+ * folder's own branch, then the holder — and adds the one this caller needs:
+ * the tip must still be exactly the fork point we started from. `-D`, not `-d`,
+ * because `-d` asks «is it merged into the branch THIS folder is on», which is
+ * a different question and answers «no» for a branch that is empty.
+ */
+export declare function dropEmptySessionBranch(workspacePath: string, branch: string, expectedSha: string): Promise<{
+    removed: boolean;
+    leftover?: string;
+}>;
 /**
  * DIRECT mode (session 16): the session's workplace IS the project folder.
  *