@sema-agent/server 7.125.1 → 7.127.0

package/dist/workspace-space-commit.d.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+/** The row's `state` closed set. `pending` = the run is over, its env has not begun committing; `committing` = its upload
+ *  is running; `publishing` = its upload is done and it is moving `latest` (re-claimed just before the move). */
+export declare const SPACE_COMMIT_STATES: readonly ["pending", "committing", "publishing"];
+export type SpaceCommitState = (typeof SPACE_COMMIT_STATES)[number];
+/** One space's row as read — `remainingMs` = its writer's deadline − now, on the store's own clock (`<= 0` = dead). */
+export interface SpaceCommitReading {
+    readonly taskId: string;
+    readonly state: SpaceCommitState;
+    readonly remainingMs: number;
+}
+/** One write of this run's row: the deadline it sets, and whether only this run's own (live) row may be moved. */
+export interface SpaceCommitClaim {
+    /** THIS run's bound: the write sets the row's deadline to now + `boundMs`. Never an operand of judging a row. */
+    readonly boundMs: number;
+    /** `true` = this run already wrote its row (its terminal fenced it): only that row, still alive, may move. */
+    readonly requireOwn: boolean;
+}
+/** The row face a run store gives the fence (its table, its clock). Every write goes through {@link decideSpaceCommitClaim}. */
+export interface SpaceCommitRows {
+    /** The space's row, or `undefined` (no commit in flight). A read that fails throws. */
+    readSpaceCommit(spaceKey: string): Promise<SpaceCommitReading | undefined>;
+    /** Make the space's row this run's, in `state`, its deadline := now + `claim.boundMs` — per {@link decideSpaceCommitClaim}.
+     *  `true` ⇒ the row is now this run's. */
+    claimSpaceCommit(spaceKey: string, taskId: string, state: SpaceCommitState, claim: SpaceCommitClaim): Promise<boolean>;
+    /** Delete this run's row (never another run's). */
+    endSpaceCommit(spaceKey: string, taskId: string): Promise<void>;
+    /** Abandon run `taskId`'s commit: in ONE transaction / write section, delete the space's row iff it is still that run's
+     *  and dead on the clock read under the row's lock ({@link decideSpaceCommitAbandon}). `true` ⇒ deleted. */
+    abandonSpaceCommit(spaceKey: string, taskId: string): Promise<boolean>;
+}
+/** Narrow a stored `state` cell to the closed set — an unknown word is a loud read failure, never a guess. */
+export declare function spaceCommitStateOf(v: unknown): SpaceCommitState;
+/** The ONE liveness predicate, shared by every backend and the reader: a row is alive while its writer's deadline is still
+ *  ahead (`remainingMs > 0`) — the deadline in the row, never the caller's own bound. */
+export declare function spaceCommitAlive(row: SpaceCommitReading): boolean;
+/**
+ * The ONE claim rule, shared by every backend: what writing this run's row does to the row that is there.
+ *  - none            ⇒ insert (unless this run's own row is required — it is gone: refuse);
+ *  - this run's row  ⇒ move it while alive; past its deadline ⇒ refuse (a next run may have abandoned it);
+ *  - another run's   ⇒ replace it only when it is dead and this run's own row is not required; else refuse.
+ */
+export declare function decideSpaceCommitClaim(row: SpaceCommitReading | undefined, taskId: string, claim: {
+    readonly requireOwn: boolean;
+}): "insert" | "update" | "refuse";
+/** The ONE abandon rule, shared by every backend: the row read under its lock may be deleted iff it is still run
+ *  `taskId`'s (the run whose row the reader saw dead) and still dead — renewed, taken by another run, or gone ⇒ keep. */
+export declare function decideSpaceCommitAbandon(row: SpaceCommitReading | undefined, taskId: string): boolean;
+/** The pending row a terminal write is asked to write (same transaction as the slot release). */
+export interface PendingSpaceCommit {
+    readonly spaceKey: string;
+    readonly claim: SpaceCommitClaim;
+}
+/** One env's fence (the adapter's face). */
+export interface SpaceCommitFence {
+    /** The space's current row (any run's) — what `connect()` waits on. Throws when the read fails. */
+    read(): Promise<SpaceCommitReading | undefined>;
+    /** Abandon the commit of run `deadTaskId` (whose row `read()` answered dead): `true` ⇒ its row is deleted under the
+     *  row's lock; `false` ⇒ it was renewed, taken or already gone — re-read. Throws when the write fails. */
+    abandon(deadTaskId: string): Promise<boolean>;
+    /** This env now holds a workspace its `destroy()` will commit (call after the previous commit was waited out and the
+     *  pod is up). `boundMs` = the upload's wall-clock bound — each write of this run's row sets its deadline to now + it. */
+    arm(boundMs: number): void;
+    /** The commit starts: the row becomes this run's `committing` (a fresh deadline). `false` ⇒ the fence is lost (this
+     *  run's row is past its deadline, or another run's live row is there) — the commit must not publish. Throws when the
+     *  write fails. */
+    begin(): Promise<boolean>;
+    /** The upload is done, `latest` is next: this run's row — only if it is still this run's and alive — becomes
+     *  `publishing` (a fresh deadline). Answers the end of that deadline on this process's clock (epoch ms, counted from
+     *  before the write, so never later than the row's own), or `undefined` = the fence is no longer this run's (its row is
+     *  past its deadline or another run's, or no commit began) — `latest` must not be published. Throws when the write fails. */
+    publish(): Promise<number | undefined>;
+    /** The commit (or the workspace) is over: this run's row, if it wrote one, is deleted; the seat disarms. Throws when
+     *  the delete fails (the seat is disarmed regardless). */
+    end(): Promise<void>;
+}
+/**
+ * Open the fence of one env with an open space lane (the factory binding, per run). `taskId` = the run row's id
+ * (`ExecutionEnvFactoryContext.taskId`); absent ⇒ no terminal write can name this env — its commit is fenced from its
+ * start only. Returns a live object ⇒ `create*`.
+ */
+export declare function createSpaceCommitFence(rows: SpaceCommitRows, spaceKey: string, taskId: string | undefined): SpaceCommitFence;
+/**
+ * The terminal write's hook (every run store's `setTerminal`): `write` runs under the run's seat; it is offered the
+ * pending row iff the run's env is armed and has not begun committing, and returns whether that row is now this run's
+ * (written in the SAME transaction / write lock as the terminal row and the active-run slot release). No seat ⇒
+ * `write(undefined)`, nothing else.
+ */
+export declare function fenceSpaceCommitAtTerminal(taskId: string, write: (pending: PendingSpaceCommit | undefined) => Promise<boolean>): Promise<void>;
+/** A row as an in-process twin keeps it (local File / memory run stores). `expiresAt` = its writer's deadline, epoch ms on
+ *  this process's clock. The schema is the one reading of a persisted record (the File twin's `space-commits/<key>.json`). */
+export declare const SPACE_COMMIT_RECORD_SCHEMA: z.ZodObject<{
+    spaceKey: z.ZodString;
+    taskId: z.ZodString;
+    state: z.ZodEnum<{
+        pending: "pending";
+        committing: "committing";
+        publishing: "publishing";
+    }>;
+    expiresAt: z.ZodNumber;
+}, z.core.$strip>;
+export type SpaceCommitRecord = Readonly<z.infer<typeof SPACE_COMMIT_RECORD_SCHEMA>>;
+/**
+ * The in-process twins' table (local File / memory run stores): the SAME rule as the SQL twins over a record store the
+ * caller supplies (`load` / `save` / `remove`; the File twin persists each record, the memory twin keeps a map).
+ * Synchronous on purpose — the twins' terminal write calls `claimSync` inside its own synchronous write section.
+ * Returns a live object ⇒ `create*`.
+ */
+export declare function createInProcessSpaceCommitTable(records: {
+    load(spaceKey: string): SpaceCommitRecord | undefined;
+    save(record: SpaceCommitRecord): void;
+    remove(spaceKey: string): void;
+}): SpaceCommitRows & {
+    claimSync(spaceKey: string, taskId: string, state: SpaceCommitState, claim: SpaceCommitClaim): boolean;
+};
+//# sourceMappingURL=workspace-space-commit.d.ts.map

package/dist/workspace-space-commit.js

@@ -0,0 +1,117 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+export const SPACE_COMMIT_STATES = ["pending", "committing", "publishing"];
+export function spaceCommitStateOf(v) {
+    const word = String(v);
+    const known = SPACE_COMMIT_STATES.find((w) => w === word);
+    if (known !== undefined)
+        return known;
+    throw new Error(`workspace_space_commit: unknown state ${JSON.stringify(word)} (closed set: ${SPACE_COMMIT_STATES.join(" | ")})`);
+}
+export function spaceCommitAlive(row) {
+    return row.remainingMs > 0;
+}
+export function decideSpaceCommitClaim(row, taskId, claim) {
+    if (row === undefined)
+        return claim.requireOwn ? "refuse" : "insert";
+    if (row.taskId === taskId)
+        return spaceCommitAlive(row) ? "update" : "refuse";
+    return !claim.requireOwn && !spaceCommitAlive(row) ? "update" : "refuse";
+}
+export function decideSpaceCommitAbandon(row, taskId) {
+    return row !== undefined && row.taskId === taskId && !spaceCommitAlive(row);
+}
+const armed = new Map();
+function serialize(seat, step) {
+    const run = seat.tail.then(step);
+    seat.tail = run.then(() => undefined, () => undefined);
+    return run;
+}
+export function createSpaceCommitFence(rows, spaceKey, taskId) {
+    const seat = { spaceKey, rowTaskId: taskId ?? `env-${randomUUID()}`, state: "idle", boundMs: 0, tail: Promise.resolve() };
+    return {
+        read: () => rows.readSpaceCommit(spaceKey),
+        abandon: (deadTaskId) => rows.abandonSpaceCommit(spaceKey, deadTaskId),
+        arm(boundMs) {
+            if (seat.state !== "idle")
+                return;
+            seat.state = "armed";
+            seat.boundMs = boundMs;
+            if (taskId !== undefined)
+                armed.set(taskId, seat);
+        },
+        begin: () => serialize(seat, async () => {
+            if (seat.state !== "armed" && seat.state !== "fenced")
+                return false;
+            const ok = await rows.claimSpaceCommit(spaceKey, seat.rowTaskId, "committing", { boundMs: seat.boundMs, requireOwn: seat.state === "fenced" });
+            if (ok)
+                seat.state = "committing";
+            return ok;
+        }),
+        publish: () => serialize(seat, async () => {
+            if (seat.state !== "committing")
+                return undefined;
+            const from = Date.now();
+            const ok = await rows.claimSpaceCommit(spaceKey, seat.rowTaskId, "publishing", { boundMs: seat.boundMs, requireOwn: true });
+            if (!ok)
+                return undefined;
+            seat.state = "publishing";
+            return from + seat.boundMs;
+        }),
+        end: () => serialize(seat, async () => {
+            const wrote = seat.state === "fenced" || seat.state === "committing" || seat.state === "publishing";
+            seat.state = "idle";
+            if (taskId !== undefined && armed.get(taskId) === seat)
+                armed.delete(taskId);
+            if (wrote)
+                await rows.endSpaceCommit(spaceKey, seat.rowTaskId);
+        }),
+    };
+}
+export async function fenceSpaceCommitAtTerminal(taskId, write) {
+    const seat = armed.get(taskId);
+    if (seat === undefined) {
+        await write(undefined);
+        return;
+    }
+    await serialize(seat, async () => {
+        const offer = seat.state === "armed" ? { spaceKey: seat.spaceKey, claim: { boundMs: seat.boundMs, requireOwn: false } } : undefined;
+        const wrote = await write(offer);
+        if (offer !== undefined && wrote)
+            seat.state = "fenced";
+    });
+}
+export const SPACE_COMMIT_RECORD_SCHEMA = z.object({
+    spaceKey: z.string().min(1),
+    taskId: z.string().min(1),
+    state: z.enum(SPACE_COMMIT_STATES),
+    expiresAt: z.number().finite(),
+});
+export function createInProcessSpaceCommitTable(records) {
+    const reading = (spaceKey) => {
+        const r = records.load(spaceKey);
+        return r === undefined ? undefined : { taskId: r.taskId, state: r.state, remainingMs: r.expiresAt - Date.now() };
+    };
+    const claimSync = (spaceKey, taskId, state, claim) => {
+        if (decideSpaceCommitClaim(reading(spaceKey), taskId, claim) === "refuse")
+            return false;
+        records.save({ spaceKey, taskId, state, expiresAt: Date.now() + claim.boundMs });
+        return true;
+    };
+    return {
+        readSpaceCommit: async (spaceKey) => reading(spaceKey),
+        claimSpaceCommit: async (spaceKey, taskId, state, claim) => claimSync(spaceKey, taskId, state, claim),
+        endSpaceCommit: async (spaceKey, taskId) => {
+            if (records.load(spaceKey)?.taskId === taskId)
+                records.remove(spaceKey);
+        },
+        abandonSpaceCommit: async (spaceKey, taskId) => {
+            if (!decideSpaceCommitAbandon(reading(spaceKey), taskId))
+                return false;
+            records.remove(spaceKey);
+            return true;
+        },
+        claimSync,
+    };
+}
+//# sourceMappingURL=workspace-space-commit.js.map

package/dist/workspace-space.d.ts

@@ -1,7 +1,7 @@
 /**
  * Workspace persistence by **space** (k8s lane) — the closed word set, the defaults, the retention domain and
- * the policy shape (pure leaf: no value imports, so `config.ts`, the capability fact and the adapter in `plugins/` can
- * all import it without a load cycle). The effective policy has ONE reading: the capability fact `workspaceSpace`
+ * the policy shape (pure leaf: no value imports from this repo — only a node builtin — so `config.ts`, the capability fact and the adapter
+ * in `plugins/` can all import it without a load cycle). The effective policy has ONE reading: the capability fact `workspaceSpace`
  * (`src/capability-facts.ts`).
  *
  * The law (one fact, one seat): a k8s pod's `/workspace` is durable across runs as an object-store "space" owned by the
@@ -15,16 +15,17 @@
  * Facility dependence: without a snapshot store (`s3Snapshot`) there is nothing to persist into — the fact is
  * unavailable and the lane behaves exactly as before (fresh pod, empty `/workspace` every run).
  */
+/** The k8s lane's workspace mount when `K8S_MOUNT_PATH` is unset (the adapter's default; the cache mount is checked against it). */
+export declare const K8S_WORKSPACE_MOUNT_DEFAULT = "/workspace";
 /** `WORKSPACE_PERSIST` closed set. `space` = the k8s workspace persists per space (the session occupant); `off` = a fresh
  *  workspace every run. */
 export declare const WORKSPACE_PERSIST_WORDS: readonly ["space", "off"];
 export type WorkspacePersist = (typeof WORKSPACE_PERSIST_WORDS)[number];
 /**
- * Default `off` — persistence is opt-in. Why: the run-end commit's ordering against the NEXT run rests on an object-store
- * marker the commit itself writes, and that PUT can land after the engine's teardown bound; then the next run restores the
- * previous-but-one snapshot and its own commit later overwrites the late one (the preceding run's changes are lost). That
- * window closes only with a commit fence held in server-side durable state, written before the session's active-run slot
- * is released; until then a deployment turns persistence on knowing the window (USAGE §9.3b).
+ * Default `space`: a k8s lane with a snapshot store persists `/workspace` across runs. The run-end commit's ordering against
+ * the NEXT run is a commit fence held in server-side durable state — the run store's `workspace_space_commit` row, written
+ * by the run's terminal write before the session's active-run slot is released (`workspace-space-commit.ts`) — so the next
+ * run waits for the previous run's commit instead of restoring an older snapshot. `off` = a fresh workspace every run.
  */
 export declare const WORKSPACE_PERSIST_DEFAULT: WorkspacePersist;
 /** `WORKSPACE_SNAPSHOT_KEEP` — snapshots kept per space key (closed integer domain; out of domain refuses boot). */
@@ -33,9 +34,74 @@ export declare const WORKSPACE_SNAPSHOT_KEEP_RANGE: {
     readonly min: 1;
     readonly max: 50;
 };
-/** The effective space policy — the `workspaceSpace` fact's witness and the value of `GET /v1/capabilities.workspaceSync`. */
-export interface WorkspaceSyncCapability {
+/**
+ * `WORKSPACE_SNAPSHOT_TIMEOUT_MS` — the k8s lane's ONE data bound (closed integer domain; out of domain refuses boot): the
+ * snapshot upload's and the restore's wall-clock, the reclaim seat's one absolute deadline per call (the cache volume and the objects of every space in that call), and the deadline a run's commit writes into its fence row (now + this
+ * number at each write — a next run waits for that run's commit until the deadline IN THE ROW, whatever its own replica's
+ * number) are all this one number (the adapter's `dataTimeoutMs`); it also bounds a large file transfer's wall-clock (a
+ * stalled one is cut earlier by the command liveness bound).
+ */
+export declare const WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT = 300000;
+export declare const WORKSPACE_SNAPSHOT_TIMEOUT_MS_RANGE: {
+    readonly min: 30000;
+    readonly max: 3600000;
+};
+/** The lane's data bound as configured — the ONE reading of `WORKSPACE_SNAPSHOT_TIMEOUT_MS` (the loader always mints it; a
+ *  hand-built config may omit it ⇒ the default): the boot assembly hands it to the adapter (`dataTimeoutMs`) and the capability
+ *  fact reports it (`workspaceSync.timeoutMs`) — the same call, so the two never disagree. */
+export declare function workspaceSnapshotTimeoutOf(lane: {
+    readonly workspaceSnapshotTimeoutMs?: number;
+}): number;
+/** The space policy the k8s adapter acts on (persistence word + retention). */
+export interface WorkspaceSpacePolicy {
     persist: WorkspacePersist;
     keep: number;
 }
+/** The effective space policy as reported — the `workspaceSpace` fact's witness and the value of `GET /v1/capabilities.workspaceSync`:
+ *  the policy plus the lane's data bound (`timeoutMs`, the snapshot upload / restore wall-clock and the longest a next run waits
+ *  for the previous run's commit). The adapter gets the bound as `dataTimeoutMs`, never through this object. */
+export interface WorkspaceSyncCapability extends WorkspaceSpacePolicy {
+    timeoutMs: number;
+}
+/** The refusal code of a `WORKSPACE_SNAPSHOT_EXCLUDE` item outside the closed form (the `config.*` family; fatal-exit prints it). */
+export declare const WORKSPACE_SNAPSHOT_EXCLUDE_INVALID = "config.workspace_snapshot_exclude_invalid";
+/**
+ * `WORKSPACE_SNAPSHOT_EXCLUDE` — the snapshot's exclusion table: a CSV of tar exclusion patterns relative to the workspace
+ * root (`build,.gradle,node_modules/.cache`), applied by the adapter's ONE tar upload as `--exclude=./<item>` (so the run-end
+ * space snapshot and the park suspend share it). Unset / empty ⇒ no table (the upload command is what it always was).
+ *
+ * The item form is CLOSED: plain relative path segments — no leading `/`, no `.` / `..` / empty segment (`./x`, `a//b`, a
+ * trailing `/`), no whitespace, no quote characters, no control characters. Tar wildcards inside a segment (`*.log`) are items
+ * like any other. A project's `.gitignore` is NOT read (a second grammar, per project, not equivalent to tar's). Items are
+ * trimmed (the CSV separator's spacing is not part of an item); a bad item refuses boot naming its position — the value is a
+ * path pattern, never a secret, so it is echoed.
+ */
+export declare function parseWorkspaceSnapshotExclude(raw: string | undefined): readonly string[];
+/** Mint one snapshot id: `kata-<owner>-<ts36>-<rand>` (see {@link SNAPSHOT_OWNER_NONE}). The time and random parts only keep ids unique; nothing reads them back. */
+export declare function mintSnapshotId(incarnation: string | undefined): string;
+/** Whether an object name in the park partition (`<snapshotId>.tar.gz`, or any single-segment name) carries the mark of THIS occupant incarnation.
+ *  An empty incarnation owns nothing; `none` and unmarked names are never owned (fail closed). */
+export declare function snapshotNameOwnedBy(name: string, incarnation: string): boolean;
+/** One ended space, as the reclaim seat is told of it: the session whose space ended (its park lane's partition) and the space key
+ *  (the occupant's incarnation — the `space/` partition, the cache volume's label and, through {@link snapshotNameOwnedBy}, the owner mark of
+ *  the park objects that are this occupant's). An empty `spaceKey` is not a space (the occupant could not be read) — the seat skips it. */
+export interface EndedSpace {
+    readonly sessionId: string;
+    readonly spaceKey: string;
+}
+/** The closed word set of `workspace_cache_reclaim_failed.reason` — ONE owner for both legs of the reclaim (the seat in
+ *  `plugins/remote-env-k8s.ts` says `delete_failed` / `budget`; the session-delete coordinator says `occupant_unreadable`). */
+export type CacheReclaimReason = "delete_failed" | "budget" | "occupant_unreadable";
+/**
+ * The ONE reclaim seat for an ended space — called where a space ENDS: the session-delete coordinator (`boot/session-faces.ts` `purgeSession`)
+ * and the managed-retention sweep after it deletes session trees (`boot/retention-lane.ts`); neither writes a reclaim of its own. It reclaims
+ * everything the space left behind: the cache volume (when configured), the `space/` snapshot partition and the session's park snapshots whose names carry the ended occupant's ownership mark (when a
+ * snapshot store is configured; old-form / `none` park objects are left to the bucket's lifecycle rule). ONE call runs under ONE
+ * absolute deadline (`dataTimeoutMs`) built at its entry — the cache volume and the objects of every space in the call; a space the deadline passed
+ * before reaching sends nothing and says so. Callers may fire-and-forget it (the session-delete coordinator does). A part that cannot be reclaimed = one operator line + `recordFailOpen`; NEVER throws: a space's leftovers never
+ * block a deletion (the bucket's lifecycle rule is the fallback for objects).
+ */
+export interface SpaceReclaimer {
+    reclaim(spaces: readonly EndedSpace[]): Promise<void>;
+}
 //# sourceMappingURL=workspace-space.d.ts.map

package/dist/workspace-space.js

@@ -1,5 +1,56 @@
+import { createHash } from "node:crypto";
+export const K8S_WORKSPACE_MOUNT_DEFAULT = "/workspace";
 export const WORKSPACE_PERSIST_WORDS = ["space", "off"];
-export const WORKSPACE_PERSIST_DEFAULT = "off";
+export const WORKSPACE_PERSIST_DEFAULT = "space";
 export const WORKSPACE_SNAPSHOT_KEEP_DEFAULT = 3;
 export const WORKSPACE_SNAPSHOT_KEEP_RANGE = { min: 1, max: 50 };
+export const WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT = 300_000;
+export const WORKSPACE_SNAPSHOT_TIMEOUT_MS_RANGE = { min: 30_000, max: 3_600_000 };
+export function workspaceSnapshotTimeoutOf(lane) {
+    return lane.workspaceSnapshotTimeoutMs ?? WORKSPACE_SNAPSHOT_TIMEOUT_MS_DEFAULT;
+}
+export const WORKSPACE_SNAPSHOT_EXCLUDE_INVALID = "config.workspace_snapshot_exclude_invalid";
+export function parseWorkspaceSnapshotExclude(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return [];
+    const items = raw.split(",").map((s) => s.trim());
+    items.forEach((item, i) => {
+        const problem = snapshotExcludeItemProblem(item);
+        if (problem === undefined)
+            return;
+        throw Object.assign(new Error(`env WORKSPACE_SNAPSHOT_EXCLUDE: item #${i + 1} of ${items.length} (${JSON.stringify(item)}) is ${problem} — each item is a tar exclusion pattern ` +
+            "relative to the workspace root, in plain path segments (e.g. WORKSPACE_SNAPSHOT_EXCLUDE=build,.gradle,node_modules/.cache); refusing to start rather than snapshot with a table that does not say what it means"), { code: WORKSPACE_SNAPSHOT_EXCLUDE_INVALID });
+    });
+    return items;
+}
+function snapshotExcludeItemProblem(item) {
+    if (item === "")
+        return "empty";
+    if (/[\s'"`\u0000-\u001f\u007f]/.test(item))
+        return "not a plain path (it holds whitespace, a quote or a control character)";
+    if (item.startsWith("/"))
+        return "absolute (a leading /) — items are relative to the workspace root";
+    const segments = item.split("/");
+    if (segments.includes(".."))
+        return "escaping the workspace (a .. segment)";
+    if (segments.some((s) => s === "" || s === "."))
+        return "not in plain segments (an empty or . segment: ./x, a//b, a trailing /)";
+    return undefined;
+}
+const SNAPSHOT_OWNER_NONE = "none";
+const SNAPSHOT_OWNER_HEX_LENGTH = 16;
+const SNAPSHOT_ID_FAMILY = "kata";
+function snapshotOwnerOf(incarnation) {
+    if (incarnation === undefined || incarnation === "")
+        return SNAPSHOT_OWNER_NONE;
+    return createHash("sha256").update(incarnation).digest("hex").slice(0, SNAPSHOT_OWNER_HEX_LENGTH);
+}
+export function mintSnapshotId(incarnation) {
+    return `${SNAPSHOT_ID_FAMILY}-${snapshotOwnerOf(incarnation)}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+export function snapshotNameOwnedBy(name, incarnation) {
+    if (incarnation === "")
+        return false;
+    return name.startsWith(`${SNAPSHOT_ID_FAMILY}-${snapshotOwnerOf(incarnation)}-`);
+}
 //# sourceMappingURL=workspace-space.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "7.125.1",
+  "version": "7.127.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",
@@ -64,8 +64,8 @@
     "build:binary:run-local:darwin-arm64": "bun build --compile --target=bun-darwin-arm64 src/run-local.ts --outfile dist/run-local-darwin-arm64"
   },
   "dependencies": {
-    "@sema-agent/core": "7.48.0",
-    "@sema-agent/settings-schema": "11.3.1",
+    "@sema-agent/core": "7.50.2",
+    "@sema-agent/settings-schema": "12.2.1",
     "e2b": "^2.28.0",
     "libsodium-wrappers": "^0.8.4",
     "mysql2": "^3.22.4",
@@ -80,7 +80,7 @@
     "sharp": "^0.35.3"
   },
   "devDependencies": {
-    "@sema-agent/sdk": "20.0.0",
+    "@sema-agent/sdk": "21.1.0",
     "@types/libsodium-wrappers": "^0.7.14",
     "@types/node": "22.10.2",
     "@types/pg": "^8.20.0",

package/dist/boot/session-incarnation-seat.d.ts

@@ -1,41 +0,0 @@
-/**
- * S-506([ref] §5)—— 记忆引擎的会话化身座 `RunnerDeps.memorySessionIncarnation` 的装配件。
- *
- * core 的座是**同步**签名(`({ sessionId }) => string | undefined`),而会话化身住在会话元数据里、读它是异步的 ⇒ 两段:
- *  · **写**(装配期):resolve-spec 每次提交(fresh 与 resume 腿同经)经 {@link createAssemblyIncarnationRead} 造的读口异步读一次会话面,
- *    记进本副本的 per-session 登记簿(`boot/execution-env.ts` 的 `noteSessionIncarnation`,与 cwd / shellEnv 同一只 LRU、同一条围栏、
- *    同一条删除);
- *  · **读**(运行期):{@link createMemorySessionIncarnationSeat} 从登记簿同步取。
- *
- * ## 读口缺席是装配期事实(合并复审 F2)
- * 「会话店有没有 `sessionFaceOf`」由 {@link sessionFaceReaderOf} 判,resolve-spec 与 runner-deps 读同一只:缺席(内存会话店 /
- * 多租户裸 boot / 降级到内存的副本)⇒ resolve-spec **构造时** warn 一次、请求路径上不再判不再打;记忆座不装(恒答 undefined 的座与不装
- * 同义,core 按 id 绑定 = 修前行为)。修前是每一次提交打一行。
- *
- * ## 读不到的臂([ref]:响亮,不静默)
- * 会话不在 / 读口抛(含空化身的响亮拒)⇒ 这一轮没有化身 ⇒ 座答 `undefined`(core 口径:按 id 绑定 —— 今天的行为,且是**保守**方向:
- * 上一位住客的 opt-out / 污染标记仍会约束这一位,不会让任何一条被放过)+ warn,**按会话去重**(同一只会话连着读不到只说一次,读到了再
- * 读不到重新说)。没有「读不到就沿用上次」的臂:装配期读失败会把登记簿那一格**清掉**,座随之答 undefined。
- *
- * ## 令牌不出本进程的内存
- * 不上 wire、不进模型上下文;warn 行只带会话 id —— 缺席的那一臂根本没有令牌可打。
- */
-import type { RunnerDeps } from "@sema-agent/core";
-import type { SessionFaceReader } from "../session-incarnation.js";
-/** warn 口(logger 的子集)。 */
-type Warn = (event: string, fields: Record<string, unknown>) => void;
-/** 会话店的「属主 + 化身」读口 —— 装配期判一次(resolve-spec 与 runner-deps 读同一只,判据不各写一份)。缺席 = 这只会话店没有它。 */
-export declare function sessionFaceReaderOf(store: unknown): SessionFaceReader | undefined;
-/**
- * 装配期化身读口(resolve-spec **构造时**建一次)。读口缺席 ⇒ 当场 warn 一次、返回 `undefined`(请求路径上不再判不再打);
- * 在场 ⇒ 返回一只读:读到 ⇒ 化身;会话不在 / 读抛 ⇒ `undefined` + 按会话去重的 warn。不抛:这是记忆座的输入,不是提交的准入门
- * (提交的属主门在 authorizer;读失败的那一格由座答 undefined 兜成保守绑定)。
- */
-export declare function createAssemblyIncarnationRead(read: SessionFaceReader | undefined, warn: Warn): ((sessionId: string) => Promise<string | undefined>) | undefined;
-/**
- * `RunnerDeps.memorySessionIncarnation` 的同步座:从本副本的 per-session 登记簿取装配期读数。缺席 ⇒ `undefined` + 每个会话一行 warn。
- * 命名照工厂律:返回的是带行为的闭包 ⇒ `create*`。
- */
-export declare function createMemorySessionIncarnationSeat(incarnationOf: (sessionId: string) => string | undefined, warn: Warn): NonNullable<RunnerDeps["memorySessionIncarnation"]>;
-export {};
-//# sourceMappingURL=session-incarnation-seat.d.ts.map

package/dist/boot/session-incarnation-seat.js

@@ -1,69 +0,0 @@
-const MISS_WARNED_MAX = 4096;
-export function sessionFaceReaderOf(store) {
-    const s = store;
-    return typeof s?.sessionFaceOf === "function" ? s.sessionFaceOf.bind(s) : undefined;
-}
-function createPerSessionWarn(warn) {
-    const warned = new Set();
-    return {
-        once(sessionId, fields) {
-            if (warned.has(sessionId))
-                return;
-            if (warned.size >= MISS_WARNED_MAX)
-                warned.clear();
-            warned.add(sessionId);
-            warn("session_incarnation_unavailable", { sessionId, ...fields });
-        },
-        clear(sessionId) {
-            warned.delete(sessionId);
-        },
-    };
-}
-export function createAssemblyIncarnationRead(read, warn) {
-    if (read === undefined) {
-        warn("session_incarnation_unavailable", {
-            reason: "no_session_face_read",
-            note: "this deployment's session store has no sessionFaceOf read (an in-memory session store) — session incarnations are not read and memory records bind by id alone; stated once at assembly",
-        });
-        return undefined;
-    }
-    const perSession = createPerSessionWarn(warn);
-    return async (sessionId) => {
-        try {
-            const face = await read(sessionId);
-            if (face === undefined) {
-                perSession.once(sessionId, { reason: "session_absent", note: "no session row at assembly — memory records for this session bind by id alone this run" });
-                return undefined;
-            }
-            perSession.clear(sessionId);
-            return face.incarnation;
-        }
-        catch (e) {
-            const code = e?.code;
-            perSession.once(sessionId, {
-                reason: typeof code === "string" ? code : "read_failed",
-                note: "the session face could not be read at assembly — memory records for this session bind by id alone this run",
-            });
-            return undefined;
-        }
-    };
-}
-export function createMemorySessionIncarnationSeat(incarnationOf, warn) {
-    const warned = new Set();
-    return ({ sessionId }) => {
-        const incarnation = incarnationOf(sessionId);
-        if (incarnation !== undefined)
-            return incarnation;
-        if (!warned.has(sessionId)) {
-            if (warned.size >= MISS_WARNED_MAX)
-                warned.clear();
-            warned.add(sessionId);
-            warn("memory_session_incarnation_unknown", {
-                sessionId,
-                note: "no incarnation was read for this session on this replica (not assembled here, or its read failed) — the memory engine binds this session's records by id alone",
-            });
-        }
-        return undefined;
-    };
-}
-//# sourceMappingURL=session-incarnation-seat.js.map

package/dist/capabilities/code-review-council.d.ts

@@ -1,49 +0,0 @@
-import { runTeamDiscussion, type Runner, type ToolSpec } from "@sema-agent/core";
-import type { Metrics } from "../observability/metrics.js";
-import type { Logger } from "../observability/logger.js";
-type TeamFn = typeof runTeamDiscussion;
-/**
- * Code-review council (Option C+, layers L1 + L3) packaged as ONE tool, so the run model is unchanged
- * and the orchestration is **code-driven** (deterministic — we don't rely on the model to follow a
- * multi-step orchestration prompt, which live runs showed it doesn't do reliably).
- *
- * - L1 (gather): one isolated, read-only-repo-tooled subagent PER differential lens, run in PARALLEL.
- * - L3 (arbitrate): a neutral arbiter grounds/dedups/buckets/ranks. It does not add findings.
- * - L2 (peer debate over findings + dispute verification with member tools) is the next layer.
- *
- * Research basis (core's design): tooled differential exploration is the main source of real bugs;
- * grounding + bucketing kill "imagined requirements" and stop a design preference being filed as a bug.
- */
-interface Lens {
-    name: string;
-    brief: string;
-}
-/**
- * Caller-tunable lens COUNT (OA request) — a structured cost/coverage dial, sibling of `@model` / `council` /
- * `debate`. The deployment owns WHICH lenses (the `LENSES` order = the priority: security/correctness first =
- * the bug-finders); the caller only picks HOW MANY. Clamp to [1, LENSES.length]; absent / non-numeric = ALL
- * (the current default → zero regression). A named subset is deliberately NOT supported (it would force a
- * published, maintained lens vocabulary contract; the count is the verifiable knob a "light/standard" UI needs).
- */
-export declare function pickLenses(count?: number): readonly Lens[];
-/** Caller-settable debate rounds: a FINITE integer clamped to [1,3]; non-number / NaN / ±Infinity = undefined
- *  (→ the council's default of 1). Mirrors `pickLenses`'s `Number.isFinite` guard — the previous inline clamp let
- *  `NaN` through (`typeof NaN === "number"`, `Math.min(3, NaN) === NaN`), corrupting the cost metric (council). */
-export declare function clampRounds(rounds: unknown): number | undefined;
-export interface CouncilToolOptions {
-    /** Aggregate the council's (otherwise invisible) sub-task cost into metrics. */
-    metrics?: Metrics;
-    logger?: Logger;
-    /** L1+L2+L3: add a peer-team debate (tool-grounded) before arbitration. Default L1+L3 only. */
-    debate?: boolean;
-    /** Debate rounds (when `debate`). Default 1. */
-    rounds?: number;
-    /** Caller-chosen lens COUNT (cost/coverage dial). Clamped to [1, LENSES.length]; absent = all lenses. */
-    lensCount?: number;
-    /** Injectable for tests; defaults to core's runTeamDiscussion. */
-    teamFn?: TeamFn;
-}
-/** Build the `run_council` tool. The lead calls it once; it returns the final arbitrated review. */
-export declare function createCouncilTool(subRunner: Runner, repoTools: ToolSpec[], objective: string, opts?: CouncilToolOptions): ToolSpec;
-export {};
-//# sourceMappingURL=code-review-council.d.ts.map