pilotswarm-sdk 0.4.1 → 0.5.1

package/dist/session-lifecycle.js

@@ -0,0 +1,324 @@
+/**
+ * runTurn preamble/postamble for the session lifecycle protocol
+ * (docs/proposals/session-lifecycle-protocol.md §3.2–3.3).
+ *
+ * The whole lifecycle lives inside the single runTurn activity (principle
+ * P5 — no other session activity depends on landing where a previous one
+ * did). Reconcile is STORE-WINS (docs/proposals/snapshot-store-wins.md): one
+ * probe per turn is the only oracle — never the orchestration's expectation,
+ * which goes stale the moment a stopped/zombie turn advances the store the
+ * control plane discarded.
+ *
+ *   preamble  p1. one probe. Store bears this turn's own turnKey →
+ *                 already-committed recovery (restore, never replay).
+ *             p2. store empty → trust a clean local dir (only truth), else fresh;
+ *                 legacy snapshot → trust clean local, else hydrate.
+ *             p3. warm ONLY when a clean local dir's marker matches the store's
+ *                 (version AND content hash); every other state — store ahead
+ *                 (a discarded/foreign turn advanced it — NO fence, we adopt it),
+ *                 a same-version content swap, a torn/dirty dir, or no marker —
+ *                 hydrates the store. Store below the marker is hydrated too and
+ *                 flagged `regressed`.
+ *             p4. (caller) write the turn sentinel just before the body
+ *   postamble c1. write .ps-turn-commit.json {turnKey, result} into the dir
+ *             c2. commit the tar (store.commitSnapshot) at base+1. alreadyCommitted
+ *                 (same turnKey) → restore the winner's snapshot + result. A
+ *                 SnapshotConflictError (store moved off base while we ran) is NOT
+ *                 fatal: the turn is left UNPUBLISHED (superseded), the sentinel
+ *                 stays dirty so the next preamble rehydrates the winner, and the
+ *                 caller emits `session.snapshot_unpublished`. A user-stopped
+ *                 result skips the commit entirely (also unpublished).
+ *             c3. write the local version marker (published turns only)
+ *             c4. clear the turn sentinel (published turns only)
+ *
+ * @internal
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { faultPoint } from "./fault-injection.js";
+import { SnapshotConflictError, clearTurnSentinel, readSnapshotMarker, readTurnCommitFile, readTurnSentinel, writeSnapshotMarker, writeTurnCommitFile, } from "./snapshot-protocol.js";
+const COMMIT_TRANSIENT_RETRIES = 3;
+// Tunable so fault-injection tests don't pay real backoff delays.
+const COMMIT_RETRY_BASE_DELAY_MS = Number.parseInt(process.env.PILOTSWARM_COMMIT_RETRY_DELAY_MS ?? "", 10) || 1_000;
+function sessionDirOf(ctx) {
+    return path.join(ctx.sessionStateDir, ctx.sessionId);
+}
+/**
+ * A marker alone is not proof the dir survived intact (a crashed recursive
+ * delete removes files in arbitrary order and can leave the marker while
+ * the session files are gone). Require the SDK's layout anchor before
+ * trusting local files without consulting the store.
+ */
+function hasUsableSessionLayout(sessionDir) {
+    return fs.existsSync(path.join(sessionDir, "workspace.yaml"));
+}
+/**
+ * Content-identity gate for the warm fast path. Only a mismatch between two
+ * PRESENT hashes forces a hydrate (a rule-breaking restore that overwrote the
+ * same version number with different content — the ETag CAS can't catch that,
+ * §5.1). When either side lacks a hash (a legacy marker/probe), fall back to
+ * version-only trust so an upgrade doesn't churn every warm worker into a
+ * spurious one-time hydrate.
+ */
+function contentMatches(markerHash, probeHash) {
+    if (markerHash && probeHash)
+        return markerHash === probeHash;
+    return true;
+}
+function markerFromHydrate(sessionDir, hydrated) {
+    writeSnapshotMarker(sessionDir, {
+        version: hydrated.version,
+        ...(hydrated.turnKey ? { turnKey: hydrated.turnKey } : {}),
+        ...(hydrated.contentHash ? { contentHash: hydrated.contentHash } : {}),
+    });
+}
+/** Restore the committed snapshot and return the stored result (§3.2 r1–r3). */
+async function recoverAlreadyCommitted(ctx) {
+    const sessionDir = sessionDirOf(ctx);
+    await ctx.dropWarmSession();
+    const hydrated = await ctx.store.hydrateSnapshot(ctx.sessionId);
+    markerFromHydrate(sessionDir, hydrated);
+    clearTurnSentinel(sessionDir);
+    const commitFile = readTurnCommitFile(sessionDir);
+    if (commitFile && commitFile.turnKey === ctx.turnKey) {
+        ctx.trace(`session=${ctx.sessionId} already-committed recovery: store at v${hydrated.version} ` +
+            `under this turnKey; returning stored result without re-running the turn`);
+        return { kind: "already-committed", version: hydrated.version, result: commitFile.result };
+    }
+    // Snapshot claims our turnKey but carries no readable committed result —
+    // degrade to a hydrated re-run (duplicate execution beats a wrong result).
+    ctx.trace(`session=${ctx.sessionId} store bears this turnKey (v${hydrated.version}) but the ` +
+        `turn-commit file is missing/unreadable; degrading to hydrated re-run`);
+    return { kind: "hydrated", baseVersion: hydrated.version, storeBehindExpected: false };
+}
+async function resolveFromStore(ctx, regressed) {
+    const sessionDir = sessionDirOf(ctx);
+    await ctx.dropWarmSession();
+    const hydrated = await ctx.store.hydrateSnapshot(ctx.sessionId);
+    markerFromHydrate(sessionDir, hydrated);
+    clearTurnSentinel(sessionDir);
+    const storeBehindExpected = hydrated.version < ctx.expectedVersion;
+    if (storeBehindExpected) {
+        ctx.trace(`session=${ctx.sessionId} store snapshot v${hydrated.version} is BEHIND the orchestration's ` +
+            `expected v${ctx.expectedVersion} (store restored from backup?); proceeding from stored state`);
+    }
+    if (regressed) {
+        ctx.trace(`session=${ctx.sessionId} store snapshot v${regressed.storeVersion} is BELOW the local marker ` +
+            `v${regressed.markerVersion} (store restored/lost data); store wins — hydrating v${hydrated.version}`);
+    }
+    return {
+        kind: "hydrated",
+        baseVersion: hydrated.version,
+        storeBehindExpected,
+        ...(regressed ? { regressed } : {}),
+    };
+}
+/**
+ * Preamble (store-wins). Runs under the per-session run-turn lock, before
+ * getOrCreate. ONE probe per turn is the reconcile oracle — never the
+ * orchestration's `expectedVersion`, which goes stale the moment a stopped or
+ * zombie turn advances the store the control plane discarded (the divergence
+ * this protocol removes). On return the local dir is in exactly one state:
+ * trusted at `baseVersion` (warm — local marker matches the store's
+ * version+hash), restored at the stored version (hydrated — the store wins),
+ * absent (fresh), or restored at this turn's committed version
+ * (already-committed — the caller returns the stored result without a body).
+ */
+export async function runTurnPreamble(ctx) {
+    const sessionDir = sessionDirOf(ctx);
+    const sentinel = readTurnSentinel(sessionDir);
+    const marker = readSnapshotMarker(sessionDir);
+    const localDirUsable = fs.existsSync(sessionDir) && hasUsableSessionLayout(sessionDir);
+    // Store-wins: one metadata probe is the ONLY oracle. `expectedVersion`
+    // rides in the input for frozen orchestration versions but is load-bearing
+    // for nothing here except the lossy-replay observability flag.
+    const probe = await ctx.store.probeSnapshot(ctx.sessionId);
+    if (sentinel) {
+        ctx.trace(`session=${ctx.sessionId} turn sentinel present (started ${sentinel.startedAt || "unknown"}); ` +
+            `local dir untrusted, resolving from store`);
+    }
+    // Idempotency (keeper): the store bears THIS turn's own key — a prior
+    // attempt of this very turn already committed (crash-after-commit, or a
+    // racing drain/lock-steal duplicate). Restore, never replay.
+    if (probe.exists && probe.turnKey && probe.turnKey === ctx.turnKey) {
+        return recoverAlreadyCommitted(ctx);
+    }
+    // Store holds nothing.
+    if (!probe.exists) {
+        // A clean, usable local dir is the best (only) data — trust it over a
+        // fresh replay; the fresh chain publishes from here.
+        if (!sentinel && localDirUsable) {
+            return { kind: "warm", baseVersion: marker?.version ?? 0 };
+        }
+        // Dirty or unusable local + empty store → fresh; lossy iff turns had
+        // been committed before (marker present, or a frozen orchestration
+        // still reports a nonzero expected version). W3 in the protocol doc.
+        await ctx.dropWarmSession();
+        fs.rmSync(sessionDir, { recursive: true, force: true });
+        return { kind: "fresh", baseVersion: 0, lossy: (marker?.version ?? ctx.expectedVersion) > 0 };
+    }
+    // Legacy snapshot (pre-protocol, no version metadata, counts as v0): a
+    // clean local dir is still trustworthy; otherwise hydrate what's stored.
+    if (probe.legacy) {
+        if (!sentinel && localDirUsable) {
+            return { kind: "warm", baseVersion: marker?.version ?? 0 };
+        }
+        return resolveFromStore(ctx);
+    }
+    // Regressed: the store sits BELOW this worker's own marker — a restore from
+    // an older backup, or store data loss. Anomalous (surfaced by the caller),
+    // but the store still wins: we hydrate what it holds.
+    const regressed = marker && probe.version < marker.version
+        ? { markerVersion: marker.version, storeVersion: probe.version }
+        : undefined;
+    // Warm fast path: a clean local dir whose marker names EXACTLY the stored
+    // state — same version AND (when both carry a hash) same content. The
+    // layout anchor guards a marker orphaned by a torn delete; the hash guards
+    // a rule-breaking same-version restore (§5.1). Only branch that trusts
+    // local files without hydrating.
+    if (!sentinel && localDirUsable && marker
+        && marker.version === probe.version
+        && contentMatches(marker.contentHash, probe.contentHash)) {
+        return { kind: "warm", baseVersion: marker.version };
+    }
+    // Store wins for everything else: store AHEAD (a discarded/foreign turn
+    // advanced it — the incident; adopt it, no zombie fence), a same-version
+    // content swap, a torn/dirty dir, or no marker.
+    return resolveFromStore(ctx, regressed);
+}
+/**
+ * Last-resort recovery when getOrCreate fails on missing/lost local state
+ * DESPITE the preamble's resolution (e.g. the SDK refused to resume from
+ * intact-looking files): restore the committed snapshot if one exists.
+ * Returns the hydrated version, or null when the store holds nothing —
+ * only then may the caller fall back to the lossy fresh replay, whose
+ * store-deleting reset is a no-op against an empty store.
+ */
+export async function attemptStoreRecovery(ctx) {
+    const probe = await ctx.store.probeSnapshot(ctx.sessionId);
+    if (!probe.exists)
+        return null;
+    const sessionDir = sessionDirOf(ctx);
+    await ctx.dropWarmSession();
+    const hydrated = await ctx.store.hydrateSnapshot(ctx.sessionId);
+    markerFromHydrate(sessionDir, hydrated);
+    clearTurnSentinel(sessionDir);
+    return hydrated.version;
+}
+/**
+ * Postamble (c1–c4). Runs under the per-session run-turn lock after the
+ * body produced `result`. Transient store failures retry in place; a CAS
+ * conflict (foreign writer) always throws — the activity must fail loudly.
+ * An `alreadyCommitted` CAS outcome (a racing duplicate of this same turn
+ * won) triggers restore-not-replay: the winner's snapshot and result are
+ * adopted, discarding this attempt's divergent local state.
+ */
+export async function runTurnCommit(ctx, baseVersion, result) {
+    // Stop-turn divergence guard: a user-stopped turn (result type "stopped")
+    // is discarded by the orchestration (stop won the ctx.race →
+    // handleTurnStopped; this runTurn is the dropped race loser) and its
+    // turnKey is never re-run. Committing its snapshot would advance the
+    // stored version while the orchestration keeps state.snapshotVersion at the
+    // base — leaving the store one ahead so every later turn fails the CAS
+    // (zombie-duplicate fence: "expected N, found N+1"). Skip the commit and
+    // leave the .ps-turn-inprogress sentinel in place so the next preamble
+    // re-hydrates the base version and discards this partial turn. (Drain and
+    // lock-steal classify as "cancelled", not "stopped", and DO commit so their
+    // same-turnKey re-run adopts the already-committed snapshot.)
+    if (result?.type === "stopped") {
+        ctx.trace(`session=${ctx.sessionId} user-stopped turn: skipping snapshot commit at ` +
+            `base v${baseVersion}; sentinel left dirty for next-turn re-hydrate`);
+        return {
+            version: baseVersion,
+            contentHash: "",
+            alreadyCommitted: false,
+            published: false,
+            unpublishedReason: "stopped",
+        };
+    }
+    const sessionDir = sessionDirOf(ctx);
+    writeTurnCommitFile(sessionDir, ctx.turnKey, result);
+    faultPoint("turn.commit.before-cas");
+    let lastError;
+    for (let attempt = 1; attempt <= COMMIT_TRANSIENT_RETRIES; attempt++) {
+        try {
+            const committed = await ctx.store.commitSnapshot(ctx.sessionId, {
+                baseVersion,
+                turnKey: ctx.turnKey,
+            });
+            faultPoint("turn.commit.after-cas");
+            if (committed.alreadyCommitted) {
+                // §3.2 restore-not-replay: a racing attempt of this same
+                // turn committed first. Its snapshot is the durable lineage;
+                // this attempt's local files diverge and must be replaced.
+                ctx.trace(`session=${ctx.sessionId} commit found this turn already committed at ` +
+                    `v${committed.version} by a racing attempt; restoring the committed state`);
+                await ctx.dropWarmSession();
+                const hydrated = await ctx.store.hydrateSnapshot(ctx.sessionId);
+                markerFromHydrate(sessionDir, hydrated);
+                clearTurnSentinel(sessionDir);
+                const commitFile = readTurnCommitFile(sessionDir);
+                return {
+                    version: committed.version,
+                    contentHash: hydrated.contentHash ?? committed.contentHash,
+                    ...(hydrated.sizeBytes != null ? { sizeBytes: hydrated.sizeBytes } : {}),
+                    ...(hydrated.rawSizeBytes != null ? { rawSizeBytes: hydrated.rawSizeBytes } : {}),
+                    alreadyCommitted: true,
+                    published: true,
+                    ...(commitFile && commitFile.turnKey === ctx.turnKey
+                        ? { storedResult: commitFile.result }
+                        : {}),
+                };
+            }
+            writeSnapshotMarker(sessionDir, {
+                version: committed.version,
+                turnKey: ctx.turnKey,
+                contentHash: committed.contentHash,
+            });
+            faultPoint("turn.commit.after-marker");
+            clearTurnSentinel(sessionDir);
+            faultPoint("turn.commit.after-sentinel-clear");
+            return {
+                version: committed.version,
+                contentHash: committed.contentHash,
+                ...(committed.sizeBytes != null ? { sizeBytes: committed.sizeBytes } : {}),
+                ...(committed.rawSizeBytes != null ? { rawSizeBytes: committed.rawSizeBytes } : {}),
+                alreadyCommitted: false,
+                published: true,
+            };
+        }
+        catch (error) {
+            if (error instanceof SnapshotConflictError) {
+                // Store-wins: a turn the control plane discarded — or a foreign
+                // writer — advanced the store off our base while this turn ran.
+                // Do NOT brick (the old zombie-duplicate fence). Give up this
+                // publish: leave the sentinel dirty so the next preamble
+                // rehydrates the winner. The turn's result still returns to the
+                // orchestration; only its snapshot memory is superseded, and
+                // the caller emits `session.snapshot_unpublished{superseded}`.
+                ctx.trace(`session=${ctx.sessionId} commit superseded: store advanced off base v${baseVersion} ` +
+                    `while this turn ran (${error.message}); leaving turn unpublished, sentinel dirty`);
+                return {
+                    version: baseVersion,
+                    contentHash: "",
+                    alreadyCommitted: false,
+                    published: false,
+                    unpublishedReason: "superseded",
+                    observedStoreVersion: error.storedVersion,
+                    ...(error.storedTurnKey ? { observedStoreTurnKey: error.storedTurnKey } : {}),
+                };
+            }
+            lastError = error;
+            const message = error instanceof Error ? error.message : String(error);
+            ctx.trace(`session=${ctx.sessionId} turn commit attempt ${attempt}/${COMMIT_TRANSIENT_RETRIES} ` +
+                `failed: ${message}`);
+            if (attempt < COMMIT_TRANSIENT_RETRIES) {
+                await new Promise((resolve) => setTimeout(resolve, COMMIT_RETRY_BASE_DELAY_MS * attempt));
+            }
+        }
+    }
+    throw lastError instanceof Error
+        ? lastError
+        : new Error(`Turn commit failed for ${ctx.sessionId}: ${String(lastError)}`);
+}
+//# sourceMappingURL=session-lifecycle.js.map

package/dist/session-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-lifecycle.js","sourceRoot":"","sources":["../src/session-lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/session-manager.d.ts

@@ -123,6 +123,8 @@ export declare class SessionManager {
     private _getLineageSessionIds;
     /** Per-session critical sections; protects the SDK session handle and local session.db. */
     private sessionLocks;
+    /** Last local activity per session — feeds the autonomous eviction clock. */
+    private sessionLastTouchedAt;
     constructor(githubToken?: string | undefined, sessionStore?: SessionStateStore | null, workerDefaults?: WorkerDefaults, sessionStateDir?: string);
     /** Store full config (with tools/hooks) for a session. Called by PilotSwarmClient. */
     setConfig(sessionId: string, config: ManagedSessionConfig): void;
@@ -192,6 +194,16 @@ export declare class SessionManager {
     withRunTurnLock<T>(sessionId: string, operation: string, fn: () => Promise<T>, options?: {
         trace?: SessionTraceWriter;
     }): Promise<T>;
+    /**
+     * Autonomous eviction sweep (lifecycle protocol §3.4): local session
+     * state is a cache. A session idle past `evictAfterMs` is reclaimed
+     * without telling anyone — sessions with a committed snapshot marker
+     * are simply destroyed + deleted (the store already holds their state;
+     * the next runTurn self-validates and hydrates); unmarked (legacy)
+     * sessions are dehydrated the old way so their only copy is preserved.
+     * Returns the number of sessions reclaimed.
+     */
+    sweepIdleSessions(evictAfterMs: number): Promise<number>;
     /**
      * Stop-turn interrupt primitive: abort the warm session's in-flight turn.
      *
@@ -223,6 +235,15 @@ export declare class SessionManager {
     private _getOrCreateUnlocked;
     /** Get a session by ID (null if not in memory on this node). */
     get(sessionId: string): ManagedSession | null;
+    /** Root directory holding per-session state dirs. */
+    getSessionStateDir(): string;
+    /**
+     * Destroy the in-memory ManagedSession only — disk state untouched.
+     * Used by the lifecycle preamble before overwriting local files with a
+     * hydrated snapshot (a warm session bound to the old files must not
+     * survive the swap). Caller holds the per-session run-turn lock.
+     */
+    dropWarmSession(sessionId: string): Promise<void>;
     /**
      * Dehydrate a session: snapshot to the session store, release in-memory state.
      *

package/dist/session-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAuE,KAAK,IAAI,EAAE,MAAM,qBAAqB,CAAC;AACpI,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAgC,KAAK,eAAe,EAAE,KAAK,oBAAoB,EAAE,KAAK,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAC3I,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAIlE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAcnD,eAAO,MAAM,iCAAiC,4CAA4C,CAAC;AAE3F,qBAAa,8BAA+B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,6CAAqC;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAOrE;AAED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,8BAA8B,CAExG;AAWD,KAAK,kBAAkB,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAwBpD,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sBAAsB,CAAC,EAAE,MAAM,EAAE,CAAC;IAClC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,4DAA4D;IAC5D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,WAAW,GAAG,kBAAkB,GAAG,yBAAyB,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,oBAAoB,EAAE,qBAAqB,CAAA;KAAE,CAAC,CAAC;IAC5L,yFAAyF;IACzF,uBAAuB,CAAC,EAAE,OAAO,oBAAoB,EAAE,qBAAqB,CAAC;IAC7E,yFAAyF;IACzF,oBAAoB,CAAC,EAAE,OAAO,oBAAoB,EAAE,qBAAqB,CAAC;IAC1E,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,gDAAgD;IAChD,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACtG,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,EAAE;QACP,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,WAAW,CAAC;QACxC,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE;YAAE,UAAU,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KACnC,CAAC;IACF,uEAAuE;IACvE,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACvC,iEAAiE;IACjE,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAgBD;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;IA6DnB,OAAO,CAAC,WAAW,CAAC;IA5DxB,OAAO,CAAC,OAAO,CAAoC;IACnD;;;;;;;;;;;OAWG;IACH,IAAI,MAAM,IAAI,aAAa,GAAG,SAAS,CAEtC;IACD,IAAI,MAAM,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,EAQ1C;IACD,OAAO,CAAC,QAAQ,CAAqC;IACrD;;;;;;;;OAQG;IACH,OAAO,CAAC,iBAAiB,CAA6B;IACtD,OAAO,CAAC,YAAY,CAAkC;IACtD,qEAAqE;IACrE,OAAO,CAAC,cAAc,CAA2C;IACjE,2EAA2E;IAC3E,OAAO,CAAC,YAAY,CAAgC;IACpD,iDAAiD;IACjD,OAAO,CAAC,cAAc,CAAiB;IACvC,oDAAoD;IACpD,OAAO,CAAC,eAAe,CAAS;IAChC,8DAA8D;IAC9D,OAAO,CAAC,SAAS,CAA0B;IAC3C;yEACqE;IACrE,OAAO,CAAC,UAAU,CAA2B;IAC7C,gEAAgE;IAChE,OAAO,CAAC,cAAc,CAA+B;IACrD,wDAAwD;IACxD,OAAO,CAAC,eAAe,CAAa;IACpC,2DAA2D;IAC3D,OAAO,CAAC,qBAAqB,CAA2D;IACxF,2FAA2F;IAC3F,OAAO,CAAC,YAAY,CAAoC;gBAG5C,WAAW,CAAC,EAAE,MAAM,YAAA,EAC5B,YAAY,CAAC,EAAE,iBAAiB,GAAG,IAAI,EACvC,cAAc,CAAC,EAAE,cAAc,EAC/B,eAAe,CAAC,EAAE,MAAM;IAO5B,sFAAsF;IACtF,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,GAAG,IAAI;IAIhE,mEAAmE;IACnE,eAAe,IAAI,MAAM,GAAG,SAAS;IAIrC;;;;OAIG;IACH,iBAAiB,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,GAAG,SAAS;IA8B/F,wBAAwB,CACpB,KAAK,EAAE,MAAM,EACb,eAAe,CAAC,EAAE,OAAO,sBAAsB,EAAE,eAAe,GAAG,IAAI,GACxE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,OAAO,sBAAsB,EAAE,eAAe,GAAG,IAAI,CAAA;KAAE;IAiB5F,sEAAsE;IACtE,eAAe,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI;IAIvD,6DAA6D;IAC7D,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI;IAI/C,4EAA4E;IAC5E,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,GAAG,IAAI;IAIlD,gFAAgF;IAChF,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI;IAIvD,4DAA4D;IAC5D,iBAAiB,CAAC,MAAM,EAAE,GAAG,GAAG,IAAI;IAIpC,mEAAmE;IACnE,uBAAuB,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI;IAIpF,+CAA+C;IAC/C,0BAA0B,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI;IAIvF;;;;OAIG;IACH,sBAAsB,IAAI;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,GAAG,CAAA;KAAE,GAAG,SAAS;IAQ7E,2CAA2C;YAC7B,YAAY;IA+C1B;;;;;;;;;;;;;OAaG;YACW,0BAA0B;IAkCxC;;;;OAIG;YACW,uBAAuB;IAUrC,OAAO,CAAC,yBAAyB;YAQnB,kBAAkB;YA+BlB,gBAAgB;IAyDxB,eAAe,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,kBAAkB,CAAA;KAAE,GACzC,OAAO,CAAC,CAAC,CAAC;IAIb;;;;;;;;;;;;;OAaG;IACG,oBAAoB,CACtB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7E,OAAO,CAAC,eAAe,CAAC;IAqD3B;;;OAGG;IACG,WAAW,CACb,SAAS,EAAE,MAAM,EACjB,kBAAkB,EAAE,yBAAyB,EAC7C,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GACjF,OAAO,CAAC,cAAc,CAAC;YAYZ,oBAAoB;IAyWlC,gEAAgE;IAChE,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAI7C;;;;;;;;;;;;;;OAcG;IACG,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,kBAAkB,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YAYjH,kBAAkB;IAmKhC;;;OAGG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,kBAAkB,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;YAY/F,gBAAgB;IAkB9B;;;OAGG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,kBAAkB,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IA+BnG;;OAEG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxF;;;;OAIG;IACG,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAY/F;;;;OAIG;IACG,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3F;;;OAGG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASpF,mDAAmD;IACnD,gBAAgB,IAAI,MAAM,EAAE;IAI5B,0DAA0D;IACpD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAY/B;;;OAGG;IACH,OAAO,CAAC,aAAa;IA8BrB;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAgC9B;;;;;;OAMG;IACH,OAAO,CAAC,sCAAsC;IAuC9C,OAAO,CAAC,6BAA6B;IAqBrC,OAAO,CAAC,mBAAmB;CAyB9B"}
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"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"}

package/dist/session-manager.js

@@ -9,6 +9,7 @@ import { buildKnowledgePromptBlocks, loadKnowledgeIndexFromFactStore, buildEnhan
 import { composeStructuredSystemMessage, extractPromptContent, mergePromptSections } from "./prompt-layering.js";
 import { buildPromptLayersEventPayload } from "./prompt-layers.js";
 import { approvePermissionForSession } from "./permissions.js";
+import { readSnapshotMarker, supportsVersionedSnapshots } from "./snapshot-protocol.js";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
@@ -148,6 +149,8 @@ export class SessionManager {
     _getLineageSessionIds = null;
     /** Per-session critical sections; protects the SDK session handle and local session.db. */
     sessionLocks = new Map();
+    /** Last local activity per session — feeds the autonomous eviction clock. */
+    sessionLastTouchedAt = new Map();
     constructor(githubToken, sessionStore, workerDefaults, sessionStateDir) {
         this.githubToken = githubToken;
         this.sessionStore = sessionStore ?? null;
@@ -433,7 +436,119 @@ export class SessionManager {
         }
     }
     async withRunTurnLock(sessionId, operation, fn, options) {
-        return this._withSessionLock(sessionId, operation, fn, options);
+        this.sessionLastTouchedAt.set(sessionId, Date.now());
+        try {
+            return await this._withSessionLock(sessionId, operation, fn, options);
+        }
+        finally {
+            this.sessionLastTouchedAt.set(sessionId, Date.now());
+        }
+    }
+    /**
+     * Autonomous eviction sweep (lifecycle protocol §3.4): local session
+     * state is a cache. A session idle past `evictAfterMs` is reclaimed
+     * without telling anyone — sessions with a committed snapshot marker
+     * are simply destroyed + deleted (the store already holds their state;
+     * the next runTurn self-validates and hydrates); unmarked (legacy)
+     * sessions are dehydrated the old way so their only copy is preserved.
+     * Returns the number of sessions reclaimed.
+     */
+    async sweepIdleSessions(evictAfterMs) {
+        if (!(evictAfterMs > 0))
+            return 0;
+        const now = Date.now();
+        // Only sessions THIS manager has actually served since boot are
+        // eviction candidates. Stranger dirs on disk (leftovers from a
+        // previous container life, or another embedded worker sharing the
+        // sessionStateDir) must never be pushed to the store — a stale dir
+        // dehydrated over a newer snapshot silently rolls the session back.
+        const candidates = new Set([
+            ...this.sessions.keys(),
+            ...this.sessionLastTouchedAt.keys(),
+        ]);
+        let reclaimed = 0;
+        for (const sessionId of candidates) {
+            if (this.sessionLocks.has(sessionId))
+                continue; // busy — never race a turn
+            const sessionDir = path.join(this.sessionStateDir, sessionId);
+            const lastTouched = this.sessionLastTouchedAt.get(sessionId);
+            if (lastTouched == null || now - lastTouched < evictAfterMs)
+                continue;
+            try {
+                await this._withSessionLock(sessionId, "eviction", async () => {
+                    // Re-check under the lock — a turn may have landed.
+                    const touched = this.sessionLastTouchedAt.get(sessionId);
+                    if (touched != null && Date.now() - touched < evictAfterMs)
+                        return;
+                    const dirExists = fs.existsSync(sessionDir);
+                    const committedMarker = dirExists ? readSnapshotMarker(sessionDir) : null;
+                    const existing = this.sessions.get(sessionId);
+                    if (existing) {
+                        try {
+                            await existing.destroy();
+                        }
+                        catch { }
+                        this.sessions.delete(sessionId);
+                    }
+                    if (!dirExists) {
+                        this.sessionLastTouchedAt.delete(sessionId);
+                        reclaimed++;
+                        return;
+                    }
+                    if (committedMarker) {
+                        // Committed snapshot in the store — pure local delete.
+                        fs.rmSync(sessionDir, { recursive: true, force: true });
+                        emitSessionManagerTrace(sessionId, `evicted (committed at v${committedMarker.version}); local cache reclaimed`);
+                    }
+                    else if (this.sessionStore) {
+                        // Unmarked dir. If the store already holds a VERSIONED
+                        // chain for this session, the local files are a stale
+                        // cache at best — reclaim without writing (a legacy
+                        // dehydrate would destroy the CAS metadata and could
+                        // roll the session back).
+                        const versioned = supportsVersionedSnapshots(this.sessionStore)
+                            ? await this.sessionStore.probeSnapshot(sessionId).catch(() => null)
+                            : null;
+                        if (versioned?.exists && !versioned.legacy) {
+                            fs.rmSync(sessionDir, { recursive: true, force: true });
+                            emitSessionManagerTrace(sessionId, `evicted (store versioned at v${versioned.version}); stale unmarked cache reclaimed`);
+                        }
+                        else {
+                            // Legacy session: its local files may be the only copy.
+                            await this._dehydrateUnlocked(sessionId, "eviction");
+                            emitSessionManagerTrace(sessionId, "evicted via legacy dehydrate (no committed marker)");
+                        }
+                    }
+                    else {
+                        return; // no store — leave local state alone
+                    }
+                    this.sessionLastTouchedAt.delete(sessionId);
+                    this.sessionClientKeys.delete(sessionId);
+                    reclaimed++;
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.warn(`[SessionManager] eviction sweep skipped ${sessionId}: ${message}`);
+            }
+        }
+        // Reap crash-orphaned hydrate temp roots (finally blocks don't run
+        // on SIGKILL). They are dot-prefixed and never legitimate sessions.
+        try {
+            for (const entry of fs.readdirSync(this.sessionStateDir, { withFileTypes: true })) {
+                if (!entry.isDirectory() || !entry.name.startsWith(".ps-hydrate-"))
+                    continue;
+                const orphan = path.join(this.sessionStateDir, entry.name);
+                try {
+                    if (now - fs.statSync(orphan).mtimeMs > 3_600_000) {
+                        fs.rmSync(orphan, { recursive: true, force: true });
+                    }
+                }
+                catch { }
+            }
+        }
+        catch { }
+        return reclaimed;
     }
     /**
      * Stop-turn interrupt primitive: abort the warm session's in-flight turn.
@@ -508,6 +623,7 @@ export class SessionManager {
         return this._getOrCreateUnlocked(sessionId, serializableConfig, options);
     }
     async _getOrCreateUnlocked(sessionId, serializableConfig, options) {
+        this.sessionLastTouchedAt.set(sessionId, Date.now());
         const turnIndex = options?.turnIndex;
         const trace = options?.trace;
         const inheritedToolNames = Array.from(new Set([
@@ -838,6 +954,26 @@ export class SessionManager {
     get(sessionId) {
         return this.sessions.get(sessionId) ?? null;
     }
+    /** Root directory holding per-session state dirs. */
+    getSessionStateDir() {
+        return this.sessionStateDir;
+    }
+    /**
+     * Destroy the in-memory ManagedSession only — disk state untouched.
+     * Used by the lifecycle preamble before overwriting local files with a
+     * hydrated snapshot (a warm session bound to the old files must not
+     * survive the swap). Caller holds the per-session run-turn lock.
+     */
+    async dropWarmSession(sessionId) {
+        const existing = this.sessions.get(sessionId);
+        if (!existing)
+            return;
+        try {
+            await existing.destroy();
+        }
+        catch { }
+        this.sessions.delete(sessionId);
+    }
     /**
      * Dehydrate a session: snapshot to the session store, release in-memory state.
      *