opencode-swarm 7.138.2 → 7.138.4

package/dist/scope/path-identity.d.ts

@@ -0,0 +1,27 @@
+import * as path from 'node:path';
+/** Filesystem identity semantics used for comparisons, never for I/O. */
+export type PathFlavor = 'win32' | 'posix';
+export declare function getPathFlavor(pathLib?: Pick<typeof path, 'sep'>): PathFlavor;
+/**
+ * Produces a comparison-only path identity. Windows identities case-fold and
+ * normalize both slash forms; POSIX identities preserve case.
+ */
+export declare function normalizePathIdentity(value: string, flavor?: PathFlavor): string;
+export declare function pathIdentitiesEqual(a: string, b: string, flavor?: PathFlavor): boolean;
+/** True when target is the container itself or a descendant of it. */
+export declare function isPathIdentityWithin(target: string, container: string, flavor?: PathFlavor): boolean;
+/**
+ * Resolves a candidate and declared entries with one filesystem flavor, then
+ * applies the canonical identity containment rule. This is the shared scope
+ * predicate for guardrails, completion observers, and authority evaluation.
+ */
+export declare function isPathWithinDeclaredScope(filePath: string, scopeEntries: readonly string[], cwd?: string, flavor?: PathFlavor): boolean;
+/**
+ * Compares drive/UNC/extended-device roots with Windows case-insensitive
+ * identity while retaining POSIX case-sensitive path semantics.
+ */
+export declare function isOnDifferentPathRoot(target: string, cwd: string, flavor?: PathFlavor): boolean;
+/** Returns a safe, caller-facing reason when path text is deceptive. */
+export declare function unsafePathTextReason(value: string): string | null;
+/** Single-line, bounded rendering for untrusted diagnostic fields. */
+export declare function sanitizeDiagnosticText(value: unknown, maxLength?: number): string;

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

@@ -1,8 +1,18 @@
 import type { Plan } from '../config/plan-schema';
 export declare const MAX_PENDING_SCOPE_BINDINGS = 256;
+export declare const DEFAULT_SCOPE_BINDING_TTL_MS: number;
+export declare const MAX_SCOPE_BINDING_TOMBSTONES = 256;
+export type ScopeBindingLifecycleState = 'live' | 'expired' | 'revoked' | 'superseded';
 export type ScopeBindingSource = 'declare_scope' | 'plan' | 'file_directive' | 'pr_feedback' | 'worktree_derived';
 export interface ScopeBinding {
     version: 2;
+    /** Stable logical authority identity across lifecycle generations. */
+    bindingId: string;
+    /** Exact immutable generation identity used by persistence and cleanup. */
+    generationId: string;
+    /** Monotonic CAS revision within one generation. */
+    revision: number;
+    lifecycleState: ScopeBindingLifecycleState;
     workspaceIdentity: string;
     planId: string;
     planStructureHash: string;
@@ -14,14 +24,43 @@ export interface ScopeBinding {
     activation: 'declaration' | 'pending_child' | 'active';
     parentOwnerSessionId?: string;
     parentCallId?: string;
+    predecessorGenerationId?: string;
+    childSessionId?: string;
     /** PR_FEEDBACK bindings carry their parent workflow identity and revision. */
     workflowSessionId?: string;
     workflowRevisionDigest?: string;
     source: ScopeBindingSource;
     files: string[];
     declaredAt: number;
+    updatedAt: number;
+    leaseStartedAt: number;
     expiresAt: number;
 }
+export declare const MAX_SCOPE_PATH_BYTES = 4096;
+export declare const MAX_SCOPE_FILES_BYTES: number;
+export type ScopeBindingAdmissionResult = {
+    ok: true;
+    binding: ScopeBinding;
+} | {
+    ok: false;
+    code: 'SCOPE_BINDING_CAPACITY' | 'SCOPE_BINDING_STALE';
+    message: string;
+};
+export type ScopeBindingResolution = {
+    status: 'found';
+    binding: ScopeBinding;
+} | {
+    status: 'expired';
+    candidates: ScopeBinding[];
+    totalCandidates: number;
+} | {
+    status: 'ambiguous';
+    candidates: ScopeBinding[];
+    totalCandidates: number;
+} | {
+    status: 'not_declared';
+};
+export declare function isScopeBindingIdentity(value: unknown): value is string;
 export declare function canonicalWorkspaceIdentity(directory: string): string | null;
 export declare function normalizeScopeFiles(files: readonly string[]): string[] | null;
 export declare function createScopeBinding(input: {
@@ -36,7 +75,7 @@ export declare function createScopeBinding(input: {
     activation?: ScopeBinding['activation'];
     ttlMs?: number;
 }): ScopeBinding | null;
-export declare function registerScopeBinding(binding: ScopeBinding): void;
+export declare function registerScopeBinding(binding: ScopeBinding): ScopeBindingAdmissionResult;
 /**
  * Resolve the binding created for one fully-approved parent Task dispatch.
  * An already-claimed child binding wins over its pending parent precursor;
@@ -83,6 +122,14 @@ export declare function getAuthorizedScopeBindingByPlanIdentity(input: {
     taskId: string;
     activeSessionId: string;
 }): ScopeBinding | null;
+/** Resolve authorization without collapsing expired and ambiguous states. */
+export declare function resolveAuthorizedScopeBindingByPlanIdentity(input: {
+    directory: string;
+    planId: string;
+    planStructureHash: string;
+    taskId: string;
+    activeSessionId: string;
+}): ScopeBindingResolution;
 /**
  * Issue #2002 recurrence guardrail (detection half).
  *
@@ -144,6 +191,22 @@ export declare function describeScopeWorkspaceMismatch(input: {
     taskId?: string | null;
 }): string | null;
 export declare function clearScopeBindings(predicate?: (binding: ScopeBinding) => boolean): ScopeBinding[];
+/** Remove one exact generation; sibling generations are never affected. */
+export declare function clearExactScopeBinding(input: {
+    bindingId: string;
+    generationId: string;
+}): ScopeBinding | null;
+export declare function installScopeBindingTombstone(binding: ScopeBinding): void;
+export declare function hasScopeBindingDenyOverlay(binding: ScopeBinding): boolean;
+/** Fail-closed overlay used only when durable revocation cannot be verified. */
+export declare function installFailedRevocationOverlay(binding: ScopeBinding, reason: Exclude<ScopeBindingLifecycleState, 'live'>): boolean;
+/**
+ * Installs an immediate generation-wide deny intent before durable retirement
+ * contends with refresh. Unlike the failure-only overlay, cleanup owns the
+ * whole exact generation and therefore deliberately follows a newer revision.
+ */
+export declare function installScopeBindingRetirementIntent(binding: Pick<ScopeBinding, 'bindingId' | 'generationId'> & Partial<ScopeBinding>): ScopeBinding | null;
+export declare function updateExactScopeBinding(binding: ScopeBinding): ScopeBindingAdmissionResult;
 /**
  * Atomically claim the pending scope for the exact Task call whose upstream
  * metadata identified the actual OpenCode child session. The call id is part of
@@ -158,6 +221,11 @@ export declare function claimScopeBindingForChild(input: {
     previous: ScopeBinding;
     claimed: ScopeBinding;
 } | null;
+export declare function createClaimedScopeBinding(previous: ScopeBinding, input: {
+    parentSessionId: string;
+    childSessionId: string;
+    dispatchCallId: string;
+}): ScopeBinding;
 export declare function deriveChildScopeBinding(parent: ScopeBinding, input: {
     childDirectory: string;
     childSessionId: string;
@@ -181,5 +249,25 @@ export declare function resolveCoderScopeSources(input: {
     source: 'declare_scope' | 'plan' | 'file_directive';
 } | {
     ok: false;
-    code: 'SCOPE_NOT_DECLARED' | 'SCOPE_CONFLICT';
+    code: 'SCOPE_NOT_DECLARED';
+    sources?: ScopeSourceSets;
+} | {
+    ok: false;
+    code: 'SCOPE_CONFLICT';
+    authoritativeSource: 'declare_scope' | 'plan';
+    authoritativeFiles: string[];
+    conflictingSource: 'plan' | 'file_directive';
+    conflictingFiles: string[];
+    disagreement: string[];
+    sources: ScopeSourceSets;
 };
+interface ScopeSourceSets {
+    explicit: string[] | null;
+    plan: string[] | null;
+    directives: string[] | null;
+}
+/** One bounded renderer shared by normal and PR-feedback preflight paths. */
+export declare function formatCoderScopeConflict(decision: Extract<ReturnType<typeof resolveCoderScopeSources>, {
+    ok: false;
+}>): string;
+export {};

package/dist/scope/scope-lease-renewal.d.ts

@@ -0,0 +1,28 @@
+import type { ScopeBinding } from './scope-binding.js';
+import { refreshScopeBindingLease, type ScopePersistenceResult } from './scope-persistence.js';
+export interface ScopeLeaseCandidateInput {
+    callID: string;
+    sessionID: string;
+    tool: string;
+    directory: string;
+    binding: ScopeBinding;
+    targets: string[];
+    args?: unknown;
+}
+export interface ScopeLeaseAfterOutput {
+    title?: unknown;
+    output?: unknown;
+    metadata?: unknown;
+}
+export interface ScopeLeaseRenewalTracker {
+    remember(input: ScopeLeaseCandidateInput): void;
+    consume(input: {
+        callID: string;
+        sessionID: string;
+        tool: string;
+        output: ScopeLeaseAfterOutput | null | undefined;
+    }): Promise<ScopePersistenceResult | null>;
+}
+type RefreshLease = typeof refreshScopeBindingLease;
+export declare function createScopeLeaseRenewalTracker(refresh?: RefreshLease, now?: () => number): ScopeLeaseRenewalTracker;
+export {};

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

@@ -1,9 +1,10 @@
 /**
  * Scope persistence for #519 (v6.71.1 hotfix).
  *
- * Persists declared coder scope to `.swarm/scopes/scope-{taskId}.json` so that
- * scope survives cross-process delegation — in-memory `session.declaredCoderScope`
- * is lost when a coder session starts in a separate process (#496 root cause B).
+ * Retains the legacy v1 `.swarm/scopes/scope-{taskId}.json` projection used by
+ * worktree materialization, and persists authorization-capable v2 bindings as
+ * exact identity/generation records. Durable v2 state is authoritative across
+ * processes; memory is only a cache and can never revive a retired generation.
  *
  * Also exposes a fallback reader that reads `plan.json:phases[].tasks[].files_touched`
  * for the active task, so architect-authored plans become a durable scope source
@@ -13,7 +14,8 @@
  *   - Atomic write via temp + rename (POSIX atomic on same filesystem).
  *   - File lock via proper-lockfile while writing.
  *   - Schema versioning: readers fail closed on unknown version.
- *   - TTL: default 24h from declaredAt; expired scopes return null.
+ *   - Legacy v1 TTL: default 24h from declaredAt; expired projections return null.
+ *   - V2 lifecycle: typed live/expired/revoked/ambiguous/overloaded decisions.
  *   - Symlink guards (defence in depth):
  *       * realpath containment check on `.swarm/scopes/` (closes parent-dir attack)
  *       * O_NOFOLLOW on both write-create and read-fd (closes leaf-file TOCTOU)
@@ -31,20 +33,15 @@
  *   - This is command-level containment, not an operating-system syscall sandbox.
  *
  * RESIDUAL RISKS:
- *   1. Platform-portability of symlink guards:
+ *   1. Platform-portability of legacy v1 symlink guards:
  *        - realpath resolves POSIX symlinks and Windows junctions, but the
  *          Windows behaviour is not covered by CI (Linux-only test matrix).
  *        - O_NOFOLLOW is a no-op on Windows (falls back to 0). The realpath
  *          containment check on `.swarm/scopes/` remains the primary guard
  *          on that platform; leaf-file TOCTOU on Windows is not closed.
- *   2. Stale lockfile DoS: a crashed writer leaves a lock for up to
- *      LOCK_STALE_MS (30s). During that window, concurrent `declare_scope`
- *      calls fail silently and the architect relies on in-memory state.
- *      Acceptable because in-memory state remains authoritative inside the
- *      live process; disk is a fallback.
- *   3. Temp-file leak: a crash between `Bun.write(tmp)` and `renameSync`
- *      leaves `scope-{id}.json.tmp.{ts}.{rand}` files. No sweeper runs today;
- *      accumulation is bounded by `/swarm close` (which rm -rf's .swarm/scopes/).
+ *   2. Legacy v1 temp-file leak: a crash between atomic-write steps can leave
+ *      temporary projection files. V2 lifecycle maintenance is bounded and
+ *      prunes settled receipts, tombstones, sidecars, and retirement intents.
  *
  * NOT a standalone syscall security boundary. Shell-write detection and the
  * central write-target resolver provide command-level interception; this module
@@ -53,6 +50,31 @@
 import { type Plan } from '../config/plan-schema';
 import { type ScopeBinding } from './scope-binding';
 declare const SCOPE_SCHEMA_VERSION: 1;
+export type ScopePersistenceCode = 'SCOPE_NOT_DECLARED' | 'SCOPE_BINDING_PERSISTENCE_FAILED' | 'SCOPE_BINDING_CAPACITY' | 'SCOPE_BINDING_ALREADY_CLAIMED' | 'SCOPE_BINDING_AMBIGUOUS' | 'SCOPE_BINDING_EXPIRED' | 'SCOPE_BINDING_STORE_OVERLOADED' | 'SCOPE_BINDING_STALE';
+export type ScopePersistenceResult<T = ScopeBinding> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    code: ScopePersistenceCode;
+    message: string;
+};
+export type DurableScopeBindingResolution = {
+    status: 'found';
+    binding: ScopeBinding;
+} | {
+    status: 'expired';
+    candidates: ScopeBinding[];
+    totalCandidates: number;
+} | {
+    status: 'ambiguous';
+    candidates: ScopeBinding[];
+    totalCandidates: number;
+} | {
+    status: 'overloaded';
+} | {
+    status: 'not_declared';
+};
 export interface PersistedScope {
     version: typeof SCOPE_SCHEMA_VERSION;
     taskId: string;
@@ -62,11 +84,11 @@ export interface PersistedScope {
 }
 export type PersistedScopeBinding = ScopeBinding;
 /**
- * Write declared scope to `.swarm/scopes/scope-{taskId}.json` atomically.
+ * Write the legacy v1 `.swarm/scopes/scope-{taskId}.json` projection atomically.
  * Safe to call concurrently — proper-lockfile serialises writers per-file.
  *
- * Silent on I/O failure: scope persistence is a defense-in-depth layer, not a
- * hard requirement. In-memory state remains authoritative for the live process.
+ * Silent on I/O failure for backward compatibility. This projection is not an
+ * authorization source; v2 callers use the fail-closed exact-generation APIs.
  */
 export declare function writeScopeToDisk(directory: string, taskId: string, files: string[], ttlMs?: number): Promise<void>;
 /**
@@ -74,7 +96,9 @@ export declare function writeScopeToDisk(directory: string, taskId: string, file
  * compatibility with older non-authorization consumers, but strict Task
  * preflight and declare_scope use only this schema.
  */
-export declare function writeScopeBindingToDisk(directory: string, binding: ScopeBinding): Promise<void>;
+export declare function writeScopeBindingToDisk(directory: string, binding: ScopeBinding): Promise<ScopePersistenceResult>;
+/** Mandatory transaction: durable verification precedes memory authority. */
+export declare function persistAndRegisterScopeBinding(directory: string, binding: ScopeBinding): Promise<ScopePersistenceResult>;
 /** Read and fully validate a v2 binding; v1 records never authorize here. */
 export declare function readScopeBindingFromDisk(input: {
     directory: string;
@@ -85,17 +109,67 @@ export declare function readScopeBindingFromDisk(input: {
     requireDispatchCorrelation?: boolean;
     requireDeclaration?: boolean;
 }): ScopeBinding | null;
+export declare function resolveScopeBindingFromDisk(input: {
+    directory: string;
+    taskId: string;
+    plan: Plan;
+    ownerSessionId: string;
+    parentCallId?: string;
+    requireDispatchCorrelation?: boolean;
+    requireDeclaration?: boolean;
+    includeExpired?: boolean;
+}): DurableScopeBindingResolution;
 /** Remove one identity-bound authorization without disturbing sibling sessions. */
 export declare function clearScopeBindingFromDisk(input: {
     directory: string;
+    binding: ScopeBinding;
+}): ScopePersistenceResult;
+export declare function tombstoneScopeBinding(directory: string, binding: ScopeBinding, reason: 'expired' | 'revoked' | 'superseded'): Promise<ScopePersistenceResult>;
+/** CAS renewal for one exact active generation. */
+export declare function refreshScopeBindingLease(input: {
+    directory: string;
+    bindingId: string;
+    generationId: string;
+    expectedRevision: number;
+    activeSessionId: string;
     taskId: string;
-    ownerSessionId: string;
-}): void;
+    ttlMs?: number;
+}): Promise<ScopePersistenceResult>;
+/**
+ * Cross-process, successor-first claim transaction. All contenders for one
+ * pending generation lock the same stable receipt path.
+ */
+export declare function claimScopeBindingForChildDurably(input: {
+    directory: string;
+    parentSessionId: string;
+    childSessionId: string;
+    dispatchCallId: string;
+}): Promise<ScopePersistenceResult<{
+    previous: ScopeBinding;
+    claimed: ScopeBinding;
+}>>;
+/**
+ * Declaration transaction used by declare_scope. Replacement is restricted to
+ * the same canonical workspace, task, and owning architect session.
+ */
+export declare function replaceExistingScopeDeclaration(input: {
+    directory: string;
+    binding: ScopeBinding;
+    replaceExisting: boolean;
+}): Promise<ScopePersistenceResult>;
+export declare function flushScopeBindingMaintenance(directory?: string): Promise<void>;
+/** Prune old non-authorizing generations and settled receipts under one lock. */
+export declare function pruneScopeBindingTombstones(directory: string): Promise<ScopePersistenceResult<number>>;
 export declare function resolveAuthorizedScopeBinding(input: {
     directory: string;
     taskId: string;
     activeSessionId: string;
 }): ScopeBinding | null;
+export declare function resolveAuthorizedScopeBindingDetailed(input: {
+    directory: string;
+    taskId: string;
+    activeSessionId: string;
+}): DurableScopeBindingResolution;
 /**
  * Recover one unambiguous child binding after an in-memory session restart.
  * Every candidate is still checked against current plan identity, exact child
@@ -105,12 +179,21 @@ export declare function resolveAuthorizedScopeBindingForSession(input: {
     directory: string;
     activeSessionId: string;
 }): ScopeBinding | null;
+export declare function resolveAuthorizedScopeBindingForSessionDetailed(input: {
+    directory: string;
+    activeSessionId: string;
+}): DurableScopeBindingResolution;
 /** Recover one exact planless PR_FEEDBACK child binding after plugin restart. */
 export declare function resolveAuthorizedPrFeedbackScopeBindingFromDisk(input: {
     directory: string;
     activeSessionId: string;
     taskId?: string;
 }): ScopeBinding | null;
+export declare const _scopePersistenceInternals: {
+    liveBindingCapacity: number;
+    bindingFileScanCapacity: number;
+    maintenanceFileScanCapacity: number;
+};
 /**
  * Read persisted scope for a task. Returns null on:
  *   - file missing

package/dist/scope/scope-resolution-diagnostic.d.ts

@@ -0,0 +1,7 @@
+import type { DurableScopeBindingResolution } from './scope-persistence.js';
+/** One bounded, single-line recovery contract for durable binding lookup failures. */
+export declare function formatScopeResolutionDiagnostic(input: {
+    resolution: DurableScopeBindingResolution;
+    taskId: string | null;
+    sessionId: string;
+}): string | null;

package/dist/tools/declare-scope.d.ts

@@ -4,6 +4,7 @@
  * This tool must be called before delegating to coder to enable scope containment checking.
  */
 import type { ToolDefinition } from '@opencode-ai/plugin/tool';
+import type { AuthorityConfig } from '../config/schema';
 /**
  * Arguments for the declare_scope tool
  */
@@ -11,6 +12,7 @@ export interface DeclareScopeArgs {
     taskId: string;
     files: string[];
     whitelist?: string[];
+    replace_existing?: boolean;
     working_directory?: string;
 }
 /**
@@ -47,7 +49,7 @@ export declare function executeDeclareScope(args: DeclareScopeArgs, fallbackDir?
     sessionID: string;
     messageID: string;
     agentName?: string;
-}): Promise<DeclareScopeResult>;
+}, authorityConfig?: AuthorityConfig): Promise<DeclareScopeResult>;
 /**
  * Tool definition for declare_scope
  */

package/dist/tools/save-plan.d.ts

@@ -23,6 +23,8 @@ export interface SavePlanArgs {
             size?: 'small' | 'medium' | 'large';
             depends?: string[];
             acceptance?: string;
+            /** Exact project-relative paths this task is expected to modify. */
+            files_touched?: string[];
             /** Spec FR-###/SC-### IDs this task maps to (issue #1687, FR-000). */
             fr_refs?: string[];
         }>;

package/dist/tools/write-pr-review-trigger-eval.d.ts

@@ -27,7 +27,7 @@ declare const WritePrReviewTriggerEvalArgsSchema: z.ZodObject<{
             "unclassified-risk": "unclassified-risk";
         }>;
         result: z.ZodLiteral<"MATCHED">;
-        evidence: z.ZodString;
+        evidence: z.ZodOptional<z.ZodString>;
         source_batch_id: z.ZodString;
         source_lane_id: z.ZodString;
     }, z.core.$strict>, z.ZodObject<{
@@ -45,7 +45,7 @@ declare const WritePrReviewTriggerEvalArgsSchema: z.ZodObject<{
             "unclassified-risk": "unclassified-risk";
         }>;
         result: z.ZodLiteral<"NOT_TRIGGERED">;
-        evidence: z.ZodString;
+        evidence: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>], "result">>;
 }, z.core.$strict>;
 export type WritePrReviewTriggerEvalArgs = z.infer<typeof WritePrReviewTriggerEvalArgsSchema>;

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

@@ -15,7 +15,7 @@
  *
  * This module publishes that authority using the same primitives as the
  * standard worktree path (`src/hooks/delegation-gate.ts`, the
- * `savePlan` → `deriveChildScopeBinding` → register + `writeScopeBindingToDisk`
+ * `savePlan` → `deriveChildScopeBinding` → `persistAndRegisterScopeBinding`
  * sequence), so every identity condition in
  * `getAuthorizedScopeBindingByPlanIdentity` is satisfied without weakening or
  * bypassing any of them.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.138.2",
+	"version": "7.138.4",
 	"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",