@bridge4dev/runner 0.52.0 → 0.53.0

package/dist/policy.d.ts

@@ -92,10 +92,40 @@ export interface PolicyContext extends AgentGitPolicy {
      * what makes a change visible when this cannot prevent it.
      */
     agentPromptFile?: string;
+    /**
+     * Does this session work in the project folder itself, or in a worktree of
+     * its own? (#361 п. 5, ADR 0004)
+     *
+     * Only DIRECT sessions share a folder — and therefore share ONE current
+     * branch with every other session and person working in it. `git checkout
+     * <branch>` there is not a local move: it rewrites the working tree under
+     * everybody at once, which is the same class of act as `git reset --hard`.
+     *
+     * **`undefined` means «apply the rule».** Deliberately the opposite polarity
+     * to `SessionDescriptor.workMode` in `protocol.ts`, where a missing value
+     * means BRANCH when the folder is prepared. Different field, different
+     * question: there the safe reading is «build a worktree», here it is «ask
+     * first». Gotcha 193 — resolve «unknown» once, in the safe direction, and say
+     * out loud when two neighbours resolve it in opposite ways.
+     */
+    workMode?: 'DIRECT' | 'BRANCH';
 }
 export interface PolicyDecision {
     decision: 'allow' | 'deny' | 'ask';
     reason: string;
+    /**
+     * A sentence written FOR THE PERSON answering the card (#361 п. 5).
+     *
+     * `reason` is a label — «strict mode», «command needs approval» — and it goes
+     * to the log and, on a denial, to the feed. A card carries neither: it shows
+     * a title, a description and the input, and the reason is dropped. So a rule
+     * that asks a question the human cannot answer without knowing WHY has to say
+     * why here, and the adapters put it on the card.
+     *
+     * Only set where there is something worth reading; absent means «the card's
+     * own title says enough».
+     */
+    explain?: string;
 }
 export declare function maskString(value: string): string;
 /** Deep-mask every string in a JSON-ish structure (payloads leaving the server). */
@@ -125,6 +155,14 @@ export declare function isGitInternalPath(p: string): boolean;
  * DELIBERATELY switched something on — with the shipped defaults the first
  * check refuses every push and the rest never run, which is byte for byte the
  * behaviour of the four regexes it replaces.
+ *
+ * **A `deny` anywhere beats an `ask` anywhere.** Until #361 every decision here
+ * was a refusal, so returning the first one found in the first segment was the
+ * same thing as returning the worst one. With an `ask` in the set that stopped
+ * being true: `git checkout main && git push origin main` would have shown a
+ * card about the checkout, and confirming it would have run the push this
+ * function exists to refuse. So `deny` returns at once, `ask` is remembered,
+ * and the loop reads to the end.
  */
 export declare function evaluateGitPolicy(command: string, ctx: PolicyContext): PolicyDecision | null;
 export interface RecipeCommandContext {

package/dist/policy.js

@@ -517,6 +517,189 @@ function parsePush(segment) {
         remoteExec,
     };
 }
+const GIT_CHECKOUT = String.raw `\bgit\s+${FLAGS}(?:checkout|switch)\b`;
+/** A word whose meaning only the shell knows — `$BRANCH`, `` `cat .b` ``, `\x`. */
+const SHELL_UNRESOLVED = /[$`\\]/;
+/**
+ * A REVISION expression — `main~1`, `v2^`, `abc123^{commit}`.
+ *
+ * Not a branch name (git's own ref grammar forbids `~` and `^` in one) and
+ * emphatically not a pathspec: checking one out leaves the folder on no branch
+ * at all. Grouping it with the pathspecs below, on the grounds that it «cannot
+ * be a branch», was exactly backwards — `git checkout main~1` detaches the
+ * shared folder for everybody in it, silently.
+ */
+const REVISION_EXPRESSION = /[~^]/;
+/**
+ * An operand git could never read as a branch name — because it is a PATH.
+ *
+ * Not a guess about intent, a fact about the ref grammar: `*`, `?`, `[` and
+ * spaces are forbidden in a branch name, a leading `:` is git's own magic
+ * pathspec prefix, and `.`, `./x`, `../x`, `/x`, `x/` are paths by shape.
+ * A closing `]` is deliberately NOT here: `git check-ref-format --branch 'wip]1'`
+ * accepts it, so calling it impossible-in-a-branch would have waved through a
+ * real branch switch (QA #255).
+ * Everything else stays ambiguous, and git resolves ambiguity in favour of the
+ * BRANCH — which is why an ambiguous word asks rather than being waved through.
+ *
+ * Characters that are merely UNUSUAL in a branch name (a backslash, a control
+ * character, `@{`) are deliberately absent: they end up in the ambiguous pile,
+ * which asks. Every gap here has to fall on that side.
+ */
+function cannotBeBranch(operand) {
+    if (operand === '.' || operand === '..')
+        return true;
+    if (/^\.{1,2}\//.test(operand) || operand.startsWith('/'))
+        return true;
+    if (operand.startsWith(':'))
+        return true;
+    if (operand.endsWith('/'))
+        return true;
+    return /[*?[ ]/.test(operand);
+}
+/**
+ * The agent chose this word, so it is quoted back at a length WE choose.
+ *
+ * This string becomes the description of a permission card and travels in an
+ * event payload the gateway caps; a single implausibly long operand should cost
+ * a few characters of the sentence, never the card.
+ */
+function shortOperand(operand) {
+    return operand.length > 60 ? `${operand.slice(0, 60)}…` : operand;
+}
+const RESTORE_A_FILE = 'To put a file back use `git checkout -- <path>` or `git restore <path>`: those touch files only.';
+const MOVES_THE_FOLDER = 'this session works in the project folder itself, so switching branches there changes the files under every other session and person working in it';
+/**
+ * Does this segment move the shared folder onto another branch? (#361 п. 5)
+ *
+ * Parsed rather than pattern matched, for the same reason as `parsePush`: the
+ * difference between «restore this file» and «move everybody to another
+ * branch» is one `--` in the middle of the arguments, and no regex answers
+ * that. Synchronous and free of child processes — gotcha 196: this runs on
+ * every Bash call of every session on the machine.
+ *
+ * Returns null when the segment is not a checkout at all, or is one of the
+ * forms that provably only touches files.
+ */
+function parseCheckout(segment) {
+    if (!new RegExp(GIT_CHECKOUT).test(segment))
+        return null;
+    const tokens = words(segment);
+    const at = tokens.findIndex((token) => token === 'checkout' || token === 'switch');
+    if (at === -1) {
+        // The regex matched but the verb is hidden by a form this tokenizer does
+        // not model. Report the moving reading — «I could not parse it» must never
+        // become «go ahead».
+        return {
+            reason: `This git command could not be read well enough to tell whether it moves the folder onto another branch, and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+        };
+    }
+    if (tokens[at] === 'switch') {
+        // `git switch` has no file form at all — it exists to move a branch.
+        return {
+            reason: `\`git switch\` moves the folder onto another branch, and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+        };
+    }
+    const rest = tokens.slice(at + 1);
+    /**
+     * `--` names paths only when there ARE paths after it.
+     *
+     * The obvious reading — «a `--` anywhere means this is a file command» — is
+     * wrong, and wrong in the direction that matters. Verified on git 2.43:
+     * `git checkout feature --` prints «Switched to branch 'feature'», and
+     * `git checkout -b tmp --` creates the branch and moves onto it. Git's own
+     * parser treats a trailing `--` as «the word before me is definitely a ref»,
+     * which is the opposite of what it looks like. So the separator is only a
+     * separator when it separates something.
+     */
+    const dashDash = rest.indexOf('--');
+    if (dashDash !== -1 && dashDash < rest.length - 1)
+        return null;
+    const head = dashDash === -1 ? rest : rest.slice(0, dashDash);
+    let fileOnly = false;
+    let movingFlag = null;
+    const operands = [];
+    for (const token of head) {
+        if (token.startsWith('--')) {
+            const name = token.split('=')[0] ?? token;
+            if (name === '--ours' ||
+                name === '--theirs' ||
+                name === '--patch' ||
+                name === '--pathspec-from-file' ||
+                name === '--pathspec-file-nul') {
+                fileOnly = true;
+            }
+            else if (name === '--orphan' ||
+                name === '--detach' ||
+                name === '--track' ||
+                name === '--merge' ||
+                name === '--force') {
+                movingFlag ??= name;
+            }
+            continue;
+        }
+        // A lone `-` is an operand: «the branch I was on before».
+        if (token.startsWith('-') && token.length > 1) {
+            for (const letter of token.slice(1)) {
+                if (letter === 'p')
+                    fileOnly = true;
+                else if ('bBtmf'.includes(letter))
+                    movingFlag ??= `-${letter}`;
+            }
+            continue;
+        }
+        operands.push(token);
+    }
+    if (fileOnly)
+        return null;
+    if (movingFlag) {
+        return {
+            reason: `\`git checkout ${shortOperand(movingFlag)}\` moves the folder onto another branch, and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+        };
+    }
+    // `git checkout` on its own restores nothing and moves nothing — but only
+    // when the arguments really are all of them. `echo feature | xargs git
+    // checkout` is a checkout whose operand is handed to it by the program in
+    // front of it, and this parser cannot see it: the segment ends with a bare
+    // `git checkout` and looks harmless. So «no operands» is only an answer when
+    // git is the thing being run, not an argument to something else.
+    if (operands.length === 0) {
+        const first = tokens.find((token) => !/^[A-Za-z_][A-Za-z0-9_]*=/.test(token));
+        if (first === 'git')
+            return null;
+        return {
+            reason: `This \`git checkout\` gets its arguments from another program, so the runner cannot tell whether it moves the folder onto another branch, and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+        };
+    }
+    for (const operand of operands) {
+        if (SHELL_UNRESOLVED.test(operand)) {
+            return {
+                reason: `This \`git checkout\` names its target through the shell, so the runner cannot tell whether it is a file or a branch — and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+            };
+        }
+        if (operand === '-') {
+            return {
+                reason: `\`git checkout -\` moves the folder back onto the previous branch, and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+            };
+        }
+        if (/^(HEAD|@)([~^].*)?$/.test(operand) ||
+            /^[0-9a-f]{7,40}$/i.test(operand) ||
+            REVISION_EXPRESSION.test(operand)) {
+            return {
+                reason: `\`git checkout ${shortOperand(operand)}\` leaves the folder on no branch at all (detached HEAD), and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+            };
+        }
+        if (cannotBeBranch(operand))
+            continue;
+        // A bare word. Git reads it as a BRANCH first and only falls back to a
+        // path, so «I meant the file» is not something this can assume — and the
+        // unambiguous spelling costs the agent three characters.
+        return {
+            reason: `\`git checkout ${shortOperand(operand)}\` is read by git as a branch first, and ${MOVES_THE_FOLDER}. ${RESTORE_A_FILE}`,
+        };
+    }
+    return null;
+}
 /**
  * The project's git rules, applied to one Bash command.
  *
@@ -525,9 +708,18 @@ function parsePush(segment) {
  * DELIBERATELY switched something on — with the shipped defaults the first
  * check refuses every push and the rest never run, which is byte for byte the
  * behaviour of the four regexes it replaces.
+ *
+ * **A `deny` anywhere beats an `ask` anywhere.** Until #361 every decision here
+ * was a refusal, so returning the first one found in the first segment was the
+ * same thing as returning the worst one. With an `ask` in the set that stopped
+ * being true: `git checkout main && git push origin main` would have shown a
+ * card about the checkout, and confirming it would have run the push this
+ * function exists to refuse. So `deny` returns at once, `ask` is remembered,
+ * and the loop reads to the end.
  */
 export function evaluateGitPolicy(command, ctx) {
     const policy = resolveGitPolicy(ctx);
+    let asked = null;
     for (const segment of commandSegments(command)) {
         if (!policy.allowDestructiveGit) {
             /**
@@ -539,10 +731,14 @@ export function evaluateGitPolicy(command, ctx) {
              * that went that way on 2026-07-28 existed nowhere else — and
              * `git reset --hard` throws away every uncommitted edit in the tree.
              *
-             * Denied rather than turned into a permission card, because under AUTO
-             * trust there is no card: Bash is allowed before the safe list is
-             * consulted. An agent that needs to remove build output can name the
-             * paths; one that wants to undo its own work has `git checkout -- <file>`.
+             * Denied rather than turned into a permission card because there is no
+             * safe version of them, not because a card was impossible: this whole
+             * function runs BEFORE the trust branches, so an `ask` returned from here
+             * does reach the person even under AUTO (that is how #361 п. 5 works two
+             * rules below). What is true is that the safe LIST never sees them — Bash
+             * is allowed before it is consulted. An agent that needs to remove build
+             * output can name the paths; one that wants to undo its own work has
+             * `git checkout -- <file>`.
              */
             if (new RegExp(String.raw `\bgit\s+${FLAGS}clean\b`).test(segment)) {
                 return {
@@ -557,6 +753,16 @@ export function evaluateGitPolicy(command, ctx) {
                 };
             }
         }
+        // #361 п. 5 — only where the folder is shared. In a BRANCH session the
+        // worktree belongs to this session alone and moving it costs nobody
+        // anything. See `PolicyContext.workMode` for why silence means «ask».
+        if (ctx.workMode !== 'BRANCH') {
+            const move = parseCheckout(segment);
+            // `reason` stays a LABEL — it goes to logs and, on a denial, to the feed.
+            // The sentence a person reads on the card travels in `explain`.
+            if (move)
+                asked ??= { decision: 'ask', reason: 'moves the shared folder', explain: move.reason };
+        }
         const push = parsePush(segment);
         if (!push)
             continue;
@@ -648,7 +854,7 @@ export function evaluateGitPolicy(command, ctx) {
             }
         }
     }
-    return null;
+    return asked;
 }
 // Commands considered safe enough to run without asking under NORMAL trust.
 // Interpreters (node/python/…) and find (-exec) are NOT here: they execute
@@ -829,7 +1035,14 @@ export function evaluateRecipeCommand(command, ctx = {}) {
          * approval screen, not a side effect of this one.
          */
         const git = evaluateGitPolicy(variant, { trustMode: 'STRICT', worktreePath: '' });
-        if (git) {
+        // Only a REFUSAL stops a recipe. Since #361 this function can also return
+        // «ask», and the first line of this doc comment is the answer to it: an
+        // approved recipe does not ask, because a human already read this exact
+        // command on the approval screen. Turning that ask into `{allowed: false}`
+        // would hard-refuse every build script that starts with `git checkout main`
+        // — a refusal invented by a rule about AGENTS, applied to a text a person
+        // wrote and approved.
+        if (git?.decision === 'deny') {
             // The sentence is rewritten, not passed through (QA-134 MINOR-2). The
             // generic one says «this project has «Принудительно запретить push»
             // switched on» — and a project that switched it OFF would be sent to look
@@ -1001,11 +1214,19 @@ export function evaluateToolUse(toolName, input, ctx) {
         // and nothing after this line is consulted. That is exactly how «agents
         // never push» quietly failed for a whole release (session 13), and it is
         // the reason these rules did not simply move onto the safe list.
+        // Both spellings are read to the end before anything is returned: a `deny`
+        // in the dequoted form must beat an `ask` in the raw one, for the same
+        // reason a later segment beats an earlier one (see `evaluateGitPolicy`).
+        let gitAsk = null;
         for (const variant of [command, dequote(command)]) {
             const git = evaluateGitPolicy(variant, ctx);
-            if (git)
+            if (git?.decision === 'deny')
                 return git;
+            if (git)
+                gitAsk ??= git;
         }
+        if (gitAsk)
+            return gitAsk;
         if (trust === 'STRICT')
             return { decision: 'ask', reason: 'strict mode' };
         if (trust === 'AUTO')

package/dist/protocol.d.ts

@@ -242,6 +242,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         url: string;
         token: string;
     } | undefined;
+    workMode?: "DIRECT" | "BRANCH" | undefined;
     pausedUntil?: string | null | undefined;
     agentLatestVersion?: string | undefined;
     skipAgentPrompt?: boolean | undefined;
@@ -252,7 +253,6 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         baseBranch?: string | undefined;
         baseSha?: string | undefined;
     } | undefined;
-    workMode?: "DIRECT" | "BRANCH" | undefined;
 }, {
     agent: "CLAUDE" | "CODEX";
     id: string;
@@ -284,6 +284,7 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
         token: string;
     } | undefined;
     mode?: "ask" | "plan" | "auto" | "full" | undefined;
+    workMode?: unknown;
     model?: string | null | undefined;
     effort?: string | null | undefined;
     epoch?: number | undefined;
@@ -296,7 +297,6 @@ export declare const SessionDescriptorSchema: z.ZodObject<{
     skipAgentPrompt?: unknown;
     branchHint?: unknown;
     branchPlan?: unknown;
-    workMode?: unknown;
 }>;
 export type SessionDescriptor = z.infer<typeof SessionDescriptorSchema>;
 /**
@@ -660,6 +660,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        workMode?: "DIRECT" | "BRANCH" | undefined;
         pausedUntil?: string | null | undefined;
         agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
@@ -670,7 +671,6 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             baseBranch?: string | undefined;
             baseSha?: string | undefined;
         } | undefined;
-        workMode?: "DIRECT" | "BRANCH" | undefined;
     }, {
         agent: "CLAUDE" | "CODEX";
         id: string;
@@ -702,6 +702,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             token: string;
         } | undefined;
         mode?: "ask" | "plan" | "auto" | "full" | undefined;
+        workMode?: unknown;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;
@@ -714,12 +715,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
-        workMode?: unknown;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
-    type: "hello_ack";
-    serverName: string;
-    serverId: string;
     sessions: {
         mode: "ask" | "plan" | "auto" | "full";
         agent: "CLAUDE" | "CODEX";
@@ -758,6 +755,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        workMode?: "DIRECT" | "BRANCH" | undefined;
         pausedUntil?: string | null | undefined;
         agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
@@ -768,13 +766,12 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             baseBranch?: string | undefined;
             baseSha?: string | undefined;
         } | undefined;
-        workMode?: "DIRECT" | "BRANCH" | undefined;
     }[];
-    maxSessions?: number | undefined;
-}, {
     type: "hello_ack";
     serverName: string;
     serverId: string;
+    maxSessions?: number | undefined;
+}, {
     sessions: {
         agent: "CLAUDE" | "CODEX";
         id: string;
@@ -806,6 +803,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             token: string;
         } | undefined;
         mode?: "ask" | "plan" | "auto" | "full" | undefined;
+        workMode?: unknown;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;
@@ -818,8 +816,10 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
-        workMode?: unknown;
     }[];
+    type: "hello_ack";
+    serverName: string;
+    serverId: string;
     maxSessions?: unknown;
 }>, z.ZodObject<{
     type: z.ZodLiteral<"event_ack">;
@@ -1093,6 +1093,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        workMode?: "DIRECT" | "BRANCH" | undefined;
         pausedUntil?: string | null | undefined;
         agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
@@ -1103,7 +1104,6 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             baseBranch?: string | undefined;
             baseSha?: string | undefined;
         } | undefined;
-        workMode?: "DIRECT" | "BRANCH" | undefined;
     }, {
         agent: "CLAUDE" | "CODEX";
         id: string;
@@ -1135,6 +1135,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             token: string;
         } | undefined;
         mode?: "ask" | "plan" | "auto" | "full" | undefined;
+        workMode?: unknown;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;
@@ -1147,7 +1148,6 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
-        workMode?: unknown;
     }>;
 }, "strip", z.ZodTypeAny, {
     type: "session_start";
@@ -1189,6 +1189,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             url: string;
             token: string;
         } | undefined;
+        workMode?: "DIRECT" | "BRANCH" | undefined;
         pausedUntil?: string | null | undefined;
         agentLatestVersion?: string | undefined;
         skipAgentPrompt?: boolean | undefined;
@@ -1199,7 +1200,6 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             baseBranch?: string | undefined;
             baseSha?: string | undefined;
         } | undefined;
-        workMode?: "DIRECT" | "BRANCH" | undefined;
     };
 }, {
     type: "session_start";
@@ -1234,6 +1234,7 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
             token: string;
         } | undefined;
         mode?: "ask" | "plan" | "auto" | "full" | undefined;
+        workMode?: unknown;
         model?: string | null | undefined;
         effort?: string | null | undefined;
         epoch?: number | undefined;
@@ -1246,7 +1247,6 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
         skipAgentPrompt?: unknown;
         branchHint?: unknown;
         branchPlan?: unknown;
-        workMode?: unknown;
     };
 }>, z.ZodObject<{
     type: z.ZodLiteral<"session_message">;
@@ -1406,8 +1406,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
 }, "strip", z.ZodTypeAny, {
     type: "workspace_settings";
     workspaceId: string;
-    trustMode?: "STRICT" | "NORMAL" | "AUTO" | undefined;
     agentAutoCommit?: boolean | undefined;
+    trustMode?: "STRICT" | "NORMAL" | "AUTO" | undefined;
     agentPushBan?: boolean | undefined;
     agentProtectedBranches?: string[] | undefined;
     agentAllowForcePush?: boolean | undefined;
@@ -1415,8 +1415,8 @@ export declare const GatewayFrameSchema: z.ZodDiscriminatedUnion<"type", [z.ZodO
 }, {
     type: "workspace_settings";
     workspaceId: string;
-    trustMode?: "STRICT" | "NORMAL" | "AUTO" | undefined;
     agentAutoCommit?: boolean | undefined;
+    trustMode?: "STRICT" | "NORMAL" | "AUTO" | undefined;
     agentPushBan?: boolean | undefined;
     agentProtectedBranches?: string[] | undefined;
     agentAllowForcePush?: boolean | undefined;

package/dist/supervisor.d.ts

@@ -359,6 +359,26 @@ export declare class Supervisor {
      * would be a lock bought for nothing.
      */
     private prepareWorkspace;
+    /**
+     * The working folder could not be built — say so in the feed, pin the fork
+     * point, and let the session go (#360).
+     *
+     * Both doors into `prepareWorkspace` end here. Three things happen in an
+     * order that is not free:
+     *
+     *  1. **The fork point is recorded first.** `git.ts` resolves it before it
+     *     writes anything, precisely so that a failure still knows it. Without it
+     *     the API keeps `base_sha = null` for the session's whole life, and
+     *     «Continue» can never prove the leftover branch is the empty one this
+     *     session created — which is the trap the ticket is about.
+     *  2. **The feed event goes out before the map entry is dropped**, because
+     *     `sendEvent` needs it. Until now neither door sent one: a failed start
+     *     was visible only as an `errorMessage` on the session row, and pressing
+     *     «Continue» wipes that.
+     *  3. **Then the status, then the entry.** A FAILED session is over, and a
+     *     leftover entry would hold one of the runner's few slots.
+     */
+    private workspacePrepareFailed;
     /**
      * Spin the adapter up — for a fresh session, a resume-on-next-message, or a
      * free CHAT session with no prompt at all (the agent boots, reports its
@@ -526,7 +546,8 @@ export declare class Supervisor {
     /**
      * Make room for one more agent process.
      *
-     * Up to `maxSessions` agents run side by side, each in its own worktree. Over
+     * Up to `maxSessions` agents run side by side — since session 16 most of them
+     * share the project folder rather than each having a worktree of its own. Over
      * that, idle-but-resumable sessions (REVIEW / WAITING_INPUT) are parked —
      * their provider session survives on disk and relaunches on the next message,
      * so parking costs context nothing. Only mid-turn sessions (RUNNING /
@@ -754,10 +775,35 @@ export declare class Supervisor {
      * Three reasons it declines, and each of them is a state in which a snapshot
      * would be a lie rather than a restore point:
      *  - the machine's owner switched checkpoints off;
-     *  - the agent is mid-turn, so the tree is being written to as we read it;
+     *  - THIS session is mid-turn, so its own tree is being written as we read it;
      *  - a repo-mutating command holds the repository.
+     *
+     * «A neighbour in the same folder is working» used to be a fourth reason, and
+     * it was the wrong one (#310): in DIRECT mode the folder is shared by design,
+     * so that rule silently switched restore points off for everybody the moment
+     * a second session opened. The neighbours are recorded on the point instead —
+     * the conversation can always be rewound to it, the files cannot.
+     *
+     * Every refusal is now audible. A restore point that was never taken is
+     * invisible until the day somebody reaches for it, and «the button is not
+     * there» is not a sentence anybody can act on.
      */
     private captureCheckpoint;
+    /**
+     * Say something once per BUSY PERIOD, not once per message (#310).
+     *
+     * A folder held by a neighbour stays held for minutes, and a session mid-turn
+     * can be sent three follow-up notes inside one answer. Keying this on the
+     * message seq would have counted each of those as its own turn and said the
+     * same sentence three times — the noise the frequency policy exists to
+     * prevent. The set is cleared when the session next comes to rest
+     * (`reportStatus`), which is exactly when the reason stops being true.
+     *
+     * A SET of keys, not the last one said: two different reasons can both come
+     * up inside one period, and remembering only the most recent would let them
+     * take turns re-announcing each other.
+     */
+    private noticeOncePerTurn;
     /**
      * Deliver messages that raced session start (already journaled).
      *
@@ -887,7 +933,15 @@ export declare class Supervisor {
     private stopWorkUnderPause;
     /** Live model / interaction-mode switch (persisted for the next relaunch). */
     private applySettings;
-    /** Is a turn (or a question the agent is parked on) in flight right now? */
+    /**
+     * Is a turn (or a question the agent is parked on) in flight right now?
+     *
+     * The same status list as `holdsTheTree` plus one term: an open question
+     * parks the session without any of those statuses, and a live settings change
+     * must not land under it. Reading the shared array rather than spelling the
+     * statuses out again is the whole point of Р8 — a fourth waiting status has
+     * to arrive in one place, not four.
+     */
     private isMidTurn;
     /** The three live setters, in the order that lets an explicit pick win. */
     private applyLiveSettings;
@@ -976,8 +1030,50 @@ export declare class Supervisor {
      * has to branch on the type, so "I did not check" cannot compile.
      */
     private requireSession;
+    /**
+     * The statuses in which a session is holding its working tree (#310).
+     *
+     * One array, read by all three predicates below. There used to be one
+     * literal, then two would have been needed, and a third would have been
+     * written the day somebody added a waiting state — which is how «the agent
+     * is busy» and «the folder is busy» come to disagree about what busy means.
+     * (`rewindActionsLive` in the dashboard is a fourth reader and a deliberate
+     * mirror: the runner does not depend on `@devbridge/shared`.)
+     */
+    private static readonly MID_TURN_STATUSES;
+    /**
+     * Is a stop still in flight over this session's live process?
+     *
+     * Three terms, written out in three places before this: an open cycle, that
+     * cycle owning the process that is running NOW, and the cycle not yet
+     * settled. #373 is what makes it load-bearing — the resting status is
+     * published before the process dies, so this is the difference between «the
+     * session is quiet» and «the session is still writing files».
+     */
+    private static stopInFlight;
+    private static holdsTheTree;
     /** A session actively mid-turn in this worktree — git writes must wait. */
     private isWorktreeBusy;
+    /**
+     * Is THIS session mid-turn? (#310)
+     *
+     * The question `isWorktreeBusy` was answering in three places where the right
+     * question was this one. They are the same question only when a folder holds
+     * exactly one session — and DIRECT mode, the default since session 16, is
+     * precisely the arrangement in which it holds several. A restore point is a
+     * snapshot of this session's own conversation; a neighbour typing in the same
+     * folder is a reason to MARK it, not to refuse to take it.
+     */
+    private isSessionMidTurn;
+    /**
+     * Everybody else who is working in this folder right now (#310).
+     *
+     * Includes a neighbour whose stop is still running: after #373 the resting
+     * status is published BEFORE the process is actually gone, so a session that
+     * reports IDLE while its stop cycle still owns a live process is still
+     * writing files. Reading `lastReported` alone would call that folder quiet.
+     */
+    private busyNeighbours;
     private static readonly EVENT_PAYLOAD_CAP;
     /**
      * Journal an event, put it on the wire, and return it.