A desktop coding agent with free access to frontier models.
TypeScript
feat(archive): final archive of the folder after the last completed turn
ogsamrat412a5cb8cd3c
diff --git a/apps/server/src/capture-client.test.ts b/apps/server/src/capture-client.test.tsindex e151918d..e0bed8cb 100644--- a/apps/server/src/capture-client.test.ts+++ b/apps/server/src/capture-client.test.ts@@ -1,6 +1,6 @@import { afterEach, describe, expect, test } from "bun:test";import { execFile } from "node:child_process";-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";@@ -227,6 +227,51 @@ describe("capture worker", () => {expect(sink.envelopes().map((item) => item.snapshot_type)).toContain("end");}, 60_000);+ test("stopping packs the project archive's final archives on the worker, unless the account is gone", async () => {+ const results: string[][] = [];+ for (const archiveFinals of [undefined, Promise.resolve(false)]) {+ const root = await tempDir("project");+ await writeFile(join(root, "README.md"), "# project\n");+ await git(root, "init", "-q");+ await git(root, "add", "README.md");+ await git(root, "commit", "-q", "-m", "initial");+ const archive = new FakeArchiveServer();+ const engine = Bun.serve({+ hostname: "127.0.0.1",+ port: 0,+ fetch: (request) => (new URL(request.url).pathname.endsWith("/message") ? Response.json([]) : Response.json({ id: "ses_final_stop_01" })),+ });+ cleanups.push(() => engine.stop(true));+ const stateDir = await tempDir("state");+ const capture = service({+ stateDir,+ collector: { upload: uploadSink().upload },+ archive: {+ enabled: true,+ excludedDirs: [],+ request: (path, init) => archive.respond(`https://api.omnirush.test/omnirush/${path}`, {+ method: init.method,+ headers: { authorization: `Bearer ${archive.token}` },+ ...(init.body === undefined ? {} : { body: init.body }),+ }),+ refreshAccessToken: async () => null,+ fetch: archive.respond,+ baseIdleMs: 0,+ },+ });+ capture.startSession("ses_final_stop_01", "workspace-final", root);+ capture.archiveSessionStarted("ses_final_stop_01", root, { baseUrl: `http://127.0.0.1:${engine.port}`, headers: [], search: "", engine: "v1" });+ await capture.idle();+ expect(archive.objects().map((object) => object.request.kind)).toEqual(["base"]);+ // Edited after the chat's last turn, then the app quits (or the user signs out).+ await writeFile(join(root, "notes.md"), "after the last turn\n");+ await capture.stop(archiveFinals === undefined ? {} : { archiveFinals });+ results.push(await readdir(join(stateDir, "omnirush-archive", "queue")));+ }+ expect(results[0]).toHaveLength(1);+ expect(results[1]).toEqual([]);+ }, 60_000);+test("OMNIRUSH_CAPTURE_WORKER=0 captures in-process with the same envelopes", async () => {const root = await syntheticWorkspace(20);const results: Array<Array<[string, string, number]>> = [];diff --git a/apps/server/src/capture-client.ts b/apps/server/src/capture-client.tsindex 2243ada2..9ac7809b 100644--- a/apps/server/src/capture-client.ts+++ b/apps/server/src/capture-client.ts@@ -32,6 +32,8 @@ import { isCollectableWebUrl, workspaceCollectorEnabled, type CollectorWebVisitconst MAX_TRACED_REQUEST_BYTES = 4 * 1024 * 1024;/** Shutdown waits this long for the last traces and end snapshots before the worker is terminated. */const STOP_TIMEOUT_MS = 20_000;+/** Shutdown waits this long to learn whether the account is still there (for the final project archives), else packs none. */+const ACCOUNT_CHECK_TIMEOUT_MS = 1_000;/** A worker that exits unexpectedly is replaced at most this many times per server. */const MAX_WORKER_RESTARTS = 3;const SESSION_ID_PATTERN = /^[A-Za-z0-9._:-]{8,128}$/;@@ -59,7 +61,12 @@ export type CaptureService = {observeSession(sessionId: string, target: EngineTarget): void;sessionDeleted(sessionId: string): void;signOut(): Promise<void>;- stop(): Promise<void>;+ /**+ * Stops capture. `archiveFinals` (default true) says whether the account is+ * still connected, so that the project archive packs its final archives;+ * a user sign-out clears the account before it restarts the server.+ */+ stop(options?: { archiveFinals?: boolean | Promise<boolean> }): Promise<void>;/** Every queued capture, upload and archive step settled (tests, profiling). */idle(): Promise<void>;diagnostics(): Promise<CaptureDiagnostics | null>;@@ -167,15 +174,16 @@ class CaptureClient implements CaptureService {return isDiagnostics(value) ? value : null;}- stop(): Promise<void> {- this.stopping ??= this.shutdown();+ stop(options: { archiveFinals?: boolean | Promise<boolean> } = {}): Promise<void> {+ this.stopping ??= this.shutdown(options.archiveFinals ?? true);return this.stopping;}- private async shutdown(): Promise<void> {+ private async shutdown(archiveFinals: boolean | Promise<boolean>): Promise<void> {// First, and synchronously: archive uploads this thread makes for the worker are aborted now.for (const { controller, channel } of this.served.values()) if (channel === "archive") controller.abort();- const done = this.dispatch({ kind: "call", id: null, method: "stop", args: [] }, [], true);+ const finals = await withinTimeout(archiveFinals, ACCOUNT_CHECK_TIMEOUT_MS);+ const done = this.dispatch({ kind: "call", id: null, method: "stop", args: [{ archiveFinals: finals }] }, [], true);let timer: ReturnType<typeof setTimeout> | undefined;const timedOut = new Promise<void>((resolvePromise) => {timer = setTimeout(() => {@@ -431,6 +439,21 @@ class CaptureClient implements CaptureService {}}+/** The answer if it comes within `ms`, else false (as for a failed check). */+async function withinTimeout(answer: boolean | Promise<boolean>, ms: number): Promise<boolean> {+ if (typeof answer === "boolean") return answer;+ let timer: ReturnType<typeof setTimeout> | undefined;+ const late = new Promise<boolean>((resolvePromise) => {+ timer = setTimeout(() => resolvePromise(false), ms);+ timer.unref?.();+ });+ try {+ return await Promise.race([answer.catch(() => false), late]);+ } finally {+ clearTimeout(timer);+ }+}+function isDiagnostics(value: unknown): value is CaptureDiagnostics {return typeof value === "object" && value !== null && "metrics" in value && "cache" in value;}diff --git a/apps/server/src/capture-host.ts b/apps/server/src/capture-host.tsindex 584696e9..e483f677 100644--- a/apps/server/src/capture-host.ts+++ b/apps/server/src/capture-host.ts@@ -16,6 +16,7 @@ import {type EngineTarget,type SessionObservers,} from "./collector-observer.js";+import type { CaptureStopOptions } from "./capture-protocol.js";import { SessionArchiver, type SessionArchiverOptions } from "./session-archive/index.js";import { ProjectArchiveLifecycle, type ArchiveLifecycleLog } from "./session-archive/lifecycle.js";import { WorkspaceCollector, type CollectorMetrics, type CollectorWebVisit } from "./workspace-collector.js";@@ -158,9 +159,13 @@ export class CaptureHost {await this.collector.clearSpool().catch(() => undefined);}- /** Server shutdown: in-flight archive uploads abort first, then every session's trace and end snapshot go out. */- async stop(): Promise<void> {- const archiveStopped = this.archive.stop();+ /**+ * Server shutdown: in-flight archive uploads abort first, then every+ * session's trace and end snapshot go out, next to the project archive's+ * final archives (unless `archiveFinals` is false: the account is gone).+ */+ async stop(options: CaptureStopOptions = { archiveFinals: true }): Promise<void> {+ const archiveStopped = this.archive.stop({ finals: options.archiveFinals });this.observers.controller.abort();await this.collector.stop().catch(() => undefined);await archiveStopped;diff --git a/apps/server/src/capture-protocol.ts b/apps/server/src/capture-protocol.tsindex 0db2ec01..b03b7454 100644--- a/apps/server/src/capture-protocol.ts+++ b/apps/server/src/capture-protocol.ts@@ -10,6 +10,9 @@import type { CaptureHost, EngineTarget, PromptRecord } from "./capture-host.js";import type { CollectorWebVisit } from "./workspace-collector.js";+/** How the capture stops: `archiveFinals` false (the account is gone) packs no final project archives. */+export type CaptureStopOptions = { archiveFinals: boolean };+/** CaptureHost methods callable from the main thread, with their arguments. */export type CaptureCalls = {startSession: [sessionId: string, workspaceId: string, root: string];@@ -21,7 +24,7 @@ export type CaptureCalls = {observeSession: [sessionId: string, target: EngineTarget];sessionDeleted: [sessionId: string];signOut: [];- stop: [];+ stop: [options?: CaptureStopOptions];idle: [];diagnostics: [];};@@ -126,7 +129,7 @@ export function invokeCapture(host: CaptureHost, call: CaptureCall): unknown {case "signOut":return host.signOut();case "stop":- return host.stop();+ return host.stop(...call.args);case "idle":return host.idle();case "diagnostics":diff --git a/apps/server/src/collector-observer.ts b/apps/server/src/collector-observer.tsindex 7bbf8095..33f9c9a9 100644--- a/apps/server/src/collector-observer.ts+++ b/apps/server/src/collector-observer.ts@@ -414,11 +414,12 @@ export function projectArchiveEngineReads(target: EngineTarget, sessionId: strin* The snapshot, the trace and the archive delta never depend on reading* the messages: a turn whose transcript cannot be read still gets them. An* observer that stops following (after an hour, or on an error) still takes- * the turn's snapshot, with its turn.diff, and flushes the trace.+ * the turn's snapshot, with its turn.diff, flushes the trace and tells the+ * project archive the turn ended without completing.*/export function observeCollectedSession(input: {collector: WorkspaceCollector;- archive: Pick<ProjectArchiveLifecycle, "turnCompleted">;+ archive: Pick<ProjectArchiveLifecycle, "turnCompleted" | "turnIncomplete">;observers: SessionObservers;sessionId: string;target: EngineTarget;@@ -439,8 +440,10 @@ export function observeCollectedSession(input: {if (observer.controller.signal.aborted) throw error;return false;};- // Whether the turn's snapshot was taken: a failure after it must not take a second.+ // Whether the turn's snapshot was taken, and whether the project archive+ // heard of the turn's end: a failure after either must not repeat it.let turnCaptured = false;+ let turnArchived = false;void (async () => {let observedBusy = false;let consecutiveSettled = 0;@@ -519,6 +522,7 @@ export function observeCollectedSession(input: {// The delta's turn number is the engine's completed-turn count, which// survives app restarts; without the messages the archiver numbers it// right after the last archived turn.+ turnArchived = true;input.archive.turnCompleted(input.sessionId, history ? history.outline : null);return;}@@ -528,6 +532,9 @@ export function observeCollectedSession(input: {turnCaptured = true;input.collector.captureSnapshot(input.sessionId, "turn_completed");input.collector.flushTrace(input.sessionId);+ // And the project archive its delta, or a final archive of the folder.+ turnArchived = true;+ input.archive.turnIncomplete(input.sessionId);})().catch((error: unknown) => {if (!observer.controller.signal.aborted) {input.collector.recordTrace(input.sessionId, "session.observer_failed", {@@ -535,6 +542,7 @@ export function observeCollectedSession(input: {});if (!turnCaptured) input.collector.captureSnapshot(input.sessionId, "turn_completed");input.collector.flushTrace(input.sessionId);+ if (!turnArchived) input.archive.turnIncomplete(input.sessionId);}}).finally(() => {observer.sessions.delete(input.sessionId);diff --git a/apps/server/src/server.ts b/apps/server/src/server.tsindex 8224c503..eaf2295e 100644--- a/apps/server/src/server.ts+++ b/apps/server/src/server.ts@@ -1286,13 +1286,22 @@ export async function startServer(config: ServerConfig): Promise<ServeResult> {log: (level, message, attributes) => logger.log(level, message, attributes),});+ /** Whether the omnirush.ai account is still stored as the server stops (null from `latest()` after a sign-out). */+ const accountStillStored = async (): Promise<boolean> => {+ if (!gatewayCredentials) return false;+ if (!gatewayCredentials.latest) return true;+ return (await gatewayCredentials.latest()) !== null;+ };+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 captureStopped = capture.stop();+ // The project archive packs its final archives only while the account+ // is still stored (an app quit, a restart), never after a sign-out.+ const captureStopped = capture.stop({ archiveFinals: accountStillStored() });let recoveryError: unknown;try { await taskRecovery?.stop(); } catch (error) { recoveryError = error; }await captureStopped;diff --git a/apps/server/src/session-archive/README.md b/apps/server/src/session-archive/README.mdindex 84c24203..33e22f81 100644--- a/apps/server/src/session-archive/README.md+++ b/apps/server/src/session-archive/README.md@@ -5,7 +5,12 @@ 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.+ added and modified entries plus the deleted paths;+- once more after the last completed turn, when the folder changed since the+ last archive: a **final** archive, an ordinary delta that repeats the last+ turn's number (when the session goes quiet, a turn ends without completing,+ the session is deleted, the app quits, and at the next app start). See+ "Final archives" below.Each archive is a pax tar, compressed with zstd and sealed with ORSEAL01 to theomnirush.ai archive key. It is queued durably under the collector state dir and@@ -32,7 +37,7 @@ The user-facing description is `docs/project-archive.md`.| `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`) |+| `lifecycle.ts` | `ProjectArchiveLifecycle`: when the server calls the archiver (session start, turn end, a turn that ends without completing, session end, sign-out, shutdown, app start), the engine-derived turn count, the child-session check, the consent-off window, the quiet window before a final archive and the bounded background queue; `projectArchiveEnabled` (`OMNIRUSH_ARCHIVE_ENABLED`) || `fake-archive-server.ts`, `test-helpers.ts` | Test support only |## API@@ -53,9 +58,11 @@ const archiver = new SessionArchiver({await archiver.start(); // crash recovery; idempotentawait archiver.captureBase(sessionId, root, turn?); // -> CaptureResultawait archiver.captureDelta(sessionId, root, turn); // -> CaptureResult+await archiver.captureFinal(sessionId, reason, {signal}); // -> CaptureResult (a final archive)+await archiver.startFinalCandidates(); // -> session ids to check at app startawait archiver.drain(); // -> DrainResultawait archiver.signOut(); // drop everything-await archiver.stop(); // shutdown+await archiver.stop({finals?, budgetMs?}); // shutdown, final archives firstarchiver.setAccessToken(token); // token rotation (gatewayUrl mode only)await archiver.pendingStatus(); // { jobs, bytes, disabled }```@@ -66,11 +73,13 @@ 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:+This implementation adds five 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.+- `stale_turn`: `turn` is not greater than the last archived turn. A turn delta must move the turn on (the server answers `archive_parent_mismatch` to a lower one). Nothing is consumed; the lifecycle then takes a final archive, so the changes are not held back until the next turn.- `failed`: an invalid session id or turn, or an I/O failure during capture. A failed base is remembered as base-pending too.+- `cancelled` (final archives): the `signal` aborted before the commit (a new prompt, or the end of the shutdown budget). Nothing is consumed.+- `unsupported` (final archives): the server refused one in this app run (see "Final archives"). None is captured until the app restarts.`DrainResult` is `{uploaded, pending, dropped, blocked, disabled}`.`blocked` is the reason the drain stopped with the queue kept (401 after a@@ -105,12 +114,13 @@ in `captureServicesByServer` and calls:| Server hook | Lifecycle call || --- | --- |-| `startServer` (`startCaptureService`) | `start()`: a drain when enabled; otherwise `signOut()` clears what a previous run left (a no-op, touching nothing, when there is no `omnirush-archive/`) |+| `startServer` (`startCaptureService`) | `start()`: a drain and the app-start final archives 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 the collector's `startSession` | `sessionStarted({sessionId, root: workspace.path, engine})`, the engine reads built on the worker from the request's engine target || The collector observer's `turn_completed` (on the worker), with the engine messages it just read (null when it could not read them) | `turnCompleted(sessionId, messages)` |-| `collector.finishSession` (session deleted) | `sessionEnded(sessionId)`: forgets the session, kicks a drain |+| The collector observer stops following a turn without seeing it settle: `session.observer_timeout` (after an hour) or `session.observer_failed` (for example the engine went away) | `turnIncomplete(sessionId)` |+| `collector.finishSession` (session deleted) | `sessionEnded(sessionId)`: a final archive (`session_deleted`), then the session is forgotten; kicks a drain || The broker's `invalidate` hook (revoked or expired account), before `clearSpool()` | `signOut()` |-| Server shutdown and a failed start | `stop()`, started first: the main thread aborts the part uploads it is making for the worker at once, before the task-recovery checkpoint (up to 10 s), then the worker stops the archiver and the collector; the worker is terminated after 20 s at the latest. A user sign-out reaches the server this way too: the desktop clears the account, then restarts the server |+| Server shutdown and a failed start | `stop({finals})`, started first: the main thread aborts the part uploads it is making for the worker at once, before the task-recovery checkpoint (up to 10 s), then the worker packs the final archives (at most `QUIT_FINAL_BUDGET_MS`, 5 s) and stops the archiver and the collector; the worker is terminated after 20 s at the latest. A user sign-out reaches the server this way too: the desktop clears the account, then restarts the server. So `server.ts` asks the account store (`omnirushGatewayCredentials.latest()`, at most 1 s) whether the account is still there, and without it no final archive is packed |What the lifecycle adds on top of the calls below:@@ -120,7 +130,33 @@ What the lifecycle adds on top of the calls below:- **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 v1 list is read a page at a time (`?limit=&before=`, each page under the 8 MiB read cap) and kept only in outline (each message's info and finish parts), so a history of any length is counted; a message over the cap on its own is counted from the info that leads it. The base gets the count read when its step runs; a delta gets the count the observer read when the turn settled. When the observer could not read the messages at all, the delta still runs with no count (`captureDelta(sessionId, root, null)`), numbered right after the last archived turn. 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).+- **Signed out stays out.** After `signOut()` or `stop()`, queued steps do not run and nothing new is scheduled. `SessionArchiver.stop()` also bumps the generation once its final archives are done or their budget is spent, so a capture still packing after that never commits (the server that replaces this one after a sign-out must not find it queued; a sign-out packs no final archive in the first place).+- **Final archives.** See "Final archives" below: the quiet window after a turn (`finalIdleMs`, default `FINAL_IDLE_MS`, 10 minutes), a turn that ends without completing, a deleted session, shutdown (`quitBudgetMs`, default `QUIT_FINAL_BUDGET_MS`, 5 s) and app start. They wait for a concurrency slot behind every other waiting step, so a base or a turn's delta is never held up by them.++### Final archives++The base and the turn deltas show the folder as each turn left it. What+changed after the last completed turn (the user's own edits, a turn that was+aborted or failed, edits while the app was closed) would otherwise only+reach the archive with the next turn, or never. A final archive captures it:++- **Wire.** An ordinary `kind: "delta"` create request: `sequence` is the+ parent's plus one, `parent_archive_id` the previous archive, and `turn`+ **equal** to the parent's (the last completed turn N; the next turn delta+ is still N+1). Several final archives for one turn may follow each other.+ Only the sealed `manifest.json` tells them apart: every delta carries+ `"trigger": "turn"` or `"trigger": "final"`, and a final archive its+ `"reason"`: `idle`, `turn_incomplete`, `session_deleted`, `app_quit` or+ `app_start`. The other manifest fields are unchanged, and a base has+ neither key. The queue record keeps the trigger too.+- **When** (`lifecycle.ts`):+ - `idle`: a turn ended (completed or not) and no prompt followed on that session within `finalIdleMs` (10 minutes). One per quiet window; a new prompt clears the timer and aborts a final archive that is queued or packing (`cancelled`).+ - `turn_incomplete`: the observer stopped following a turn (`turnIncomplete`). The lifecycle reads the engine's messages again: a completed-turn count that moved gets the turn's delta, as if `turnCompleted` had fired; a count that did not, or messages that cannot be read, get a final archive. A `turnCompleted` whose count did not move (a prompt aborted before any answer, a reverted history: `stale_turn`) gets one too.+ - `session_deleted`: `sessionEnded` queues one before the session is forgotten, also for a session this app run has not seen (the archiver answers `no_base` when it never had a base). The session's record is marked `ended`.+ - `app_quit`: `stop()` passes the sessions of this app run (resolved, or unresolved but maybe with a base from an earlier run), the most recent first, to `SessionArchiver.stop({finals, budgetMs})`. The drain and its retry timer stop first; the final archives are captured one after the other (a session whose capture is still running goes last), each with an abort signal that the scan and the tar writer check between entries and blocks. When the budget (5 s) runs out, the signal aborts, and the generation is bumped: nothing commits after that. They are uploaded at the next start.+ - `app_start`: `start()` asks `startFinalCandidates()` for the sessions whose chain moved within the last 7 days, not stopped and not ended: every one with a turn captured since its last final archive (`final_due` in its record: the last shutdown did not get to it, or the app was killed), and the most recent one on each other folder (edits while the app was closed). At most 10, the most recent first.+- **Guards.** `captureFinal` needs a base (`no_base` otherwise, also while the base is pending), a session that is not stopped and archiving on (`disabled`). It runs the gate of section 4 again on the session root recorded at the base: a folder that is gone, or that the gate refuses now, gets nothing (`not_archivable`). A folder that did not change uploads nothing (`unchanged`: a stat-only scan with the root's hash cache). Only the session root is scanned, with the same exclusions, credential filter and pass 2 checks as every other archive. The lifecycle's rules hold as for any capture: consent off, signed out, `OMNIRUSH_ARCHIVE_ENABLED`, child sessions, the bounded queue. The server's per-upload and per-chat limits count final archives like any other (a 413 stops the session).+- **A server without final archives.** A backend from before 1.0.11 answers `409 archive_parent_mismatch` to a delta whose turn equals its parent's. Until the server has accepted a final archive in this app run, the first final archive in a chain keeps the chain point before it (`rewind` in the session record, with that archive's baseline, which `start()` keeps too). On that 409 for a final archive, the drain holds the session and, under its lock, puts the chain back there, drops the final archive and every job chained on it, and captures one turn delta again on top (with the highest turn among the dropped turn deltas), so later turns keep uploading. It logs once, and no final archive is captured again until the app restarts (`unsupported`). Once a final archive is uploaded, the rewind point goes (its baseline is deleted) and a later `archive_parent_mismatch` ends the chain as before.The contract the lifecycle follows is the original wiring note below.@@ -182,18 +218,17 @@ void sessionArchiver.captureBase(sessionId, root, completedTurns).then(() => sesvoid 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`.+- `completedTurns` must strictly increase per session, across app restarts too. A turn delta needs `turn > parent turn` (only a final archive repeats the parent's 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:+The session was deleted: a final archive of what changed since its last+archive, then kick the queue (as implemented, the lifecycle does both):```ts-void sessionArchiver.drain();+void sessionArchiver.captureFinal(sessionId, "session_deleted").then(() => sessionArchiver.drain());```#### 5. Sign-out (the broker's `invalidate` hook, next to `workspaceCollector.clearSpool()`)@@ -220,10 +255,10 @@ token rotation.#### 6. App shutdown (where `workspaceCollector.stop()` is called)```ts-await sessionArchiver.stop();+await sessionArchiver.stop({ finals: sessionIdsOfThisRun, budgetMs: 5_000 });```-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.+This stops the drain and the retry timer and aborts the part PUT in flight at once (the part is sent again on resume), then packs a final archive for each session in `finals` within `budgetMs` (none without them). Queued archives stay on disk for step 1, and the upload is not aborted at the server.#### Authentication@@ -258,7 +293,7 @@ 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.+- **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. The exception is `archive_parent_mismatch` on a final archive before the server accepted one (see "Final archives").- **`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.@@ -296,8 +331,8 @@ cd apps/server && bun --conditions=development test src/session-archive- 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 and its `path`; `git status` never rewriting `.git/index`.+ - a multi-MiB `writeSealedArchive` round trip checked with the `zstd` CLI, and a stopped writer rejecting.+- `manifest.test.ts`: UTF-8 byte order; the credential filter; the exclusions (credential, FIFO, app state, `__omnirush__`, unreadable, non-UTF-8); the hash cache; a stopped scan reading nothing; 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, with a delta's `trigger` and a final archive's `reason`; the git block and its `path`; `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; `git_parent` (nearest parent wins, a `.git` folder without `HEAD` there qualifies nothing, root `.git` preferred, dotfiles home, system dirs, posix and `path.win32` walks including `/Volumes/<disk>` homes and WSL shares).- `upload.test.ts` (in-process fake API and S3):- the happy path;@@ -312,10 +347,11 @@ cd apps/server && bun --conditions=development test src/session-archive- 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, and after the last archived turn when the messages could not be read; 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.+- `lifecycle.test.ts` (fake archiver and engine, plus runs 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, and after the last archived turn when the messages could not be read; 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. Final archives: one idle final per quiet window, a new prompt cancelling a pending or packing one; a turn that ends without completing (delta when the engine's count moved, final otherwise or when the engine cannot be read, and a completed turn whose count did not move); a deleted session (child never); shutdown passing this run's sessions most recent first with the budget, and nothing without a budget, with consent off or with the account gone; app-start finals queued behind other steps; on the real archiver, the idle, quit and app-start finals of one session with the next turn's delta after them.- `../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.+- `../capture-client.test.ts`: stopping the capture worker packs a final archive, and none when the account is gone.- `../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; a history past the 8 MiB read cap (one message over it alone) still gets its base, its turns' transcripts and deltas, and a turn whose messages cannot be read still gets its snapshot and delta; 428 checked once with the chat unaffected; the flag off sends nothing.+- `../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; a turn whose observer fails still gets its delta, numbered from the engine; a history past the 8 MiB read cap (one message over it alone) still gets its base, its turns' transcripts and deltas, and a turn whose messages cannot be read still gets its snapshot and delta; 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`;@@ -325,4 +361,5 @@ cd apps/server && bun --conditions=development test src/session-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.+ - the app's state dir under the root pruned;+ - final archives: none without a base or when unchanged; the equal-turn wire values (sequence, parent, turn), chained finals, `trigger` and `reason` in the manifest; a server without final archives (`strictTurns`): one refused create, the chain put back, the turn delta queued behind the final captured again, later turns uploaded, one log line; shutdown finals within the budget, a hanging one cut at it and captured at the next start; the app-start candidates (a final due, the most recent session per folder; not deleted or older than 7 days); a deleted session whose folder is gone.diff --git a/apps/server/src/session-archive/fake-archive-server.ts b/apps/server/src/session-archive/fake-archive-server.tsindex 2fa09c73..a445d5b6 100644--- a/apps/server/src/session-archive/fake-archive-server.ts+++ b/apps/server/src/session-archive/fake-archive-server.ts@@ -3,7 +3,9 @@* 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.+ * part listing and completion checks. A delta's turn may repeat its parent's+ * (a final archive), as the backend accepts from 1.0.11 on; `strictTurns`+ * emulates the backend before that.*/import { createHash, randomUUID } from "node:crypto";@@ -39,6 +41,8 @@ export class FakeArchiveServer {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;+ /** A backend without final archives: a delta's turn must be greater than its parent's (409 archive_parent_mismatch otherwise). */+ strictTurns = false;readonly archives = new Map<string, FakeArchive>();readonly calls: FakeCall[] = [];readonly puts: Array<{ archiveId: string; partNumber: number; status: number }> = [];@@ -159,7 +163,8 @@ export class FakeArchiveServer {}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) {+ if (!parent || parent.status !== "uploaded" || parent.request.sequence !== sequence - 1 || parent.request.session_id !== sessionId+ || turn < parent.request.turn || (this.strictTurns && turn === parent.request.turn)) {return json(409, { detail: "archive_parent_mismatch" });}}diff --git a/apps/server/src/session-archive/index.test.ts b/apps/server/src/session-archive/index.test.tsindex 4a253715..610c1dee 100644--- a/apps/server/src/session-archive/index.test.ts+++ b/apps/server/src/session-archive/index.test.ts@@ -417,3 +417,199 @@ describe("SessionArchiver", () => {expect(manifestOf(members).excluded).toMatchObject({ app_state: 1 });});});++describe("SessionArchiver final archives", () => {+ const archiveIdOf = (result: Awaited<ReturnType<SessionArchiver["captureFinal"]>>) => (result.status === "queued" ? result.archiveId : "");++ test("a final archive is a delta that repeats the last turn, says why in its manifest, and chains; nothing when unchanged, none without a base", async () => {+ const server = new FakeArchiveServer();+ const { root } = await project();+ const state = await tempDir("state");+ const subject = archiver(server, state);+ const id = "ses_final_chain_1";++ expect(await subject.captureFinal(id, "idle")).toEqual({ status: "skipped", reason: "no_base" });+ expect((await subject.captureBase(id, root)).status).toBe("queued");+ // Nothing changed since the base: no archive, no request.+ expect(await subject.captureFinal(id, "idle")).toEqual({ status: "skipped", reason: "unchanged" });+ await writeFile(join(root, "src/app.ts"), "export const app = 2;\n");+ expect(await subject.captureDelta(id, root, 3)).toMatchObject({ status: "queued", sequence: 1 });++ // The user edits after the turn: a final archive for turn 3, then another one.+ await writeFile(join(root, "src/user.ts"), "export const user = 1;\n");+ const idle = await subject.captureFinal(id, "idle");+ expect(idle).toMatchObject({ status: "queued", kind: "delta", sequence: 2 });+ await rm(join(root, "src/user.ts"));+ await writeFile(join(root, "notes.md"), "later\n");+ const quit = await subject.captureFinal(id, "app_quit");+ expect(quit).toMatchObject({ status: "queued", kind: "delta", sequence: 3 });+ // Turn 3 is archived: a delta for it again is stale; the next turn is 4.+ expect(await subject.captureDelta(id, root, 3)).toEqual({ status: "skipped", reason: "stale_turn" });+ await writeFile(join(root, "src/app.ts"), "export const app = 4;\n");+ expect(await subject.captureDelta(id, root, 4)).toMatchObject({ status: "queued", sequence: 4 });+ expect(await subject.drain()).toMatchObject({ uploaded: 5, pending: 0, dropped: 0 });++ const objects = server.objects();+ expect(objects.map((object) => [object.request.kind, object.request.sequence, object.request.turn])).toEqual([["base", 0, 0], ["delta", 1, 3], ["delta", 2, 3], ["delta", 3, 3], ["delta", 4, 4]]);+ for (let index = 1; index < objects.length; index += 1) expect(objects[index]!.request.parent_archive_id).toBe(objects[index - 1]!.request.archive_id);+ const manifests = await Promise.all(objects.map(async (object) => manifestOf(await openArchive(object.object!))));+ expect("trigger" in manifests[0]!).toBe(false);+ expect(manifests.slice(1).map((manifest) => [manifest.turn, manifest.trigger, manifest.reason])).toEqual([[3, "turn", undefined], [3, "final", "idle"], [3, "final", "app_quit"], [4, "turn", undefined]]);+ expect(manifests[2]).toMatchObject({ archive_id: archiveIdOf(idle), sequence: 2, parent_archive_id: objects[1]!.request.archive_id });+ expect((await openArchive(objects[2]!.object!)).map((member) => member.name)).toContain("src/user.ts");+ expect(manifests[3]).toMatchObject({ archive_id: archiveIdOf(quit), deleted: ["src/user.ts"] });++ // The server took a final archive: the chain point kept for a refusal is gone, one baseline is left.+ expect(await subject.captureFinal(id, "idle")).toEqual({ status: "skipped", reason: "unchanged" });+ expect(await readdir(join(state, ARCHIVE_STATE_DIRECTORY, "baselines"))).toHaveLength(1);+ });++ test("a server without final archives: the refused final is dropped once, the chain goes back, and the turn delta queued behind it is captured again", async () => {+ const server = new FakeArchiveServer();+ server.strictTurns = true;+ const { root } = await project();+ const state = await tempDir("state");+ const logs: Array<{ level: string; message: string }> = [];+ const subject = archiver(server, state, { log: (level, message) => logs.push({ level, message }) });+ const id = "ses_old_backend_1";++ expect((await subject.captureBase(id, root)).status).toBe("queued");+ await writeFile(join(root, "turn1.txt"), "turn 1\n");+ expect((await subject.captureDelta(id, root, 1)).status).toBe("queued");+ expect(await subject.drain()).toMatchObject({ uploaded: 2 });++ // Offline for a while: a final archive, then the next turn's delta chained on it.+ await writeFile(join(root, "user.txt"), "edited after turn 1\n");+ expect(await subject.captureFinal(id, "idle")).toMatchObject({ status: "queued", sequence: 2 });+ await writeFile(join(root, "turn2.txt"), "turn 2\n");+ expect(await subject.captureDelta(id, root, 2)).toMatchObject({ status: "queued", sequence: 3 });+ expect(await subject.drain()).toMatchObject({ uploaded: 0, dropped: 2, blocked: null, disabled: false });++ // Final archives are off until the app restarts (this also waits for the rewind).+ await writeFile(join(root, "user.txt"), "edited again\n");+ expect(await subject.captureFinal(id, "idle")).toEqual({ status: "skipped", reason: "unsupported" });+ expect(await subject.drain()).toMatchObject({ uploaded: 1, pending: 0 });+ const objects = server.objects();+ expect(objects.map((object) => [object.request.sequence, object.request.turn])).toEqual([[0, 0], [1, 1], [2, 2]]);+ expect(objects[2]!.request.parent_archive_id).toBe(objects[1]!.request.archive_id);+ const recaptured = await openArchive(objects[2]!.object!);+ expect(manifestOf(recaptured)).toMatchObject({ trigger: "turn", turn: 2, sequence: 2 });+ // Both the final's changes and the turn's are in the delta captured again.+ expect(recaptured.map((member) => member.name)).toEqual(expect.arrayContaining(["user.txt", "turn2.txt"]));++ // Later turns keep uploading on the restored chain.+ await writeFile(join(root, "turn3.txt"), "turn 3\n");+ expect(await subject.captureDelta(id, root, 3)).toMatchObject({ status: "queued", sequence: 3 });+ expect(await subject.drain()).toMatchObject({ uploaded: 1, pending: 0 });+ expect(server.objects().map((object) => object.request.turn)).toEqual([0, 1, 2, 3]);+ // One refused create, no retry loop; logged once, and the session was never stopped.+ expect(server.callPaths().filter((path) => path === "POST archives 409")).toHaveLength(1);+ expect(logs.filter((log) => log.message.includes("does not accept final"))).toHaveLength(1);+ expect(logs.filter((log) => log.level === "warn")).toEqual([]);+ expect(await readdir(join(state, ARCHIVE_STATE_DIRECTORY, "queue"))).toEqual([]);+ });++ test("shutdown captures final archives within its budget: a slow one is cut at the budget, and the next start checks that folder again", async () => {+ const server = new FakeArchiveServer();+ const fast = await project();+ const slow = await project();+ const state = await tempDir("state");+ // A gate that hangs for the slow folder while `hang` is set (a scan that never ends would do the same).+ let hang = true;+ const detectors = [+ async (root: string, options?: Parameters<typeof gitMarkerDetector>[1]) => {+ if (hang && root === slow.root) await new Promise(() => undefined);+ return gitMarkerDetector(root, options);+ },+ gitParentDetector,+ ];+ const first = archiver(server, state, { detectors });+ // The start-time gate let both in before anything hung.+ hang = false;+ expect((await first.captureBase("ses_quit_fast_01", fast.root)).status).toBe("queued");+ expect((await first.captureBase("ses_quit_slow_01", slow.root)).status).toBe("queued");+ expect(await first.drain()).toMatchObject({ uploaded: 2 });+ hang = true;+ await writeFile(join(fast.root, "after.txt"), "after the last turn\n");+ await writeFile(join(slow.root, "after.txt"), "after the last turn\n");++ const stoppedAt = Date.now();+ await first.stop({ finals: ["ses_quit_fast_01", "ses_quit_slow_01"], budgetMs: 400 });+ const elapsed = Date.now() - stoppedAt;+ expect(elapsed).toBeGreaterThanOrEqual(350);+ expect(elapsed).toBeLessThan(1_500);+ // Only the fast folder's final made it into the queue, nothing was uploaded at shutdown.+ const queued = await readdir(join(state, ARCHIVE_STATE_DIRECTORY, "queue"));+ expect(queued).toHaveLength(1);+ expect(server.objects()).toHaveLength(2);++ // The next app start: the slow folder's session still has its final due.+ hang = false;+ const second = archiver(server, state, { detectors });+ expect(await second.startFinalCandidates()).toEqual(expect.arrayContaining(["ses_quit_fast_01", "ses_quit_slow_01"]));+ expect(await second.captureFinal("ses_quit_fast_01", "app_start")).toEqual({ status: "skipped", reason: "unchanged" });+ expect(await second.captureFinal("ses_quit_slow_01", "app_start")).toMatchObject({ status: "queued", sequence: 1 });+ expect(await second.drain()).toMatchObject({ uploaded: 2, pending: 0 });+ const finals = await Promise.all(server.objects().slice(2).map(async (object) => [object.request.session_id, object.request.turn, manifestOf(await openArchive(object.object!)).reason]));+ expect(finals.sort()).toEqual([["ses_quit_fast_01", 0, "app_quit"], ["ses_quit_slow_01", 0, "app_start"]]);+ });++ test("app start: a final for sessions whose folder may have changed while the app was closed; not for deleted, stopped or old ones", async () => {+ const server = new FakeArchiveServer();+ const { root } = await project();+ const other = await project();+ const state = await tempDir("state");+ let clock = Date.now() - 8 * 24 * 60 * 60_000;+ const subject = archiver(server, state, { now: () => new Date(clock) });+ // Eight days ago: a chat on the other folder.+ expect((await subject.captureBase("ses_start_old_01", other.root)).status).toBe("queued");+ // Earlier today, two chats on this folder: one ended its day with a turn, the other was archived after its turn.+ clock = Date.now() - 60 * 60_000;+ expect((await subject.captureBase("ses_start_due_01", root)).status).toBe("queued");+ await writeFile(join(root, "due.txt"), "turn\n");+ expect((await subject.captureDelta("ses_start_due_01", root, 1)).status).toBe("queued");+ expect((await subject.captureBase("ses_start_deleted", root)).status).toBe("queued");+ clock = Date.now() - 30 * 60_000;+ expect((await subject.captureBase("ses_start_last_01", root)).status).toBe("queued");+ await writeFile(join(root, "last.txt"), "turn\n");+ expect((await subject.captureDelta("ses_start_last_01", root, 2)).status).toBe("queued");+ await writeFile(join(root, "gone.txt"), "last edit\n");+ expect(await subject.captureFinal("ses_start_last_01", "app_quit")).toMatchObject({ status: "queued" });+ // Deleted in the app: its final, and it is ended.+ expect(await subject.captureFinal("ses_start_deleted", "session_deleted")).toMatchObject({ status: "queued" });+ expect(await subject.drain()).toMatchObject({ pending: 0 });+ await subject.stop();++ // Edited while the app was closed.+ await writeFile(join(root, "closed.txt"), "edited while closed\n");+ clock = Date.now();+ const next = archiver(server, state, { now: () => new Date(clock) });+ // The most recent session on the folder, and the one whose final never came; newest first.+ expect(await next.startFinalCandidates()).toEqual(["ses_start_last_01", "ses_start_due_01"]);+ const last = await next.captureFinal("ses_start_last_01", "app_start");+ expect(last).toMatchObject({ status: "queued", kind: "delta", sequence: 3 });+ expect(await next.drain()).toMatchObject({ uploaded: 1 });+ const object = server.objects().find((candidate) => candidate.request.archive_id === archiveIdOf(last))!;+ expect(object.request).toMatchObject({ session_id: "ses_start_last_01", kind: "delta", sequence: 3, turn: 2 });+ const members = await openArchive(object.object!);+ expect(manifestOf(members)).toMatchObject({ trigger: "final", reason: "app_start", turn: 2 });+ expect(members.map((member) => member.name)).toContain("closed.txt");+ // Its final settles the session whose last turn had none; the folder's most recent archive is now that one.+ clock += 1_000;+ expect(await next.captureFinal("ses_start_due_01", "app_start")).toMatchObject({ status: "queued", sequence: 2 });+ expect(await next.startFinalCandidates()).toEqual(["ses_start_due_01"]);+ });++ test("a session deleted with its folder gone gets no final, and is not checked at the next start", async () => {+ const server = new FakeArchiveServer();+ const { root } = await project();+ const state = await tempDir("state");+ const subject = archiver(server, state);+ expect((await subject.captureBase("ses_deleted_gone", root)).status).toBe("queued");+ await subject.drain();+ await rm(root, { recursive: true, force: true });+ expect(await subject.captureFinal("ses_deleted_gone", "session_deleted")).toEqual({ status: "skipped", reason: "not_archivable" });+ expect(await subject.startFinalCandidates()).toEqual([]);+ expect(server.objects()).toHaveLength(1);+ });+});diff --git a/apps/server/src/session-archive/index.ts b/apps/server/src/session-archive/index.tsindex b915c0c9..0011f4b4 100644--- a/apps/server/src/session-archive/index.ts+++ b/apps/server/src/session-archive/index.ts@@ -1,11 +1,12 @@/*** 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.+ * whole folder at session start, a delta after every completed turn that+ * changed anything, and a final delta (the last turn's number again) when the+ * folder changed after that turn; 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";@@ -26,6 +27,8 @@ import {readArchiveGit,scanArchiveTree,type ArchiveKind,+ type ArchiveTrigger,+ type FinalReason,type ScannedEntry,} from "./manifest.js";import { writeSealedArchive } from "./pack.js";@@ -42,7 +45,7 @@ import {} from "./upload.js";export { gitMarkerDetector, gitParentDetector, isArchivableProject, type ArchivableProject, type ProjectMarkerDetector } from "./detect.js";-export { isArchiveCredentialPath } from "./manifest.js";+export { isArchiveCredentialPath, type ArchiveTrigger, type FinalReason } from "./manifest.js";export type { ArchiveApiRequest } from "./upload.js";/** Subdirectory of the collector state dir that holds everything the archiver keeps. */@@ -56,6 +59,10 @@ const MAX_JOB_AGE_MS = 7 * 24 * 60 * 60_000;const JOB_RETRY_BASE_MS = 60_000;const JOB_RETRY_MAX_MS = 60 * 60_000;const SIGN_OUT_ABORT_TIMEOUT_MS = 5_000;+/** At app start, sessions whose chain moved within this long may get a final archive (startFinalCandidates). */+const START_FINAL_WINDOW_MS = 7 * 24 * 60 * 60_000;+/** At most this many sessions are scanned for a final archive at app start. */+const MAX_START_FINALS = 10;export type SessionArchiverOptions = {/** As the collector: the archive routes are derived from it like the collect URL. */@@ -93,7 +100,11 @@ export type CaptureSkipReason =/** Additions to the section 13.2 union: */| "unavailable"| "stale_turn"- | "failed";+ | "failed"+ /** Final archives only: cancelled by a new prompt or by the end of the shutdown budget. */+ | "cancelled"+ /** Final archives only: the server refused one (a backend without them); none until the app restarts. */+ | "unsupported";export type CaptureResult =| { status: "queued"; archiveId: string; kind: ArchiveKind; sequence: number; size: number }@@ -111,6 +122,14 @@ export type DrainResult = {disabled: boolean;};+/** Where a chain continues from: its next sequence, last archive, last turn and the baseline of that archive. */+const chainPointSchema = z.object({+ next_sequence: z.number().int().nonnegative(),+ last_archive_id: z.string().nullable(),+ last_turn: z.number().int().nullable(),+ baseline: z.string().nullable(),+});+const sessionStateSchema = z.object({v: z.literal(1),session_id: z.string(),@@ -122,6 +141,18 @@ const sessionStateSchema = z.object({baseline: z.string().nullable(),stopped: z.string().nullable(),updated_at: z.string(),+ // Added in 1.0.11; optional so that earlier records still load.+ /**+ * Set while final archives the server has not accepted yet are in the+ * chain: the chain as it was before the first of them, whose baseline is+ * kept. A server that refuses final archives sends the chain back to it+ * (rewindRefusedFinal).+ */+ rewind: chainPointSchema.nullable().optional(),+ /** A turn was captured since the last final archive: at app start the folder is checked once more. */+ final_due: z.boolean().optional(),+ /** When the session was deleted in the app: no final archive at app start. */+ ended: z.string().nullable().optional(),});type SessionState = z.infer<typeof sessionStateSchema>;@@ -145,6 +176,8 @@ const queueRecordSchema = z.object({session_key: z.string(),request: createRequestSchema,sealed_file: z.string(),+ /** A delta's trigger (1.0.11 on): how a refused final is told from a broken chain. */+ trigger: z.enum(["turn", "final"]).optional(),created_at: z.string(),attempts: z.number().int().nonnegative(),next_attempt_at: z.string().nullable(),@@ -178,6 +211,17 @@ function errorSummary(error: unknown): string {return "unknown error";}+/** How a capture was asked for. */+type CaptureOptions = {+ /** Deltas only: a completed turn, or a final archive with its reason. */+ trigger?: ArchiveTrigger;+ reason?: FinalReason;+ /** A final archive of a session deleted in the app: its record is marked ended. */+ ended?: boolean;+ /** Cancels the capture until its commit. */+ signal?: AbortSignal;+};+export class SessionArchiver {private readonly dir: string;private readonly dirs: { sessions: string; baselines: string; hashCache: string; queue: string; pending: string; tmp: string };@@ -203,6 +247,10 @@ export class SessionArchiver {private drainAgain = false;private drainController: AbortController | null = null;private retryTimer: ReturnType<typeof setTimeout> | null = null;+ /** The server accepted a final archive in this app run: a later refusal is a real chain conflict. */+ private finalsAccepted = false;+ /** The server refused a final archive (a backend without them): none is captured until the app restarts. */+ private finalsRefused = false;constructor(options: SessionArchiverOptions) {const stateDir = resolve(options.stateDir);@@ -289,10 +337,87 @@ export class SessionArchiver {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", next, key, generation);+ return this.captureArchive(state, "delta", next, key, generation, { trigger: "turn" });+ }));+ }++ /**+ * A final archive: the folder after the last completed turn (the session+ * went quiet, a turn ended without completing, the session was deleted,+ * the app quits or starts again). A delta like any other, numbered with+ * the last archived turn again, whose manifest says `"trigger": "final"`+ * and why. Only for a session with a base, whose root the gate still+ * accepts; nothing when the folder did not change. `signal` cancels it+ * until its commit.+ */+ captureFinal(sessionId: string, reason: FinalReason, options: { signal?: AbortSignal } = {}): Promise<CaptureResult> {+ const { signal } = options;+ return this.guard("delta", sessionId, 0, async () => this.withSession(sessionId, async () => {+ const generation = this.generation;+ if (signal?.aborted) return { status: "skipped", reason: "cancelled" };+ if (this.disabled || !this.uploader.configured) return { status: "skipped", reason: "disabled" };+ const state = await this.loadSession(sessionId);+ if (!state || state.next_sequence === 0 || state.last_turn === null) return { status: "skipped", reason: "no_base" };+ if (state.stopped || this.stoppedSessions.has(sessionId)) return { status: "skipped", reason: "stopped" };+ const ended = reason === "session_deleted";+ const skip = async (skipReason: CaptureSkipReason): Promise<CaptureResult> => {+ if (ended && generation === this.generation) await this.saveSession({ ...state, final_due: false, ended: this.now().toISOString(), updated_at: this.now().toISOString() });+ return { status: "skipped", reason: skipReason };+ };+ if (this.finalsRefused) return skip("unsupported");+ // The folder may be gone, or no longer what the start-time gate accepted.+ const gate = await isArchivableProject(state.root, this.detectors, { appDirs: this.appDirs });+ if (!gate.archivable) return skip("not_archivable");+ const key = await this.currentKey(signal);+ if (signal?.aborted) return { status: "skipped", reason: "cancelled" };+ if (key === "disabled") return { status: "skipped", reason: "disabled" };+ if (key === "unavailable") return { status: "skipped", reason: "unavailable" };+ try {+ return await this.captureArchive(state, "delta", state.last_turn, key, generation, { trigger: "final", reason, ended, ...(signal ? { signal } : {}) });+ } catch (error) {+ if (signal?.aborted) return { status: "skipped", reason: "cancelled" };+ throw error;+ }}));}+ /**+ * The sessions to give a final archive once at app start: every session+ * with a turn captured since its last final archive (the app quit before+ * that final, or crashed), and the most recent session on each other+ * folder (the folder may have changed while the app was closed). Only+ * sessions whose chain moved within the last 7 days, not stopped and not+ * deleted; the most recent first, at most 10.+ */+ async startFinalCandidates(): Promise<string[]> {+ try {+ await this.start();+ if (this.disabled) return [];+ const nowMs = this.now().getTime();+ const sessions: SessionState[] = [];+ for (const name of await readdir(this.dirs.sessions)) {+ if (!name.endsWith(".json")) continue;+ const parsed = sessionStateSchema.safeParse(await readJsonFile(join(this.dirs.sessions, name)));+ if (!parsed.success || name !== `${stateKey(parsed.data.session_id)}.json`) continue;+ const state = parsed.data;+ if (state.stopped || state.ended || state.next_sequence === 0 || !(nowMs - Date.parse(state.updated_at) <= START_FINAL_WINDOW_MS)) continue;+ sessions.push(state);+ }+ sessions.sort((left, right) => right.updated_at.localeCompare(left.updated_at));+ const roots = new Set<string>();+ const picked: string[] = [];+ for (const state of sessions) {+ const newestOnRoot = !roots.has(state.root);+ roots.add(state.root);+ if (state.final_due || newestOnRoot) picked.push(state.session_id);+ }+ return picked.slice(0, MAX_START_FINALS);+ } catch (error) {+ this.log("warn", "OmniRush archive could not list the sessions to check at start", { error: errorSummary(error) });+ return [];+ }+ }+/** Uploads queued archives until the queue is empty or blocked; never throws. */drain(): Promise<DrainResult> {if (this.draining) {@@ -339,23 +464,58 @@ export class SessionArchiver {this.disabled = null;this.stoppedSessions.clear();this.resettingSessions.clear();+ this.finalsAccepted = false;+ this.finalsRefused = false;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.+ * App shutdown: stops the drain and the retry timer at once; queued+ * archives stay for the next start. With `finals`, a final archive of each+ * of those sessions is captured first, one after the other, all within+ * `budgetMs` (a session whose capture is still running goes last); captures+ * already running may commit within the budget too. After it nothing+ * commits: a capture still packing is dropped (the server that replaces+ * this one after a sign-out must not find it queued), and the next start+ * checks the folder again (startFinalCandidates).*/- async stop(): Promise<void> {+ async stop(options: { finals?: readonly string[]; budgetMs?: number } = {}): Promise<void> {+ this.clearRetryTimer();+ this.drainController?.abort();+ const budgetMs = options.budgetMs ?? 0;+ if (options.finals && options.finals.length > 0 && budgetMs > 0) await this.quitFinals(options.finals, budgetMs);this.generation += 1;this.clearRetryTimer();this.drainController?.abort();await this.draining?.catch(() => undefined);}+ /** stop()'s final archives: sessions with nothing running first; whatever is left at the deadline is cancelled. */+ private async quitFinals(sessionIds: readonly string[], budgetMs: number): Promise<void> {+ const controller = new AbortController();+ const ordered = [...sessionIds.filter((id) => !this.sessionTails.has(id)), ...sessionIds.filter((id) => this.sessionTails.has(id))];+ let done = 0;+ const captures = (async () => {+ for (const sessionId of ordered) {+ if (controller.signal.aborted) return;+ await this.captureFinal(sessionId, "app_quit", { signal: controller.signal });+ done += 1;+ }+ })();+ let timer: ReturnType<typeof setTimeout> | undefined;+ const deadline = new Promise<void>((resolvePromise) => {+ timer = setTimeout(resolvePromise, budgetMs);+ timer.unref?.();+ });+ await Promise.race([captures, deadline]);+ clearTimeout(timer);+ controller.abort();+ if (done < ordered.length) {+ this.log("info", "OmniRush archive shutdown budget ran out; the remaining folders are checked at the next start", { budgetMs, sessions: ordered.length, finished: done });+ }+ }+// --- captures -------------------------------------------------------------------------private async guard(kind: ArchiveKind, sessionId: string, turn: number, task: () => Promise<CaptureResult>): Promise<CaptureResult> {@@ -420,9 +580,9 @@ export class SessionArchiver {}}- private async currentKey(): Promise<ArchiveKey | "disabled" | "unavailable"> {+ private async currentKey(signal?: AbortSignal): Promise<ArchiveKey | "disabled" | "unavailable"> {if (this.key) return this.key;- const fetched = await this.uploader.fetchKey();+ const fetched = await this.uploader.fetchKey(signal);if (fetched.status === "disabled") {await this.disable(fetched.code);return "disabled";@@ -436,22 +596,23 @@ export class SessionArchiver {* 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> {+ private async captureArchive(state: SessionState, kind: ArchiveKind, turn: number, key: ArchiveKey, generation: number, options: CaptureOptions = {}): Promise<CaptureResult> {hintGarbageCollection();try {- return await this.captureArchiveOnce(state, kind, turn, key, generation);+ return await this.captureArchiveOnce(state, kind, turn, key, generation, options);} 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> {+ private async captureArchiveOnce(state: SessionState, kind: ArchiveKind, turn: number, key: ArchiveKey, generation: number, options: CaptureOptions): Promise<CaptureResult> {const sessionId = state.session_id;const sessionKey = stateKey(sessionId);const rootKey = stateKey(state.root);+ const { signal } = options;const cache = await this.loadHashCache(rootKey);- const scanning = scanArchiveTree(state.root, { excludedDirs: this.appDirs, includeCredentialFiles: this.includeCredentials, hashCache: cache });+ const scanning = scanArchiveTree(state.root, { excludedDirs: this.appDirs, includeCredentialFiles: this.includeCredentials, hashCache: cache, ...(signal ? { signal } : {}) });const gitReading = kind === "base" ? readArchiveGit(state.root) : null;const scan = await scanning;let files: ScannedEntry[] = scan.entries;@@ -465,6 +626,7 @@ export class SessionArchiver {const delta = computeArchiveDelta(baseline, scan.entries);if (isArchiveDeltaEmpty(delta)) {if (cache.changed) await this.saveHashCache(rootKey, cache);+ if (generation === this.generation) await this.noteUnchanged(state, options);return { status: "skipped", reason: "unchanged" };}files = delta.files;@@ -482,6 +644,8 @@ export class SessionArchiver {turn,createdAt,parentArchiveId: kind === "base" ? null : state.last_archive_id,+ ...(kind === "delta" && options.trigger ? { trigger: options.trigger } : {}),+ ...(kind === "delta" && options.reason ? { reason: options.reason } : {}),label: archiveLabel(state.root),marker: state.marker,git,@@ -493,7 +657,7 @@ export class SessionArchiver {let sealed: Awaited<ReturnType<typeof writeSealedArchive>>;try {sealed = await writeSealedArchive(- { root: state.root, manifest, createdAtSeconds: Math.floor(createdAt.getTime() / 1000), entries: files },+ { root: state.root, manifest, createdAtSeconds: Math.floor(createdAt.getTime() / 1000), entries: files, ...(signal ? { signal } : {}) },{ publicKey: key.publicKey },partial,);@@ -501,9 +665,10 @@ export class SessionArchiver {await rm(partial, { force: true });throw error;}- if (generation !== this.generation || this.disabled || this.stoppedSessions.has(sessionId)) {+ if (generation !== this.generation || this.disabled || this.stoppedSessions.has(sessionId) || signal?.aborted) {await rm(partial, { force: true });- return { status: "skipped", reason: this.disabled ? "disabled" : "stopped" };+ if (this.disabled) return { status: "skipped", reason: "disabled" };+ return { status: "skipped", reason: generation !== this.generation || this.stoppedSessions.has(sessionId) ? "stopped" : "cancelled" };}// 1-2: the sealed file and its queue record.const sealedFile = `${archiveId}.orseal`;@@ -527,6 +692,7 @@ export class SessionArchiver {session_key: sessionKey,request,sealed_file: sealedFile,+ ...(kind === "delta" && options.trigger ? { trigger: options.trigger } : {}),created_at: createdAt.toISOString(),attempts: 0,next_attempt_at: null,@@ -539,17 +705,24 @@ export class SessionArchiver {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.+ // 4: commit. Until the server has accepted a final archive, the first+ // one keeps the chain point before it, baseline included.const previousBaseline = state.baseline;+ const rewind = state.rewind ?? (options.trigger === "final" && !this.finalsAccepted+ ? { next_sequence: state.next_sequence, last_archive_id: state.last_archive_id, last_turn: state.last_turn, baseline: state.baseline }+ : null);await this.saveSession({...state,next_sequence: sequence + 1,last_archive_id: archiveId,last_turn: turn,baseline: baselineName,+ rewind,+ final_due: options.trigger !== "final",+ ...(options.ended ? { ended: this.now().toISOString() } : {}),updated_at: this.now().toISOString(),});- if (previousBaseline && previousBaseline !== baselineName) await rm(join(this.dirs.baselines, previousBaseline), { force: true });+ if (previousBaseline && previousBaseline !== baselineName && previousBaseline !== rewind?.baseline) await rm(join(this.dirs.baselines, previousBaseline), { force: true });await this.saveHashCache(rootKey, cache);this.log("info", "OmniRush project archive queued", {sessionId,@@ -557,6 +730,7 @@ export class SessionArchiver {kind,sequence,turn,+ ...(options.trigger === "final" ? { trigger: "final", reason: options.reason } : {}),bytes: sealed.size,files: files.length,...(deleted ? { deleted: deleted.length } : {}),@@ -565,6 +739,18 @@ export class SessionArchiver {return { status: "queued", archiveId, kind, sequence, size: sealed.size };}+ /** Nothing changed: after a turn the session's final is due (checked at the next start), a final settles it. */+ private async noteUnchanged(state: SessionState, options: CaptureOptions): Promise<void> {+ const final = options.trigger === "final";+ if (final && !state.final_due && !options.ended) return;+ await this.saveSession({+ ...state,+ final_due: !final,+ ...(options.ended ? { ended: this.now().toISOString() } : {}),+ updated_at: this.now().toISOString(),+ });+ }+// --- drain -----------------------------------------------------------------------------private async runDrain(): Promise<DrainResult> {@@ -642,6 +828,7 @@ export class SessionArchiver {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 });+ if (record.trigger === "final") this.finalAccepted(sessionId, record.request.sequence);break;case "disabled":result.dropped += await this.disable(outcome.code);@@ -652,7 +839,12 @@ export class SessionArchiver {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);+ if (record.trigger === "final" && outcome.code === "archive_parent_mismatch" && !this.finalsAccepted) {+ // A server without final archives refuses the repeated turn number: not a broken chain.+ result.dropped += await this.rewindRefusedFinal(record);+ } else {+ result.dropped += await this.stopSession(sessionId, outcome.code);+ }held.add(sessionId);break;case "rekey":@@ -749,6 +941,81 @@ export class SessionArchiver {if (state && !state.stopped) await this.saveSession({ ...state, stopped: code, updated_at: this.now().toISOString() });}+ /**+ * The server accepted a final archive: it takes them, and the chain up to+ * `sequence` stands, so the session no longer needs its rewind point.+ */+ private finalAccepted(sessionId: string, sequence: number): void {+ this.finalsAccepted = true;+ const generation = this.generation;+ void this.withSession(sessionId, async () => {+ if (generation !== this.generation) return;+ const state = await this.loadSession(sessionId);+ const rewind = state?.rewind;+ if (!state || !rewind || rewind.next_sequence > sequence) return;+ if (rewind.baseline && rewind.baseline !== state.baseline) await rm(join(this.dirs.baselines, rewind.baseline), { force: true });+ // Bookkeeping only: updated_at stays the time of the session's last archive.+ await this.saveSession({ ...state, rewind: null });+ }).catch((error) => this.log("warn", "OmniRush archive session update failed", { sessionId, error: errorSummary(error) }));+ }++ /**+ * 409 archive_parent_mismatch on a final archive before any was accepted:+ * a server that does not take final archives (their turn repeats the+ * parent's). The final is dropped, with the jobs chained on it, and the+ * chain goes back to where it was before it; a turn delta dropped with it+ * is captured again on top, so later turns keep uploading. No final+ * archive is captured again until the app restarts. Returns the jobs+ * dropped.+ */+ private async rewindRefusedFinal(record: QueueRecord): Promise<number> {+ const sessionId = record.request.session_id;+ const from = record.request.sequence;+ if (!this.finalsRefused) {+ this.finalsRefused = true;+ this.log("info", "The omnirush.ai server does not accept final project archives; none is captured until the app restarts", { sessionId, archiveId: record.archive_id });+ }+ const chained = (job: QueueRecord) => job.request.session_id === sessionId && job.request.sequence >= from;+ const dropped = (await this.listQueue()).filter(chained);+ // Held out of the drain until the chain is back where the server has it.+ this.resettingSessions.add(sessionId);+ const generation = this.generation;+ let recaptured = false;+ void this.withSession(sessionId, async () => {+ if (generation !== this.generation) return;+ // Jobs committed since (a capture that held the lock) are chained on it too.+ const jobs = (await this.listQueue()).filter(chained);+ const state = await this.loadSession(sessionId);+ const rewind = state?.rewind;+ if (!state || state.stopped) {+ for (const job of jobs) await this.deleteJob(job);+ return;+ }+ if (!rewind || rewind.next_sequence !== from) {+ // Nothing to go back to: the chain ends as for any conflict.+ this.stoppedSessions.set(sessionId, "archive_parent_mismatch");+ await this.markStopped(sessionId, "archive_parent_mismatch");+ return;+ }+ // The state first: a crash before the jobs go leaves them past next_sequence, which start() removes.+ const restored: SessionState = { ...state, ...rewind, rewind: null, final_due: true, updated_at: this.now().toISOString() };+ await this.saveSession(restored);+ if (state.baseline && state.baseline !== rewind.baseline) await rm(join(this.dirs.baselines, state.baseline), { force: true });+ for (const job of jobs) await this.deleteJob(job);+ const turn = Math.max(-1, ...jobs.filter((job) => job.trigger !== "final").map((job) => job.request.turn));+ if (turn > (restored.last_turn ?? -1) && this.key) {+ const again = await this.captureArchive(restored, "delta", turn, this.key, generation, { trigger: "turn" });+ recaptured = again.status === "queued";+ }+ })+ .catch((error) => this.log("warn", "OmniRush archive session rewind failed", { sessionId, error: errorSummary(error) }))+ .finally(() => {+ this.resettingSessions.delete(sessionId);+ if (recaptured && generation === this.generation) void this.drain();+ });+ return dropped.length;+ }+/** 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);@@ -765,7 +1032,8 @@ export class SessionArchiver {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() });+ if (state.rewind?.baseline) await rm(join(this.dirs.baselines, state.rewind.baseline), { force: true });+ await this.saveSession({ ...state, next_sequence: 0, last_archive_id: null, last_turn: null, baseline: null, rewind: 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));@@ -890,7 +1158,7 @@ export class SessionArchiver {}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));+ const namedBaselines = new Set([...sessions.values()].flatMap((session) => [session.baseline, session.rewind?.baseline ?? null]).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 });}diff --git a/apps/server/src/session-archive/lifecycle.test.ts b/apps/server/src/session-archive/lifecycle.test.tsindex ec51e596..82252786 100644--- a/apps/server/src/session-archive/lifecycle.test.ts+++ b/apps/server/src/session-archive/lifecycle.test.ts@@ -5,7 +5,7 @@ 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 { SessionArchiver, type CaptureResult, type DrainResult, type FinalReason } from "./index.js";import {completedTurnCount,projectArchiveEnabled,@@ -28,7 +28,12 @@ class FakeArchiver implements ProjectArchiver {readonly calls: string[] = [];base: (sessionId: string, turn: number) => Promise<CaptureResult> = async () => queued("base");delta: (sessionId: string, turn: number | null) => Promise<CaptureResult> = async (_sessionId, turn) => queued("delta", turn ?? 0);+ final: (sessionId: string, reason: FinalReason, signal?: AbortSignal) => Promise<CaptureResult> = async () => skipped("unchanged");drainResult: () => Promise<DrainResult> = async () => drained;+ /** What startFinalCandidates answers (not recorded as a call). */+ startFinals: string[] = [];+ /** The options of each stop() call. */+ readonly stops: Array<{ finals?: readonly string[]; budgetMs?: number }> = [];async captureBase(sessionId: string, root: string, turn = 0): Promise<CaptureResult> {this.calls.push(`base ${sessionId} ${root} ${turn}`);@@ -40,6 +45,15 @@ class FakeArchiver implements ProjectArchiver {return this.delta(sessionId, turn);}+ async captureFinal(sessionId: string, reason: FinalReason, options: { signal?: AbortSignal } = {}): Promise<CaptureResult> {+ this.calls.push(`final ${sessionId} ${reason}`);+ return this.final(sessionId, reason, options.signal);+ }++ async startFinalCandidates(): Promise<string[]> {+ return this.startFinals;+ }+async drain(): Promise<DrainResult> {this.calls.push("drain");return this.drainResult();@@ -49,13 +63,18 @@ class FakeArchiver implements ProjectArchiver {this.calls.push("signOut");}- async stop(): Promise<void> {+ async stop(options: { finals?: readonly string[]; budgetMs?: number } = {}): Promise<void> {this.calls.push("stop");+ this.stops.push(options);}captures(): string[] {return this.calls.filter((call) => call.startsWith("base") || call.startsWith("delta"));}++ finals(): string[] {+ return this.calls.filter((call) => call.startsWith("final"));+ }}type Message = { info: Record<string, unknown>; parts: unknown[] };@@ -86,7 +105,7 @@ function engine(input: { parentID?: string; messages?: () => unknown; session?:return { reader, reads };}-function lifecycle(archiver: ProjectArchiver, options: { enabled?: boolean; now?: () => number; concurrency?: number } = {}) {+function lifecycle(archiver: ProjectArchiver, options: { enabled?: boolean; now?: () => number; concurrency?: number; finalIdleMs?: number; quitBudgetMs?: number } = {}) {const logs: Array<{ level: string; message: string; attributes?: Record<string, unknown> }> = [];const subject = new ProjectArchiveLifecycle({archiver,@@ -95,6 +114,8 @@ function lifecycle(archiver: ProjectArchiver, options: { enabled?: boolean; now?consentRecheckMs: 60_000,...(options.now ? { now: options.now } : {}),...(options.concurrency ? { concurrency: options.concurrency } : {}),+ ...(options.finalIdleMs !== undefined ? { finalIdleMs: options.finalIdleMs } : {}),+ ...(options.quitBudgetMs !== undefined ? { quitBudgetMs: options.quitBudgetMs } : {}),});return { subject, logs };}@@ -558,3 +579,236 @@ describe("ProjectArchiveLifecycle base quiet period", () => {}});});++describe("ProjectArchiveLifecycle final archives", () => {+ const sleep = (ms: number) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms));++ /** Turn deltas numbered like the real archiver: a count that did not move is stale. */+ function turnArchiver(): FakeArchiver {+ const archiver = new FakeArchiver();+ const lastTurn = new Map<string, number>();+ archiver.base = async (sessionId, turn) => {+ lastTurn.set(sessionId, turn);+ return queued("base");+ };+ archiver.delta = async (sessionId, turn) => {+ const next = turn ?? (lastTurn.get(sessionId) ?? 0) + 1;+ if (next <= (lastTurn.get(sessionId) ?? -1)) return skipped("stale_turn");+ lastTurn.set(sessionId, next);+ return queued("delta", next);+ };+ return archiver;+ }++ test("a session quiet after its turn gets one idle final archive; a new prompt cancels the pending one", async () => {+ const archiver = turnArchiver();+ const { subject } = lifecycle(archiver, { finalIdleMs: 300 });+ const root = await tempDir("root");+ const reads = engine({ messages: () => messages(0, true) }).reader;+ subject.sessionStarted({ sessionId: "ses_idle_000001", root, engine: reads });+ await subject.settled();+ // The next prompt comes within the quiet window: no final archive.+ subject.turnCompleted("ses_idle_000001", messages(1));+ await sleep(30);+ subject.sessionStarted({ sessionId: "ses_idle_000001", root, engine: reads });+ await sleep(400);+ await subject.settled();+ expect(archiver.finals()).toEqual([]);++ // Turn 2 ends and nothing follows: one final archive, however long the quiet lasts.+ subject.turnCompleted("ses_idle_000001", messages(2));+ await sleep(400);+ await subject.settled();+ expect(archiver.finals()).toEqual(["final ses_idle_000001 idle"]);+ await sleep(400);+ await subject.settled();+ expect(archiver.finals()).toHaveLength(1);+ expect(archiver.captures()).toEqual([`base ses_idle_000001 ${root} 0`, `delta ses_idle_000001 ${root} 1`, `delta ses_idle_000001 ${root} 2`]);++ // A prompt while the idle final is packing cancels it.+ let signal: AbortSignal | undefined;+ archiver.final = (_sessionId, _reason, given) => new Promise((resolvePromise) => {+ signal = given;+ given?.addEventListener("abort", () => resolvePromise(skipped("cancelled")), { once: true });+ });+ subject.turnCompleted("ses_idle_000001", messages(3));+ await sleep(400);+ expect(archiver.finals()).toHaveLength(2);+ expect(signal?.aborted).toBe(false);+ subject.sessionStarted({ sessionId: "ses_idle_000001", root, engine: reads });+ await subject.settled();+ expect(signal?.aborted).toBe(true);+ });++ test("a turn that ends without completing: its delta when the engine's count moved, else a final archive", async () => {+ const archiver = turnArchiver();+ const { subject } = lifecycle(archiver, { finalIdleMs: 60_000 });+ const root = await tempDir("root");+ let count: number | null = 0;+ const reads = engine({ messages: () => (count === null ? Promise.reject(new Error("ECONNREFUSED")) : messages(count)) });+ subject.sessionStarted({ sessionId: "ses_abnormal_001", root, engine: reads.reader });+ await subject.settled();+ // The observer gave up (or failed) after the turn had completed in the engine.+ count = 1;+ subject.turnIncomplete("ses_abnormal_001");+ await subject.settled();+ // Aborted before any answer: the count did not move.+ subject.turnIncomplete("ses_abnormal_001");+ await subject.settled();+ // The engine went away: no count to go by.+ count = null;+ subject.turnIncomplete("ses_abnormal_001");+ await subject.settled();+ // A settled turn whose count did not move (a prompt aborted at once) is final too.+ subject.turnCompleted("ses_abnormal_001", messages(1, true));+ await subject.settled();+ expect(archiver.calls.filter((call) => call !== "drain")).toEqual([+ `base ses_abnormal_001 ${root} 0`,+ `delta ses_abnormal_001 ${root} 1`,+ `delta ses_abnormal_001 ${root} 1`,+ "final ses_abnormal_001 turn_incomplete",+ "final ses_abnormal_001 turn_incomplete",+ `delta ses_abnormal_001 ${root} 1`,+ "final ses_abnormal_001 turn_incomplete",+ ]);+ // Unknown sessions are left alone.+ subject.turnIncomplete("ses_unknown_0001");+ await subject.settled();+ expect(archiver.finals()).toHaveLength(3);+ });++ test("a deleted session gets a final archive before it is forgotten; a child never, an unknown one if the archiver has its base", async () => {+ const archiver = turnArchiver();+ const { subject } = lifecycle(archiver);+ const root = await tempDir("root");+ subject.sessionStarted({ sessionId: "ses_deleted_0001", root, engine: engine().reader });+ subject.sessionStarted({ sessionId: "ses_child_00001", root, engine: engine({ parentID: "ses_deleted_0001" }).reader });+ await subject.settled();+ subject.turnCompleted("ses_deleted_0001", messages(1));+ subject.sessionEnded("ses_deleted_0001");+ subject.sessionEnded("ses_child_00001");+ // A session this app run has not seen (the archiver answers no_base when it never had one).+ subject.sessionEnded("ses_earlier_0001");+ await subject.settled();+ expect(archiver.finals().sort()).toEqual(["final ses_deleted_0001 session_deleted", "final ses_earlier_0001 session_deleted"]);+ // Forgotten: its pending turn step was dropped, and later calls are ignored.+ subject.turnCompleted("ses_deleted_0001", messages(2));+ await subject.settled();+ expect(archiver.captures()).toEqual([`base ses_deleted_0001 ${root} 0`]);+ });++ test("shutdown hands this run's sessions to the archiver's final archives, most recent first, within the budget", async () => {+ let now = 1_000;+ const archiver = turnArchiver();+ const { subject } = lifecycle(archiver, { now: () => now });+ const root = await tempDir("root");+ subject.sessionStarted({ sessionId: "ses_quit_old_001", root, engine: engine().reader });+ now += 1_000;+ subject.sessionStarted({ sessionId: "ses_quit_new_001", root, engine: engine().reader });+ subject.sessionStarted({ sessionId: "ses_quit_child_1", root, engine: engine({ parentID: "ses_quit_new_001" }).reader });+ await subject.settled();+ now += 1_000;+ subject.turnCompleted("ses_quit_old_001", messages(1));+ await subject.settled();+ await subject.stop();+ expect(archiver.stops).toEqual([{ finals: ["ses_quit_old_001", "ses_quit_new_001"], budgetMs: 5_000 }]);++ // No budget, consent off, or the account gone (a user sign-out restarts the server): a plain stop.+ const noBudget = turnArchiver();+ const off = lifecycle(noBudget, { quitBudgetMs: 0 });+ off.subject.sessionStarted({ sessionId: "ses_quit_none_01", root, engine: engine().reader });+ await off.subject.settled();+ await off.subject.stop();+ const refused = turnArchiver();+ refused.base = async () => skipped("disabled");+ const consent = lifecycle(refused);+ consent.subject.sessionStarted({ sessionId: "ses_quit_none_02", root, engine: engine().reader });+ await consent.subject.settled();+ await consent.subject.stop();+ const gone = turnArchiver();+ const signedOut = lifecycle(gone);+ signedOut.subject.sessionStarted({ sessionId: "ses_quit_none_03", root, engine: engine().reader });+ await signedOut.subject.settled();+ await signedOut.subject.stop({ finals: false });+ expect([...noBudget.stops, ...refused.stops, ...gone.stops]).toEqual([{}, {}, {}]);+ });++ test("app start: the sessions the archiver names get a final archive, behind every other waiting step", async () => {+ const archiver = turnArchiver();+ const { subject } = lifecycle(archiver);+ const root = await tempDir("root");+ const first = deferred<CaptureResult>();+ archiver.base = (sessionId) => (sessionId === "ses_start_first1" ? first.promise : Promise.resolve(queued("base")));+ // A base is packing when the app-start check comes back.+ subject.sessionStarted({ sessionId: "ses_start_first1", root, engine: engine().reader });+ await sleep(10);+ expect(archiver.captures()).toEqual([`base ses_start_first1 ${root} 0`]);+ archiver.startFinals = ["ses_start_final1", "ses_start_final2"];+ subject.start();+ await sleep(10);+ subject.sessionStarted({ sessionId: "ses_start_next01", root, engine: engine().reader });+ first.resolve(queued("base"));+ await subject.settled();+ expect(archiver.calls.filter((call) => call !== "drain")).toEqual([+ `base ses_start_first1 ${root} 0`,+ `base ses_start_next01 ${root} 0`,+ "final ses_start_final1 app_start",+ "final ses_start_final2 app_start",+ ]);+ });++ test("with the real archiver: after the last turn, the folder is archived when the chat goes quiet, when the app quits and at the next start", 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 id = "ses_final_real_1";++ const first = lifecycle(archiverFor(), { finalIdleMs: 100 });+ first.subject.start();+ first.subject.sessionStarted({ sessionId: id, root, engine: engine({ messages: () => messages(0, true) }).reader });+ await first.subject.settled();+ await writeFile(join(root, "turn.txt"), "turn 1\n");+ first.subject.turnCompleted(id, messages(1));+ await first.subject.settled();+ // The user edits after the turn; the chat stays quiet.+ await writeFile(join(root, "idle.txt"), "after the turn\n");+ await sleep(200);+ await first.subject.settled();+ // More edits, then the app quits.+ await writeFile(join(root, "quit.txt"), "before quitting\n");+ await first.subject.stop();+ // And edits while it is closed.+ await writeFile(join(root, "closed.txt"), "while closed\n");++ const second = lifecycle(archiverFor());+ second.subject.start();+ await second.subject.settled();+ second.subject.sessionStarted({ sessionId: id, root, engine: engine({ messages: () => messages(1, true) }).reader });+ await second.subject.settled();+ await writeFile(join(root, "turn.txt"), "turn 2\n");+ second.subject.turnCompleted(id, messages(2));+ await second.subject.settled();+ await second.subject.stop();++ const objects = server.objects();+ expect(objects.map((object) => [object.request.kind, object.request.sequence, object.request.turn])).toEqual([+ ["base", 0, 0], ["delta", 1, 1], ["delta", 2, 1], ["delta", 3, 1], ["delta", 4, 1], ["delta", 5, 2],+ ]);+ const manifests = await Promise.all(objects.map(async (object) => {+ const members = await openArchive(object.object!);+ return { manifest: manifestOf(members), names: members.slice(1).map((member) => member.name) };+ }));+ expect(manifests.slice(1).map(({ manifest }) => [manifest.trigger, manifest.reason])).toEqual([["turn", undefined], ["final", "idle"], ["final", "app_quit"], ["final", "app_start"], ["turn", undefined]]);+ expect(manifests[2]!.names).toContain("idle.txt");+ expect(manifests[3]!.names).toContain("quit.txt");+ expect(manifests[4]!.names).toContain("closed.txt");+ expect(manifests[5]!.names).toContain("turn.txt");+ expect([...first.logs, ...second.logs].filter((log) => log.level === "warn")).toEqual([]);+ });+});diff --git a/apps/server/src/session-archive/lifecycle.ts b/apps/server/src/session-archive/lifecycle.tsindex 89409a7b..9bede8f6 100644--- a/apps/server/src/session-archive/lifecycle.ts+++ b/apps/server/src/session-archive/lifecycle.ts@@ -4,14 +4,18 @@* run in the background, a bounded number at a time (one by default), and one* session's steps always run in call order. A base can wait for a quiet* period after the last prompt (baseIdleMs), so a burst of chats opened and- * prompted one after another is packed once the burst is over. Nothing here- * throws into the request path; an unexpected failure costs one warn line.+ * prompted one after another is packed once the burst is over. After the+ * last completed turn, a final archive catches what changed since: when the+ * session stays quiet (finalIdleMs), when a turn ends without completing,+ * when the session is deleted, when the app quits (within quitBudgetMs) and,+ * for what that missed, when the app starts again. 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";+import type { CaptureResult, DrainResult, FinalReason, SessionArchiver } from "./index.js";-export type ProjectArchiver = Pick<SessionArchiver, "captureBase" | "captureDelta" | "drain" | "signOut" | "stop">;+export type ProjectArchiver = Pick<SessionArchiver, "captureBase" | "captureDelta" | "captureFinal" | "startFinalCandidates" | "drain" | "signOut" | "stop">;/** Engine reads for one session, resolving to the parsed JSON, or null when it cannot be read. */export type ArchiveEngineReads = {@@ -39,11 +43,23 @@ export type ProjectArchiveLifecycleOptions = {*/baseIdleMs?: number;baseMaxDeferMs?: number;+ /** A session with no prompt for this long after a turn ended gets a final archive (FINAL_IDLE_MS). */+ finalIdleMs?: number;+ /** Shutdown packs the final archives of this app run's sessions for at most this long in all (QUIT_FINAL_BUDGET_MS); 0 packs none. */+ quitBudgetMs?: number;/** Tests. */now?: () => number;};const DEFAULT_CONSENT_RECHECK_MS = 10 * 60_000;+/** The quiet window after a turn: with no new prompt by then, the session gets a final archive. */+export const FINAL_IDLE_MS = 10 * 60_000;+/**+ * What shutdown spends, at most, packing final archives (the desktop app+ * waits for the server to stop before it quits). What does not fit is+ * checked at the next app start.+ */+export const QUIT_FINAL_BUDGET_MS = 5_000;/** OMNIRUSH_ARCHIVE_ENABLED: on unless set to 0, false, no or off. */export function projectArchiveEnabled(env: NodeJS.ProcessEnv = process.env): boolean {@@ -115,6 +131,14 @@ type SessionRecord = {start: { root: string; engine: ArchiveEngineReads } | null;/** A start step is queued or running. */starting: boolean;+ /** The engine reads of the latest prompt: a turn that ends without completing reads its turn count there. */+ engine: ArchiveEngineReads;+ /** When a prompt was last dispatched or a turn last ended (shutdown takes the most recent sessions first). */+ activeAt: number;+ /** The quiet window after the last turn; its end queues the idle final archive. */+ idleTimer: ReturnType<typeof setTimeout> | null;+ /** Cancels the idle final archive while it is queued or packing: a new prompt ends the quiet period. */+ idleFinal: AbortController | null;};export class ProjectArchiveLifecycle {@@ -124,6 +148,8 @@ export class ProjectArchiveLifecycle {private readonly consentRecheckMs: number;private readonly baseIdleMs: number;private readonly baseMaxDeferMs: number;+ private readonly finalIdleMs: number;+ private readonly quitBudgetMs: number;private readonly now: () => number;private readonly enabled: boolean;private signedOut = false;@@ -137,6 +163,8 @@ export class ProjectArchiveLifecycle {private readonly background = new Set<Promise<void>>();private running = 0;private readonly waiting: Array<() => void> = [];+ /** Final archives wait for a slot behind every other step. */+ private readonly waitingLow: Array<() => void> = [];/** When the last prompt was dispatched on any session: bases wait for a quiet period after it. */private lastPromptAt = 0;/** Bases waiting for the quiet period; stop() and signOut() wake them. */@@ -150,6 +178,8 @@ export class ProjectArchiveLifecycle {this.consentRecheckMs = options.consentRecheckMs ?? DEFAULT_CONSENT_RECHECK_MS;this.baseIdleMs = Math.max(0, options.baseIdleMs ?? 0);this.baseMaxDeferMs = Math.max(this.baseIdleMs, options.baseMaxDeferMs ?? this.baseIdleMs * 5);+ this.finalIdleMs = Math.max(0, options.finalIdleMs ?? FINAL_IDLE_MS);+ this.quitBudgetMs = Math.max(0, options.quitBudgetMs ?? QUIT_FINAL_BUDGET_MS);this.now = options.now ?? Date.now;}@@ -163,29 +193,43 @@ export class ProjectArchiveLifecycle {/*** 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.+ * unfinished, and checks the folders of recent sessions once for changes+ * made after their last archive (a final archive the last shutdown did not+ * get to, or edits while the app was closed). 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)));+ if (!this.enabled) {+ this.track(this.archiver.signOut().catch((error: unknown) => this.warn("clear", error)));+ return;+ }+ this.kick();+ this.track(this.archiver.startFinalCandidates().then((sessionIds) => {+ for (const sessionId of sessionIds) this.final(sessionId, "app_start");+ }, (error: unknown) => this.warn("start", 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.+ * already completed; child (sub-agent) sessions are never archived. It+ * also ends the session's quiet period: its idle final archive is off.*/sessionStarted(input: { sessionId: string; root: string; engine: ArchiveEngineReads }): void {+ const known = this.sessions.get(input.sessionId);+ if (known) this.cancelIdleFinal(known);if (!this.active || this.consentOff) return;const promptedAt = this.now();this.lastPromptAt = promptedAt;- const known = this.sessions.get(input.sessionId);+ if (known) {+ known.engine = input.engine;+ known.activeAt = promptedAt;+ }// 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 };+ const record: SessionRecord = known ?? { root: null, start: null, starting: false, engine: input.engine, activeAt: promptedAt, idleTimer: null, idleFinal: null };record.start = { root: input.root, engine: input.engine };record.starting = true;this.sessions.set(input.sessionId, record);@@ -214,16 +258,43 @@ export class ProjectArchiveLifecycle {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);+ await this.captureTurn(sessionId, record, turns);});+ this.armIdleFinal(sessionId, record);}- /** The session was deleted: nothing to capture, the queue keeps uploading. */+ /**+ * The observer stopped following the session's turn without seeing it+ * complete (it gave up after an hour, or failed, such as when the engine+ * went away). The engine's turn count is read again: when it moved, the+ * turn gets its delta as if it had completed; otherwise (or when the+ * engine cannot be read) the folder gets a final archive.+ */+ turnIncomplete(sessionId: string): void {+ const record = this.sessions.get(sessionId);+ if (!this.active || this.consentOff || !record) return;+ this.schedule(sessionId, "turn", async () => {+ if (this.sessions.get(sessionId) !== record) return;+ if (record.start && !(await this.resolve(sessionId, record, null))) return;+ if (!record.root) return;+ const turns = completedTurnCount(await record.engine.messages().catch(() => null));+ await this.captureTurn(sessionId, record, turns, turns === null);+ });+ this.armIdleFinal(sessionId, record);+ }++ /**+ * The session was deleted: a last final archive of its folder (when it+ * has a base and the folder is still there), then it is forgotten; the+ * queue keeps uploading.+ */sessionEnded(sessionId: string): void {+ const record = this.sessions.get(sessionId);+ if (record) this.cancelIdleFinal(record);this.sessions.delete(sessionId);+ // A resolved session without a root is a child, not archivable or stopped. One this app+ // run has not seen may still have a base from an earlier run; the archiver knows.+ if (this.active && !this.consentOff && (!record || record.root || record.start)) this.final(sessionId, "session_deleted");this.kick();}@@ -235,15 +306,25 @@ export class ProjectArchiveLifecycle {async signOut(): Promise<void> {this.signedOut = true;this.wakeSleepers();+ for (const record of this.sessions.values()) this.cancelIdleFinal(record);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> {+ /**+ * Server shutdown: no new steps, and the queue stays on disk for the next+ * start. Unless `finals` is false (the account is gone), the sessions of+ * this app run get a final archive first, the most recent first, within+ * quitBudgetMs in all (what does not fit is checked at the next start).+ */+ async stop(options: { finals?: boolean } = {}): Promise<void> {+ const finals = options.finals !== false && this.active && !this.consentOff && this.quitBudgetMs > 0+ ? [...this.sessions].filter(([, record]) => record.root || record.start).sort(([, left], [, right]) => right.activeAt - left.activeAt).map(([sessionId]) => sessionId)+ : [];this.stopped = true;this.wakeSleepers();- await this.archiver.stop().catch((error: unknown) => this.warn("stop", error));+ for (const record of this.sessions.values()) this.cancelIdleFinal(record);+ await this.archiver.stop(finals.length > 0 ? { finals, budgetMs: this.quitBudgetMs } : {}).catch((error: unknown) => this.warn("stop", error));}/** Resolves once every scheduled step and drain has finished (tests). */@@ -283,6 +364,68 @@ export class ProjectArchiveLifecycle {return true;}+ /**+ * The capture at a turn's end: its delta, numbered with the engine's+ * completed-turn count (null: after the last archived turn). A count that+ * did not move (the prompt was aborted before any answer, or the history+ * was reverted) gets a final archive instead, as does a turn whose count+ * is unknown when `finalWithoutCount`.+ */+ private async captureTurn(sessionId: string, record: SessionRecord, turns: number | null, finalWithoutCount = false): Promise<void> {+ if (!record.root || this.sessions.get(sessionId) !== record || this.consentOff) return;+ let result: CaptureResult | null = null;+ if (!finalWithoutCount) {+ result = await this.archiver.captureDelta(sessionId, record.root, turns);+ if (result.status === "skipped" && result.reason === "stopped") record.root = null;+ this.settle(result);+ }+ if (result && !(result.status === "skipped" && result.reason === "stale_turn")) return;+ if (!record.root || this.consentOff) return;+ const final = await this.archiver.captureFinal(sessionId, "turn_incomplete");+ if (final.status === "skipped" && final.reason === "stopped") record.root = null;+ this.settle(final);+ }++ /**+ * Queues a final archive for the session, behind its earlier steps and+ * behind other sessions' waiting steps. With `record`, only while that+ * record is current and has a root (an idle final); `signal` cancels it.+ */+ private final(sessionId: string, reason: FinalReason, record?: SessionRecord, signal?: AbortSignal): void {+ this.schedule(sessionId, "final", async () => {+ if (signal?.aborted || this.consentOff) return;+ if (record && (this.sessions.get(sessionId) !== record || !record.root)) return;+ const result = await this.archiver.captureFinal(sessionId, reason, signal ? { signal } : {});+ if (record && result.status === "skipped" && result.reason === "stopped") record.root = null;+ this.settle(result);+ }, undefined, true);+ }++ /** A turn ended: the quiet window starts; without a prompt by its end, an idle final archive is queued. At most one per window. */+ private armIdleFinal(sessionId: string, record: SessionRecord): void {+ this.cancelIdleFinal(record);+ record.activeAt = this.now();+ // Known not to be archived (a child, not archivable, stopped): nothing to arm.+ if (!record.root && !record.start) return;+ const timer = setTimeout(() => {+ if (record.idleTimer !== timer) return;+ record.idleTimer = null;+ if (!this.active || this.sessions.get(sessionId) !== record) return;+ const controller = new AbortController();+ record.idleFinal = controller;+ this.final(sessionId, "idle", record, controller.signal);+ }, this.finalIdleMs);+ timer.unref?.();+ record.idleTimer = timer;+ }++ private cancelIdleFinal(record: SessionRecord): void {+ if (record.idleTimer) clearTimeout(record.idleTimer);+ record.idleTimer = null;+ record.idleFinal?.abort();+ record.idleFinal = null;+ }+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;@@ -347,9 +490,10 @@ export class ProjectArchiveLifecycle {/*** Runs `task` after the session's earlier steps and `before` (a wait that- * never rejects), within the concurrency bound; never rejects.+ * never rejects), within the concurrency bound (a `low` step lets every+ * other waiting step go first); never rejects.*/- private schedule(sessionId: string, step: string, task: () => Promise<void>, before?: () => Promise<void>): void {+ private schedule(sessionId: string, step: string, task: () => Promise<void>, before?: () => Promise<void>, low = false): void {const previous = this.tails.get(sessionId) ?? Promise.resolve();const run = previous.then(before).then(() => this.bounded(async () => {if (!this.active) return;@@ -358,21 +502,21 @@ export class ProjectArchiveLifecycle {} catch (error) {this.warn(step, error, sessionId);}- }));+ }, low));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> {+ private async bounded(task: () => Promise<void>, low = false): Promise<void> {if (this.running < this.concurrency) this.running += 1;- else await new Promise<void>((resolvePromise) => this.waiting.push(resolvePromise));+ else await new Promise<void>((resolvePromise) => (low ? this.waitingLow : this.waiting).push(resolvePromise));try {await task();} finally {// The slot passes straight to the next waiter, if any.- const next = this.waiting.shift();+ const next = this.waiting.shift() ?? this.waitingLow.shift();if (next) next();else this.running -= 1;}diff --git a/apps/server/src/session-archive/manifest.test.ts b/apps/server/src/session-archive/manifest.test.tsindex 92aeeadd..77039a94 100644--- a/apps/server/src/session-archive/manifest.test.ts+++ b/apps/server/src/session-archive/manifest.test.ts@@ -152,6 +152,16 @@ describe("scan", () => {const delta = computeArchiveDelta(unchanged.entries.map(archiveEntry), changed.entries);expect(paths(delta.files)).toEqual(["f3.txt"]);});++ test("a scan stops when its signal aborts, reading nothing more", async () => {+ const root = await tempDir("scan-abort");+ for (let index = 0; index < 50; index += 1) await writeFile(join(root, `f${index}.txt`), `content ${index}`);+ const metrics = emptyScanMetrics();+ const aborted = new AbortController();+ aborted.abort(new Error("shutdown budget spent"));+ await expect(scanArchiveTree(root, { signal: aborted.signal, metrics })).rejects.toThrow("shutdown budget spent");+ expect(metrics).toMatchObject({ stats: 0, fileReads: 0 });+ });});describe("delta", () => {@@ -242,6 +252,13 @@ describe("manifest and git block", () => {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"]);+ // A delta says why it was taken: a completed turn, or a final archive and its reason (the turn repeats the parent's).+ const turn = JSON.parse(buildManifestBytes({ ...common, kind: "delta", sequence: 3, parentArchiveId: "0b1f0f7a-6f2e-4c8e-8d8a-3a4d2c9e7b10", trigger: "turn", deleted: [] }).toString("utf8"));+ expect(Object.keys(turn)).toEqual(["schema", "kind", "archive_id", "session_id", "sequence", "turn", "created_at", "parent_archive_id", "trigger", "workspace", "files", "deleted", "excluded"]);+ expect(turn.trigger).toBe("turn");+ const final = JSON.parse(buildManifestBytes({ ...common, kind: "delta", sequence: 4, parentArchiveId: "0b1f0f7a-6f2e-4c8e-8d8a-3a4d2c9e7b10", trigger: "final", reason: "idle", deleted: [] }).toString("utf8"));+ expect(final).toMatchObject({ kind: "delta", sequence: 4, turn: 7, trigger: "final", reason: "idle" });+ expect(Object.keys(final).slice(7, 11)).toEqual(["parent_archive_id", "trigger", "reason", "workspace"]);});test("workspace.git: head, branch, origin without userinfo, dirty; null outside a repository", async () => {diff --git a/apps/server/src/session-archive/manifest.ts b/apps/server/src/session-archive/manifest.tsindex ce6804f2..f764a1f3 100644--- a/apps/server/src/session-archive/manifest.ts+++ b/apps/server/src/session-archive/manifest.ts@@ -35,6 +35,14 @@ 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";+/**+ * Why a delta was taken (manifest.json `trigger`): a completed turn, or a+ * final archive of the folder after the last completed turn, which carries+ * that turn's number again.+ */+export type ArchiveTrigger = "turn" | "final";+/** What prompted a final archive (manifest.json `reason`). */+export type FinalReason = "idle" | "turn_incomplete" | "session_deleted" | "app_quit" | "app_start";export type ArchiveEntryType = "file" | "dir" | "symlink";/** One manifest `files` item (section 5.4). */@@ -94,6 +102,8 @@ export type ArchiveManifest = {turn: number;created_at: string;parent_archive_id: string | null;+ trigger?: ArchiveTrigger;+ reason?: FinalReason;workspace: { label: string; marker: string; git: ArchiveGit | null };files: ArchiveEntry[];deleted?: string[];@@ -319,6 +329,8 @@ export type ScanOptions = {statConcurrency?: number;hashConcurrency?: number;metrics?: ScanMetrics;+ /** Stops the scan between entries: it then rejects with the signal's reason. */+ signal?: AbortSignal;};export type ScanResult = { entries: ScannedEntry[]; excluded: ExcludedCounts };@@ -394,7 +406,7 @@ function statFields(stats: BigIntStats) {}/** 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> {+async function hashFile(absolute: string, size: number, buffer: Buffer, metrics: ScanMetrics, signal?: AbortSignal): Promise<string | null> {let handle: Awaited<ReturnType<typeof open>>;try {handle = await open(absolute, OPEN_ENTRY_FLAGS);@@ -408,6 +420,8 @@ async function hashFile(absolute: string, size: number, buffer: Buffer, metrics:const hash = createHash("sha256");let remaining = size;while (remaining > 0) {+ // A stopped scan does not finish a big file first (the scan rejects right after).+ if (signal?.aborted) return null;const { bytesRead } = await handle.read(buffer, 0, Math.min(buffer.length, remaining), null);if (bytesRead === 0) break;hash.update(buffer.subarray(0, bytesRead));@@ -432,6 +446,7 @@ export async function scanArchiveTree(root: string, options: ScanOptions = {}):const concurrency = options.statConcurrency ?? STAT_CONCURRENCY;const metrics = options.metrics ?? emptyScanMetrics();const cache = options.hashCache;+ const signal = options.signal;const excluded = emptyExcludedCounts();const prunedDirs = await excludedRelativeDirs(root, options.excludedDirs ?? []);const includeCredentials = options.includeCredentialFiles === true;@@ -439,6 +454,7 @@ export async function scanArchiveTree(root: string, options: ScanOptions = {}):const toHash: ScannedEntry[] = [];const inspect = async (relDir: string, absDir: string, name: string, next: Array<{ rel: string; abs: string }>): Promise<void> => {+ signal?.throwIfAborted();const rel = relDir ? [relDir, name].join("/") : name;const abs = join(absDir, name);let stats: BigIntStats;@@ -499,6 +515,7 @@ export async function scanArchiveTree(root: string, options: ScanOptions = {}):while (level.length > 0) {const names: Array<{ relDir: string; absDir: string; name: string }> = [];await forEachBounded(level, concurrency, async (dir) => {+ signal?.throwIfAborted();let raw: Buffer[];try {raw = await readdir(dir.abs, { encoding: "buffer" });@@ -523,9 +540,10 @@ export async function scanArchiveTree(root: string, options: ScanOptions = {}):const unreadable = new Set<ScannedEntry>();const buffers: Buffer[] = [];await forEachBounded(toHash, options.hashConcurrency ?? HASH_CONCURRENCY, async (entry) => {+ signal?.throwIfAborted();const buffer = buffers.pop() ?? Buffer.allocUnsafe(HASH_READ_BYTES);try {- const sha256 = await hashFile(join(root, ...entry.path.split("/")), entry.size, buffer, metrics);+ const sha256 = await hashFile(join(root, ...entry.path.split("/")), entry.size, buffer, metrics, signal);if (sha256 === null) {unreadable.add(entry);cache?.forget(entry.path);@@ -537,6 +555,7 @@ export async function scanArchiveTree(root: string, options: ScanOptions = {}):buffers.push(buffer);}});+ signal?.throwIfAborted();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));@@ -616,6 +635,9 @@ export type ManifestInput = {turn: number;createdAt: Date;parentArchiveId: string | null;+ /** Deltas only: a completed turn, or a final archive (then with its reason). */+ trigger?: ArchiveTrigger;+ reason?: FinalReason;label: string;marker: string;git: ArchiveGit | null;@@ -643,6 +665,8 @@ export function manifestSource(input: ManifestInput): ManifestSource {turn: input.turn,created_at: input.createdAt.toISOString(),parent_archive_id: input.parentArchiveId,+ ...(input.trigger ? { trigger: input.trigger } : {}),+ ...(input.reason ? { reason: input.reason } : {}),workspace: { label: input.label, marker: input.marker, git: input.git },});const deleted = input.kind === "delta" ? `,"deleted":${JSON.stringify(input.deleted ?? [])}` : "";diff --git a/apps/server/src/session-archive/pack.test.ts b/apps/server/src/session-archive/pack.test.tsindex fc6a4845..0ad389aa 100644--- a/apps/server/src/session-archive/pack.test.ts+++ b/apps/server/src/session-archive/pack.test.ts@@ -316,5 +316,10 @@ describe("pax tar writer", () => {}// An existing output file is never overwritten.await expect(writeSealedArchive({ root, manifest, createdAtSeconds: 0, entries }, { publicKey: testKeys.publicKey }, out)).rejects.toThrow();+ // A stopped writer (the shutdown budget spent) rejects instead of finishing.+ const stopped = new AbortController();+ stopped.abort(new Error("shutdown budget spent"));+ const cut = join(await tempDir("pack-sealed-cut"), "archive.orseal");+ await expect(writeSealedArchive({ root, manifest, createdAtSeconds: 0, entries, signal: stopped.signal }, { publicKey: testKeys.publicKey }, cut)).rejects.toThrow("shutdown budget spent");});});diff --git a/apps/server/src/session-archive/pack.ts b/apps/server/src/session-archive/pack.tsindex a2806184..2050a941 100644--- a/apps/server/src/session-archive/pack.ts+++ b/apps/server/src/session-archive/pack.ts@@ -139,6 +139,8 @@ export type PackInput = {createdAtSeconds: number;/** Exactly the manifest's `files`, in the same order. */entries: readonly ScannedEntry[];+ /** Stops the writer between members and output blocks: it then rejects with the signal's reason. */+ signal?: AbortSignal;};export type PackOutcome = { unstable: string[]; tarBytes: number };@@ -176,6 +178,7 @@ class TarWriter {}private async rotate(): Promise<void> {+ this.input.signal?.throwIfAborted();this.tarBytes += this.used;this.block = await this.emit(this.block);this.used = 0;@@ -306,6 +309,7 @@ class TarWriter {await this.smallFile(MANIFEST_MEMBER, input.manifest);let members = 0;for (const entry of input.entries) {+ input.signal?.throwIfAborted();members += 1;if (members % GC_HINT_MEMBERS === 0) hintGarbageCollection();if (entry.type === "dir") {diff --git a/apps/server/src/workspace-collector.server.e2e.test.ts b/apps/server/src/workspace-collector.server.e2e.test.tsindex 30e227b1..eac8add8 100644--- a/apps/server/src/workspace-collector.server.e2e.test.ts+++ b/apps/server/src/workspace-collector.server.e2e.test.ts@@ -113,8 +113,12 @@ function startMockEngine(input: { provider: string; model: string; history?: Engconst prompts: unknown[] = [];const workflowPrompts: unknown[] = [];const received: string[] = [];- /** How long a prompt keeps the root session busy, and the error status its message route answers with (null: none). */- const control: { busyMs: number; rootMessagesStatus: number | null } = { busyMs: 50, rootMessagesStatus: null };+ /**+ * How long a prompt keeps the root session busy, the error status its+ * message route answers with (null: none), and a body the status route+ * answers with instead of JSON (null: none), which makes the observer fail.+ */+ const control: { busyMs: number; rootMessagesStatus: number | null; statusBody: string | null } = { busyMs: 50, rootMessagesStatus: null, statusBody: null };const message = (session: string, id: string, role: "user" | "assistant", text: string): EngineMessage => ({info: {id,@@ -144,6 +148,7 @@ function startMockEngine(input: { provider: string; model: string; history?: Eng// matching, so "/session/ses_root/prompt%5Fasync" is a prompt dispatch.const pathname = decodeURI(url.pathname);if (pathname === "/session/status") {+ if (control.statusBody !== null) return new Response(control.statusBody, { status: 200 });return Response.json({ ...(busy ? { ses_root: { type: "busy" } } : {}), ...(workflowBusy ? { ses_workflow: { type: "busy" } } : {}) });}if (["/permission", "/question"].includes(pathname)) return Response.json([]);@@ -892,6 +897,26 @@ describe("project archive wiring", () => {expect(archive.calls.filter((call) => call.path === "archives/key")).toHaveLength(1);}, 60_000);+ test("a turn the observer stops following (it failed) still gets its delta, numbered from the engine", async () => {+ const { root, engine, archive, gateway, omnirush } = await archivedServer();+ expect((await prompt(omnirush.base)).status).toBe(204);+ await waitFor(() => (traces(gateway.uploads).length >= 1 ? true : undefined));+ await waitFor(() => (archive.objects().length >= 1 ? true : undefined));+ // The status route stops answering JSON: the observer fails before it sees the turn settle.+ engine.control.statusBody = "not json";+ await writeFile(join(root, "feature.txt"), "new work\n");+ expect((await prompt(omnirush.base)).status).toBe(204);+ const objects = await waitFor(() => (archive.objects().some((object) => object.request.turn === 2) ? archive.objects() : undefined));+ const failed = await waitFor(() => traces(gateway.uploads).find((envelope) => events(envelope).some((event) => event.type === "session.observer_failed")));+ await omnirush.stop();++ expect(events(failed).some((event) => event.type === "session.observer_failed")).toBe(true);+ expect(objects.map((object) => [object.request.kind, object.request.turn])).toEqual([["base", 1], ["delta", 2]]);+ const members = await openArchive(objects[1]!.object!);+ expect(manifestOf(members)).toMatchObject({ kind: "delta", turn: 2, trigger: "turn" });+ expect(members.map((member) => member.name)).toContain("feature.txt");+ }, 60_000);+test("a chat whose history is past the 8 MiB read cap keeps each turn's transcript, turn snapshot and archive delta, and gets its base; a turn whose messages cannot be read keeps its snapshot and delta", async () => {const message = (id: string, role: "user" | "assistant", part: Record<string, unknown>): EngineMessage => ({info: { id, sessionID: "ses_root", role, time: role === "assistant" ? { created: 1, completed: 2 } : { created: 1 } },diff --git a/docs/project-archive.md b/docs/project-archive.mdindex 2b24782a..2bf24fd9 100644--- a/docs/project-archive.md+++ b/docs/project-archive.md@@ -1,10 +1,12 @@# Project archiveWhen a chat runs in a folder that is a git project, OmniRush.ai keeps 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, the size limits,-and how to opt out.+encrypted copy of the whole project folder on omnirush.ai: when the chat+starts, after every completed turn, and once more when the chat goes quiet,+is deleted, or the app quits. With that copy, the project can be restored+as it was after any turn of the chat, and as it was left at the end. This+page describes what the desktop app uploads, when it uploads it, the size+limits, and how to opt out.The project archive is separate from the workspace collector described in[workspace-collector-privacy.md](workspace-collector-privacy.md). The@@ -55,9 +57,29 @@ archived.- **After each turn that changed something:** only the files that wereadded or changed, plus the list of deleted paths. A turn that changednothing uploads nothing.+- **Once more after the last turn (a final copy):** the files added,+ changed or deleted since the previous upload, in the same form, when the+ folder changed after the chat's last completed turn, for example because+ you edited files yourself, or a turn was stopped or failed before it+ finished. The app looks for such changes:+ - when the chat has had no new message for 10 minutes after a turn (a+ new message before then cancels it);+ - when a turn ends without completing (the app stops following it after+ an hour, or loses track of it);+ - when you delete the chat in the app, if its folder still exists;+ - when you quit the app. The app spends at most about 5 seconds on this+ while it shuts down; the copy is uploaded the next time the app runs;+ - when the app starts again, for chats archived in the last 7 days:+ anything the last shutdown did not get to, and changes made while the+ app was closed (for the most recent chat on each folder).++ A folder that did not change uploads nothing. A final copy is only taken+ for a chat that already has its full copy, and only while the folder is+ still one that qualifies (see [When it runs](#when-it-runs)).Each upload records the chat and its turn number, so the folder can be-rebuilt as it was after any turn.+rebuilt as it was after any turn. A final copy carries the number of the+last completed turn again and is marked as final, with what prompted it.## Size limits@@ -110,7 +132,9 @@ The app never makes a chat wait for the archive. Archives are packed anduploaded in the background, one at a time, on a separate thread, soswitching between chats stays responsive while an archive is packed. 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+interrupted resumes from where it stopped the next time the app runs. When+the app quits, uploads in progress stop at once; the final copies packed+while it shuts down are uploaded the next time it runs. Anarchive that still has not been uploaded after 7 days is deleted, andarchiving stops for that chat. The next chat starts over with a new fullcopy. Archive problems are written to the app's log. They never show up