opencode-swarm 7.135.2 → 7.135.3

package/dist/config/constants.d.ts

@@ -118,6 +118,24 @@ export declare const AUTO_PROCEED_BANNER = "## \u23ED\uFE0F AUTO-PROCEED STATUS\
  * Zod schema in schema.ts).
  */
 export declare const DEFAULT_LEAN_TURBO_CONFIG: LeanTurboConfig;
+/**
+ * Directory name of the DD-6 default swarm-managed worktree base, created as a
+ * SIBLING of the project root (`<project-parent>/.swarm-worktrees`).
+ *
+ * Single source of truth shared by `resolveWorktreeBaseDir` in
+ * `src/worktree/core.ts` (which BUILDS lane paths) and
+ * `src/config/lane-context.ts` (which RECOGNISES a lane path after the fact,
+ * from inside the lane's own OpenCode instance). Those two must never drift: if
+ * creation and recognition disagree, a lane instance silently fails to be
+ * identified as a lane and falls back to unscoped permission behaviour.
+ *
+ * It lives in this leaf constants module rather than in `src/worktree/core.ts`
+ * so that the init-path-safe lane modules can share it without pulling the
+ * worktree lifecycle module into the plugin entry's import graph
+ * (AGENTS.md invariant 1; enforced by
+ * `tests/unit/turbo/lean/init-safety.test.ts`).
+ */
+export declare const SWARM_WORKTREE_DIR_NAME = ".swarm-worktrees";
 export declare const DEFAULT_WORKTREE_ISOLATION_CONFIG: WorktreeIsolationConfig;
 export declare const LEAN_TURBO_BANNER = "## \uD83D\uDEE4\uFE0F LEAN TURBO ACTIVE\n\nLane-based parallel execution is enabled for this phase.\n\nBehavioral changes:\n- Tasks are partitioned into parallel lanes based on file-scope conflicts. Tasks in the same lane run sequentially; tasks in different lanes run concurrently (up to max_parallel_coders).\n- **Lane dispatch overrides the one-agent-per-message rule**: for lean lane dispatch only, you may send multiple Task tool calls concurrently (one per lane).\n- **Lane tasks skip per-task Stage B** (reviewer + test_engineer). Quality is enforced at phase-end via phase reviewer and critic gates instead.\n- **Degraded tasks** (global files, protected paths, high-risk patterns) and **serialized tasks** (lock-conflicted) run through standard serial workflow with full Stage B gates.\n- **Phase reviewer and critic are REQUIRED** before phase_complete when lean turbo is active \u2014 they serve as the holistic quality gate for all lane work.\n- **Full-Auto composition**: if Full-Auto is also active, lane dispatch is subject to Full-Auto delegation policy and phase approval.\n- Use the lean_turbo_run_phase tool to execute a phase with parallel lanes\n\nDo NOT skip phase reviewer/critic when configured. Degraded and serialized tasks MUST still go through full Stage B.\n";
 export declare const EPIC_MODE_BANNER = "## \uD83E\uDDED EPIC MODE ACTIVE\n\n**\u26D4 THE USER ALWAYS COMES FIRST \u2014 this overrides everything below.** The user can message you at ANY time, including mid-phase while coders are running or retrying. The instant a user message arrives \u2014 a question, a slash command, a comment, anything \u2014 STOP advancing the flow. Do not dispatch, do not retry, do not call another tool. Read what they said and respond to them directly, in plain conversation, first. Never keep executing the protocol and leave a user message unanswered \u2014 ignoring the user is the single worst failure mode in this mode. After you've answered, pick up where you left off. If you're mid-wave when they interrupt, tell them the state (\"3.1 and 3.2 are still running; I'll continue once I've answered you\") rather than going silent.\n\n**Activation \u2260 start.** Until the user asks for execution (\"start phase N\", \"run task X\", \"continue\"): do nothing. On `/swarm turbo epic`, `/swarm epic *` and any slash status/config command: call the named tool ONCE, surface its output VERBATIM, then stop. Don't infer intent \u2014 if unsure, ASK. This restraint applies ONLY before activation.\n\n**Talk to the user as you work** \u2014 like you naturally would. Once they ask you to run a phase, keep them in the loop with a sentence before each step about what you're doing and why (\"Declaring scopes for 3.1\u20133.3 so the planner can find parallelism\u2026\", \"Discrimination and calibration are independent, so I'll run 3.1 and 3.2 in parallel\u2026\"). This is normal conversation, not a form to fill in \u2014 the steps below tell you the key facts to share, but say them in your own voice. Don't go silent and tool-only through a phase.\n\nUse `epic_plan_waves` (NOT `lean_turbo_plan_lanes` or the deprecated `epic_run_phase`) for the wave plan. Do NOT call `lean_turbo_run_phase` directly.\n\n### Six-step flow (only when the user asks to run a phase)\n\n> Supersedes Rule 1a/3a: declare ALL pending scopes UP FRONT (step 1), BEFORE step 2. Just-in-time declaration breaks the wave planner.\n\n**1. `declare_scope` for every pending task** \u2014 one call per single `taskId` string (NOT ranges/arrays/globs). Tight, disjoint scopes; avoid shared files (`__init__.py`, barrels, registries) \u2014 they force serial waves. Declared scope is a CONTRACT; if a task needs more files mid-run, re-declare BEFORE dispatching.\n\n**2. `epic_decide_phase(directory, phase=N, sessionID)`** \u2014 returns:\n- `decided`+`promote` \u2192 step 3\n- `demoted` \u2192 step 6 (per-task serial)\n- `scopes-missing` \u2192 `declare_scope` each `missingScopes[]`, retry step 2\n- `no-phase` | `phase-empty` | `phase-already-complete` | `epic-state-unreadable` \u2192 fix per response `message`, retry. `phase-already-complete` means call step 2 with `phase=N+1` (NOT step 4 directly).\n- other \u2192 fix per `message`, retry\n\n**3. Surface the verdict to the user immediately, before any further action:**\n> Epic Mode: <PROMOTE|DEMOTE> (p=<value>) \u2014 <one-sentence rationale or top blocking reason>\n> Dependencies: <task_id> \u2190 <deps>; \u2026 (omit if none)\n\nThe verdict is the user's only visibility into what Epic is doing \u2014 silence here makes the mode invisible. If you're going to spend time on this phase, tell the user why up front. Phrase it naturally; the format above is a guide, not a script.\n\n**4. `epic_plan_waves(directory, phase=N)`** \u2014 returns `{ waves: [{ waveId, taskIds, files }], serializedTasks, degradedTasks, degradationSummary }`. Failure reasons mirror step 2; additionally: `git-failed` (retry), `planner-error` (check `errors[0]`).\n\n**4b. Surface the wave plan to the user, before dispatching any `Task`:**\n> Wave plan (<N> waves): Wave 1 \u2192 [<ids>] (parallel); Wave 2 \u2192 [<ids>]; \u2026 \u2014 serialized [<ids>], degraded [<ids>]\n\nWalk them through which tasks run in which wave and what's parallel \u2014 naturally, in your own words. If `waves.length` exceeds the distinct-dependency-layer count, also flag the over-split and its likely cause (typical: a shared file like a barrel/registry in multiple scopes forces serial waves), e.g. \"Wave N split into K single-task waves because every scope claims `<shared-file>` \u2014 re-declare those tasks without it to restore parallelism, then re-plan.\"\n\n`serializedTasks` causes (NOT `declare_scope`-fixable): cycle, `no-scope`, `invalid-scope`, cap-exhaustion. Fix dep graph or scope contents, re-plan.\n\n`degradedTasks[].reason` keys:\n- `global file conflict` / `protected path` \u2192 balanced mode, dispatch per-task after waves\n- `cross-batch upstream not committed (greenfield-smart Rule 3): <ids>` \u2192 commit named upstreams, re-plan\n- `unresolved in-batch dependency: <ids>` \u2192 fix upstream degrade/serialize, re-plan\n- `planning leftover (no identifiable blocker)` \u2192 surface as planner bug\n\n**5. Dispatch each wave: `wave.taskIds.length` SEPARATE `Task` calls in ONE assistant message.** Per wave in order:\n- One `Task(subagent_type=\"coder\", description=\"Phase N task <id>\", prompt=\"<scope + acceptance>\")` per `taskId`\n- ALL in same turn \u2192 concurrent\n- Wait for all in wave to reach `update_task_status(completed)` + `epic_record_divergence` before next wave\n\n\u26A0\uFE0F **Three defects:**\n1. **Bundling**: multiple ids in one Task call \u2192 kills 1:1 coder visibility\n2. **Splitting across messages**: serial execution, no parallelism\n3. **Skipping single-task waves**: still emit ONE Task, wait for completion+divergence\n\nThis is the only sanctioned dispatch path. Don't use `lean_turbo_run_phase`; don't bundle through other tools \u2014 visibility requires `Task`.\n\n`serializedTasks` + `degradedTasks` (after wave loop): ONE Task per assistant message each, never batched, wait for completion+divergence between.\n\n**6. After each `update_task_status(completed)`, call `epic_record_divergence(directory, taskId, sessionID)`** (feeds calibration). If `summary.isClean: false`:\n> Divergence: task `<id>` wrote <undeclaredCount> undeclared file(s) (ratio <ratio>)\n\n### Phase-complete + audit\n\nPhase reviewer + critic still required at `phase_complete` (Epic Mode doesn't change Stage B).\n\nAudit (no architect needed): `/swarm epic status | last | decide | calibration`.\n";

package/dist/config/host-path.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Faithful transcription of OpenCode's path-canonicalisation helpers.
+ *
+ * ## Why this must exist
+ *
+ * The host asks for `external_directory` permission with a pattern it has run
+ * through `Filesystem.normalizePathPattern` — for example
+ * `src/tools/…` (offset 100715012):
+ *
+ * ```js
+ * let u = G.normalizePathPattern(Hr.join(y, "*"));
+ * yield* o.ask({ permission: "external_directory", patterns: [u], always: [u], … });
+ * ```
+ *
+ * Rule patterns from config get NO such treatment: `Permission.fromConfig`
+ * applies only `~` / `$HOME` expansion. So for a rule to match, its text must
+ * already equal what the host will produce for the asked path.
+ *
+ * That matters because `normalizePathPattern` resolves symlinks via
+ * `realpathSync.native`. A lane reached through a Windows junction (or a macOS
+ * `/var` → `/private/var` symlink) is asked for under its REAL path, while an
+ * un-canonicalised rule names the link path — so the lane is denied access to
+ * its own granted directory.
+ *
+ * Verbatim host source (`C:\OpenCode\opencode.exe`, opencode 1.18.10,
+ * offsets 107196170-107196420; the minified names resolve via the chunk's own
+ * imports at offset 107192671: `ky`=`path.resolve`, `yy`=`path.join`,
+ * `ek`=`fs.realpathSync`):
+ *
+ * ```js
+ * function j(F){ let z=ky(X(F)); try{ return ek.native(z) }catch{ return z } }
+ * YW.normalizePath = j;
+ *
+ * function J(F){
+ *   if(F==="*") return F;
+ *   let z=F.match(/^(.*)[\\/]\*$/);
+ *   if(!z) return j(F);
+ *   let Z=/^[A-Za-z]:$/.test(z[1]) ? z[1]+"\\" : z[1];
+ *   return yy(j(Z),"*");
+ * }
+ * YW.normalizePathPattern = J;
+ *
+ * function X(F){ return F
+ *   .replace(/^\/([a-zA-Z]):(?:[\\/]|$)/,(z,Z)=>`${Z.toUpperCase()}:/`)
+ *   .replace(/^\/([a-zA-Z])(?:\/|$)/,(z,Z)=>`${Z.toUpperCase()}:/`)
+ *   .replace(/^\/cygdrive\/([a-zA-Z])(?:\/|$)/,(z,Z)=>`${Z.toUpperCase()}:/`)
+ *   .replace(/^\/mnt\/([a-zA-Z])(?:\/|$)/,(z,Z)=>`${Z.toUpperCase()}:/`) }
+ * YW.windowsPath = X;
+ * ```
+ *
+ * If a future OpenCode release changes these, lane rules stop matching. The
+ * shared-normaliser tests in `tests/unit/config/lane-permissions.test.ts` are
+ * the tripwire — re-extract before "fixing" them.
+ *
+ * @module config/host-path
+ */
+/**
+ * Test-only DI seam (AGENTS.md invariant 7). Lets tests simulate a symlink /
+ * junction without creating one, and assert the ENOENT degradation.
+ */
+export declare const _internals: {
+    realpathSyncNative: (p: string) => string;
+};
+/** Host `Filesystem.windowsPath`. */
+declare function hostWindowsPath(input: string): string;
+/**
+ * Host `Filesystem.normalizePath`: `realpathSync.native(path.resolve(windowsPath(p)))`,
+ * degrading to the un-realpath'd resolved form on ANY realpath failure.
+ *
+ * The host uses a bare `catch` here (not an ENOENT check), so a permission
+ * error degrades identically to a missing path. Transcribed as-is: diverging
+ * would make our rule text disagree with the host's asked text in exactly the
+ * cases where a lane is already having filesystem trouble.
+ */
+declare function hostNormalizePath(input: string): string;
+/**
+ * Host `Filesystem.normalizePathPattern`.
+ *
+ * Canonicalises the DIRECTORY part of a `<dir>/*` pattern and re-appends the
+ * wildcard, leaving the bare `*` catch-all untouched. Note the drive-root
+ * special case: for `C:/*` the captured directory is `C:` which
+ * `path.resolve` would turn into the process's current directory on that
+ * drive, so the host appends a separator first.
+ */
+export declare function hostNormalizePathPattern(pattern: string): string;
+/**
+ * Tier-0 test seam (writing-tests skill): pure transcriptions with no external
+ * dependency beyond the DI'd realpath. Only {@link hostNormalizePathPattern} is
+ * consumed by production code, so these stay internal.
+ */
+export declare const _test_exports: {
+    hostWindowsPath: typeof hostWindowsPath;
+    hostNormalizePath: typeof hostNormalizePath;
+};
+export {};

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