opencode-swarm 7.134.3 → 7.135.1

package/dist/scope/scope-binding.d.ts

@@ -83,6 +83,66 @@ export declare function getAuthorizedScopeBindingByPlanIdentity(input: {
     taskId: string;
     activeSessionId: string;
 }): ScopeBinding | null;
+/**
+ * Issue #2002 recurrence guardrail (detection half).
+ *
+ * The defect class is: *a hook constructed once with the plugin-root
+ * `ctx.directory` applies that root to sessions that actually execute in a
+ * different root.* Its signature failure is silent — a binding for this exact
+ * session exists and is otherwise valid, but `workspaceIdentity` (filter
+ * condition #1 in `getAuthorizedScopeBindingByPlanIdentity`) never matches, so
+ * the lookup returns null and the caller reports a generic
+ * `SCOPE_NOT_DECLARED` that names neither root.
+ *
+ * This turns that silence into a precise, self-describing diagnostic at the one
+ * user-visible failure site (`src/hooks/scope-guard.ts`). It catches the class
+ * at ANY call site that resolves a binding with the wrong root — present or
+ * future — rather than only at the two gates fixed for this issue.
+ *
+ * Diagnostic-only: never grants or denies authorization. Callers still fall
+ * back to the ordinary `SCOPE_NOT_DECLARED` denial whenever this returns null.
+ *
+ * The candidate filter mirrors every non-workspace correlation clause
+ * `getAuthorizedScopeBindingByPlanIdentity` requires for an otherwise-valid
+ * Task-scoped authorization — dispatch correlation (`dispatchCallId` present
+ * and equal to `ownerMessageId`/`parentCallId`) plus a genuine parent/child
+ * session split — so a stale or malformed "active" leftover that never went
+ * through the real claim/derive path cannot be mislabeled as a workspace
+ * mismatch just because it happens to share session + task + `activation`.
+ * `pr_feedback` bindings are excluded outright: they resolve through an
+ * entirely separate authorization path
+ * (`getAuthorizedPrFeedbackScopeBinding` / `resolveAuthorizedPrFeedbackScopeBindingFromDisk`)
+ * that the caller already attempted before falling into this diagnostic, and
+ * a live `pr_feedback` binding otherwise satisfies every correlation clause
+ * above.
+ *
+ * `planId`/`planStructureHash` are deliberately NOT compared here: a
+ * plan-drifted binding at the SAME root is already excluded by the
+ * `workspaceIdentity` clause below (it would never have reached this
+ * diagnostic branch in the first place — the ordinary lookup would have
+ * rejected it on plan identity, not returned null for lack of a match at
+ * all). Reading the plan at `input.directory` to compare identities would
+ * also be unreliable here: `input.directory` is, by construction, the root
+ * this diagnostic suspects is wrong, so its `.swarm/plan.json` may not exist
+ * or may belong to an unrelated project — silently disabling the guardrail
+ * exactly where it matters most.
+ *
+ * Returns null (no mismatch claim) whenever `input.directory` itself cannot
+ * be resolved to a canonical identity (e.g. a deleted lane directory) —
+ * otherwise every active binding for the session would trivially satisfy
+ * `workspaceIdentity !== null`, misreporting a missing-directory failure as a
+ * wrong-root failure.
+ *
+ * @param input.directory - The root the caller resolved against
+ * @param input.activeSessionId - The session attempting the write
+ * @param input.taskId - Optional task filter
+ * @returns A human-readable mismatch description, or null
+ */
+export declare function describeScopeWorkspaceMismatch(input: {
+    directory: string;
+    activeSessionId: string;
+    taskId?: string | null;
+}): string | null;
 export declare function clearScopeBindings(predicate?: (binding: ScopeBinding) => boolean): ScopeBinding[];
 /**
  * Atomically claim the pending scope for the exact Task call whose upstream
@@ -103,6 +163,14 @@ export declare function deriveChildScopeBinding(parent: ScopeBinding, input: {
     childSessionId: string;
     parentCallId: string;
 }): ScopeBinding;
+/**
+ * Containment predicate shared by every scope consumer: a candidate path is
+ * covered by a scope entry when it is that entry or lives beneath it. Exported
+ * so authority-minting callers (e.g. the Lean Turbo lane publisher) narrow a
+ * candidate file set against plan authority using the *same* semantics the
+ * write gates later enforce, instead of re-implementing containment.
+ */
+export declare function scopeContains(scope: readonly string[], candidate: string): boolean;
 export declare function resolveCoderScopeSources(input: {
     explicitFiles: readonly string[] | null | undefined;
     planFiles: readonly string[] | null | undefined;

package/dist/services/status-service.d.ts

@@ -118,6 +118,16 @@ export interface StatusData {
         sharedRoot?: string;
         generation?: number;
     };
+    /** FR-010: last heartbeat activity for the session */
+    lastActivity?: {
+        sessionId: string;
+        /** epoch ms from getLastHeartbeat */
+        timestamp: number;
+        /** null when no heartbeat recorded */
+        agoMs: number | null;
+        /** human-readable: "5s ago", "12m ago", "2h ago", "never" */
+        agoLabel: string;
+    };
     /**
      * #1850: memory cohort link status. Distinct from `cohort` (knowledge link)
      * so status can distinguish knowledge-linked from memory-linked (acceptance
@@ -139,7 +149,7 @@ export interface StatusData {
  * Get status data from the swarm directory.
  * Returns structured data that can be used by GUI, background flows, or commands.
  */
-export declare function getStatusData(directory: string, agents: Record<string, AgentDefinition>): Promise<StatusData>;
+export declare function getStatusData(directory: string, agents: Record<string, AgentDefinition>, sessionId?: string): Promise<StatusData>;
 /**
  * Format status data as markdown for command output.
  * This is the thin adapter that delegates to the service.
@@ -149,4 +159,4 @@ export declare function formatStatusMarkdown(status: StatusData): string;
  * Handle status command - delegates to service and formats output.
  * Kept for backward compatibility - thin adapter.
  */
-export declare function handleStatusCommand(directory: string, agents: Record<string, AgentDefinition>): Promise<string>;
+export declare function handleStatusCommand(directory: string, agents: Record<string, AgentDefinition>, sessionId?: string): Promise<string>;

package/dist/session/snapshot-reader.d.ts

@@ -7,6 +7,12 @@ import type { SerializedAgentSession, SnapshotData } from './snapshot-writer';
 /**
  * Transient session fields that must be reset on rehydration.
  * Centralised here to keep the reset logic DRY and auditable.
+ *
+ * `workspaceDirectory` (issue #2002) deliberately does NOT belong in this
+ * list: it is never part of `SerializedAgentSession` in the first place (see
+ * the TRUST BOUNDARY / DELIBERATELY NOT SNAPSHOTTED comment at its field
+ * declaration in `src/state.ts`), so `deserializeAgentSession` never restores
+ * it and there is nothing here to reset.
  */
 export declare const TRANSIENT_SESSION_FIELDS: ReadonlyArray<{
     name: string;

package/dist/state.d.ts

@@ -226,6 +226,72 @@ export interface AgentSessionState {
     } | null;
     /** Declared file scope for current coder task (null = no scope declared) */
     declaredCoderScope: string[] | null;
+    /**
+     * Issue #2002: the root this session actually EXECUTES in, when it differs
+     * from the plugin-root `ctx.directory`.
+     *
+     * Worktree-isolated coder children are created with
+     * `session.create({ query: { directory: <lane> } })`, and their scope binding
+     * is derived and published against that lane. The write gates are constructed
+     * once at plugin init with `ctx.directory` and would otherwise resolve every
+     * session's binding, containment, and `.swarm/` reads against the project
+     * root — which can never match a lane-rooted binding.
+     *
+     * TRUST BOUNDARY: written ONLY by `recordSessionWorkspaceRoot`, whose single
+     * closed allowlist of production callers each pass `provisionWorktree`'s own
+     * output. `ensureAgentSession`'s `directory` argument (which can carry an
+     * agent-supplied `working_directory`, e.g. via `declare_scope`) must NEVER
+     * write this field.
+     *
+     * DELIBERATELY NOT SNAPSHOTTED (issue #2002 follow-up). `serializeAgentSession`
+     * (`src/session/snapshot-writer.ts`) intentionally omits this field, and it
+     * MUST stay omitted. The reason is trust, not oversight: `.swarm/session/state.json`
+     * lives under the project-root `.swarm/` directory, which the architect agent
+     * can write, so a restored string in that file is not a trusted resolution
+     * root — a tampered or stale snapshot could install an arbitrary root, or
+     * re-point a session at a *different* lane it never owned (cross-lane
+     * containment re-rooting). Persisting it would only be safe if rehydrate could
+     * revalidate the restored value against a durable, plugin-owned record of
+     * provisioned lanes, and no such record exists:
+     *   - `worktree-provisioning-owner.ts`'s durable marker
+     *     (`recordWorktreeProvisioningOwner`) stores no `worktreePath` at all, and
+     *     its `worktreeSessionId` field is always the *parent* session id
+     *     (`worktree-isolation.ts` passes `args.parentSessionID`, confirmed by
+     *     every production and test call site) — it cannot answer "does child
+     *     session X own lane path Y".
+     *   - `background-delegations.jsonl` (`src/background/pending-delegations.ts`)
+     *     does carry a `worktree.worktreePath` keyed by the child session id, but
+     *     it is written only inside the `isBackgroundTrue(...)` branch of
+     *     `delegation-gate.ts` (~line 3157) — i.e. only for `background: true` Task
+     *     dispatches. It is never written for the ordinary synchronous worktree
+     *     dispatch in `worktree-isolation.ts`, nor for the Lean Turbo dispatch in
+     *     `src/turbo/lean/lane-scope.ts`, which are the two actual
+     *     `recordSessionWorkspaceRoot` callers. It does not cover the field it
+     *     would need to validate.
+     *   - Re-deriving the expected path from `provisionWorktree`'s own naming
+     *     scheme (`resolveWorktreeBaseDir(directory, worktreeDir)/parentSessionId/taskId`,
+     *     or the `os.tmpdir()/swwt/...` Windows-shortened form) does not close the
+     *     gap either: it requires the child's *parent* session id, which is only
+     *     available from `delegationChains` in the very same untrusted snapshot —
+     *     validating one untrusted field with another untrusted field is circular,
+     *     not a validation. It would also require spawning `git worktree list` per
+     *     restored session inside `loadSnapshot`, which runs on the plugin-init
+     *     path under a bounded timeout (AGENTS.md invariant 1 / repro-704).
+     * Net effect: a plugin restart mid-lane loses the recorded root, and
+     * `resolveSessionWorkspaceDirectory` falls back to the plugin-root directory —
+     * fail-closed, byte-identical to pre-#2002 behaviour, never a widened
+     * authority (see its own doc comment). The lane coder is blocked with
+     * `SCOPE_NOT_DECLARED` (`src/hooks/scope-guard.ts`,
+     * `src/hooks/guardrails/tool-before.ts`) until a human/architect re-dispatches
+     * it, exactly like the pre-fix bug — not worse. `rehydrateState` (which would
+     * apply a restored value) only runs from `loadSnapshot`, itself only called at
+     * plugin init (`src/index.ts`), so this window is a real process restart, not
+     * something that can strip a live in-session lane coder of its root.
+     * Do NOT add this field to `TRANSIENT_SESSION_FIELDS`
+     * (`src/session/snapshot-reader.ts`) either — it is never restored in the
+     * first place, so there is nothing to reset.
+     */
+    workspaceDirectory?: string;
     /** Last scope violation message (null = no violation) */
     lastScopeViolation: string | null;
     /** Flag for one-shot scope violation warning injection in messagesTransform */
@@ -720,6 +786,58 @@ export declare function getAgentSession(sessionId: string): AgentSessionState |
  * @returns The AgentSessionState
  */
 export declare function ensureAgentSession(sessionId: string, agentName?: string, directory?: string): AgentSessionState;
+/**
+ * Issue #2002 — record the root a session actually EXECUTES in, when it
+ * differs from the plugin-root `ctx.directory`.
+ *
+ * TRUST BOUNDARY (security-critical): this function performs NO path
+ * validation. `laneRoot` is trusted purely because of WHO calls it, not
+ * because of its shape — `provisionWorktree` can legitimately relocate a lane
+ * outside the swarm worktree base (e.g. a `os.tmpdir()`-shortened path on
+ * Windows when the path-budget check trips), so a shape predicate would
+ * refuse a legitimately provisioned lane and silently reintroduce the bug
+ * this closes.
+ *
+ * The only thing standing between this setter and a privilege-escalation bug
+ * is a closed allowlist of production callers, each of which passes
+ * `provisionWorktree`'s own return value — never a tool argument, never
+ * `ensureAgentSession`'s `directory` parameter (which CAN carry an
+ * agent-supplied `working_directory`, e.g. via `declare_scope`). That
+ * allowlist is mechanically enforced by
+ * `tests/unit/state/session-workspace-root-trusted-callers.test.ts`. Adding a
+ * new call site is a privilege-escalation review, not a formality: the
+ * reviewer must confirm the new caller passes `provisionWorktree` output
+ * before adding it to that test's allowlist.
+ *
+ * A blank or whitespace-only `laneRoot` is ignored (treated as unset) rather
+ * than being recorded and later resolving to `path.resolve('')` (cwd).
+ *
+ * ORDERING IS PART OF THE CONTRACT. This never creates the session — callers
+ * MUST register it with its real agent name (`ensureAgentSession(sessionId,
+ * 'coder', laneRoot)`) FIRST. Calling this on an unregistered session is a
+ * deliberate no-op, so resolution falls back to the plugin root and the write
+ * is blocked. Creating the session here instead would register
+ * `swarmState.activeAgent` as 'unknown', which fails OPEN rather than closed —
+ * see the inline comment in the body for the full chain.
+ *
+ * @param sessionId - The session identifier
+ * @param laneRoot - `provisionWorktree`'s own output; never agent-supplied
+ */
+export declare function recordSessionWorkspaceRoot(sessionId: string, laneRoot: string): void;
+/**
+ * Issue #2002 — resolve the root a write gate should evaluate path
+ * containment and scope-binding lookups against for a given session.
+ *
+ * Fail-closed: returns `fallbackDirectory` (the plugin-root `ctx.directory`)
+ * whenever no root was recorded for this session, or the recorded value is
+ * blank/unset — i.e. byte-identical to pre-#2002 behaviour for every session
+ * that was never lane-rooted.
+ *
+ * @param sessionId - The session identifier
+ * @param fallbackDirectory - The plugin-root directory to fall back to
+ * @returns the session's recorded workspace root, or `fallbackDirectory`
+ */
+export declare function resolveSessionWorkspaceDirectory(sessionId: string, fallbackDirectory: string): string;
 /**
  * Update only the agent event timestamp (for stale detection).
  * Does NOT change agent name or reset guardrail state.

package/dist/telemetry.d.ts

@@ -10,6 +10,10 @@ export type ReviewerGateEvidenceKind = 'genuine' | 'fallback' | 'data_quality' |
  */
 export type ReviewerGateReasonCode = 'lean_turbo_completed_lane' | 'standard_turbo_non_tier3' | 'durable_evidence_complete' | 'workflow_state_complete' | 'stage_b_parallel_complete' | 'no_active_sessions' | 'zero_valid_sessions' | 'restart_recovery_complete' | 'scoped_delegation_complete' | 'unscoped_delegation_complete' | 'corrupt_evidence' | 'required_gates_missing' | 'inspection_error';
 export type TelemetryListener = (event: TelemetryEvent, data: Record<string, unknown>) => void;
+export declare function startHeartbeatTracking(): void;
+export declare function getLastHeartbeat(sessionId: string): number | undefined;
+export declare function stopHeartbeatTracking(): void;
+export declare function resetHeartbeatTrackingForTesting(): void;
 /**
  * Number of emits between rotation checks. 50 keeps the overhead at one
  * `statSync` per 50 telemetry writes (~once per few seconds in a busy
@@ -87,4 +91,5 @@ export declare const _internals: {
     telemetry: typeof telemetry;
     emit: typeof emit;
     rotateTelemetryIfNeeded: typeof rotateTelemetryIfNeeded;
+    heartbeatListenerCount: () => number;
 };

package/dist/turbo/lean/lane-scope.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Lean Turbo lane write authority (issue #2002 — Lean Turbo half).
+ *
+ * ## The defect this closes
+ *
+ * A Lean Turbo lane creates a coder session rooted at the lane worktree and
+ * dispatches it with `tools: { write: true, edit: true, patch: true }`
+ * (`src/turbo/lean/runner.ts`), but nothing ever published a v2 scope binding
+ * for that session and nothing ever materialized the authoritative plan into
+ * the lane. `resolveAuthorizedScopeBinding` starts from
+ * `readCurrentPlan(directory)` (`src/scope/scope-persistence.ts`), so with no
+ * `.swarm/plan.json` in the lane it returned null before it even looked at a
+ * binding — and every lane coder write failed `SCOPE_NOT_DECLARED` regardless
+ * of which directory the gate resolved.
+ *
+ * This module publishes that authority using the same primitives as the
+ * standard worktree path (`src/hooks/delegation-gate.ts`, the
+ * `savePlan` → `deriveChildScopeBinding` → register + `writeScopeBindingToDisk`
+ * sequence), so every identity condition in
+ * `getAuthorizedScopeBindingByPlanIdentity` is satisfied without weakening or
+ * bypassing any of them.
+ *
+ * ## Authority boundary
+ *
+ * A lane binding authorizes exactly the intersection of
+ *   1. `lane.files` — the file set the lane already holds exclusive locks on
+ *      (`acquireLaneLocks(directory, laneId, lane.files, agent, lane.taskIds[0], …)`
+ *      in `src/turbo/lean/runner.ts`), and
+ *   2. the authoritative plan's `files_touched` for the lane's own tasks.
+ *
+ * It therefore grants nothing the lane's pre-existing file locks did not
+ * already reserve for this dispatch, and nothing the plan does not attribute to
+ * this lane's tasks. It is rooted at the lane worktree, owned by the lane's
+ * child session id, and correlated to a single synthetic dispatch id — so it
+ * can never authorize a write in another lane or in the project root.
+ *
+ * ## Known gap (deliberate, not a bypass)
+ *
+ * A lane may carry several task ids (`src/turbo/lean/planner.ts` assigns every
+ * non-conflicting ready task to the first non-conflicting lane). The scope
+ * gates resolve a binding by a single `session.currentTaskId`, so a lane gets
+ * ONE binding labelled with the lane's representative task id
+ * (`lane.taskIds[0]`, the same representative the lock layer already uses) and
+ * carrying the lane's whole plan-backed authority. This mirrors the lock
+ * record 1:1; it does not widen the lane past what the lock already reserved.
+ *
+ * ## Fail-closed contract
+ *
+ * When a lane has no representative task id in strict `N.M[.P]` form, no
+ * plan-backed files, or an unusable child identity, this module publishes
+ * NOTHING and returns null. The lane coder then hits the ordinary
+ * `SCOPE_NOT_DECLARED` block — byte-identical to pre-fix behaviour. There is no
+ * path here that grants a lane coder write authority without a validated,
+ * plan-correlated, lane-rooted binding.
+ */
+import type { Plan } from '../../config/plan-schema';
+import { type ScopeBinding } from '../../scope/scope-binding';
+/**
+ * Namespace for the synthetic dispatch-call id that correlates a lane's child
+ * binding to its parent Lean Turbo run. Lean Turbo dispatches through the
+ * OpenCode session API rather than the Task tool, so there is no upstream
+ * `callID`. The prefix keeps these ids disjoint from real Task call ids so a
+ * lane binding can never be claimed by a Task-dispatch lookup.
+ */
+export declare const LEAN_TURBO_LANE_DISPATCH_PREFIX = "lean-turbo-lane";
+/** Minimal lane shape this module needs. Matches `LeanTurboLane`. */
+export interface LeanTurboLaneScopeLane {
+    laneId: string;
+    taskIds: readonly string[];
+    files: readonly string[];
+}
+export interface PublishLeanTurboLaneScopeInput {
+    /** Project root the Lean Turbo run was started in. */
+    primaryDirectory: string;
+    /** Root the lane's coder session actually executes in. */
+    laneRoot: string;
+    /**
+     * True only when `laneRoot` is `provisionWorktree`'s own output. Never
+     * derive this from a path comparison and never from an agent-supplied
+     * value: it gates both the lane plan materialization and the workspace-root
+     * recording, which are the two writes that must follow provisioning
+     * authority only.
+     */
+    isolated: boolean;
+    /** Authoritative plan for this run (already loaded from the project root). */
+    plan: Plan;
+    lane: LeanTurboLaneScopeLane;
+    /** Session running the Lean Turbo phase (the architect). */
+    parentSessionId: string;
+    /** Session id returned by `session.create` for this lane. */
+    childSessionId: string;
+}
+/**
+ * Resolve the file set a lane may be authorized for: lane-locked files that the
+ * authoritative plan also attributes to one of the lane's own tasks.
+ *
+ * Returns null when the plan attributes no usable file to this lane's tasks or
+ * when no locked lane file falls inside that plan authority — both are
+ * fail-closed outcomes, never a widening fallback.
+ */
+export declare function resolveLeanTurboLaneAuthorityFiles(plan: Plan, lane: LeanTurboLaneScopeLane): string[] | null;
+/**
+ * Publish one Lean Turbo lane's write authority.
+ *
+ * Ordering is deliberate:
+ *   1. validate identity and resolve plan-backed authority (cheap, no writes) —
+ *      a failure here publishes nothing at all;
+ *   2. materialize the authoritative plan into the lane (isolated lanes only,
+ *      so concurrent lanes never re-write the project's own plan ledger);
+ *   3. derive the active child binding, register it, and persist it under the
+ *      lane root;
+ *   4. bind the child session to the lane root so the write gates resolve
+ *      against the lane instead of the plugin-root `ctx.directory`.
+ *
+ * @returns the published child binding, or null when the lane cannot be
+ *   authorized (fail closed — the caller must NOT grant any substitute).
+ * @throws only on unexpected I/O failure (e.g. `savePlan` rejecting). The
+ *   caller treats a throw as a hard dispatch failure.
+ */
+export declare function publishLeanTurboLaneScopeBinding(input: PublishLeanTurboLaneScopeInput): Promise<ScopeBinding | null>;

package/dist/turbo/lean/runner.d.ts

@@ -16,13 +16,15 @@
  * - If dispatch fails, locks for that lane are released and lane is marked 'failed'
  */
 import type { OpencodeClient } from '@opencode-ai/sdk';
+import type { Plan } from '../../config/plan-schema';
 import type { LeanTurboConfig } from '../../config/schema';
 import { loadFullAutoRunState } from '../../full-auto/state';
 import { acquireLaneLocks, releaseLaneLocks } from '../../parallel/file-locks';
 import { loadPlanJsonOnly } from '../../plan/manager';
-import { ensureAgentSession, hasActiveFullAuto } from '../../state';
+import { hasActiveFullAuto } from '../../state';
 import { type ModelOverride } from '../../utils/model-dispatch-fallback';
 import { writeLaneEvidence, writePhaseEvidence } from './evidence';
+import { publishLeanTurboLaneScopeBinding } from './lane-scope';
 import { attemptMergeBackFromDirty, getMergeStrategy, mergeLaneBranch, postMergeCleanup, startupOrphanRecovery } from './merge-back';
 import { planLeanTurboLanes } from './planner';
 import type { LeanTurboDegradedTask, LeanTurboLane } from './state';
@@ -167,6 +169,32 @@ export interface LeanTurboPhaseResult {
     /** Lanes whose coder completed but merge-back to primary branch failed */
     mergeBackFailures?: MergeBackFailureInfo[];
 }
+/**
+ * Orchestrates Lean Turbo lane execution.
+ *
+ * ## Usage
+ *
+ * ```ts
+ * const runner = new LeanTurboRunner({
+ *   directory: projectRoot,
+ *   sessionID: 'sess-abc123',
+ *   opencodeClient: swarmState.opencodeClient,
+ *   generatedAgentNames: swarmState.generatedAgentNames,
+ * });
+ *
+ * const result = await runner.runPhase(1);
+ * // ... monitor lanes ...
+ * await runner.cleanup();
+ * ```
+ */
+/**
+ * Error code returned when a lane's write authority could not be published
+ * (issue #2002). Deliberately free of any token matched by
+ * `TRANSIENT_MODEL_ERROR_PATTERN` / `QUOTA_ERROR_PATTERN`, and classified
+ * `permanent` explicitly in `_processLane` so a broken authority handshake can
+ * never be mistaken for a provider blip and retried across fallback models.
+ */
+export declare const LANE_SCOPE_DENIED_CODE = "LEAN_TURBO_LANE_SCOPE_DENIED";
 export declare class LeanTurboRunner {
     /**
      * Test-only dependency-injection seam.
@@ -195,8 +223,11 @@ export declare class LeanTurboRunner {
         startupOrphanRecovery: typeof startupOrphanRecovery;
         getMergeStrategy: typeof getMergeStrategy;
         assertCleanWorkingTree: typeof assertCleanWorkingTree;
-        /** DI seam for ensureAgentSession — allows tests to intercept advisory queue writes. */
-        ensureAgentSession: typeof ensureAgentSession;
+        /**
+         * Issue #2002: publishes a lane's plan-correlated, lane-rooted write
+         * authority before the lane's coder prompt is sent.
+         */
+        publishLeanTurboLaneScopeBinding: typeof publishLeanTurboLaneScopeBinding;
     };
     /**
      * Test-only dependency-injection seam for session operations.
@@ -269,12 +300,43 @@ export declare class LeanTurboRunner {
      *
      * @param lane - Lane to dispatch
      * @param agentName - Agent name to dispatch to
+     * @param worktreeDirectory - Provisioned lane worktree, when isolation is on
+     * @param model - Per-call model override for a fallback attempt (#1896)
+     * @param plan - Authoritative plan for this run. Required to publish the
+     *   lane's write authority (issue #2002). When omitted, no binding is
+     *   minted AND the lane's `write`/`edit`/`patch` tools are force-disabled
+     *   (see `_doDispatch`) — an unscoped lane can never be dispatched
+     *   writable, regardless of caller. Only `_processLane` supplies a plan in
+     *   production (always, per `runPhase`'s own `NO_PLAN` guard); direct
+     *   callers that omit it get a read-only lane rather than a silent
+     *   unscoped-but-writable one.
      */
-    dispatchLane(lane: LeanTurboLane, agentName: string, worktreeDirectory?: string, model?: ModelOverride): Promise<LaneDispatchResult>;
+    dispatchLane(lane: LeanTurboLane, agentName: string, worktreeDirectory?: string, model?: ModelOverride, plan?: Plan): Promise<LaneDispatchResult>;
     /**
      * Internal dispatch implementation (separated for timeout wrapping).
      */
     private _doDispatch;
+    /**
+     * Publish the lane's write authority for a freshly created lane session
+     * (issue #2002 — Lean Turbo half).
+     *
+     * Two distinct fail-closed outcomes, deliberately kept apart:
+     *
+     * - **No authorizable lane** (`publishLeanTurboLaneScopeBinding` returns
+     *   null: representative task id not in strict `N.M[.P]` form, no
+     *   plan-backed files, unusable child identity). Nothing is published and
+     *   the lane still runs — the coder is blocked by the ordinary
+     *   `SCOPE_NOT_DECLARED` gate exactly as it was before this fix. An
+     *   architect advisory makes the unscoped lane visible instead of silent.
+     * - **Publication failed unexpectedly** (I/O error, plan materialization
+     *   rejected). That is not a pre-existing state, so the lane session is
+     *   torn down and the dispatch fails permanently rather than running a
+     *   coder whose authority is in an unknown state.
+     *
+     * @returns a failing `LaneDispatchResult` to abort the dispatch, or null to
+     *   continue.
+     */
+    private _publishLaneScope;
     /**
      * Get current status of all lanes tracked by this runner.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.134.3",
+	"version": "7.135.1",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",