opencode-swarm 7.135.1 → 7.135.3

package/dist/config/lane-context.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Swarm worktree-lane context detection.
+ *
+ * ## Why this exists
+ *
+ * OpenCode partitions **all** permission state by *directory*. Every service
+ * that matters — `Permission.state`, `Agent.state`, `Plugin.state`,
+ * `ToolRegistry.state` — is built through the same directory-keyed
+ * `InstanceState` cache. When opencode-swarm creates a worktree-lane session
+ * bound to a new directory (`session.create({ query: { directory: lanePath } })`),
+ * that lane gets a brand-new permission universe: an empty `approved` list, so
+ * every prior "Allow always" is forgotten, and a private pending map. Because a
+ * lane instance has no TUI attached, an `external_directory` prompt raised there
+ * can never be answered and the lane hangs forever (the host's `Permission.ask`
+ * awaits its deferred with no timeout).
+ *
+ * The fix is to pre-resolve permissions for lane instances via the plugin
+ * `config` hook. That requires answering one question cheaply and reliably:
+ * **is this directory a swarm worktree lane, and if so, what project is it a
+ * worktree of?**
+ *
+ * ## Why there is no `git` subprocess here
+ *
+ * The obvious implementation is
+ * `git -C <lane> rev-parse --path-format=absolute --git-common-dir`. This module
+ * deliberately does not do that. `resolveLaneContext` is called from the plugin
+ * `config` hook, which the host runs inside `Plugin.state` initialisation —
+ * squarely on the plugin-init path that AGENTS.md invariant 1 governs, and that
+ * invariant names Git commands explicitly as forbidden there.
+ *
+ * Instead this module reads the two files git itself would consult:
+ *
+ *   - `<lane>/.git` — in a linked worktree this is a *file*, not a directory,
+ *     containing `gitdir: <main>/.git/worktrees/<name>`.
+ *   - `<main>/.git/worktrees/<name>/commondir` — a relative pointer back to the
+ *     shared `.git` directory (normally `../..`).
+ *
+ * That is the same information the subprocess would return, obtained with at
+ * most two small synchronous reads, no child process, no timeout to get wrong,
+ * and nothing to kill in a `finally`. It is strictly safer on the init path than
+ * a spawn would be, and it removes an entire class of invariant-3 exposure.
+ *
+ * @module config/lane-context
+ */
+import { addDeferredWarning } from '../services/warning-buffer';
+/**
+ * A resolved swarm worktree lane.
+ */
+export interface LaneContext {
+    /** Absolute, resolved path of the lane worktree itself. */
+    lanePath: string;
+    /**
+     * Absolute, resolved path of the project this lane is a git worktree of —
+     * i.e. the main working tree that owns the shared `.git` directory.
+     */
+    parentProjectPath: string;
+}
+/**
+ * Test-only dependency-injection seam (AGENTS.md invariant 7 — prefer
+ * `_internals` over `mock.module`, which leaks across files in Bun's shared
+ * test-runner process). Tests replace these to simulate unreadable `.git`
+ * files, malformed pointers, and permission errors. Restore in `afterEach`.
+ */
+export declare const _internals: {
+    readFileSync: (p: string, enc: BufferEncoding) => string;
+    statSync: (p: string) => {
+        isFile(): boolean;
+    };
+    addDeferredWarning: typeof addDeferredWarning;
+    /**
+     * Clears the detection cache. Test-only; production has no reason to call
+     * it because a directory's lane-ness cannot change while the process holds
+     * an OpenCode instance for that directory.
+     */
+    clearCache: () => void;
+};
+/**
+ * Decides whether `directory` is a swarm worktree lane and, if so, resolves the
+ * lane path and the parent project it is a worktree of.
+ *
+ * Detection requires two independent conditions, the second of which may be
+ * satisfied either way:
+ *
+ *  1. REQUIRED — the directory (or a bounded number of its ancestors) is a real
+ *     LINKED git worktree whose main working tree resolves. A main working tree
+ *     has a `.git` directory rather than a file and is never a lane.
+ *  2. REQUIRED — the worktree is swarm-OWNED, established by EITHER
+ *     (a) its branch matching the full grammar in `./swarm-branch.ts`
+ *         (`swarm/<purpose>/<sessionId>/<id>` or `swarm-lane/<sessionId>/<id>`,
+ *         with `<sessionId>` of the form `ses_…`) — the authoritative,
+ *         path-independent signal; OR
+ *     (b) the path sitting under a `.swarm-worktrees` base — the fallback for a
+ *         worktree whose HEAD is detached or unreadable, so its branch cannot
+ *         be consulted.
+ *
+ * (2a) is a full-grammar match rather than a `swarm/` prefix test on purpose: a
+ * user-authored `swarm/my-own-experiment` worktree must NOT be captured. A
+ * false positive is worse than a false negative here — see the module note in
+ * `./swarm-branch.ts`.
+ *
+ * A detached-HEAD swarm lane created OUTSIDE `.swarm-worktrees` (a
+ * `worktree_dir` override, or the Windows path-budget fallback) satisfies
+ * neither branch of (2) and is a false NEGATIVE: no permission changes, i.e.
+ * today's behaviour. That is the safe direction and is left as-is.
+ *
+ * NEVER throws. Any error — nonexistent directory, unreadable `.git`, malformed
+ * pointer, permission error, non-string input — yields `null` ("not a lane"),
+ * which preserves today's behaviour for ordinary sessions. That direction is
+ * the safe one: a false negative means "no permission changes at all", while a
+ * false positive would apply a deny-by-default ruleset to a normal project.
+ *
+ * @param directory - Directory to classify (typically the plugin's own
+ *                    `ctx.directory`, which under this host IS the instance
+ *                    directory).
+ * @returns The resolved lane context, or `null` when `directory` is not a lane.
+ */
+export declare function resolveLaneContext(directory: string): LaneContext | null;

package/dist/config/lane-permissions.d.ts

@@ -0,0 +1,277 @@
+/**
+ * Scoped `external_directory` permission rules for swarm worktree-lane
+ * instances.
+ *
+ * ## The problem this solves
+ *
+ * A lane session is created against a new directory, so OpenCode builds it a
+ * fresh directory-keyed permission universe with an empty `approved` list. The
+ * host's default agent ruleset ends in `external_directory: { "*": "ask" }`, and
+ * a lane instance has no TUI attached to answer an ask — `Permission.ask` parks
+ * on a deferred with no timeout and the lane hangs forever.
+ *
+ * ## The mechanism
+ *
+ * The plugin `config` hook runs once per OpenCode instance (`Plugin.state` is
+ * built through the same directory-keyed `InstanceState` cache as
+ * `Permission.state`), so in a lane instance it runs with `ctx.directory` set to
+ * the lane path. Rules merged into the top-level `permission` block there are
+ * folded by the host into **every** agent's ruleset:
+ *
+ * ```js
+ * // opencode host, Agent.state
+ * l = a.fromConfig(p.permission ?? {})            // top-level config permission
+ * r = { build: { permission: a.merge(c, ..., l) }, plan: {...}, general: {...},
+ *       explore: {...}, compaction: {...}, title: {...}, summary: {...} }
+ * for (const [n, s] of Object.entries(p.agent ?? {})) {
+ *   let e = r[n];
+ *   if (!e) e = r[n] = { ..., permission: a.merge(c, l), ... };   // swarm agents
+ *   e.permission = a.merge(e.permission, a.fromConfig(s.permission ?? {}));
+ * }
+ * ```
+ *
+ * Top-level is therefore strictly broader than per-agent injection: it reaches
+ * the host-native agents (`build`, `plan`, `general`, `explore`, ...) that a
+ * lane can also run, and it lands *before* any per-agent block so explicit
+ * per-agent user config still wins. Injecting the same rules per-agent as well
+ * would duplicate every rule in every ruleset and would make our injected rules
+ * outrank the user's own top-level entries — the wrong precedence.
+ *
+ * ## DISCLOSED ASSUMPTION: hook-before-agents ordering
+ *
+ * This design requires the `config` hook to run before `Agent.state` reads the
+ * config. What is PROVEN: both sides touch the *same* object — `Plugin.state`
+ * does `U = yield* Config.get()` and mutates `U` in place, `Agent.state` does
+ * `p = yield* Config.get()`, and `Config.state` is InstanceState-cached, so
+ * `get()` returns one shared instance. There is no copy; only ordering is in
+ * question.
+ *
+ * What is NOT proven: any static ordering guarantee. Two bounded searches of
+ * the host binary came back negative — the Agent layer's deps
+ * (`deps:[J.node,O.node,P.node,_.node,$.node,Ve]`, offset 100817167) do not
+ * include the Plugin node (the three symbols the Agent chunk imports from the
+ * Plugin chunk are `$G`, `b8`, `r1`, none of which is the Plugin service), and
+ * `Plugin.init` (offset 102128681) has no caller anywhere in the bundle. The
+ * hook therefore fires lazily, when `Plugin.state` is first populated by a
+ * `Plugin.trigger` / `Plugin.list`.
+ *
+ * The evidence that it holds is empirical and strong: opencode-swarm's agents
+ * are registered ONLY by this config hook, and they demonstrably appear in the
+ * TUI, which is impossible unless the hook ran before `Agent.state` was built.
+ * Treat it as a verified-in-practice property of this host build rather than a
+ * contract. If a future OpenCode release reorders layer construction, the
+ * symptom is loud and immediate — no swarm agents at all — not a silent
+ * permission regression.
+ *
+ * ## Rule ordering is load-bearing
+ *
+ * The host evaluates with `findLast` over the flattened rule list:
+ *
+ * ```js
+ * function c(j, J, ...K) {
+ *   return K.flat().findLast((z) => g.match(j, z.permission) && g.match(J, z.pattern))
+ *          ?? { action: "ask", permission: j, pattern: "*" };
+ * }
+ * ```
+ *
+ * and `fromConfig` preserves `Object.entries` order. So **later wins**, and the
+ * catch-all `"*": "deny"` must be emitted FIRST, before the specific allows.
+ * Emitting it last would deny everything. `tests/unit/config/lane-permissions.test.ts`
+ * pins this against a faithful re-implementation of the host's own
+ * `fromConfig`/`merge`/`evaluate`, so the ordering contract is verified rather
+ * than assumed.
+ *
+ * Two further host behaviours matter and are deliberately relied upon:
+ *
+ *  - `Wildcard.match` compiles the rule pattern with `*` -> `.*` under the `s`
+ *    (dotAll) flag, so `<dir>/*` covers the entire subtree, and it normalises
+ *    `\` to `/` on both sides before matching, so native Windows paths are fine.
+ *  - After merging config, the host appends
+ *    `external_directory: { <Global.Path.data>/tool-output/*: "allow" }` to every
+ *    agent unless a rule already matches that exact pattern with `action: "deny"`.
+ *    Our catch-all uses pattern `"*"`, which does not satisfy that exact-string
+ *    check, so the append still happens and still lands last. Tool output stays
+ *    readable. The emitted ruleset is intentionally not the final ruleset.
+ *
+ * @module config/lane-permissions
+ */
+import { addDeferredWarning } from '../services/warning-buffer';
+import type { LaneContext } from './lane-context';
+import { resolveLaneContext } from './lane-context';
+/**
+ * Lane permission policy. Mirrors `worktree.lane_permissions` in
+ * `src/config/schema.ts`.
+ */
+export type LanePermissionMode = 'scoped_allow' | 'deny' | 'off';
+/** Permission actions OpenCode understands for a rule. */
+type PermissionAction = 'allow' | 'ask' | 'deny';
+/** Result of assembling a lane's `external_directory` rule map. */
+interface LaneRuleBuild {
+    /** The rule map, in emission (== evaluation) order. */
+    rules: Record<string, PermissionAction>;
+    /**
+     * User-configured patterns whose `"ask"` was coerced to `"deny"` because a
+     * lane has no TUI that could answer an ask. Empty in the common case.
+     */
+    coercedAskPatterns: string[];
+}
+/** An allowlisted directory plus the justification for granting it. */
+interface LaneAllowlistEntry {
+    /** Absolute directory path. */
+    dir: string;
+    /**
+     * The emitted `external_directory` rule pattern for {@link dir}.
+     *
+     * Computed ONCE here and reused by both consumers — the rule map and the
+     * `.swarm/events.jsonl` record. Deriving it twice meant a second round of
+     * `realpathSync.native` per entry on the config-hook path and, more
+     * importantly, left room for the two to disagree: if they ever did, the
+     * event log would misreport the rule that was actually emitted, which is
+     * precisely the observability this subsystem exists to provide.
+     */
+    pattern: string;
+    /** Why this directory is justified — recorded in `.swarm/events.jsonl`. */
+    reason: string;
+}
+/**
+ * Converts an absolute directory into the `external_directory` rule pattern
+ * that covers it and everything beneath it.
+ *
+ * The literal part of the directory is escaped for the host's matcher. The host
+ * compiles a rule pattern as:
+ *
+ * ```js
+ * o.replace(/[.+^${}()|[\]\\]/g,"\\$&").replace(/\*​/g,".*").replace(/\?/g,".")
+ * // then: new RegExp("^"+compiled+"$","si")
+ * ```
+ *
+ * Note what is NOT escaped: `*` and `?`. A directory legitimately named `a*`
+ * (legal on POSIX) would compile to `a.*` and silently grant every sibling
+ * starting with `a`; `?` becomes a single-character wildcard the same way. The
+ * matcher offers no escape syntax for either, so such a directory cannot be
+ * expressed exactly. {@link isExpressibleDirectory} therefore drops it from the
+ * allowlist rather than emitting an over-broad grant: dropping fails safe (the
+ * path is denied, and its absence is visible in the event log), emitting would
+ * fail open.
+ *
+ * The matcher also uses the `i` flag, so patterns are case-insensitive even on
+ * case-sensitive filesystems. `/home/u/Work/*` will therefore also match
+ * `/home/u/work/...`. That widening is inherent to the host and cannot be
+ * avoided from a rule pattern; it is recorded here so it is a known, reviewed
+ * property rather than a surprise.
+ */
+declare function laneDirectoryPattern(dir: string): string;
+/**
+ * Builds the justified `external_directory` allowlist for a lane.
+ *
+ * Every entry is a directory the lane provably needs in order to do the work it
+ * was created for. Nothing is added "just in case" — an over-broad allowlist
+ * here is the security cost of this fix, so each entry carries its reason and
+ * is asserted in tests.
+ *
+ * @param lane - Resolved lane context.
+ * @returns Deduplicated absolute directories with justifications.
+ */
+declare function buildLaneAllowlist(lane: LaneContext, configuredSkillPaths?: readonly string[], configuredSkillUrls?: readonly string[]): LaneAllowlistEntry[];
+/**
+ * Builds the `external_directory` rule map to write into the top-level
+ * `permission` block of a lane instance's config.
+ *
+ * Emission order (which IS the evaluation order, later-wins):
+ *
+ *  1. `"*": "deny"` — our catch-all, so nothing can be left pending in a lane
+ *     that has no TUI to answer it. This is the only mechanism that delivers
+ *     the approved policy's "answered, not hung" guarantee now that the host's
+ *     `permission.ask` plugin hook is confirmed dead (never triggered by
+ *     opencode 1.18.10).
+ *  2. Our justified allowlist — beats the catch-all because it comes later.
+ *  3. Whatever the user already configured — beats everything, because explicit
+ *     user configuration must always outrank a plugin default. A user entry
+ *     keyed `"*"` replaces our catch-all's value in place (same key), so
+ *     `external_directory: "allow"` in `opencode.json` still means allow-all.
+ *
+ * ## Why `"ask"` is coerced to `"deny"` INSIDE A LANE
+ *
+ * A user's `allow` and `deny` are honoured verbatim. `ask` is not, and that is
+ * deliberate: a lane instance has no TUI attached, so `ask` cannot be answered
+ * by anyone. It is not a third policy choice there — it is a guaranteed
+ * indefinite hang, which is the exact defect this module exists to remove.
+ * Honouring it literally would let a top-level `external_directory: "ask"` (or
+ * any `"ask"` pattern) silently reinstate the bug while this code reported
+ * success. Coercion resolves to the fail-safe direction (`deny`, never
+ * `allow`), the affected patterns are named in the advisory, and they are
+ * recorded under `coercedAskPatterns` in the `.swarm/events.jsonl` entry so the
+ * decision is auditable rather than silent. Users who genuinely want the
+ * prompting behaviour back have `worktree.lane_permissions: "off"`.
+ *
+ * @param mode     - Configured lane permission policy.
+ * @param lane     - Resolved lane context.
+ * @param existing - Current `external_directory` value from the config being
+ *                   mutated, if any.
+ * @returns The rule map plus any patterns whose `ask` was coerced, or `null`
+ *          when the policy is `off` (the caller must then touch nothing).
+ */
+declare function buildLaneExternalDirectoryRules(mode: LanePermissionMode, lane: LaneContext, existing?: unknown, precomputedAllowlist?: readonly LaneAllowlistEntry[]): LaneRuleBuild | null;
+/**
+ * Renders the operator-facing remedy text for a lane whose permissions are
+ * being scoped.
+ *
+ * The permission system itself carries an action, not a message — a `deny` rule
+ * cannot explain itself. So the explanation is delivered out-of-band (a deferred
+ * warning plus a `.swarm/events.jsonl` record) and names the exact
+ * `opencode.json` edit that widens the allowlist.
+ */
+declare function renderLanePermissionAdvisory(mode: Exclude<LanePermissionMode, 'off'>, lane: LaneContext, allowlist: readonly LaneAllowlistEntry[], coercedAskPatterns?: readonly string[]): string;
+/**
+ * Tier-0 test seam (see the writing-tests skill): these are pure functions with
+ * no external dependencies, so they are tested directly rather than mocked.
+ * They are intentionally NOT part of the module's public API — only
+ * {@link applyLanePermissions} is called from production.
+ */
+export declare const _test_exports: {
+    buildLaneAllowlist: typeof buildLaneAllowlist;
+    buildLaneExternalDirectoryRules: typeof buildLaneExternalDirectoryRules;
+    laneDirectoryPattern: typeof laneDirectoryPattern;
+    renderLanePermissionAdvisory: typeof renderLanePermissionAdvisory;
+};
+/**
+ * Test-only dependency-injection seam (AGENTS.md invariant 7). Tests replace
+ * these to assert the event record and advisory without touching the real
+ * filesystem or the process-wide warning buffer. Restore in `afterEach`.
+ */
+export declare const _internals: {
+    resolveLaneContext: typeof resolveLaneContext;
+    addDeferredWarning: typeof addDeferredWarning;
+    appendFileSync: (p: string, data: string, enc: BufferEncoding) => void;
+    mkdirSync: (p: string, opts: {
+        recursive: boolean;
+    }) => string | undefined;
+};
+/** Outcome of {@link applyLanePermissions}, returned for tests and logging. */
+export interface LanePermissionApplication {
+    /** `true` when the directory was recognised as a swarm worktree lane. */
+    lane: boolean;
+    /** Effective policy. `undefined` when `lane` is `false`. */
+    mode?: LanePermissionMode;
+    /** Rules written into `permission.external_directory`, when any. */
+    rules?: Record<string, PermissionAction>;
+}
+/**
+ * Applies scoped lane permissions to an OpenCode config object, in place.
+ *
+ * Called from the plugin `config` hook. When `directory` is not a swarm
+ * worktree lane this returns immediately and mutates NOTHING — ordinary
+ * sessions must be byte-for-byte unaffected, which
+ * `tests/unit/config/lane-permissions-config.test.ts` asserts directly.
+ *
+ * @param opencodeConfig - The live merged config object the host handed to the
+ *                         `config` hook. Mutated in place, as the hook contract
+ *                         requires.
+ * @param directory      - The plugin's own `ctx.directory`. Under this host that
+ *                         IS the instance directory, so in a lane instance it is
+ *                         the lane path.
+ * @param mode           - Configured `worktree.lane_permissions` policy.
+ * @returns What was decided, for logging and tests.
+ */
+export declare function applyLanePermissions(opencodeConfig: Record<string, unknown>, directory: string, mode: LanePermissionMode): LanePermissionApplication;
+export {};

package/dist/config/schema.d.ts

@@ -1197,6 +1197,11 @@ export declare const WorktreeIsolationConfigSchema: z.ZodObject<{
         skip: "skip";
         copy: "copy";
     }>>;
+    lane_permissions: z.ZodDefault<z.ZodEnum<{
+        scoped_allow: "scoped_allow";
+        deny: "deny";
+        off: "off";
+    }>>;
     serialization_release_after_dispatches: z.ZodDefault<z.ZodNumber>;
     serialization_release_after_ms: z.ZodDefault<z.ZodNumber>;
     runtime_isolation: z.ZodOptional<z.ZodObject<{
@@ -2449,6 +2454,11 @@ export declare const PluginConfigSchema: z.ZodObject<{
             skip: "skip";
             copy: "copy";
         }>>;
+        lane_permissions: z.ZodDefault<z.ZodEnum<{
+            scoped_allow: "scoped_allow";
+            deny: "deny";
+            off: "off";
+        }>>;
         serialization_release_after_dispatches: z.ZodDefault<z.ZodNumber>;
         serialization_release_after_ms: z.ZodDefault<z.ZodNumber>;
         runtime_isolation: z.ZodOptional<z.ZodObject<{

package/dist/config/swarm-branch.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The swarm worktree BRANCH GRAMMAR — single source of truth for both building
+ * and recognising the branch names that identify a swarm-owned worktree.
+ *
+ * ## Why a grammar and not a prefix
+ *
+ * Lane detection (`src/config/lane-context.ts`) uses the branch name as its
+ * ownership signal because, unlike the worktree's path, it is invariant across
+ * all three provisioning layouts (default `.swarm-worktrees`, a configured
+ * `worktree.worktree_dir`, and the Windows path-budget fallback that relocates
+ * a lane to `<os.tmpdir()>/swwt/...`).
+ *
+ * Matching a bare `swarm/` PREFIX is not safe. A user running
+ * `git worktree add -b swarm/my-own-experiment ../scratch` would be classified
+ * as a lane, and their ordinary interactive session would then have
+ * `external_directory: { "*": "deny", ... }` injected. That is strictly worse
+ * than the hang this subsystem exists to fix, because the host's
+ * `Permission.ask` short-circuits on a deny before it ever creates a deferred:
+ *
+ * ```js
+ * // opencode 1.18.10, Permission.ask
+ * if (W.action === "deny") return yield* new U.DeniedError({ ... });
+ * ```
+ *
+ * — so no prompt is raised and "Allow always" can never be reached. The user
+ * has no in-session recovery.
+ *
+ * The grammar below therefore matches the COMPLETE shape
+ * `makeWorktreeBranchName` emits, including a session segment constrained to
+ * OpenCode's `ses_`-prefixed identifier form. `tests/unit/config/swarm-branch.test.ts`
+ * holds a round-trip property test over the producer and a negative corpus of
+ * plausible human-authored branch names.
+ *
+ * @module config/swarm-branch
+ */
+/**
+ * True when `sessionId` is a session identifier the lane grammar can encode.
+ *
+ * Tool arguments are LLM-supplied (`sessionID: z.string()`) and the host's own
+ * `SessionID` brand is only `isStartsWith("ses")`, so a value like `ses-run-1`
+ * passes the host but yields a branch the recogniser cannot match — a lane that
+ * silently skips permission scoping and hangs. Callers that accept a session id
+ * from outside should check this before provisioning.
+ */
+export declare function isSwarmSessionId(sessionId: unknown): sessionId is string;
+/**
+ * Builds the branch name for a swarm worktree.
+ *
+ * The ONLY producer of these names. `makeWorktreeBranchName` in
+ * `src/worktree/core.ts` delegates here so the producer and
+ * {@link matchSwarmLaneBranch} cannot drift.
+ *
+ * @param sessionId    - Parent session identifier.
+ * @param id           - Execution-unit identifier (task or lane id).
+ * @param purpose      - Worktree purpose (e.g. `lane`).
+ * @param legacyLane   - Use Lean Turbo's `swarm-lane/<sessionId>/<id>` style.
+ */
+export declare function buildSwarmBranchName(sessionId: string, id: string, purpose: string, legacyLane: boolean): string;
+/**
+ * Recognises the DEFAULT lane PATH shape,
+ * `<base>/.swarm-worktrees/<sessionId>/<id>`.
+ *
+ * This is the fallback ownership signal for a worktree whose HEAD is detached
+ * or unreadable, so its branch cannot be consulted. It must be as tight as the
+ * branch grammar: matching "any path containing a `.swarm-worktrees` segment"
+ * captures a user's own `git worktree add -b my-feature ../.swarm-worktrees/manual-user-wt`,
+ * which then has an unrecoverable deny-by-default injected into an ordinary
+ * interactive session.
+ *
+ * `provisionWorktree` builds this path as
+ * `path.resolve(resolveWorktreeBaseDir(directory), sessionId, id)`, i.e. exactly
+ * two segments after the base, so the shape check requires exactly that — with
+ * the session segment held to the SAME `ses_…` constraint the branch grammar
+ * uses. The directory name comes from the same `SWARM_WORKTREE_DIR_NAME`
+ * constant `resolveWorktreeBaseDir` builds with, so the three definitions
+ * cannot drift.
+ *
+ * KNOWN RESIDUAL (accepted, not a defect to chase): a worktree the USER created
+ * at exactly `<base>/.swarm-worktrees/ses_<alnum>/<id>` on a non-swarm branch
+ * still classifies as a lane. Reaching it requires deliberately creating a
+ * directory literally named `ses_<alnum>` under a `.swarm-worktrees` base, and
+ * the same leniency is what keeps a REAL lane detected after someone checks out
+ * a different branch inside it. Narrowing further would trade a far more likely
+ * false negative (a real lane silently unscoped, i.e. the original hang) for a
+ * far less likely false positive.
+ *
+ * Note this recognises only the DEFAULT layout. A `worktree_dir` override or
+ * the Windows path-budget fallback produces a different path, and a lane in
+ * those layouts with a detached HEAD is a false NEGATIVE — no permission
+ * changes, i.e. today's behaviour. That is the safe direction.
+ *
+ * @param lanePath - An already-resolved absolute path.
+ */
+export declare function matchSwarmLanePath(lanePath: string): {
+    sessionId: string;
+    id: string;
+} | undefined;
+/** A branch name recognised as a swarm worktree lane. */
+export interface SwarmLaneBranch {
+    /** Worktree purpose. `'lane'` for the legacy style, which encodes no purpose. */
+    purpose: string;
+    sessionId: string;
+    id: string;
+    style: 'purpose' | 'legacy-lane';
+}
+/**
+ * Recognises a branch name produced by {@link buildSwarmBranchName}.
+ *
+ * Matches the complete grammar and nothing wider:
+ *   - `swarm/<purpose>/<sessionId>/<id>`   — exactly 4 segments
+ *   - `swarm-lane/<sessionId>/<id>`        — exactly 3 segments
+ *
+ * with `<sessionId>` matching `ses_[A-Za-z0-9]+` and `<purpose>` / `<id>` each
+ * a single non-empty, non-dot segment. Anything else — including a bare
+ * `swarm/my-own-experiment`, or a real lane name with extra trailing segments —
+ * returns `undefined`, which classifies the worktree as NOT swarm-owned and
+ * leaves it completely untouched.
+ *
+ * @returns The parsed branch, or `undefined` when the name is not a swarm lane.
+ */
+export declare function matchSwarmLaneBranch(branch: string): SwarmLaneBranch | undefined;
+/**
+ * Tier-0 test seam (writing-tests skill). The prefix list is an implementation
+ * detail of the grammar — production code goes through
+ * {@link buildSwarmBranchName} / {@link matchSwarmLaneBranch} — but the branch
+ * tests assert that both documented styles are actually exercised.
+ */
+export declare const _test_exports: {
+    SWARM_WORKTREE_BRANCH_PREFIXES: readonly ["swarm/", "swarm-lane/"];
+};

package/dist/hooks/delegation-gate.d.ts

@@ -265,11 +265,50 @@ interface MessageWithParts {
     info: MessageInfo;
     parts: MessagePart[];
 }
+declare function extractPlanCriticVerdict(output: unknown): 'APPROVED' | 'NEEDS_REVISION' | 'REJECTED' | null;
 /**
  * Returns whether the plan in the given directory has a valid plan-critic
  * approval. Does not throw — returns `false` for any failure (fail-closed).
  */
 export declare function isPlanCriticApproved(directory: string): Promise<boolean>;
+/**
+ * Escape hatch for the ratchet-tighter `critic_pre_plan` gate (issue #2012).
+ *
+ * When the critic returns APPROVED but the mechanical snapshot recorder
+ * ({@link recordPlanCriticApprovalSnapshotIfApplicable}) fails to persist it
+ * (verdict-format mismatch, dispatch-signal miss, or a plan.json read race),
+ * the gate permanently blocks ALL coder delegations because `critic_pre_plan`
+ * defaults to `true` and cannot be disabled (ratchet-tighter). This records a
+ * manual `plan_critic_gate` approval snapshot so the gate unblocks, with a
+ * distinct `method: 'manual_override'` audit marker so a human or downstream
+ * review can distinguish a manual approval from a mechanical critic approval.
+ *
+ * This mirrors the established escape-hatch pattern (PR_REVIEW gate #1898:
+ * `abortPrWorkflow` + `/swarm abort-pr-workflow` + `abort_pr_workflow` tool).
+ *
+ * Fail-closed preconditions:
+ * - The session must be an active **architect** session. The escape hatch is an
+ *   escalation; non-architect callers are rejected so a coder/reviewer cannot
+ *   self-unblock.
+ * - A plan.json must exist; you cannot approve a non-existent plan.
+ *
+ * @param directory - Project root containing `.swarm/`
+ * @param sessionID - The caller's session id (must be an architect session)
+ * @param options.reason - Optional human/agent-supplied reason (audited)
+ * @param options.userConfirmed - `true` only when invoked via the restricted
+ *   `/swarm approve-plan-critic` command (human-run); `false` when invoked via
+ *   the `approve_plan_critic` tool (agent-initiated). Recorded in the audit so a
+ *   self-approve is visible.
+ */
+export declare function forceRecordPlanCriticApproval(directory: string, sessionID: string, options?: {
+    reason?: string;
+    userConfirmed?: boolean;
+}): Promise<{
+    planId: string;
+    recordedAt: string;
+    reason?: string;
+    userConfirmed: boolean;
+}>;
 export declare function resolveDelegatedPlanTaskId(args: Record<string, unknown>, knownPlanTaskIds?: ReadonlySet<string>): string | null;
 /**
  * Builds a cause-specific diagnostic for `prepareCoderScope`'s SCOPE_NOT_DECLARED
@@ -332,7 +371,9 @@ export declare const _internals: {
     bindBackgroundCoderReservationForDispatch: typeof import("../background/pending-delegations.js").bindBackgroundCoderReservation;
     releaseBackgroundCoderReservationForDispatch: typeof import("../background/pending-delegations.js").releaseBackgroundCoderReservation;
     resetStandardWorktreeIsolationState: typeof resetStandardWorktreeIsolationState;
-    PLAN_CRITIC_TASK_SIGNALS: readonly ["critic-gate", "plan critic", "review plan", "review the plan", "plan.md", "approve the plan", "plan approval"];
+    PLAN_CRITIC_TASK_SIGNALS: readonly ["critic-gate", "plan critic", "review plan", "review the plan", "plan.md", "approve the plan", "plan approval", "pre-implementation review", "evaluate this plan", "evaluate the plan", "assess this plan", "assess the plan", "plan soundness", "before implementation", "review the plan below"];
+    extractPlanCriticVerdict: typeof extractPlanCriticVerdict;
+    forceRecordPlanCriticApproval: typeof forceRecordPlanCriticApproval;
     provisionWorktree: typeof _wtiInternals.provisionWorktree;
     removeWorktree: typeof _wtiInternals.removeWorktree;
     attemptMergeBackFromDirty: typeof _wtiInternals.attemptMergeBackFromDirty;