Skip to content

A desktop coding agent with free access to frontier models.

TypeScript

feat(archive): upload the whole project folder, encrypted, for git sessions

ogsamrat1c2aa1916566
diff --git a/apps/server/src/omnirush-gateway-broker.test.ts b/apps/server/src/omnirush-gateway-broker.test.ts
index fd1b35e0..116e92f1 100644
--- a/apps/server/src/omnirush-gateway-broker.test.ts
+++ b/apps/server/src/omnirush-gateway-broker.test.ts
@@ -625,3 +625,62 @@ describe("OmniRush gateway broker sharing a device session with the desktop acco
expect((await store.status()).connected).toBe(false);
});
});
+
+describe("OmniRush gateway broker project archive requests", () => {
+ const archiveId = "0f6c2a7e-5b1d-4c8e-9a3f-2d7b6e1c4a90";
+
+ test("reach the gateway root with the device bearer and refresh an expired one like collect()", async () => {
+ const calls: Array<{ url: string; method: string; authorization: string | null; contentType: string | null; body: unknown }> = [];
+ const refreshCalls: string[] = [];
+ const broker = new OmniRushGatewayBroker({
+ credentials: { gatewayUrl: "https://gateway.example/omnirush/v1/", accessToken: "access-1", refreshToken: "refresh-1" },
+ engineToken: "local-engine-token",
+ fetch: async (input, init) => {
+ const url = String(input);
+ if (url.endsWith("/device/refresh")) {
+ refreshCalls.push((JSON.parse(String(init?.body)) as { refresh_token: string }).refresh_token);
+ return Response.json({ access_token: "access-2", refresh_token: "refresh-2", gateway_url: "https://gateway.example/omnirush/v1" });
+ }
+ const headers = new Headers(init?.headers);
+ calls.push({ url, method: init?.method ?? "GET", authorization: headers.get("authorization"), contentType: headers.get("content-type"), body: init?.body });
+ return headers.get("authorization") === "Bearer access-2"
+ ? Response.json({ ok: true })
+ : Response.json({ detail: "invalid_token" }, { status: 401 });
+ },
+ });
+
+ expect((await broker.archiveRequest("archives/key", { method: "GET" })).status).toBe(200);
+ const body = JSON.stringify({ parts: [{ part_number: 1, etag: "\"e1\"" }] });
+ expect((await broker.archiveRequest(`archives/${archiveId}/complete`, { method: "POST", body })).status).toBe(200);
+
+ expect(refreshCalls).toEqual(["refresh-1"]);
+ expect(calls).toEqual([
+ { url: "https://gateway.example/omnirush/archives/key", method: "GET", authorization: "Bearer access-1", contentType: null, body: undefined },
+ { url: "https://gateway.example/omnirush/archives/key", method: "GET", authorization: "Bearer access-2", contentType: null, body: undefined },
+ { url: `https://gateway.example/omnirush/archives/${archiveId}/complete`, method: "POST", authorization: "Bearer access-2", contentType: "application/json", body },
+ ]);
+ });
+
+ test("never leave the archive routes, and answer 401 without an account", async () => {
+ const urls: string[] = [];
+ const broker = new OmniRushGatewayBroker({
+ credentials: { gatewayUrl: "https://gateway.example/omnirush/v1", accessToken: "access-1", refreshToken: "refresh-1" },
+ engineToken: "local-engine-token",
+ fetch: async (input) => {
+ urls.push(String(input));
+ return Response.json({ ok: true });
+ },
+ });
+ for (const path of ["collect", "archives/../device/refresh", "archives/not-a-uuid/parts", `archives/${archiveId}/delete`, "https://elsewhere.example/archives"]) {
+ expect([path, (await broker.archiveRequest(path, { method: "POST", body: "{}" })).status]).toEqual([path, 404]);
+ }
+ expect(urls).toEqual([]);
+ expect((await broker.archiveRequest("archives", { method: "POST", body: "{}" })).status).toBe(200);
+ expect(urls).toEqual(["https://gateway.example/omnirush/archives"]);
+
+ const signedOut = new OmniRushGatewayBroker({ engineToken: "local-engine-token" });
+ const response = await signedOut.archiveRequest("archives/key", { method: "GET" });
+ expect(response.status).toBe(401);
+ expect(await response.json()).toEqual({ error: "omnirush_account_required" });
+ });
+});
diff --git a/apps/server/src/omnirush-gateway-broker.ts b/apps/server/src/omnirush-gateway-broker.ts
index 480e9047..5d65b10c 100644
--- a/apps/server/src/omnirush-gateway-broker.ts
+++ b/apps/server/src/omnirush-gateway-broker.ts
@@ -146,14 +146,18 @@ function upstreamUrl(gatewayUrl: string, path: string): string {
return url.toString();
}
-function collectorUrl(gatewayUrl: string): string {
+/** `<gateway root>/<path>`: the gateway URL with its trailing `/` and `/v1` stripped, as for every omnirush.ai API route. */
+function apiUrl(gatewayUrl: string, path: string): string {
const url = new URL(gatewayUrl);
- url.pathname = url.pathname.replace(/\/+$/, "").replace(/\/v1$/, "") + "/collect";
+ url.pathname = `${url.pathname.replace(/\/+$/, "").replace(/\/v1$/, "")}/${path}`;
url.search = "";
url.hash = "";
return url.toString();
}
+/** The project archive routes the session archiver calls (archives, archives/key, archives/<id>/parts|complete|abort). */
+const ARCHIVE_API_PATH = /^archives(?:\/key|\/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\/(?:parts|complete|abort))?$/;
+
/**
* Set by the omnirush-reasoning-effort engine plugin; keep the two
* definitions identical. The header is consumed here and never forwarded.
@@ -288,29 +292,51 @@ export class OmniRushGatewayBroker {
});
}
- async collect(sessionId: string, body: Uint8Array): Promise<Response> {
- if (!this.state) return Response.json({ error: "omnirush_account_required" }, { status: 401 });
- const tokenUsed = this.state.accessToken;
- const send = () => this.fetcher(collectorUrl(this.state!.gatewayUrl), {
+ collect(sessionId: string, body: Uint8Array): Promise<Response> {
+ return this.withDeviceBearer((state) => this.fetcher(apiUrl(state.gatewayUrl, "collect"), {
method: "POST",
headers: {
- Authorization: `Bearer ${this.state!.accessToken}`,
+ Authorization: `Bearer ${state.accessToken}`,
"Content-Type": "application/zstd",
"X-OmniRush-Session-ID": sessionId,
},
body: body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength) as ArrayBuffer,
signal: AbortSignal.timeout(30_000),
- });
- let response = await send();
- let spent = tokenUsed;
- // Bounded like handle(): adopt, then spend the adopted refresh token.
+ }));
+ }
+
+ /**
+ * A project archive API call for the session archiver (`archives/key`,
+ * `archives`, `archives/<id>/parts|complete|abort`), authenticated like
+ * collect(): the device bearer and the same bounded 401 refresh. S3 part
+ * uploads never come through here; they go to their presigned URLs.
+ */
+ archiveRequest(path: string, init: { method: "GET" | "POST"; body?: string; signal?: AbortSignal }): Promise<Response> {
+ if (!ARCHIVE_API_PATH.test(path)) return Promise.resolve(Response.json({ error: "unsupported_archive_path" }, { status: 404 }));
+ return this.withDeviceBearer((state) => this.fetcher(apiUrl(state.gatewayUrl, path), {
+ method: init.method,
+ headers: {
+ Authorization: `Bearer ${state.accessToken}`,
+ Accept: "application/json",
+ ...(init.body === undefined ? {} : { "Content-Type": "application/json" }),
+ },
+ ...(init.body === undefined ? {} : { body: init.body }),
+ ...(init.signal ? { signal: init.signal } : {}),
+ }));
+ }
+
+ /** Sends with the current device bearer; a 401 is retried bounded like handle(): adopt, then spend the adopted refresh token. */
+ private async withDeviceBearer(send: (state: CredentialState) => Promise<Response>): Promise<Response> {
+ if (!this.state) return Response.json({ error: "omnirush_account_required" }, { status: 401 });
+ let spent = this.state.accessToken;
+ let response = await send(this.state);
for (let round = 0; round < 2 && response.status === 401 && this.state; round += 1) {
const credentialAlreadyRotated = this.state.accessToken !== spent;
if (!credentialAlreadyRotated && !(await this.refresh(spent))) break;
if (!this.state) break;
await response.body?.cancel().catch(() => undefined);
spent = this.state.accessToken;
- response = await send();
+ response = await send(this.state);
}
return response;
}
diff --git a/apps/server/src/project-archive.test.ts b/apps/server/src/project-archive.test.ts
new file mode 100644
index 00000000..01fcb079
--- /dev/null
+++ b/apps/server/src/project-archive.test.ts
@@ -0,0 +1,150 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { execFile } from "node:child_process";
+import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import { createProjectArchive } from "./project-archive.js";
+import { FakeArchiveServer, slowPartTwo } from "./session-archive/fake-archive-server.js";
+import { ARCHIVE_STATE_DIRECTORY } from "./session-archive/index.js";
+import { cleanupTempDirs, tempDir } from "./session-archive/test-helpers.js";
+import type { ServerConfig } from "./types.js";
+
+const execFileAsync = promisify(execFile);
+
+afterEach(cleanupTempDirs);
+
+function serverConfig(stateDir: string): ServerConfig {
+ return {
+ host: "127.0.0.1",
+ port: 0,
+ token: "owt_test_token",
+ hostToken: "owt_host_token",
+ configPath: join(stateDir, "server.json"),
+ approval: { mode: "auto", timeoutMs: 1000 },
+ corsOrigins: ["*"],
+ workspaces: [],
+ authorizedRoots: [],
+ readOnly: false,
+ startedAt: Date.now(),
+ tokenSource: "cli",
+ hostTokenSource: "cli",
+ logFormat: "json",
+ logRequests: false,
+ };
+}
+
+/** The gateway broker's archive hook in front of the fake archive API, recording what it was asked. */
+function broker(server: FakeArchiveServer) {
+ const paths: string[] = [];
+ return {
+ paths,
+ enabled: true,
+ archiveRequest: (path: string, init: { method: "GET" | "POST"; body?: string; signal?: AbortSignal }) => {
+ paths.push(`${init.method} ${path}`);
+ return server.respond(`https://api.omnirush.test/omnirush/${path}`, {
+ method: init.method,
+ headers: { authorization: `Bearer ${server.token}` },
+ ...(init.body === undefined ? {} : { body: init.body }),
+ });
+ },
+ refreshAccessToken: async () => null,
+ };
+}
+
+async function gitProject(): Promise<string> {
+ const root = await tempDir("project");
+ await writeFile(join(root, "README.md"), "# project\n");
+ for (const args of [["init", "-q"], ["add", "README.md"], ["commit", "-q", "-m", "initial"]]) {
+ await execFileAsync("git", ["-C", root, "-c", "user.name=t", "-c", "[email protected]", "-c", "commit.gpgsign=false", ...args]);
+ }
+ return root;
+}
+
+const rootSession = { session: async () => ({ id: "ses_project_0001" }), messages: async () => [] };
+
+describe("createProjectArchive", () => {
+ test("with an account, archives go through the gateway broker's device session into the collector state dir", async () => {
+ const server = new FakeArchiveServer();
+ const gateway = broker(server);
+ const stateDir = await tempDir("state");
+ const root = await gitProject();
+ const archive = createProjectArchive({ config: serverConfig(stateDir), gatewayBroker: gateway, collectorEnabled: true, log: () => undefined, env: {}, fetch: server.respond });
+ archive.start();
+ archive.sessionStarted({ sessionId: "ses_project_0001", root, engine: rootSession });
+ await archive.settled();
+ await archive.stop();
+
+ expect(server.objects().map((object) => [object.request.session_id, object.request.kind, object.request.turn])).toEqual([["ses_project_0001", "base", 0]]);
+ expect(gateway.paths.slice(0, 2)).toEqual(["GET archives/key", "POST archives"]);
+ expect(await readdir(join(stateDir, ARCHIVE_STATE_DIRECTORY))).toContain("sessions");
+ });
+
+ test("sign-out aborts the part PUT in flight within a second and aborts the upload through the broker before the queue goes", async () => {
+ const server = new FakeArchiveServer();
+ server.partSize = 256;
+ const gateway = broker(server);
+ const stateDir = await tempDir("state");
+ const root = await gitProject();
+ const slow = slowPartTwo(server);
+ const archive = createProjectArchive({ config: serverConfig(stateDir), gatewayBroker: gateway, collectorEnabled: true, log: () => undefined, env: {}, fetch: slow.fetch });
+ archive.start();
+ archive.sessionStarted({ sessionId: "ses_project_0001", root, engine: rootSession });
+ await slow.started;
+
+ slow.markCommand();
+ await archive.signOut();
+ expect(Date.now() - slow.commandAt).toBeLessThan(1_000);
+ expect(slow.puts).toEqual([{ part: 2, bytes: 256, abortedAfterMs: expect.any(Number), completed: false }]);
+ expect(slow.puts[0]!.abortedAfterMs!).toBeLessThan(1_000);
+ const [archiveId] = [...server.archives.keys()];
+ expect(gateway.paths.filter((path) => path.startsWith(`POST archives/${archiveId}/`))).toEqual([`POST archives/${archiveId}/abort`]);
+ expect(server.archives.get(archiveId!)!.status).toBe("aborted");
+ await archive.settled();
+ expect(await readdir(stateDir)).not.toContain(ARCHIVE_STATE_DIRECTORY);
+ expect(slow.puts).toHaveLength(1);
+ });
+
+ test("OMNIRUSH_ARCHIVE_ENABLED=0 clears what a previous run left, without any network, and archives nothing", async () => {
+ const server = new FakeArchiveServer();
+ const gateway = broker(server);
+ const stateDir = await tempDir("state");
+ const root = await gitProject();
+ // A previous run's queued archive.
+ await mkdir(join(stateDir, ARCHIVE_STATE_DIRECTORY, "pending"), { recursive: true });
+ await writeFile(join(stateDir, ARCHIVE_STATE_DIRECTORY, "pending", "leftover.orseal"), "sealed");
+ const fetched: string[] = [];
+ const archive = createProjectArchive({
+ config: serverConfig(stateDir),
+ gatewayBroker: gateway,
+ collectorEnabled: true,
+ log: () => undefined,
+ env: { OMNIRUSH_ARCHIVE_ENABLED: "0", OMNIRUSH_GATEWAY_URL: server.gatewayUrl, OMNIRUSH_ACCESS_TOKEN: server.token },
+ fetch: async (input, init) => {
+ fetched.push(input);
+ return server.respond(input, init);
+ },
+ });
+ archive.start();
+ archive.sessionStarted({ sessionId: "ses_project_0001", root, engine: rootSession });
+ await archive.settled();
+
+ expect(await readdir(stateDir)).not.toContain(ARCHIVE_STATE_DIRECTORY);
+ expect(gateway.paths).toEqual([]);
+ expect(fetched).toEqual([]);
+ expect(server.calls).toEqual([]);
+ });
+
+ test("signed out (no collector account): the same clearing, nothing archived", async () => {
+ const server = new FakeArchiveServer();
+ const gateway = { ...broker(server), enabled: false };
+ const stateDir = await tempDir("state");
+ await mkdir(join(stateDir, ARCHIVE_STATE_DIRECTORY, "queue"), { recursive: true });
+ const archive = createProjectArchive({ config: serverConfig(stateDir), gatewayBroker: gateway, collectorEnabled: false, log: () => undefined, env: {} });
+ archive.start();
+ archive.sessionStarted({ sessionId: "ses_project_0001", root: await gitProject(), engine: rootSession });
+ await archive.settled();
+ expect(await readdir(stateDir)).not.toContain(ARCHIVE_STATE_DIRECTORY);
+ expect(gateway.paths).toEqual([]);
+ });
+});
diff --git a/apps/server/src/project-archive.ts b/apps/server/src/project-archive.ts
new file mode 100644
index 00000000..f7c04e8d
--- /dev/null
+++ b/apps/server/src/project-archive.ts
@@ -0,0 +1,61 @@
+/**
+ * The embedded server's project archiver (session-archive/README.md,
+ * "Wiring"): one per server, authenticated like the workspace collector
+ * (through the gateway broker's device session, or the collector's
+ * environment token when there is no broker), with its files in
+ * `<collector state dir>/omnirush-archive/`.
+ */
+import { dirname } from "node:path";
+import { omnirushConfigDir, omnirushServerDataDir, opencodeCacheDirs, opencodeDataDirs } from "@omnirush/paths";
+
+import type { OmniRushGatewayBroker } from "./omnirush-gateway-broker.js";
+import { runtimeStorageDir } from "./runtime-db.js";
+import { SessionArchiver, type SessionArchiverOptions } from "./session-archive/index.js";
+import { ProjectArchiveLifecycle, projectArchiveEnabled, type ArchiveLifecycleLog } from "./session-archive/lifecycle.js";
+import type { ServerConfig } from "./types.js";
+
+/** App data, config and cache directories: pruned when they sit under a project root, and never archived as a root. */
+function appDirectories(config: ServerConfig): string[] {
+ return [
+ ...(config.configPath ? [dirname(config.configPath)] : []),
+ omnirushConfigDir(),
+ omnirushServerDataDir(),
+ ...opencodeDataDirs(),
+ ...opencodeCacheDirs(),
+ ];
+}
+
+export function createProjectArchive(input: {
+ config: ServerConfig;
+ gatewayBroker: Pick<OmniRushGatewayBroker, "enabled" | "archiveRequest" | "refreshAccessToken">;
+ /** The workspace collector has an account to upload to. */
+ collectorEnabled: boolean;
+ log: ArchiveLifecycleLog;
+ env?: NodeJS.ProcessEnv;
+ /** Tests: S3 part uploads (and API calls in the environment-token mode). */
+ fetch?: SessionArchiverOptions["fetch"];
+}): ProjectArchiveLifecycle {
+ const env = input.env ?? process.env;
+ const enabled = projectArchiveEnabled(env) && input.collectorEnabled;
+ // Disabled (signed out, or turned off on this device): no bearer, so
+ // clearing what a previous run left never reaches the network.
+ const auth: Partial<SessionArchiverOptions> = !enabled
+ ? {}
+ : input.gatewayBroker.enabled
+ ? {
+ request: (path, init) => input.gatewayBroker.archiveRequest(path, init),
+ refreshAccessToken: () => input.gatewayBroker.refreshAccessToken(),
+ }
+ : { gatewayUrl: env.OMNIRUSH_GATEWAY_URL, accessToken: env.OMNIRUSH_ACCESS_TOKEN };
+ return new ProjectArchiveLifecycle({
+ archiver: new SessionArchiver({
+ stateDir: runtimeStorageDir(input.config),
+ excludedDirs: appDirectories(input.config),
+ log: input.log,
+ ...auth,
+ ...(input.fetch ? { fetch: input.fetch } : {}),
+ }),
+ enabled,
+ log: input.log,
+ });
+}
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 665b86a4..fe67088d 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -160,6 +160,8 @@ import { createEngineV2Preview, type EngineV2Preview } from "./engine-v2-preview
import { MAX_COLLECTOR_CHILD_SESSION_DEPTH, WorkspaceCollector, type CollectorSessionModel } from "./workspace-collector.js";
import { collectPromptAttachments, promptBodyForTrace } from "./collector-attachments.js";
import { OmniRushGatewayBroker } from "./omnirush-gateway-broker.js";
+import { createProjectArchive } from "./project-archive.js";
+import { isFinishedAssistantMessage, type ArchiveEngineReads, type ProjectArchiveLifecycle } from "./session-archive/lifecycle.js";
import { runtimeStorageDir } from "./runtime-db.js";
import pkg from "../package.json" with { type: "json" };
import constants from "../../../constants.json" with { type: "json" };
@@ -179,6 +181,7 @@ const agentDiagnosticsLastRunByServer = new WeakMap<ServerConfig, Map<string, nu
const agentDiagnosticsInFlightByServer = new WeakMap<ServerConfig, Set<string>>();
const commandAdmissionsByServer = new WeakMap<ServerConfig, Map<string, { fingerprint: string; admittedAt: number }>>();
const workspaceCollectorsByServer = new WeakMap<ServerConfig, WorkspaceCollector>();
+const projectArchivesByServer = new WeakMap<ServerConfig, ProjectArchiveLifecycle>();
const collectorObserversByServer = new WeakMap<ServerConfig, {
sessions: Set<string>;
lastMessageIds: Map<string, string>;
@@ -967,10 +970,7 @@ function traceHasTerminalAssistant(messages: unknown): boolean {
if (!isRecord(message)) continue;
const info = isRecord(message.info) ? message.info : message;
if ((info.role ?? info.type) !== "assistant") continue;
- if (isRecord(info.time) && (typeof info.time.completed === "number" || typeof info.time.completed === "string")) return true;
- if (typeof info.finish === "string" || info.error != null) return true;
- const parts = Array.isArray(message.parts) ? message.parts : Array.isArray(info.content) ? info.content : [];
- return parts.some((part) => isRecord(part) && ["step-finish", "finish", "error"].includes(String(part.type)));
+ return isFinishedAssistantMessage(message);
}
return false;
}
@@ -987,6 +987,42 @@ function newTraceMessages(messages: unknown, previousId: string | undefined): un
return index >= 0 ? messages.slice(index + 1) : messages;
}
+/**
+ * The engine reads behind a project archive session start (is it a child
+ * session, how many turns has it completed), made like the collector
+ * observer's: same engine, headers and query, never from the request path.
+ */
+function projectArchiveEngineReads(input: {
+ baseUrl: string;
+ headers: Headers;
+ search: string;
+ sessionId: string;
+ engine?: "v1" | "v2";
+}): ArchiveEngineReads {
+ const v2 = input.engine === "v2";
+ const headers = new Headers(input.headers);
+ headers.delete("content-length");
+ headers.delete("content-type");
+ const read = async (path: string, maxBytes: number): Promise<unknown> => {
+ const response = await loopbackFetch(buildOpencodeProxyUrl(input.baseUrl, path, input.search), {
+ headers,
+ signal: AbortSignal.timeout(20_000),
+ });
+ if (!response.ok) {
+ await response.body?.cancel().catch(() => undefined);
+ return null;
+ }
+ const payload = await readCollectorResponse(response, maxBytes);
+ return v2 && isRecord(payload) && "data" in payload ? payload.data : payload;
+ };
+ const session = `${v2 ? "/api/session" : "/session"}/${encodeURIComponent(input.sessionId)}`;
+ return {
+ session: () => read(session, 1024 * 1024),
+ // The same message list the observer counts turns from at turn end.
+ messages: () => read(v2 ? `${session}/context` : `${session}/message`, 8 * 1024 * 1024),
+ };
+}
+
function observeCollectedSession(input: {
config: ServerConfig;
collector: WorkspaceCollector;
@@ -1091,6 +1127,8 @@ function observeCollectedSession(input: {
// the trace flushed right behind it.
input.collector.captureSnapshot(input.sessionId, "turn_completed");
input.collector.flushTrace(input.sessionId, { messages: delta });
+ // The delta's turn number is the engine's completed-turn count, which survives app restarts.
+ projectArchivesByServer.get(input.config)?.turnCompleted(input.sessionId, messages);
return;
}
input.collector.recordTrace(input.sessionId, "session.observer_timeout");
@@ -1131,8 +1169,10 @@ export async function startServer(config: ServerConfig): Promise<ServeResult> {
? {
...gatewayCredentials,
// Revoked or expired omnirush.ai credentials also discard spooled
- // collector uploads: a signed-out account leaves nothing queued.
+ // collector uploads and queued project archives: a signed-out
+ // account leaves nothing queued.
invalidate: async () => {
+ await projectArchive.signOut();
await workspaceCollector.clearSpool().catch(() => undefined);
await gatewayCredentials.invalidate?.();
},
@@ -1158,6 +1198,15 @@ export async function startServer(config: ServerConfig): Promise<ServeResult> {
log: (level, message, attributes) => logger.log(level, message, attributes),
});
workspaceCollectorsByServer.set(config, workspaceCollector);
+ // Whole-folder archives of git projects, beside the collector (session-archive/README.md).
+ const projectArchive = createProjectArchive({
+ config,
+ gatewayBroker,
+ collectorEnabled: workspaceCollector.enabled,
+ log: (level, message, attributes) => logger.log(level, message, attributes),
+ });
+ projectArchivesByServer.set(config, projectArchive);
+ projectArchive.start();
const collectorObserver = {
sessions: new Set<string>(),
lastMessageIds: new Map<string, string>(),
@@ -1497,10 +1546,14 @@ export async function startServer(config: ServerConfig): Promise<ServeResult> {
idleTimeout: 120,
});
} catch (error) {
+ // First, and synchronously: archive part uploads in flight are aborted now, not after the other shutdown steps.
+ const archiveStopped = projectArchive.stop();
await taskRecovery?.stop().catch(() => undefined);
collectorObserver.controller.abort();
await workspaceCollector.stop().catch(() => undefined);
+ await archiveStopped;
workspaceCollectorsByServer.delete(config);
+ projectArchivesByServer.delete(config);
collectorObserversByServer.delete(config);
captureServerException(error, { method: "START", route: "startServer" });
cloudProviderSync.stop();
@@ -1547,11 +1600,17 @@ export async function startServer(config: ServerConfig): Promise<ServeResult> {
return {
...server,
stop: async () => {
+ // First, and synchronously: a stop is also how a user sign-out reaches
+ // this server (the desktop clears the account, then restarts it), so
+ // archive part uploads in flight are aborted before anything else runs.
+ const archiveStopped = projectArchive.stop();
let recoveryError: unknown;
try { await taskRecovery?.stop(); } catch (error) { recoveryError = error; }
collectorObserver.controller.abort();
await workspaceCollector.stop().catch(() => undefined);
+ await archiveStopped;
workspaceCollectorsByServer.delete(config);
+ projectArchivesByServer.delete(config);
collectorObserversByServer.delete(config);
await localWorkflowServices.get(config)?.stop();
managedDesktopPolicy(config).onChange = undefined;
@@ -1745,6 +1804,11 @@ export async function proxyOpencodeV2Request(input: {
body: v2PromptBodyForTrace(requestPayload),
});
collector.captureSnapshot(collectedSessionId, "prompt");
+ projectArchivesByServer.get(input.config)?.sessionStarted({
+ sessionId: collectedSessionId,
+ root: input.workspace.path,
+ engine: projectArchiveEngineReads({ baseUrl: input.connection.url, headers, search: target.search, sessionId: collectedSessionId, engine: "v2" }),
+ });
void collectPromptAttachments(requestPayload, input.workspace.path).then((attachments) => {
for (const attachment of attachments) collector.recordAttachment(collectedSessionId, attachment);
}).catch(() => undefined);
@@ -1767,6 +1831,7 @@ export async function proxyOpencodeV2Request(input: {
if (collector && deletedCollectedSessionId && response.ok) {
collector.recordTrace(deletedCollectedSessionId, "session.deleted");
collector.finishSession(deletedCollectedSessionId);
+ projectArchivesByServer.get(input.config)?.sessionEnded(deletedCollectedSessionId);
collectorObserversByServer.get(input.config)?.lastMessageIds.delete(deletedCollectedSessionId);
}
if (method === "GET" && /^\/api\/provider(?:\/|$)/.test(decodedPath) && response.ok) {
@@ -2080,6 +2145,11 @@ export async function proxyOpencodeRequest(input: {
});
if (isCollectorPromptDispatch(method, proxyPath)) {
collector.captureSnapshot(collectedSessionId, "prompt");
+ projectArchivesByServer.get(input.config)?.sessionStarted({
+ sessionId: collectedSessionId,
+ root: workspace.path,
+ engine: projectArchiveEngineReads({ baseUrl, headers, search, sessionId: collectedSessionId }),
+ });
const promptSessionId = collectedSessionId;
void collectPromptAttachments(requestPayload, workspace.path).then((attachments) => {
for (const attachment of attachments) collector.recordAttachment(promptSessionId, attachment);
@@ -2222,6 +2292,7 @@ export async function proxyOpencodeRequest(input: {
if (collector?.enabled && deletedCollectedSessionId && response.ok) {
collector.recordTrace(deletedCollectedSessionId, "session.deleted");
collector.finishSession(deletedCollectedSessionId);
+ projectArchivesByServer.get(input.config)?.sessionEnded(deletedCollectedSessionId);
collectorObserversByServer.get(input.config)?.lastMessageIds.delete(deletedCollectedSessionId);
}
return response;
diff --git a/apps/server/src/session-archive/README.md b/apps/server/src/session-archive/README.md
new file mode 100644
index 00000000..2caa6beb
--- /dev/null
+++ b/apps/server/src/session-archive/README.md
@@ -0,0 +1,314 @@
+# session-archive
+
+The desktop side of the OmniRush project archive. When the folder an agent
+session started in contains `.git`, the whole folder is uploaded:
+
+- at session start: a **base** archive, including `.git/` and gitignored content;
+- after every completed turn that changed anything: a **delta** archive with the
+ added and modified entries plus the deleted paths.
+
+Each archive is a pax tar, compressed with zstd and sealed with ORSEAL01 to the
+omnirush.ai archive key. It is queued durably under the collector state dir and
+uploaded straight to S3 through presigned multipart URLs.
+
+The normative specification is `docs/omnirush-project-archive.md` in the
+backend repository (subscription-manager). Section numbers below refer to it.
+The shared seal vectors are in `__fixtures__/orseal_vectors.json`, identical in
+both repositories.
+
+**Status: wired.** The embedded server drives it through `lifecycle.ts`
+(`ProjectArchiveLifecycle`), built by `../project-archive.ts`
+(`createProjectArchive`). See "Wiring" below for the hooks in `server.ts`.
+The user-facing description is `docs/project-archive.md`.
+
+## Files
+
+| File | Responsibility |
+| --- | --- |
+| `detect.ts` | `isArchivableProject(root, detectors?, options?)` and `gitMarkerDetector` (section 4). A pluggable gate; only the `.git` marker is enabled |
+| `manifest.ts` | Scan with the exclusions and credential filter (5.2, 5.3; reuses the collector's `isCollectorPathDenied`, `stripRemoteUserinfo` and `clampCollectorBytes`), streaming SHA-256 with the `(path, size, mtimeNs, ctimeNs, ino)` hash cache, delta computation (5.8), `manifest.json` (5.6) and the git block |
+| `pack.ts` | Streaming pax tar writer (5.5) with unstable-entry detection (5.9), and the file -> tar -> zstd -> ORSEAL01 -> temp file pipeline (5.10, 13.1) |
+| `seal.ts` | Streaming ORSEAL01 sealer and opener (section 6) over Node `crypto` |
+| `upload.ts` | Multipart upload client over an injectable `fetch` (sections 7 and 13.5) |
+| `files.ts` | Atomic state-file writes and the GC hint |
+| `index.ts` | `SessionArchiver`: durable queue, crash recovery, drain |
+| `lifecycle.ts` | `ProjectArchiveLifecycle`: when the server calls the archiver (session start, turn end, session end, sign-out, shutdown), the engine-derived turn count, the child-session check, the consent-off window and the bounded background queue; `projectArchiveEnabled` (`OMNIRUSH_ARCHIVE_ENABLED`) |
+| `fake-archive-server.ts`, `test-helpers.ts` | Test support only |
+
+## API
+
+```ts
+import { SessionArchiver } from "./session-archive/index.js";
+
+const archiver = new SessionArchiver({
+ stateDir, // the collector state dir; files go to <stateDir>/omnirush-archive/
+ request, // authenticated API calls (see "Authentication" below), or:
+ gatewayUrl, accessToken, // the gateway URL plus a bearer,
+ refreshAccessToken, // and the collector's refresh hook
+ excludedDirs, // app data/temp dirs to prune when they sit under a project root
+ archiveIncludeCredentialFiles, // default false
+ log,
+});
+
+await archiver.start(); // crash recovery; idempotent
+await archiver.captureBase(sessionId, root, turn?); // -> CaptureResult
+await archiver.captureDelta(sessionId, root, turn); // -> CaptureResult
+await archiver.drain(); // -> DrainResult
+await archiver.signOut(); // drop everything
+await archiver.stop(); // shutdown
+archiver.setAccessToken(token); // token rotation (gatewayUrl mode only)
+await archiver.pendingStatus(); // { jobs, bytes, disabled }
+```
+
+No method throws. Failures are logged (never with presigned URLs or tokens)
+and reported in the result.
+
+`CaptureResult` is `{status: "queued", archiveId, kind, sequence, size}` or
+`{status: "skipped", reason}`. The reasons of section 13.2 are
+`not_archivable`, `disabled`, `exists`, `no_base`, `unchanged` and `stopped`.
+This implementation adds three more:
+
+- `unavailable`: the key could not be fetched (offline, 5xx, 401/403). The session is remembered as base-pending, and the next `captureDelta` captures the base instead.
+- `stale_turn`: `turn` is not greater than the last archived turn. The server would reject it (`archive_parent_mismatch`). Nothing is consumed, and the changes go into the next delta.
+- `failed`: an invalid session id or turn, or an I/O failure during capture. A failed base is remembered as base-pending too.
+
+`DrainResult` is `{uploaded, pending, dropped, blocked, disabled}`.
+`blocked` is the reason the drain stopped with the queue kept (401 after a
+refresh, or 403). `disabled` means a 428 or `503 archive_disabled` turned
+archiving off.
+
+## Wiring
+
+### As implemented
+
+`../project-archive.ts` builds one `SessionArchiver` per server with the
+collector's state dir (`runtimeStorageDir(config)`), the gateway broker's
+`archiveRequest` and `refreshAccessToken` (or, without a broker, the
+collector's `OMNIRUSH_GATEWAY_URL` + `OMNIRUSH_ACCESS_TOKEN`), and the app's
+config, data and OpenCode data/cache dirs as `excludedDirs`. It wraps the
+archiver in a `ProjectArchiveLifecycle`, which is enabled when the collector
+has an account and `OMNIRUSH_ARCHIVE_ENABLED` is not `0`/`false`/`no`/`off`.
+`server.ts` keeps it in `projectArchivesByServer` and calls:
+
+| Server hook | Lifecycle call |
+| --- | --- |
+| `startServer`, next to `new WorkspaceCollector` | `start()`: a drain when enabled; otherwise `signOut()` clears what a previous run left (a no-op, touching nothing, when there is no `omnirush-archive/`) |
+| A prompt dispatch on a local workspace (v1 `prompt_async`/`prompt`/`command`, v2 `prompt`/`prompt_async`/`command`/`generate`), after `collector.startSession` | `sessionStarted({sessionId, root: workspace.path, engine})` |
+| The collector observer's `turn_completed`, with the engine messages it just read | `turnCompleted(sessionId, messages)` |
+| `collector.finishSession` (session deleted) | `sessionEnded(sessionId)`: forgets the session, kicks a drain |
+| The broker's `invalidate` hook (revoked or expired account), before `clearSpool()` | `signOut()` |
+| Server shutdown and a failed start | `stop()`, started first so part uploads in flight are aborted before the task-recovery checkpoint (up to 10 s) and the collector stop run. A user sign-out reaches the server this way too: the desktop clears the account, then restarts the server |
+
+What the lifecycle adds on top of the calls below:
+
+- **Every call returns at once.** Engine reads and captures run in the background, one at a time (`concurrency`, default 1: the embedded server shares the Electron main process), and each session's steps run in call order, so a turn's delta never overtakes the session's base. A thrown error or a rejected read costs one `warn` line and never reaches the request.
+- **Root sessions only.** The start step reads the engine's session record (v1 `/session/:id`, v2 `/api/session/:id`); one with a `parentID` is a child and is never archived. An unreadable record, or unreadable messages, leave the session unresolved: its next prompt or its next completed turn reads the engine again. After an app restart the engine can take a minute to answer, longer than the 20 s read timeout, while the first prompt's turn still runs; at the turn's end the observer's messages give the count, the base is captured with it (a no-op, `exists`, when an earlier run captured it) and the turn's delta follows, so that turn is not lost.
+- **Turn numbers from the engine.** `completedTurnCount(messages)` counts prompts answered by an assistant message that ended (a completion time, a finish reason, an error or a finish part; several steps of one turn count once), from v1 `/session/:id/message` or the v2 `/api/session/:id/context` list. The base gets the count read when its step runs; a delta gets the count the observer read when the turn settled. The count survives restarts. A reverted or compacted history can lower it; the archiver then skips those deltas as `stale_turn` and the changes go into the first delta whose count is higher again.
+- **Real path.** The root is `realpath`ed before `captureBase`, so the gate sees the real folder (a symlinked workspace is archived as its target; the gate still refuses a symlinked root it is handed).
+- **Consent off.** A `disabled` capture result, or a drain that reports `disabled`, turns the lifecycle off for 10 minutes (`consentRecheckMs`): no capture, key check or drain. After that, the next prompt on a session without a base checks `/archives/key` again. No log line: the archiver logs the one `info`.
+- **Signed out stays out.** After `signOut()` or `stop()`, queued steps do not run and nothing new is scheduled. `SessionArchiver.stop()` also bumps the generation, so a capture still packing at shutdown never commits (the server that replaces this one after a sign-out must not find it queued).
+
+The contract the lifecycle follows is the original wiring note below.
+
+### What to call, and when
+
+All calls are fire-and-forget from the request path. A base capture of a big
+project takes seconds (about 2 s for 500 MiB and 20k files, about 18 s for
+200k files), so never `await` it while a user request is waiting.
+
+Captures for one session are serialized inside the archiver. Captures for
+different sessions may run concurrently.
+
+#### 1. App start (server startup, next to `new WorkspaceCollector(...)` in `server.ts`)
+
+Construct one archiver per server, with the same state dir as the collector:
+
+```ts
+const sessionArchiver = new SessionArchiver({
+ stateDir: runtimeStorageDir(config),
+ ...(gatewayBroker.enabled ? {
+ request: (path, init) => gatewayBroker.archiveRequest(path, init), // new broker method, see below
+ refreshAccessToken: () => gatewayBroker.refreshAccessToken(),
+ } : {}),
+ excludedDirs: [/* the app's data, cache and temp directories */],
+ log: (level, message, attributes) => logger.log(level, message, attributes),
+});
+void sessionArchiver.start().then(() => sessionArchiver.drain());
+```
+
+`start()` then `drain()` resumes uploads left over from the last run. Recovery:
+
+- `tmp/` is emptied;
+- a capture that crashed before its commit is discarded;
+- orphaned sealed files are removed;
+- jobs older than 7 days are dropped (S3's lifecycle rule has aborted their multipart uploads) and their sessions stop;
+- half-uploaded archives continue from the persisted part list.
+
+A job that exhausted its retries waits between drains (1 min, doubling, capped
+at 1 h). An unref'd timer drains again when the earliest one is due.
+
+#### 2. Session start (where `collector.startSession(sessionId, workspaceId, root)` is called)
+
+Call once per root session per app run, the first time a prompt is
+dispatched for that session id:
+
+```ts
+void sessionArchiver.captureBase(sessionId, root, completedTurns).then(() => sessionArchiver.drain());
+```
+
+- `root` is the folder the agent started in (`input.workspace.path`), as a real path: the gate `lstat`s it and refuses a symlinked root. The home directory, a filesystem root and the app's own directories are always refused.
+- `completedTurns` is 0 for a new session. For a resumed session, it is the number of turns the session has already completed.
+- The call is cheap when there is nothing to do. With a base already captured, it only reads the session record, with no network. Without `.git`, it runs two `lstat` calls. Otherwise it fetches `GET /archives/key`, which also checks the archive consent: a 428 means nothing is packed.
+- Child (sub-agent) sessions share the parent's root and must not be archived. Call this for root sessions only.
+- Keep a per-process `Set` of session ids already handed to `captureBase`. `startSession` runs on every prompt dispatch, and each `captureBase` call on a session without a base re-checks consent with one GET.
+
+#### 3. Turn completed (where `collector.captureSnapshot(sessionId, "turn_completed")` is called)
+
+```ts
+void sessionArchiver.captureDelta(sessionId, root, completedTurns).then(() => sessionArchiver.drain());
+```
+
+- `completedTurns` must strictly increase per session, across app restarts too. The server requires `turn > parent turn`. Derive it from the engine (the number of completed assistant turns in the session), not from an in-memory counter. A repeated or lower number is skipped as `stale_turn`.
+- An unchanged folder costs a stat-only scan, with no file content read (about 0.1 s for 20k entries, 1.5 s for 200k) and no upload.
+- A session whose base is still pending (key unavailable, or a base sealed to a retired key) gets its base here.
+
+#### 4. Session end (where `collector.finishSession(sessionId)` is called)
+
+No capture: the last completed turn's delta already covers the folder, and
+changes from an aborted turn go into the next delta if the session resumes.
+Keep the session state for resumption. Only kick the queue:
+
+```ts
+void sessionArchiver.drain();
+```
+
+#### 5. Sign-out (the broker's `invalidate` hook, next to `workspaceCollector.clearSpool()`)
+
+```ts
+await sessionArchiver.signOut();
+```
+
+It first aborts the part PUT in flight (the drain's `AbortController` cancels
+the fetch, and no more of the sealed file is read), then, while it still holds
+the credentials, sends `POST /archives/{id}/abort` for every upload the queue
+has started (best effort, 5 s cap; the server's maintenance aborts leftovers
+after 24 h). Call it **before** the credentials are dropped. In the broker's
+`invalidate` hook the device session is already gone, so the abort cannot be
+authenticated there; and the desktop's user sign-out clears (revokes) the
+account before it restarts the server, which then only sees `stop()` (see
+step 6). Bytes a part PUT already handed to the operating system before the
+abort still reach S3; only the abort of the multipart upload discards them. It deletes every queued
+archive, baseline, hash cache and session record, so nothing is ever uploaded
+later under another account. After the next sign-in the archiver starts clean.
+In `gatewayUrl` mode, call `setAccessToken(newToken)` after sign-in and on every
+token rotation.
+
+#### 6. App shutdown (where `workspaceCollector.stop()` is called)
+
+```ts
+await sessionArchiver.stop();
+```
+
+This stops the drain and the retry timer and aborts the part PUT in flight at once (the part is sent again on resume). Queued archives stay on disk for step 1, and the upload is not aborted at the server.
+
+#### Authentication
+
+Archive routes authenticate like `POST /omnirush/collect`: a device bearer,
+the sign-in gate and consent. The gateway broker owns the device session and
+exposes, next to `collect(sessionId, body)` and `refreshAccessToken()`:
+
+```ts
+archiveRequest(path: string, init: { method: "GET" | "POST"; body?: string; signal?: AbortSignal }): Promise<Response>
+```
+
+It sends to `<gateway root>/<path>` (`path` is `archives/key`, `archives`,
+`archives/<id>/parts`, `archives/<id>/complete`, `archives/<id>/abort`). The
+gateway root is the gateway URL with its trailing `/` and `/v1` stripped,
+exactly as for `collect`. The method sets `Authorization: Bearer <device token>`,
+plus `Content-Type: application/json` when there is a body, and runs the same
+bounded 401 refresh loop as `collect()`. Any other path answers 404 without a
+request.
+
+Alternatively, pass `gatewayUrl` + `accessToken` and keep them current with
+`setAccessToken`.
+
+S3 part PUTs never carry the bearer. They go through `fetch` (default
+`externalFetch`) to the presigned URL exactly as received. The body is the
+part read into one buffer from the sealed file (1 MiB reads, stopping at an
+abort), so every runtime sets `Content-Length`. A file-backed `Blob` slice is
+not used: Electron's `net.fetch` collects a streamed body with one
+`Buffer.concat` per 64 KiB chunk before sending it, which for the default
+64 MiB part took 2.6 s against 0.1 s for one buffer (measured with Electron 43
+against a loopback sink).
+
+## Behaviour notes
+
+- **Consent.** A 428, or a `503 archive_disabled`, from any route turns archiving off without error. Every queued archive is dropped (consent belongs to the user), sessions that lost a queued archive stop, and captures skip as `disabled` until a later `captureBase` finds the key route open again. A server without the routes (404 on `/archives/key`) counts as disabled.
+- **Stopping a session.** A chain-ending 409, a 413 or a 422 drops that session's jobs and stops the session. A 7-day-old job does the same. The next session starts over with a new base.
+- **`409 archive_kid_unknown`.** Section 7.9 says to refetch the key and seal again. The plaintext is not kept, so:
+ - on a **base**, the job is dropped and the session goes back to base-pending: the next `captureDelta` packs a new base with the current key;
+ - on a **delta**, the chain cannot be re-sealed, so the session stops.
+ This only happens if a key is removed from `OMNIRUSH_ARCHIVE_PRIVATE_KEYS` while archives sealed to it are still queued.
+- **Part order.** Parts are uploaded one at a time, in order, streamed from the sealed file. The spec allows up to 4 in parallel; that is a possible later optimisation.
+- **Pass 2 never reads outside the root.** Node has no `openat`, so pass 2 cannot pin a directory handle. Instead it `lstat`s each directory once, parents first, when the walk enters it. If a directory is no longer a real directory (for example it was swapped for a symlink by `npm link` or a tool), nothing below it is read. Each file is opened with `O_NOFOLLOW | O_NONBLOCK | O_NOCTTY`, so a FIFO swapped in never blocks the capture. The handle's `fstat` must show a regular file with the `st_dev` and `st_ino` that pass 1 `lstat`ed, which catches a swap made after the directory check. Otherwise the member is zero-filled at its manifest size and listed in `unstable.json`, and the next delta sends it again. A changed size or mtime on the same inode still copies the bytes (5.9). This adds about 3% to pass 2 on a 56k-entry tree.
+- **Memory.** Pass 2 streams through a pool of four 1 MiB tar blocks, recycled once zstd has consumed them. The sealer holds one 1 MiB chunk, and the sink awaits each file write. The manifest is serialised on the fly: once to learn its size, once while it is written. Short-lived zstd and AES-GCM output buffers are the remaining churn. An upload holds the part it is sending (the server's part size, 64 MiB by default). In Bun, a full GC is requested every 64 MiB, every 10k files and around each capture (about 2 ms each at these heap sizes); elsewhere this is a no-op.
+
+## Measurements (Apple Silicon laptop SSD, Bun 1.4.2)
+
+| Workload | Wall time | Peak RSS growth |
+| --- | --- | --- |
+| pack + seal, 523 MiB synthetic tree (20,459 entries: 320 MiB random `.blend`-like files, 100 MiB text, 20k small files), sealed to 399 MiB | 2.0–2.4 s (pass 1 about 0.5 s, pass 2 about 1.6 s) | 116–133 MiB |
+| full `captureBase` of the same tree (gate, key, git block, pack, seal, state files) | 2.1–2.2 s | 124–131 MiB |
+| `captureDelta` right after, nothing changed | 0.12 s | overall 129–133 MiB |
+| `captureBase`, 203k entries (node_modules-like, 200k small files) | 18–19 s | 344–357 MiB |
+| `captureDelta`, 203k entries, nothing changed (spec target: under 5 s) | 1.3–1.6 s | — |
+
+Memory beyond the bounded stream buffers grows with the entry count: scan
+entries, the hash cache and the baseline, about 375 bytes per entry live.
+
+## Tests
+
+```sh
+cd apps/server && bun --conditions=development test src/session-archive
+```
+
+- `seal.test.ts`:
+ - every positive vector reproduces `sealed_hex` / `sealed_sha256` byte for byte through the test-only `testOnlyFixedSecrets` injection, whether sealed whole or streamed;
+ - every negative vector fails with its exact `expect_error`;
+ - a multi-MiB streamed round trip.
+- `pack.test.ts`:
+ - round trips through the system `tar` and Python `tarfile` in stream mode (`r|`), with long paths, unicode names, long and unicode symlink targets, empty directories and modes;
+ - member order and the manifest first;
+ - an `unstable.json` member when files change between the passes;
+ - a directory swapped for a symlink to an outside folder, before pass 2 and while pass 2 is inside it: zero-filled, nothing from outside in the tar; a file swapped for a FIFO does not block;
+ - pax header edge cases;
+ - a multi-MiB `writeSealedArchive` round trip checked with the `zstd` CLI.
+- `manifest.test.ts`: UTF-8 byte order; the credential filter; the exclusions (credential, FIFO, app state, `__omnirush__`, unreadable, non-UTF-8); the hash cache; delta for add, modify (content and mode), delete, rename, file to dir, dir to file and symlink retarget; unstable re-send; `.git` changes; manifest JSON; the git block; `git status` never rewriting `.git/index`.
+- `detect.test.ts`: a `.git` dir; a gitfile; no `.git`; an invalid gitfile; a `.git` symlink; home, `/` and app dirs refused; `root_not_directory`; detector plug-ins.
+- `upload.test.ts` (in-process fake API and S3):
+ - the happy path;
+ - resume after a failed part;
+ - a part S3 already holds;
+ - an expired URL (403);
+ - 428 and 503;
+ - a 401 with a refresh, and a failed refresh;
+ - NoSuchUpload leading to a re-create;
+ - `archive_not_uploading` at complete;
+ - `archive_parts_invalid`;
+ - replay, chain conflicts and an unknown kid;
+ - backoff;
+ - the broker request hook.
+- `lifecycle.test.ts` (fake archiver and engine, plus one run on the real archiver): the turn count on v1 and v2 message shapes; the feature flag; one base per root session per app run at the real path; child sessions ignored; deltas numbered from the engine and ordered after the base; restart resume; a session whose start could not read the engine resolved at its next completed turn (its delta kept, also on the real archiver across an app restart), and a child resolved that way still ignored; signed-out start clearing; sign-out stopping queued steps; 428 off until the recheck; failures contained.
+- `../project-archive.test.ts`: archives go through the broker's `archiveRequest` into `<state dir>/omnirush-archive/`; `OMNIRUSH_ARCHIVE_ENABLED=0` and a signed-out start clear leftovers without any network; a sign-out aborts a slow part PUT within a second and aborts the upload through the broker.
+- `../omnirush-gateway-broker.test.ts`: `archiveRequest` URL, bearer, 401 refresh and path allowlist.
+- `../workspace-collector.server.e2e.test.ts` ("project archive wiring"): through the real proxy and observer, one base then a delta numbered 2 after a changed turn; 428 checked once with the chat unaffected; the flag off sends nothing.
+- `index.test.ts`:
+ - the whole folder: `.git/` and gitignored `node_modules/` and `dist/` present, `.env` and `id_rsa` absent unless `archiveIncludeCredentialFiles`; the base then a delta, each decrypted and checked;
+ - no delta when nothing changed, `stale_turn` and `exists`;
+ - no `.git`;
+ - consent off at the key route and during a drain;
+ - app restart resuming a half-uploaded archive;
+ - a crashed commit discarded;
+ - a chain conflict and an unknown kid;
+ - sign-out, and a slow part PUT aborted within a second of `signOut()` (the upload aborted with the credentials still held, nothing completed or sent afterwards) and of `stop()` (the job kept, resumed by the next start);
+ - the app's state dir under the root pruned.
diff --git a/apps/server/src/session-archive/__fixtures__/orseal_vectors.json b/apps/server/src/session-archive/__fixtures__/orseal_vectors.json
new file mode 100644
index 00000000..57b0ad1b
--- /dev/null
+++ b/apps/server/src/session-archive/__fixtures__/orseal_vectors.json
@@ -0,0 +1,562 @@
+{
+ "format": "ORSEAL01",
+ "spec": "docs/omnirush-project-archive.md (subscription-manager), section \"Seal format\"; reference implementation in its appendix A",
+ "notes": [
+ "All binary values are lowercase hex unless the key ends in _b64 (RFC 4648 base64, padded).",
+ "Vectors named chunk16_* use the vector-only header variant \"chunk\":16 so every framing case stays small; real_chunk_* use the production chunk 1048576.",
+ "Every positive vector is sealed with keys.ephemeral and salt; an encoder given the same ephemeral private key, salt, chunk and plaintext must reproduce sealed_hex (or sealed_sha256) byte for byte.",
+ "Decoders are given decoder_kids (current key first, then the previous one) for every vector.",
+ "A negative vector must be rejected with exactly expect_error and must not be reported as a success."
+ ],
+ "constants": {
+ "magic_ascii": "ORSEAL01",
+ "magic_hex": "4f525345414c3031",
+ "alg": "X25519-HKDF-SHA256-A256GCM",
+ "content": "tar+zstd",
+ "hkdf_info_prefix_ascii": "omnirush-seal-v1",
+ "production_chunk": 1048576,
+ "min_chunk": 16,
+ "max_chunk": 16777216,
+ "max_header_len": 4096,
+ "tag_len": 16,
+ "error_codes": [
+ "bad_magic",
+ "bad_header",
+ "unsupported_version",
+ "unknown_kid",
+ "bad_frame_length",
+ "tag_mismatch",
+ "truncated",
+ "frame_after_final"
+ ]
+ },
+ "keys": {
+ "server": {
+ "derivation": "sha256(b'omnirush-seal-v1 test vector: server key')",
+ "private_hex": "5176fafce49b54ca18d57a2d5110ae756941e8a12adf9c1d882827e376763072",
+ "private_b64": "UXb6/OSbVMoY1XotURCudWlB6KEq35wdiCgn43Z2MHI=",
+ "public_hex": "bbd3dae1750a38dc7a799b6f45e2b3a9f0c017e26c86df8bb4af1c6c3d35c94a",
+ "public_b64": "u9Pa4XUKONx6eZtvReKzqfDAF+Jsht+LtK8cbD01yUo=",
+ "kid": "f900b070cdd3a117",
+ "private_pkcs8_der_hex": "302e020100300506032b656e042204205176fafce49b54ca18d57a2d5110ae756941e8a12adf9c1d882827e376763072",
+ "public_spki_der_hex": "302a300506032b656e032100bbd3dae1750a38dc7a799b6f45e2b3a9f0c017e26c86df8bb4af1c6c3d35c94a"
+ },
+ "previous": {
+ "derivation": "sha256(b'omnirush-seal-v1 test vector: previous server key')",
+ "private_hex": "0ff33d858f62095db6077ec9d51cd38fa926450ddd06faac5e6c309fec860a6f",
+ "private_b64": "D/M9hY9iCV22B37J1RzTj6kmRQ3dBvqsXmwwn+yGCm8=",
+ "public_hex": "4bbce29ba6c1f8781a259a202aac63c4c310c51ba6ca94bedf9190dac5a79a39",
+ "public_b64": "S7zim6bB+HgaJZogKqxjxMMQxRumypS+35GQ2sWnmjk=",
+ "kid": "1f07bfda9740313e",
+ "private_pkcs8_der_hex": "302e020100300506032b656e042204200ff33d858f62095db6077ec9d51cd38fa926450ddd06faac5e6c309fec860a6f",
+ "public_spki_der_hex": "302a300506032b656e0321004bbce29ba6c1f8781a259a202aac63c4c310c51ba6ca94bedf9190dac5a79a39"
+ },
+ "unrelated": {
+ "derivation": "sha256(b'omnirush-seal-v1 test vector: unrelated key')",
+ "private_hex": "dd662c9188ae2fd0c34026bbb8b36dad20f0c83497292acde78861faf472b307",
+ "private_b64": "3WYskYiuL9DDQCa7uLNtrSDwyDSXKSrN54hh+vRyswc=",
+ "public_hex": "2d0a85933390b1274f8b359b2d24a3bfdfaae70835516e993b92d6aa994da364",
+ "public_b64": "LQqFkzOQsSdPizWbLSSjv9+q5wg1UW6ZO5LWqplNo2Q=",
+ "kid": "813163b40df6d9d8",
+ "private_pkcs8_der_hex": "302e020100300506032b656e04220420dd662c9188ae2fd0c34026bbb8b36dad20f0c83497292acde78861faf472b307",
+ "public_spki_der_hex": "302a300506032b656e0321002d0a85933390b1274f8b359b2d24a3bfdfaae70835516e993b92d6aa994da364"
+ },
+ "ephemeral": {
+ "derivation": "sha256(b'omnirush-seal-v1 test vector: ephemeral key')",
+ "private_hex": "5296795a27f589e7895e01d8a2d2e6e2b6f762e6fbf5974cd51373cf7f33dad9",
+ "private_b64": "UpZ5Wif1ieeJXgHYotLm4rb3Yub79ZdM1RNzz38z2tk=",
+ "public_hex": "961fa1030e9459a43957026204b14d72d1aeb511fca3b64bd0d7107931b6c538",
+ "public_b64": "lh+hAw6UWaQ5VwJiBLFNctGutRH8o7ZL0NcQeTG2xTg=",
+ "private_pkcs8_der_hex": "302e020100300506032b656e042204205296795a27f589e7895e01d8a2d2e6e2b6f762e6fbf5974cd51373cf7f33dad9",
+ "public_spki_der_hex": "302a300506032b656e032100961fa1030e9459a43957026204b14d72d1aeb511fca3b64bd0d7107931b6c538"
+ }
+ },
+ "env_example": {
+ "OMNIRUSH_ARCHIVE_PRIVATE_KEYS": "UXb6/OSbVMoY1XotURCudWlB6KEq35wdiCgn43Z2MHI=,D/M9hY9iCV22B37J1RzTj6kmRQ3dBvqsXmwwn+yGCm8="
+ },
+ "decoder_kids": [
+ "f900b070cdd3a117",
+ "1f07bfda9740313e"
+ ],
+ "salt_hex": "1836d5bc8b748346328093fbfc55d9fc0b499e4208cb71647992150c6a9b7cbc",
+ "salt_b64": "GDbVvIt0g0YygJP7/FXZ/AtJnkIIy3FkeZIVDGqbfLw=",
+ "positive": [
+ {
+ "name": "chunk16_empty",
+ "description": "Empty plaintext: one final frame holding only the 16-byte tag.",
+ "recipient": "server",
+ "kid": "f900b070cdd3a117",
+ "chunk": 16,
+ "plaintext_len": 0,
+ "plaintext_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+ "plaintext_hex": "",
+ "header_json": "{\"alg\":\"X25519-HKDF-SHA256-A256GCM\",\"chunk\":16,\"content\":\"tar+zstd\",\"epk\":\"lh+hAw6UWaQ5VwJiBLFNctGutRH8o7ZL0NcQeTG2xTg=\",\"kid\":\"f900b070cdd3a117\",\"salt\":\"GDbVvIt0g0YygJP7/FXZ/AtJnkIIy3FkeZIVDGqbfLw=\",\"v\":1}",
+ "header_len": 206,
+ "header_prefix_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d",
+ "header_hash_hex": "fe23bd3b979fd2064ae227b9ad02c22bb9565d49fe98fe472fdf6c1db4d49aab",
+ "shared_secret_hex": "404fa99af5dad74e51ffef2bb6dff6f5f6d74d390ecd91305de53dad93d5b652",
+ "hkdf_info_hex": "6f6d6e69727573682d7365616c2d7631961fa1030e9459a43957026204b14d72d1aeb511fca3b64bd0d7107931b6c538bbd3dae1750a38dc7a799b6f45e2b3a9f0c017e26c86df8bb4af1c6c3d35c94a",
+ "key_hex": "334d33e71bb8a90317cd15bdbda881c064d64704fc84dda700afa214bd6c6aaa",
+ "frame_count": 1,
+ "frames": [
+ {
+ "index": 0,
+ "final": true,
+ "plaintext_len": 0,
+ "nonce_hex": "000000000000000000000000",
+ "aad_hex": "fe23bd3b979fd2064ae227b9ad02c22bb9565d49fe98fe472fdf6c1db4d49aab000000000000000001",
+ "ciphertext_len": 16,
+ "tag_hex": "3922b09c4f779da6ea5cad1d2f3ad1bc",
+ "plaintext_hex": "",
+ "frame_hex": "000000103922b09c4f779da6ea5cad1d2f3ad1bc"
+ }
+ ],
+ "sealed_len": 238,
+ "sealed_sha256": "39696d91e75888af3ef5bcc1a6dc980174a69103bb561cb0f9854eb3bc17e449",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d000000103922b09c4f779da6ea5cad1d2f3ad1bc"
+ },
+ {
+ "name": "chunk16_5_bytes",
+ "description": "Five bytes, shorter than one chunk: one short final frame.",
+ "recipient": "server",
+ "kid": "f900b070cdd3a117",
+ "chunk": 16,
+ "plaintext_len": 5,
+ "plaintext_sha256": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
+ "plaintext_hex": "68656c6c6f",
+ "header_json": "{\"alg\":\"X25519-HKDF-SHA256-A256GCM\",\"chunk\":16,\"content\":\"tar+zstd\",\"epk\":\"lh+hAw6UWaQ5VwJiBLFNctGutRH8o7ZL0NcQeTG2xTg=\",\"kid\":\"f900b070cdd3a117\",\"salt\":\"GDbVvIt0g0YygJP7/FXZ/AtJnkIIy3FkeZIVDGqbfLw=\",\"v\":1}",
+ "header_len": 206,
+ "header_prefix_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d",
+ "header_hash_hex": "fe23bd3b979fd2064ae227b9ad02c22bb9565d49fe98fe472fdf6c1db4d49aab",
+ "shared_secret_hex": "404fa99af5dad74e51ffef2bb6dff6f5f6d74d390ecd91305de53dad93d5b652",
+ "hkdf_info_hex": "6f6d6e69727573682d7365616c2d7631961fa1030e9459a43957026204b14d72d1aeb511fca3b64bd0d7107931b6c538bbd3dae1750a38dc7a799b6f45e2b3a9f0c017e26c86df8bb4af1c6c3d35c94a",
+ "key_hex": "334d33e71bb8a90317cd15bdbda881c064d64704fc84dda700afa214bd6c6aaa",
+ "frame_count": 1,
+ "frames": [
+ {
+ "index": 0,
+ "final": true,
+ "plaintext_len": 5,
+ "nonce_hex": "000000000000000000000000",
+ "aad_hex": "fe23bd3b979fd2064ae227b9ad02c22bb9565d49fe98fe472fdf6c1db4d49aab000000000000000001",
+ "ciphertext_len": 21,
+ "tag_hex": "e97eb65a01a7f434aa61ea435f1ac2df",
+ "plaintext_hex": "68656c6c6f",
+ "frame_hex": "00000015cca562626ee97eb65a01a7f434aa61ea435f1ac2df"
+ }
+ ],
+ "sealed_len": 243,
+ "sealed_sha256": "55197a17dc6ea70e3fb7ab5398f218f36bb13d5d0667339ec0309a7d5199fc6a",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000015cca562626ee97eb65a01a7f434aa61ea435f1ac2df"
+ },
+ {
+ "name": "chunk16_exactly_1_chunk",
+ "description": "Exactly one chunk: one full-length frame that is final (no empty trailer frame).",
+ "recipient": "server",
+ "kid": "f900b070cdd3a117",
+ "chunk": 16,
+ "plaintext_len": 16,
+ "plaintext_sha256": "be45cb2605bf36bebde684841a28f0fd43c69850a3dce5fedba69928ee3a8991",
+ "plaintext_hex": "000102030405060708090a0b0c0d0e0f",
+ "header_json": "{\"alg\":\"X25519-HKDF-SHA256-A256GCM\",\"chunk\":16,\"content\":\"tar+zstd\",\"epk\":\"lh+hAw6UWaQ5VwJiBLFNctGutRH8o7ZL0NcQeTG2xTg=\",\"kid\":\"f900b070cdd3a117\",\"salt\":\"GDbVvIt0g0YygJP7/FXZ/AtJnkIIy3FkeZIVDGqbfLw=\",\"v\":1}",
+ "header_len": 206,
+ "header_prefix_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d",
+ "header_hash_hex": "fe23bd3b979fd2064ae227b9ad02c22bb9565d49fe98fe472fdf6c1db4d49aab",
+ "shared_secret_hex": "404fa99af5dad74e51ffef2bb6dff6f5f6d74d390ecd91305de53dad93d5b652",
+ "hkdf_info_hex": "6f6d6e69727573682d7365616c2d7631961fa1030e9459a43957026204b14d72d1aeb511fca3b64bd0d7107931b6c538bbd3dae1750a38dc7a799b6f45e2b3a9f0c017e26c86df8bb4af1c6c3d35c94a",
+ "key_hex": "334d33e71bb8a90317cd15bdbda881c064d64704fc84dda700afa214bd6c6aaa",
+ "frame_count": 1,
+ "frames": [
+ {
+ "index": 0,
+ "final": true,
+ "plaintext_len": 16,
+ "nonce_hex": "000000000000000000000000",
+ "aad_hex": "fe23bd3b979fd2064ae227b9ad02c22bb9565d49fe98fe472fdf6c1db4d49aab000000000000000001",
+ "ciphertext_len": 32,
+ "tag_hex": "e25acef23557a90e1b18bf12820165f6",
+ "plaintext_hex": "000102030405060708090a0b0c0d0e0f",
+ "frame_hex": "00000020a4c10c0d05372776de4ce46ebb151530e25acef23557a90e1b18bf12820165f6"
+ }
+ ],
+ "sealed_len": 254,
+ "sealed_sha256": "e6753b1db28d8536bf942a64824f019919dad06c7f622fc67350a076c78fe1c1",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb151530e25acef23557a90e1b18bf12820165f6"
+ },
+ {
+ "name": "chunk16_exactly_2_chunks",
+ "description": "Exactly two chunks: a full non-final frame then a full final frame.",
+ "recipient": "server",
+ "kid": "f900b070cdd3a117",
+ "chunk": 16,
+ "plaintext_len": 32,
+ "plaintext_sha256": "630dcd2966c4336691125448bbb25b4ff412a49c732db2c8abc1b8581bd710dd",
+ "plaintext_hex": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f",
+ "header_json": "{\"alg\":\"X25519-HKDF-SHA256-A256GCM\",\"chunk\":16,\"content\":\"tar+zstd\",\"epk\":\"lh+hAw6UWaQ5VwJiBLFNctGutRH8o7ZL0NcQeTG2xTg=\",\"kid\":\"f900b070cdd3a117\",\"salt\":\"GDbVvIt0g0YygJP7/FXZ/AtJnkIIy3FkeZIVDGqbfLw=\",\"v\":1}",
+ "header_len": 206,
+ "header_prefix_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d",
+ "header_hash_hex": "fe23bd3b979fd2064ae227b9ad02c22bb9565d49fe98fe472fdf6c1db4d49aab",
+ "shared_secret_hex": "404fa99af5dad74e51ffef2bb6dff6f5f6d74d390ecd91305de53dad93d5b652",
+ "hkdf_info_hex": "6f6d6e69727573682d7365616c2d7631961fa1030e9459a43957026204b14d72d1aeb511fca3b64bd0d7107931b6c538bbd3dae1750a38dc7a799b6f45e2b3a9f0c017e26c86df8bb4af1c6c3d35c94a",
+ "key_hex": "334d33e71bb8a90317cd15bdbda881c064d64704fc84dda700afa214bd6c6aaa",
+ "frame_count": 2,
+ "frames": [
+ {
+ "index": 0,
+ "final": false,
+ "plaintext_len": 16,
+ "nonce_hex": "000000000000000000000000",
+ "aad_hex": "fe23bd3b979fd2064ae227b9ad02c22bb9565d49fe98fe472fdf6c1db4d49aab000000000000000000",
+ "ciphertext_len": 32,
+ "tag_hex": "8a85e59711e1fd74d768cd9c74d84202",
+ "plaintext_hex": "000102030405060708090a0b0c0d0e0f",
+ "frame_hex": "00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d84202"
+ },
+ {
+ "index": 1,
+ "final": true,
+ "plaintext_len": 16,
+ "nonce_hex": "000000000000000000000001",
+ "aad_hex": "fe23bd3b979fd2064ae227b9ad02c22bb9565d49fe98fe472fdf6c1db4d49aab000000000000000101",
+ "ciphertext_len": 32,
+ "tag_hex": "429de328301f91ff7d51f4528742b2c9",
+ "plaintext_hex": "101112131415161718191a1b1c1d1e1f",
+ "frame_hex": "00000020cc68d05c59ea8da95b785ebd74e111bb429de328301f91ff7d51f4528742b2c9"
+ }
+ ],
+ "sealed_len": 290,
+ "sealed_sha256": "d2d2299bf84b0ba7848105e1acaa6eb44d25e6a9d76039c8b8bc9fbfa7e1d9ba",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d8420200000020cc68d05c59ea8da95b785ebd74e111bb429de328301f91ff7d51f4528742b2c9"
+ },
+ {
+ "name": "chunk16_2_5_chunks",
+ "description": "Two and a half chunks: two full non-final frames and a short final frame.",
+ "recipient": "server",
+ "kid": "f900b070cdd3a117",
+ "chunk": 16,
+ "plaintext_len": 40,
+ "plaintext_sha256": "5faa4eec3611556812c2d74b437c8c49add3f910f10063d801441f7d75cd5e3b",
+ "plaintext_hex": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f2021222324252627",
+ "header_json": "{\"alg\":\"X25519-HKDF-SHA256-A256GCM\",\"chunk\":16,\"content\":\"tar+zstd\",\"epk\":\"lh+hAw6UWaQ5VwJiBLFNctGutRH8o7ZL0NcQeTG2xTg=\",\"kid\":\"f900b070cdd3a117\",\"salt\":\"GDbVvIt0g0YygJP7/FXZ/AtJnkIIy3FkeZIVDGqbfLw=\",\"v\":1}",
+ "header_len": 206,
+ "header_prefix_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d",
+ "header_hash_hex": "fe23bd3b979fd2064ae227b9ad02c22bb9565d49fe98fe472fdf6c1db4d49aab",
+ "shared_secret_hex": "404fa99af5dad74e51ffef2bb6dff6f5f6d74d390ecd91305de53dad93d5b652",
+ "hkdf_info_hex": "6f6d6e69727573682d7365616c2d7631961fa1030e9459a43957026204b14d72d1aeb511fca3b64bd0d7107931b6c538bbd3dae1750a38dc7a799b6f45e2b3a9f0c017e26c86df8bb4af1c6c3d35c94a",
+ "key_hex": "334d33e71bb8a90317cd15bdbda881c064d64704fc84dda700afa214bd6c6aaa",
+ "frame_count": 3,
+ "frames": [
+ {
+ "index": 0,
+ "final": false,
+ "plaintext_len": 16,
+ "nonce_hex": "000000000000000000000000",
+ "aad_hex": "fe23bd3b979fd2064ae227b9ad02c22bb9565d49fe98fe472fdf6c1db4d49aab000000000000000000",
+ "ciphertext_len": 32,
+ "tag_hex": "8a85e59711e1fd74d768cd9c74d84202",
+ "plaintext_hex": "000102030405060708090a0b0c0d0e0f",
+ "frame_hex": "00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d84202"
+ },
+ {
+ "index": 1,
+ "final": false,
+ "plaintext_len": 16,
+ "nonce_hex": "000000000000000000000001",
+ "aad_hex": "fe23bd3b979fd2064ae227b9ad02c22bb9565d49fe98fe472fdf6c1db4d49aab000000000000000100",
+ "ciphertext_len": 32,
+ "tag_hex": "2a42c84d14a9c585b12186dc719b953d",
+ "plaintext_hex": "101112131415161718191a1b1c1d1e1f",
+ "frame_hex": "00000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d"
+ },
+ {
+ "index": 2,
+ "final": true,
+ "plaintext_len": 8,
+ "nonce_hex": "000000000000000000000002",
+ "aad_hex": "fe23bd3b979fd2064ae227b9ad02c22bb9565d49fe98fe472fdf6c1db4d49aab000000000000000201",
+ "ciphertext_len": 24,
+ "tag_hex": "d137ecb1ec44fed0f6f0bc1a3388e62c",
+ "plaintext_hex": "2021222324252627",
+ "frame_hex": "00000018f7991ef354df03d0d137ecb1ec44fed0f6f0bc1a3388e62c"
+ }
+ ],
+ "sealed_len": 318,
+ "sealed_sha256": "980a36c0eda21eada00f073fa2a003fa4580593463d8a625ab1bc881f52efab4",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d8420200000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d00000018f7991ef354df03d0d137ecb1ec44fed0f6f0bc1a3388e62c"
+ },
+ {
+ "name": "chunk16_previous_key",
+ "description": "Sealed to the previous (rotated-out but still configured) server key; a decoder holding both keys must open it.",
+ "recipient": "previous",
+ "kid": "1f07bfda9740313e",
+ "chunk": 16,
+ "plaintext_len": 7,
+ "plaintext_sha256": "f42546d5ecdd452509808b2d6d0413b5a738c70a793b99ccf8ed6f423aac83d3",
+ "plaintext_hex": "726f7461746564",
+ "header_json": "{\"alg\":\"X25519-HKDF-SHA256-A256GCM\",\"chunk\":16,\"content\":\"tar+zstd\",\"epk\":\"lh+hAw6UWaQ5VwJiBLFNctGutRH8o7ZL0NcQeTG2xTg=\",\"kid\":\"1f07bfda9740313e\",\"salt\":\"GDbVvIt0g0YygJP7/FXZ/AtJnkIIy3FkeZIVDGqbfLw=\",\"v\":1}",
+ "header_len": 206,
+ "header_prefix_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2231663037626664613937343033313365222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d",
+ "header_hash_hex": "5870c60a85cbcf56d03313ff3ce1e4ffd2dc6e59d347f3049364f672c6f6b34b",
+ "shared_secret_hex": "396751f879d4d86d2a1017e4e6b986a7424c2bfdc9846abc24ae35eafce1c003",
+ "hkdf_info_hex": "6f6d6e69727573682d7365616c2d7631961fa1030e9459a43957026204b14d72d1aeb511fca3b64bd0d7107931b6c5384bbce29ba6c1f8781a259a202aac63c4c310c51ba6ca94bedf9190dac5a79a39",
+ "key_hex": "86cf9b95389fee4b022983fb3210203ff54816959f1384f9c75c64dbb1f7a479",
+ "frame_count": 1,
+ "frames": [
+ {
+ "index": 0,
+ "final": true,
+ "plaintext_len": 7,
+ "nonce_hex": "000000000000000000000000",
+ "aad_hex": "5870c60a85cbcf56d03313ff3ce1e4ffd2dc6e59d347f3049364f672c6f6b34b000000000000000001",
+ "ciphertext_len": 23,
+ "tag_hex": "c641ee39d0dea36adff1430984ff2719",
+ "plaintext_hex": "726f7461746564",
+ "frame_hex": "000000177c64f4e72ed465c641ee39d0dea36adff1430984ff2719"
+ }
+ ],
+ "sealed_len": 245,
+ "sealed_sha256": "25d179a64c0c0be2147f45abcdfb71046f0c84d636f0b7d7964cd3d137a8bd1b",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2231663037626664613937343033313365222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d000000177c64f4e72ed465c641ee39d0dea36adff1430984ff2719"
+ },
+ {
+ "name": "real_chunk_5_bytes",
+ "description": "Production header (chunk 1048576) with a five-byte plaintext.",
+ "recipient": "server",
+ "kid": "f900b070cdd3a117",
+ "chunk": 1048576,
+ "plaintext_len": 5,
+ "plaintext_sha256": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824",
+ "plaintext_hex": "68656c6c6f",
+ "header_json": "{\"alg\":\"X25519-HKDF-SHA256-A256GCM\",\"chunk\":1048576,\"content\":\"tar+zstd\",\"epk\":\"lh+hAw6UWaQ5VwJiBLFNctGutRH8o7ZL0NcQeTG2xTg=\",\"kid\":\"f900b070cdd3a117\",\"salt\":\"GDbVvIt0g0YygJP7/FXZ/AtJnkIIy3FkeZIVDGqbfLw=\",\"v\":1}",
+ "header_len": 211,
+ "header_prefix_hex": "4f525345414c3031000000d37b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a313034383537362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d",
+ "header_hash_hex": "e09a5e393f93134d73052f6fd87a6b75aac179a0d529b5938346366f0bb1340d",
+ "shared_secret_hex": "404fa99af5dad74e51ffef2bb6dff6f5f6d74d390ecd91305de53dad93d5b652",
+ "hkdf_info_hex": "6f6d6e69727573682d7365616c2d7631961fa1030e9459a43957026204b14d72d1aeb511fca3b64bd0d7107931b6c538bbd3dae1750a38dc7a799b6f45e2b3a9f0c017e26c86df8bb4af1c6c3d35c94a",
+ "key_hex": "334d33e71bb8a90317cd15bdbda881c064d64704fc84dda700afa214bd6c6aaa",
+ "frame_count": 1,
+ "frames": [
+ {
+ "index": 0,
+ "final": true,
+ "plaintext_len": 5,
+ "nonce_hex": "000000000000000000000000",
+ "aad_hex": "e09a5e393f93134d73052f6fd87a6b75aac179a0d529b5938346366f0bb1340d000000000000000001",
+ "ciphertext_len": 21,
+ "tag_hex": "1670dbc8f5feeb56191468f47bdb4ead",
+ "plaintext_hex": "68656c6c6f",
+ "frame_hex": "00000015cca562626e1670dbc8f5feeb56191468f47bdb4ead"
+ }
+ ],
+ "sealed_len": 248,
+ "sealed_sha256": "5d399a22f9ab33b930a096eb6f73d0e7dea19b9a0f40f687cdff8227183eba53",
+ "sealed_hex": "4f525345414c3031000000d37b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a313034383537362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000015cca562626e1670dbc8f5feeb56191468f47bdb4ead"
+ },
+ {
+ "name": "real_chunk_2_5_chunks",
+ "description": "Production header, 2.5 MiB plaintext (byte i = i mod 251): frames of 1048576, 1048576 and 524288 plaintext bytes. Too large to inline: compare sealed_sha256 and the per-frame digests.",
+ "recipient": "server",
+ "kid": "f900b070cdd3a117",
+ "chunk": 1048576,
+ "plaintext_len": 2621440,
+ "plaintext_sha256": "35aeff7e048974ee23c365c8faf6bcb868ca0529c69309a00f6cde98bfbf89ce",
+ "plaintext_generator": {
+ "kind": "i_mod_251",
+ "length": 2621440,
+ "definition": "plaintext[i] = i % 251 for 0 <= i < length"
+ },
+ "header_json": "{\"alg\":\"X25519-HKDF-SHA256-A256GCM\",\"chunk\":1048576,\"content\":\"tar+zstd\",\"epk\":\"lh+hAw6UWaQ5VwJiBLFNctGutRH8o7ZL0NcQeTG2xTg=\",\"kid\":\"f900b070cdd3a117\",\"salt\":\"GDbVvIt0g0YygJP7/FXZ/AtJnkIIy3FkeZIVDGqbfLw=\",\"v\":1}",
+ "header_len": 211,
+ "header_prefix_hex": "4f525345414c3031000000d37b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a313034383537362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d",
+ "header_hash_hex": "e09a5e393f93134d73052f6fd87a6b75aac179a0d529b5938346366f0bb1340d",
+ "shared_secret_hex": "404fa99af5dad74e51ffef2bb6dff6f5f6d74d390ecd91305de53dad93d5b652",
+ "hkdf_info_hex": "6f6d6e69727573682d7365616c2d7631961fa1030e9459a43957026204b14d72d1aeb511fca3b64bd0d7107931b6c538bbd3dae1750a38dc7a799b6f45e2b3a9f0c017e26c86df8bb4af1c6c3d35c94a",
+ "key_hex": "334d33e71bb8a90317cd15bdbda881c064d64704fc84dda700afa214bd6c6aaa",
+ "frame_count": 3,
+ "frames": [
+ {
+ "index": 0,
+ "final": false,
+ "plaintext_len": 1048576,
+ "nonce_hex": "000000000000000000000000",
+ "aad_hex": "e09a5e393f93134d73052f6fd87a6b75aac179a0d529b5938346366f0bb1340d000000000000000000",
+ "ciphertext_len": 1048592,
+ "tag_hex": "1a47fb60ea4f372b91cce707a334d5df",
+ "ciphertext_sha256": "2b75c3540e91bf7319cb4ba59393f6c542b059d24256e46bb561f1958372d13d",
+ "ciphertext_head_hex": "a4c10c0d05372776de4ce46ebb1515301d149187cbb0bbe44532303ebea7d762"
+ },
+ {
+ "index": 1,
+ "final": false,
+ "plaintext_len": 1048576,
+ "nonce_hex": "000000000000000000000001",
+ "aad_hex": "e09a5e393f93134d73052f6fd87a6b75aac179a0d529b5938346366f0bb1340d000000000000000100",
+ "ciphertext_len": 1048592,
+ "tag_hex": "fe42dd4f7e1b24deaa3247fd913aa8ac",
+ "ciphertext_sha256": "c4e93ddaf88bdb13c35b2aee3a809da348b8714754abc52881b3e40975b6b442",
+ "ciphertext_head_hex": "49ef55d7d4650022deffdb06c95eac0042d695360630722a5986730607363d1d"
+ },
+ {
+ "index": 2,
+ "final": true,
+ "plaintext_len": 524288,
+ "nonce_hex": "000000000000000000000002",
+ "aad_hex": "e09a5e393f93134d73052f6fd87a6b75aac179a0d529b5938346366f0bb1340d000000000000000201",
+ "ciphertext_len": 524304,
+ "tag_hex": "892562f7501a0c30751a73e0200ca52e",
+ "ciphertext_sha256": "5050234ab212da5a25cba7821770922676429778a84c01b6d59f6df1b40b3c76",
+ "ciphertext_head_hex": "f8880de243ce10c10756121a734ede865a48284c49a2444e2e304cb80f243a2f"
+ }
+ ],
+ "sealed_len": 2621723,
+ "sealed_sha256": "0438d2bda205dc7a065514870a5f29570dfd414be3b2e74a5588127e901f0611",
+ "sealed_head_hex": "4f525345414c3031000000d37b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a313034383537362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00100010a4c10c0d05372776de4ce46ebb1515301d149187cbb0bbe44532303ebe",
+ "sealed_tail_hex": "d72fb867cb63f855a518c890d621adbe3b65449ac558d8c423595b04773cc6e7f30bf264796d7cad1520ace6fe980b03892562f7501a0c30751a73e0200ca52e"
+ }
+ ],
+ "negative": [
+ {
+ "name": "flipped_tag",
+ "description": "Last tag byte of frame 0 flipped.",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "tag_mismatch",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d8420300000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d00000018f7991ef354df03d0d137ecb1ec44fed0f6f0bc1a3388e62c"
+ },
+ {
+ "name": "flipped_ciphertext",
+ "description": "First ciphertext byte of frame 1 flipped.",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "tag_mismatch",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d84202000000204c68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d00000018f7991ef354df03d0d137ecb1ec44fed0f6f0bc1a3388e62c"
+ },
+ {
+ "name": "truncated_final_frame_removed",
+ "description": "The final frame is dropped: the stream ends after a full frame sealed as non-final. The decoder opens the last frame as final, fails, retries it as non-final, succeeds, and reports truncation.",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "truncated",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d8420200000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d"
+ },
+ {
+ "name": "truncated_final_frame_partial",
+ "description": "The last 5 bytes of the final frame are cut off.",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "truncated",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d8420200000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d00000018f7991ef354df03d0d137ecb1ec44fed0f6f0bc"
+ },
+ {
+ "name": "truncated_length_prefix",
+ "description": "The stream ends 2 bytes into the final frame's length prefix.",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "truncated",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d8420200000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d0000"
+ },
+ {
+ "name": "header_only",
+ "description": "Magic and header, no frame at all (a final frame is mandatory, even for empty plaintext).",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "truncated",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d"
+ },
+ {
+ "name": "extra_frame_after_final",
+ "description": "A correctly authenticated frame 3 (sealed with the right key, index 3, final=1) appended after the short final frame 2.",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "frame_after_final",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d8420200000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d00000018f7991ef354df03d0d137ecb1ec44fed0f6f0bc1a3388e62c00000015a573f1f6f3b295b2a0559439828207bfdf71c0cd24"
+ },
+ {
+ "name": "extra_frame_after_full_final",
+ "description": "A correctly authenticated frame 1 appended after a full-length final frame 0. The decoder opens frame 0 as non-final (bytes follow), fails, retries it as final, succeeds, and reports frame_after_final.",
+ "base": "chunk16_exactly_1_chunk",
+ "expect_error": "frame_after_final",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb151530e25acef23557a90e1b18bf12820165f600000015b901b63d2c7dc2f534c08811e29a7e7f930105abd5"
+ },
+ {
+ "name": "trailing_garbage",
+ "description": "Three stray bytes after the final frame.",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "frame_after_final",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d8420200000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d00000018f7991ef354df03d0d137ecb1ec44fed0f6f0bc1a3388e62c000001"
+ },
+ {
+ "name": "swapped_frames",
+ "description": "Frames 0 and 1 swapped (both full, non-final).",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "tag_mismatch",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d8420200000018f7991ef354df03d0d137ecb1ec44fed0f6f0bc1a3388e62c"
+ },
+ {
+ "name": "wrong_kid",
+ "description": "A well-formed seal to a key the decoder does not hold (kid 813163b40df6d9d8); rejected before any key agreement.",
+ "expect_error": "unknown_kid",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2238313331363362343064663664396438222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d0000002061085cdbd2e85d87dab7ffdc9c40b74f59cda52c663418242a0011ecf6cc2e13000000202194102b18a10b2abaac49a68eb86005777652b4dd7ed3d1a5803257208d508f000000184d5401f2d60847994ad78462fef9f06875d8e9a3002e03ff"
+ },
+ {
+ "name": "bad_magic",
+ "description": "Magic ORSEAL02 instead of ORSEAL01.",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "bad_magic",
+ "sealed_hex": "4f525345414c3032000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d8420200000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d00000018f7991ef354df03d0d137ecb1ec44fed0f6f0bc1a3388e62c"
+ },
+ {
+ "name": "short_input",
+ "description": "Three bytes: not even a magic.",
+ "expect_error": "bad_magic",
+ "sealed_hex": "4f5253"
+ },
+ {
+ "name": "unsupported_version",
+ "description": "A header with \"v\":2, otherwise consistent.",
+ "expect_error": "unsupported_version",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a327d00000020a4c10c0d05372776de4ce46ebb1515304677ff6b68bc280a5bf7eb124738e80000000020cc68d05c59ea8da95b785ebd74e111bbe6b0d2b16df410fb3dbea052427b3f3f00000018f7991ef354df03d01dc5f64d95192bae7a6f9a9400684c2e"
+ },
+ {
+ "name": "header_extra_key",
+ "description": "The header carries an extra key \"x\"; only the seven v1 keys are allowed.",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "bad_header",
+ "sealed_hex": "4f525345414c3031000000d47b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a312c2278223a317d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d8420200000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d00000018f7991ef354df03d0d137ecb1ec44fed0f6f0bc1a3388e62c"
+ },
+ {
+ "name": "header_wrong_content",
+ "description": "The header says \"content\":\"tar\"; v1 archives are \"tar+zstd\".",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "bad_header",
+ "sealed_hex": "4f525345414c3031000000c97b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a22746172222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d8420200000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d00000018f7991ef354df03d0d137ecb1ec44fed0f6f0bc1a3388e62c"
+ },
+ {
+ "name": "header_chunk_too_small",
+ "description": "The header says \"chunk\":15 (minimum 16).",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "bad_header",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31352c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d8420200000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d00000018f7991ef354df03d0d137ecb1ec44fed0f6f0bc1a3388e62c"
+ },
+ {
+ "name": "header_len_too_large",
+ "description": "header_len 4097 (maximum 4096).",
+ "expect_error": "bad_header",
+ "sealed_hex": "4f525345414c3031000010012020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020202020"
+ },
+ {
+ "name": "low_order_epk",
+ "description": "The epk is the all-zero point, which gives an all-zero X25519 shared secret.",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "bad_header",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a22414141414141414141414141414141414141414141414141414141414141414141414141414141414141413d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000020a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d8420200000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d00000018f7991ef354df03d0d137ecb1ec44fed0f6f0bc1a3388e62c"
+ },
+ {
+ "name": "oversized_frame_length",
+ "description": "Frame 0 length prefix says chunk+17 (33) bytes; the maximum is chunk+16.",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "bad_frame_length",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d00000021a4c10c0d05372776de4ce46ebb1515308a85e59711e1fd74d768cd9c74d842020000000020cc68d05c59ea8da95b785ebd74e111bb2a42c84d14a9c585b12186dc719b953d00000018f7991ef354df03d0d137ecb1ec44fed0f6f0bc1a3388e62c"
+ },
+ {
+ "name": "undersized_frame_length",
+ "description": "Frame 0 length prefix says 15 bytes, shorter than a tag.",
+ "base": "chunk16_2_5_chunks",
+ "expect_error": "bad_frame_length",
+ "sealed_hex": "4f525345414c3031000000ce7b22616c67223a225832353531392d484b44462d5348413235362d4132353647434d222c226368756e6b223a31362c22636f6e74656e74223a227461722b7a737464222c2265706b223a226c682b68417736555761513556774a69424c464e63744775745248386f375a4c304e6351655447327854673d222c226b6964223a2266393030623037306364643361313137222c2273616c74223a22474462567649743067305979674a50372f46585a2f41744a6e6b49497933466b655a495644477162664c773d222c2276223a317d0000000fa4c10c0d05372776de4ce46ebb1515"
+ }
+ ]
+}
diff --git a/apps/server/src/session-archive/detect.test.ts b/apps/server/src/session-archive/detect.test.ts
new file mode 100644
index 00000000..5eeb905e
--- /dev/null
+++ b/apps/server/src/session-archive/detect.test.ts
@@ -0,0 +1,84 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdir, symlink, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { gitMarkerDetector, isArchivableProject, type ProjectMarkerDetector } from "./detect.js";
+import { cleanupTempDirs, tempDir } from "./test-helpers.js";
+
+afterEach(cleanupTempDirs);
+
+describe("project gate", () => {
+ test("a folder with a .git directory is archivable", async () => {
+ const root = await tempDir("gate-dir");
+ await mkdir(join(root, ".git"));
+ expect(await isArchivableProject(root)).toEqual({ archivable: true, reason: "git_dir", marker: ".git" });
+ });
+
+ test("a folder with a .git gitfile (worktree or submodule) is archivable, even when its target is missing", async () => {
+ const root = await tempDir("gate-file");
+ await writeFile(join(root, ".git"), "gitdir: /nowhere/.git/worktrees/feature\n");
+ expect(await isArchivableProject(root)).toEqual({ archivable: true, reason: "git_file", marker: ".git" });
+ });
+
+ test("a folder without .git is not archivable", async () => {
+ const root = await tempDir("gate-none");
+ await writeFile(join(root, "package.json"), "{}");
+ expect(await isArchivableProject(root)).toEqual({ archivable: false, reason: "no_marker", marker: null });
+ });
+
+ test("a .git file that is not a gitfile, or too large, is gitfile_invalid", async () => {
+ const root = await tempDir("gate-invalid");
+ await writeFile(join(root, ".git"), "not a gitfile\n");
+ expect(await isArchivableProject(root)).toEqual({ archivable: false, reason: "gitfile_invalid", marker: null });
+ await writeFile(join(root, ".git"), `gitdir: ${"x".repeat(5000)}\n`);
+ expect((await isArchivableProject(root)).reason).toBe("gitfile_invalid");
+ });
+
+ test("a .git symlink is no marker", async () => {
+ const root = await tempDir("gate-link");
+ const real = await tempDir("gate-link-target");
+ await mkdir(join(real, ".git"));
+ await symlink(join(real, ".git"), join(root, ".git"));
+ expect(await gitMarkerDetector(root)).toBeNull();
+ expect((await isArchivableProject(root)).reason).toBe("no_marker");
+ });
+
+ test("the home directory, filesystem roots and the app's own directories are refused before any detector runs", async () => {
+ let calls = 0;
+ const counting: ProjectMarkerDetector = async () => {
+ calls += 1;
+ return { archivable: true, reason: "git_dir", marker: ".git" };
+ };
+ expect(await isArchivableProject(homedir(), [counting])).toEqual({ archivable: false, reason: "root_too_broad", marker: null });
+ expect((await isArchivableProject("/", [counting])).reason).toBe("root_too_broad");
+ const fakeHome = await tempDir("gate-home");
+ await mkdir(join(fakeHome, ".git"));
+ expect((await isArchivableProject(fakeHome, [gitMarkerDetector], { homeDir: fakeHome })).reason).toBe("root_too_broad");
+ const state = await tempDir("gate-state");
+ await mkdir(join(state, "inner/.git"), { recursive: true });
+ expect((await isArchivableProject(join(state, "inner"), [counting], { appDirs: [state] })).reason).toBe("root_too_broad");
+ expect(calls).toBe(0);
+ });
+
+ test("a root that is not an absolute path to an existing directory is root_not_directory", async () => {
+ const root = await tempDir("gate-notdir");
+ await writeFile(join(root, "file"), "x");
+ await symlink(root, join(root, "link"));
+ expect((await isArchivableProject(join(root, "file"))).reason).toBe("root_not_directory");
+ expect((await isArchivableProject(join(root, "missing"))).reason).toBe("root_not_directory");
+ expect((await isArchivableProject("relative/path")).reason).toBe("root_not_directory");
+ expect((await isArchivableProject(join(root, "link"))).reason).toBe("root_not_directory");
+ });
+
+ test("detectors plug in: the first archivable result wins, else the first non-null one", async () => {
+ const root = await tempDir("gate-plugins");
+ const blend: ProjectMarkerDetector = async () => ({ archivable: true, reason: "blend_file", marker: "*.blend" });
+ const invalid: ProjectMarkerDetector = async () => ({ archivable: false, reason: "gitfile_invalid", marker: null });
+ const broken: ProjectMarkerDetector = async () => {
+ throw new Error("detectors must not throw, but the gate survives it");
+ };
+ expect(await isArchivableProject(root, [broken, invalid, blend])).toEqual({ archivable: true, reason: "blend_file", marker: "*.blend" });
+ expect((await isArchivableProject(root, [invalid, gitMarkerDetector])).reason).toBe("gitfile_invalid");
+ });
+});
diff --git a/apps/server/src/session-archive/detect.ts b/apps/server/src/session-archive/detect.ts
new file mode 100644
index 00000000..f255fe1d
--- /dev/null
+++ b/apps/server/src/session-archive/detect.ts
@@ -0,0 +1,137 @@
+/**
+ * The project gate (section 4): a session is archived only when the folder
+ * the agent started in is a project. v1 recognises one marker, a `.git`
+ * entry; further markers plug in as detectors.
+ */
+import { lstat, open, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+
+export type ArchivableProject = {
+ archivable: boolean;
+ /** git_dir | git_file | no_marker | gitfile_invalid | root_not_directory | root_too_broad */
+ reason: string;
+ /** The marker that qualified the root (".git"), null when not archivable. */
+ marker: string | null;
+};
+
+/** Looks at the root itself only (never walks the tree); null when its marker is absent. Never throws. */
+export type ProjectMarkerDetector = (root: string) => Promise<ArchivableProject | null>;
+
+const MAX_GITFILE_BYTES = 4096;
+
+async function readSmallFile(path: string, maxBytes: number): Promise<Buffer | null> {
+ let handle: Awaited<ReturnType<typeof open>> | null = null;
+ try {
+ handle = await open(path, "r");
+ const buffer = Buffer.alloc(maxBytes);
+ let length = 0;
+ while (length < maxBytes) {
+ const { bytesRead } = await handle.read(buffer, length, maxBytes - length, length);
+ if (bytesRead === 0) break;
+ length += bytesRead;
+ }
+ return buffer.subarray(0, length);
+ } catch {
+ return null;
+ } finally {
+ await handle?.close().catch(() => undefined);
+ }
+}
+
+/** `.git` as a directory, or as a worktree/submodule gitfile (`gitdir: ...`). */
+export const gitMarkerDetector: ProjectMarkerDetector = async (root) => {
+ try {
+ const marker = join(root, ".git");
+ const stats = await lstat(marker);
+ if (stats.isDirectory()) return { archivable: true, reason: "git_dir", marker: ".git" };
+ if (!stats.isFile()) return null;
+ const invalid: ArchivableProject = { archivable: false, reason: "gitfile_invalid", marker: null };
+ if (stats.size > MAX_GITFILE_BYTES) return invalid;
+ const content = await readSmallFile(marker, MAX_GITFILE_BYTES);
+ if (!content) return null;
+ const firstLine = content.toString("utf8").split(/\r?\n/, 1)[0] ?? "";
+ return /^gitdir: .+/.test(firstLine) ? { archivable: true, reason: "git_file", marker: ".git" } : invalid;
+ } catch {
+ return null;
+ }
+};
+
+export type ProjectGateOptions = {
+ /** The desktop's own state, temp and data directories; a root equal to or inside one is refused. */
+ appDirs?: readonly string[];
+ /** Tests only; defaults to os.homedir(). */
+ homeDir?: string;
+};
+
+async function pathForms(path: string): Promise<string[]> {
+ const forms = [resolve(path)];
+ try {
+ const real = await realpath(path);
+ if (!forms.includes(real)) forms.push(real);
+ } catch {
+ // A directory that does not exist yet is compared by its resolved form only.
+ }
+ return forms;
+}
+
+function isSameOrInside(child: string, parent: string): boolean {
+ const rel = relative(parent, child);
+ return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+function samePath(left: string, right: string): boolean {
+ return relative(left, right) === "";
+}
+
+function isFilesystemRoot(path: string): boolean {
+ if (parse(path).root === path) return true;
+ // macOS volume mount points: /Volumes and /Volumes/<name>.
+ return /^\/Volumes(?:\/[^/]+)?\/?$/.test(path);
+}
+
+/** Why a root may never be archived even with a marker (section 4.3), or null when it may. */
+async function refusedRoot(root: string, options: ProjectGateOptions): Promise<string | null> {
+ if (!isAbsolute(root)) return "root_not_directory";
+ try {
+ if (!(await lstat(root)).isDirectory()) return "root_not_directory";
+ } catch {
+ return "root_not_directory";
+ }
+ const roots = await pathForms(root);
+ const homes = await pathForms(options.homeDir ?? homedir());
+ const appDirs = (await Promise.all((options.appDirs ?? []).map(pathForms))).flat();
+ for (const candidate of roots) {
+ if (isFilesystemRoot(candidate)) return "root_too_broad";
+ if (homes.some((home) => samePath(candidate, home))) return "root_too_broad";
+ if (appDirs.some((dir) => isSameOrInside(candidate, dir))) return "root_too_broad";
+ }
+ return null;
+}
+
+/**
+ * Whether the session root is a project to archive: the root checks first,
+ * then the detectors in order; the first archivable result wins, else the
+ * first non-null one, else no_marker.
+ */
+export async function isArchivableProject(
+ root: string,
+ detectors: readonly ProjectMarkerDetector[] = [gitMarkerDetector],
+ options: ProjectGateOptions = {},
+): Promise<ArchivableProject> {
+ const refused = await refusedRoot(root, options);
+ if (refused) return { archivable: false, reason: refused, marker: null };
+ let first: ArchivableProject | null = null;
+ for (const detector of detectors) {
+ let result: ArchivableProject | null = null;
+ try {
+ result = await detector(root);
+ } catch {
+ result = null;
+ }
+ if (!result) continue;
+ if (result.archivable) return result;
+ first ??= result;
+ }
+ return first ?? { archivable: false, reason: "no_marker", marker: null };
+}
diff --git a/apps/server/src/session-archive/fake-archive-server.ts b/apps/server/src/session-archive/fake-archive-server.ts
new file mode 100644
index 00000000..2fa09c73
--- /dev/null
+++ b/apps/server/src/session-archive/fake-archive-server.ts
@@ -0,0 +1,291 @@
+/**
+ * Test double for the omnirush.ai archive routes and S3 multipart uploads,
+ * served through an injectable `fetch` (no sockets). It follows sections 7.2
+ * to 7.7 closely enough for the client's behaviour to be checked: auth,
+ * consent, replay and restart semantics, presigned URL expiry, NoSuchUpload,
+ * part listing and completion checks.
+ */
+import { createHash, randomUUID } from "node:crypto";
+
+import { testKeys } from "./test-helpers.js";
+
+type Part = { etag: string; bytes: Buffer };
+
+export type FakeArchive = {
+ request: Record<string, unknown> & { archive_id: string; session_id: string; sequence: number; turn: number; size: number; kind: string; parent_archive_id: string | null };
+ status: "uploading" | "uploaded" | "aborted" | "failed";
+ uploadId: string;
+ partSize: number;
+ partCount: number;
+ /** Parts S3 holds for the current multipart upload; null once S3 forgot the upload (NoSuchUpload). */
+ parts: Map<number, Part> | null;
+ object: Buffer | null;
+};
+
+export type FakeCall = { method: string; path: string; status: number; body?: unknown };
+
+type Hook = (call: { method: string; path: string; body: unknown }) => Response | "network" | undefined;
+type PutHook = (put: { archiveId: string; partNumber: number; attempt: number }) => Response | "network" | undefined;
+
+function json(status: number, body: unknown): Response {
+ return new Response(JSON.stringify(body), { status, headers: { "Content-Type": "application/json" } });
+}
+
+export class FakeArchiveServer {
+ readonly gatewayUrl = "https://api.omnirush.test/omnirush/v1";
+ private readonly apiRoot = "https://api.omnirush.test/omnirush/";
+ private readonly s3Root = "https://bucket.s3.test/";
+ token = "token-1";
+ partSize = 1024;
+ /** When set, every route but abort answers with this (428 archive_consent_required, 503 archive_disabled). */
+ gate: { status: number; detail: string } | null = null;
+ readonly archives = new Map<string, FakeArchive>();
+ readonly calls: FakeCall[] = [];
+ readonly puts: Array<{ archiveId: string; partNumber: number; status: number }> = [];
+ /** Presigned URLs issued before this counter are expired. */
+ private urlGeneration = 0;
+ private expiredBefore = 0;
+ apiHook: Hook | null = null;
+ putHook: PutHook | null = null;
+ private readonly putAttempts = new Map<string, number>();
+
+ /** The injectable fetch: routes API and S3 URLs to the fakes. */
+ readonly respond = async (input: string, init?: RequestInit): Promise<Response> => {
+ const method = init?.method ?? "GET";
+ if (input.startsWith(this.s3Root)) return this.s3(input, init);
+ if (!input.startsWith(this.apiRoot)) throw new TypeError(`unexpected URL in fake fetch: ${input}`);
+ const path = input.slice(this.apiRoot.length);
+ const bodyText = typeof init?.body === "string" ? init.body : undefined;
+ const body: unknown = bodyText ? JSON.parse(bodyText) : undefined;
+ const hooked = this.apiHook?.({ method, path, body });
+ if (hooked === "network") throw new TypeError("fetch failed");
+ const response = hooked ?? this.api(method, path, body, new Headers(init?.headers).get("authorization"));
+ this.calls.push({ method, path, status: response.status, body });
+ return response;
+ };
+
+ /** Presigned URLs issued so far stop working (403), as after their hour or a role session expiry. */
+ expireUrls(): void {
+ this.expiredBefore = this.urlGeneration;
+ }
+
+ /** S3 forgets the multipart upload (maintenance abort, lifecycle rule): NoSuchUpload from now on. */
+ forgetUpload(archiveId: string): void {
+ const archive = this.archives.get(archiveId);
+ if (archive) archive.parts = null;
+ }
+
+ callPaths(): string[] {
+ return this.calls.map((call) => `${call.method} ${call.path} ${call.status}`);
+ }
+
+ objects(): FakeArchive[] {
+ return [...this.archives.values()].filter((archive) => archive.status === "uploaded").sort((left, right) => left.request.sequence - right.request.sequence);
+ }
+
+ private presign(archive: FakeArchive, partNumber: number): string {
+ const generation = this.urlGeneration;
+ this.urlGeneration += 1;
+ return `${this.s3Root}v1/${archive.request.archive_id}.orseal?uploadId=${archive.uploadId}&partNumber=${partNumber}&X-Amz-Signature=${generation}`;
+ }
+
+ private urls(archive: FakeArchive, numbers: number[]) {
+ return numbers.map((partNumber) => ({ part_number: partNumber, url: this.presign(archive, partNumber) }));
+ }
+
+ private startUpload(archive: FakeArchive): void {
+ archive.uploadId = randomUUID();
+ archive.parts = new Map();
+ archive.status = "uploading";
+ archive.object = null;
+ }
+
+ private createdBody(archive: FakeArchive) {
+ return {
+ archive_id: archive.request.archive_id,
+ status: archive.status,
+ upload_id: archive.uploadId,
+ object_key: `v1/users/u/sessions/${archive.request.session_id}/archives/${String(archive.request.sequence).padStart(6, "0")}-${archive.request.kind}-${archive.request.archive_id}.orseal`,
+ part_size: archive.partSize,
+ part_count: archive.partCount,
+ parts: this.urls(archive, Array.from({ length: Math.min(100, archive.partCount) }, (_, index) => index + 1)),
+ expires_at: new Date(Date.now() + 3_600_000).toISOString(),
+ };
+ }
+
+ private api(method: string, path: string, body: unknown, authorization: string | null): Response {
+ if (authorization !== `Bearer ${this.token}`) return json(401, { detail: "invalid_token" });
+ const abort = /^archives\/([^/]+)\/abort$/.exec(path);
+ if (this.gate && !abort) return json(this.gate.status, { detail: this.gate.detail });
+ if (method === "GET" && path === "archives/key") return json(200, { kid: testKeys.kid, public_key: testKeys.publicB64, alg: "X25519-HKDF-SHA256-A256GCM" });
+ if (method === "POST" && path === "archives") return this.create(body);
+ const parts = /^archives\/([^/]+)\/parts$/.exec(path);
+ if (method === "POST" && parts) return this.listParts(parts[1]!, body);
+ const complete = /^archives\/([^/]+)\/complete$/.exec(path);
+ if (method === "POST" && complete) return this.complete(complete[1]!, body);
+ if (method === "POST" && abort) {
+ const archive = this.archives.get(abort[1]!);
+ if (!archive) return json(404, { detail: "archive_not_found" });
+ if (archive.status === "uploaded") return json(409, { detail: "archive_already_uploaded" });
+ archive.status = "aborted";
+ archive.parts = null;
+ return json(200, { archive_id: abort[1], status: "aborted" });
+ }
+ return json(404, { detail: "not_found" });
+ }
+
+ private create(body: unknown): Response {
+ if (typeof body !== "object" || body === null) return json(422, { detail: [] });
+ const request = Object.fromEntries(Object.entries(body));
+ const { archive_id: archiveId, session_id: sessionId, sequence, turn, size, kind, parent_archive_id: parentId, kid } = request;
+ if (typeof archiveId !== "string" || typeof sessionId !== "string" || typeof sequence !== "number" || typeof turn !== "number"
+ || typeof size !== "number" || size < 1 || (kind !== "base" && kind !== "delta") || (parentId !== null && typeof parentId !== "string")) {
+ return json(422, { detail: [] });
+ }
+ if (kind === "base" && (sequence !== 0 || parentId !== null)) return json(422, { detail: [] });
+ if (kid !== testKeys.kid) return json(409, { detail: "archive_kid_unknown" });
+ const existing = this.archives.get(archiveId);
+ if (existing) {
+ if (JSON.stringify(existing.request) !== JSON.stringify(request)) return json(409, { detail: "archive_id_conflict" });
+ if (existing.status === "uploaded") return json(200, { archive_id: archiveId, status: "uploaded", parts: [] });
+ if (existing.status === "aborted" || existing.status === "failed") {
+ this.startUpload(existing);
+ return json(201, this.createdBody(existing));
+ }
+ return json(200, this.createdBody(existing));
+ }
+ for (const archive of this.archives.values()) {
+ if (archive.request.session_id === sessionId && archive.request.sequence === sequence) return json(409, { detail: "archive_sequence_conflict" });
+ }
+ if (kind === "delta") {
+ const parent = parentId ? this.archives.get(parentId) : undefined;
+ if (!parent || parent.status !== "uploaded" || parent.request.sequence !== sequence - 1 || parent.request.session_id !== sessionId || turn <= parent.request.turn) {
+ return json(409, { detail: "archive_parent_mismatch" });
+ }
+ }
+ const partSize = this.partSize;
+ const archive: FakeArchive = {
+ request: { ...request, archive_id: archiveId, session_id: sessionId, sequence, turn, size, kind, parent_archive_id: parentId },
+ status: "uploading",
+ uploadId: "",
+ partSize,
+ partCount: Math.ceil(size / partSize),
+ parts: null,
+ object: null,
+ };
+ this.startUpload(archive);
+ this.archives.set(archiveId, archive);
+ return json(201, this.createdBody(archive));
+ }
+
+ private listParts(archiveId: string, body: unknown): Response {
+ const archive = this.archives.get(archiveId);
+ if (!archive) return json(404, { detail: "archive_not_found" });
+ if (archive.status !== "uploading" || !archive.parts) {
+ if (archive.status === "uploading") archive.status = "aborted";
+ return json(409, { detail: "archive_not_uploading" });
+ }
+ const numbers = typeof body === "object" && body !== null && "part_numbers" in body && Array.isArray(body.part_numbers) ? body.part_numbers.filter((value): value is number => typeof value === "number") : [];
+ return json(200, {
+ archive_id: archiveId,
+ parts: this.urls(archive, numbers),
+ uploaded: [...archive.parts.entries()].sort(([left], [right]) => left - right).map(([partNumber, part]) => ({ part_number: partNumber, etag: part.etag, size: part.bytes.length })),
+ expires_at: new Date(Date.now() + 3_600_000).toISOString(),
+ });
+ }
+
+ private complete(archiveId: string, body: unknown): Response {
+ const archive = this.archives.get(archiveId);
+ if (!archive) return json(404, { detail: "archive_not_found" });
+ if (archive.status === "uploaded") return json(200, { archive_id: archiveId, status: "uploaded", size: archive.request.size });
+ if (archive.status !== "uploading" || !archive.parts) {
+ if (archive.status === "uploading") archive.status = "aborted";
+ return json(409, { detail: "archive_not_uploading" });
+ }
+ const listed = typeof body === "object" && body !== null && "parts" in body && Array.isArray(body.parts) ? body.parts : [];
+ if (listed.length !== archive.partCount) return json(422, { detail: [] });
+ const pieces: Buffer[] = [];
+ for (let partNumber = 1; partNumber <= archive.partCount; partNumber += 1) {
+ const claimed = listed.find((item: unknown) => typeof item === "object" && item !== null && "part_number" in item && item.part_number === partNumber);
+ const held = archive.parts.get(partNumber);
+ if (!held || typeof claimed !== "object" || claimed === null || !("etag" in claimed) || claimed.etag !== held.etag) return json(409, { detail: "archive_parts_invalid" });
+ pieces.push(held.bytes);
+ }
+ const object = Buffer.concat(pieces);
+ if (object.length !== archive.request.size) {
+ archive.status = "failed";
+ return json(409, { detail: "archive_size_mismatch" });
+ }
+ archive.object = object;
+ archive.status = "uploaded";
+ return json(200, { archive_id: archiveId, status: "uploaded", size: object.length, completed_at: new Date().toISOString() });
+ }
+
+ private async s3(input: string, init?: RequestInit): Promise<Response> {
+ const url = new URL(input);
+ const archiveId = url.pathname.replace(/^\/v1\//, "").replace(/\.orseal$/, "");
+ const partNumber = Number(url.searchParams.get("partNumber"));
+ const key = `${archiveId}:${partNumber}`;
+ const attempt = (this.putAttempts.get(key) ?? 0) + 1;
+ this.putAttempts.set(key, attempt);
+ const record = (status: number) => this.puts.push({ archiveId, partNumber, status });
+ const hooked = this.putHook?.({ archiveId, partNumber, attempt });
+ if (hooked === "network") {
+ record(0);
+ throw new TypeError("fetch failed");
+ }
+ if (hooked) {
+ record(hooked.status);
+ return hooked;
+ }
+ if (init?.method !== "PUT") return new Response("", { status: 405 });
+ const archive = this.archives.get(archiveId);
+ if (Number(url.searchParams.get("X-Amz-Signature")) < this.expiredBefore) {
+ record(403);
+ return new Response("<Error><Code>AccessDenied</Code></Error>", { status: 403 });
+ }
+ if (!archive || !archive.parts || url.searchParams.get("uploadId") !== archive.uploadId) {
+ record(404);
+ return new Response("<Error><Code>NoSuchUpload</Code></Error>", { status: 404 });
+ }
+ const bytes = Buffer.from(await new Response(init.body ?? null).arrayBuffer());
+ const etag = `"${createHash("md5").update(bytes).digest("hex")}"`;
+ archive.parts.set(partNumber, { etag, bytes });
+ record(200);
+ return new Response(null, { status: 200, headers: { ETag: etag } });
+ }
+}
+
+/**
+ * A slow link for part 2 of every upload: its PUT would take 30 s. Records
+ * each such PUT (its body size, and how long after `markCommand()` its
+ * signal aborted); part 1 and the API go straight to the fake server.
+ */
+export function slowPartTwo(server: FakeArchiveServer) {
+ let started!: () => void;
+ const state = {
+ started: new Promise<void>((resolvePromise) => { started = resolvePromise; }),
+ commandAt: 0,
+ puts: [] as Array<{ part: number; bytes: number | null; abortedAfterMs: number | null; completed: boolean }>,
+ markCommand: () => { state.commandAt = Date.now(); },
+ fetch: async (input: string, init?: RequestInit): Promise<Response> => {
+ const part = input.startsWith("https://bucket.s3.test/") ? Number(new URL(input).searchParams.get("partNumber")) : 0;
+ if (part !== 2) return server.respond(input, init);
+ const entry = { part, bytes: init?.body instanceof Uint8Array ? init.body.byteLength : null, abortedAfterMs: null as number | null, completed: false };
+ state.puts.push(entry);
+ started();
+ return new Promise<Response>((resolvePromise, reject) => {
+ const timer = setTimeout(() => {
+ entry.completed = true;
+ resolvePromise(server.respond(input, init));
+ }, 30_000);
+ init?.signal?.addEventListener("abort", () => {
+ clearTimeout(timer);
+ entry.abortedAfterMs = Date.now() - state.commandAt;
+ reject(init.signal!.reason);
+ }, { once: true });
+ });
+ },
+ };
+ return state;
+}
diff --git a/apps/server/src/session-archive/files.ts b/apps/server/src/session-archive/files.ts
new file mode 100644
index 00000000..681e6905
--- /dev/null
+++ b/apps/server/src/session-archive/files.ts
@@ -0,0 +1,85 @@
+/** Durable state files for the archiver: every write goes to a temp name, is fsynced, then renamed. */
+import { createHash, randomBytes } from "node:crypto";
+import { open, readFile, rename, rm } from "node:fs/promises";
+
+/** The first 32 hex characters of SHA-256(text): state file names for session ids and root paths. */
+export function stateKey(text: string): string {
+ return createHash("sha256").update(text, "utf8").digest("hex").slice(0, 32);
+}
+
+type WritableHandle = { write(buffer: Buffer, offset: number, length: number): Promise<{ bytesWritten: number }> };
+
+async function writeAll(handle: WritableHandle, text: string): Promise<void> {
+ const bytes = Buffer.from(text, "utf8");
+ let offset = 0;
+ while (offset < bytes.length) {
+ const { bytesWritten } = await handle.write(bytes, offset, bytes.length - offset);
+ offset += bytesWritten;
+ }
+}
+
+/** Writes text pieces to `path` atomically; large documents never become one string. */
+export async function writeChunksAtomic(path: string, chunks: Iterable<string>): Promise<void> {
+ const temp = `${path}.${randomBytes(6).toString("hex")}.tmp`;
+ const handle = await open(temp, "wx", 0o600);
+ try {
+ let pending: string[] = [];
+ let pendingLength = 0;
+ for (const chunk of chunks) {
+ pending.push(chunk);
+ pendingLength += chunk.length;
+ if (pendingLength >= 1 << 20) {
+ await writeAll(handle, pending.join(""));
+ pending = [];
+ pendingLength = 0;
+ }
+ }
+ if (pending.length > 0) await writeAll(handle, pending.join(""));
+ await handle.sync();
+ } catch (error) {
+ await handle.close().catch(() => undefined);
+ await rm(temp, { force: true });
+ throw error;
+ }
+ await handle.close();
+ try {
+ await rename(temp, path);
+ } catch (error) {
+ await rm(temp, { force: true });
+ throw error;
+ }
+}
+
+export function writeJsonAtomic(path: string, value: unknown): Promise<void> {
+ return writeChunksAtomic(path, [`${JSON.stringify(value)}\n`]);
+}
+
+/** Parsed JSON, or null when the file is missing or not JSON. */
+export async function readJsonFile(path: string): Promise<unknown> {
+ let text: string;
+ try {
+ text = await readFile(path, "utf8");
+ } catch {
+ return null;
+ }
+ try {
+ return JSON.parse(text);
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * Runs a full garbage collection when the runtime offers one (Bun.gc); a
+ * no-op elsewhere. Streaming an archive churns through hundreds of MiB of
+ * short-lived buffers (zstd output, AES-GCM output) that the collector would
+ * otherwise let pile up well past the stream's bounded working set. Callers
+ * hint once per 64 MiB of data; a collection takes a few milliseconds at the
+ * heap sizes involved.
+ */
+export function hintGarbageCollection(): void {
+ const runtime: unknown = Reflect.get(globalThis, "Bun");
+ if (typeof runtime !== "object" || runtime === null) return;
+ const gc: unknown = Reflect.get(runtime, "gc");
+ if (typeof gc === "function") Reflect.apply(gc, runtime, [true]);
+}
diff --git a/apps/server/src/session-archive/index.test.ts b/apps/server/src/session-archive/index.test.ts
new file mode 100644
index 00000000..5dff6b68
--- /dev/null
+++ b/apps/server/src/session-archive/index.test.ts
@@ -0,0 +1,343 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { execFile } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { promisify } from "node:util";
+
+import { FakeArchiveServer, slowPartTwo } from "./fake-archive-server.js";
+import { ARCHIVE_STATE_DIRECTORY, SessionArchiver, type SessionArchiverOptions } from "./index.js";
+import { cleanupTempDirs, manifestOf, openArchive, tempDir } from "./test-helpers.js";
+
+const execFileAsync = promisify(execFile);
+
+afterEach(cleanupTempDirs);
+
+async function git(root: string, ...args: string[]): Promise<string> {
+ const { stdout } = await execFileAsync("git", ["-C", root, "-c", "user.name=t", "-c", "[email protected]", "-c", "commit.gpgsign=false", ...args]);
+ return stdout.trim();
+}
+
+function archiver(server: FakeArchiveServer, stateDir: string, options: Partial<SessionArchiverOptions> = {}) {
+ return new SessionArchiver({
+ gatewayUrl: server.gatewayUrl,
+ accessToken: server.token,
+ fetch: server.respond,
+ stateDir,
+ retry: { baseMs: 1, maxMs: 2, attempts: 2 },
+ ...options,
+ });
+}
+
+const sha256 = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex");
+
+/** A git project with ignored dependencies and build output, a binary asset and two credential files. */
+async function project(): Promise<{ root: string; blend: Buffer; head: string }> {
+ const root = await tempDir("project");
+ await git(root, "init", "-q", "-b", "main");
+ await mkdir(join(root, "src"));
+ await writeFile(join(root, "src/app.ts"), "export const app = 1;\n");
+ await writeFile(join(root, ".gitignore"), "node_modules/\ndist/\n");
+ await mkdir(join(root, "node_modules/left-pad"), { recursive: true });
+ await writeFile(join(root, "node_modules/left-pad/index.js"), "module.exports = (s) => s;\n");
+ await mkdir(join(root, "dist"));
+ await writeFile(join(root, "dist/bundle.js"), "console.log(1);\n");
+ await mkdir(join(root, "assets"));
+ const blend = randomBytes(300 * 1024);
+ await writeFile(join(root, "assets/scene.blend"), blend);
+ await writeFile(join(root, ".env"), "API_KEY=sk-live-1234567890\n");
+ await writeFile(join(root, "id_rsa"), "-----BEGIN OPENSSH PRIVATE KEY-----\n");
+ await git(root, "add", "src", ".gitignore", "assets");
+ await git(root, "commit", "-q", "-m", "initial");
+ await git(root, "branch", "token-fix");
+ await git(root, "remote", "add", "origin", "https://user:[email protected]/acme/app.git");
+ return { root, blend, head: await git(root, "rev-parse", "HEAD") };
+}
+
+describe("SessionArchiver", () => {
+ test("whole folder: base with .git and ignored content, credentials left out, then a delta after a change", async () => {
+ const server = new FakeArchiveServer();
+ const { root, blend, head } = await project();
+ const state = await tempDir("state");
+ const logs: string[] = [];
+ const subject = archiver(server, state, { log: (_level, message) => logs.push(message) });
+
+ const base = await subject.captureBase("ses_whole_folder", root);
+ expect(base).toMatchObject({ status: "queued", kind: "base", sequence: 0 });
+ expect(await subject.drain()).toEqual({ uploaded: 1, pending: 0, dropped: 0, blocked: null, disabled: false });
+
+ const [first] = server.objects();
+ expect(first!.request).toMatchObject({ session_id: "ses_whole_folder", kind: "base", sequence: 0, turn: 0, parent_archive_id: null, marker: ".git", content: "tar+zstd", kid: "f900b070cdd3a117" });
+ expect(first!.request.size).toBe(first!.object!.length);
+ expect(first!.request.sha256).toBe(sha256(first!.object!));
+ const members = await openArchive(first!.object!);
+ const names = members.map((member) => member.name);
+ for (const present of [".git/HEAD", ".git/config", ".git/refs/heads/main", ".git/refs/heads/token-fix", "node_modules/left-pad/index.js", "dist/bundle.js", "assets/scene.blend", "src/app.ts", ".gitignore"]) {
+ expect(names).toContain(present);
+ }
+ expect(names).not.toContain(".env");
+ expect(names).not.toContain("id_rsa");
+ expect(members.find((member) => member.name === "assets/scene.blend")!.content.equals(blend)).toBe(true);
+ const manifest = manifestOf(members);
+ expect(manifest).toMatchObject({
+ schema: "omnirush.archive.v1",
+ kind: "base",
+ archive_id: base.status === "queued" ? base.archiveId : "",
+ session_id: "ses_whole_folder",
+ sequence: 0,
+ turn: 0,
+ parent_archive_id: null,
+ workspace: { label: basename(root), marker: ".git", git: { head, branch: "main", remote: "https://github.com/acme/app.git", dirty: true } },
+ excluded: { credential: 2, special: 0, app_state: 0, reserved: 0, unreadable: 0, non_utf8: 0 },
+ });
+ expect("deleted" in manifest).toBe(false);
+ expect(Array.isArray(manifest.files) ? manifest.files.length : -1).toBe(members.length - 1);
+
+ // A turn edits, adds, deletes and commits.
+ await writeFile(join(root, "src/app.ts"), "export const app = 2;\n");
+ await writeFile(join(root, "src/new.ts"), "export const added = true;\n");
+ await rm(join(root, "dist/bundle.js"));
+ await git(root, "add", "src");
+ await git(root, "commit", "-q", "-m", "turn one");
+ const delta = await subject.captureDelta("ses_whole_folder", root, 1);
+ expect(delta).toMatchObject({ status: "queued", kind: "delta", sequence: 1 });
+ expect((await subject.drain()).uploaded).toBe(1);
+ const second = server.objects()[1]!;
+ expect(second.request).toMatchObject({ kind: "delta", sequence: 1, turn: 1, parent_archive_id: first!.request.archive_id });
+ const deltaMembers = await openArchive(second.object!);
+ const deltaManifest = manifestOf(deltaMembers);
+ expect(deltaManifest).toMatchObject({ kind: "delta", sequence: 1, turn: 1, parent_archive_id: first!.request.archive_id, deleted: ["dist/bundle.js"] });
+ const changed = deltaMembers.slice(1).map((member) => member.name);
+ expect(changed).toEqual(expect.arrayContaining(["src/app.ts", "src/new.ts", ".git/refs/heads/main", ".git/index"]));
+ expect(changed).not.toContain("node_modules/left-pad/index.js");
+ expect(changed).not.toContain("assets/scene.blend");
+ expect(deltaMembers.find((member) => member.name === "src/app.ts")!.content.toString()).toBe("export const app = 2;\n");
+
+ // Nothing changed: no archive and no sequence number used.
+ expect(await subject.captureDelta("ses_whole_folder", root, 2)).toEqual({ status: "skipped", reason: "unchanged" });
+ expect(await subject.captureDelta("ses_whole_folder", root, 1)).toEqual({ status: "skipped", reason: "stale_turn" });
+ expect(await subject.captureBase("ses_whole_folder", root)).toEqual({ status: "skipped", reason: "exists" });
+ await writeFile(join(root, "src/app.ts"), "export const app = 3;\n");
+ expect(await subject.captureDelta("ses_whole_folder", root, 3)).toMatchObject({ status: "queued", sequence: 2 });
+ expect((await subject.drain()).uploaded).toBe(1);
+ expect(server.objects().map((archive) => archive.request.sequence)).toEqual([0, 1, 2]);
+ // Nothing is left behind in the state dir once uploaded.
+ const archiveDir = join(state, ARCHIVE_STATE_DIRECTORY);
+ expect(await readdir(join(archiveDir, "pending"))).toEqual([]);
+ expect(await readdir(join(archiveDir, "queue"))).toEqual([]);
+ expect(await readdir(join(archiveDir, "tmp"))).toEqual([]);
+ expect(await readdir(join(archiveDir, "baselines"))).toHaveLength(1);
+ expect(logs.join("\n")).not.toContain("X-Amz-Signature");
+ });
+
+ test("archiveIncludeCredentialFiles keeps .env and id_rsa", async () => {
+ const server = new FakeArchiveServer();
+ const { root } = await project();
+ const subject = archiver(server, await tempDir("state"), { archiveIncludeCredentialFiles: true });
+ expect((await subject.captureBase("ses_with_credentials", root)).status).toBe("queued");
+ await subject.drain();
+ const names = (await openArchive(server.objects()[0]!.object!)).map((member) => member.name);
+ expect(names).toEqual(expect.arrayContaining([".env", "id_rsa"]));
+ });
+
+ test("a folder without .git is not archived and nothing is sent", async () => {
+ const server = new FakeArchiveServer();
+ const root = await tempDir("plain");
+ await writeFile(join(root, "notes.md"), "hello");
+ const subject = archiver(server, await tempDir("state"));
+ expect(await subject.captureBase("ses_plain_folder", root)).toEqual({ status: "skipped", reason: "not_archivable" });
+ expect(await subject.captureDelta("ses_plain_folder", root, 1)).toEqual({ status: "skipped", reason: "no_base" });
+ expect(server.calls).toEqual([]);
+ });
+
+ test("428 at /archives/key: nothing is packed, archiving stays off until a later captureBase succeeds", async () => {
+ const server = new FakeArchiveServer();
+ server.gate = { status: 428, detail: "archive_consent_required" };
+ const { root } = await project();
+ const state = await tempDir("state");
+ const subject = archiver(server, state);
+ expect(await subject.captureBase("ses_no_consent", root)).toEqual({ status: "skipped", reason: "disabled" });
+ expect(await subject.captureDelta("ses_no_consent", root, 1)).toEqual({ status: "skipped", reason: "disabled" });
+ expect(await readdir(join(state, ARCHIVE_STATE_DIRECTORY, "pending"))).toEqual([]);
+ expect(server.calls.map((call) => call.path)).toEqual(["archives/key"]);
+ server.gate = null;
+ expect((await subject.captureBase("ses_consented_now", root)).status).toBe("queued");
+ });
+
+ test("428 during a drain drops every queued archive and stops the sessions that lost one", async () => {
+ const server = new FakeArchiveServer();
+ const { root } = await project();
+ const state = await tempDir("state");
+ const subject = archiver(server, state);
+ expect((await subject.captureBase("ses_withdrawn", root)).status).toBe("queued");
+ server.gate = { status: 428, detail: "archive_consent_required" };
+ expect(await subject.drain()).toEqual({ uploaded: 0, pending: 0, dropped: 1, blocked: null, disabled: true });
+ expect(await readdir(join(state, ARCHIVE_STATE_DIRECTORY, "pending"))).toEqual([]);
+ server.gate = null;
+ await writeFile(join(root, "src/app.ts"), "changed");
+ expect(await subject.captureDelta("ses_withdrawn", root, 1)).toEqual({ status: "skipped", reason: "disabled" });
+ // A new session re-checks consent and starts over with a new base; the old chain stays stopped.
+ expect((await subject.captureBase("ses_after_consent", root)).status).toBe("queued");
+ expect(await subject.captureDelta("ses_withdrawn", root, 2)).toEqual({ status: "skipped", reason: "stopped" });
+ });
+
+ test("app start resumes queued and half-uploaded archives from the state dir", async () => {
+ const server = new FakeArchiveServer();
+ const { root } = await project();
+ const state = await tempDir("state");
+ const first = archiver(server, state);
+ expect((await first.captureBase("ses_resumed_upload", root)).status).toBe("queued");
+ let failing = true;
+ server.putHook = ({ partNumber }) => (failing && partNumber === 3 ? "network" : undefined);
+ const interrupted = await first.drain();
+ expect(interrupted).toMatchObject({ uploaded: 0, pending: 1 });
+ await first.stop();
+ const sentBefore = server.puts.filter((put) => put.status === 200).map((put) => put.partNumber);
+ expect(sentBefore).toEqual([1, 2]);
+
+ // Leftovers of a crash: a partial capture and an orphan sealed file.
+ const archiveDir = join(state, ARCHIVE_STATE_DIRECTORY);
+ await writeFile(join(archiveDir, "tmp", "dead.partial"), "x");
+ await writeFile(join(archiveDir, "pending", "orphan.orseal"), "x");
+
+ failing = false;
+ server.puts.length = 0;
+ const later = new Date(Date.now() + 2 * 60 * 60_000);
+ const second = archiver(server, state, { now: () => later });
+ expect(await second.drain()).toEqual({ uploaded: 1, pending: 0, dropped: 0, blocked: null, disabled: false });
+ expect(server.puts[0]!.partNumber).toBe(3);
+ expect(server.puts.some((put) => put.partNumber === 1 || put.partNumber === 2)).toBe(false);
+ expect(await readdir(join(archiveDir, "tmp"))).toEqual([]);
+ expect(await readdir(join(archiveDir, "pending"))).toEqual([]);
+ const members = await openArchive(server.objects()[0]!.object!);
+ expect(members.map((member) => member.name)).toContain("src/app.ts");
+ });
+
+ test("a capture that crashed before its session commit is discarded at start", async () => {
+ const server = new FakeArchiveServer();
+ const { root } = await project();
+ const state = await tempDir("state");
+ const first = archiver(server, state);
+ const base = await first.captureBase("ses_crash_commit", root);
+ if (base.status !== "queued") throw new Error("base not queued");
+ const queueDir = join(state, ARCHIVE_STATE_DIRECTORY, "queue");
+ const record = JSON.parse(await readFile(join(queueDir, `${base.archiveId}.json`), "utf8"));
+ const ghostId = "11111111-2222-4333-8444-555555555555";
+ await writeFile(join(queueDir, `${ghostId}.json`), JSON.stringify({ ...record, archive_id: ghostId, sealed_file: `${ghostId}.orseal`, request: { ...record.request, archive_id: ghostId, kind: "delta", sequence: 1, turn: 1, parent_archive_id: base.archiveId } }));
+ await writeFile(join(state, ARCHIVE_STATE_DIRECTORY, "pending", `${ghostId}.orseal`), "sealed");
+ const second = archiver(server, state);
+ expect((await second.drain()).uploaded).toBe(1);
+ expect(await readdir(queueDir)).toEqual([]);
+ expect(server.objects().map((archive) => archive.request.archive_id)).toEqual([base.archiveId]);
+ });
+
+ test("a chain-ending conflict stops the session; an unknown kid on a base captures the base again", async () => {
+ const server = new FakeArchiveServer();
+ const { root } = await project();
+ const subject = archiver(server, await tempDir("state"));
+ expect((await subject.captureBase("ses_conflicted", root)).status).toBe("queued");
+ server.apiHook = ({ path }) => (path === "archives" ? new Response(JSON.stringify({ detail: "archive_sequence_conflict" }), { status: 409 }) : undefined);
+ expect(await subject.drain()).toMatchObject({ uploaded: 0, dropped: 1, pending: 0 });
+ await writeFile(join(root, "src/app.ts"), "changed");
+ expect(await subject.captureDelta("ses_conflicted", root, 1)).toEqual({ status: "skipped", reason: "stopped" });
+
+ let rotated = false;
+ server.apiHook = ({ path }) => {
+ if (path !== "archives" || rotated) return undefined;
+ rotated = true;
+ return new Response(JSON.stringify({ detail: "archive_kid_unknown" }), { status: 409 });
+ };
+ const firstBase = await subject.captureBase("ses_rotated_key", root);
+ expect(firstBase.status).toBe("queued");
+ expect(await subject.drain()).toMatchObject({ uploaded: 0, dropped: 1 });
+ const again = await subject.captureDelta("ses_rotated_key", root, 1);
+ expect(again).toMatchObject({ status: "queued", kind: "base", sequence: 0 });
+ expect(again.status === "queued" && firstBase.status === "queued" && again.archiveId !== firstBase.archiveId).toBe(true);
+ expect((await subject.drain()).uploaded).toBe(1);
+ expect(server.objects().at(-1)!.request).toMatchObject({ session_id: "ses_rotated_key", kind: "base", turn: 1 });
+ });
+
+ test("signOut aborts uploads in flight and removes every queued archive and record", async () => {
+ const server = new FakeArchiveServer();
+ const { root } = await project();
+ const state = await tempDir("state");
+ const subject = archiver(server, state);
+ const base = await subject.captureBase("ses_signed_out", root);
+ server.putHook = ({ partNumber }) => (partNumber === 2 ? "network" : undefined);
+ await subject.drain();
+ await subject.signOut();
+ expect(server.callPaths()).toContain(`POST archives/${base.status === "queued" ? base.archiveId : ""}/abort 200`);
+ const archiveDir = join(state, ARCHIVE_STATE_DIRECTORY);
+ await expect(readdir(archiveDir)).rejects.toThrow();
+ // After sign-in the archiver starts clean.
+ subject.setAccessToken(server.token);
+ server.putHook = null;
+ expect(await subject.captureDelta("ses_signed_out", root, 1)).toEqual({ status: "skipped", reason: "no_base" });
+ expect((await subject.captureBase("ses_signed_back_in", root)).status).toBe("queued");
+ });
+
+ test("signOut aborts the part PUT in flight within a second, aborts the upload with the credentials it still holds, and sends nothing more", async () => {
+ const server = new FakeArchiveServer();
+ const { root } = await project();
+ const state = await tempDir("state");
+ const slow = slowPartTwo(server);
+ const subject = archiver(server, state, { fetch: slow.fetch });
+ const base = await subject.captureBase("ses_slow_sign_out", root);
+ const archiveId = base.status === "queued" ? base.archiveId : "";
+ const draining = subject.drain();
+ await slow.started;
+
+ slow.markCommand();
+ await subject.signOut();
+ const signOutMs = Date.now() - slow.commandAt;
+ expect(slow.puts).toEqual([{ part: 2, bytes: server.partSize, abortedAfterMs: expect.any(Number), completed: false }]);
+ expect(slow.puts[0]!.abortedAfterMs!).toBeLessThan(1_000);
+ expect(signOutMs).toBeLessThan(1_000);
+ expect(await draining).toMatchObject({ uploaded: 0 });
+ // The abort went out with a bearer the server still accepted, and nothing completed the archive.
+ expect(server.callPaths()).toContain(`POST archives/${archiveId}/abort 200`);
+ expect(server.callPaths().filter((path) => path.includes("/complete"))).toEqual([]);
+ expect(server.archives.get(archiveId)!.status).toBe("aborted");
+ await expect(readdir(join(state, ARCHIVE_STATE_DIRECTORY))).rejects.toThrow();
+ await Bun.sleep(50);
+ expect(slow.puts).toHaveLength(1);
+ expect(server.puts.filter((put) => put.partNumber > 1)).toEqual([]);
+ });
+
+ test("stop aborts the part PUT in flight within a second; the job stays queued and the next start resumes it", async () => {
+ const server = new FakeArchiveServer();
+ const { root } = await project();
+ const state = await tempDir("state");
+ const slow = slowPartTwo(server);
+ const subject = archiver(server, state, { fetch: slow.fetch });
+ const base = await subject.captureBase("ses_slow_stop_0001", root);
+ const archiveId = base.status === "queued" ? base.archiveId : "";
+ const draining = subject.drain();
+ await slow.started;
+
+ slow.markCommand();
+ await subject.stop();
+ expect(Date.now() - slow.commandAt).toBeLessThan(1_000);
+ expect(slow.puts[0]!.abortedAfterMs!).toBeLessThan(1_000);
+ await draining;
+ // An app quit is not a sign-out: the upload is kept on both sides.
+ expect(server.callPaths().filter((path) => path.includes("/abort") || path.includes("/complete"))).toEqual([]);
+ expect(await readdir(join(state, ARCHIVE_STATE_DIRECTORY, "queue"))).toEqual([`${archiveId}.json`]);
+
+ const next = archiver(server, state);
+ expect(await next.drain()).toMatchObject({ uploaded: 1, pending: 0 });
+ expect(server.objects().map((archive) => archive.request.archive_id)).toEqual([archiveId]);
+ });
+
+ test("the app's own state directory under the root is pruned", async () => {
+ const server = new FakeArchiveServer();
+ const { root } = await project();
+ const state = join(root, ".omnirush-state");
+ const subject = archiver(server, state);
+ expect((await subject.captureBase("ses_state_inside", root)).status).toBe("queued");
+ await subject.drain();
+ const members = await openArchive(server.objects()[0]!.object!);
+ expect(members.some((member) => member.name.startsWith(".omnirush-state"))).toBe(false);
+ expect(manifestOf(members).excluded).toMatchObject({ app_state: 1 });
+ });
+});
diff --git a/apps/server/src/session-archive/index.ts b/apps/server/src/session-archive/index.ts
new file mode 100644
index 00000000..37e31d44
--- /dev/null
+++ b/apps/server/src/session-archive/index.ts
@@ -0,0 +1,898 @@
+/**
+ * SessionArchiver (section 13): the desktop side of the OmniRush project
+ * archive. A session whose root holds a `.git` gets a base archive of the
+ * whole folder at session start and a delta after every completed turn that
+ * changed anything; each is sealed to the omnirush.ai archive key, queued
+ * durably under the collector state dir and uploaded to S3 through presigned
+ * multipart URLs. The embedded server drives it through lifecycle.ts; see
+ * README.md.
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, rename, rm, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+
+import { externalFetch } from "../server-fetch.js";
+import { gitMarkerDetector, isArchivableProject, type ProjectMarkerDetector } from "./detect.js";
+import { hintGarbageCollection, readJsonFile, stateKey, writeChunksAtomic, writeJsonAtomic } from "./files.js";
+import {
+ ArchiveHashCache,
+ archiveLabel,
+ baselineChunks,
+ computeArchiveDelta,
+ isArchiveDeltaEmpty,
+ manifestSource,
+ parseBaselineText,
+ readArchiveGit,
+ scanArchiveTree,
+ type ArchiveKind,
+ type ScannedEntry,
+} from "./manifest.js";
+import { writeSealedArchive } from "./pack.js";
+import { SEAL_CONTENT } from "./seal.js";
+import {
+ ArchiveUploader,
+ DEFAULT_RETRY_POLICY,
+ type ArchiveApiRequest,
+ type ArchiveCreateRequest,
+ type ArchiveFetch,
+ type ArchiveKey,
+ type ArchiveLog,
+ type RetryPolicy,
+} from "./upload.js";
+
+export { gitMarkerDetector, isArchivableProject, type ArchivableProject, type ProjectMarkerDetector } from "./detect.js";
+export { isArchiveCredentialPath } from "./manifest.js";
+export type { ArchiveApiRequest } from "./upload.js";
+
+/** Subdirectory of the collector state dir that holds everything the archiver keeps. */
+export const ARCHIVE_STATE_DIRECTORY = "omnirush-archive";
+const SESSION_ID_PATTERN = /^[A-Za-z0-9._:-]{8,128}$/;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const MAX_TURN = 2 ** 31 - 1;
+/** S3's lifecycle rule removes multipart uploads after 7 days; older jobs cannot finish. */
+const MAX_JOB_AGE_MS = 7 * 24 * 60 * 60_000;
+/** Between drains, a job that failed its retries waits this long, doubling per failure. */
+const JOB_RETRY_BASE_MS = 60_000;
+const JOB_RETRY_MAX_MS = 60 * 60_000;
+const SIGN_OUT_ABORT_TIMEOUT_MS = 5_000;
+
+export type SessionArchiverOptions = {
+ /** As the collector: the archive routes are derived from it like the collect URL. */
+ gatewayUrl?: string;
+ accessToken?: string;
+ /** The collector's hook: a fresh bearer after a 401, or null. */
+ refreshAccessToken?: () => Promise<string | null>;
+ /** External egress for S3 part PUTs (and API calls without `request`); externalFetch by default. */
+ fetch?: ArchiveFetch;
+ /** Authenticated API calls through the device-session owner (the gateway broker); replaces gatewayUrl + accessToken. */
+ request?: ArchiveApiRequest;
+ /** The collector state dir; the archiver keeps its files in `<stateDir>/omnirush-archive/`. */
+ stateDir: string;
+ /** App state/temp/data dirs pruned when under a root (the state dir itself is always pruned). */
+ excludedDirs?: string[];
+ /** Default false: the credential filter of section 5.3 applies. */
+ archiveIncludeCredentialFiles?: boolean;
+ detectors?: ProjectMarkerDetector[];
+ log?: ArchiveLog;
+ /** Tests. */
+ now?: () => Date;
+ /** Tests (the ephemeral key and salt are injected through seal.ts, never here). */
+ random?: { uuid(): string; bytes(n: number): Buffer };
+ /** Tests: backoff timings of the upload client. */
+ retry?: Partial<RetryPolicy>;
+};
+
+export type CaptureSkipReason =
+ | "not_archivable"
+ | "disabled"
+ | "exists"
+ | "no_base"
+ | "unchanged"
+ | "stopped"
+ /** Additions to the section 13.2 union: */
+ | "unavailable"
+ | "stale_turn"
+ | "failed";
+
+export type CaptureResult =
+ | { status: "queued"; archiveId: string; kind: ArchiveKind; sequence: number; size: number }
+ | { status: "skipped"; reason: CaptureSkipReason };
+
+export type DrainResult = {
+ uploaded: number;
+ /** Jobs still queued when the drain ended. */
+ pending: number;
+ /** Jobs dropped (session stopped, archiving turned off, expired). */
+ dropped: number;
+ /** Why the drain stopped early with the queue kept (401 after refresh, 403), else null. */
+ blocked: string | null;
+ /** Archiving was turned off (428 / 503 archive_disabled) during this drain. */
+ disabled: boolean;
+};
+
+const sessionStateSchema = z.object({
+ v: z.literal(1),
+ session_id: z.string(),
+ root: z.string(),
+ marker: z.string(),
+ next_sequence: z.number().int().nonnegative(),
+ last_archive_id: z.string().nullable(),
+ last_turn: z.number().int().nullable(),
+ baseline: z.string().nullable(),
+ stopped: z.string().nullable(),
+ updated_at: z.string(),
+});
+type SessionState = z.infer<typeof sessionStateSchema>;
+
+const createRequestSchema = z.object({
+ archive_id: z.string().regex(UUID_PATTERN),
+ session_id: z.string().regex(SESSION_ID_PATTERN),
+ kind: z.enum(["base", "delta"]),
+ sequence: z.number().int().nonnegative(),
+ turn: z.number().int().nonnegative(),
+ parent_archive_id: z.string().regex(UUID_PATTERN).nullable(),
+ size: z.number().int().positive(),
+ sha256: z.string().regex(/^[0-9a-f]{64}$/),
+ kid: z.string().regex(/^[0-9a-f]{16}$/),
+ content: z.literal(SEAL_CONTENT),
+ marker: z.string(),
+});
+
+const queueRecordSchema = z.object({
+ v: z.literal(1),
+ archive_id: z.string().regex(UUID_PATTERN),
+ session_key: z.string(),
+ request: createRequestSchema,
+ sealed_file: z.string(),
+ created_at: z.string(),
+ attempts: z.number().int().nonnegative(),
+ next_attempt_at: z.string().nullable(),
+ recreates: z.number().int().nonnegative(),
+ upload: z.object({
+ upload_id: z.string(),
+ object_key: z.string(),
+ part_size: z.number().int().positive(),
+ part_count: z.number().int().positive(),
+ etags: z.record(z.string(), z.string()),
+ }).nullable(),
+});
+type QueueRecord = z.infer<typeof queueRecordSchema>;
+
+const archiverStateSchema = z.object({
+ v: z.literal(1),
+ disabled: z.string().nullable(),
+ key: z.object({ kid: z.string(), public_key: z.string(), alg: z.string() }).nullable(),
+});
+
+async function readText(path: string): Promise<string | null> {
+ try {
+ return await readFile(path, "utf8");
+ } catch {
+ return null;
+ }
+}
+
+function errorSummary(error: unknown): string {
+ if (error instanceof Error) return `${error.name}: ${error.message}`;
+ return "unknown error";
+}
+
+export class SessionArchiver {
+ private readonly dir: string;
+ private readonly dirs: { sessions: string; baselines: string; hashCache: string; queue: string; pending: string; tmp: string };
+ private readonly uploader: ArchiveUploader;
+ private readonly detectors: readonly ProjectMarkerDetector[];
+ private readonly appDirs: string[];
+ private readonly includeCredentials: boolean;
+ private readonly log: ArchiveLog;
+ private readonly now: () => Date;
+ private readonly random: { uuid(): string; bytes(n: number): Buffer };
+ private readonly retry: RetryPolicy;
+ private started: Promise<void> | null = null;
+ private key: ArchiveKey | null = null;
+ private disabled: string | null = null;
+ private readonly sessionTails = new Map<string, Promise<void>>();
+ /** Sessions stopped by the drain; captures in flight check it before they commit. */
+ private readonly stoppedSessions = new Map<string, string>();
+ /** Sessions whose base is being reset after a key change; the drain holds their jobs. */
+ private readonly resettingSessions = new Set<string>();
+ /** Bumped by signOut(): captures and drains started before it never commit. */
+ private generation = 0;
+ private draining: Promise<DrainResult> | null = null;
+ private drainAgain = false;
+ private drainController: AbortController | null = null;
+ private retryTimer: ReturnType<typeof setTimeout> | null = null;
+
+ constructor(options: SessionArchiverOptions) {
+ const stateDir = resolve(options.stateDir);
+ this.dir = join(stateDir, ARCHIVE_STATE_DIRECTORY);
+ this.dirs = {
+ sessions: join(this.dir, "sessions"),
+ baselines: join(this.dir, "baselines"),
+ hashCache: join(this.dir, "hash-cache"),
+ queue: join(this.dir, "queue"),
+ pending: join(this.dir, "pending"),
+ tmp: join(this.dir, "tmp"),
+ };
+ this.log = options.log ?? (() => undefined);
+ this.now = options.now ?? (() => new Date());
+ this.random = options.random ?? { uuid: () => randomUUID(), bytes: (n) => randomBytes(n) };
+ this.retry = {
+ ...DEFAULT_RETRY_POLICY,
+ random: () => this.random.bytes(4).readUInt32BE(0) / 2 ** 32,
+ ...options.retry,
+ };
+ this.uploader = new ArchiveUploader({
+ gatewayUrl: options.gatewayUrl ?? process.env.OMNIRUSH_GATEWAY_URL,
+ ...(options.accessToken !== undefined ? { accessToken: options.accessToken } : {}),
+ ...(options.refreshAccessToken ? { refreshAccessToken: options.refreshAccessToken } : {}),
+ fetch: options.fetch ?? externalFetch,
+ ...(options.request ? { request: options.request } : {}),
+ retry: this.retry,
+ log: this.log,
+ });
+ this.detectors = options.detectors ?? [gitMarkerDetector];
+ this.appDirs = [stateDir, ...(options.excludedDirs ?? []).map((dir) => resolve(dir))];
+ this.includeCredentials = options.archiveIncludeCredentialFiles === true;
+ }
+
+ // --- public API -------------------------------------------------------------------
+
+ /** Crash recovery (section 13.4). Idempotent; every other method awaits it. */
+ start(): Promise<void> {
+ this.started ??= this.recover().catch((error) => {
+ this.log("warn", "OmniRush archive state recovery failed", { error: errorSummary(error) });
+ });
+ return this.started;
+ }
+
+ /** The device bearer changed (collector token rotation). */
+ setAccessToken(token: string | null): void {
+ this.uploader.setAccessToken(token);
+ }
+
+ /**
+ * Base archive at session start (new session, or a resumed one without a
+ * base). No-op when the gate says not archivable, archiving is off, or the
+ * session already has a base. Checks consent through GET /archives/key
+ * before packing anything.
+ */
+ captureBase(sessionId: string, root: string, turn = 0): Promise<CaptureResult> {
+ return this.guard("base", sessionId, turn, async () => this.withSession(sessionId, async () => {
+ const generation = this.generation;
+ const state = await this.loadSession(sessionId);
+ if (state?.stopped || this.stoppedSessions.has(sessionId)) return { status: "skipped", reason: "stopped" };
+ if (state && state.next_sequence > 0) return { status: "skipped", reason: "exists" };
+ return this.captureBaseLocked(sessionId, resolve(root), turn, generation);
+ }));
+ }
+
+ /**
+ * Delta after a completed turn. No-op without a base, when the session
+ * stopped archiving, or when nothing in the folder changed. A session whose
+ * base could not be captured yet (key unavailable) gets its base instead.
+ */
+ captureDelta(sessionId: string, root: string, turn: number): Promise<CaptureResult> {
+ return this.guard("delta", sessionId, turn, async () => this.withSession(sessionId, async () => {
+ const generation = this.generation;
+ if (this.disabled) return { status: "skipped", reason: "disabled" };
+ const state = await this.loadSession(sessionId);
+ if (!state) return { status: "skipped", reason: "no_base" };
+ if (state.stopped || this.stoppedSessions.has(sessionId)) return { status: "skipped", reason: "stopped" };
+ if (resolve(root) !== state.root) this.log("warn", "OmniRush archive delta root differs from the session root; using the session root", { sessionId });
+ if (state.next_sequence === 0) return this.captureBaseLocked(sessionId, state.root, turn, generation);
+ if (state.last_turn !== null && turn <= state.last_turn) return { status: "skipped", reason: "stale_turn" };
+ const key = await this.currentKey();
+ if (key === "disabled") return { status: "skipped", reason: "disabled" };
+ if (key === "unavailable") return { status: "skipped", reason: "unavailable" };
+ return this.captureArchive(state, "delta", turn, key, generation);
+ }));
+ }
+
+ /** Uploads queued archives until the queue is empty or blocked; never throws. */
+ drain(): Promise<DrainResult> {
+ if (this.draining) {
+ this.drainAgain = true;
+ return this.draining;
+ }
+ const run = this.runDrain().finally(() => {
+ if (this.draining === run) this.draining = null;
+ });
+ this.draining = run;
+ return run;
+ }
+
+ /** Queue size, for diagnostics. */
+ async pendingStatus(): Promise<{ jobs: number; bytes: number; disabled: string | null }> {
+ await this.start();
+ const records = await this.listQueue();
+ return { jobs: records.length, bytes: records.reduce((sum, record) => sum + record.request.size, 0), disabled: this.disabled };
+ }
+
+ /**
+ * The account signed out: abort in-flight uploads (best effort), drop every
+ * queued archive, baseline, hash cache and session record. Archives are the
+ * user's; nothing may be uploaded later under another account.
+ */
+ async signOut(): Promise<void> {
+ this.generation += 1;
+ this.clearRetryTimer();
+ this.drainController?.abort();
+ try {
+ // Without a state dir there is nothing to abort or delete; recovery would only create one.
+ if (await stat(this.dir).then(() => true, () => false)) {
+ await this.start();
+ const records = await this.listQueue();
+ const aborts = records.filter((record) => record.upload).map((record) => this.uploader.abort(record.archive_id, AbortSignal.timeout(SIGN_OUT_ABORT_TIMEOUT_MS)));
+ await Promise.race([Promise.all(aborts), new Promise((resolvePromise) => setTimeout(resolvePromise, SIGN_OUT_ABORT_TIMEOUT_MS).unref?.())]);
+ }
+ await this.draining?.catch(() => undefined);
+ await rm(this.dir, { recursive: true, force: true });
+ } catch (error) {
+ this.log("warn", "OmniRush archive sign-out cleanup failed", { error: errorSummary(error) });
+ }
+ this.key = null;
+ this.disabled = null;
+ this.stoppedSessions.clear();
+ this.resettingSessions.clear();
+ this.uploader.setAccessToken(null);
+ this.started = null;
+ }
+
+ /**
+ * App shutdown: stops the drain and the retry timer; queued archives stay
+ * for the next start. A capture still packing never commits: the server
+ * that replaces this one (after a sign-out, maybe for another account)
+ * must not find it in the queue. Its changes go into the next delta.
+ */
+ async stop(): Promise<void> {
+ this.generation += 1;
+ this.clearRetryTimer();
+ this.drainController?.abort();
+ await this.draining?.catch(() => undefined);
+ }
+
+ // --- captures -------------------------------------------------------------------------
+
+ private async guard(kind: ArchiveKind, sessionId: string, turn: number, task: () => Promise<CaptureResult>): Promise<CaptureResult> {
+ if (!SESSION_ID_PATTERN.test(sessionId) || !Number.isSafeInteger(turn) || turn < 0 || turn > MAX_TURN) {
+ this.log("warn", "OmniRush archive capture called with an invalid session id or turn", { kind });
+ return { status: "skipped", reason: "failed" };
+ }
+ try {
+ await this.start();
+ return await task();
+ } catch (error) {
+ this.log("warn", "OmniRush archive capture failed", { sessionId, kind, error: errorSummary(error) });
+ return { status: "skipped", reason: "failed" };
+ }
+ }
+
+ private withSession<T>(sessionId: string, task: () => Promise<T>): Promise<T> {
+ const previous = this.sessionTails.get(sessionId) ?? Promise.resolve();
+ const run = previous.then(task);
+ const tail = run.then(() => undefined, () => undefined);
+ this.sessionTails.set(sessionId, tail);
+ void tail.then(() => {
+ if (this.sessionTails.get(sessionId) === tail) this.sessionTails.delete(sessionId);
+ });
+ return run;
+ }
+
+ private async captureBaseLocked(sessionId: string, root: string, turn: number, generation: number): Promise<CaptureResult> {
+ if (!this.uploader.configured) return { status: "skipped", reason: "disabled" };
+ const gate = await isArchivableProject(root, this.detectors, { appDirs: this.appDirs });
+ if (!gate.archivable || !gate.marker) return { status: "skipped", reason: "not_archivable" };
+ const fetched = await this.uploader.fetchKey();
+ if (fetched.status === "disabled") {
+ await this.disable(fetched.code);
+ return { status: "skipped", reason: "disabled" };
+ }
+ const state: SessionState = {
+ v: 1,
+ session_id: sessionId,
+ root,
+ marker: gate.marker,
+ next_sequence: 0,
+ last_archive_id: null,
+ last_turn: null,
+ baseline: null,
+ stopped: null,
+ updated_at: this.now().toISOString(),
+ };
+ if (fetched.status === "unavailable") {
+ // Remembered with next_sequence 0: the next captureDelta tries the base again.
+ if (generation === this.generation) await this.saveSession(state);
+ this.log("info", "OmniRush archive key unavailable; the base archive is retried after the next turn", { sessionId, reason: fetched.reason });
+ return { status: "skipped", reason: "unavailable" };
+ }
+ await this.enable(fetched.key);
+ try {
+ return await this.captureArchive(state, "base", turn, fetched.key, generation);
+ } catch (error) {
+ // Remembered with next_sequence 0 so the next captureDelta tries the base again.
+ if (generation === this.generation && !(await this.loadSession(sessionId))) await this.saveSession(state).catch(() => undefined);
+ throw error;
+ }
+ }
+
+ private async currentKey(): Promise<ArchiveKey | "disabled" | "unavailable"> {
+ if (this.key) return this.key;
+ const fetched = await this.uploader.fetchKey();
+ if (fetched.status === "disabled") {
+ await this.disable(fetched.code);
+ return "disabled";
+ }
+ if (fetched.status === "unavailable") return "unavailable";
+ await this.enable(fetched.key);
+ return fetched.key;
+ }
+
+ /**
+ * One capture under the session's lock. The collection hints around it keep
+ * a capture's per-entry garbage from stacking on top of the previous one's.
+ */
+ private async captureArchive(state: SessionState, kind: ArchiveKind, turn: number, key: ArchiveKey, generation: number): Promise<CaptureResult> {
+ hintGarbageCollection();
+ try {
+ return await this.captureArchiveOnce(state, kind, turn, key, generation);
+ } finally {
+ hintGarbageCollection();
+ }
+ }
+
+ /** Pass 1, delta, pass 2 and the commit protocol of section 13.4. */
+ private async captureArchiveOnce(state: SessionState, kind: ArchiveKind, turn: number, key: ArchiveKey, generation: number): Promise<CaptureResult> {
+ const sessionId = state.session_id;
+ const sessionKey = stateKey(sessionId);
+ const rootKey = stateKey(state.root);
+ const cache = await this.loadHashCache(rootKey);
+ const scanning = scanArchiveTree(state.root, { excludedDirs: this.appDirs, includeCredentialFiles: this.includeCredentials, hashCache: cache });
+ const gitReading = kind === "base" ? readArchiveGit(state.root) : null;
+ const scan = await scanning;
+ let files: ScannedEntry[] = scan.entries;
+ let deleted: string[] | undefined;
+ if (kind === "delta") {
+ const baseline = state.baseline ? parseBaselineText(await readText(join(this.dirs.baselines, state.baseline))) : null;
+ if (!baseline) {
+ await this.markStopped(sessionId, "baseline_missing");
+ return { status: "skipped", reason: "stopped" };
+ }
+ const delta = computeArchiveDelta(baseline, scan.entries);
+ if (isArchiveDeltaEmpty(delta)) {
+ if (cache.changed) await this.saveHashCache(rootKey, cache);
+ return { status: "skipped", reason: "unchanged" };
+ }
+ files = delta.files;
+ deleted = delta.deleted;
+ }
+ const git = await (gitReading ?? readArchiveGit(state.root));
+ const archiveId = this.random.uuid();
+ const sequence = state.next_sequence;
+ const createdAt = this.now();
+ const manifest = manifestSource({
+ kind,
+ archiveId,
+ sessionId,
+ sequence,
+ turn,
+ createdAt,
+ parentArchiveId: kind === "base" ? null : state.last_archive_id,
+ label: archiveLabel(state.root),
+ marker: state.marker,
+ git,
+ files,
+ ...(deleted ? { deleted } : {}),
+ excluded: scan.excluded,
+ });
+ const partial = join(this.dirs.tmp, `${archiveId}.partial`);
+ let sealed: Awaited<ReturnType<typeof writeSealedArchive>>;
+ try {
+ sealed = await writeSealedArchive(
+ { root: state.root, manifest, createdAtSeconds: Math.floor(createdAt.getTime() / 1000), entries: files },
+ { publicKey: key.publicKey },
+ partial,
+ );
+ } catch (error) {
+ await rm(partial, { force: true });
+ throw error;
+ }
+ if (generation !== this.generation || this.disabled || this.stoppedSessions.has(sessionId)) {
+ await rm(partial, { force: true });
+ return { status: "skipped", reason: this.disabled ? "disabled" : "stopped" };
+ }
+ // 1-2: the sealed file and its queue record.
+ const sealedFile = `${archiveId}.orseal`;
+ await rename(partial, join(this.dirs.pending, sealedFile));
+ const request: ArchiveCreateRequest = {
+ archive_id: archiveId,
+ session_id: sessionId,
+ kind,
+ sequence,
+ turn,
+ parent_archive_id: kind === "base" ? null : state.last_archive_id,
+ size: sealed.size,
+ sha256: sealed.sha256,
+ kid: sealed.kid,
+ content: SEAL_CONTENT,
+ marker: state.marker,
+ };
+ const record: QueueRecord = {
+ v: 1,
+ archive_id: archiveId,
+ session_key: sessionKey,
+ request,
+ sealed_file: sealedFile,
+ created_at: createdAt.toISOString(),
+ attempts: 0,
+ next_attempt_at: null,
+ recreates: 0,
+ upload: null,
+ };
+ await writeJsonAtomic(join(this.dirs.queue, `${archiveId}.json`), record);
+ // 3: the new baseline is the full scan; entries that changed while packing get a null hash so the next delta sends them again.
+ const unstable = new Set(sealed.unstable);
+ for (const path of unstable) cache.forget(path);
+ const baselineName = `${sessionKey}-${sequence}.json`;
+ await writeChunksAtomic(join(this.dirs.baselines, baselineName), baselineChunks(scan.entries, unstable));
+ // 4: commit.
+ const previousBaseline = state.baseline;
+ await this.saveSession({
+ ...state,
+ next_sequence: sequence + 1,
+ last_archive_id: archiveId,
+ last_turn: turn,
+ baseline: baselineName,
+ updated_at: this.now().toISOString(),
+ });
+ if (previousBaseline && previousBaseline !== baselineName) await rm(join(this.dirs.baselines, previousBaseline), { force: true });
+ await this.saveHashCache(rootKey, cache);
+ this.log("info", "OmniRush project archive queued", {
+ sessionId,
+ archiveId,
+ kind,
+ sequence,
+ turn,
+ bytes: sealed.size,
+ files: files.length,
+ ...(deleted ? { deleted: deleted.length } : {}),
+ ...(unstable.size > 0 ? { unstable: unstable.size } : {}),
+ });
+ return { status: "queued", archiveId, kind, sequence, size: sealed.size };
+ }
+
+ // --- drain -----------------------------------------------------------------------------
+
+ private async runDrain(): Promise<DrainResult> {
+ const result: DrainResult = { uploaded: 0, pending: 0, dropped: 0, blocked: null, disabled: false };
+ this.clearRetryTimer();
+ const controller = new AbortController();
+ this.drainController = controller;
+ try {
+ await this.start();
+ const generation = this.generation;
+ do {
+ this.drainAgain = false;
+ if (!(await this.drainOnce(result, controller.signal, generation))) break;
+ } while (this.drainAgain && !controller.signal.aborted);
+ const remaining = await this.listQueue();
+ result.pending = remaining.length;
+ if (!controller.signal.aborted && generation === this.generation && !result.blocked && !result.disabled) this.scheduleRetry(remaining);
+ } catch (error) {
+ this.log("warn", "OmniRush archive drain failed", { error: errorSummary(error) });
+ } finally {
+ if (this.drainController === controller) this.drainController = null;
+ }
+ return result;
+ }
+
+ /**
+ * The queue in upload order: each session's jobs strictly by sequence (a
+ * delta's parent must be uploaded first, whatever the clock did), sessions
+ * by the creation time of their oldest job.
+ */
+ private async orderedQueue(): Promise<QueueRecord[]> {
+ const bySession = new Map<string, QueueRecord[]>();
+ for (const record of await this.listQueue()) {
+ const jobs = bySession.get(record.request.session_id) ?? [];
+ jobs.push(record);
+ bySession.set(record.request.session_id, jobs);
+ }
+ const sessions = [...bySession.values()].map((jobs) => jobs.sort((left, right) => left.request.sequence - right.request.sequence));
+ sessions.sort((left, right) => left[0]!.created_at.localeCompare(right[0]!.created_at));
+ return sessions.flat();
+ }
+
+ /** One pass over the queue; false when the drain must stop. */
+ private async drainOnce(result: DrainResult, signal: AbortSignal, generation: number): Promise<boolean> {
+ const records = await this.orderedQueue();
+ const held = new Set<string>();
+ const nowMs = this.now().getTime();
+ for (const record of records) {
+ if (signal.aborted || generation !== this.generation) return false;
+ const sessionId = record.request.session_id;
+ if (held.has(sessionId) || this.resettingSessions.has(sessionId)) continue;
+ if (this.stoppedSessions.has(sessionId)) {
+ await this.deleteJob(record);
+ result.dropped += 1;
+ continue;
+ }
+ if (nowMs - Date.parse(record.created_at) > MAX_JOB_AGE_MS) {
+ result.dropped += await this.stopSession(sessionId, "archive_expired");
+ held.add(sessionId);
+ continue;
+ }
+ if (record.next_attempt_at && Date.parse(record.next_attempt_at) > nowMs) {
+ held.add(sessionId);
+ continue;
+ }
+ const job = { request: record.request, sealedPath: join(this.dirs.pending, record.sealed_file), upload: record.upload, recreates: record.recreates };
+ const persist = async () => {
+ record.upload = job.upload;
+ record.recreates = job.recreates;
+ await writeJsonAtomic(join(this.dirs.queue, `${record.archive_id}.json`), record);
+ };
+ const outcome = await this.uploader.upload(job, persist, signal);
+ switch (outcome.status) {
+ case "uploaded":
+ await this.deleteJob(record);
+ result.uploaded += 1;
+ this.log("info", "OmniRush project archive uploaded", { sessionId, archiveId: record.archive_id, kind: record.request.kind, sequence: record.request.sequence, bytes: record.request.size });
+ break;
+ case "disabled":
+ result.dropped += await this.disable(outcome.code);
+ result.disabled = true;
+ return false;
+ case "blocked":
+ result.blocked = outcome.reason;
+ this.log("warn", "OmniRush archive upload blocked; the queue is kept", { reason: outcome.reason });
+ return false;
+ case "stop_session":
+ result.dropped += await this.stopSession(sessionId, outcome.code);
+ held.add(sessionId);
+ break;
+ case "rekey":
+ this.key = null;
+ await this.saveArchiverState();
+ if (record.request.kind === "base") {
+ // Nothing exists on the server yet: the base is captured again with the current key.
+ result.dropped += await this.resetToNoBase(sessionId);
+ } else {
+ result.dropped += await this.stopSession(sessionId, outcome.code);
+ }
+ held.add(sessionId);
+ break;
+ case "retry_later": {
+ record.attempts += 1;
+ const delay = Math.min(JOB_RETRY_MAX_MS, JOB_RETRY_BASE_MS * 2 ** (record.attempts - 1));
+ record.next_attempt_at = new Date(nowMs + delay).toISOString();
+ await persist();
+ held.add(sessionId);
+ this.log("warn", "OmniRush archive upload deferred", { sessionId, archiveId: record.archive_id, attempts: record.attempts, reason: outcome.reason });
+ break;
+ }
+ case "aborted":
+ return false;
+ }
+ }
+ return true;
+ }
+
+ private scheduleRetry(records: readonly QueueRecord[]): void {
+ const next = records.map((record) => (record.next_attempt_at ? Date.parse(record.next_attempt_at) : Number.NaN)).filter(Number.isFinite);
+ if (next.length === 0) return;
+ const delay = Math.max(1_000, Math.min(...next) - this.now().getTime());
+ this.retryTimer = setTimeout(() => {
+ this.retryTimer = null;
+ void this.drain();
+ }, delay);
+ this.retryTimer.unref?.();
+ }
+
+ private clearRetryTimer(): void {
+ if (this.retryTimer) clearTimeout(this.retryTimer);
+ this.retryTimer = null;
+ }
+
+ // --- state transitions -------------------------------------------------------------------
+
+ /** 428 / 503: archiving is off for the user. Every queued job goes; sessions that lost jobs stop. */
+ private async disable(code: string): Promise<number> {
+ if (!this.disabled) this.log("info", "OmniRush project archiving is off for this account", { code });
+ this.disabled = code;
+ this.key = null;
+ await this.saveArchiverState();
+ const records = await this.listQueue();
+ for (const record of records) {
+ await this.deleteJob(record);
+ this.requestStop(record.request.session_id, "archive_disabled");
+ }
+ return records.length;
+ }
+
+ private async enable(key: ArchiveKey): Promise<void> {
+ const changed = this.disabled !== null || this.key?.kid !== key.kid;
+ this.disabled = null;
+ this.key = key;
+ if (changed) await this.saveArchiverState();
+ }
+
+ /** Drops the session's queued jobs and marks it stopped; returns how many jobs were dropped. */
+ private async stopSession(sessionId: string, code: string): Promise<number> {
+ const records = (await this.listQueue()).filter((record) => record.request.session_id === sessionId);
+ for (const record of records) await this.deleteJob(record);
+ this.requestStop(sessionId, code);
+ this.log("warn", "OmniRush archiving stopped for a session", { sessionId, code, droppedJobs: records.length });
+ return records.length;
+ }
+
+ /** Marks the session stopped now (in memory) and in its state file once its lock is free. */
+ private requestStop(sessionId: string, code: string): void {
+ if (this.stoppedSessions.has(sessionId)) return;
+ this.stoppedSessions.set(sessionId, code);
+ const generation = this.generation;
+ void this.withSession(sessionId, async () => {
+ if (generation === this.generation) await this.markStopped(sessionId, code);
+ }).catch((error) => this.log("warn", "OmniRush archive session stop failed", { sessionId, error: errorSummary(error) }));
+ }
+
+ /** Under the session lock: the stopped flag, and any job queued since. */
+ private async markStopped(sessionId: string, code: string): Promise<void> {
+ for (const record of await this.listQueue()) {
+ if (record.request.session_id === sessionId) await this.deleteJob(record);
+ }
+ const state = await this.loadSession(sessionId);
+ if (state && !state.stopped) await this.saveSession({ ...state, stopped: code, updated_at: this.now().toISOString() });
+ }
+
+ /** A base sealed to an unknown kid: forget it so the next capture seals a new base with the current key. */
+ private async resetToNoBase(sessionId: string): Promise<number> {
+ const dropped = (await this.listQueue()).filter((record) => record.request.session_id === sessionId);
+ for (const record of dropped) await this.deleteJob(record);
+ // Held out of the drain until the reset has run: a delta packed on top of
+ // the dropped base would otherwise be sent and end the chain with a 409.
+ this.resettingSessions.add(sessionId);
+ const generation = this.generation;
+ void this.withSession(sessionId, async () => {
+ if (generation !== this.generation) return;
+ for (const record of await this.listQueue()) {
+ if (record.request.session_id === sessionId) await this.deleteJob(record);
+ }
+ const state = await this.loadSession(sessionId);
+ if (!state || state.stopped) return;
+ if (state.baseline) await rm(join(this.dirs.baselines, state.baseline), { force: true });
+ await this.saveSession({ ...state, next_sequence: 0, last_archive_id: null, last_turn: null, baseline: null, updated_at: this.now().toISOString() });
+ })
+ .catch((error) => this.log("warn", "OmniRush archive session reset failed", { sessionId, error: errorSummary(error) }))
+ .finally(() => this.resettingSessions.delete(sessionId));
+ this.log("info", "OmniRush archive key changed; the session's base archive will be captured again", { sessionId });
+ return dropped.length;
+ }
+
+ // --- files -------------------------------------------------------------------------------
+
+ private sessionPath(sessionId: string): string {
+ return join(this.dirs.sessions, `${stateKey(sessionId)}.json`);
+ }
+
+ private async loadSession(sessionId: string): Promise<SessionState | null> {
+ const parsed = sessionStateSchema.safeParse(await readJsonFile(this.sessionPath(sessionId)));
+ return parsed.success && parsed.data.session_id === sessionId ? parsed.data : null;
+ }
+
+ private async saveSession(state: SessionState): Promise<void> {
+ await writeJsonAtomic(this.sessionPath(state.session_id), state);
+ }
+
+ private async loadHashCache(rootKey: string): Promise<ArchiveHashCache> {
+ return ArchiveHashCache.fromText(await readText(join(this.dirs.hashCache, `${rootKey}.json`)));
+ }
+
+ private async saveHashCache(rootKey: string, cache: ArchiveHashCache): Promise<void> {
+ await writeChunksAtomic(join(this.dirs.hashCache, `${rootKey}.json`), cache.jsonChunks());
+ }
+
+ private async saveArchiverState(): Promise<void> {
+ await writeJsonAtomic(join(this.dir, "state.json"), {
+ v: 1,
+ disabled: this.disabled,
+ key: this.key ? { kid: this.key.kid, public_key: this.key.publicKey.toString("base64"), alg: this.key.alg } : null,
+ });
+ }
+
+ private async listQueue(): Promise<QueueRecord[]> {
+ let names: string[];
+ try {
+ names = await readdir(this.dirs.queue);
+ } catch {
+ return [];
+ }
+ const records: QueueRecord[] = [];
+ for (const name of names) {
+ if (!name.endsWith(".json")) continue;
+ const parsed = queueRecordSchema.safeParse(await readJsonFile(join(this.dirs.queue, name)));
+ if (parsed.success && name === `${parsed.data.archive_id}.json`) records.push(parsed.data);
+ }
+ return records;
+ }
+
+ private async deleteJob(record: QueueRecord): Promise<void> {
+ await rm(join(this.dirs.pending, record.sealed_file), { force: true });
+ await rm(join(this.dirs.queue, `${record.archive_id}.json`), { force: true });
+ }
+
+ /** Startup (section 13.4): tmp emptied, uncommitted and orphaned files removed, stale jobs dropped. */
+ private async recover(): Promise<void> {
+ for (const dir of Object.values(this.dirs)) await mkdir(dir, { recursive: true, mode: 0o700 });
+ await rm(this.dirs.tmp, { recursive: true, force: true });
+ await mkdir(this.dirs.tmp, { recursive: true, mode: 0o700 });
+ for (const name of await readdir(this.dir)) {
+ if (name.endsWith(".tmp")) await rm(join(this.dir, name), { force: true });
+ }
+
+ const saved = archiverStateSchema.safeParse(await readJsonFile(join(this.dir, "state.json")));
+ if (saved.success) {
+ this.disabled = saved.data.disabled;
+ const publicKey = saved.data.key ? Buffer.from(saved.data.key.public_key, "base64") : null;
+ if (saved.data.key && publicKey?.length === 32) this.key = { kid: saved.data.key.kid, publicKey, alg: saved.data.key.alg };
+ }
+
+ const sessions = new Map<string, SessionState>();
+ for (const name of await readdir(this.dirs.sessions)) {
+ const path = join(this.dirs.sessions, name);
+ if (!name.endsWith(".json")) {
+ await rm(path, { force: true });
+ continue;
+ }
+ const parsed = sessionStateSchema.safeParse(await readJsonFile(path));
+ if (parsed.success && name === `${stateKey(parsed.data.session_id)}.json`) sessions.set(stateKey(parsed.data.session_id), parsed.data);
+ else await rm(path, { force: true });
+ }
+
+ const pendingFiles = new Set(await readdir(this.dirs.pending));
+ const kept = new Set<string>();
+ const nowMs = this.now().getTime();
+ const stop = async (session: SessionState, code: string) => {
+ if (session.stopped) return;
+ session.stopped = code;
+ session.updated_at = this.now().toISOString();
+ await this.saveSession(session);
+ };
+ for (const name of await readdir(this.dirs.queue)) {
+ const path = join(this.dirs.queue, name);
+ const parsed = name.endsWith(".json") ? queueRecordSchema.safeParse(await readJsonFile(path)) : null;
+ if (!parsed?.success || name !== `${parsed.data.archive_id}.json`) {
+ await rm(path, { force: true });
+ continue;
+ }
+ const record = parsed.data;
+ const session = sessions.get(record.session_key);
+ if (!session || session.stopped || record.request.sequence >= session.next_sequence) {
+ // A crash before the session commit (step 4), or a stopped session: never uploaded.
+ await this.deleteJob(record);
+ continue;
+ }
+ if (!pendingFiles.has(record.sealed_file)) {
+ await this.deleteJob(record);
+ await stop(session, "archive_file_missing");
+ continue;
+ }
+ if (nowMs - Date.parse(record.created_at) > MAX_JOB_AGE_MS) {
+ await this.deleteJob(record);
+ await stop(session, "archive_expired");
+ continue;
+ }
+ kept.add(record.sealed_file);
+ }
+ for (const name of pendingFiles) if (!kept.has(name)) await rm(join(this.dirs.pending, name), { force: true });
+
+ const namedBaselines = new Set([...sessions.values()].map((session) => session.baseline).filter((name) => name !== null));
+ for (const name of await readdir(this.dirs.baselines)) {
+ if (!namedBaselines.has(name)) await rm(join(this.dirs.baselines, name), { force: true });
+ }
+ for (const name of await readdir(this.dirs.hashCache)) {
+ if (name.endsWith(".tmp")) await rm(join(this.dirs.hashCache, name), { force: true });
+ }
+ }
+}
diff --git a/apps/server/src/session-archive/lifecycle.test.ts b/apps/server/src/session-archive/lifecycle.test.ts
new file mode 100644
index 00000000..87c46ceb
--- /dev/null
+++ b/apps/server/src/session-archive/lifecycle.test.ts
@@ -0,0 +1,490 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { execFile } from "node:child_process";
+import { mkdir, symlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import { FakeArchiveServer } from "./fake-archive-server.js";
+import { SessionArchiver, type CaptureResult, type DrainResult } from "./index.js";
+import {
+ completedTurnCount,
+ projectArchiveEnabled,
+ ProjectArchiveLifecycle,
+ type ArchiveEngineReads,
+ type ProjectArchiver,
+} from "./lifecycle.js";
+import { cleanupTempDirs, manifestOf, openArchive, tempDir } from "./test-helpers.js";
+
+const execFileAsync = promisify(execFile);
+
+afterEach(cleanupTempDirs);
+
+const queued = (kind: "base" | "delta", sequence = 0): CaptureResult => ({ status: "queued", archiveId: `archive-${kind}-${sequence}`, kind, sequence, size: 1 });
+const skipped = (reason: Extract<CaptureResult, { status: "skipped" }>["reason"]): CaptureResult => ({ status: "skipped", reason });
+const drained: DrainResult = { uploaded: 0, pending: 0, dropped: 0, blocked: null, disabled: false };
+
+/** Records every call; each result can be swapped per test. */
+class FakeArchiver implements ProjectArchiver {
+ readonly calls: string[] = [];
+ base: (sessionId: string, turn: number) => Promise<CaptureResult> = async () => queued("base");
+ delta: (sessionId: string, turn: number) => Promise<CaptureResult> = async (_sessionId, turn) => queued("delta", turn);
+ drainResult: () => Promise<DrainResult> = async () => drained;
+
+ async captureBase(sessionId: string, root: string, turn = 0): Promise<CaptureResult> {
+ this.calls.push(`base ${sessionId} ${root} ${turn}`);
+ return this.base(sessionId, turn);
+ }
+
+ async captureDelta(sessionId: string, root: string, turn: number): Promise<CaptureResult> {
+ this.calls.push(`delta ${sessionId} ${root} ${turn}`);
+ return this.delta(sessionId, turn);
+ }
+
+ async drain(): Promise<DrainResult> {
+ this.calls.push("drain");
+ return this.drainResult();
+ }
+
+ async signOut(): Promise<void> {
+ this.calls.push("signOut");
+ }
+
+ async stop(): Promise<void> {
+ this.calls.push("stop");
+ }
+
+ captures(): string[] {
+ return this.calls.filter((call) => call.startsWith("base") || call.startsWith("delta"));
+ }
+}
+
+type Message = { info: Record<string, unknown>; parts: unknown[] };
+
+/** A v1 engine message list: `completed` answered prompts, then optionally one still running. */
+function messages(completed: number, running = false): Message[] {
+ const list: Message[] = [];
+ for (let turn = 1; turn <= completed + (running ? 1 : 0); turn += 1) {
+ list.push({ info: { id: `user_${turn}`, role: "user", time: { created: turn } }, parts: [] });
+ if (turn <= completed) list.push({ info: { id: `assistant_${turn}`, role: "assistant", time: { created: turn, completed: turn + 1 } }, parts: [] });
+ }
+ return list;
+}
+
+/** Engine reads for one session, counting how often each route is read. */
+function engine(input: { parentID?: string; messages?: () => unknown; session?: () => unknown } = {}) {
+ const reads = { session: 0, messages: 0 };
+ const reader: ArchiveEngineReads = {
+ session: async () => {
+ reads.session += 1;
+ return input.session ? input.session() : { id: "ses_root_0001", ...(input.parentID ? { parentID: input.parentID } : {}) };
+ },
+ messages: async () => {
+ reads.messages += 1;
+ return input.messages ? input.messages() : [];
+ },
+ };
+ return { reader, reads };
+}
+
+function lifecycle(archiver: ProjectArchiver, options: { enabled?: boolean; now?: () => number; concurrency?: number } = {}) {
+ const logs: Array<{ level: string; message: string; attributes?: Record<string, unknown> }> = [];
+ const subject = new ProjectArchiveLifecycle({
+ archiver,
+ enabled: options.enabled ?? true,
+ log: (level, message, attributes) => logs.push({ level, message, ...(attributes ? { attributes } : {}) }),
+ consentRecheckMs: 60_000,
+ ...(options.now ? { now: options.now } : {}),
+ ...(options.concurrency ? { concurrency: options.concurrency } : {}),
+ });
+ return { subject, logs };
+}
+
+function deferred<T>() {
+ let resolve!: (value: T) => void;
+ const promise = new Promise<T>((resolvePromise) => { resolve = resolvePromise; });
+ return { promise, resolve };
+}
+
+describe("completedTurnCount", () => {
+ test("counts prompts answered by an assistant message that ended, v1 and v2 shapes", () => {
+ expect(completedTurnCount(messages(0))).toBe(0);
+ expect(completedTurnCount(messages(3))).toBe(3);
+ // The running turn is not complete yet.
+ expect(completedTurnCount(messages(2, true))).toBe(2);
+ // Several assistant steps of one turn count once; a finish part or an error also ends a turn.
+ expect(completedTurnCount([
+ { info: { role: "user" } },
+ { info: { role: "assistant", finish: "tool-calls" } },
+ { info: { role: "assistant", time: { completed: 5 } } },
+ { info: { role: "user" } },
+ { info: { role: "assistant" }, parts: [{ type: "step-finish" }] },
+ { info: { role: "user" } },
+ { info: { role: "assistant", error: { name: "MessageAbortedError" } } },
+ ])).toBe(3);
+ // v2 context entries carry the role as `type`.
+ expect(completedTurnCount([
+ { id: "u1", type: "user" },
+ { id: "a1", type: "assistant", time: { created: 1, completed: 2 } },
+ { id: "c1", type: "compaction" },
+ { id: "u2", type: "user" },
+ { id: "a2", type: "assistant", content: [{ type: "text" }] },
+ ])).toBe(1);
+ expect(completedTurnCount(null)).toBeNull();
+ expect(completedTurnCount({ status: 500, unavailable: true })).toBeNull();
+ });
+});
+
+describe("projectArchiveEnabled", () => {
+ test("is on by default and off only when OMNIRUSH_ARCHIVE_ENABLED says so", () => {
+ expect(projectArchiveEnabled({})).toBe(true);
+ expect(projectArchiveEnabled({ OMNIRUSH_ARCHIVE_ENABLED: "1" })).toBe(true);
+ expect(projectArchiveEnabled({ OMNIRUSH_ARCHIVE_ENABLED: "" })).toBe(true);
+ for (const off of ["0", "false", "FALSE", " no ", "off"]) expect(projectArchiveEnabled({ OMNIRUSH_ARCHIVE_ENABLED: off })).toBe(false);
+ });
+});
+
+describe("ProjectArchiveLifecycle", () => {
+ test("app start resumes the queue; a root session gets one base per app run at its real path and completed turns", async () => {
+ const archiver = new FakeArchiver();
+ const { subject, logs } = lifecycle(archiver);
+ subject.start();
+ await subject.settled();
+ expect(archiver.calls).toEqual(["drain"]);
+
+ const real = await tempDir("root");
+ const link = join(await tempDir("links"), "project");
+ await symlink(real, link);
+ const reads = engine({ messages: () => messages(2, true) });
+ subject.sessionStarted({ sessionId: "ses_root_0001", root: link, engine: reads.reader });
+ // Every prompt dispatch calls this; only the first one reaches the archiver.
+ subject.sessionStarted({ sessionId: "ses_root_0001", root: link, engine: reads.reader });
+ await subject.settled();
+ subject.sessionStarted({ sessionId: "ses_root_0001", root: link, engine: reads.reader });
+ await subject.settled();
+
+ expect(archiver.captures()).toEqual([`base ses_root_0001 ${real} 2`]);
+ expect(reads.reads).toEqual({ session: 1, messages: 1 });
+ // A queued base is uploaded right away.
+ expect(archiver.calls.slice(1)).toEqual([`base ses_root_0001 ${real} 2`, "drain"]);
+ expect(logs).toEqual([]);
+ });
+
+ test("child (sub-agent) sessions are never archived", async () => {
+ const archiver = new FakeArchiver();
+ const { subject } = lifecycle(archiver);
+ const root = await tempDir("root");
+ const child = engine({ parentID: "ses_root_0001", messages: () => messages(1) });
+ subject.sessionStarted({ sessionId: "ses_child_0001", root, engine: child.reader });
+ await subject.settled();
+ subject.turnCompleted("ses_child_0001", messages(1));
+ subject.sessionStarted({ sessionId: "ses_child_0001", root, engine: child.reader });
+ await subject.settled();
+
+ // v2 session records nest the fields under `info`.
+ const v2Child = engine({ session: () => ({ info: { id: "ses_child_0002", parentID: "ses_root_0001" } }) });
+ subject.sessionStarted({ sessionId: "ses_child_0002", root, engine: v2Child.reader });
+ await subject.settled();
+
+ expect(archiver.captures()).toEqual([]);
+ // Known to be a child: the engine is not asked again, and its messages are never read.
+ expect(child.reads).toEqual({ session: 1, messages: 0 });
+ });
+
+ test("delta turn numbers come from the engine's completed turns, in order after the base", async () => {
+ const archiver = new FakeArchiver();
+ const { subject } = lifecycle(archiver);
+ const root = await tempDir("root");
+ const baseGate = deferred<CaptureResult>();
+ archiver.base = () => baseGate.promise;
+ subject.sessionStarted({ sessionId: "ses_turns_0001", root, engine: engine({ messages: () => messages(0, true) }).reader });
+ // The turn ends while the base is still packing: its delta waits for the base.
+ subject.turnCompleted("ses_turns_0001", messages(1));
+ subject.turnCompleted("ses_turns_0001", messages(2));
+ // Unreadable messages: no delta (the next one carries the changes).
+ subject.turnCompleted("ses_turns_0001", { status: 503, unavailable: true });
+ // Unknown sessions (never started in this app run) are left alone.
+ subject.turnCompleted("ses_unknown_0001", messages(4));
+ baseGate.resolve(queued("base"));
+ await subject.settled();
+
+ expect(archiver.captures()).toEqual([
+ `base ses_turns_0001 ${root} 0`,
+ `delta ses_turns_0001 ${root} 1`,
+ `delta ses_turns_0001 ${root} 2`,
+ ]);
+ });
+
+ test("after a restart, a resumed session continues from the engine's turn count", async () => {
+ const archiver = new FakeArchiver();
+ const root = await tempDir("root");
+ // The first app run archived turns 0 to 3 of this session; the archiver's state says so.
+ archiver.base = async () => skipped("exists");
+ const { subject } = lifecycle(archiver);
+ subject.start();
+ subject.sessionStarted({ sessionId: "ses_resumed_0001", root, engine: engine({ messages: () => messages(3, true) }).reader });
+ subject.turnCompleted("ses_resumed_0001", messages(4));
+ await subject.settled();
+ expect(archiver.calls).toEqual(["drain", `base ses_resumed_0001 ${root} 3`, `delta ses_resumed_0001 ${root} 4`, "drain"]);
+ });
+
+ test("without an account (or with archiving turned off) start clears what a previous run left and nothing is captured", async () => {
+ const archiver = new FakeArchiver();
+ const { subject } = lifecycle(archiver, { enabled: false });
+ subject.start();
+ const root = await tempDir("root");
+ subject.sessionStarted({ sessionId: "ses_signed_out_01", root, engine: engine().reader });
+ subject.turnCompleted("ses_signed_out_01", messages(1));
+ subject.sessionEnded("ses_signed_out_01");
+ await subject.settled();
+ expect(archiver.calls).toEqual(["signOut"]);
+ });
+
+ test("sign-out stops the archiver: queued steps never run and nothing is captured or uploaded afterwards", async () => {
+ const archiver = new FakeArchiver();
+ const { subject } = lifecycle(archiver);
+ const root = await tempDir("root");
+ const first = deferred<CaptureResult>();
+ archiver.base = (sessionId) => (sessionId === "ses_first_0001" ? first.promise : Promise.resolve(queued("base")));
+ subject.sessionStarted({ sessionId: "ses_first_0001", root, engine: engine().reader });
+ // One capture at a time: the second session waits behind the first.
+ subject.sessionStarted({ sessionId: "ses_second_001", root, engine: engine().reader });
+ await Bun.sleep(5);
+ expect(archiver.captures()).toEqual([`base ses_first_0001 ${root} 0`]);
+
+ await subject.signOut();
+ first.resolve(queued("base"));
+ subject.sessionStarted({ sessionId: "ses_third_0001", root, engine: engine().reader });
+ subject.turnCompleted("ses_first_0001", messages(1));
+ subject.sessionEnded("ses_first_0001");
+ await subject.settled();
+ expect(archiver.calls).toEqual([`base ses_first_0001 ${root} 0`, "signOut"]);
+ });
+
+ test("428 (archive consent missing) turns archiving off quietly until the consent recheck", async () => {
+ let now = 1_000;
+ const archiver = new FakeArchiver();
+ const { subject, logs } = lifecycle(archiver, { now: () => now });
+ const root = await tempDir("root");
+ archiver.base = async () => skipped("disabled");
+ subject.sessionStarted({ sessionId: "ses_consent_001", root, engine: engine().reader });
+ await subject.settled();
+ // Off: no capture, no consent check and no upload for any session.
+ subject.sessionStarted({ sessionId: "ses_consent_001", root, engine: engine().reader });
+ subject.sessionStarted({ sessionId: "ses_consent_002", root, engine: engine().reader });
+ subject.turnCompleted("ses_consent_001", messages(1));
+ subject.sessionEnded("ses_consent_003");
+ await subject.settled();
+ expect(archiver.calls).toEqual([`base ses_consent_001 ${root} 0`]);
+
+ // Past the recheck time the session's next prompt checks consent again, which is now given.
+ now += 60_001;
+ archiver.base = async () => queued("base");
+ subject.sessionStarted({ sessionId: "ses_consent_001", root, engine: engine({ messages: () => messages(1, true) }).reader });
+ await subject.settled();
+ expect(archiver.calls.slice(1)).toEqual([`base ses_consent_001 ${root} 1`, "drain"]);
+
+ // Consent withdrawn while uploading: the drain turns archiving off the same way.
+ archiver.drainResult = async () => ({ ...drained, dropped: 1, disabled: true });
+ subject.turnCompleted("ses_consent_001", messages(2));
+ await subject.settled();
+ subject.turnCompleted("ses_consent_001", messages(3));
+ subject.sessionStarted({ sessionId: "ses_consent_004", root, engine: engine().reader });
+ await subject.settled();
+ expect(archiver.calls.slice(3)).toEqual([`delta ses_consent_001 ${root} 2`, "drain"]);
+ expect(logs).toEqual([]);
+ });
+
+ test("failures never reach the caller: one warn line each, and archiving carries on", async () => {
+ const archiver = new FakeArchiver();
+ const { subject, logs } = lifecycle(archiver);
+ const root = await tempDir("root");
+ archiver.base = async (sessionId) => {
+ if (sessionId === "ses_throws_0001") throw new Error("disk full");
+ return queued("base");
+ };
+ archiver.drainResult = async () => { throw new Error("drain exploded"); };
+ subject.sessionStarted({ sessionId: "ses_throws_0001", root, engine: engine().reader });
+ // The engine could not be read: skipped now, tried again on the next prompt.
+ let engineUp = false;
+ const flaky = engine({ session: () => { if (!engineUp) throw new Error("ECONNREFUSED"); return { id: "ses_flaky_00001" }; } });
+ subject.sessionStarted({ sessionId: "ses_flaky_00001", root, engine: flaky.reader });
+ // A root that no longer exists is not archivable; nothing to warn about.
+ subject.sessionStarted({ sessionId: "ses_gone_000001", root: join(root, "missing"), engine: engine().reader });
+ await subject.settled();
+ expect(archiver.captures()).toEqual([`base ses_throws_0001 ${root} 0`]);
+ expect(logs.map((log) => [log.level, log.message, log.attributes?.step ?? log.attributes?.reason])).toEqual([
+ ["warn", "OmniRush project archive step failed", "base"],
+ ["warn", "OmniRush project archive could not read the engine for a session; its next prompt or turn tries again", "the engine session could not be read"],
+ ]);
+
+ engineUp = true;
+ subject.sessionStarted({ sessionId: "ses_flaky_00001", root, engine: flaky.reader });
+ await subject.settled();
+ expect(archiver.captures().at(-1)).toBe(`base ses_flaky_00001 ${root} 0`);
+ expect(logs.at(-1)).toMatchObject({ level: "warn", message: "OmniRush project archive step failed", attributes: { step: "drain", error: "Error: drain exploded" } });
+ // Resolved once: later prompts do not read the engine again.
+ subject.sessionStarted({ sessionId: "ses_flaky_00001", root, engine: flaky.reader });
+ await subject.settled();
+ expect(flaky.reads).toEqual({ session: 2, messages: 1 });
+ });
+
+ test("after a restart the engine can still be starting: the session is resolved when its turn completes, and the turn's delta is not lost", async () => {
+ const archiver = new FakeArchiver();
+ const { subject, logs } = lifecycle(archiver);
+ const root = await tempDir("root");
+ // The previous app run archived the base and turns 1 to 7.
+ archiver.base = async () => skipped("exists");
+ let engineUp = false;
+ const slow = engine({
+ session: () => {
+ if (!engineUp) throw new Error("TimeoutError: the engine did not answer");
+ return { id: "ses_restart_0001" };
+ },
+ messages: () => messages(7, true),
+ });
+ subject.start();
+ subject.sessionStarted({ sessionId: "ses_restart_0001", root, engine: slow.reader });
+ await subject.settled();
+ expect(archiver.captures()).toEqual([]);
+ expect(logs.map((log) => log.attributes?.reason)).toEqual(["the engine session could not be read"]);
+
+ // The engine came up and ran turn 8; the observer read its messages.
+ engineUp = true;
+ subject.turnCompleted("ses_restart_0001", messages(8));
+ await subject.settled();
+ expect(archiver.captures()).toEqual([`base ses_restart_0001 ${root} 8`, `delta ses_restart_0001 ${root} 8`]);
+ // The observer's messages give the count: the message list is not read again.
+ expect(slow.reads).toEqual({ session: 2, messages: 0 });
+
+ // Resolved: the next turn is an ordinary delta, with no engine read.
+ subject.turnCompleted("ses_restart_0001", messages(9));
+ subject.sessionStarted({ sessionId: "ses_restart_0001", root, engine: slow.reader });
+ await subject.settled();
+ expect(archiver.captures().slice(2)).toEqual([`delta ses_restart_0001 ${root} 9`]);
+ expect(slow.reads).toEqual({ session: 2, messages: 0 });
+ });
+
+ test("a session still unreadable when its turn completes stays pending; a child resolved at turn end is never archived", async () => {
+ const archiver = new FakeArchiver();
+ const { subject, logs } = lifecycle(archiver);
+ const root = await tempDir("root");
+ let engineUp = false;
+ const down = engine({ session: () => { if (!engineUp) throw new Error("ECONNREFUSED"); return { id: "ses_down_000001" }; } });
+ subject.sessionStarted({ sessionId: "ses_down_000001", root, engine: down.reader });
+ subject.turnCompleted("ses_down_000001", messages(1));
+ await subject.settled();
+ expect(archiver.captures()).toEqual([]);
+ expect(logs).toHaveLength(2);
+ // The changes are not lost: the first turn that can resolve the session captures the folder.
+ engineUp = true;
+ subject.turnCompleted("ses_down_000001", messages(2));
+ await subject.settled();
+ expect(archiver.captures()).toEqual([`base ses_down_000001 ${root} 2`, `delta ses_down_000001 ${root} 2`]);
+
+ let childUp = false;
+ const child = engine({ session: () => { if (!childUp) throw new Error("ECONNREFUSED"); return { id: "ses_child_0003", parentID: "ses_down_000001" }; } });
+ subject.sessionStarted({ sessionId: "ses_child_0003", root, engine: child.reader });
+ await subject.settled();
+ childUp = true;
+ subject.turnCompleted("ses_child_0003", messages(1));
+ subject.turnCompleted("ses_child_0003", messages(2));
+ await subject.settled();
+ expect(archiver.captures()).toHaveLength(2);
+ expect(child.reads).toEqual({ session: 2, messages: 0 });
+ });
+
+ test("with the real archiver: base at session start, a delta per changed turn, and the next app run resumes the upload", async () => {
+ const server = new FakeArchiveServer();
+ const root = await tempDir("project");
+ const git = (...args: string[]) => execFileAsync("git", ["-C", root, "-c", "user.name=t", "-c", "[email protected]", "-c", "commit.gpgsign=false", ...args]);
+ await git("init", "-q", "-b", "main");
+ await writeFile(join(root, "app.ts"), "export const app = 1;\n");
+ await git("add", "app.ts");
+ await git("commit", "-q", "-m", "initial");
+ const state = await tempDir("state");
+ const archiverFor = (now?: () => Date) => new SessionArchiver({
+ gatewayUrl: server.gatewayUrl,
+ accessToken: server.token,
+ fetch: server.respond,
+ stateDir: state,
+ retry: { baseMs: 1, maxMs: 2, attempts: 2 },
+ ...(now ? { now } : {}),
+ });
+
+ const first = lifecycle(archiverFor());
+ first.subject.start();
+ first.subject.sessionStarted({ sessionId: "ses_real_000001", root, engine: engine({ messages: () => messages(0, true) }).reader });
+ await first.subject.settled();
+ // Nothing changed during turn 1: no delta.
+ first.subject.turnCompleted("ses_real_000001", messages(1));
+ await first.subject.settled();
+ expect(server.objects().map((archive) => [archive.request.kind, archive.request.turn])).toEqual([["base", 0]]);
+
+ // Turn 2 changes the folder, but S3 is unreachable until the app restarts.
+ await mkdir(join(root, "src"));
+ await writeFile(join(root, "src/feature.ts"), "export const feature = true;\n");
+ server.putHook = () => "network";
+ first.subject.turnCompleted("ses_real_000001", messages(2));
+ await first.subject.settled();
+ await first.subject.stop();
+ expect(server.objects()).toHaveLength(1);
+
+ // The next app run, after the failed job's backoff.
+ server.putHook = null;
+ const later = new Date(Date.now() + 2 * 60_000);
+ const second = lifecycle(archiverFor(() => later));
+ second.subject.start();
+ await second.subject.settled();
+ const archives = server.objects();
+ expect(archives.map((archive) => [archive.request.kind, archive.request.sequence, archive.request.turn])).toEqual([["base", 0, 0], ["delta", 1, 2]]);
+ const delta = await openArchive(archives[1]!.object!);
+ expect(delta.map((member) => member.name)).toContain("src/feature.ts");
+ expect(manifestOf(delta)).toMatchObject({ kind: "delta", turn: 2 });
+ expect([...first.logs, ...second.logs].filter((log) => log.level === "warn" && !log.message.includes("deferred"))).toEqual([]);
+ });
+
+ test("with the real archiver: after an app restart whose engine is still starting, the first turn's change is archived with its turn", async () => {
+ const server = new FakeArchiveServer();
+ const root = await tempDir("project");
+ const git = (...args: string[]) => execFileAsync("git", ["-C", root, "-c", "user.name=t", "-c", "[email protected]", "-c", "commit.gpgsign=false", ...args]);
+ await git("init", "-q", "-b", "main");
+ await writeFile(join(root, "app.ts"), "export const app = 1;\n");
+ await git("add", "app.ts");
+ await git("commit", "-q", "-m", "initial");
+ const state = await tempDir("state");
+ const archiverFor = () => new SessionArchiver({ gatewayUrl: server.gatewayUrl, accessToken: server.token, fetch: server.respond, stateDir: state, retry: { baseMs: 1, maxMs: 2, attempts: 2 } });
+
+ const first = lifecycle(archiverFor());
+ first.subject.start();
+ first.subject.sessionStarted({ sessionId: "ses_restarted_01", root, engine: engine({ messages: () => messages(0, true) }).reader });
+ await first.subject.settled();
+ await writeFile(join(root, "after.txt"), "after restart\n");
+ first.subject.turnCompleted("ses_restarted_01", messages(1));
+ await first.subject.settled();
+ await first.subject.stop();
+
+ // The next app run: the engine does not answer the session start's reads.
+ const second = lifecycle(archiverFor());
+ second.subject.start();
+ let engineUp = false;
+ const reads = engine({
+ session: () => {
+ if (!engineUp) throw new Error("TimeoutError: the engine did not answer");
+ return { id: "ses_restarted_01" };
+ },
+ messages: () => messages(1, true),
+ });
+ second.subject.sessionStarted({ sessionId: "ses_restarted_01", root, engine: reads.reader });
+ await second.subject.settled();
+ engineUp = true;
+ await writeFile(join(root, "after.txt"), "after restart 2\n");
+ second.subject.turnCompleted("ses_restarted_01", messages(2));
+ await second.subject.settled();
+
+ const archives = server.objects();
+ expect(archives.map((archive) => [archive.request.kind, archive.request.sequence, archive.request.turn])).toEqual([["base", 0, 0], ["delta", 1, 1], ["delta", 2, 2]]);
+ const latest = await openArchive(archives[2]!.object!);
+ expect(latest.find((member) => member.name === "after.txt")!.content.toString()).toBe("after restart 2\n");
+ expect(manifestOf(latest)).toMatchObject({ kind: "delta", turn: 2 });
+ });
+});
diff --git a/apps/server/src/session-archive/lifecycle.ts b/apps/server/src/session-archive/lifecycle.ts
new file mode 100644
index 00000000..892878f1
--- /dev/null
+++ b/apps/server/src/session-archive/lifecycle.ts
@@ -0,0 +1,331 @@
+/**
+ * The project archive's place in the embedded server's session lifecycle
+ * (README "Wiring"). Every method returns at once: engine reads and captures
+ * run in the background, a bounded number at a time (one by default), and one
+ * session's steps always run in call order. Nothing here throws into the
+ * request path; an unexpected failure costs one warn line.
+ */
+import { realpath } from "node:fs/promises";
+
+import type { CaptureResult, DrainResult, SessionArchiver } from "./index.js";
+
+export type ProjectArchiver = Pick<SessionArchiver, "captureBase" | "captureDelta" | "drain" | "signOut" | "stop">;
+
+/** Engine reads for one session, resolving to the parsed JSON, or null when it cannot be read. */
+export type ArchiveEngineReads = {
+ /** The session record (v1 `/session/:id`, v2 `/api/session/:id`). */
+ session(): Promise<unknown>;
+ /** The session's messages in order (v1 `/session/:id/message`, v2 `/api/session/:id/context`). */
+ messages(): Promise<unknown>;
+};
+
+export type ArchiveLifecycleLog = (level: "info" | "warn", message: string, attributes?: Record<string, unknown>) => void;
+
+export type ProjectArchiveLifecycleOptions = {
+ archiver: ProjectArchiver;
+ /** An account is connected and OMNIRUSH_ARCHIVE_ENABLED is not off. */
+ enabled: boolean;
+ log: ArchiveLifecycleLog;
+ /** Session steps (engine reads plus a capture) running at once. */
+ concurrency?: number;
+ /** While archiving is off for the account (428, 503 archive_disabled), consent is checked again at most this often. */
+ consentRecheckMs?: number;
+ /** Tests. */
+ now?: () => number;
+};
+
+const DEFAULT_CONSENT_RECHECK_MS = 10 * 60_000;
+
+/** OMNIRUSH_ARCHIVE_ENABLED: on unless set to 0, false, no or off. */
+export function projectArchiveEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+ return !["0", "false", "no", "off"].includes((env.OMNIRUSH_ARCHIVE_ENABLED ?? "").trim().toLowerCase());
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function messageInfo(message: Record<string, unknown>): Record<string, unknown> {
+ return isRecord(message.info) ? message.info : message;
+}
+
+/** An assistant message that ended: a completion time, a finish reason, an error, or a finish part (v1 and v2 shapes). */
+export function isFinishedAssistantMessage(message: Record<string, unknown>): boolean {
+ const info = messageInfo(message);
+ if (isRecord(info.time) && (typeof info.time.completed === "number" || typeof info.time.completed === "string")) return true;
+ if (typeof info.finish === "string" || info.error != null) return true;
+ const parts = Array.isArray(message.parts) ? message.parts : Array.isArray(info.content) ? info.content : [];
+ return parts.some((part) => isRecord(part) && ["step-finish", "finish", "error"].includes(String(part.type)));
+}
+
+/**
+ * Completed turns in an engine message list: prompts answered by an assistant
+ * message that ended (several assistant steps of one turn count once). Each
+ * completed turn adds one, so the number strictly increases from one turn to
+ * the next and survives app restarts. Null when the list could not be read.
+ */
+export function completedTurnCount(messages: unknown): number | null {
+ if (!Array.isArray(messages)) return null;
+ let turns = 0;
+ let awaitingReply = false;
+ for (const message of messages) {
+ if (!isRecord(message)) continue;
+ const info = messageInfo(message);
+ const role = info.role ?? info.type;
+ if (role === "user") {
+ awaitingReply = true;
+ } else if (role === "assistant" && awaitingReply && isFinishedAssistantMessage(message)) {
+ turns += 1;
+ awaitingReply = false;
+ }
+ }
+ return turns;
+}
+
+/** The parent of a session record: a string for a child (sub-agent) session, null for a root one, undefined when unreadable. */
+function parentSessionId(session: unknown): string | null | undefined {
+ if (!isRecord(session)) return undefined;
+ const info = isRecord(session.info) ? session.info : session;
+ const parent = info.parentID ?? info.parentId ?? info.parent_id;
+ return typeof parent === "string" && parent ? parent : null;
+}
+
+function errorSummary(error: unknown): string {
+ return error instanceof Error ? `${error.name}: ${error.message}` : "unknown error";
+}
+
+/** What this app run knows about a session handed to captureBase. */
+type SessionRecord = {
+ /** The real path of the session root once resolved; null when deltas are pointless (child, not archivable, stopped) or not known yet. */
+ root: string | null;
+ /**
+ * Where the start step reads the engine, until one read succeeded. While
+ * it is set the session is unresolved (the engine may still be starting
+ * after an app restart), and the next prompt or completed turn resolves it.
+ */
+ start: { root: string; engine: ArchiveEngineReads } | null;
+ /** A start step is queued or running. */
+ starting: boolean;
+};
+
+export class ProjectArchiveLifecycle {
+ private readonly archiver: ProjectArchiver;
+ private readonly log: ArchiveLifecycleLog;
+ private readonly concurrency: number;
+ private readonly consentRecheckMs: number;
+ private readonly now: () => number;
+ private readonly enabled: boolean;
+ private signedOut = false;
+ private stopped = false;
+ /** Archiving is off for the account until then (428 / 503 archive_disabled). */
+ private consentOffUntil = 0;
+ /** Sessions handed to captureBase in this app run. */
+ private readonly sessions = new Map<string, SessionRecord>();
+ private readonly tails = new Map<string, Promise<void>>();
+ /** Drains and the start-up clear, for settled(). */
+ private readonly background = new Set<Promise<void>>();
+ private running = 0;
+ private readonly waiting: Array<() => void> = [];
+
+ constructor(options: ProjectArchiveLifecycleOptions) {
+ this.archiver = options.archiver;
+ this.enabled = options.enabled;
+ this.log = options.log;
+ this.concurrency = Math.max(1, options.concurrency ?? 1);
+ this.consentRecheckMs = options.consentRecheckMs ?? DEFAULT_CONSENT_RECHECK_MS;
+ this.now = options.now ?? Date.now;
+ }
+
+ private get active(): boolean {
+ return this.enabled && !this.signedOut && !this.stopped;
+ }
+
+ private get consentOff(): boolean {
+ return this.now() < this.consentOffUntil;
+ }
+
+ /**
+ * App start. With an account, resumes the uploads the last run left
+ * unfinished. Without one (signed out, or archiving turned off on this
+ * device), removes whatever a previous run left: nothing queued under an
+ * account may be uploaded later.
+ */
+ start(): void {
+ if (this.enabled) this.kick();
+ else this.track(this.archiver.signOut().catch((error: unknown) => this.warn("clear", error)));
+ }
+
+ /**
+ * A prompt was dispatched on a local session. The first time per app run,
+ * a root session gets its base archive with the number of turns it has
+ * already completed; child (sub-agent) sessions are never archived.
+ */
+ sessionStarted(input: { sessionId: string; root: string; engine: ArchiveEngineReads }): void {
+ if (!this.active || this.consentOff) return;
+ const known = this.sessions.get(input.sessionId);
+ // Resolved, or its start step is still queued: nothing to add.
+ if (known && (!known.start || known.starting)) return;
+ // New, or unresolved because the engine could not be read: (re)try with this prompt's reads.
+ const record: SessionRecord = known ?? { root: null, start: null, starting: false };
+ record.start = { root: input.root, engine: input.engine };
+ record.starting = true;
+ this.sessions.set(input.sessionId, record);
+ this.schedule(input.sessionId, "base", async () => {
+ try {
+ if (this.sessions.get(input.sessionId) === record && record.start) await this.resolve(input.sessionId, record, null);
+ } finally {
+ record.starting = false;
+ }
+ });
+ }
+
+ /**
+ * The session settled after a turn. `messages` are the engine's messages
+ * the observer read at that point; the delta carries their completed-turn
+ * count, and the archiver skips it when nothing changed. A session whose
+ * start could not read the engine (after an app restart the engine can
+ * take a minute to answer) is resolved here first, so the turn is not lost.
+ */
+ turnCompleted(sessionId: string, messages: unknown): void {
+ const record = this.sessions.get(sessionId);
+ if (!this.active || this.consentOff || !record) return;
+ const turns = completedTurnCount(messages);
+ if (turns === null) return;
+ this.schedule(sessionId, "delta", async () => {
+ if (this.sessions.get(sessionId) !== record) return;
+ if (record.start && !(await this.resolve(sessionId, record, turns))) return;
+ if (!record.root || this.sessions.get(sessionId) !== record || this.consentOff) return;
+ const result = await this.archiver.captureDelta(sessionId, record.root, turns);
+ if (result.status === "skipped" && result.reason === "stopped") record.root = null;
+ this.settle(result);
+ });
+ }
+
+ /** The session was deleted: nothing to capture, the queue keeps uploading. */
+ sessionEnded(sessionId: string): void {
+ this.sessions.delete(sessionId);
+ this.kick();
+ }
+
+ /**
+ * The account signed out or was invalidated: nothing is captured or
+ * uploaded any more, uploads in flight are aborted and every queued
+ * archive and session record is deleted.
+ */
+ async signOut(): Promise<void> {
+ this.signedOut = true;
+ this.sessions.clear();
+ await this.archiver.signOut().catch((error: unknown) => this.warn("sign-out", error));
+ }
+
+ /** Server shutdown: no new steps; the queue stays on disk for the next start. */
+ async stop(): Promise<void> {
+ this.stopped = true;
+ await this.archiver.stop().catch((error: unknown) => this.warn("stop", error));
+ }
+
+ /** Resolves once every scheduled step and drain has finished (tests). */
+ async settled(): Promise<void> {
+ while (this.tails.size > 0 || this.background.size > 0) await Promise.all([...this.tails.values(), ...this.background]);
+ }
+
+ /**
+ * The start step: is it a root session (child sessions are never
+ * archived), at which real path, and its base with `turns` completed turns
+ * (read from the engine when null). The base is a no-op ("exists") when an
+ * earlier app run captured it. False while the engine cannot be read: the
+ * session stays unresolved for its next prompt or completed turn.
+ */
+ private async resolve(sessionId: string, record: SessionRecord, turns: number | null): Promise<boolean> {
+ const start = record.start;
+ if (!start) return true;
+ const parent = parentSessionId(await start.engine.session().catch(() => null));
+ if (parent === undefined) return this.unresolved(sessionId, "the engine session could not be read");
+ if (parent !== null) {
+ record.start = null;
+ return true;
+ }
+ const root = await realpath(start.root).catch(() => null);
+ if (!root) {
+ record.start = null;
+ return true;
+ }
+ const count = turns ?? completedTurnCount(await start.engine.messages().catch(() => null));
+ if (count === null) return this.unresolved(sessionId, "the engine messages could not be read");
+ record.start = null;
+ record.root = root;
+ const result = await this.archiver.captureBase(sessionId, root, count);
+ if (result.status === "skipped" && result.reason === "disabled") this.sessions.delete(sessionId);
+ if (result.status === "skipped" && (result.reason === "not_archivable" || result.reason === "stopped")) record.root = null;
+ this.settle(result);
+ return true;
+ }
+
+ private unresolved(sessionId: string, reason: string): false {
+ this.log("warn", "OmniRush project archive could not read the engine for a session; its next prompt or turn tries again", { sessionId, reason });
+ return false;
+ }
+
+ private settle(result: CaptureResult): void {
+ if (result.status === "queued") {
+ this.consentOffUntil = 0;
+ this.kick();
+ } else if (result.reason === "disabled") {
+ this.archivingOff();
+ }
+ }
+
+ /** Off quietly: no capture, consent check or upload until the recheck time (or the next app start). */
+ private archivingOff(): void {
+ this.consentOffUntil = this.now() + this.consentRecheckMs;
+ }
+
+ /** Starts a drain unless one is running (the archiver coalesces them). */
+ private kick(): void {
+ if (!this.active || this.consentOff) return;
+ this.track(this.archiver.drain()
+ .then((result: DrainResult) => {
+ if (result.disabled) this.archivingOff();
+ })
+ .catch((error: unknown) => this.warn("drain", error)));
+ }
+
+ private track(work: Promise<void>): void {
+ this.background.add(work);
+ void work.finally(() => this.background.delete(work));
+ }
+
+ /** Runs `task` after the session's earlier steps, within the concurrency bound; never rejects. */
+ private schedule(sessionId: string, step: string, task: () => Promise<void>): void {
+ const previous = this.tails.get(sessionId) ?? Promise.resolve();
+ const run = previous.then(() => this.bounded(async () => {
+ if (!this.active) return;
+ try {
+ await task();
+ } catch (error) {
+ this.warn(step, error, sessionId);
+ }
+ }));
+ this.tails.set(sessionId, run);
+ void run.then(() => {
+ if (this.tails.get(sessionId) === run) this.tails.delete(sessionId);
+ });
+ }
+
+ private async bounded(task: () => Promise<void>): Promise<void> {
+ if (this.running < this.concurrency) this.running += 1;
+ else await new Promise<void>((resolvePromise) => this.waiting.push(resolvePromise));
+ try {
+ await task();
+ } finally {
+ // The slot passes straight to the next waiter, if any.
+ const next = this.waiting.shift();
+ if (next) next();
+ else this.running -= 1;
+ }
+ }
+
+ private warn(step: string, error: unknown, sessionId?: string): void {
+ this.log("warn", "OmniRush project archive step failed", { step, ...(sessionId ? { sessionId } : {}), error: errorSummary(error) });
+ }
+}
diff --git a/apps/server/src/session-archive/manifest.test.ts b/apps/server/src/session-archive/manifest.test.ts
new file mode 100644
index 00000000..3badd6ae
--- /dev/null
+++ b/apps/server/src/session-archive/manifest.test.ts
@@ -0,0 +1,279 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { execFile } from "node:child_process";
+import { chmod, mkdir, rename, rm, stat, symlink, utimes, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import {
+ ArchiveHashCache,
+ archiveEntry,
+ buildManifestBytes,
+ compareArchivePaths,
+ computeArchiveDelta,
+ emptyScanMetrics,
+ isArchiveCredentialPath,
+ readArchiveGit,
+ scanArchiveTree,
+ type ScannedEntry,
+} from "./manifest.js";
+import { cleanupTempDirs, tempDir } from "./test-helpers.js";
+
+const execFileAsync = promisify(execFile);
+
+afterEach(cleanupTempDirs);
+
+async function git(root: string, ...args: string[]): Promise<string> {
+ const { stdout } = await execFileAsync("git", ["-C", root, "-c", "user.name=t", "-c", "[email protected]", "-c", "commit.gpgsign=false", ...args]);
+ return stdout.trim();
+}
+
+const paths = (entries: readonly { path: string }[]) => entries.map((entry) => entry.path);
+
+describe("path order", () => {
+ test("compareArchivePaths is UTF-8 byte order", () => {
+ const alphabet = ["a", "b", "-", ".", "/", "é", "\u{ff21}", "\u{e000}", "\u{1f600}", "\u{10348}", "z", "0"];
+ const strings = Array.from({ length: 400 }, (_, index) => {
+ let text = "";
+ for (let char = 0; char < 1 + (index % 5); char += 1) text += alphabet[(index * 7 + char * 13) % alphabet.length];
+ return text;
+ });
+ const expected = [...strings].sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+ expect([...strings].sort(compareArchivePaths)).toEqual(expected);
+ expect(compareArchivePaths("a", "a/b")).toBeLessThan(0);
+ expect(compareArchivePaths("\u{ff21}", "\u{1f600}")).toBeLessThan(0);
+ });
+});
+
+describe("credential filter", () => {
+ test("git internals are exempt and node_modules is not a denial", () => {
+ expect(isArchiveCredentialPath(".env")).toBe(true);
+ expect(isArchiveCredentialPath("config/.env.production")).toBe(true);
+ expect(isArchiveCredentialPath("id_rsa")).toBe(true);
+ expect(isArchiveCredentialPath("certs/server.pem")).toBe(true);
+ expect(isArchiveCredentialPath(".ssh/config")).toBe(true);
+ expect(isArchiveCredentialPath(".git/refs/heads/token-fix")).toBe(false);
+ expect(isArchiveCredentialPath(".git/config")).toBe(false);
+ expect(isArchiveCredentialPath("node_modules/pkg/index.js")).toBe(false);
+ expect(isArchiveCredentialPath("src/app.ts")).toBe(false);
+ expect(isArchiveCredentialPath("dist/bundle.js")).toBe(false);
+ });
+});
+
+describe("scan", () => {
+ test("the whole folder: .git, ignored and build content present; exclusions counted", async () => {
+ const root = await tempDir("scan");
+ const state = join(root, ".omnirush-state");
+ await mkdir(join(root, ".git/refs/heads"), { recursive: true });
+ await writeFile(join(root, ".git/HEAD"), "ref: refs/heads/main\n");
+ await writeFile(join(root, ".git/refs/heads/token-fix"), "0".repeat(40));
+ await mkdir(join(root, "node_modules/js-tokens"), { recursive: true });
+ await writeFile(join(root, "node_modules/js-tokens/index.js"), "module.exports = 1;\n");
+ await mkdir(join(root, ".venv/bin"), { recursive: true });
+ await symlink("/usr/bin/python3", join(root, ".venv/bin/python"));
+ await mkdir(join(root, "dist"), { recursive: true });
+ await writeFile(join(root, "dist/out.js"), "built\n");
+ await mkdir(join(root, "build"), { recursive: true });
+ await writeFile(join(root, "build/app.o"), Buffer.from([0, 1, 2, 3]));
+ await writeFile(join(root, ".gitignore"), "node_modules/\ndist/\nbuild/\n.venv/\n");
+ await writeFile(join(root, ".env"), "SECRET=1\n");
+ await writeFile(join(root, "id_rsa"), "key\n");
+ await mkdir(join(root, ".ssh"));
+ await writeFile(join(root, ".ssh/config"), "Host x\n");
+ await mkdir(join(root, "__omnirush__"));
+ await mkdir(join(state, "omnirush-archive"), { recursive: true });
+ await writeFile(join(state, "omnirush-archive/state.json"), "{}");
+ await execFileAsync("mkfifo", [join(root, "pipe")]);
+ await mkdir(join(root, "locked/inner"), { recursive: true });
+ await writeFile(join(root, "locked/inner/file.txt"), "x");
+ await chmod(join(root, "locked"), 0o000);
+ try {
+ const { entries, excluded } = await scanArchiveTree(root, { excludedDirs: [state] });
+ const listed = paths(entries);
+ for (const present of [".git", ".git/HEAD", ".git/refs/heads/token-fix", "node_modules/js-tokens/index.js", ".venv/bin/python", "dist/out.js", "build/app.o", ".gitignore", ".ssh", "locked"]) {
+ expect(listed).toContain(present);
+ }
+ for (const absent of [".env", "id_rsa", ".ssh/config", "__omnirush__", ".omnirush-state", "pipe", "locked/inner"]) {
+ expect(listed).not.toContain(absent);
+ }
+ const running = typeof process.getuid === "function" ? process.getuid() : -1;
+ expect(excluded).toEqual({ credential: 3, special: 1, app_state: 1, reserved: 1, unreadable: running === 0 ? 0 : 1, non_utf8: 0 });
+ expect(listed).toEqual([...listed].sort(compareArchivePaths));
+ const link = entries.find((entry) => entry.path === ".venv/bin/python")!;
+ expect(link).toMatchObject({ type: "symlink", size: 0, sha256: null, target: "/usr/bin/python3" });
+ const dir = entries.find((entry) => entry.path === "dist")!;
+ expect(dir).toMatchObject({ type: "dir", size: 0, sha256: null });
+ const file = entries.find((entry) => entry.path === "build/app.o")!;
+ expect(file).toMatchObject({ type: "file", size: 4, sha256: "054edec1d0211f624fed0cbca9d4f9400b0e491c43742af2c5b0abebf0c990d8" });
+
+ const everything = await scanArchiveTree(root, { excludedDirs: [state], includeCredentialFiles: true });
+ expect(paths(everything.entries)).toEqual(expect.arrayContaining([".env", "id_rsa", ".ssh/config"]));
+ expect(everything.excluded.credential).toBe(0);
+ } finally {
+ await chmod(join(root, "locked"), 0o755);
+ }
+ });
+
+ test("names that are not valid UTF-8 are excluded, never decoded lossily", async () => {
+ const root = await tempDir("scan-bytes");
+ await writeFile(join(root, "ok.txt"), "x");
+ const bad = Buffer.concat([Buffer.from(`${root}/bad-`), Buffer.from([0xff, 0xfe]), Buffer.from(".txt")]);
+ let created = true;
+ try {
+ await writeFile(bad, "x");
+ } catch {
+ created = false; // APFS and most macOS volumes reject such names outright.
+ }
+ const { entries, excluded } = await scanArchiveTree(root);
+ expect(paths(entries)).toEqual(["ok.txt"]);
+ expect(excluded.non_utf8).toBe(created ? 1 : 0);
+ });
+
+ test("cache hits read no content; a writer that keeps mtime is still caught", async () => {
+ const root = await tempDir("scan-cache");
+ for (let index = 0; index < 20; index += 1) await writeFile(join(root, `f${index}.txt`), `content ${index}`);
+ const cache = new ArchiveHashCache();
+ const first = emptyScanMetrics();
+ await scanArchiveTree(root, { hashCache: cache, metrics: first });
+ expect(first.fileReads).toBe(20);
+ // Round trip through the JSON form, as between captures.
+ const text = [...cache.jsonChunks()].join("");
+ expect(JSON.parse(text).entries).toHaveLength(20);
+ const reloaded = ArchiveHashCache.fromText(text);
+ expect(reloaded.size).toBe(20);
+ const second = emptyScanMetrics();
+ const unchanged = await scanArchiveTree(root, { hashCache: reloaded, metrics: second });
+ expect(second).toMatchObject({ fileReads: 0, cacheHits: 20, bytesHashed: 0 });
+ const before = await stat(join(root, "f3.txt"));
+ await writeFile(join(root, "f3.txt"), "CONTENT 3");
+ await utimes(join(root, "f3.txt"), before.atime, before.mtime);
+ const third = emptyScanMetrics();
+ const changed = await scanArchiveTree(root, { hashCache: reloaded, metrics: third });
+ expect(third.fileReads).toBe(1);
+ const delta = computeArchiveDelta(unchanged.entries.map(archiveEntry), changed.entries);
+ expect(paths(delta.files)).toEqual(["f3.txt"]);
+ });
+});
+
+describe("delta", () => {
+ async function scan(root: string): Promise<ScannedEntry[]> {
+ return (await scanArchiveTree(root)).entries;
+ }
+
+ test("add, modify (content and mode), delete, rename and type changes", async () => {
+ const root = await tempDir("delta");
+ await writeFile(join(root, "keep.txt"), "same");
+ await writeFile(join(root, "edit.txt"), "before");
+ await writeFile(join(root, "run.sh"), "#!/bin/sh\n", { mode: 0o644 });
+ await writeFile(join(root, "gone.txt"), "bye");
+ await writeFile(join(root, "old-name.txt"), "moved");
+ await writeFile(join(root, "becomes-dir"), "file");
+ await mkdir(join(root, "becomes-file/sub"), { recursive: true });
+ await writeFile(join(root, "becomes-file/sub/x.txt"), "x");
+ await mkdir(join(root, "mode-dir"));
+ await symlink("keep.txt", join(root, "link"));
+ const baseline = (await scan(root)).map(archiveEntry);
+
+ expect(computeArchiveDelta(baseline, await scan(root))).toEqual({ files: [], deleted: [] });
+
+ await writeFile(join(root, "edit.txt"), "after!");
+ await chmod(join(root, "run.sh"), 0o755);
+ await rm(join(root, "gone.txt"));
+ await rename(join(root, "old-name.txt"), join(root, "new-name.txt"));
+ await rm(join(root, "becomes-dir"));
+ await mkdir(join(root, "becomes-dir"));
+ await writeFile(join(root, "becomes-dir/inside.txt"), "in");
+ await rm(join(root, "becomes-file"), { recursive: true });
+ await writeFile(join(root, "becomes-file"), "now a file");
+ await chmod(join(root, "mode-dir"), 0o700);
+ await rm(join(root, "link"));
+ await symlink("edit.txt", join(root, "link"));
+ await writeFile(join(root, "added.txt"), "new");
+
+ const delta = computeArchiveDelta(baseline, await scan(root));
+ expect(paths(delta.files)).toEqual(["added.txt", "becomes-dir", "becomes-dir/inside.txt", "becomes-file", "edit.txt", "link", "mode-dir", "new-name.txt", "run.sh"]);
+ expect(delta.deleted).toEqual(["becomes-file/sub", "becomes-file/sub/x.txt", "gone.txt", "old-name.txt"]);
+ expect(delta.files.find((entry) => entry.path === "becomes-dir")!.type).toBe("dir");
+ expect(delta.files.find((entry) => entry.path === "becomes-file")!.type).toBe("file");
+ expect(delta.files.find((entry) => entry.path === "link")!.target).toBe("edit.txt");
+ });
+
+ test("a baseline entry with a null hash (unstable) is always sent again", async () => {
+ const root = await tempDir("delta-unstable");
+ await writeFile(join(root, "a.txt"), "a");
+ const baseline = (await scan(root)).map((entry) => ({ ...archiveEntry(entry), sha256: null }));
+ expect(paths(computeArchiveDelta(baseline, await scan(root)).files)).toEqual(["a.txt"]);
+ });
+
+ test("changes inside .git (a new commit) are a delta", async () => {
+ const root = await tempDir("delta-git");
+ await git(root, "init", "-q", "-b", "main");
+ await writeFile(join(root, "a.txt"), "a");
+ await git(root, "add", "a.txt");
+ await git(root, "commit", "-q", "-m", "one");
+ const baseline = (await scan(root)).map(archiveEntry);
+ await git(root, "commit", "-q", "--allow-empty", "-m", "two");
+ const delta = computeArchiveDelta(baseline, await scan(root));
+ expect(delta.files.some((entry) => entry.path === ".git/refs/heads/main" || entry.path.startsWith(".git/objects/"))).toBe(true);
+ expect(delta.files.every((entry) => entry.path.startsWith(".git"))).toBe(true);
+ });
+});
+
+describe("manifest and git block", () => {
+ test("manifest JSON: key order, base without deleted, delta with deleted", () => {
+ const common = {
+ archiveId: "5d0c6f9e-1d8e-4b5c-9a53-0e8f2b7c1a44",
+ sessionId: "ses_manifest",
+ turn: 7,
+ createdAt: new Date("2026-09-23T10:15:30.123Z"),
+ label: "my-app",
+ marker: ".git",
+ git: { head: "a".repeat(40), branch: "main", remote: "https://github.com/acme/my-app.git", dirty: true },
+ files: [
+ { path: "current", type: "symlink" as const, mode: 493, size: 0, sha256: null, target: "releases/v2" },
+ { path: "src/new", type: "dir" as const, mode: 493, size: 0, sha256: null },
+ ],
+ excluded: { credential: 2, special: 0, app_state: 0, reserved: 0, unreadable: 0, non_utf8: 0 },
+ };
+ const base = JSON.parse(buildManifestBytes({ ...common, kind: "base", sequence: 0, parentArchiveId: null }).toString("utf8"));
+ expect(Object.keys(base)).toEqual(["schema", "kind", "archive_id", "session_id", "sequence", "turn", "created_at", "parent_archive_id", "workspace", "files", "excluded"]);
+ expect(base.created_at).toBe("2026-09-23T10:15:30.123Z");
+ expect(base.files[0]).toEqual({ path: "current", type: "symlink", mode: 493, size: 0, sha256: null, target: "releases/v2" });
+ expect(Object.keys(base.files[1])).toEqual(["path", "type", "mode", "size", "sha256"]);
+ const delta = JSON.parse(buildManifestBytes({ ...common, kind: "delta", sequence: 3, parentArchiveId: "0b1f0f7a-6f2e-4c8e-8d8a-3a4d2c9e7b10", deleted: ["src/old.ts"] }).toString("utf8"));
+ expect(delta.deleted).toEqual(["src/old.ts"]);
+ expect(Object.keys(delta).slice(-3)).toEqual(["files", "deleted", "excluded"]);
+ });
+
+ test("workspace.git: head, branch, origin without userinfo, dirty; null outside a repository", async () => {
+ const root = await tempDir("git-block");
+ expect(await readArchiveGit(root)).toBeNull();
+ await git(root, "init", "-q", "-b", "main");
+ expect(await readArchiveGit(root)).toEqual({ head: null, branch: "main", remote: null, dirty: false });
+ await writeFile(join(root, "a.txt"), "a");
+ await git(root, "add", "a.txt");
+ await git(root, "commit", "-q", "-m", "one");
+ await git(root, "remote", "add", "upstream", "https://example.com/upstream.git");
+ await git(root, "remote", "add", "origin", "https://user:[email protected]/acme/my-app.git");
+ const head = await git(root, "rev-parse", "HEAD");
+ expect(await readArchiveGit(root)).toEqual({ head, branch: "main", remote: "https://github.com/acme/my-app.git", dirty: false });
+ await writeFile(join(root, "untracked.txt"), "u");
+ expect((await readArchiveGit(root))!.dirty).toBe(true);
+ await git(root, "checkout", "-q", "--detach");
+ expect((await readArchiveGit(root))!.branch).toBeNull();
+ });
+
+ test("reading the git block does not rewrite .git/index (no spurious delta)", async () => {
+ const root = await tempDir("git-locks");
+ await git(root, "init", "-q", "-b", "main");
+ await writeFile(join(root, "a.txt"), "a");
+ await git(root, "add", "a.txt");
+ await git(root, "commit", "-q", "-m", "one");
+ // A touched tracked file makes a plain `git status` refresh and rewrite the index.
+ const later = new Date(Date.now() + 5_000);
+ await utimes(join(root, "a.txt"), later, later);
+ const before = (await scanArchiveTree(root)).entries.map(archiveEntry);
+ await readArchiveGit(root);
+ const after = await scanArchiveTree(root);
+ expect(computeArchiveDelta(before, after.entries)).toEqual({ files: [], deleted: [] });
+ });
+});
diff --git a/apps/server/src/session-archive/manifest.ts b/apps/server/src/session-archive/manifest.ts
new file mode 100644
index 00000000..14ffa31c
--- /dev/null
+++ b/apps/server/src/session-archive/manifest.ts
@@ -0,0 +1,741 @@
+/**
+ * Scanning a session root for the project archive (sections 5.2 to 5.8): the
+ * whole folder, `.git/` and ignored content included, minus the exclusions of
+ * 5.2; streaming SHA-256 with a (path, size, mtimeNs, ctimeNs, ino) cache;
+ * delta computation against the previous archive's entry list; and the
+ * `__omnirush__/manifest.json` document.
+ */
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { constants as fsConstants, type BigIntStats } from "node:fs";
+import { lstat, open, readdir, readlink, realpath } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
+
+import { clampCollectorBytes, isCollectorPathDenied, stripRemoteUserinfo } from "../workspace-collector.js";
+import { hintGarbageCollection } from "./files.js";
+
+export const ARCHIVE_SCHEMA = "omnirush.archive.v1";
+export const RESERVED_ROOT_NAME = "__omnirush__";
+const STAT_CONCURRENCY = 64;
+const HASH_CONCURRENCY = 6;
+const HASH_READ_BYTES = 128 * 1024;
+/** Bytes hashed, or entries inspected or hashed, between two garbage collection hints. */
+const GC_HINT_BYTES = 64 * 1024 * 1024;
+const GC_HINT_ENTRIES = 10_000;
+const MAX_LABEL_BYTES = 255;
+const GIT_TIMEOUT_MS = 15_000;
+/**
+ * Opens an entry for reading: never through a symlink in the last component
+ * (O_NOFOLLOW), and never blocking when a FIFO replaced the file after lstat
+ * (O_NONBLOCK, which regular files ignore; O_NOCTTY for a terminal). Callers
+ * fstat the handle and read only a regular file.
+ */
+export const OPEN_ENTRY_FLAGS =
+ fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0) | (fsConstants.O_NOCTTY ?? 0);
+
+export type ArchiveKind = "base" | "delta";
+export type ArchiveEntryType = "file" | "dir" | "symlink";
+
+/** One manifest `files` item (section 5.4). */
+export type ArchiveEntry = {
+ path: string;
+ type: ArchiveEntryType;
+ mode: number;
+ size: number;
+ sha256: string | null;
+ target?: string;
+};
+
+/** A scanned entry: the manifest fields plus what pass 2 and the hash cache need. */
+export type ScannedEntry = ArchiveEntry & {
+ /** Tar mtime: floor(mtimeMs / 1000), clamped at pack time. */
+ mtime: number;
+ /** `size:mtimeNs:ctimeNs:ino` from lstat: the hash cache key, and what pass 2 re-checks (size and mtimeNs). */
+ statKey: string;
+ /** st_dev from lstat: with the ino in statKey, the identity pass 2 requires of the file it reads. */
+ dev: number;
+};
+
+/** The prefix of a stat key that pass 2 compares against fstat: size and mtimeNs. */
+export function statKeyPrefix(size: bigint | number, mtimeNs: bigint): string {
+ return `${size}:${mtimeNs}:`;
+}
+
+/** Whether `stats` (an fstat) describe the file pass 1 lstat'ed for `entry`: same st_dev and st_ino. */
+export function isSameFileIdentity(entry: ScannedEntry, stats: BigIntStats): boolean {
+ return entry.dev === Number(stats.dev) && entry.statKey.endsWith(`:${stats.ino}`);
+}
+
+export type ExcludedCounts = {
+ credential: number;
+ special: number;
+ app_state: number;
+ reserved: number;
+ unreadable: number;
+ non_utf8: number;
+};
+
+export type ArchiveGit = { head: string | null; branch: string | null; remote: string | null; dirty: boolean };
+
+export type ArchiveManifest = {
+ schema: typeof ARCHIVE_SCHEMA;
+ kind: ArchiveKind;
+ archive_id: string;
+ session_id: string;
+ sequence: number;
+ turn: number;
+ created_at: string;
+ parent_archive_id: string | null;
+ workspace: { label: string; marker: string; git: ArchiveGit | null };
+ files: ArchiveEntry[];
+ deleted?: string[];
+ excluded: ExcludedCounts;
+};
+
+export function emptyExcludedCounts(): ExcludedCounts {
+ return { credential: 0, special: 0, app_state: 0, reserved: 0, unreadable: 0, non_utf8: 0 };
+}
+
+/**
+ * Orders paths by their UTF-8 bytes (section 5.4) without encoding them:
+ * UTF-16 order differs from code point order only where a surrogate meets a
+ * unit in U+E000..U+FFFF, so the first differing units are remapped.
+ */
+export function compareArchivePaths(left: string, right: string): number {
+ const length = Math.min(left.length, right.length);
+ for (let index = 0; index < length; index += 1) {
+ let a = left.charCodeAt(index);
+ let b = right.charCodeAt(index);
+ if (a === b) continue;
+ if (a >= 0xd800) a = a >= 0xe000 ? a - 0x800 : a + 0x2000;
+ if (b >= 0xd800) b = b >= 0xe000 ? b - 0x800 : b + 0x2000;
+ return a - b;
+ }
+ return left.length - right.length;
+}
+
+/**
+ * True when a file or symlink must be left out of the archive (section 5.3):
+ * the collector's credential denylist, with git internals exempt and
+ * `node_modules` not counted as a denial.
+ */
+export function isArchiveCredentialPath(relPath: string): boolean {
+ const parts = relPath.split("/");
+ if (parts.some((part) => part.toLowerCase() === ".git")) return false;
+ const rest = parts.filter((part) => part.toLowerCase() !== "node_modules");
+ return rest.length > 0 && isCollectorPathDenied(rest.join("/"));
+}
+
+/** workspace.label: the root's basename, at most 255 UTF-8 bytes. */
+export function archiveLabel(root: string): string {
+ return clampCollectorBytes(basename(resolve(root)), MAX_LABEL_BYTES).text;
+}
+
+// --- hash cache -------------------------------------------------------------------
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+/**
+ * Iterates the entry rows of a state document written one JSON row per line
+ * (`{"v":..,"entries":[` / rows / `]}`) without materialising the whole
+ * parsed array next to the text.
+ */
+export function* jsonLineRows(text: string): Generator<unknown> {
+ let start = 0;
+ while (start < text.length) {
+ let end = text.indexOf("\n", start);
+ if (end === -1) end = text.length;
+ let line = text.slice(start, end);
+ start = end + 1;
+ if (line.endsWith(",")) line = line.slice(0, -1);
+ if (!line.startsWith("[") && !line.startsWith("{\"path\"")) continue;
+ try {
+ yield JSON.parse(line);
+ } catch {
+ // A damaged row is skipped; the caller decides whether that matters.
+ }
+ }
+}
+
+function* jsonLineDocument<T>(header: string, rows: Iterable<T>, serialise: (row: T) => string, rowsPerChunk = 2_000): Generator<string> {
+ yield header;
+ let batch: string[] = [];
+ let first = true;
+ for (const row of rows) {
+ batch.push(serialise(row));
+ if (batch.length >= rowsPerChunk) {
+ yield `${first ? "" : ","}\n${batch.join(",\n")}`;
+ first = false;
+ batch = [];
+ }
+ }
+ if (batch.length > 0) yield `${first ? "" : ","}\n${batch.join(",\n")}`;
+ yield "\n]}\n";
+}
+
+/**
+ * path -> (size, mtimeNs, ctimeNs, ino, sha256), shared by the sessions of one
+ * root. A hit requires the whole stat key to match, so a writer that
+ * preserves mtime is still caught by ctime or inode. Rows loaded from disk
+ * are packed into one string (sha256 then the stat key); rows of the current
+ * scan are the scanned entries themselves, so a 200k-entry scan adds no
+ * strings. During a scan, rows move from `previous` to `current`; paths the
+ * scan did not see are dropped at commitScan() without a second index.
+ */
+export class ArchiveHashCache {
+ /** Rows not yet seen by the running scan: packed strings from disk, or entries of the previous scan. */
+ private previous = new Map<string, string | ScannedEntry>();
+ private current = new Map<string, ScannedEntry>();
+ private dirty = false;
+
+ /** Loads the text written by jsonChunks(); anything unreadable is an empty cache. */
+ static fromText(text: string | null): ArchiveHashCache {
+ const cache = new ArchiveHashCache();
+ if (!text?.startsWith('{"v":2,')) return cache;
+ for (const row of jsonLineRows(text)) {
+ if (!Array.isArray(row) || row.length !== 3) continue;
+ const [path, statKey, sha256] = row;
+ if (typeof path !== "string" || typeof statKey !== "string" || typeof sha256 !== "string" || !SHA256_HEX.test(sha256)) continue;
+ cache.previous.set(path, [sha256, statKey].join(""));
+ }
+ return cache;
+ }
+
+ get changed(): boolean {
+ return this.dirty;
+ }
+
+ get size(): number {
+ return this.previous.size + this.current.size;
+ }
+
+ /** The cached SHA-256 when the entry's stat key matches; the scan sets entry.sha256 from it. */
+ lookup(entry: ScannedEntry): string | null {
+ const held = this.previous.get(entry.path);
+ if (held === undefined) return null;
+ this.previous.delete(entry.path);
+ const sha256 = typeof held === "string"
+ ? (held.length === 64 + entry.statKey.length && held.endsWith(entry.statKey) ? held.slice(0, 64) : null)
+ : (held.statKey === entry.statKey ? held.sha256 : null);
+ if (!sha256) {
+ this.dirty = true;
+ return null;
+ }
+ this.current.set(entry.path, entry);
+ return sha256;
+ }
+
+ /** Records a freshly hashed entry (entry.sha256 already set). */
+ remember(entry: ScannedEntry): void {
+ this.previous.delete(entry.path);
+ this.current.set(entry.path, entry);
+ this.dirty = true;
+ }
+
+ forget(path: string): void {
+ const had = this.previous.delete(path) || this.current.delete(path);
+ if (had) this.dirty = true;
+ }
+
+ /** Ends a scan: paths the scan did not see are dropped. */
+ commitScan(): void {
+ if (this.previous.size > 0) this.dirty = true;
+ this.previous = this.current;
+ this.current = new Map();
+ }
+
+ /** The cache as JSON text pieces, one row per line, so it is never one giant string. */
+ jsonChunks(): Generator<string> {
+ this.dirty = false;
+ // A path is in exactly one of the two maps (lookup and remember move it to current).
+ const { previous, current } = this;
+ function* rows(): Generator<string> {
+ for (const [path, held] of previous) {
+ if (typeof held === "string") yield JSON.stringify([path, held.slice(64), held.slice(0, 64)]);
+ else if (held.sha256) yield JSON.stringify([path, held.statKey, held.sha256]);
+ }
+ for (const [path, entry] of current) if (entry.sha256) yield JSON.stringify([path, entry.statKey, entry.sha256]);
+ }
+ return jsonLineDocument('{"v":2,"entries":[', rows(), (row) => row);
+ }
+}
+
+/** The baseline document: the full entry list after an archive, one entry per line; `unstable` paths get a null hash. */
+export function baselineChunks(entries: readonly ArchiveEntry[], unstable: ReadonlySet<string> = new Set()): Generator<string> {
+ return jsonLineDocument('{"v":1,"entries":[', entries, (entry) => {
+ const out = archiveEntry(entry);
+ if (unstable.has(entry.path)) out.sha256 = null;
+ return JSON.stringify(out);
+ });
+}
+
+const ENTRY_TYPES: ReadonlySet<string> = new Set(["file", "dir", "symlink"]);
+
+/** Parses a baseline document; null when it is not one (the session cannot compute deltas any more). */
+export function parseBaselineText(text: string | null): ArchiveEntry[] | null {
+ if (!text?.startsWith('{"v":1,')) return null;
+ const entries: ArchiveEntry[] = [];
+ for (const row of jsonLineRows(text)) {
+ if (typeof row !== "object" || row === null) return null;
+ const path = "path" in row ? row.path : undefined;
+ const type = "type" in row ? row.type : undefined;
+ const mode = "mode" in row ? row.mode : undefined;
+ const size = "size" in row ? row.size : undefined;
+ const sha256 = "sha256" in row ? row.sha256 : undefined;
+ const target = "target" in row ? row.target : undefined;
+ if (typeof path !== "string" || typeof type !== "string" || !ENTRY_TYPES.has(type) || typeof mode !== "number" || typeof size !== "number") return null;
+ if (sha256 !== null && typeof sha256 !== "string") return null;
+ if (target !== undefined && typeof target !== "string") return null;
+ const entry: ArchiveEntry = { path, type: type === "file" ? "file" : type === "dir" ? "dir" : "symlink", mode, size, sha256 };
+ if (target !== undefined) entry.target = target;
+ entries.push(entry);
+ }
+ return entries;
+}
+
+// --- scanning -----------------------------------------------------------------------
+
+/** Work counters for tests and profiling. */
+export type ScanMetrics = { stats: number; fileReads: number; bytesHashed: number; cacheHits: number };
+
+export function emptyScanMetrics(): ScanMetrics {
+ return { stats: 0, fileReads: 0, bytesHashed: 0, cacheHits: 0 };
+}
+
+export type ScanOptions = {
+ /** Absolute app state/temp/data directories; pruned (and counted as app_state) when under the root. */
+ excludedDirs?: readonly string[];
+ /** archiveIncludeCredentialFiles: turns the credential filter off entirely. */
+ includeCredentialFiles?: boolean;
+ hashCache?: ArchiveHashCache;
+ statConcurrency?: number;
+ hashConcurrency?: number;
+ metrics?: ScanMetrics;
+};
+
+export type ScanResult = { entries: ScannedEntry[]; excluded: ExcludedCounts };
+
+/**
+ * Runs `operation` over `items` with at most `limit` in flight. The workers
+ * pull plain data items, so a 200k-entry level costs 200k small objects, not
+ * 200k suspended async frames.
+ */
+async function forEachBounded<T>(items: readonly T[], limit: number, operation: (item: T) => Promise<void>): Promise<void> {
+ let next = 0;
+ const worker = async (): Promise<void> => {
+ while (next < items.length) {
+ const item = items[next]!;
+ next += 1;
+ await operation(item);
+ }
+ };
+ await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, worker));
+}
+
+const NAME_DECODER = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+
+function decodeName(raw: Buffer): string | null {
+ try {
+ return NAME_DECODER.decode(raw);
+ } catch {
+ return null;
+ }
+}
+
+function portable(path: string): string {
+ return sep === "/" ? path : path.split(sep).join("/");
+}
+
+/** The excluded directories that lie strictly under the root, as root-relative paths. */
+async function excludedRelativeDirs(root: string, dirs: readonly string[]): Promise<Set<string>> {
+ const rootForms = new Set([resolve(root)]);
+ try {
+ rootForms.add(await realpath(root));
+ } catch {
+ // The scan reports an unreadable root itself.
+ }
+ const result = new Set<string>();
+ for (const dir of dirs) {
+ const forms = new Set([resolve(dir)]);
+ try {
+ forms.add(await realpath(dir));
+ } catch {
+ // Not created yet: only its resolved form can be under the root.
+ }
+ for (const form of forms) {
+ for (const rootForm of rootForms) {
+ const rel = relative(rootForm, form);
+ const outside = rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+ if (rel && !outside) result.add(portable(rel));
+ }
+ }
+ }
+ return result;
+}
+
+// Strings kept per entry are built with join(), which yields one flat string;
+// template concatenation in JSC yields a rope that keeps every piece alive,
+// roughly doubling the per-entry cost on a 200k-entry tree.
+function statFields(stats: BigIntStats) {
+ return {
+ mode: Number(stats.mode & 0o7777n),
+ mtime: Number(stats.mtimeNs / 1_000_000_000n),
+ statKey: [stats.size, stats.mtimeNs, stats.ctimeNs, stats.ino].join(":"),
+ dev: Number(stats.dev),
+ };
+}
+
+/** SHA-256 of the first `size` bytes (the lstat size): pass 2 streams exactly those and detects any change. */
+async function hashFile(absolute: string, size: number, buffer: Buffer, metrics: ScanMetrics): Promise<string | null> {
+ let handle: Awaited<ReturnType<typeof open>>;
+ try {
+ handle = await open(absolute, OPEN_ENTRY_FLAGS);
+ } catch {
+ return null;
+ }
+ metrics.fileReads += 1;
+ if (metrics.fileReads % GC_HINT_ENTRIES === 0) hintGarbageCollection();
+ try {
+ if (!(await handle.stat()).isFile()) return null;
+ const hash = createHash("sha256");
+ let remaining = size;
+ while (remaining > 0) {
+ const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, remaining), null);
+ if (bytesRead === 0) break;
+ hash.update(buffer.subarray(0, bytesRead));
+ if (Math.floor((metrics.bytesHashed + bytesRead) / GC_HINT_BYTES) > Math.floor(metrics.bytesHashed / GC_HINT_BYTES)) hintGarbageCollection();
+ metrics.bytesHashed += bytesRead;
+ remaining -= bytesRead;
+ }
+ return hash.digest("hex");
+ } catch {
+ return null;
+ } finally {
+ await handle.close().catch(() => undefined);
+ }
+}
+
+/**
+ * Pass 1: walks the root with lstat (never following a symlink), applies the
+ * exclusions of section 5.2 and hashes every file whose cache key changed.
+ * Entries come back sorted by UTF-8 bytes.
+ */
+export async function scanArchiveTree(root: string, options: ScanOptions = {}): Promise<ScanResult> {
+ const concurrency = options.statConcurrency ?? STAT_CONCURRENCY;
+ const metrics = options.metrics ?? emptyScanMetrics();
+ const cache = options.hashCache;
+ const excluded = emptyExcludedCounts();
+ const prunedDirs = await excludedRelativeDirs(root, options.excludedDirs ?? []);
+ const includeCredentials = options.includeCredentialFiles === true;
+ const entries: ScannedEntry[] = [];
+ const toHash: ScannedEntry[] = [];
+
+ const inspect = async (relDir: string, absDir: string, name: string, next: Array<{ rel: string; abs: string }>): Promise<void> => {
+ const rel = relDir ? [relDir, name].join("/") : name;
+ const abs = join(absDir, name);
+ let stats: BigIntStats;
+ try {
+ stats = await lstat(abs, { bigint: true });
+ metrics.stats += 1;
+ if (metrics.stats % GC_HINT_ENTRIES === 0) hintGarbageCollection();
+ } catch {
+ excluded.unreadable += 1;
+ return;
+ }
+ if (stats.isDirectory()) {
+ if (prunedDirs.has(rel)) {
+ excluded.app_state += 1;
+ return;
+ }
+ entries.push({ path: rel, type: "dir", size: 0, sha256: null, ...statFields(stats) });
+ next.push({ rel, abs });
+ return;
+ }
+ if (!stats.isFile() && !stats.isSymbolicLink()) {
+ excluded.special += 1;
+ return;
+ }
+ if (!includeCredentials && isArchiveCredentialPath(rel)) {
+ excluded.credential += 1;
+ return;
+ }
+ if (stats.isSymbolicLink()) {
+ let target: string | null;
+ try {
+ target = decodeName(await readlink(abs, { encoding: "buffer" }));
+ } catch {
+ excluded.unreadable += 1;
+ return;
+ }
+ if (target === null) {
+ excluded.non_utf8 += 1;
+ return;
+ }
+ entries.push({ path: rel, type: "symlink", size: 0, sha256: null, target, ...statFields(stats) });
+ return;
+ }
+ const entry: ScannedEntry = { path: rel, type: "file", size: Number(stats.size), sha256: null, ...statFields(stats) };
+ const cached = cache?.lookup(entry) ?? null;
+ if (cached) {
+ entry.sha256 = cached;
+ metrics.cacheHits += 1;
+ } else {
+ toHash.push(entry);
+ }
+ entries.push(entry);
+ };
+
+ // Breadth-first, one directory level at a time: list the level's
+ // directories, then lstat every name found, both with bounded concurrency.
+ let level: Array<{ rel: string; abs: string }> = [{ rel: "", abs: resolve(root) }];
+ while (level.length > 0) {
+ const names: Array<{ relDir: string; absDir: string; name: string }> = [];
+ await forEachBounded(level, concurrency, async (dir) => {
+ let raw: Buffer[];
+ try {
+ raw = await readdir(dir.abs, { encoding: "buffer" });
+ } catch (error) {
+ if (!dir.rel) throw error;
+ // The directory itself is recorded; its content is not.
+ excluded.unreadable += 1;
+ return;
+ }
+ for (const bytes of raw) {
+ const name = decodeName(bytes);
+ if (name === null) excluded.non_utf8 += 1;
+ else if (!dir.rel && name === RESERVED_ROOT_NAME) excluded.reserved += 1;
+ else names.push({ relDir: dir.rel, absDir: dir.abs, name });
+ }
+ });
+ const next: Array<{ rel: string; abs: string }> = [];
+ await forEachBounded(names, concurrency, (item) => inspect(item.relDir, item.absDir, item.name, next));
+ level = next;
+ }
+
+ const unreadable = new Set<ScannedEntry>();
+ const buffers: Buffer[] = [];
+ await forEachBounded(toHash, options.hashConcurrency ?? HASH_CONCURRENCY, async (entry) => {
+ const buffer = buffers.pop() ?? Buffer.allocUnsafe(HASH_READ_BYTES);
+ try {
+ const sha256 = await hashFile(join(root, ...entry.path.split("/")), entry.size, buffer, metrics);
+ if (sha256 === null) {
+ unreadable.add(entry);
+ cache?.forget(entry.path);
+ return;
+ }
+ entry.sha256 = sha256;
+ cache?.remember(entry);
+ } finally {
+ buffers.push(buffer);
+ }
+ });
+ excluded.unreadable += unreadable.size;
+ const kept = unreadable.size > 0 ? entries.filter((entry) => !unreadable.has(entry)) : entries;
+ kept.sort((left, right) => compareArchivePaths(left.path, right.path));
+ cache?.commitScan();
+ return { entries: kept, excluded };
+}
+
+// --- delta ----------------------------------------------------------------------
+
+/** Whether `current` counts as modified against `previous` (section 5.8). */
+export function isArchiveEntryModified(previous: ArchiveEntry, current: ArchiveEntry): boolean {
+ if (previous.type !== current.type || previous.mode !== current.mode) return true;
+ if (current.type === "file") return previous.sha256 !== current.sha256;
+ if (current.type === "symlink") return previous.target !== current.target;
+ return false;
+}
+
+export type ArchiveDelta<T extends ArchiveEntry> = { files: T[]; deleted: string[] };
+
+function sortedByPath<T extends ArchiveEntry>(entries: readonly T[]): readonly T[] {
+ for (let index = 1; index < entries.length; index += 1) {
+ if (compareArchivePaths(entries[index - 1]!.path, entries[index]!.path) >= 0) {
+ return [...entries].sort((left, right) => compareArchivePaths(left.path, right.path));
+ }
+ }
+ return entries;
+}
+
+/**
+ * Added and modified entries of the scan, plus every baseline path that is
+ * gone, both sorted. A merge of two sorted lists: no index of either is built.
+ */
+export function computeArchiveDelta<T extends ArchiveEntry>(baseline: readonly ArchiveEntry[], current: readonly T[]): ArchiveDelta<T> {
+ const previous = sortedByPath(baseline);
+ const scanned = sortedByPath(current);
+ const files: T[] = [];
+ const deleted: string[] = [];
+ let left = 0;
+ let right = 0;
+ while (left < previous.length || right < scanned.length) {
+ const old = previous[left];
+ const now = scanned[right];
+ const order = old === undefined ? 1 : now === undefined ? -1 : compareArchivePaths(old.path, now.path);
+ if (order < 0) {
+ deleted.push(old!.path);
+ left += 1;
+ } else if (order > 0) {
+ files.push(now!);
+ right += 1;
+ } else {
+ if (isArchiveEntryModified(old!, now!)) files.push(now!);
+ left += 1;
+ right += 1;
+ }
+ }
+ return { files, deleted };
+}
+
+export function isArchiveDeltaEmpty(delta: ArchiveDelta<ArchiveEntry>): boolean {
+ return delta.files.length === 0 && delta.deleted.length === 0;
+}
+
+// --- manifest ---------------------------------------------------------------------
+
+/** The manifest/baseline form of an entry: exactly the section 5.4 fields, in order. */
+export function archiveEntry(entry: ArchiveEntry): ArchiveEntry {
+ const out: ArchiveEntry = { path: entry.path, type: entry.type, mode: entry.mode, size: entry.size, sha256: entry.sha256 };
+ if (entry.type === "symlink") out.target = entry.target ?? "";
+ return out;
+}
+
+export type ManifestInput = {
+ kind: ArchiveKind;
+ archiveId: string;
+ sessionId: string;
+ sequence: number;
+ turn: number;
+ createdAt: Date;
+ parentArchiveId: string | null;
+ label: string;
+ marker: string;
+ git: ArchiveGit | null;
+ files: readonly ArchiveEntry[];
+ deleted?: readonly string[];
+ excluded: ExcludedCounts;
+};
+
+/** A manifest that is serialised on demand: its size first, then its bytes while the tar is written. */
+export type ManifestSource = { size: number; chunks: () => Iterable<Buffer> };
+
+/**
+ * `__omnirush__/manifest.json`. The entries are serialised a batch at a time,
+ * once to learn the size the tar header needs and again while the member is
+ * written, so a 200k-entry manifest (about 165 bytes per entry) is never held
+ * in memory whole. The entries must not change in between.
+ */
+export function manifestSource(input: ManifestInput): ManifestSource {
+ const head = JSON.stringify({
+ schema: ARCHIVE_SCHEMA,
+ kind: input.kind,
+ archive_id: input.archiveId,
+ session_id: input.sessionId,
+ sequence: input.sequence,
+ turn: input.turn,
+ created_at: input.createdAt.toISOString(),
+ parent_archive_id: input.parentArchiveId,
+ workspace: { label: input.label, marker: input.marker, git: input.git },
+ });
+ const deleted = input.kind === "delta" ? `,"deleted":${JSON.stringify(input.deleted ?? [])}` : "";
+ const tail = `]${deleted},"excluded":${JSON.stringify(input.excluded)}}`;
+ function* chunks(): Generator<Buffer> {
+ yield Buffer.from(`${head.slice(0, -1)},"files":[`, "utf8");
+ for (let index = 0; index < input.files.length; index += 2_000) {
+ const batch = input.files.slice(index, index + 2_000).map((entry) => JSON.stringify(archiveEntry(entry)));
+ yield Buffer.from(`${index === 0 ? "" : ","}${batch.join(",")}`, "utf8");
+ }
+ yield Buffer.from(tail, "utf8");
+ }
+ let size = 0;
+ for (const chunk of chunks()) size += chunk.length;
+ return { size, chunks };
+}
+
+export function buildManifestBytes(input: ManifestInput): Buffer {
+ return Buffer.concat([...manifestSource(input).chunks()]);
+}
+
+// --- git ------------------------------------------------------------------------
+
+type GitRun = { ok: boolean; stdout: string; truncated: boolean };
+
+/** Runs git in the root without locks, prompts or fsmonitor hooks; reads at most `maxBytes` of stdout. */
+function runGit(root: string, args: string[], maxBytes = 64 * 1024): Promise<GitRun> {
+ return new Promise((resolvePromise) => {
+ const chunks: Buffer[] = [];
+ let total = 0;
+ let truncated = false;
+ let settled = false;
+ let child: ReturnType<typeof spawn> | null = null;
+ const finish = (ok: boolean) => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ resolvePromise({ ok, stdout: Buffer.concat(chunks).toString("utf8"), truncated });
+ };
+ const timer = setTimeout(() => {
+ child?.kill("SIGKILL");
+ finish(false);
+ }, GIT_TIMEOUT_MS);
+ timer.unref?.();
+ try {
+ child = spawn("git", ["-C", root, "-c", "core.fsmonitor=false", "-c", "core.quotePath=false", ...args], {
+ stdio: ["ignore", "pipe", "ignore"],
+ windowsHide: true,
+ env: { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_OPTIONAL_LOCKS: "0", GIT_PAGER: "cat", PAGER: "cat", LC_ALL: "C" },
+ });
+ } catch {
+ finish(false);
+ return;
+ }
+ child.stdout?.on("data", (chunk: Buffer) => {
+ if (truncated) return;
+ const room = maxBytes - total;
+ if (chunk.length >= room) {
+ chunks.push(chunk.subarray(0, room));
+ total = maxBytes;
+ truncated = true;
+ child?.kill("SIGKILL");
+ finish(true);
+ return;
+ }
+ chunks.push(chunk);
+ total += chunk.length;
+ });
+ child.on("error", () => finish(false));
+ child.on("close", (code) => finish(code === 0));
+ });
+}
+
+async function gitLine(root: string, args: string[]): Promise<string | null> {
+ const result = await runGit(root, args);
+ if (!result.ok || result.truncated) return null;
+ return result.stdout.trim() || null;
+}
+
+/**
+ * workspace.git (section 5.6): HEAD, branch, the origin (else first) remote
+ * without userinfo, and whether `git status --porcelain` prints anything.
+ * Null when git cannot read the repository. GIT_OPTIONAL_LOCKS=0 keeps
+ * `git status` from rewriting .git/index, which would otherwise show up as a
+ * change in the next delta.
+ */
+export async function readArchiveGit(root: string): Promise<ArchiveGit | null> {
+ if (!(await runGit(root, ["rev-parse", "--git-dir"])).ok) return null;
+ const [head, branch, remotes, status] = await Promise.all([
+ gitLine(root, ["rev-parse", "--verify", "-q", "HEAD"]),
+ gitLine(root, ["symbolic-ref", "--short", "-q", "HEAD"]),
+ gitLine(root, ["remote"]),
+ runGit(root, ["status", "--porcelain", "--untracked-files=normal"], 1),
+ ]);
+ const names = remotes?.split(/\r?\n/).map((name) => name.trim()).filter(Boolean) ?? [];
+ const remoteName = names.includes("origin") ? "origin" : names[0];
+ const remoteUrl = remoteName ? await gitLine(root, ["remote", "get-url", remoteName]) : null;
+ return {
+ head: head && /^[0-9a-f]{40,64}$/.test(head) ? head : null,
+ branch,
+ remote: remoteUrl ? stripRemoteUserinfo(remoteUrl) : null,
+ dirty: status.ok && status.stdout.length > 0,
+ };
+}
diff --git a/apps/server/src/session-archive/pack.test.ts b/apps/server/src/session-archive/pack.test.ts
new file mode 100644
index 00000000..fc6a4845
--- /dev/null
+++ b/apps/server/src/session-archive/pack.test.ts
@@ -0,0 +1,320 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { execFile } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { lstat, mkdir, readFile, readlink, rename, rm, symlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+import { buildManifestBytes, emptyExcludedCounts, scanArchiveTree, type ScannedEntry } from "./manifest.js";
+import { MANIFEST_MEMBER, UNSTABLE_MEMBER, packArchiveTar, tarMemberHeader, writeSealedArchive } from "./pack.js";
+import { cleanupTempDirs, openArchive, readTar, tempDir, testKeys } from "./test-helpers.js";
+
+const execFileAsync = promisify(execFile);
+
+afterEach(cleanupTempDirs);
+
+const LONG_DIR = `deep/${"d".repeat(60)}/${"e".repeat(60)}`;
+const LONG_FILE = `${LONG_DIR}/${"f".repeat(80)}.txt`;
+const UNICODE_FILE = "naïve/日本語 ファイル 😀.md";
+const LONG_TARGET = `../${"t".repeat(120)}/target`;
+
+async function buildTree(root: string): Promise<void> {
+ await mkdir(join(root, LONG_DIR), { recursive: true });
+ await mkdir(join(root, "naïve"), { recursive: true });
+ await mkdir(join(root, "empty/inner"), { recursive: true });
+ await mkdir(join(root, "bin"), { recursive: true });
+ await writeFile(join(root, LONG_FILE), "long path content\n");
+ await writeFile(join(root, UNICODE_FILE), "unicode ✓\n");
+ await writeFile(join(root, "a.txt"), "alpha\n");
+ await writeFile(join(root, "bin/run.sh"), "#!/bin/sh\necho hi\n", { mode: 0o755 });
+ await writeFile(join(root, "big.bin"), Buffer.alloc(3 * 1024 * 1024 + 17, 7));
+ await symlink("a.txt", join(root, "link-short"));
+ await symlink(LONG_TARGET, join(root, "link-long"));
+ await symlink("naïve/日本語 ファイル 😀.md", join(root, "link-unicode"));
+ await symlink("/usr/bin/env", join(root, "link-absolute"));
+}
+
+/** Scans, runs `mutate`, then packs; `afterFirstBlock` runs once pass 2 has emitted its first block. */
+async function packTree(root: string, mutate?: () => Promise<void>, afterFirstBlock?: () => Promise<void>) {
+ const { entries } = await scanArchiveTree(root);
+ const manifest = buildManifestBytes({
+ kind: "base",
+ archiveId: "5d0c6f9e-1d8e-4b5c-9a53-0e8f2b7c1a44",
+ sessionId: "ses_pack_test",
+ sequence: 0,
+ turn: 0,
+ createdAt: new Date("2026-09-23T10:15:30.123Z"),
+ parentArchiveId: null,
+ label: "project",
+ marker: ".git",
+ git: null,
+ files: entries,
+ excluded: emptyExcludedCounts(),
+ });
+ await mutate?.();
+ const tar = packArchiveTar({ root, manifest, createdAtSeconds: 1790158530, entries });
+ const pieces: Buffer[] = [];
+ let pending = afterFirstBlock;
+ for await (const piece of tar.stream) {
+ pieces.push(Buffer.from(piece));
+ const run = pending;
+ pending = undefined;
+ await run?.();
+ }
+ const bytes = Buffer.concat(pieces);
+ return { entries, manifest, bytes, outcome: tar.outcome() };
+}
+
+const IN_TREE_CONFIG = "in-tree config, 41 bytes long...........\n";
+const OUTSIDE_CONFIG = "Host prod\n IdentityFile ~/.ssh/prod_key\n";
+
+/** Replaces root/sub with a symlink to `outside`, as `npm link` or a tool might. */
+async function swapForSymlink(root: string, outside: string): Promise<void> {
+ await rename(join(root, "sub"), join(root, "sub.old"));
+ await symlink(outside, join(root, "sub"));
+}
+
+const sha256 = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex");
+
+describe("pax tar writer", () => {
+ test("member order: manifest first, then the manifest's files in order", async () => {
+ const root = await tempDir("pack-order");
+ await buildTree(root);
+ const { entries, manifest, bytes, outcome } = await packTree(root);
+ expect(outcome.unstable).toEqual([]);
+ expect(outcome.tarBytes).toBe(bytes.length);
+ expect(bytes.length % 512).toBe(0);
+ expect(bytes.subarray(bytes.length - 1024).every((byte) => byte === 0)).toBe(true);
+ const members = readTar(bytes);
+ expect(members[0]!.name).toBe(MANIFEST_MEMBER);
+ expect(members[0]!.content.equals(manifest)).toBe(true);
+ expect(members[0]!.mode).toBe(0o644);
+ expect(members[0]!.mtime).toBe(1790158530);
+ expect(members.slice(1).map((member) => member.name)).toEqual(entries.map((entry) => entry.path));
+ for (const member of members) {
+ expect(member.uid).toBe(0);
+ expect(member.gid).toBe(0);
+ expect(["0", "2", "5"]).toContain(member.typeflag);
+ }
+ const byName = new Map(members.map((member) => [member.name, member]));
+ expect(byName.get("big.bin")!.content.equals(await readFile(join(root, "big.bin")))).toBe(true);
+ expect(byName.get("bin/run.sh")!.mode).toBe(0o755);
+ expect(byName.get("link-long")!.linkname).toBe(LONG_TARGET);
+ expect(byName.get("link-unicode")!.linkname).toBe("naïve/日本語 ファイル 😀.md");
+ expect(byName.get(UNICODE_FILE)!.content.toString()).toBe("unicode ✓\n");
+ expect(byName.get("empty/inner")!.typeflag).toBe("5");
+ // Directories precede their content.
+ const order = members.map((member) => member.name);
+ expect(order.indexOf("naïve")).toBeLessThan(order.indexOf(UNICODE_FILE));
+ });
+
+ test("round trip through the system tar: long paths, unicode, symlinks, empty directories", async () => {
+ const root = await tempDir("pack-src");
+ await buildTree(root);
+ const { bytes } = await packTree(root);
+ const work = await tempDir("pack-out");
+ await writeFile(join(work, "archive.tar"), bytes);
+ const out = join(work, "out");
+ await mkdir(out);
+ await execFileAsync("tar", ["-xf", join(work, "archive.tar"), "-C", out]);
+ expect(await readFile(join(out, LONG_FILE), "utf8")).toBe("long path content\n");
+ expect(await readFile(join(out, UNICODE_FILE), "utf8")).toBe("unicode ✓\n");
+ expect(sha256(await readFile(join(out, "big.bin")))).toBe(sha256(await readFile(join(root, "big.bin"))));
+ expect(await readlink(join(out, "link-long"))).toBe(LONG_TARGET);
+ // bsdtar on macOS NFD-normalizes extracted link targets; the raw bytes are checked by the other readers.
+ expect((await readlink(join(out, "link-unicode"))).normalize("NFC")).toBe("naïve/日本語 ファイル 😀.md");
+ expect(await readlink(join(out, "link-absolute"))).toBe("/usr/bin/env");
+ expect((await lstat(join(out, "empty/inner"))).isDirectory()).toBe(true);
+ expect((await lstat(join(out, "bin/run.sh"))).mode & 0o777).toBe(0o755);
+ const manifest = JSON.parse(await readFile(join(out, MANIFEST_MEMBER), "utf8"));
+ expect(manifest.schema).toBe("omnirush.archive.v1");
+ });
+
+ test("Python tarfile reads the stream the way the server does (mode r|)", async () => {
+ const python = await execFileAsync("python3", ["--version"]).then(() => true, () => false);
+ if (!python) return;
+ const root = await tempDir("pack-py");
+ await buildTree(root);
+ const { bytes, entries } = await packTree(root);
+ const work = await tempDir("pack-py-out");
+ await writeFile(join(work, "archive.tar"), bytes);
+ const script = [
+ "import hashlib, json, sys, tarfile",
+ "out = []",
+ "with open(sys.argv[1], 'rb') as f:",
+ " with tarfile.open(fileobj=f, mode='r|') as t:",
+ " for m in t:",
+ " data = t.extractfile(m).read() if m.isfile() else b''",
+ " out.append([m.name, m.type.decode(), m.mode, m.size, m.linkname, hashlib.sha256(data).hexdigest() if m.isfile() else None, m.uid, m.gid, m.uname, m.gname])",
+ "print(json.dumps(out))",
+ ].join("\n");
+ const { stdout } = await execFileAsync("python3", ["-c", script, join(work, "archive.tar")], { maxBuffer: 16 * 1024 * 1024 });
+ const listed: Array<[string, string, number, number, string, string | null, number, number, string, string]> = JSON.parse(stdout);
+ expect(listed[0]![0]).toBe(MANIFEST_MEMBER);
+ const byPath = new Map<string, ScannedEntry>(entries.map((entry) => [entry.path, entry]));
+ for (const [name, type, mode, size, linkname, digest, uid, gid, uname, gname] of listed.slice(1)) {
+ const entry = byPath.get(name);
+ expect(entry).toBeDefined();
+ expect(mode).toBe(entry!.mode);
+ expect([uid, gid, uname, gname]).toEqual([0, 0, "", ""]);
+ if (entry!.type === "file") {
+ expect(type).toBe("0");
+ expect(size).toBe(entry!.size);
+ expect(digest).toBe(entry!.sha256);
+ } else if (entry!.type === "symlink") {
+ expect(type).toBe("2");
+ expect(linkname).toBe(entry!.target!);
+ } else {
+ expect(type).toBe("5");
+ }
+ }
+ expect(listed.length).toBe(entries.length + 1);
+ });
+
+ test("a file that changes between the passes keeps its manifest size and is listed as unstable", async () => {
+ const root = await tempDir("pack-unstable");
+ await writeFile(join(root, "grows.txt"), "0123456789");
+ await writeFile(join(root, "shrinks.txt"), "0123456789");
+ await writeFile(join(root, "vanishes.txt"), "0123456789");
+ await writeFile(join(root, "same.txt"), "0123456789");
+ await symlink("same.txt", join(root, "retarget"));
+ const { entries, bytes, outcome } = await packTree(root, async () => {
+ await writeFile(join(root, "grows.txt"), "0123456789ABCDEFGHIJ");
+ await writeFile(join(root, "shrinks.txt"), "0123");
+ await rm(join(root, "vanishes.txt"));
+ await rm(join(root, "retarget"));
+ await symlink("grows.txt", join(root, "retarget"));
+ });
+ expect(outcome.unstable).toEqual(["grows.txt", "retarget", "shrinks.txt", "vanishes.txt"]);
+ const members = readTar(bytes);
+ const byName = new Map(members.map((member) => [member.name, member]));
+ expect(byName.get("grows.txt")!.content.toString()).toBe("0123456789");
+ expect(byName.get("shrinks.txt")!.content.toString()).toBe("0123\0\0\0\0\0\0");
+ expect(byName.get("vanishes.txt")!.content.equals(Buffer.alloc(10))).toBe(true);
+ expect(byName.get("retarget")!.linkname).toBe("same.txt");
+ expect(byName.get("same.txt")!.content.toString()).toBe("0123456789");
+ const last = members.at(-1)!;
+ expect(last.name).toBe(UNSTABLE_MEMBER);
+ expect(JSON.parse(last.content.toString())).toEqual({
+ schema: "omnirush.archive.unstable.v1",
+ paths: ["grows.txt", "retarget", "shrinks.txt", "vanishes.txt"],
+ });
+ expect(members.length).toBe(entries.length + 2);
+ });
+
+ test("a directory swapped for a symlink before pass 2: nothing is read from outside the root", async () => {
+ const root = await tempDir("pack-swap");
+ const outside = await tempDir("pack-swap-outside");
+ await mkdir(join(root, "sub"));
+ await writeFile(join(root, "sub/config"), IN_TREE_CONFIG);
+ await symlink("config", join(root, "sub/alias"));
+ await writeFile(join(outside, "config"), OUTSIDE_CONFIG);
+ await symlink("config", join(outside, "alias"));
+ const { bytes, outcome } = await packTree(root, () => swapForSymlink(root, outside));
+ expect(bytes.includes("IdentityFile")).toBe(false);
+ expect(outcome.unstable).toEqual(["sub/alias", "sub/config"]);
+ const byName = new Map(readTar(bytes).map((member) => [member.name, member]));
+ expect(byName.get("sub/config")!.content.equals(Buffer.alloc(IN_TREE_CONFIG.length))).toBe(true);
+ expect(byName.get("sub/alias")!.linkname).toBe("config");
+ });
+
+ test("a directory swapped while pass 2 is inside it: the file behind the symlink is zero-filled", async () => {
+ const root = await tempDir("pack-swap-live");
+ const outside = await tempDir("pack-swap-live-outside");
+ await mkdir(join(root, "sub"));
+ // Pass 2 is still streaming a.bin when the first block arrives: the stream buffers at most a few MiB.
+ await writeFile(join(root, "sub/a.bin"), randomBytes(8 * 1024 * 1024));
+ await writeFile(join(root, "sub/config"), IN_TREE_CONFIG);
+ await writeFile(join(outside, "config"), OUTSIDE_CONFIG);
+ const { bytes, outcome } = await packTree(root, undefined, () => swapForSymlink(root, outside));
+ expect(bytes.includes("IdentityFile")).toBe(false);
+ expect(outcome.unstable).toEqual(["sub/config"]);
+ const byName = new Map(readTar(bytes).map((member) => [member.name, member]));
+ expect(byName.get("sub/a.bin")!.content.equals(await readFile(join(root, "sub.old/a.bin")))).toBe(true);
+ expect(byName.get("sub/config")!.content.equals(Buffer.alloc(IN_TREE_CONFIG.length))).toBe(true);
+ });
+
+ test("a file replaced by a FIFO between the passes does not block pass 2", async () => {
+ if (process.platform === "win32") return;
+ const root = await tempDir("pack-fifo");
+ await writeFile(join(root, "pipe"), "0123456789");
+ await writeFile(join(root, "same.txt"), "0123456789");
+ const { bytes, outcome } = await packTree(root, async () => {
+ await rm(join(root, "pipe"));
+ await execFileAsync("mkfifo", [join(root, "pipe")]);
+ });
+ expect(outcome.unstable).toEqual(["pipe"]);
+ const byName = new Map(readTar(bytes).map((member) => [member.name, member]));
+ expect(byName.get("pipe")!.content.equals(Buffer.alloc(10))).toBe(true);
+ expect(byName.get("same.txt")!.content.toString()).toBe("0123456789");
+ });
+
+ test("headers: pax records for long or non-ASCII names and targets, ASCII fallbacks, size field", () => {
+ const plain = tarMemberHeader({ name: "src/app.ts", mode: 0o644, size: 5, mtime: 100, typeflag: "0" });
+ expect(plain.length).toBe(512);
+ const exactly100 = tarMemberHeader({ name: "x".repeat(100), mode: 0o644, size: 0, mtime: 0, typeflag: "0" });
+ expect(exactly100.length).toBe(512);
+ const long = tarMemberHeader({ name: "y".repeat(101), mode: 0o644, size: 0, mtime: 0, typeflag: "0" });
+ expect(long.length).toBe(1536);
+ expect(long.subarray(0, 14).toString()).toBe("././@PaxHeader");
+ expect(long.subarray(512, 1024).toString("utf8")).toContain(` path=${"y".repeat(101)}\n`);
+ const unicode = tarMemberHeader({ name: "é.txt", mode: 0o644, size: 0, mtime: -5, typeflag: "0" });
+ const main = unicode.subarray(1024);
+ expect(main.subarray(0, 6).toString("latin1")).toBe("__.txt");
+ const [parsed] = readTar(Buffer.concat([unicode, Buffer.alloc(1024)]));
+ expect(parsed!.name).toBe("é.txt");
+ expect(parsed!.mtime).toBe(0);
+ const huge = tarMemberHeader({ name: "huge.bin", mode: 0o644, size: 8 ** 11, mtime: 0, typeflag: "0" });
+ expect(huge.subarray(512, 1024).toString()).toContain(` size=${8 ** 11}\n`);
+ expect(huge.subarray(1024 + 124, 1024 + 136).toString()).toBe("00000000000\0");
+ });
+
+ test("writeSealedArchive: a multi-MiB tree survives tar -> zstd -> seal with recycled blocks", async () => {
+ const root = await tempDir("pack-sealed");
+ await mkdir(join(root, "many"), { recursive: true });
+ await writeFile(join(root, "random.bin"), randomBytes(6 * 1024 * 1024 + 333));
+ await writeFile(join(root, "text.log"), "line of compressible log text\n".repeat(150_000));
+ for (let index = 0; index < 300; index += 1) await writeFile(join(root, `many/f${index}.txt`), randomBytes(1 + index * 37));
+ const { entries } = await scanArchiveTree(root);
+ const manifest = buildManifestBytes({
+ kind: "base",
+ archiveId: "5d0c6f9e-1d8e-4b5c-9a53-0e8f2b7c1a44",
+ sessionId: "ses_pack_sealed",
+ sequence: 0,
+ turn: 0,
+ createdAt: new Date(),
+ parentArchiveId: null,
+ label: "project",
+ marker: ".git",
+ git: null,
+ files: entries,
+ excluded: emptyExcludedCounts(),
+ });
+ const out = join(await tempDir("pack-sealed-out"), "archive.orseal");
+ const sealed = await writeSealedArchive({ root, manifest, createdAtSeconds: 0, entries }, { publicKey: testKeys.publicKey }, out);
+ const bytes = await readFile(out);
+ expect(sealed.size).toBe(bytes.length);
+ expect(sealed.sha256).toBe(sha256(bytes));
+ expect(sealed.kid).toBe(testKeys.kid);
+ expect(sealed.unstable).toEqual([]);
+ expect(sealed.tarBytes).toBeGreaterThan(10 * 1024 * 1024);
+ const members = await openArchive(bytes);
+ expect(members.map((member) => member.name)).toEqual([MANIFEST_MEMBER, ...entries.map((entry) => entry.path)]);
+ for (const entry of entries) {
+ if (entry.type !== "file") continue;
+ expect(sha256(members.find((member) => member.name === entry.path)!.content)).toBe(entry.sha256!);
+ }
+ // The payload is one zstd frame with a content checksum, readable by the zstd CLI too.
+ const zstd = await execFileAsync("zstd", ["--version"]).then(() => true, () => false);
+ if (zstd) {
+ const { zstdDecompressSync } = await import("node:zlib");
+ const { openSealedBuffer } = await import("./seal.js");
+ const payload = join(await tempDir("pack-sealed-zst"), "payload.tar.zst");
+ await writeFile(payload, await openSealedBuffer(bytes, testKeys.keyring));
+ await execFileAsync("zstd", ["-t", "-q", payload]);
+ expect(zstdDecompressSync(await readFile(payload)).length).toBe(sealed.tarBytes);
+ }
+ // An existing output file is never overwritten.
+ await expect(writeSealedArchive({ root, manifest, createdAtSeconds: 0, entries }, { publicKey: testKeys.publicKey }, out)).rejects.toThrow();
+ });
+});
diff --git a/apps/server/src/session-archive/pack.ts b/apps/server/src/session-archive/pack.ts
new file mode 100644
index 00000000..a2806184
--- /dev/null
+++ b/apps/server/src/session-archive/pack.ts
@@ -0,0 +1,477 @@
+/**
+ * Pass 2 of a capture (sections 5.5, 5.9, 5.10, 13.1): a streaming POSIX pax
+ * tar writer, and the pipeline file -> tar -> zstd -> ORSEAL01 -> temp file.
+ * Memory is bounded by a few output blocks and stream buffers whatever the
+ * project size.
+ */
+import { createHash } from "node:crypto";
+import { lstat, open, readlink } from "node:fs/promises";
+import { join } from "node:path";
+import { once } from "node:events";
+import { PassThrough, Writable, type Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { constants as zlibConstants, createZstdCompress } from "node:zlib";
+
+import {
+ OPEN_ENTRY_FLAGS,
+ compareArchivePaths,
+ isSameFileIdentity,
+ statKeyPrefix,
+ type ManifestSource,
+ type ScannedEntry,
+} from "./manifest.js";
+import { hintGarbageCollection } from "./files.js";
+import { SealStream, type SealOptions } from "./seal.js";
+
+export const MANIFEST_MEMBER = "__omnirush__/manifest.json";
+export const UNSTABLE_MEMBER = "__omnirush__/unstable.json";
+export const UNSTABLE_SCHEMA = "omnirush.archive.unstable.v1";
+const TAR_BLOCK = 512;
+/** Tar output is assembled in blocks of this size; file content is read straight into them. */
+const OUTPUT_BLOCK = 1 << 20;
+const MAX_OCTAL_11 = 8 ** 11 - 1;
+const PAX_HEADER_NAME = Buffer.from("././@PaxHeader", "ascii");
+const ZSTD_LEVEL = 3;
+/** Output blocks (64 MiB), or members, between two garbage collection hints. */
+const GC_HINT_BLOCKS = 64;
+const GC_HINT_MEMBERS = 10_000;
+
+type Typeflag = "0" | "2" | "5" | "x";
+
+function isAscii(bytes: Buffer): boolean {
+ for (const byte of bytes) if (byte >= 0x80) return false;
+ return true;
+}
+
+/** The ustar fallback when a pax record carries the real value: non-ASCII bytes become `_`, cut to 100 bytes. */
+function asciiFallback(bytes: Buffer): Buffer {
+ const out = Buffer.from(bytes.subarray(0, 100));
+ for (let index = 0; index < out.length; index += 1) if (out[index]! >= 0x80) out[index] = 0x5f;
+ return out;
+}
+
+function writeOctal(block: Buffer, offset: number, width: number, value: number): void {
+ const digits = value.toString(8).padStart(width - 1, "0");
+ if (digits.length > width - 1) throw new RangeError("tar numeric field overflow");
+ block.write(digits, offset, width - 1, "ascii");
+ block[offset + width - 1] = 0;
+}
+
+function clampMtime(seconds: number): number {
+ return Math.min(Math.max(Math.floor(seconds), 0), MAX_OCTAL_11);
+}
+
+function ustarHeader(name: Buffer, mode: number, size: number, mtime: number, typeflag: Typeflag, linkname: Buffer | null): Buffer {
+ const block = Buffer.alloc(TAR_BLOCK);
+ name.copy(block, 0, 0, 100);
+ writeOctal(block, 100, 8, mode & 0o7777);
+ writeOctal(block, 108, 8, 0);
+ writeOctal(block, 116, 8, 0);
+ writeOctal(block, 124, 12, size);
+ writeOctal(block, 136, 12, mtime);
+ block.fill(0x20, 148, 156);
+ block.write(typeflag, 156, 1, "ascii");
+ linkname?.copy(block, 157, 0, 100);
+ block.write("ustar\0", 257, 6, "ascii");
+ block.write("00", 263, 2, "ascii");
+ writeOctal(block, 329, 8, 0);
+ writeOctal(block, 337, 8, 0);
+ let sum = 0;
+ for (const byte of block) sum += byte;
+ block.write(sum.toString(8).padStart(6, "0"), 148, 6, "ascii");
+ block[154] = 0;
+ block[155] = 0x20;
+ return block;
+}
+
+/** One `"<len> <key>=<value>\n"` record; `len` counts the whole record, its own digits included. */
+function paxRecord(key: string, value: string): string {
+ const rest = Buffer.byteLength(` ${key}=${value}\n`, "utf8");
+ let digits = 1;
+ while (String(rest + digits).length !== digits) digits += 1;
+ return `${rest + digits} ${key}=${value}\n`;
+}
+
+function paddingFor(size: number): number {
+ return (TAR_BLOCK - (size % TAR_BLOCK)) % TAR_BLOCK;
+}
+
+export type TarMember = { name: string; mode: number; size: number; mtime: number; typeflag: "0" | "2" | "5"; linkname?: string };
+
+/** The header blocks of one member: a pax `x` header first when the path, target or size needs one. */
+export function tarMemberHeader(member: TarMember): Buffer {
+ const mtime = clampMtime(member.mtime);
+ const records: string[] = [];
+ let name: Buffer = Buffer.from(member.name, "utf8");
+ if (name.length > 100 || !isAscii(name)) {
+ records.push(paxRecord("path", member.name));
+ name = asciiFallback(name);
+ }
+ let linkname: Buffer | null = null;
+ if (member.linkname !== undefined) {
+ linkname = Buffer.from(member.linkname, "utf8");
+ if (linkname.length > 100 || !isAscii(linkname)) {
+ records.push(paxRecord("linkpath", member.linkname));
+ linkname = asciiFallback(linkname);
+ }
+ }
+ let size = member.size;
+ if (size > MAX_OCTAL_11) {
+ records.push(paxRecord("size", String(size)));
+ size = 0;
+ }
+ const header = ustarHeader(name, member.mode, size, mtime, member.typeflag, linkname);
+ if (records.length === 0) return header;
+ const body = Buffer.from(records.join(""), "utf8");
+ return Buffer.concat([
+ ustarHeader(PAX_HEADER_NAME, 0o644, body.length, mtime, "x", null),
+ body,
+ Buffer.alloc(paddingFor(body.length)),
+ header,
+ ]);
+}
+
+export type PackInput = {
+ root: string;
+ /** `__omnirush__/manifest.json`: its bytes, or a source that serialises it while it is written. */
+ manifest: Buffer | ManifestSource;
+ /** created_at in seconds: the mtime of the manifest and unstable members. */
+ createdAtSeconds: number;
+ /** Exactly the manifest's `files`, in the same order. */
+ entries: readonly ScannedEntry[];
+};
+
+export type PackOutcome = { unstable: string[]; tarBytes: number };
+
+export type TarPack = { stream: Readable; outcome: () => PackOutcome };
+
+/** Takes a filled output block and resolves with the next (empty) one to fill. */
+type EmitBlock = (block: Buffer) => Promise<Buffer>;
+
+/**
+ * Writes the tar stream of an archive into output blocks: the manifest, the
+ * entries streamed from disk, then `__omnirush__/unstable.json` when an entry
+ * changed after pass 1. File content is read straight into the blocks. Only
+ * a full block waits on the consumer; the members themselves are plain async
+ * calls (async generators, one chain per member, cost several times the
+ * memory on a 200k-member tree).
+ */
+class TarWriter {
+ private readonly unstable: string[] = [];
+ private tarBytes = 0;
+ private finished = false;
+ private block: Buffer;
+ private used = 0;
+ private rotations = 0;
+ /** The directories above the last entry read, from the root down, and whether each was a real directory. */
+ private readonly parents: Array<{ name: string; real: boolean }> = [];
+
+ constructor(private readonly input: PackInput, first: Buffer, private readonly emit: EmitBlock) {
+ this.block = first;
+ }
+
+ outcome(): PackOutcome {
+ if (!this.finished) throw new Error("the tar stream has not finished");
+ return { unstable: [...this.unstable], tarBytes: this.tarBytes };
+ }
+
+ private async rotate(): Promise<void> {
+ this.tarBytes += this.used;
+ this.block = await this.emit(this.block);
+ this.used = 0;
+ this.rotations += 1;
+ if (this.rotations % GC_HINT_BLOCKS === 0) hintGarbageCollection();
+ }
+
+ private async put(bytes: Buffer): Promise<void> {
+ let offset = 0;
+ while (offset < bytes.length) {
+ if (this.used === OUTPUT_BLOCK) await this.rotate();
+ const take = Math.min(bytes.length - offset, OUTPUT_BLOCK - this.used);
+ bytes.copy(this.block, this.used, offset, offset + take);
+ this.used += take;
+ offset += take;
+ }
+ }
+
+ private async zeros(count: number): Promise<void> {
+ let left = count;
+ while (left > 0) {
+ if (this.used === OUTPUT_BLOCK) await this.rotate();
+ const take = Math.min(left, OUTPUT_BLOCK - this.used);
+ this.block.fill(0, this.used, this.used + take);
+ this.used += take;
+ left -= take;
+ }
+ }
+
+ private async smallFile(name: string, content: Buffer | ManifestSource): Promise<void> {
+ const source = Buffer.isBuffer(content) ? { size: content.length, chunks: () => [content] } : content;
+ await this.put(tarMemberHeader({ name, mode: 0o644, size: source.size, mtime: this.input.createdAtSeconds, typeflag: "0" }));
+ let written = 0;
+ for (const piece of source.chunks()) {
+ written += piece.length;
+ if (written > source.size) break;
+ await this.put(piece);
+ }
+ if (written !== source.size) throw new Error(`${name} changed while it was written`);
+ await this.zeros(paddingFor(source.size));
+ }
+
+ /**
+ * Whether every directory above `parts` (a root-relative path, split) is
+ * still a real directory and not a symlink, so that opening the path cannot
+ * leave the root. Each directory is lstat'ed once, parents first, when the
+ * walk enters it, and the result holds for its subtree (contiguous in byte
+ * order). A swap after that is caught per file by fileContent()'s identity
+ * check.
+ */
+ private async parentsInRoot(parts: readonly string[]): Promise<boolean> {
+ const { parents } = this;
+ const depth = parts.length - 1;
+ let kept = 0;
+ while (kept < parents.length && kept < depth && parents[kept]!.name === parts[kept]) kept += 1;
+ parents.length = kept;
+ for (let index = kept; index < depth; index += 1) {
+ let real = index === 0 || parents[index - 1]!.real;
+ if (real) {
+ try {
+ real = (await lstat(join(this.input.root, ...parts.slice(0, index + 1)))).isDirectory();
+ } catch {
+ real = false;
+ }
+ }
+ parents.push({ name: parts[index]!, real });
+ }
+ return depth === 0 || parents[depth - 1]!.real;
+ }
+
+ /**
+ * Streams exactly entry.size bytes (truncated or NUL-padded); false when the
+ * file is not what pass 1 saw. Bytes are copied only from the regular file
+ * pass 1 lstat'ed (same st_dev and st_ino) under real directories; anything
+ * else (a file replaced, reached through a directory swapped for a symlink,
+ * a FIFO) is zero-filled.
+ */
+ private async fileContent(entry: ScannedEntry, absolute: string, parentsInRoot: boolean): Promise<boolean> {
+ let stable = false;
+ let handle: Awaited<ReturnType<typeof open>> | null = null;
+ if (parentsInRoot) {
+ try {
+ handle = await open(absolute, OPEN_ENTRY_FLAGS);
+ const stats = await handle.stat({ bigint: true });
+ if (stats.isFile() && isSameFileIdentity(entry, stats)) {
+ stable = stats.size === BigInt(entry.size) && entry.statKey.startsWith(statKeyPrefix(stats.size, stats.mtimeNs));
+ } else {
+ await handle.close();
+ handle = null;
+ }
+ } catch {
+ await handle?.close().catch(() => undefined);
+ handle = null;
+ }
+ }
+ const hash = createHash("sha256");
+ let remaining = entry.size;
+ try {
+ while (handle && remaining > 0) {
+ if (this.used === OUTPUT_BLOCK) await this.rotate();
+ const want = Math.min(remaining, OUTPUT_BLOCK - this.used);
+ let bytesRead = 0;
+ try {
+ ({ bytesRead } = await handle.read(this.block, this.used, want, null));
+ } catch {
+ stable = false;
+ }
+ if (bytesRead === 0) break;
+ hash.update(this.block.subarray(this.used, this.used + bytesRead));
+ this.used += bytesRead;
+ remaining -= bytesRead;
+ }
+ } finally {
+ await handle?.close().catch(() => undefined);
+ }
+ if (remaining > 0) {
+ stable = false;
+ await this.zeros(remaining);
+ } else if (hash.digest("hex") !== entry.sha256) {
+ stable = false;
+ }
+ return stable;
+ }
+
+ /** Writes the whole archive; the last, partial block is emitted too. */
+ async write(): Promise<void> {
+ const { input, unstable } = this;
+ await this.smallFile(MANIFEST_MEMBER, input.manifest);
+ let members = 0;
+ for (const entry of input.entries) {
+ members += 1;
+ if (members % GC_HINT_MEMBERS === 0) hintGarbageCollection();
+ if (entry.type === "dir") {
+ await this.put(tarMemberHeader({ name: `${entry.path}/`, mode: entry.mode, size: 0, mtime: entry.mtime, typeflag: "5" }));
+ continue;
+ }
+ const parts = entry.path.split("/");
+ const absolute = join(input.root, ...parts);
+ const parentsInRoot = await this.parentsInRoot(parts);
+ if (entry.type === "symlink") {
+ const target = entry.target ?? "";
+ await this.put(tarMemberHeader({ name: entry.path, mode: entry.mode, size: 0, mtime: entry.mtime, typeflag: "2", linkname: target }));
+ try {
+ const stats = parentsInRoot ? await lstat(absolute) : null;
+ if (!stats?.isSymbolicLink() || (await readlink(absolute)) !== target) unstable.push(entry.path);
+ } catch {
+ unstable.push(entry.path);
+ }
+ continue;
+ }
+ await this.put(tarMemberHeader({ name: entry.path, mode: entry.mode, size: entry.size, mtime: entry.mtime, typeflag: "0" }));
+ const stable = await this.fileContent(entry, absolute, parentsInRoot);
+ await this.zeros(paddingFor(entry.size));
+ if (!stable) unstable.push(entry.path);
+ }
+ if (unstable.length > 0) {
+ unstable.sort(compareArchivePaths);
+ await this.smallFile(UNSTABLE_MEMBER, Buffer.from(JSON.stringify({ schema: UNSTABLE_SCHEMA, paths: unstable }), "utf8"));
+ }
+ await this.zeros(2 * TAR_BLOCK);
+ if (this.used > 0) {
+ this.tarBytes += this.used;
+ await this.emit(this.block.subarray(0, this.used));
+ this.used = 0;
+ }
+ this.finished = true;
+ }
+}
+
+/** The tar stream of an archive as a Readable (fresh blocks: safe for any consumer). */
+export function packArchiveTar(input: PackInput): TarPack {
+ const stream = new PassThrough({ highWaterMark: OUTPUT_BLOCK });
+ const writer = new TarWriter(input, Buffer.allocUnsafe(OUTPUT_BLOCK), async (block) => {
+ if (!stream.write(block)) await once(stream, "drain");
+ return Buffer.allocUnsafe(OUTPUT_BLOCK);
+ });
+ writer.write().then(() => stream.end(), (error: unknown) => stream.destroy(error instanceof Error ? error : new Error(String(error))));
+ return { stream, outcome: () => writer.outcome() };
+}
+
+/**
+ * A few output blocks recycled between the tar writer and the compressor: a
+ * block returns to the pool once the compressor's write callback says it has
+ * consumed it, so pass 2 allocates the same few MiB whatever the archive size.
+ */
+class BlockPool {
+ private readonly free: Buffer[] = [];
+ private readonly waiters: Array<(block: Buffer) => void> = [];
+ private readonly owned = new Map<ArrayBufferLike, Buffer>();
+
+ constructor(private readonly capacity: number) {}
+
+ acquire(): Promise<Buffer> {
+ const block = this.free.pop();
+ if (block) return Promise.resolve(block);
+ if (this.owned.size < this.capacity) {
+ const fresh = Buffer.allocUnsafeSlow(OUTPUT_BLOCK);
+ this.owned.set(fresh.buffer, fresh);
+ return Promise.resolve(fresh);
+ }
+ return new Promise((resolvePromise) => this.waiters.push(resolvePromise));
+ }
+
+ /** Takes back the block a (possibly partial) view belongs to. */
+ release(view: Buffer): void {
+ const block = this.owned.get(view.buffer);
+ if (!block) return;
+ const waiter = this.waiters.shift();
+ if (waiter) waiter(block);
+ else this.free.push(block);
+ }
+
+ /** After a failure: nobody may wait forever for a block. */
+ unblock(): void {
+ for (const waiter of this.waiters.splice(0)) waiter(Buffer.allocUnsafe(OUTPUT_BLOCK));
+ }
+}
+
+const POOL_BLOCKS = 4;
+
+type FileHandle = Awaited<ReturnType<typeof open>>;
+
+/** The last stage: writes each chunk to the file and waits for it, then fsyncs. */
+class FileSink extends Writable {
+ constructor(private readonly handle: FileHandle) {
+ super({ highWaterMark: OUTPUT_BLOCK });
+ }
+
+ override _write(chunk: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+ this.writeAll([chunk]).then(() => callback(), (error: unknown) => callback(error instanceof Error ? error : new Error(String(error))));
+ }
+
+ override _writev(chunks: Array<{ chunk: Buffer }>, callback: (error?: Error | null) => void): void {
+ this.writeAll(chunks.map((item) => item.chunk)).then(() => callback(), (error: unknown) => callback(error instanceof Error ? error : new Error(String(error))));
+ }
+
+ private async writeAll(buffers: Buffer[]): Promise<void> {
+ let pending = buffers.filter((buffer) => buffer.length > 0);
+ while (pending.length > 0) {
+ let { bytesWritten } = await this.handle.writev(pending);
+ while (pending.length > 0 && bytesWritten >= pending[0]!.length) {
+ bytesWritten -= pending[0]!.length;
+ pending = pending.slice(1);
+ }
+ if (pending.length > 0 && bytesWritten > 0) pending = [pending[0]!.subarray(bytesWritten), ...pending.slice(1)];
+ }
+ }
+
+ override _final(callback: (error?: Error | null) => void): void {
+ this.handle.sync().then(() => callback(), (error: unknown) => callback(error instanceof Error ? error : new Error(String(error))));
+ }
+}
+
+export type SealedArchive = PackOutcome & { size: number; sha256: string; kid: string };
+
+/**
+ * file -> tar -> zstd (level 3, checksum, one frame) -> ORSEAL01 -> `outputPath`,
+ * then fsync. The output file must not exist yet.
+ */
+export async function writeSealedArchive(input: PackInput, seal: SealOptions, outputPath: string): Promise<SealedArchive> {
+ const sealer = new SealStream(seal);
+ const compressor = createZstdCompress({
+ chunkSize: 256 * 1024,
+ params: {
+ [zlibConstants.ZSTD_c_compressionLevel]: ZSTD_LEVEL,
+ [zlibConstants.ZSTD_c_checksumFlag]: 1,
+ },
+ });
+ const handle = await open(outputPath, "wx", 0o600);
+ try {
+ const pool = new BlockPool(POOL_BLOCKS);
+ let failure: unknown = null;
+ const downstream = pipeline(compressor, sealer, new FileSink(handle));
+ downstream.catch((error: unknown) => {
+ failure ??= error;
+ pool.unblock();
+ });
+ const writer = new TarWriter(input, await pool.acquire(), async (block) => {
+ if (failure) throw failure;
+ compressor.write(block, () => pool.release(block));
+ return pool.acquire();
+ });
+ try {
+ await writer.write();
+ } catch (error) {
+ failure ??= error;
+ }
+ if (failure) {
+ compressor.destroy();
+ await downstream.catch(() => undefined);
+ throw failure;
+ }
+ compressor.end();
+ await downstream;
+ return { ...writer.outcome(), ...sealer.result(), kid: sealer.kid };
+ } finally {
+ await handle.close();
+ }
+}
diff --git a/apps/server/src/session-archive/seal.test.ts b/apps/server/src/session-archive/seal.test.ts
new file mode 100644
index 00000000..fba2f0c0
--- /dev/null
+++ b/apps/server/src/session-archive/seal.test.ts
@@ -0,0 +1,132 @@
+import { describe, expect, test } from "bun:test";
+import { createHash, randomBytes } from "node:crypto";
+import { Readable } from "node:stream";
+
+import vectors from "./__fixtures__/orseal_vectors.json" with { type: "json" };
+import {
+ SEAL_CHUNK,
+ SealError,
+ SealStream,
+ openSealed,
+ openSealedBuffer,
+ sealBuffer,
+ sealKeyring,
+ sealKid,
+ x25519PrivateKey,
+ x25519PublicRaw,
+} from "./seal.js";
+
+type KeyName = "server" | "previous" | "unrelated";
+
+const hex = (value: string) => Buffer.from(value, "hex");
+const keyring = sealKeyring([hex(vectors.keys.server.private_hex), hex(vectors.keys.previous.private_hex)]);
+const fixed = { ephemeralPrivateKey: hex(vectors.keys.ephemeral.private_hex), salt: hex(vectors.salt_hex) };
+const sha256 = (bytes: Uint8Array) => createHash("sha256").update(bytes).digest("hex");
+
+function isKeyName(name: string): name is KeyName {
+ return name === "server" || name === "previous" || name === "unrelated";
+}
+
+function plaintextOf(vector: (typeof vectors.positive)[number]): Buffer {
+ if ("plaintext_hex" in vector && typeof vector.plaintext_hex === "string") return hex(vector.plaintext_hex);
+ const length = vector.plaintext_len;
+ const bytes = Buffer.allocUnsafe(length);
+ for (let index = 0; index < length; index += 1) bytes[index] = index % 251;
+ return bytes;
+}
+
+async function sealStreamed(plaintext: Buffer, options: ConstructorParameters<typeof SealStream>[0], pieceSize: number) {
+ const sealer = new SealStream(options);
+ const out: Buffer[] = [];
+ sealer.on("data", (piece: Buffer) => out.push(piece));
+ const done = new Promise<void>((resolve, reject) => {
+ sealer.on("end", resolve);
+ sealer.on("error", reject);
+ });
+ for (let offset = 0; offset < plaintext.length; offset += pieceSize) sealer.write(plaintext.subarray(offset, offset + pieceSize));
+ sealer.end();
+ await done;
+ return { sealed: Buffer.concat(out), result: sealer.result() };
+}
+
+describe("ORSEAL01 vectors", () => {
+ test("keys and kids match the fixture", () => {
+ for (const name of ["server", "previous", "unrelated"] as const) {
+ const key = vectors.keys[name];
+ expect(x25519PublicRaw(x25519PrivateKey(hex(key.private_hex))).toString("hex")).toBe(key.public_hex);
+ expect(sealKid(hex(key.public_hex))).toBe(key.kid);
+ }
+ expect([...keyring.keys()]).toEqual(vectors.decoder_kids);
+ });
+
+ for (const vector of vectors.positive) {
+ test(`positive ${vector.name}: seal reproduces the vector and opens`, async () => {
+ if (!isKeyName(vector.recipient)) throw new Error(`unknown recipient ${vector.recipient}`);
+ const plaintext = plaintextOf(vector);
+ expect(sha256(plaintext)).toBe(vector.plaintext_sha256);
+ const options = { publicKey: hex(vectors.keys[vector.recipient].public_hex), chunk: vector.chunk, testOnlyFixedSecrets: fixed };
+ const whole = sealBuffer(plaintext, options);
+ expect(whole.kid).toBe(vector.kid);
+ expect(whole.size).toBe(vector.sealed_len);
+ expect(whole.sha256).toBe(vector.sealed_sha256);
+ expect(sha256(whole.sealed)).toBe(vector.sealed_sha256);
+ if ("sealed_hex" in vector && typeof vector.sealed_hex === "string") expect(whole.sealed.toString("hex")).toBe(vector.sealed_hex);
+ // The streaming sealer gives the same bytes whatever the write sizes.
+ for (const pieceSize of [1, 7, vector.chunk, 65_536]) {
+ if (plaintext.length > 100_000 && pieceSize < 1000) continue;
+ const streamed = await sealStreamed(plaintext, options, pieceSize);
+ expect(streamed.result.sha256).toBe(vector.sealed_sha256);
+ expect(streamed.sealed.equals(whole.sealed)).toBe(true);
+ }
+ expect((await openSealedBuffer(whole.sealed, keyring)).equals(plaintext)).toBe(true);
+ });
+ }
+
+ for (const vector of vectors.negative) {
+ test(`negative ${vector.name}: fails with ${vector.expect_error}`, async () => {
+ let code: string | null = null;
+ try {
+ await openSealedBuffer(hex(vector.sealed_hex), keyring);
+ } catch (error) {
+ code = error instanceof SealError ? error.code : `unexpected ${String(error)}`;
+ }
+ expect(code).toBe(vector.expect_error);
+ });
+ }
+});
+
+describe("ORSEAL01 streaming", () => {
+ test("a random multi-MiB payload round-trips with bounded frames", async () => {
+ const publicKey = hex(vectors.keys.server.public_hex);
+ const plaintext = randomBytes(5 * SEAL_CHUNK + 12_345);
+ const { sealed, result } = await sealStreamed(plaintext, { publicKey }, 300_000);
+ expect(result.size).toBe(sealed.length);
+ expect(result.sha256).toBe(sha256(sealed));
+ // 12 + header + L + 20 * frames (section 6.2).
+ const headerLength = sealed.readUInt32BE(8);
+ expect(sealed.length).toBe(12 + headerLength + plaintext.length + 20 * 6);
+ // Opening streams frame by frame from small source pieces: no emitted piece exceeds one chunk.
+ const source = Readable.from((function* () {
+ for (let offset = 0; offset < sealed.length; offset += 64 * 1024) yield sealed.subarray(offset, offset + 64 * 1024);
+ })());
+ const pieces: Buffer[] = [];
+ for await (const piece of openSealed(source, keyring)) {
+ expect(piece.length).toBeLessThanOrEqual(SEAL_CHUNK);
+ pieces.push(piece);
+ }
+ expect(Buffer.concat(pieces).equals(plaintext)).toBe(true);
+ });
+
+ test("fresh ephemeral keys and salts make every seal unique", () => {
+ const publicKey = hex(vectors.keys.server.public_hex);
+ const first = sealBuffer(Buffer.from("same"), { publicKey });
+ const second = sealBuffer(Buffer.from("same"), { publicKey });
+ expect(first.sealed.equals(second.sealed)).toBe(false);
+ expect(first.kid).toBe(vectors.keys.server.kid);
+ });
+
+ test("an archive sealed to an unrelated key is unknown_kid", async () => {
+ const { sealed } = sealBuffer(Buffer.from("x"), { publicKey: hex(vectors.keys.unrelated.public_hex) });
+ await expect(openSealedBuffer(sealed, keyring)).rejects.toMatchObject({ code: "unknown_kid" });
+ });
+});
diff --git a/apps/server/src/session-archive/seal.ts b/apps/server/src/session-archive/seal.ts
new file mode 100644
index 00000000..5586dfea
--- /dev/null
+++ b/apps/server/src/session-archive/seal.ts
@@ -0,0 +1,481 @@
+/**
+ * ORSEAL01: seals a byte stream to the omnirush.ai archive key (X25519 +
+ * HKDF-SHA256 + AES-256-GCM in authenticated frames). The format, the key id
+ * and the decoder's error rules are normative in
+ * docs/omnirush-project-archive.md section 6 of the backend repository; the
+ * shared vectors are in __fixtures__/orseal_vectors.json.
+ */
+import {
+ createCipheriv,
+ createDecipheriv,
+ createHash,
+ createPrivateKey,
+ createPublicKey,
+ diffieHellman,
+ generateKeyPairSync,
+ hkdfSync,
+ randomBytes,
+ type Hash,
+ type KeyObject,
+} from "node:crypto";
+import { Transform, type TransformCallback } from "node:stream";
+
+export const SEAL_MAGIC = Buffer.from("ORSEAL01", "ascii");
+export const SEAL_ALG = "X25519-HKDF-SHA256-A256GCM";
+export const SEAL_CONTENT = "tar+zstd";
+/** The only chunk size production writers use. */
+export const SEAL_CHUNK = 1 << 20;
+export const SEAL_MIN_CHUNK = 16;
+export const SEAL_MAX_CHUNK = 1 << 24;
+export const SEAL_MAX_HEADER_LEN = 4096;
+const TAG_LEN = 16;
+const MAX_FRAMES = 2 ** 32;
+const HKDF_INFO = Buffer.from("omnirush-seal-v1", "ascii");
+const HEADER_KEYS = new Set(["alg", "chunk", "content", "epk", "kid", "salt", "v"]);
+// DER wrappers that turn a raw 32-byte X25519 key into PKCS#8 / SPKI for Node's key objects.
+const PKCS8_X25519_PREFIX = Buffer.from("302e020100300506032b656e04220420", "hex");
+const SPKI_X25519_PREFIX = Buffer.from("302a300506032b656e032100", "hex");
+
+export type SealErrorCode =
+ | "bad_magic"
+ | "bad_header"
+ | "unsupported_version"
+ | "unknown_kid"
+ | "bad_frame_length"
+ | "tag_mismatch"
+ | "truncated"
+ | "frame_after_final";
+
+export class SealError extends Error {
+ constructor(readonly code: SealErrorCode) {
+ super(code);
+ this.name = "SealError";
+ }
+}
+
+function raw32(bytes: Uint8Array, what: string): Buffer {
+ if (bytes.length !== 32) throw new TypeError(`${what} must be 32 bytes`);
+ return Buffer.from(bytes);
+}
+
+export function x25519PrivateKey(raw: Uint8Array): KeyObject {
+ return createPrivateKey({ key: Buffer.concat([PKCS8_X25519_PREFIX, raw32(raw, "X25519 private key")]), format: "der", type: "pkcs8" });
+}
+
+export function x25519PublicKey(raw: Uint8Array): KeyObject {
+ return createPublicKey({ key: Buffer.concat([SPKI_X25519_PREFIX, raw32(raw, "X25519 public key")]), format: "der", type: "spki" });
+}
+
+/** The raw 32-byte public key of an X25519 private or public key object. */
+export function x25519PublicRaw(key: KeyObject): Buffer {
+ const publicKey = key.type === "private" ? createPublicKey(key) : key;
+ const der = publicKey.export({ format: "der", type: "spki" });
+ return Buffer.from(der.subarray(der.length - 32));
+}
+
+/** kid: the first 16 lowercase hex characters of SHA-256(raw public key). */
+export function sealKid(publicRaw: Uint8Array): string {
+ return createHash("sha256").update(raw32(publicRaw, "X25519 public key")).digest("hex").slice(0, 16);
+}
+
+function deriveKey(shared: Buffer, salt: Buffer, epk: Buffer, serverPublic: Buffer): Buffer {
+ return Buffer.from(hkdfSync("sha256", shared, salt, Buffer.concat([HKDF_INFO, epk, serverPublic]), 32));
+}
+
+function agree(privateKey: KeyObject, publicKey: KeyObject): Buffer | null {
+ let shared: Buffer;
+ try {
+ shared = diffieHellman({ privateKey, publicKey });
+ } catch {
+ return null;
+ }
+ // A low-order point yields an all-zero secret; Node already throws on it,
+ // the explicit check keeps that guarantee independent of the runtime.
+ return shared.every((byte) => byte === 0) ? null : shared;
+}
+
+function frameNonce(index: number): Buffer {
+ const nonce = Buffer.alloc(12);
+ nonce.writeBigUInt64BE(BigInt(index), 4);
+ return nonce;
+}
+
+function frameAad(headerHash: Buffer, index: number, final: boolean): Buffer {
+ const aad = Buffer.alloc(41);
+ headerHash.copy(aad, 0);
+ aad.writeBigUInt64BE(BigInt(index), 32);
+ aad[40] = final ? 1 : 0;
+ return aad;
+}
+
+/** One frame as pieces (length prefix, ciphertext, tag): no second copy of the ciphertext is made. */
+function encryptFrame(key: Buffer, headerHash: Buffer, index: number, final: boolean, plaintext: Buffer): Buffer[] {
+ const cipher = createCipheriv("aes-256-gcm", key, frameNonce(index));
+ cipher.setAAD(frameAad(headerHash, index, final));
+ const length = Buffer.allocUnsafe(4);
+ length.writeUInt32BE(plaintext.length + TAG_LEN, 0);
+ const body = cipher.update(plaintext);
+ const tail = cipher.final();
+ const pieces = [length, body];
+ if (tail.length > 0) pieces.push(tail);
+ pieces.push(cipher.getAuthTag());
+ return pieces;
+}
+
+function decryptFrame(key: Buffer, headerHash: Buffer, index: number, final: boolean, frame: Buffer): Buffer | null {
+ try {
+ const decipher = createDecipheriv("aes-256-gcm", key, frameNonce(index));
+ decipher.setAAD(frameAad(headerHash, index, final));
+ decipher.setAuthTag(frame.subarray(frame.length - TAG_LEN));
+ const head = decipher.update(frame.subarray(0, frame.length - TAG_LEN));
+ const tail = decipher.final();
+ return tail.length === 0 ? head : Buffer.concat([head, tail]);
+ } catch {
+ return null;
+ }
+}
+
+export type SealOptions = {
+ /** The recipient's raw 32-byte X25519 public key (GET /omnirush/archives/key). */
+ publicKey: Uint8Array;
+ /** Plaintext bytes per frame. Production MUST leave the default (1 MiB); the vectors use 16. */
+ chunk?: number;
+ /**
+ * TEST VECTORS ONLY. Fixes the ephemeral private key and the salt so a seal
+ * reproduces orseal_vectors.json byte for byte. Production code never sets
+ * it: every archive gets a fresh ephemeral key and salt from the CSPRNG.
+ */
+ testOnlyFixedSecrets?: { ephemeralPrivateKey: Uint8Array; salt: Uint8Array };
+};
+
+export type SealResult = { size: number; sha256: string };
+
+/**
+ * The ORSEAL01 framing core, shared by SealStream and sealBuffer. It holds at
+ * most one chunk of plaintext: a full chunk becomes a non-final frame only
+ * once more input arrives, and whatever is held at the end (possibly a full
+ * chunk, or nothing) becomes the final frame. It counts and hashes its own
+ * output, which the create request needs.
+ */
+class FrameSealer {
+ readonly kid: string;
+ private readonly key: Buffer;
+ private readonly headerHash: Buffer;
+ private readonly prefix: Buffer;
+ private readonly chunk: number;
+ private readonly pending: Buffer;
+ private pendingLength = 0;
+ private index = 0;
+ private started = false;
+ private readonly outputHash: Hash = createHash("sha256");
+ private outputBytes = 0;
+ private sealed: SealResult | null = null;
+
+ constructor(options: SealOptions) {
+ const chunk = options.chunk ?? SEAL_CHUNK;
+ if (!Number.isInteger(chunk) || chunk < SEAL_MIN_CHUNK || chunk > SEAL_MAX_CHUNK) throw new RangeError("invalid seal chunk size");
+ const serverPublicRaw = raw32(options.publicKey, "X25519 public key");
+ const ephemeral = options.testOnlyFixedSecrets
+ ? x25519PrivateKey(options.testOnlyFixedSecrets.ephemeralPrivateKey)
+ : generateKeyPairSync("x25519").privateKey;
+ const salt = options.testOnlyFixedSecrets ? raw32(options.testOnlyFixedSecrets.salt, "salt") : randomBytes(32);
+ const epk = x25519PublicRaw(ephemeral);
+ const shared = agree(ephemeral, x25519PublicKey(serverPublicRaw));
+ if (!shared) throw new RangeError("the archive public key is not a valid X25519 point");
+ this.kid = sealKid(serverPublicRaw);
+ this.chunk = chunk;
+ this.key = deriveKey(shared, salt, epk, serverPublicRaw);
+ // Key order alg, chunk, content, epk, kid, salt, v: sorted, as the format requires.
+ const header = Buffer.from(JSON.stringify({
+ alg: SEAL_ALG,
+ chunk,
+ content: SEAL_CONTENT,
+ epk: epk.toString("base64"),
+ kid: this.kid,
+ salt: salt.toString("base64"),
+ v: 1,
+ }), "utf8");
+ const length = Buffer.alloc(4);
+ length.writeUInt32BE(header.length, 0);
+ this.prefix = Buffer.concat([SEAL_MAGIC, length, header]);
+ this.headerHash = createHash("sha256").update(this.prefix).digest();
+ this.pending = Buffer.allocUnsafe(chunk);
+ }
+
+ get result(): SealResult | null {
+ return this.sealed;
+ }
+
+ private emit(bytes: Buffer, out: (bytes: Buffer) => void): void {
+ this.outputHash.update(bytes);
+ this.outputBytes += bytes.length;
+ out(bytes);
+ }
+
+ private start(out: (bytes: Buffer) => void): void {
+ if (this.started) return;
+ this.started = true;
+ this.emit(this.prefix, out);
+ }
+
+ private frame(final: boolean, out: (bytes: Buffer) => void): void {
+ if (this.index >= MAX_FRAMES) throw new RangeError("too many seal frames");
+ for (const piece of encryptFrame(this.key, this.headerHash, this.index, final, this.pending.subarray(0, this.pendingLength))) this.emit(piece, out);
+ this.index += 1;
+ this.pendingLength = 0;
+ }
+
+ update(bytes: Buffer, out: (bytes: Buffer) => void): void {
+ if (this.sealed) throw new Error("the seal is already finished");
+ this.start(out);
+ let offset = 0;
+ while (offset < bytes.length) {
+ if (this.pendingLength === this.chunk) this.frame(false, out);
+ const take = Math.min(bytes.length - offset, this.chunk - this.pendingLength);
+ bytes.copy(this.pending, this.pendingLength, offset, offset + take);
+ this.pendingLength += take;
+ offset += take;
+ }
+ }
+
+ finish(out: (bytes: Buffer) => void): SealResult {
+ if (this.sealed) throw new Error("the seal is already finished");
+ this.start(out);
+ this.frame(true, out);
+ this.sealed = { size: this.outputBytes, sha256: this.outputHash.digest("hex") };
+ return this.sealed;
+ }
+}
+
+/** Streaming ORSEAL01 sealer (section 6.6); memory is one chunk plus stream buffers. */
+export class SealStream extends Transform {
+ private readonly sealer: FrameSealer;
+
+ constructor(options: SealOptions) {
+ super();
+ this.sealer = new FrameSealer(options);
+ }
+
+ get kid(): string {
+ return this.sealer.kid;
+ }
+
+ /** Ciphertext size and SHA-256; available once the stream has finished. */
+ result(): SealResult {
+ const result = this.sealer.result;
+ if (!result) throw new Error("the seal stream has not finished");
+ return result;
+ }
+
+ override _transform(data: Buffer | string, encoding: BufferEncoding, callback: TransformCallback): void {
+ try {
+ this.sealer.update(typeof data === "string" ? Buffer.from(data, encoding) : data, (bytes) => this.push(bytes));
+ callback();
+ } catch (error) {
+ callback(error instanceof Error ? error : new Error(String(error)));
+ }
+ }
+
+ override _flush(callback: TransformCallback): void {
+ try {
+ this.sealer.finish((bytes) => this.push(bytes));
+ callback();
+ } catch (error) {
+ callback(error instanceof Error ? error : new Error(String(error)));
+ }
+ }
+}
+
+/** Seals a buffer in one call (tests and small payloads). */
+export function sealBuffer(plaintext: Uint8Array, options: SealOptions): { sealed: Buffer; kid: string } & SealResult {
+ const sealer = new FrameSealer(options);
+ const out: Buffer[] = [];
+ const push = (bytes: Buffer) => out.push(bytes);
+ sealer.update(Buffer.from(plaintext.buffer, plaintext.byteOffset, plaintext.byteLength), push);
+ const result = sealer.finish(push);
+ return { sealed: Buffer.concat(out), kid: sealer.kid, ...result };
+}
+
+// --- opening -------------------------------------------------------------------
+
+export type SealKey = { kid: string; privateKey: KeyObject; publicRaw: Buffer };
+/** kid -> key, every configured private key (current first). */
+export type SealKeyring = Map<string, SealKey>;
+
+export function sealKeyring(privateKeys: readonly Uint8Array[]): SealKeyring {
+ const keyring: SealKeyring = new Map();
+ for (const raw of privateKeys) {
+ const privateKey = x25519PrivateKey(raw);
+ const publicRaw = x25519PublicRaw(privateKey);
+ const kid = sealKid(publicRaw);
+ if (!keyring.has(kid)) keyring.set(kid, { kid, privateKey, publicRaw });
+ }
+ return keyring;
+}
+
+/** Exact reads plus a one-byte look-ahead over an async byte source. */
+class ByteReader {
+ private readonly iterator: AsyncIterator<Uint8Array>;
+ private buffered: Buffer[] = [];
+ private length = 0;
+ private done = false;
+
+ constructor(source: AsyncIterable<Uint8Array>) {
+ this.iterator = source[Symbol.asyncIterator]();
+ }
+
+ private async fill(wanted: number): Promise<void> {
+ while (this.length < wanted && !this.done) {
+ const next = await this.iterator.next();
+ if (next.done) {
+ this.done = true;
+ break;
+ }
+ if (next.value.length === 0) continue;
+ const piece = Buffer.from(next.value.buffer, next.value.byteOffset, next.value.byteLength);
+ this.buffered.push(piece);
+ this.length += piece.length;
+ }
+ }
+
+ /** Up to `count` bytes; fewer only at the end of the source. */
+ async read(count: number): Promise<Buffer> {
+ await this.fill(count);
+ const take = Math.min(count, this.length);
+ const joined = this.buffered.length === 1 ? this.buffered[0]! : Buffer.concat(this.buffered, this.length);
+ const out = Buffer.from(joined.subarray(0, take));
+ const rest = joined.subarray(take);
+ this.buffered = rest.length > 0 ? [rest] : [];
+ this.length = rest.length;
+ return out;
+ }
+
+ async more(): Promise<boolean> {
+ await this.fill(1);
+ return this.length > 0;
+ }
+
+ async close(): Promise<void> {
+ await this.iterator.return?.();
+ }
+}
+
+const UTF8 = new TextDecoder("utf-8", { fatal: true });
+const B64_32 = /^[A-Za-z0-9+/]{43}=$/;
+
+function canonicalBase64Of32(value: unknown): Buffer {
+ if (typeof value !== "string" || !B64_32.test(value)) throw new SealError("bad_header");
+ const raw = Buffer.from(value, "base64");
+ if (raw.length !== 32 || raw.toString("base64") !== value) throw new SealError("bad_header");
+ return raw;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+type OpenedHeader = { chunk: number; key: Buffer; headerHash: Buffer; kid: string };
+
+async function openHeader(reader: ByteReader, keyring: SealKeyring): Promise<OpenedHeader> {
+ const magic = await reader.read(8);
+ if (!magic.equals(SEAL_MAGIC)) throw new SealError("bad_magic");
+ const rawLength = await reader.read(4);
+ if (rawLength.length < 4) throw new SealError("truncated");
+ const length = rawLength.readUInt32BE(0);
+ if (length === 0 || length > SEAL_MAX_HEADER_LEN) throw new SealError("bad_header");
+ const head = await reader.read(length);
+ if (head.length < length) throw new SealError("truncated");
+ let header: unknown;
+ try {
+ header = JSON.parse(UTF8.decode(head));
+ } catch {
+ throw new SealError("bad_header");
+ }
+ if (!isRecord(header)) throw new SealError("bad_header");
+ const version = header.v;
+ if (typeof version !== "number" || !Number.isInteger(version)) throw new SealError("bad_header");
+ if (version !== 1) throw new SealError("unsupported_version");
+ const keys = Object.keys(header);
+ const { chunk, kid } = header;
+ if (
+ keys.length !== HEADER_KEYS.size
+ || !keys.every((key) => HEADER_KEYS.has(key))
+ || header.alg !== SEAL_ALG
+ || header.content !== SEAL_CONTENT
+ || typeof chunk !== "number"
+ || !Number.isInteger(chunk)
+ || chunk < SEAL_MIN_CHUNK
+ || chunk > SEAL_MAX_CHUNK
+ || typeof kid !== "string"
+ || !/^[0-9a-f]{16}$/.test(kid)
+ ) {
+ throw new SealError("bad_header");
+ }
+ const epk = canonicalBase64Of32(header.epk);
+ const salt = canonicalBase64Of32(header.salt);
+ const recipient = keyring.get(kid);
+ if (!recipient) throw new SealError("unknown_kid");
+ let ephemeralPublic: KeyObject;
+ try {
+ ephemeralPublic = x25519PublicKey(epk);
+ } catch {
+ throw new SealError("bad_header");
+ }
+ const shared = agree(recipient.privateKey, ephemeralPublic);
+ if (!shared) throw new SealError("bad_header");
+ return {
+ chunk,
+ kid,
+ key: deriveKey(shared, salt, epk, recipient.publicRaw),
+ headerHash: createHash("sha256").update(Buffer.concat([magic, rawLength, head])).digest(),
+ };
+}
+
+/**
+ * Opens an ORSEAL01 stream frame by frame (section 6.7). The plaintext is
+ * authentic only once the generator returns without throwing: a failing
+ * stream can yield a verified prefix first, and a caller must discard
+ * everything it received when a SealError is thrown.
+ */
+export async function* openSealed(source: AsyncIterable<Uint8Array>, keyring: SealKeyring): AsyncGenerator<Buffer, { kid: string }> {
+ const reader = new ByteReader(source);
+ try {
+ const { chunk, key, headerHash, kid } = await openHeader(reader, keyring);
+ for (let index = 0; ; index += 1) {
+ const rawLength = await reader.read(4);
+ if (rawLength.length < 4) throw new SealError("truncated");
+ const length = rawLength.readUInt32BE(0);
+ if (length < TAG_LEN || length > chunk + TAG_LEN) throw new SealError("bad_frame_length");
+ const frame = await reader.read(length);
+ if (frame.length < length) throw new SealError("truncated");
+ const more = await reader.more();
+ const full = length === chunk + TAG_LEN;
+ const final = !full || !more;
+ const plaintext = decryptFrame(key, headerHash, index, final, frame);
+ if (!plaintext) {
+ if (full && decryptFrame(key, headerHash, index, !final, frame)) {
+ throw new SealError(final ? "truncated" : "frame_after_final");
+ }
+ throw new SealError("tag_mismatch");
+ }
+ yield plaintext;
+ if (final) {
+ if (more) throw new SealError("frame_after_final");
+ return { kid };
+ }
+ }
+ } finally {
+ await reader.close();
+ }
+}
+
+async function* once(bytes: Uint8Array): AsyncGenerator<Uint8Array> {
+ yield bytes;
+}
+
+/** Opens a whole sealed buffer; throws SealError on any failure. */
+export async function openSealedBuffer(sealed: Uint8Array, keyring: SealKeyring): Promise<Buffer> {
+ const pieces: Buffer[] = [];
+ for await (const piece of openSealed(once(sealed), keyring)) pieces.push(piece);
+ return Buffer.concat(pieces);
+}
diff --git a/apps/server/src/session-archive/test-helpers.ts b/apps/server/src/session-archive/test-helpers.ts
new file mode 100644
index 00000000..20a8815f
--- /dev/null
+++ b/apps/server/src/session-archive/test-helpers.ts
@@ -0,0 +1,112 @@
+/** Shared helpers for the session-archive tests (not used by production code). */
+import { mkdtemp, realpath, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { zstdDecompressSync } from "node:zlib";
+
+import vectors from "./__fixtures__/orseal_vectors.json" with { type: "json" };
+import { openSealedBuffer, sealKeyring } from "./seal.js";
+
+const created: string[] = [];
+
+/** A fresh temp directory by its real path (macOS temp paths go through a /var symlink). */
+export async function tempDir(prefix: string): Promise<string> {
+ const dir = await realpath(await mkdtemp(join(tmpdir(), `omnirush-archive-test-${prefix}-`)));
+ created.push(dir);
+ return dir;
+}
+
+export async function cleanupTempDirs(): Promise<void> {
+ await Promise.all(created.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+}
+
+export async function collectStream(stream: AsyncIterable<Uint8Array>): Promise<Buffer> {
+ const pieces: Buffer[] = [];
+ for await (const piece of stream) pieces.push(Buffer.from(piece));
+ return Buffer.concat(pieces);
+}
+
+export type TarMemberRead = { name: string; typeflag: string; mode: number; size: number; mtime: number; linkname: string; uid: number; gid: number; content: Buffer };
+
+function field(block: Buffer, offset: number, length: number): string {
+ const raw = block.subarray(offset, offset + length);
+ const end = raw.indexOf(0);
+ return raw.subarray(0, end === -1 ? length : end).toString("utf8");
+}
+
+function octal(block: Buffer, offset: number, length: number): number {
+ const text = field(block, offset, length).trim();
+ return text ? Number.parseInt(text, 8) : 0;
+}
+
+/** A minimal pax-aware tar reader for assertions: ustar members plus `x` records (path, linkpath, size). */
+export function readTar(tar: Buffer): TarMemberRead[] {
+ const members: TarMemberRead[] = [];
+ let offset = 0;
+ let pax: Record<string, string> = {};
+ while (offset + 512 <= tar.length) {
+ const block = tar.subarray(offset, offset + 512);
+ if (block.every((byte) => byte === 0)) break;
+ let sum = 0;
+ for (let index = 0; index < 512; index += 1) sum += index >= 148 && index < 156 ? 0x20 : block[index]!;
+ if (sum !== octal(block, 148, 8)) throw new Error(`bad tar checksum at ${offset}`);
+ const typeflag = field(block, 156, 1);
+ let size = octal(block, 124, 12);
+ offset += 512;
+ if (typeflag === "x") {
+ const body = tar.subarray(offset, offset + size);
+ pax = {};
+ let position = 0;
+ while (position < body.length) {
+ const space = body.indexOf(0x20, position);
+ const length = Number.parseInt(body.subarray(position, space).toString("ascii"), 10);
+ if (!(length > 0) || body[position + length - 1] !== 0x0a) throw new Error("bad pax record");
+ const record = body.subarray(space + 1, position + length - 1).toString("utf8");
+ const equals = record.indexOf("=");
+ pax[record.slice(0, equals)] = record.slice(equals + 1);
+ position += length;
+ }
+ offset += Math.ceil(size / 512) * 512;
+ continue;
+ }
+ const prefix = field(block, 345, 155);
+ let name = pax.path ?? (prefix ? `${prefix}/${field(block, 0, 100)}` : field(block, 0, 100));
+ if (pax.size) size = Number(pax.size);
+ const linkname = pax.linkpath ?? field(block, 157, 100);
+ if (typeflag === "5" && name.endsWith("/")) name = name.slice(0, -1);
+ members.push({
+ name,
+ typeflag,
+ mode: octal(block, 100, 8),
+ size,
+ mtime: octal(block, 136, 12),
+ linkname,
+ uid: octal(block, 108, 8),
+ gid: octal(block, 116, 8),
+ content: Buffer.from(tar.subarray(offset, offset + size)),
+ });
+ pax = {};
+ offset += Math.ceil(size / 512) * 512;
+ }
+ return members;
+}
+
+export const testKeys = {
+ publicKey: Buffer.from(vectors.keys.server.public_hex, "hex"),
+ publicB64: vectors.keys.server.public_b64,
+ kid: vectors.keys.server.kid,
+ keyring: sealKeyring([Buffer.from(vectors.keys.server.private_hex, "hex")]),
+};
+
+/** Sealed archive bytes -> the tar members inside (unseal, unzstd, parse). */
+export async function openArchive(sealed: Buffer): Promise<TarMemberRead[]> {
+ return readTar(zstdDecompressSync(await openSealedBuffer(sealed, testKeys.keyring)));
+}
+
+export function manifestOf(members: readonly TarMemberRead[]): Record<string, unknown> {
+ const first = members[0];
+ if (!first || first.name !== "__omnirush__/manifest.json") throw new Error("the manifest is not the first member");
+ const parsed: unknown = JSON.parse(first.content.toString("utf8"));
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("the manifest is not an object");
+ return Object.fromEntries(Object.entries(parsed));
+}
diff --git a/apps/server/src/session-archive/upload.test.ts b/apps/server/src/session-archive/upload.test.ts
new file mode 100644
index 00000000..f4e0d457
--- /dev/null
+++ b/apps/server/src/session-archive/upload.test.ts
@@ -0,0 +1,285 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { randomBytes, randomUUID } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { FakeArchiveServer } from "./fake-archive-server.js";
+import { cleanupTempDirs, tempDir, testKeys } from "./test-helpers.js";
+import { ArchiveUploader, resolveArchiveApiRoot, type ArchiveUploadJob, type ArchiveUploaderOptions } from "./upload.js";
+
+afterEach(cleanupTempDirs);
+
+const FAST_RETRY = { baseMs: 1, maxMs: 2, attempts: 3 };
+
+async function sealedJob(bytes = randomBytes(4 * 1024 + 100), overrides: Partial<ArchiveUploadJob["request"]> = {}) {
+ const dir = await tempDir("upload");
+ const sealedPath = join(dir, "archive.orseal");
+ await writeFile(sealedPath, bytes);
+ const job: ArchiveUploadJob = {
+ request: {
+ archive_id: randomUUID(),
+ session_id: "ses_upload_test",
+ kind: "base",
+ sequence: 0,
+ turn: 0,
+ parent_archive_id: null,
+ size: bytes.length,
+ sha256: "0".repeat(64),
+ kid: testKeys.kid,
+ content: "tar+zstd",
+ marker: ".git",
+ ...overrides,
+ },
+ sealedPath,
+ upload: null,
+ recreates: 0,
+ };
+ const persisted: string[] = [];
+ const persist = async () => {
+ persisted.push(JSON.stringify(job.upload));
+ };
+ return { job, bytes, persist, persisted };
+}
+
+function uploader(server: FakeArchiveServer, options: Partial<ArchiveUploaderOptions> = {}) {
+ return new ArchiveUploader({ gatewayUrl: server.gatewayUrl, accessToken: server.token, fetch: server.respond, retry: FAST_RETRY, ...options });
+}
+
+describe("archive upload client", () => {
+ test("the API root is derived like the collect URL", () => {
+ expect(resolveArchiveApiRoot("https://api.omnirush.ai/omnirush/v1/")).toBe("https://api.omnirush.ai/omnirush");
+ expect(resolveArchiveApiRoot("https://api.omnirush.ai/omnirush")).toBe("https://api.omnirush.ai/omnirush");
+ expect(resolveArchiveApiRoot("http://127.0.0.1:8080/v1")).toBe("http://127.0.0.1:8080");
+ expect(resolveArchiveApiRoot("http://api.omnirush.ai/v1")).toBeNull();
+ expect(resolveArchiveApiRoot(undefined)).toBeNull();
+ });
+
+ test("happy path: create, PUT every part from the file, complete", async () => {
+ const server = new FakeArchiveServer();
+ const { job, bytes, persist } = await sealedJob();
+ const outcome = await uploader(server).upload(job, persist);
+ expect(outcome).toEqual({ status: "uploaded" });
+ const [archive] = server.objects();
+ expect(archive!.object!.equals(bytes)).toBe(true);
+ expect(server.puts.map((put) => put.partNumber)).toEqual([1, 2, 3, 4, 5]);
+ expect(server.callPaths()).toEqual(["POST archives 201", `POST archives/${job.request.archive_id}/complete 200`]);
+ expect(Object.keys(job.upload!.etags)).toHaveLength(5);
+ });
+
+ test("the key route: kid checked against the public key; 428 and 503 turn archiving off", async () => {
+ const server = new FakeArchiveServer();
+ const client = uploader(server);
+ const key = await client.fetchKey();
+ expect(key.status).toBe("ok");
+ if (key.status === "ok") expect(key.key.publicKey.equals(testKeys.publicKey)).toBe(true);
+ server.gate = { status: 428, detail: "archive_consent_required" };
+ expect(await client.fetchKey()).toEqual({ status: "disabled", code: "archive_consent_required" });
+ server.gate = { status: 503, detail: "archive_disabled" };
+ expect(await client.fetchKey()).toEqual({ status: "disabled", code: "archive_disabled" });
+ // A 503 that is not archive_disabled is an outage, retried and then left for later.
+ server.gate = { status: 503, detail: "maintenance" };
+ expect((await client.fetchKey()).status).toBe("unavailable");
+ });
+
+ test("428 and 503 archive_disabled on create turn archiving off without an error", async () => {
+ for (const gate of [{ status: 428, detail: "archive_consent_required" }, { status: 503, detail: "archive_disabled" }]) {
+ const server = new FakeArchiveServer();
+ server.gate = gate;
+ const { job, persist } = await sealedJob();
+ expect(await uploader(server).upload(job, persist)).toEqual({ status: "disabled", code: gate.detail });
+ expect(server.puts).toHaveLength(0);
+ expect(server.calls).toHaveLength(1);
+ }
+ });
+
+ test("resume after a failed part: the failed part is sent again and the others are skipped", async () => {
+ const server = new FakeArchiveServer();
+ let failing = true;
+ server.putHook = ({ partNumber }) => (failing && partNumber === 3 ? "network" : undefined);
+ const { job, bytes, persist, persisted } = await sealedJob();
+ const first = await uploader(server).upload(job, persist);
+ expect(first.status).toBe("retry_later");
+ // Parts 1 and 2 made it and were persisted before the failure.
+ expect(Object.keys(job.upload!.etags).sort()).toEqual(["1", "2"]);
+ expect(persisted.length).toBeGreaterThanOrEqual(3);
+ // The app restarts from the persisted record: one /parts call, then only the missing parts.
+ const restored: ArchiveUploadJob = JSON.parse(JSON.stringify(job));
+ failing = false;
+ server.puts.length = 0;
+ const second = await uploader(server).upload(restored, persist);
+ expect(second).toEqual({ status: "uploaded" });
+ expect(server.puts.map((put) => put.partNumber)).toEqual([3, 4, 5]);
+ expect(server.objects()[0]!.object!.equals(bytes)).toBe(true);
+ expect(server.callPaths().filter((call) => call.includes("/parts"))).toEqual([`POST archives/${job.request.archive_id}/parts 200`]);
+ });
+
+ test("a part S3 already holds (answer lost before it was persisted) is not sent again", async () => {
+ const server = new FakeArchiveServer();
+ const { job, bytes, persist } = await sealedJob();
+ let crash = true;
+ const client = uploader(server);
+ // Parts 1 and 2 go up, part 3 fails; then "crash" as if part 2's etag had never been persisted.
+ server.putHook = ({ partNumber }) => (crash && partNumber === 3 ? "network" : undefined);
+ expect((await client.upload(job, persist)).status).toBe("retry_later");
+ delete job.upload!.etags["2"];
+ crash = false;
+ server.puts.length = 0;
+ expect(await client.upload(job, persist)).toEqual({ status: "uploaded" });
+ expect(server.puts.map((put) => put.partNumber)).toEqual([3, 4, 5]);
+ expect(server.objects()[0]!.object!.equals(bytes)).toBe(true);
+ });
+
+ test("an expired presigned URL (403) is refreshed through /parts and retried", async () => {
+ const server = new FakeArchiveServer();
+ const { job, bytes, persist } = await sealedJob();
+ server.putHook = ({ partNumber, attempt }) => {
+ if (partNumber === 2 && attempt === 1) server.expireUrls();
+ return undefined;
+ };
+ expect(await uploader(server).upload(job, persist)).toEqual({ status: "uploaded" });
+ expect(server.puts.map((put) => `${put.partNumber}:${put.status}`)).toEqual(["1:200", "2:403", "2:200", "3:200", "4:200", "5:200"]);
+ expect(server.callPaths()).toContain(`POST archives/${job.request.archive_id}/parts 200`);
+ expect(server.objects()[0]!.object!.equals(bytes)).toBe(true);
+ });
+
+ test("401: the bearer is refreshed once and the call retried; a failed refresh blocks the drain", async () => {
+ const server = new FakeArchiveServer();
+ server.token = "token-2";
+ const { job, persist } = await sealedJob();
+ let refreshes = 0;
+ const client = uploader(server, {
+ accessToken: "token-1",
+ refreshAccessToken: async () => {
+ refreshes += 1;
+ return "token-2";
+ },
+ });
+ expect(await client.upload(job, persist)).toEqual({ status: "uploaded" });
+ expect(refreshes).toBe(1);
+ expect(server.callPaths()[0]).toBe("POST archives 401");
+
+ const other = new FakeArchiveServer();
+ other.token = "rotated";
+ const second = await sealedJob();
+ const stuck = uploader(other, { accessToken: "stale", refreshAccessToken: async () => null });
+ expect(await stuck.upload(second.job, second.persist)).toEqual({ status: "blocked", reason: "unauthorized" });
+ });
+
+ test("NoSuchUpload on a part: /parts answers archive_not_uploading and the upload is re-created", async () => {
+ const server = new FakeArchiveServer();
+ const { job, bytes, persist } = await sealedJob();
+ let forgotten = false;
+ server.putHook = ({ archiveId, partNumber }) => {
+ if (partNumber === 3 && !forgotten) {
+ forgotten = true;
+ server.forgetUpload(archiveId);
+ }
+ return undefined;
+ };
+ expect(await uploader(server).upload(job, persist)).toEqual({ status: "uploaded" });
+ const paths = server.callPaths();
+ expect(paths).toEqual([
+ "POST archives 201",
+ `POST archives/${job.request.archive_id}/parts 409`,
+ "POST archives 201",
+ `POST archives/${job.request.archive_id}/complete 200`,
+ ]);
+ // The restarted upload sends every part again.
+ expect(server.puts.filter((put) => put.status === 200).map((put) => put.partNumber)).toEqual([1, 2, 1, 2, 3, 4, 5]);
+ expect(server.objects()[0]!.object!.equals(bytes)).toBe(true);
+ });
+
+ test("archive_not_uploading at complete re-creates with the same body", async () => {
+ const server = new FakeArchiveServer();
+ const { job, bytes, persist } = await sealedJob();
+ let aborted = false;
+ server.apiHook = ({ path }) => {
+ if (path.endsWith("/complete") && !aborted) {
+ aborted = true;
+ server.forgetUpload(job.request.archive_id);
+ }
+ return undefined;
+ };
+ expect(await uploader(server).upload(job, persist)).toEqual({ status: "uploaded" });
+ expect(server.callPaths()).toEqual([
+ "POST archives 201",
+ `POST archives/${job.request.archive_id}/complete 409`,
+ "POST archives 201",
+ `POST archives/${job.request.archive_id}/complete 200`,
+ ]);
+ expect(server.objects()[0]!.object!.equals(bytes)).toBe(true);
+ });
+
+ test("archive_parts_invalid at complete relists and re-uploads what S3 lacks", async () => {
+ const server = new FakeArchiveServer();
+ const { job, bytes, persist } = await sealedJob();
+ let dropped = false;
+ server.apiHook = ({ path }) => {
+ if (path.endsWith("/complete") && !dropped) {
+ dropped = true;
+ server.archives.get(job.request.archive_id)!.parts!.delete(4);
+ }
+ return undefined;
+ };
+ expect(await uploader(server).upload(job, persist)).toEqual({ status: "uploaded" });
+ expect(server.puts.map((put) => put.partNumber)).toEqual([1, 2, 3, 4, 5, 4]);
+ expect(server.objects()[0]!.object!.equals(bytes)).toBe(true);
+ });
+
+ test("a replayed create of an uploaded archive is done; chain-ending conflicts stop the session; an unknown kid asks for a new seal", async () => {
+ const server = new FakeArchiveServer();
+ const { job, persist } = await sealedJob();
+ const client = uploader(server);
+ expect(await client.upload(job, persist)).toEqual({ status: "uploaded" });
+ const replay: ArchiveUploadJob = { ...job, upload: null };
+ expect(await client.upload(replay, persist)).toEqual({ status: "uploaded" });
+
+ const conflict = await sealedJob(undefined, { archive_id: randomUUID() });
+ expect(await client.upload(conflict.job, conflict.persist)).toEqual({ status: "stop_session", code: "archive_sequence_conflict" });
+
+ const orphan = await sealedJob(undefined, { kind: "delta", sequence: 1, turn: 1, parent_archive_id: randomUUID(), session_id: "ses_other_1" });
+ expect(await client.upload(orphan.job, orphan.persist)).toEqual({ status: "stop_session", code: "archive_parent_mismatch" });
+
+ const rekey = await sealedJob(undefined, { kid: "0123456789abcdef", session_id: "ses_other_2" });
+ expect(await client.upload(rekey.job, rekey.persist)).toEqual({ status: "rekey", code: "archive_kid_unknown" });
+ });
+
+ test("network errors and 5xx back off and are left for a later drain; 502 recovers", async () => {
+ const server = new FakeArchiveServer();
+ const { job, persist } = await sealedJob();
+ let failures = 0;
+ server.apiHook = ({ path }) => {
+ if (path === "archives" && failures < 2) {
+ failures += 1;
+ return failures === 1 ? "network" : new Response(JSON.stringify({ detail: "archive_storage_error" }), { status: 502 });
+ }
+ return undefined;
+ };
+ const slept: number[] = [];
+ const client = uploader(server, { retry: { ...FAST_RETRY, sleep: async (ms) => void slept.push(ms) } });
+ expect(await client.upload(job, persist)).toEqual({ status: "uploaded" });
+ expect(slept).toHaveLength(2);
+
+ const down = new FakeArchiveServer();
+ down.apiHook = () => "network";
+ const second = await sealedJob();
+ expect((await uploader(down).upload(second.job, second.persist)).status).toBe("retry_later");
+ });
+
+ test("an API request hook replaces the bearer handling (the gateway broker path)", async () => {
+ const server = new FakeArchiveServer();
+ const { job, persist } = await sealedJob();
+ const seen: string[] = [];
+ const client = new ArchiveUploader({
+ fetch: server.respond,
+ retry: FAST_RETRY,
+ request: (path, init) => {
+ seen.push(`${init.method} ${path}`);
+ return server.respond(`https://api.omnirush.test/omnirush/${path}`, { method: init.method, body: init.body, headers: { Authorization: `Bearer ${server.token}` } });
+ },
+ });
+ expect(client.configured).toBe(true);
+ expect(await client.upload(job, persist)).toEqual({ status: "uploaded" });
+ expect(seen).toEqual(["POST archives", `POST archives/${job.request.archive_id}/complete`]);
+ });
+});
diff --git a/apps/server/src/session-archive/upload.ts b/apps/server/src/session-archive/upload.ts
new file mode 100644
index 00000000..116f83bb
--- /dev/null
+++ b/apps/server/src/session-archive/upload.ts
@@ -0,0 +1,562 @@
+/**
+ * The archive upload client (sections 7 and 13.5): JSON calls to the
+ * omnirush.ai archive routes, and part PUTs straight to S3 through presigned
+ * URLs, each part read from the sealed file when it is sent. Presigned URLs
+ * and bearer tokens are credentials and are never logged.
+ */
+import { open, type FileHandle } from "node:fs/promises";
+import { z } from "zod";
+
+import { SEAL_ALG, SEAL_CONTENT, sealKid } from "./seal.js";
+
+export type ArchiveFetch = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * An authenticated request to the omnirush.ai API, relative to its root
+ * (`archives/key`, `archives`, `archives/<id>/parts`, ...). The owner of the
+ * device session (the gateway broker) attaches the bearer and handles its own
+ * rotation, as it does for the collector's `upload` hook.
+ */
+export type ArchiveApiRequest = (path: string, init: { method: "GET" | "POST"; body?: string; signal?: AbortSignal }) => Promise<Response>;
+export type ArchiveLog = (level: "info" | "warn", message: string, attributes?: Record<string, unknown>) => void;
+
+export type RetryPolicy = {
+ /** First backoff; doubles per attempt (1 s). */
+ baseMs: number;
+ /** Backoff cap (5 min). */
+ maxMs: number;
+ /** Attempts per request before it is left to the next drain (8). */
+ attempts: number;
+ sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+ random: () => number;
+};
+
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+ return new Promise((resolvePromise) => {
+ if (signal?.aborted) {
+ resolvePromise();
+ return;
+ }
+ const timer = setTimeout(done, ms);
+ function done() {
+ clearTimeout(timer);
+ signal?.removeEventListener("abort", done);
+ resolvePromise();
+ }
+ signal?.addEventListener("abort", done, { once: true });
+ });
+}
+
+export const DEFAULT_RETRY_POLICY: RetryPolicy = { baseMs: 1_000, maxMs: 5 * 60_000, attempts: 8, sleep, random: Math.random };
+
+/** Exponential backoff with plus or minus 20% jitter. */
+export function backoffMs(policy: RetryPolicy, attempt: number): number {
+ const exact = Math.min(policy.maxMs, policy.baseMs * 2 ** Math.max(0, attempt - 1));
+ return Math.round(exact * (0.8 + 0.4 * policy.random()));
+}
+
+const REQUEST_TIMEOUT_MS = 30_000;
+/** A part PUT may take this long at least, and longer for big parts on slow links (32 KB/s floor). */
+const PART_MIN_TIMEOUT_MS = 10 * 60_000;
+const PART_MIN_BYTES_PER_MS = 32;
+/** A part is read from the sealed file in slices this big, checking for an abort between them. */
+const PART_READ_SLICE_BYTES = 1024 * 1024;
+const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+const PART_RETRYABLE_STATUSES = new Set([400, 408, 429, 500, 502, 503, 504]);
+const MAX_PARTS_PER_REQUEST = 100;
+const MAX_UPLOAD_ROUNDS = 6;
+/** Create conflicts that end the session's chain (section 7.9). */
+const CHAIN_ENDING_CODES = new Set(["archive_id_conflict", "archive_sequence_conflict", "archive_parent_mismatch", "archive_deleted"]);
+
+/**
+ * The omnirush.ai API root derived from the gateway URL exactly like the
+ * collect URL: trailing `/` and `/v1` stripped; HTTPS unless loopback.
+ */
+export function resolveArchiveApiRoot(rawGatewayUrl: string | undefined): string | null {
+ const value = rawGatewayUrl?.trim();
+ if (!value) return null;
+ try {
+ const url = new URL(value);
+ if (url.protocol !== "https:" && !(url.protocol === "http:" && ["127.0.0.1", "localhost", "[::1]", "::1"].includes(url.hostname))) return null;
+ url.pathname = url.pathname.replace(/\/+$/, "").replace(/\/v1$/, "");
+ url.search = "";
+ url.hash = "";
+ return url.toString().replace(/\/+$/, "");
+ } catch {
+ return null;
+ }
+}
+
+export type ArchiveCreateRequest = {
+ archive_id: string;
+ session_id: string;
+ kind: "base" | "delta";
+ sequence: number;
+ turn: number;
+ parent_archive_id: string | null;
+ size: number;
+ sha256: string;
+ kid: string;
+ content: typeof SEAL_CONTENT;
+ marker: string;
+};
+
+export type ArchiveUploadState = {
+ upload_id: string;
+ object_key: string;
+ part_size: number;
+ part_count: number;
+ /** part number -> ETag exactly as S3 returned it (quotes included). */
+ etags: Record<string, string>;
+};
+
+/** What the uploader needs from a queued job; it mutates `upload` and `recreates` and persists through the callback. */
+export type ArchiveUploadJob = {
+ request: ArchiveCreateRequest;
+ sealedPath: string;
+ upload: ArchiveUploadState | null;
+ recreates: number;
+};
+
+export type ArchiveKey = { kid: string; publicKey: Buffer; alg: string };
+
+export type KeyResult =
+ | { status: "ok"; key: ArchiveKey }
+ | { status: "disabled"; code: string }
+ | { status: "unavailable"; reason: string };
+
+export type UploadOutcome =
+ | { status: "uploaded" }
+ /** 428 / 503 archive_disabled: archiving is off for the user, without error. */
+ | { status: "disabled"; code: string }
+ /** 401 after a refresh, or 403: stop draining and keep the queue. */
+ | { status: "blocked"; reason: string }
+ /** A chain-ending conflict, 413 or 422: drop the session's jobs and stop archiving it. */
+ | { status: "stop_session"; code: string }
+ /** 409 archive_kid_unknown: the archive was sealed to a key the server no longer has. */
+ | { status: "rekey"; code: string }
+ /** Transient failure after the retries: leave the job to a later drain. */
+ | { status: "retry_later"; reason: string }
+ | { status: "aborted" };
+
+const keySchema = z.object({ kid: z.string().regex(/^[0-9a-f]{16}$/), public_key: z.string(), alg: z.string() });
+const partUrlSchema = z.object({ part_number: z.number().int().min(1), url: z.string().min(1) });
+const createSchema = z.object({
+ archive_id: z.string(),
+ status: z.string(),
+ upload_id: z.string().nullish(),
+ object_key: z.string().nullish(),
+ part_size: z.number().int().positive().nullish(),
+ part_count: z.number().int().positive().nullish(),
+ parts: z.array(partUrlSchema).nullish(),
+});
+const partsSchema = z.object({
+ parts: z.array(partUrlSchema),
+ uploaded: z.array(z.object({ part_number: z.number().int().min(1), etag: z.string().min(1), size: z.number().int().nonnegative() })).nullish(),
+});
+
+type ApiResult =
+ | { kind: "ok"; status: number; body: unknown }
+ | { kind: "error"; status: number; code: string | null }
+ | { kind: "unavailable"; reason: string }
+ | { kind: "aborted" };
+
+async function errorCode(response: Response): Promise<string | null> {
+ try {
+ const body: unknown = await response.json();
+ if (typeof body !== "object" || body === null) return null;
+ if ("detail" in body && typeof body.detail === "string") return body.detail;
+ if ("error" in body && typeof body.error === "string") return body.error;
+ } catch {
+ // Not JSON: the status alone decides.
+ }
+ return null;
+}
+
+function timeoutSignal(ms: number, signal?: AbortSignal): AbortSignal {
+ const timeout = AbortSignal.timeout(ms);
+ return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+export type ArchiveUploaderOptions = {
+ gatewayUrl?: string;
+ accessToken?: string;
+ refreshAccessToken?: () => Promise<string | null>;
+ /** External egress (S3 PUTs, and API calls without `request`). */
+ fetch: ArchiveFetch;
+ request?: ArchiveApiRequest;
+ retry?: Partial<RetryPolicy>;
+ log?: ArchiveLog;
+};
+
+type PartsResult = { urls: Map<number, string>; uploaded: Array<{ part_number: number; etag: string; size: number }> };
+
+/**
+ * One part of the sealed file, read into a single buffer (null once `signal`
+ * aborted: nothing more is read). A single-chunk body gets a Content-Length
+ * from every fetch and is copied once by Electron's net.fetch, which collects
+ * a streamed body with one Buffer.concat per chunk before sending it; a 64 MiB
+ * part streamed in 64 KiB Blob chunks costs seconds of main-process copying.
+ */
+async function readPart(file: FileHandle, start: number, length: number, signal?: AbortSignal): Promise<Uint8Array<ArrayBuffer> | null> {
+ const bytes = new Uint8Array(new ArrayBuffer(length));
+ let offset = 0;
+ while (offset < length) {
+ if (signal?.aborted) return null;
+ const { bytesRead } = await file.read(bytes, offset, Math.min(PART_READ_SLICE_BYTES, length - offset), start + offset);
+ if (bytesRead === 0) throw new Error("archive file ended early");
+ offset += bytesRead;
+ }
+ return signal?.aborted ? null : bytes;
+}
+
+export class ArchiveUploader {
+ private token: string | null;
+ private readonly apiRoot: string | null;
+ private readonly retry: RetryPolicy;
+ private readonly log: ArchiveLog;
+
+ constructor(private readonly options: ArchiveUploaderOptions) {
+ this.token = options.accessToken?.trim() || null;
+ this.apiRoot = resolveArchiveApiRoot(options.gatewayUrl);
+ this.retry = { ...DEFAULT_RETRY_POLICY, ...options.retry };
+ this.log = options.log ?? (() => undefined);
+ }
+
+ /** Whether the API can be reached at all: a request hook, or a gateway URL plus a bearer. */
+ get configured(): boolean {
+ return Boolean(this.options.request) || (this.apiRoot !== null && this.token !== null);
+ }
+
+ setAccessToken(token: string | null): void {
+ this.token = token?.trim() || null;
+ }
+
+ private send(method: "GET" | "POST", path: string, body: unknown, signal?: AbortSignal): Promise<Response> {
+ const payload = body === undefined ? undefined : JSON.stringify(body);
+ if (this.options.request) return this.options.request(path, { method, ...(payload === undefined ? {} : { body: payload }), signal: timeoutSignal(REQUEST_TIMEOUT_MS, signal) });
+ if (!this.apiRoot || !this.token) return Promise.reject(new Error("archive API not configured"));
+ return this.options.fetch(`${this.apiRoot}/${path}`, {
+ method,
+ headers: {
+ Authorization: `Bearer ${this.token}`,
+ Accept: "application/json",
+ ...(payload === undefined ? {} : { "Content-Type": "application/json" }),
+ },
+ ...(payload === undefined ? {} : { body: payload }),
+ signal: timeoutSignal(REQUEST_TIMEOUT_MS, signal),
+ });
+ }
+
+ private async refresh(): Promise<boolean> {
+ if (!this.options.refreshAccessToken) return false;
+ try {
+ const token = (await this.options.refreshAccessToken())?.trim() ?? "";
+ if (!token) return false;
+ this.token = token;
+ return true;
+ } catch {
+ return false;
+ }
+ }
+
+ /** One API call: 401 refreshes the bearer once; network errors and retryable statuses back off. */
+ private async call(method: "GET" | "POST", path: string, body: unknown, signal?: AbortSignal): Promise<ApiResult> {
+ let refreshed = false;
+ let attempt = 0;
+ for (;;) {
+ if (signal?.aborted) return { kind: "aborted" };
+ let response: Response;
+ let failure: string;
+ try {
+ response = await this.send(method, path, body, signal);
+ if (response.ok) {
+ const parsed: unknown = await response.json().catch(() => null);
+ return { kind: "ok", status: response.status, body: parsed };
+ }
+ const code = await errorCode(response);
+ if (response.status === 401 && !refreshed) {
+ refreshed = true;
+ if (await this.refresh()) continue;
+ }
+ if (!RETRYABLE_STATUSES.has(response.status) || (response.status === 503 && code === "archive_disabled")) {
+ return { kind: "error", status: response.status, code };
+ }
+ failure = `status ${response.status}`;
+ } catch (error) {
+ if (signal?.aborted) return { kind: "aborted" };
+ failure = error instanceof Error ? error.name : "network error";
+ }
+ attempt += 1;
+ if (attempt >= this.retry.attempts) return { kind: "unavailable", reason: failure };
+ await this.retry.sleep(backoffMs(this.retry, attempt), signal);
+ }
+ }
+
+ /** The outcome for failures every route shares (7.1, 7.9); null when the caller decides. */
+ private common(result: ApiResult): UploadOutcome | null {
+ if (result.kind === "aborted") return { status: "aborted" };
+ if (result.kind === "unavailable") return { status: "retry_later", reason: result.reason };
+ if (result.kind === "ok") return null;
+ if (result.status === 401) return { status: "blocked", reason: "unauthorized" };
+ if (result.status === 403) return { status: "blocked", reason: result.code ?? "forbidden" };
+ if (result.status === 428) return { status: "disabled", code: result.code ?? "archive_consent_required" };
+ if (result.status === 503) return { status: "disabled", code: result.code ?? "archive_disabled" };
+ if (result.status === 413) return { status: "stop_session", code: result.code ?? "archive_too_large" };
+ if (result.status === 422) return { status: "stop_session", code: "archive_request_invalid" };
+ return null;
+ }
+
+ /** GET /archives/key (7.2). 428, 503 and a server without the route all mean archiving is off. */
+ async fetchKey(signal?: AbortSignal): Promise<KeyResult> {
+ if (!this.configured) return { status: "disabled", code: "not_configured" };
+ const result = await this.call("GET", "archives/key", undefined, signal);
+ if (result.kind === "ok") {
+ const parsed = keySchema.safeParse(result.body);
+ if (!parsed.success) return { status: "unavailable", reason: "invalid key response" };
+ const publicKey = Buffer.from(parsed.data.public_key, "base64");
+ if (publicKey.length !== 32 || publicKey.toString("base64") !== parsed.data.public_key || sealKid(publicKey) !== parsed.data.kid || parsed.data.alg !== SEAL_ALG) {
+ return { status: "unavailable", reason: "invalid key response" };
+ }
+ return { status: "ok", key: { kid: parsed.data.kid, publicKey, alg: parsed.data.alg } };
+ }
+ if (result.kind === "error" && result.status === 404) return { status: "disabled", code: "archive_routes_missing" };
+ const outcome = this.common(result);
+ if (outcome?.status === "disabled") return { status: "disabled", code: outcome.code };
+ if (result.kind === "error") return { status: "unavailable", reason: `status ${result.status}` };
+ return { status: "unavailable", reason: result.kind === "unavailable" ? result.reason : result.kind };
+ }
+
+ /** Best-effort POST /archives/{id}/abort (7.7); one attempt, result ignored. */
+ async abort(archiveId: string, signal?: AbortSignal): Promise<void> {
+ try {
+ const response = await this.send("POST", `archives/${archiveId}/abort`, {}, signal);
+ await response.body?.cancel().catch(() => undefined);
+ } catch {
+ // The server's stale-upload maintenance aborts it within a day.
+ }
+ }
+
+ private async create(job: ArchiveUploadJob, signal?: AbortSignal): Promise<UploadOutcome | { uploaded: true } | { upload: ArchiveUploadState; urls: Map<number, string> }> {
+ const result = await this.call("POST", "archives", job.request, signal);
+ if (result.kind === "ok") {
+ const parsed = createSchema.safeParse(result.body);
+ if (!parsed.success || parsed.data.archive_id !== job.request.archive_id) return { status: "retry_later", reason: "invalid create response" };
+ if (parsed.data.status === "uploaded") return { uploaded: true };
+ const { upload_id: uploadId, object_key: objectKey, part_size: partSize, part_count: partCount } = parsed.data;
+ if (!uploadId || !objectKey || !partSize || !partCount || partCount !== Math.ceil(job.request.size / partSize)) {
+ return { status: "retry_later", reason: "invalid create response" };
+ }
+ const urls = new Map((parsed.data.parts ?? []).map((part) => [part.part_number, part.url]));
+ return { upload: { upload_id: uploadId, object_key: objectKey, part_size: partSize, part_count: partCount, etags: {} }, urls };
+ }
+ const outcome = this.common(result);
+ if (outcome) return outcome;
+ if (result.kind !== "error") return { status: "retry_later", reason: "create failed" };
+ if (result.status === 409 && result.code === "archive_kid_unknown") return { status: "rekey", code: result.code };
+ if (result.status === 409 && result.code && CHAIN_ENDING_CODES.has(result.code)) return { status: "stop_session", code: result.code };
+ return { status: "retry_later", reason: `create status ${result.status}` };
+ }
+
+ private async listParts(job: ArchiveUploadJob, partNumbers: number[], signal?: AbortSignal): Promise<UploadOutcome | "recreate" | PartsResult> {
+ const result = await this.call("POST", `archives/${job.request.archive_id}/parts`, { part_numbers: partNumbers }, signal);
+ if (result.kind === "ok") {
+ const parsed = partsSchema.safeParse(result.body);
+ if (!parsed.success) return { status: "retry_later", reason: "invalid parts response" };
+ return { urls: new Map(parsed.data.parts.map((part) => [part.part_number, part.url])), uploaded: parsed.data.uploaded ?? [] };
+ }
+ const outcome = this.common(result);
+ if (outcome) return outcome;
+ if (result.kind === "error" && (result.status === 404 || (result.status === 409 && result.code === "archive_not_uploading"))) return "recreate";
+ return { status: "retry_later", reason: result.kind === "error" ? `parts status ${result.status}` : "parts failed" };
+ }
+
+ private async complete(job: ArchiveUploadJob, upload: ArchiveUploadState, signal?: AbortSignal): Promise<UploadOutcome | "recreate" | "relist" | { reupload: string }> {
+ const parts = Array.from({ length: upload.part_count }, (_, index) => ({ part_number: index + 1, etag: upload.etags[String(index + 1)] ?? "" }));
+ const result = await this.call("POST", `archives/${job.request.archive_id}/complete`, { parts }, signal);
+ if (result.kind === "ok") return { status: "uploaded" };
+ const outcome = this.common(result);
+ if (outcome) return outcome;
+ if (result.kind === "error") {
+ if (result.status === 404 || (result.status === 409 && result.code === "archive_not_uploading")) return "recreate";
+ if (result.status === 409 && result.code === "archive_parts_invalid") return "relist";
+ if (result.status === 409 && (result.code === "archive_size_mismatch" || result.code === "archive_seal_invalid")) return { reupload: result.code };
+ return { status: "retry_later", reason: `complete status ${result.status}` };
+ }
+ return { status: "retry_later", reason: "complete failed" };
+ }
+
+ /** PUT one part to its presigned URL; an abort of `signal` cancels the request at once. */
+ private async putPart(url: string, body: Uint8Array<ArrayBuffer>, signal?: AbortSignal): Promise<{ etag: string } | "forbidden" | "gone" | { failed: string }> {
+ let attempt = 0;
+ for (;;) {
+ if (signal?.aborted) return { failed: "aborted" };
+ let failure: string;
+ try {
+ const timeout = Math.max(PART_MIN_TIMEOUT_MS, Math.ceil(body.byteLength / PART_MIN_BYTES_PER_MS));
+ const response = await this.options.fetch(url, { method: "PUT", body, signal: timeoutSignal(timeout, signal) });
+ await response.body?.cancel().catch(() => undefined);
+ if (response.ok) {
+ const etag = response.headers.get("etag");
+ if (etag) return { etag };
+ failure = "missing etag";
+ } else if (response.status === 403) {
+ return "forbidden";
+ } else if (response.status === 404) {
+ return "gone";
+ } else if (!PART_RETRYABLE_STATUSES.has(response.status)) {
+ return { failed: `part status ${response.status}` };
+ } else {
+ failure = `part status ${response.status}`;
+ }
+ } catch (error) {
+ if (signal?.aborted) return { failed: "aborted" };
+ failure = error instanceof Error ? error.name : "network error";
+ }
+ attempt += 1;
+ if (attempt >= this.retry.attempts) return { failed: failure };
+ await this.retry.sleep(backoffMs(this.retry, attempt), signal);
+ }
+ }
+
+ /** PUTs every part S3 does not hold yet; "recreate" when the multipart upload is gone. */
+ private async putMissingParts(
+ job: ArchiveUploadJob,
+ upload: ArchiveUploadState,
+ file: FileHandle,
+ initialUrls: Map<number, string>,
+ persist: () => Promise<void>,
+ signal?: AbortSignal,
+ ): Promise<UploadOutcome | "recreate" | "done"> {
+ const urls = new Map(initialUrls);
+ const size = job.request.size;
+ const partBytes = (part: number) => Math.min(upload.part_size, size - (part - 1) * upload.part_size);
+ const missing = () => {
+ const parts: number[] = [];
+ for (let part = 1; part <= upload.part_count; part += 1) if (!upload.etags[String(part)]) parts.push(part);
+ return parts;
+ };
+ let forbiddenInRow = 0;
+ for (;;) {
+ if (signal?.aborted) return { status: "aborted" };
+ const todo = missing();
+ const part = todo[0];
+ if (part === undefined) return "done";
+ const url = urls.get(part);
+ if (!url) {
+ const listed = await this.listParts(job, todo.slice(0, MAX_PARTS_PER_REQUEST), signal);
+ if (listed === "recreate" || "status" in listed) return listed;
+ let learned = false;
+ for (const held of listed.uploaded) {
+ if (held.part_number <= upload.part_count && held.size === partBytes(held.part_number) && upload.etags[String(held.part_number)] !== held.etag) {
+ upload.etags[String(held.part_number)] = held.etag;
+ learned = true;
+ }
+ }
+ if (learned) await persist();
+ for (const [number, partUrl] of listed.urls) urls.set(number, partUrl);
+ if (!urls.has(part) && !upload.etags[String(part)]) return { status: "retry_later", reason: "no part url" };
+ continue;
+ }
+ let body: Uint8Array<ArrayBuffer> | null;
+ try {
+ body = await readPart(file, (part - 1) * upload.part_size, partBytes(part), signal);
+ } catch (error) {
+ // The next drain checks the file again (a truncated one stops the session).
+ return { status: "retry_later", reason: `archive file read failed: ${error instanceof Error ? error.message : "unknown"}` };
+ }
+ if (!body) return { status: "aborted" };
+ const result = await this.putPart(url, body, signal);
+ if (result === "forbidden") {
+ // An expired URL, or expired signing credentials: fetch fresh URLs and retry.
+ forbiddenInRow += 1;
+ if (forbiddenInRow > 2) return { status: "retry_later", reason: "part forbidden" };
+ urls.clear();
+ continue;
+ }
+ if (result === "gone") {
+ // NoSuchUpload: /parts answers archive_not_uploading, then the upload is re-created.
+ urls.clear();
+ const listed = await this.listParts(job, [part], signal);
+ if (listed === "recreate" || "status" in listed) return listed;
+ for (const [number, partUrl] of listed.urls) urls.set(number, partUrl);
+ forbiddenInRow += 1;
+ if (forbiddenInRow > 2) return { status: "retry_later", reason: "part not found" };
+ continue;
+ }
+ if ("failed" in result) {
+ if (signal?.aborted) return { status: "aborted" };
+ this.log("warn", "OmniRush archive part upload failed", { archiveId: job.request.archive_id, part, reason: result.failed });
+ return { status: "retry_later", reason: result.failed };
+ }
+ forbiddenInRow = 0;
+ upload.etags[String(part)] = result.etag;
+ urls.delete(part);
+ await persist();
+ }
+ }
+
+ /**
+ * Uploads one sealed archive: create (or resume), PUT the parts S3 lacks,
+ * complete. Never throws; the job's upload state is persisted after every
+ * part so a restart resumes where it stopped.
+ */
+ async upload(job: ArchiveUploadJob, persist: () => Promise<void>, signal?: AbortSignal): Promise<UploadOutcome> {
+ if (signal?.aborted) return { status: "aborted" };
+ let file: FileHandle;
+ try {
+ file = await open(job.sealedPath, "r");
+ } catch {
+ return { status: "stop_session", code: "archive_file_missing" };
+ }
+ try {
+ if ((await file.stat()).size !== job.request.size) return { status: "stop_session", code: "archive_file_corrupt" };
+ return await this.uploadFrom(file, job, persist, signal);
+ } finally {
+ await file.close().catch(() => undefined);
+ }
+ }
+
+ private async uploadFrom(file: FileHandle, job: ArchiveUploadJob, persist: () => Promise<void>, signal?: AbortSignal): Promise<UploadOutcome> {
+ for (let round = 0; round < MAX_UPLOAD_ROUNDS; round += 1) {
+ if (signal?.aborted) return { status: "aborted" };
+ let urls = new Map<number, string>();
+ if (!job.upload) {
+ const created = await this.create(job, signal);
+ if ("status" in created) return created;
+ if ("uploaded" in created) return { status: "uploaded" };
+ job.upload = created.upload;
+ urls = created.urls;
+ await persist();
+ }
+ const upload = job.upload;
+ const put = await this.putMissingParts(job, upload, file, urls, persist, signal);
+ if (put === "recreate") {
+ job.upload = null;
+ await persist();
+ continue;
+ }
+ if (put !== "done") return put;
+ const completed = await this.complete(job, upload, signal);
+ if (completed === "recreate") {
+ job.upload = null;
+ await persist();
+ continue;
+ }
+ if (completed === "relist") {
+ // Trust S3's own part list: /parts reports what it holds and the rest is sent again.
+ upload.etags = {};
+ await persist();
+ continue;
+ }
+ if ("reupload" in completed) {
+ if (job.recreates >= 1) return { status: "stop_session", code: completed.reupload };
+ job.recreates += 1;
+ job.upload = null;
+ await persist();
+ continue;
+ }
+ return completed;
+ }
+ return { status: "retry_later", reason: "upload rounds exhausted" };
+ }
+}
diff --git a/apps/server/src/workspace-collector.server.e2e.test.ts b/apps/server/src/workspace-collector.server.e2e.test.ts
index 7a9332e8..2f90779d 100644
--- a/apps/server/src/workspace-collector.server.e2e.test.ts
+++ b/apps/server/src/workspace-collector.server.e2e.test.ts
@@ -1,13 +1,15 @@
import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
import { execFile } from "node:child_process";
import { createHash } from "node:crypto";
-import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { promisify } from "node:util";
import { zstdDecompressSync } from "node:zlib";
import { proxyOpencodeRequest, proxyOpencodeV2Request, startServer } from "./server.js";
+import { FakeArchiveServer } from "./session-archive/fake-archive-server.js";
+import { manifestOf, openArchive } from "./session-archive/test-helpers.js";
import type { ServerConfig } from "./types.js";
/**
@@ -269,14 +271,27 @@ async function settledRun(base: string, runId: string): Promise<{ status: string
throw new Error("the workflow run did not settle");
}
-/** The omnirush.ai collector endpoint, recording every decompressed envelope. */
-function startMockGateway() {
+/**
+ * The omnirush.ai collector endpoint, recording every decompressed envelope.
+ * With `archive`, it also serves the project archive routes from that fake,
+ * with the presigned S3 part URLs pointing back here.
+ */
+function startMockGateway(archive?: FakeArchiveServer) {
const uploads: Upload[] = [];
const server = Bun.serve({
hostname: "127.0.0.1",
port: 0,
async fetch(request) {
const url = new URL(request.url);
+ if (archive && url.pathname.startsWith("/omnirush/archives")) {
+ const body = request.method === "GET" ? undefined : await request.text();
+ const response = await archive.respond(`https://api.omnirush.test${url.pathname}`, { method: request.method, headers: request.headers, ...(body ? { body } : {}) });
+ const text = (await response.text()).replaceAll("https://bucket.s3.test/", `http://127.0.0.1:${server.port}/s3/`);
+ return new Response(text, { status: response.status, headers: { "content-type": "application/json" } });
+ }
+ if (archive && url.pathname.startsWith("/s3/")) {
+ return archive.respond(`https://bucket.s3.test/${url.pathname.slice("/s3/".length)}${url.search}`, { method: request.method, body: await request.arrayBuffer() });
+ }
if (url.pathname === "/omnirush/collect" && request.method === "POST") {
if (request.headers.get("authorization") !== "Bearer access-token") return Response.json({ detail: "unauthorized" }, { status: 401 });
const compressed = Buffer.from(await request.arrayBuffer());
@@ -817,3 +832,73 @@ describe("collection gaps: the v2 mount and local workflow steps", () => {
expect(gateway.uploads.at(-1)?.envelope.session).toEqual({ provider_id: "anthropic", model_id: "claude-sonnet-4-5", variant: "high", child_session_ids: [] });
}, 60_000);
});
+
+describe("project archive wiring", () => {
+ /** A server whose gateway also serves the archive routes; `ses_root` has a two-level subagent tree. */
+ async function archivedServer(setup: (archive: FakeArchiveServer) => void = () => undefined) {
+ const { root, stateDir } = await createWorkspace();
+ const engine = startMockEngine({ provider: "openai", model: "gpt-5" });
+ const archive = new FakeArchiveServer();
+ archive.token = "access-token";
+ setup(archive);
+ const gateway = startMockGateway(archive);
+ const omnirush = await startOmniRush(serverConfig({ root, stateDir, engineBaseUrl: engine.baseUrl, gatewayUrl: gateway.gatewayUrl }));
+ return { root, stateDir, archive, gateway, omnirush };
+ }
+
+ test("a git workspace's root session is archived through the device session: one base, then a delta for a turn that changed the folder", async () => {
+ const { root, archive, gateway, omnirush } = await archivedServer();
+ expect((await prompt(omnirush.base)).status).toBe(204);
+ await waitFor(() => (traces(gateway.uploads).length >= 1 ? true : undefined));
+ const [base] = await waitFor(() => (archive.objects().length >= 1 ? archive.objects() : undefined));
+
+ await writeFile(join(root, "feature.txt"), "new work\n");
+ expect((await prompt(omnirush.base)).status).toBe(204);
+ await waitFor(() => (traces(gateway.uploads).length >= 2 ? true : undefined));
+ const objects = await waitFor(() => (archive.objects().some((object) => object.request.turn === 2) ? archive.objects() : undefined));
+ await omnirush.stop();
+
+ expect(base!.request).toMatchObject({ session_id: "ses_root", kind: "base", sequence: 0, marker: ".git" });
+ expect((await openArchive(base!.object!)).map((member) => member.name)).toEqual(expect.arrayContaining(["app.txt", ".git/HEAD"]));
+ // One base however many prompts; the turn numbers are the engine's completed-turn count, strictly increasing.
+ expect(objects.filter((object) => object.request.kind === "base")).toHaveLength(1);
+ const turns = objects.map((object) => object.request.turn);
+ expect(turns.every((turn, index) => index === 0 || turn > turns[index - 1]!)).toBe(true);
+ const delta = objects.at(-1)!;
+ expect(delta.request).toMatchObject({ kind: "delta", turn: 2 });
+ const members = await openArchive(delta.object!);
+ expect(members.map((member) => member.name)).toContain("feature.txt");
+ expect(manifestOf(members)).toMatchObject({ session_id: "ses_root", turn: 2 });
+ // The subagent sessions are never archived, and the key was fetched once.
+ expect(new Set(objects.map((object) => object.request.session_id))).toEqual(new Set(["ses_root"]));
+ expect(archive.calls.filter((call) => call.path === "archives/key")).toHaveLength(1);
+ }, 60_000);
+
+ test("without archive consent (428) nothing is packed or uploaded, consent is checked once, and the chat carries on", async () => {
+ const { stateDir, archive, gateway, omnirush } = await archivedServer((fake) => {
+ fake.gate = { status: 428, detail: "archive_consent_required" };
+ });
+ expect((await prompt(omnirush.base)).status).toBe(204);
+ await waitFor(() => (traces(gateway.uploads).length >= 1 ? true : undefined));
+ expect((await prompt(omnirush.base)).status).toBe(204);
+ await waitFor(() => (traces(gateway.uploads).length >= 2 ? true : undefined));
+ await omnirush.stop();
+ expect(archive.callPaths()).toEqual(["GET archives/key 428"]);
+ expect(await readdir(join(stateDir, "omnirush-archive", "pending"))).toEqual([]);
+ }, 60_000);
+
+ test("OMNIRUSH_ARCHIVE_ENABLED=0 turns the archive off on this device: no archive request at all", async () => {
+ const previous = process.env.OMNIRUSH_ARCHIVE_ENABLED;
+ process.env.OMNIRUSH_ARCHIVE_ENABLED = "0";
+ cleanups.push(() => {
+ if (previous === undefined) delete process.env.OMNIRUSH_ARCHIVE_ENABLED;
+ else process.env.OMNIRUSH_ARCHIVE_ENABLED = previous;
+ });
+ const { stateDir, archive, gateway, omnirush } = await archivedServer();
+ expect((await prompt(omnirush.base)).status).toBe(204);
+ await waitFor(() => (traces(gateway.uploads).length >= 1 ? true : undefined));
+ await omnirush.stop();
+ expect(archive.calls).toEqual([]);
+ expect(await readdir(stateDir)).not.toContain("omnirush-archive");
+ }, 60_000);
+});
diff --git a/docs/project-archive.md b/docs/project-archive.md
new file mode 100644
index 00000000..7986d513
--- /dev/null
+++ b/docs/project-archive.md
@@ -0,0 +1,116 @@
+# Project archive
+
+When a chat runs in a folder that is a git project, OmniRush.ai can keep an
+encrypted copy of the whole project folder on omnirush.ai. With that copy,
+the project can be restored as it was after any turn of the chat. This page
+describes what the desktop app uploads, when it uploads it, and how to turn
+it off.
+
+The project archive is separate from the workspace collector described in
+[workspace-collector-privacy.md](workspace-collector-privacy.md). The
+collector keeps running for every chat and sends scrubbed, size-capped
+snapshots. The archive is a raw copy of the folder: file contents are not
+scrubbed and there is no size cap.
+
+## When it runs
+
+All of these must be true:
+
+- You are signed in to omnirush.ai in the app.
+- You have turned on the **project archive** opt-in in your omnirush.ai
+ consent settings. It is a separate choice, off by default. Agreeing to the
+ general data collection does not turn it on.
+- The folder the chat started in contains `.git` (a git repository, a
+ worktree or a submodule). Nothing is archived for other folders.
+- The folder is not your home folder, the root of a disk, or one of the
+ app's own data folders. If the chat's folder is a symbolic link, the
+ folder it points to is the one checked and archived.
+
+Sub-agent chats (tasks the agent starts on its own) are not archived. They
+work in the same folder as the chat that started them, which is already
+archived.
+
+## What gets uploaded
+
+- **When the chat starts:** the whole folder as it is on disk. That
+ includes the `.git` folder with the full history and files that git
+ ignores, such as `node_modules/`, build output, media and other binaries.
+ A chat that already has this full copy, for example one you continue
+ after restarting the app, does not get a second one.
+- **After each turn that changed something:** only the files that were
+ added or changed, plus the list of deleted paths. A turn that changed
+ nothing uploads nothing.
+
+Each upload records the chat and its turn number, so the folder can be
+rebuilt as it was after any turn.
+
+## What is left out
+
+- **Credential files.** The archive applies the same filename rules as the
+ workspace collector:
+ - environment files (`.env`, `.env.local`, ...);
+ - SSH, cloud and GPG folders (`.ssh/`, `.aws/`, `.gnupg/`);
+ - private keys and certificates (`id_rsa`, `id_ed25519`, `*.pem`, `*.key`);
+ - `credentials*` and `secrets*` files, and anything under a `keys/` or
+ `secrets/` folder;
+ - package manager and tool logins (`.npmrc`, `.pypirc`, `.netrc`,
+ `kubeconfig`, `.docker/config.json`);
+ - wallet files;
+ - other files named after a key, secret, token or password.
+
+ A folder such as `.ssh/` still appears in the copy, but empty. Two
+ exceptions: files inside `.git` are always kept, so the history stays
+ intact, and source code and documentation files are usually kept even
+ when their name contains one of these words (for example `src/token.ts`
+ or `docs/api-token-guide.md`). Their contents are uploaded unchanged.
+- Sockets, pipes and device files.
+- The app's own data folders, if they are inside the project folder.
+- Files and folders that cannot be read.
+
+Symbolic links are stored as links. The app never follows a link to read
+something outside the project folder.
+
+## Encryption
+
+Each archive is compressed and then encrypted on your computer before
+anything leaves it. It is encrypted with omnirush.ai's public archive key
+(X25519 key agreement with AES-256-GCM). The network and the storage
+service only see encrypted data, plus a few details they need to store it:
+sizes, the chat id and turn numbers. omnirush.ai holds the matching private
+key and can decrypt the archives. The encryption protects your project
+while it is sent and stored. It does not hide the project from
+omnirush.ai.
+
+## Uploading
+
+The app never makes a chat wait for the archive. Archives are packed and
+uploaded in the background, one at a time. Until an archive is uploaded,
+it waits in the app's state folder (`omnirush-archive/`). An upload that is
+interrupted resumes from where it stopped the next time the app runs. An
+archive that still has not been uploaded after 7 days is deleted, and
+archiving stops for that chat. The next chat starts over with a new full
+copy. Archive problems are written to the app's log. They never show up
+as chat errors.
+
+## Turning it off
+
+- **Withdraw the project archive opt-in on omnirush.ai.** omnirush.ai then
+ deletes the archives it holds for you. The app stops archiving the next
+ time it contacts omnirush.ai (at the next upload, or when a new chat
+ starts), and archives waiting on your computer are deleted, not
+ uploaded. While the opt-in is off, the app asks again when a new chat
+ starts, at most once every 10 minutes. If you turn the opt-in back on,
+ chats started after that are archived without restarting the app.
+- **Sign out.** Uploads in progress are cancelled, and every archive
+ waiting on this computer is deleted, along with the app's records of
+ what it already archived. Nothing is uploaded later, even if you sign in
+ again or sign in with another account.
+- **Turn it off on this computer.** Start the app with
+ `OMNIRUSH_ARCHIVE_ENABLED=0` in its environment, for example by launching
+ it from a terminal where the variable is set. Nothing is archived, and
+ archives already waiting on this computer are deleted without being
+ uploaded.
+
+For the technical specification, see `docs/omnirush-project-archive.md` in
+the omnirush.ai backend repository. The desktop implementation is in
+`apps/server/src/session-archive/`.
diff --git a/docs/workspace-collector-privacy.md b/docs/workspace-collector-privacy.md
index bcfdee48..ba4ed276 100644
--- a/docs/workspace-collector-privacy.md
+++ b/docs/workspace-collector-privacy.md
@@ -1,5 +1,7 @@
# Workspace collector privacy rails
+The project archive, a separate opt-in that uploads an encrypted, unscrubbed copy of git project folders, is described in [project-archive.md](project-archive.md).
+
The desktop server's workspace collector (`apps/server/src/workspace-collector.ts`) snapshots consented workspace files, git metadata and session traces for omnirush.ai; the backend applies the same denylist and scrubber server-side, so a rule changed on one side must land on the other, and the desktop side may only ever be the stricter of the two. Before anything leaves the machine, credential-named paths are dropped and counted in the envelope's `privacy.denied_file_count`: any path component whose words (split on space, `_`, `-`, `.`) include key(s), secret(s), token(s), password(s), passwd, credential(s), id_rsa, id_ed25519, netrc, npmrc, pypirc, kubeconfig, wallet, seed or mnemonic, plus `.aws`, `.ssh`, `.gnupg` and `.docker/config.json`, on top of the older `.env*`, `credentials*`, `secrets*`, `keys/`, `*.pem`/`*.key` rules. A file with a source-code or docs extension (`.ts`, `.py`, `.md`, `.json`, `.yml`, ...) is kept instead and scrubbed: a secret-named assignment (`password:`, `api_key =`, `"token":`, `export CLIENT_SECRET=`, in INI/YAML/JSON/dotenv/shell/source spelling; the key is split into segments on `_`, `-`, `.`, `:`, camelCase and letter/digit boundaries, and qualifies only when a whole segment or adjacent pair is a listed family word, so `author`, `keywords` and `tokenizer_class` never do) loses its value under value rule v2: in SOURCE mode (files with a programming-language extension: js, cjs, mjs, ts, tsx, jsx, py, go, rs, java, kt, c, cc, cpp, h, hpp, rb, php, swift, cs, scala, sh, bash, zsh, ps1, lua, dart, vue, svelte, map, patch, diff) a value is redacted only when it is 8+ non-space characters, not a code expression, `<placeholder>` or filesystem path, not an unquoted identifier or member expression (`config.token`, `tokenFile`), and carries a digit or is 20+ mixed-case characters, while CONFIG mode (every other extension, none, the envelope's git diff and the trace) keeps the permissive rule of 8+ characters with a letter, skipping only filesystem paths and unquoted dotted identifiers, and a key whose last segment is a structural word (`length`, `ttl`, `url`, `path`, `name`, `id`, `header`, `file`, `filename`, `dir`, `mode`, `method`, `role`, `owner`, `type`, `kind`, `enabled`, `estimate`, `hash`, `digest`, `at`, `config`, `client`, `prefix`, `suffix`, `format`, `scheme`, `provider`, `status`, `state`, `label`, `description`, `title`, `class`, `field`, `fields`, `list`, `names`, `version`, `timeout`, `limit`, `max`, `min`, `interval`, `retries`, `port`) never names a secret. A `Bearer` value is redacted only when its token carries a digit or is 20+ mixed-case characters that are not a bare identifier, the AWS 40-character proximity pass runs only on documents of three or more lines (a single-line JSON document relies on its key, or on a sibling naming AWS), and provider token shapes (AWS access key ids and, near them, secret access keys; GitHub, Slack, Google, Stripe, OpenAI, Anthropic, JWTs, Discord, `Bearer` values, private key blocks, URL userinfo) become `[REDACTED]`, and personal identifiers become `[REDACTED_PII]`. `.json` files and the trace document are scrubbed as JSON (every string, keys included) so a redaction can never break an escape sequence; git diffs stay text. As on the backend, a `.json` file first gets the AWS proximity pass over its raw text, an object or array whose keys or string values name aws/secret makes all its values AWS context (the container rail, which also covers the trace), every pair of a repeated key is kept and scrubbed (JSON.parse alone would drop the earlier value unscrubbed), and a document nested deeper than 512 levels gets the text scrub instead. The same denylist filters the manifest, touched paths, git status and diff sections.
The backend's second-sample refinements (46ee95e) are mirrored exactly: in SOURCE mode an unquoted value must also be token-shaped (only letters, digits and `_ . / + = ~ -`, so `stagedClient?.plaintext`, `params[8]` and `[0-9a-f]{16}` stay) and the key must start the text or follow whitespace, `{`, `,`, `(`, a quote or backtick, `+` or `#` (so `?token=` or `pipeline-token:...` inside a string literal stays), while CONFIG keeps its word-start guard. 53 more structural last segments never name a secret (`in`, `out`, `expires`, `ms`, `bytes`, `encryption`, `algorithm`, `policy`, `source`, `handler`, `event`, `message`, `error`, `envelope`, `ref`, `alias`, ...; `auth_code` and `password_plaintext` still do), a JSON key that looks like a path or filename (holds `/` or `\`, or ends in a 1-5 character extension) is not a secret key in the JSON rail though its value still gets the provider-token scrub, and URL userinfo is redacted only when it holds a password (`scheme://user:pass@host` becomes `scheme://[REDACTED]@host`; a bare `user@host` stays). The assignment rule reads whitespace exactly as the backend's Python `\s` does, and in SOURCE mode a desktop key may also start right after any non-ASCII character (a byte order mark, or the `é` of `café_token`, which the backend's Unicode `\w` spans instead), so the desktop never redacts less than the backend there. URL userinfo with an empty user (`redis://:<password>@host`, Redis's AUTH form) is redacted too; the backend at 46ee95e misses it, so there the desktop is the stricter side.