opencode-swarm 7.138.4 → 7.139.1

package/dist/memory/injector.d.ts

@@ -34,9 +34,11 @@ export interface MemoryLifecycleHooks {
 }
 export declare function createMemoryLifecycleHooks(options: MemoryLifecycleHookOptions): MemoryLifecycleHooks;
 declare function messagesContainRecall(messages: unknown[]): boolean;
+declare function recallMessageInsertIndex(messages: unknown[]): number;
 declare function compactText(text: string): string;
 export type { ProposeMemoryInput, MemoryKind };
 export declare const _test_exports: {
     compactText: typeof compactText;
     messagesContainRecall: typeof messagesContainRecall;
+    recallMessageInsertIndex: typeof recallMessageInsertIndex;
 };

package/dist/plan/manager.d.ts

@@ -41,6 +41,7 @@ export interface AcknowledgedRemovals {
 import { type Plan, type RuntimePlan, type TaskStatus } from '../config/plan-schema';
 import { isGitRepo } from '../git/branch';
 import { getWorktreeMergeFailure } from '../hooks/delegation-gate/worktree-merge-status';
+import { recordTaskAttempt } from '../services/run-memory.js';
 import { isEpicModeActiveForProject } from '../turbo/epic/state.js';
 import { commitTaskCompletion } from '../turbo/epic/task-commit.js';
 import { readTaskScopes } from '../turbo/lean/conflicts.js';
@@ -64,6 +65,7 @@ export declare const _internals: {
     readTaskScopes: typeof readTaskScopes;
     commitTaskCompletion: typeof commitTaskCompletion;
     getWorktreeMergeFailure: typeof getWorktreeMergeFailure;
+    recordTaskAttempt: typeof recordTaskAttempt;
 };
 /** @internal Test seam for snapshot retry helper */
 export declare const _snapshot_test_exports: {

package/dist/services/context-budget-service.d.ts

@@ -42,7 +42,12 @@ export interface ContextBudgetReport {
 export interface ContextBudgetConfig {
     /** Enable or disable budget monitoring */
     enabled: boolean;
-    /** Maximum token budget (default: 40000) */
+    /**
+     * The context-window denominator, in tokens. Production callers derive this
+     * per-model via `resolveContextWindowTokens` (`src/config/context-window.ts`)
+     * and never pass a constant; `DEFAULT_CONTEXT_BUDGET_CONFIG.budgetTokens`
+     * below is only the no-information floor.
+     */
     budgetTokens: number;
     /** Warning threshold percentage (default: 70) */
     warningPct: number;

package/dist/services/run-memory.d.ts

@@ -16,7 +16,28 @@ export interface RunMemoryEntry {
     taskFingerprint: string;
     /** Which agent executed the task (e.g. "coder") */
     agent: string;
-    /** Outcome of the task execution */
+    /**
+     * Outcome of the task execution.
+     *
+     * PRODUCER COVERAGE (keep this note accurate — directive 2, no unwired code):
+     * - `pass` / `fail` are produced today by TWO call sites, deliberately split:
+     *   1. `plan/manager.updateTaskStatus` records the TERMINAL outcome after
+     *      savePlan succeeds — `completed` -> pass, `blocked` -> fail. It lives
+     *      there, not in the `update_task_status` tool, because the tool is only
+     *      one of two writers: the council APPROVE fast-path completes tasks via
+     *      `advanceTaskStateAndPersist` (src/state.ts) with no tool call.
+     *   2. `update_task_status` records a `fail` when a council or QA gate
+     *      BLOCKS a completion. That is a refusal, not a status transition, so
+     *      it never reaches updateTaskStatus and must be recorded at the tool.
+     * - `retry` has a CONSUMER (`summarizeTask` below treats it like `fail`) but
+     *   no producer. It is deliberately retained for the guardrails
+     *   transient-retry path (AGENTS.md invariant 9), which owns retry
+     *   accounting and is out of scope here. Do not add a `retry` producer from
+     *   the task-status path — a gate block is a real failure, not a retry.
+     * - `skip` has neither producer nor consumer (`summarizeTask` ignores it).
+     *   It is retained only so pre-existing `.swarm/run-memory.jsonl` lines
+     *   written by hand or by older builds still parse.
+     */
     outcome: 'pass' | 'fail' | 'retry' | 'skip';
     /** 1-indexed attempt number */
     attemptNumber: number;
@@ -51,12 +72,39 @@ export declare function recordOutcome(directory: string, entry: RunMemoryEntry):
  */
 export declare function getTaskHistory(directory: string, taskId: string): Promise<RunMemoryEntry[]>;
 /**
- * Get all failure and retry entries
+ * Input for {@link recordTaskAttempt}. `attemptNumber` and `taskFingerprint`
+ * are derived, not supplied — callers know the task, not its history.
+ */
+export interface TaskAttemptInput {
+    /** Plan.json task ID (e.g. "3.2") */
+    taskId: string;
+    /** Which agent executed the task (e.g. "coder") */
+    agent: string;
+    /** Outcome of this attempt */
+    outcome: RunMemoryEntry['outcome'];
+    /** One-line failure reason — required in practice for fail/retry to be useful */
+    failureReason?: string;
+    /** Plan `files_touched` for the task; feeds the fingerprint */
+    fileTargets?: string[];
+    /** Wall-clock time in milliseconds */
+    durationMs?: number;
+}
+/**
+ * Record one task attempt, deriving the attempt number from prior history.
+ *
+ * This is the single production producer for `.swarm/run-memory.jsonl`, which
+ * `getRunMemorySummary` reads back for cross-turn failure-pattern avoidance.
+ *
+ * Advisory-only and fail-open by contract: run memory is context enrichment,
+ * never a correctness gate, so a write failure must never surface to — or
+ * abort — the caller's primary operation (a task status update). The work is
+ * still awaited rather than fire-and-forget, so the entry is durable before the
+ * caller returns and a test can observe it.
  *
  * @param directory - The swarm workspace directory
- * @returns Array of fail/retry entries
+ * @param input - The attempt to record
  */
-export declare function getFailures(directory: string): Promise<RunMemoryEntry[]>;
+export declare function recordTaskAttempt(directory: string, input: TaskAttemptInput): Promise<void>;
 /**
  * Group entries by taskId
  */
@@ -79,8 +127,8 @@ export declare function getRunMemorySummary(directory: string): Promise<string |
 export declare const _internals: {
     generateTaskFingerprint: typeof generateTaskFingerprint;
     recordOutcome: typeof recordOutcome;
+    recordTaskAttempt: typeof recordTaskAttempt;
     getTaskHistory: typeof getTaskHistory;
-    getFailures: typeof getFailures;
     getRunMemorySummary: typeof getRunMemorySummary;
     groupByTaskId: typeof groupByTaskId;
     summarizeTask: typeof summarizeTask;

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

@@ -72,6 +72,20 @@ export interface StatusData {
     leanPauseReason?: string;
     /** Last known context budget percentage (0-100), or null if not yet measured */
     contextBudgetPct: number | null;
+    /**
+     * The DENOMINATOR `contextBudgetPct` was measured against, in tokens, or
+     * null when no budget report has run. Carried alongside the percentage
+     * because the denominator is now derived per-model (`model.limit.context`)
+     * rather than being a constant this renderer could assume. The renderer
+     * previously back-computed the estimate from
+     * `DEFAULT_CONTEXT_BUDGET_CONFIG.budgetTokens`, which was **40000** (not
+     * 128000 — that was the schema default for `model_limits.default`, a
+     * different constant on a different path). So the status line printed a
+     * figure that did not match the percentage beside it for any user whose
+     * warnings fired against anything other than 40000 — i.e. every user with a
+     * `model_limits` override, and now everyone, since the live window is used.
+     */
+    contextBudgetTokens?: number | null;
     /** Number of context compaction events triggered this session */
     compactionCount: number;
     /** ISO timestamp of last compaction snapshot, or null if none */

package/dist/state.d.ts

@@ -598,6 +598,24 @@ export declare const swarmState: {
     generatedAgentNames: string[];
     /** Last known context budget percentage (0-100), updated by system-enhancer */
     lastBudgetPct: number;
+    /**
+     * The DENOMINATOR `lastBudgetPct` was computed against, in tokens. Written
+     * by system-enhancer at the same two statements that write `lastBudgetPct`,
+     * because a percentage without its denominator cannot be turned back into a
+     * token estimate. `/swarm status` used to reconstruct the estimate from a
+     * hardcoded constant, so a user whose real denominator differed saw a token
+     * figure that did not match the percentage next to it. 0 means "no budget
+     * report has run yet".
+     */
+    lastBudgetTokens: number;
+    /**
+     * Live `model.limit.context` per session — keyed by sessionID, recorded by
+     * the `experimental.chat.system.transform` hook (the only hook the host
+     * gives a `Model` to) and read by the `experimental.chat.messages.transform`
+     * consumers, which receive messages but no model object. Bounded via
+     * {@link setLiveContextWindow} (AGENTS.md invariant 8).
+     */
+    liveContextWindows: Map<string, number>;
     /** Per-session guardrail state — keyed by sessionID */
     agentSessions: Map<string, AgentSessionState>;
     /** In-flight rehydration promises — awaited by rehydrateState before clearing agentSessions */
@@ -1142,6 +1160,25 @@ export declare function ensureSessionEnvironment(sessionId: string): Environment
 export declare const MAX_TRACKED_CRITICAL_SHOWN = 500;
 export declare const MAX_TRACKED_KNOWLEDGE_ACKS = 5000;
 export declare const MAX_TRACKED_GATE_DENIALS = 500;
+export declare const MAX_TRACKED_CONTEXT_WINDOWS = 500;
+/**
+ * Record the live `model.limit.context` the host reported for `sessionID`,
+ * FIFO-evicting the oldest entry past {@link MAX_TRACKED_CONTEXT_WINDOWS}.
+ *
+ * Only accepts a finite number ≥ 1 — the caller (`src/config/context-window.ts`
+ * `isUsableContextWindow`) applies the real plausibility floor, and storing a
+ * junk value here would hand it to every `messages.transform` consumer. A
+ * rejected value leaves any previously recorded window in place rather than
+ * clobbering it, so one malformed turn does not blank a good reading.
+ */
+export declare function setLiveContextWindow(sessionID: string | undefined, tokens: unknown): void;
+/**
+ * Read the live context window recorded for `sessionID`, or `undefined` when
+ * no `system.transform` has run for it yet (first turn of a session, or a
+ * consumer that never sees a sessionID). Callers must degrade to the static
+ * resolution rungs rather than assume a value.
+ */
+export declare function getLiveContextWindow(sessionID: string | undefined): number | undefined;
 /** Set the critical shown ids for a session, FIFO-evicting the oldest entry
  * if the cap is exceeded. Re-setting an existing key keeps insertion order
  * fresh for that key (delete-then-set). */

package/dist/tools/context-status.d.ts

@@ -79,9 +79,11 @@ export declare const _internals: {
  * @param warnThreshold - Usage ratio that triggers 'warn' state (default 0.7)
  * @param criticalThreshold - Usage ratio that triggers 'critical' state (default 0.9)
  * @param modelLimitsConfig - Model-specific limit overrides from config
+ * @param liveContextLimit - Live `model.limit.context` recorded for the session
+ *   by the system.transform hook; `undefined` when none has been seen yet
  * @returns Context status with token usage, limit, and threshold state
  */
-declare function computeContextHeadroom(messages: ContextMessage[], warnThreshold?: number, criticalThreshold?: number, modelLimitsConfig?: Record<string, number>): ContextStatusResult;
+declare function computeContextHeadroom(messages: ContextMessage[], warnThreshold?: number, criticalThreshold?: number, modelLimitsConfig?: Record<string, number>, liveContextLimit?: unknown): ContextStatusResult;
 /**
  * context_status tool — read-only context window headroom report.
  *

package/dist/tools/update-task-status.d.ts

@@ -6,6 +6,7 @@ import type { ToolContext, ToolDefinition } from '@opencode-ai/plugin/tool';
 import { readTaskEvidenceRaw } from '../gate-evidence.js';
 import { tryAcquireLock } from '../parallel/file-locks.js';
 import { loadPlan, updateTaskStatus } from '../plan/manager';
+import { recordTaskAttempt } from '../services/run-memory.js';
 import { hasActiveLeanTurbo, hasActiveTurboMode } from '../state';
 import { type ReviewerGateEvidenceKind, type ReviewerGateReasonCode } from '../telemetry.js';
 import { verifyLeanTurboTaskCompletion } from '../turbo/lean/task-completion';
@@ -26,6 +27,7 @@ export declare const _internals: {
     verifyLeanTurboTaskCompletion: typeof verifyLeanTurboTaskCompletion;
     hasPassedDurableGateEvidence: typeof hasPassedDurableGateEvidence;
     emitReviewerGateDecision: (sessionId: string, taskId: string, blocked: boolean, reasonCode: ReviewerGateReasonCode, evidenceKind: ReviewerGateEvidenceKind) => void;
+    recordTaskAttempt: typeof recordTaskAttempt;
 };
 /**
  * Arguments for the update_task_status tool

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

@@ -81,6 +81,16 @@ interface SessionClient {
             id: string;
         };
     }): Promise<void>;
+    /**
+     * Optional graceful abort. Present on the real opencode SDK session at
+     * runtime (absent on minimal test fakes). Teardown awaits it before delete
+     * so opencode flushes the final part/message (#2123).
+     */
+    abort?(options: {
+        path: {
+            id: string;
+        };
+    }): Promise<unknown>;
 }
 /**
  * Result of a single lane dispatch (session creation + prompt).

package/dist/utils/ephemeral-session-teardown.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Ephemeral opencode session teardown — abort-then-delete ordering that closes
+ * the FOREIGN KEY constraint race described in issue #2123.
+ *
+ * ## Why this exists
+ *
+ * opencode writes the final assistant `part`/`message` **asynchronously**, in
+ * `SessionProcessor.cleanup`, which runs as a stream-drain finalizer that can
+ * settle AFTER `session.prompt()` resolves. The `part.message_id` foreign key
+ * is `ON DELETE CASCADE`, so a `session.delete()` that lands before that flush
+ * cascade-removes the parent `message` row; opencode's late `updatePart`/
+ * `updateMessage` then fails with `SQLiteError: FOREIGN KEY constraint failed`
+ * (in opencode's own log — the plugin's `session.delete()` promise resolves
+ * fine, which is why a `.catch(() => {})` on the delete cannot prevent it).
+ *
+ * ## Why awaiting `session.abort()` fixes it
+ *
+ * `POST /session/{id}/abort` resolves only after `SessionRunState.cancel` →
+ * `Runner.cancel` → `Fiber.interrupt(runFiber)`. Effect's `Fiber.interrupt` runs
+ * every finalizer on the target fiber before resolving, and the run-loop fiber
+ * carries `Effect.ensuring(cleanup())`. Therefore, once `await session.abort()`
+ * resolves, opencode has already flushed the final part/message (or the session
+ * was already idle, in which case `cleanup` ran during natural completion).
+ * Source: opencode v1.18.16 — `packages/opencode/src/session/{run-state,runner,
+ * processor}.ts`.
+ *
+ * Because `cleanup` awaits each pending tool-call deferred with a 250 ms
+ * timeout, the abort step can block up to ~250 ms+ under interruption. Its
+ * bounded timeout must stay well above that (default 5 s) or it would give up
+ * before the flush lands and re-introduce the race.
+ */
+import { log } from './logger.js';
+/** Minimum lifecycle surface for tearing an ephemeral session down. */
+export interface EphemeralSessionLifecycle {
+    /** Server-side abort; optional because some session shims (tests, older hosts) lack it. */
+    abort?: (args: {
+        path: {
+            id: string;
+        };
+    }) => Promise<unknown>;
+    /** Hard delete the session and cascade its rows. */
+    delete: (args: {
+        path: {
+            id: string;
+        };
+    }) => Promise<unknown>;
+}
+export declare const DEFAULT_EPHEMERAL_ABORT_TIMEOUT_MS = 5000;
+export declare const DEFAULT_EPHEMERAL_TEARDOWN_DELETE_TIMEOUT_MS = 2000;
+export interface TeardownEphemeralSessionOptions {
+    /** Bounded timeout for the graceful abort step. Must stay > ~500 ms. */
+    abortTimeoutMs?: number;
+    /** Bounded timeout for the hard delete step. */
+    deleteTimeoutMs?: number;
+    /**
+     * Skip the abort step. Use only for sessions that were never prompted (no
+     * final part flush pending) — e.g. a session that timed out during
+     * `session.create` before `session.prompt` was ever called.
+     */
+    skipAbort?: boolean;
+}
+/**
+ * Race a session HTTP call against a bounded timer. The structural lifecycle
+ * type carries no `signal` (it must also fit the `SessionOps` shim), so the
+ * timer bounds the AWAIT only — it cannot pre-empt the in-flight SDK request,
+ * which is allowed to settle in the background. Mirrors `boundedDeleteEphemeralSession`
+ * in `src/evaluation/ephemeral-agent-dispatcher.ts`. Best-effort: never throws.
+ */
+declare function boundedSessionCall(call: () => Promise<unknown>, timeoutMs: number, timeoutLabel: string, failureLabel: string, sessionId: string): Promise<void>;
+/**
+ * Bounded graceful abort. Guarantees opencode has flushed the session's final
+ * part/message before resolving (or that the session was already idle). Never
+ * throws; logs timeouts/failures via the debug-gated logger.
+ */
+export declare function boundedAbortEphemeralSession(session: EphemeralSessionLifecycle, sessionId: string, timeoutMs?: number): Promise<void>;
+/**
+ * Bounded hard delete. Never throws; logs timeouts/failures.
+ */
+export declare function boundedDeleteEphemeralSession(session: EphemeralSessionLifecycle, sessionId: string, timeoutMs?: number): Promise<void>;
+/**
+ * Tear an ephemeral session down without racing opencode's final part/message
+ * flush (#2123): a bounded, awaited `session.abort()` (flush) FOLLOWED BY a
+ * bounded `session.delete()`. Best-effort: never throws.
+ *
+ * Callers that need cleanup guaranteed before they return should `await` this.
+ * Fire-and-forget callers may `void` it — the abort→delete ordering still holds
+ * inside the unit, so the FK race is closed regardless; only the caller's own
+ * completion timing is detached (process exit before completion leaks a
+ * session, same as the prior fire-and-forget delete, and is harmless).
+ */
+export declare function teardownEphemeralSession(session: EphemeralSessionLifecycle, sessionId: string, options?: TeardownEphemeralSessionOptions): Promise<void>;
+export declare const _internals: {
+    boundedSessionCall: typeof boundedSessionCall;
+    boundedAbort: typeof boundedAbortEphemeralSession;
+    boundedDelete: typeof boundedDeleteEphemeralSession;
+    log: typeof log;
+};
+export {};

package/dist/utils/path-security.d.ts

@@ -17,14 +17,107 @@ export declare function containsPathTraversal(str: string): boolean;
  */
 export declare function containsControlChars(str: string): boolean;
 /**
- * Validate a directory path for safety.
+ * Validate a **project/workspace root** for safety.
+ *
+ * Distinct from {@link validateDirectory}, which additionally rejects absolute
+ * paths and is therefore only correct for a *relative sub-path*. A workspace
+ * root is absolute by contract — `ctx.directory` injected by `createSwarmTool`
+ * is always an absolute project root (AGENTS.md invariant 4) — so applying
+ * `validateDirectory` to one rejects 100% of real inputs and silently kills
+ * whatever feature depends on it. That is exactly how `.swarm/run-memory.jsonl`
+ * came to have no producer and a consumer that threw on every call.
+ *
+ * This validator keeps the checks that are meaningful for a root (empty,
+ * traversal segments, control/bidi characters). Containment of the actual FILE
+ * is not this function's job and is unchanged: `validateSwarmPath(directory,
+ * filename)` resolves the target under `<directory>/.swarm`, rejects any path
+ * that escapes it, and rejects a symlinked `.swarm` base.
+ *
+ * It ALSO requires the root to be absolute and to not be a filesystem or system
+ * location — see `validateProjectDirectory` below, which this function
+ * delegates to, for why those two checks are load-bearing rather than
+ * defensive. In short: `validateSwarmPath` pins the write *inside* the root, so
+ * it cannot help when the root itself is `E:\` or `/etc`, and a RELATIVE root
+ * resolves `.swarm/` against the host process cwd — the same invariant-4 hazard
+ * as an empty root.
+ *
+ * @param directory - The workspace root to validate
+ * @throws Error if the root is invalid
+ */
+export declare function validateWorkspaceRoot(directory: string): void;
+/**
+ * Validate a relative directory path for safety.
  * Rejects empty paths, paths with traversal, control characters, and absolute paths.
  * Throws an Error if the directory is invalid.
  *
+ * Do NOT use this on a project/workspace root — see {@link validateWorkspaceRoot}.
+ *
  * @param directory - The directory string to validate
  * @throws Error if directory is invalid
  */
 export declare function validateDirectory(directory: string): void;
+/**
+ * Validate a TRUSTED, already-absolute project root directory.
+ *
+ * This is the trust-model counterpart to `validateDirectory` above, NOT a
+ * relaxation of it. `validateDirectory` guards UNTRUSTED, RELATIVE sub-path
+ * input and therefore rejects absolute paths by design. A project root that
+ * the plugin host injects (`ctx.directory`, or the documented direct-CLI /
+ * test `process.cwd()` fallback) is ALWAYS absolute, so handing one to
+ * `validateDirectory` throws unconditionally — the misapplication that made
+ * the context-budget and run-memory features dead on every real invocation
+ * (issue #1619 follow-up).
+ *
+ * What this still enforces — every check that is meaningful for a root:
+ * - Non-empty. An empty root makes `path.resolve('', '.swarm')` land on
+ *   whatever the host process cwd happens to be, which is an invariant-4
+ *   (`.swarm/` containment) violation, not a harmless no-op.
+ * - No traversal and no control / directional-format characters. A root
+ *   carrying `..`, a NUL byte, or a bidi override is never a legitimate
+ *   injected project root.
+ * - MUST be absolute. A relative root resolves against the host's process cwd
+ *   — the same invariant-4 hazard as the empty case, and the reason this is a
+ *   positive requirement rather than merely "absolute is tolerated".
+ *
+ * WHAT "ABSOLUTE" MEANS HERE IS PARTLY PLATFORM-DEPENDENT. The check is
+ * `path.isAbsolute(directory) || /^[A-Za-z]:[/\\]/.test(directory)`, and
+ * `path.isAbsolute` is bound to the host platform. Measured, not assumed
+ * (2026-08-10, issue #1619 review round 4, F5):
+ *
+ *   | root                        | POSIX host | Windows host |
+ *   | --------------------------- | ---------- | ------------ |
+ *   | `/srv/app`                  | accepted   | accepted     |
+ *   | `C:/app`, `C:\app`          | accepted   | accepted     |
+ *   | `//server/share/project`    | accepted   | accepted     |
+ *   | `\\server\share\project`    | REJECTED   | accepted     |
+ *   | `app/relative`              | rejected   | rejected     |
+ *
+ * So the drive-letter fallback is what makes Windows drive roots portable, and
+ * a POSIX root is absolute on Windows too (`path.win32.isAbsolute('/srv')` is
+ * true — a driveless rooted path passes there, resolving against the current
+ * drive). But the BACKSLASH UNC form is not portable: it is win32-absolute and
+ * not posix-absolute, and no fallback covers it, so it validates on Windows and
+ * throws on a Linux CI runner. Only the forward-slash UNC spelling is accepted
+ * on both.
+ *
+ * UNC paths are intentionally accepted ON WINDOWS: they are absolute there and
+ * can be a legitimate project root. Rejecting them would silently re-create the
+ * dead-feature class this function exists to fix, because every caller sits
+ * behind a debug-gated catch. Nothing is lost by the POSIX rejection — a
+ * `\\server\share` root is not a usable path on POSIX in the first place.
+ *
+ * NOT interchangeable with `validateProjectRoot` (src/evidence/manager.ts).
+ * That one is a filesystem-touching, fail-closed check that the directory is
+ * the OUTERMOST project root (no ancestor owns a `.swarm/`). It does I/O
+ * (realpathSync plus a bounded ancestor walk) on every call and it correctly
+ * REJECTS a linked git worktree whose parent checkout has a `.swarm/` — right
+ * for a one-shot evidence write, wrong for a per-turn chat-transform hook.
+ * Reserve it for writes that must be pinned to the outermost project root.
+ *
+ * @param directory - the injected, trusted project root
+ * @throws Error if the directory is not a usable absolute project root
+ */
+export declare function validateProjectDirectory(directory: string): void;
 /**
  * Validate that a resolved path stays within an allowed root directory.
  * Resolves symlinks via realpathSync for both the target path and the root,
@@ -105,6 +198,7 @@ export declare const _internals: {
     containsPathTraversal: typeof containsPathTraversal;
     containsControlChars: typeof containsControlChars;
     validateDirectory: typeof validateDirectory;
+    validateProjectDirectory: typeof validateProjectDirectory;
     validateSymlinkBoundary: typeof validateSymlinkBoundary;
     isCanonicalPathWithinRoot: typeof isCanonicalPathWithinRoot;
     validateTargetWithinRoot: typeof validateTargetWithinRoot;

package/dist/utils/swarm-artifact-cache.d.ts

@@ -1,3 +1,4 @@
+import * as fsSync from 'node:fs';
 export interface SwarmArtifactCacheStats {
     textReadCount: number;
     textCacheHitCount: number;
@@ -14,6 +15,18 @@ export interface SwarmArtifactCacheStats {
     textEntryCount: number;
     parsedEntryCount: number;
 }
+/**
+ * Dependency-injection seam for testing. Tests can temporarily replace these
+ * to force a specific (e.g. colliding) stat stamp without relying on
+ * filesystem/platform-specific ctime semantics (utimesSync cannot set ctime
+ * portably — see swarm-artifact-cache.test.ts's documented Windows/POSIX
+ * divergence). Restore each entry in afterEach via the saved original
+ * reference.
+ */
+export declare const _internals: {
+    stat: typeof fsSync.promises.stat;
+    statSync: fsSync.StatSyncFn;
+};
 export declare function cloneCachedValue<T>(value: T): T;
 export declare function readCachedTextFileSync(filePath: string, directRead: () => string | null): string | null;
 export declare function readCachedTextFile(filePath: string, directRead: () => Promise<string | null>): Promise<string | null>;

package/dist/worktree/index.d.ts

@@ -1,5 +1,5 @@
 export type { AutoCommitSkip, AutoCommitSuccess, CleanCheckFailure, CleanCheckSuccess, CleanFailure, CleanSuccess, ProvisionFailure, ProvisionSuccess, RemoveFailure, RemoveSuccess, } from './core';
 export { _internals as coreInternals, assertCleanWorkingTree, autoCommitDirty, checkPathBudget, cleanUntrackedFiles, isCleanWorktree, isPathUnderSwarmWorktreeBase, makeWorktreeBranchName, provisionWorktree, removeWorktree, resolveWorktreeBaseDir, shortenWorktreePath, } from './core';
 export type { CleanupFailure, CleanupSuccess, ConflictHandlingError, ConflictInfo, DirtyMergeFailure, DirtyMergePartial, DirtyMergeSuccess, MergeConflict, MergeFailure, MergeSuccess, OrphanCleanupResult, StartupRecoveryResult, } from './merge';
-export { _internals as mergeInternals, attemptMergeBackFromDirty, cleanupOrphanedBranches, getMergeStrategy, handleMergeConflict, mergeLaneBranch, postMergeCleanup, startupOrphanRecovery, } from './merge';
+export { _internals as mergeInternals, attemptMergeBackFromDirty, cleanupOrphanedBranches, getMergeStrategy, handleMergeConflict, mergeLaneBranch, postMergeCleanup, pruneStaleWorktreeMetadata, scanRegisteredWorktreeLiveness, startupOrphanRecovery, } from './merge';
 export * from './types';

package/dist/worktree/merge.d.ts

@@ -130,6 +130,14 @@ export interface OrphanCleanupResult {
      * deletions were skipped this pass (fail-safe). */
     recoveryReadError?: boolean;
 }
+export interface OrphanCleanupOptions {
+    /**
+     * Preserve branches that are not merged into HEAD. Interactive reset flows
+     * retain the historical force-delete default; unattended startup recovery
+     * sets this to true so a missing worktree cannot erase its only commits.
+     */
+    preserveUnmerged?: boolean;
+}
 export interface StartupRecoveryResult {
     prunedWorktrees: boolean;
     remainingBranches: string[];
@@ -180,6 +188,30 @@ export declare function reconcileLandedMerge(primaryDir: string, provenance: Mer
  * @returns Discriminated union: success, partial failure, or full failure.
  */
 export declare function postMergeCleanup(directory: string, branchName: string): Promise<CleanupSuccess | CleanupFailure>;
+/**
+ * Remove only stale Git worktree registration metadata. This deliberately does
+ * not delete a lane branch; callers hand branch reconciliation to
+ * `provisionWorktree`, which refuses branches with unmerged commits and uses
+ * non-forced `git branch -d` for proven-merged stale branches.
+ */
+export declare function pruneStaleWorktreeMetadata(directory: string): Promise<{
+    pruned: true;
+} | {
+    error: string;
+}>;
+export type RegisteredWorktreeLivenessScan = {
+    status: 'ok';
+    liveBranches: string[];
+} | {
+    status: 'uncertain';
+    reason: string;
+};
+/**
+ * Enumerate branches whose registered worktree paths still exist. Stale Git
+ * metadata with a missing path is deliberately excluded so an expired
+ * provisional owner cannot become permanent ownership after a crash.
+ */
+export declare function scanRegisteredWorktreeLiveness(directory: string): Promise<RegisteredWorktreeLivenessScan>;
 /**
  * Handles a merge conflict by listing conflicted files and aborting the
  * in-progress operation to restore the working tree to a clean state.
@@ -228,14 +260,15 @@ declare function extractSessionId(branchName: string): string | null;
  * Cleans up orphaned swarm-lane branches that do not belong to any active session.
  *
  * Lists all swarm-lane/ and swarm/lane/ branches, identifies orphans (branches whose
- * session ID is not in `activeSessionIds`), force-deletes them, and prunes stale
- * worktree metadata.
+ * session ID is not in `activeSessionIds`), deletes them according to the
+ * requested preservation policy, and prunes stale worktree metadata.
  *
  * @param directory        - The project root (cwd for all git commands).
  * @param activeSessionIds - Session IDs that are still active; their branches are skipped.
+ * @param options          - Branch preservation policy for unattended recovery.
  * @returns Result with arrays of removed, skipped, and errored branch names.
  */
-export declare function cleanupOrphanedBranches(directory: string, activeSessionIds?: string[]): Promise<OrphanCleanupResult>;
+export declare function cleanupOrphanedBranches(directory: string, activeSessionIds?: string[], options?: OrphanCleanupOptions): Promise<OrphanCleanupResult>;
 /**
  * Performs startup orphan recovery: prunes stale worktrees, then identifies
  * any remaining orphaned swarm-lane branches for warning.

package/package.json

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