Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
66.2 KB
Raw Blame

session-archive

The desktop side of the OmniRush project archive. When the folder an agent session started in contains .git, the whole folder is uploaded (with the all-folders policy on, any other folder too, see "All folders" below; with the touched-files policy on, any other folder gets only the files the agent touched there, see "Touched files" below):

  • at session start: a base archive, including .git/ and without anything git ignores (see "Gitignored content" below);
  • after every completed turn that changed anything: a delta archive with the 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 the omnirush.ai archive key. It is queued durably under the session uploader state dir and uploaded straight to S3 through presigned multipart URLs.

The normative specification is docs/omnirush-project-archive.md in the backend repository (subscription-manager). Section numbers below refer to it. The shared seal vectors are in __fixtures__/orseal_vectors.json, identical in both repositories.

Status: wired. The embedded server drives it through lifecycle.ts (ProjectArchiveLifecycle), built by ../project-archive.ts (createProjectArchive). See "Wiring" below for the hooks in server.ts. The user-facing description is docs/project-archive.md.

Files

File Responsibility
detect.ts isArchivableProject(root, detectors?, options?), gitMarkerDetector and gitParentDetector (section 4). A pluggable gate; the .git marker, in the root or (git_parent) in the nearest parent (a .git folder there must hold HEAD), never at any account's home on any volume or share, a filesystem, drive, share or mount root, or in a system or app directory (on a UNC share such as \\wsl$\<distro>, also usr, etc, var, opt and root). A git_parent root is archived alone, without the parent's .git. folderDetector / folderRootRefusal / refusedFolderRoot for the all-folders and touched-files policies (4.4): markers folder and touched
policy.ts parseArchivePolicy: policy.all_folders and policy.touched_files from the GET /archives/key body; anything but true is off
touched.ts Touched-files mode: TouchedPathStore (each session's touched paths, appended to touched/<session>.jsonl), scanTouchedFiles (pass 1 over those paths only: lstat from the root, never through a link out of it, a touched folder never expanded) and touchedChange (the delta and the next baseline)
ignore.ts Gitignored content: ArchiveIgnore (the scan's per-folder ignore scopes: git ls-files --others --ignored --exclude-standard --directory in the root's repository, in a nested repository, or with a private empty GIT_DIR for a folder in none; the session uploader's walkFallback .gitignore rules without git) and touchedIgnoredPaths (git check-ignore over touched files only)
manifest.ts Scan with the exclusions and credential filter (5.2, 5.3; reuses the session uploader's isUploadPathDenied, stripRemoteUserinfo and clampUploadBytes), streaming SHA-256 with the (path, size, mtimeNs, ctimeNs, ino) hash cache, delta computation (5.8), manifest.json (5.6) and the git block (path from git rev-parse --show-prefix; git runs with GIT_CEILING_DIRECTORIES set to the real home so it never climbs into home)
pack.ts Streaming pax tar writer (5.5) with unstable-entry detection (5.9), and the file -> tar -> zstd -> ORSEAL01 -> temp file pipeline (5.10, 13.1)
seal.ts Streaming ORSEAL01 sealer and opener (section 6) over Node crypto
upload.ts Multipart upload client over an injectable fetch (sections 7 and 13.5)
files.ts Atomic state-file writes and the GC hint
index.ts SessionArchiver: durable queue, crash recovery, drain
lifecycle.ts ProjectArchiveLifecycle: when the server calls the archiver (session start, turn end, 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)
files-used-policy.ts Files used (backend spec 19.7): the files_used item and its reasons, the caps (64 MiB per file, 256 MiB per chat), classifyUse (scope, and whether the bytes are archived from the scan, staged, or held), the home config allowlist and scrubHomeConfig. Pure; byte-identical to the CLI's
files-used-shell.ts Files used: the files a shell command reads, writes or runs, from its text alone. Pure; byte-identical to the CLI's
deps.ts Files used: the resolved versions of each subproject from its lockfile (the state's dependencies). Pure; byte-identical to the CLI's
files-used.ts Files used, the app side: FilesUsedStore (staged copies and the items waiting for the next state), FilesUsedTracker (the end of each tool call keeps its temp files and scrubbed home config; the end of each turn lists every file its calls used, plus the end-of-turn snapshot of files changed during the turn, and reports the project and outside ones as touched), collectDependencyProjects, watchToolCallEnds. Only the agent's own tool calls are read: no hooks, no file watchers
fake-archive-server.ts, test-helpers.ts Test support only

API

import { SessionArchiver } from "./session-archive/index.js";

const archiver = new SessionArchiver({
  stateDir,                          // the session uploader state dir; files go to <stateDir>/omnirush-archive/
  request,                           // authenticated API calls (see "Authentication" below), or:
  gatewayUrl, accessToken,           //   the gateway URL plus a bearer,
  refreshAccessToken,                //   and the session uploader's refresh hook
  excludedDirs,                      // app data/temp dirs to prune when they sit under a project root
  archiveIncludeCredentialFiles,     // default false
  log,
});

await archiver.start();                                   // crash recovery; idempotent
await archiver.captureBase(sessionId, root, turn?);       // -> CaptureResult
await archiver.captureDelta(sessionId, root, turn);       // -> CaptureResult
await archiver.captureFinal(sessionId, reason, {signal}); // -> CaptureResult (a final archive)
await archiver.startFinalCandidates();                    // -> session ids to check at app start
archiver.recordTouched(sessionId, path);                  // a path the session touched (touched-files mode)
archiver.forgetTouched(sessionId);                        // drop them (a child session)
await archiver.drain();                                   // -> DrainResult
await archiver.signOut();                                 // drop everything
await archiver.stop({finals?, budgetMs?});                // shutdown, final archives first
archiver.setAccessToken(token);                           // token rotation (gatewayUrl mode only)
await archiver.pendingStatus();                           // { jobs, bytes, disabled }

No method throws. Failures are logged (never with presigned URLs or tokens) and reported in the result.

CaptureResult is {status: "queued", archiveId, kind, sequence, size} or {status: "skipped", reason}. The reasons of section 13.2 are not_archivable, disabled, exists, no_base, unchanged and stopped (unchanged is also a touched-files session registered, or captured, with no touched file yet: no base). 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. 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 refresh, or 403). disabled means a 428 or 503 archive_disabled turned archiving off.

Wiring

As implemented

../project-archive.ts works out one archiver per server (projectArchiveSettings): the session uploader's state dir (runtimeStorageDir(config)), the gateway broker's archiveRequest and refreshAccessToken (or, without a broker, the session uploader's OMNIRUSH_GATEWAY_URL + OMNIRUSH_ACCESS_TOKEN), and the app's config, data and OpenCode data/cache dirs as excludedDirs. The archiver is wrapped in a ProjectArchiveLifecycle, which is enabled when the session uploader has an account and OMNIRUSH_ARCHIVE_ENABLED is not 0/false/no/off.

The lifecycle, its SessionArchiver and the session uploader run together in ../capture-host.ts, which server.ts starts on a worker thread (../capture-client.ts, ../capture-worker.ts): scanning, hashing, tar, zstd and sealing never run on the server's main event loop, which in the desktop app is the Electron main process. The worker asks the main thread for the broker's archiveRequest and refreshAccessToken and for the S3 part PUTs (external egress goes through the embedding runtime's network stack), each as one message with its body transferred, and cancels them the same way. Where no worker can start (OMNIRUSH_CAPTURE_WORKER=0, or a runtime that cannot load the worker module, such as the single-file CLI binary) the same host runs in-process. server.ts keeps the capture service in captureServicesByServer and calls:

Server hook Lifecycle call
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 session uploader's startSession sessionStarted({sessionId, root: workspace.path, engine}), the engine reads built on the worker from the request's engine target
The session uploader observer starts following a turn (on the worker): the first of an observation, or the next one after a request that came in while a turn settled turnFollowed(sessionId): the session's idle final archive is off until that turn ends
The session uploader observer's turn_completed (on the worker), with the engine messages it just read (null when it could not read them), however long the turn ran turnCompleted(sessionId, messages)
The session uploader observer stops following a turn without seeing it settle: session.observer_timeout (its 24-hour safety bound) or session.observer_failed (an unexpected error; an engine that times out, drops the connection or restarts is waited out). A server stop ends an observation without this call turnIncomplete(sessionId)
The session uploader's onPathTouched (on the worker, in capture-host.ts, so no message crosses to the main thread): a path in the root from a trace event (recordTrace, a child session's messages), a watcher event, the reconcile pass, the end-of-turn artifact scan, or a change capture's scan, before the session uploader's own denylist pathTouched(sessionId, path): passed to SessionArchiver.recordTouched for a session this run started that may be archived (resolved with a root, or not resolved yet); a child session's paths are dropped (forgetTouched)
sessionUploader.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({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 session uploader; 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:

  • Every call returns at once. Engine reads and captures run in the background, one at a time (concurrency, default 1), and each session's steps run in call order, so a turn's delta never overtakes the session's base. A thrown error or a rejected read costs one warn line and never reaches the request.
  • A base waits for a quiet moment. The server passes baseIdleMs 2 s and baseMaxDeferMs 10 s (PROJECT_ARCHIVE_BASE_IDLE_MS, PROJECT_ARCHIVE_BASE_MAX_DEFER_MS): a base is packed once no prompt has been dispatched on any session for 2 s, and at the latest 10 s after its own prompt. Chats opened and prompted one after another are packed once the burst is over, one at a time; a lone chat's base still shows the folder as its first turn began. The wait holds no concurrency slot, and stop() or signOut() ends it without packing. Each session still gets its own base (sequence 0 of its own chain, section 7 of the backend spec); a second chat on the same folder packs from the root's persisted hash cache, so pass 1 of an unchanged tree reads no file (pass 2 streams and hashes the bytes it packs, as section 5.9 requires).
  • Root sessions only. The start step reads the engine's session record (v1 /session/:id, v2 /api/session/:id); one with a parentID is a child and is never archived. An unreadable record, or unreadable messages, leave the session unresolved: its next prompt or its next completed turn reads the engine again, and the start step also runs again on its own after 1, 2, 5 and 10 minutes (UNRESOLVED_RETRY_DELAYS_MS; one retry waits at a time, and each failed read logs one warn, with retryInMs when it armed a retry). A deleted session, a sign-out and a shutdown clear the waiting retry, and a start read that fails after one of them arms none. After an app restart the engine can take a minute to answer, longer than the 20 s read timeout, while the first prompt's turn still runs, possibly for hours; a retry captures the base once the engine answers, or at the latest the turn's end does, with the count from the observer's messages (a no-op, exists, when an earlier run captured it), and the turn's delta follows, so that turn is not lost.
  • Turn numbers from the engine. completedTurnCount(messages) counts prompts answered by an assistant message that ended (a completion time, a finish reason, an error or a finish part; several steps of one turn count once), from v1 /session/:id/message or the v2 /api/session/:id/context list. The 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 realpathed 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; every session's timers (the idle final archive's quiet window, an unresolved start's retry) are cleared, as sessionEnded clears a deleted session's. 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), and so does the observer following the session's next turn (turnFollowed): a prompt sent while the previous turn settled reaches the lifecycle before that turn's turnCompleted does, and the quiet window armed then must not run through the next turn. The observer follows a turn for as long as it runs, so after a turn of several hours the window starts when it ends.
    • turn_incomplete: the observer stopped following a turn (turnIncomplete: past its 24-hour safety bound, or on an unexpected error; never at a server stop, whose final archives are app_quit). 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 active 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), the most recently active one on each other folder (edits while the app was closed), and every touched-files session (its files are its own), also one without a base yet that has touched paths. At most 10, the most recently active first. Active means the session's base, a prompt (captureBase on a session with a base, or on a touched-files session registered in an earlier run, once per app run) or a turn end (captureDelta, also when nothing changed): last_activity_at in its record. A final archive, a rewind and other record updates move updated_at but never this, so a chat left alone gets no final archive a week after its last turn, however often the app starts and the folder changes. A record from before 1.1.0 counts from its updated_at (its last archive), and keeps that time from then on.
  • Guards. captureFinal needs a base (no_base otherwise, also while the base is pending; a touched-files session without one gets its base instead, when it has a touched file), 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 plain folder or touched files: the root checks and the folder refusals, and their policy must be on): 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).
  • Several chats on one folder. Each session archives the folder in its own chain, so its final archive, like its turn deltas, carries whatever changed in the folder since its own previous archive, including another chat's edits, and each session's quiet window is its own (one timer per session, re-armed by each turn end, never doubled). The session uploader's rule for a shared root (a chat without a turn in progress leaves the filesystem changes made during another chat's turn to that turn's snapshots, session-uploader.ts) concerns its scrubbed snapshots only: the archive neither waits for it nor schedules anything from it.
  • A server without final archives. A backend from before 1.1.0 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.

What to call, and when

All calls are fire-and-forget from the request path. A base capture of a big project takes seconds (about 2 s for 500 MiB and 20k files, about 18 s for 200k files), so never await it while a user request is waiting.

Captures for one session are serialized inside the archiver. Captures for different sessions may run concurrently.

1. App start (server startup, next to new SessionUploader(...) in server.ts)

Construct one archiver per server, with the same state dir as the session uploader:

const sessionArchiver = new SessionArchiver({
  stateDir: runtimeStorageDir(config),
  ...(gatewayBroker.enabled ? {
    request: (path, init) => gatewayBroker.archiveRequest(path, init),   // new broker method, see below
    refreshAccessToken: () => gatewayBroker.refreshAccessToken(),
  } : {}),
  excludedDirs: [/* the app's data, cache and temp directories */],
  log: (level, message, attributes) => logger.log(level, message, attributes),
});
void sessionArchiver.start().then(() => sessionArchiver.drain());

start() then drain() resumes uploads left over from the last run. Recovery:

  • tmp/ is emptied;
  • a capture that crashed before its commit is discarded;
  • orphaned sealed files are removed;
  • jobs older than 7 days are dropped (S3's lifecycle rule has aborted their multipart uploads) and their sessions stop;
  • half-uploaded archives continue from the persisted part list.

A job that exhausted its retries waits between drains (1 min, doubling, capped at 1 h). An unref'd timer drains again when the earliest one is due.

2. Session start (where sessionUploader.startSession(sessionId, workspaceId, root) is called)

Call once per root session per app run, the first time a prompt is dispatched for that session id:

void sessionArchiver.captureBase(sessionId, root, completedTurns).then(() => sessionArchiver.drain());
  • root is the folder the agent started in (input.workspace.path), as a real path: the gate lstats it and refuses a symlinked root. The home directory, a filesystem root and the app's own directories are always refused.
  • completedTurns is 0 for a new session. For a resumed session, it is the number of turns the session has already completed.
  • The call is cheap when there is nothing to do. With a base already captured, it only reads the session record and writes the prompt's time into it (the app-start window), with no network. Without .git, it runs a few lstat calls: the root, then its parents up to the nearest .git, home or a guarded directory, and for a folder the all-folders refusals accept it reads the kept policy or sends one quick probe (at most one GET per 5 minutes, see "All folders" below). Otherwise it fetches GET /archives/key, which also checks the archive consent: a 428 means nothing is packed.
  • Child (sub-agent) sessions share the parent's root and must not be archived. Call this for root sessions only.
  • Keep a per-process Set of session ids already handed to captureBase. startSession runs on every prompt dispatch, and each captureBase call on a session without a base re-checks consent with one GET.

3. Turn completed (where sessionUploader.captureSnapshot(sessionId, "turn_completed") is called)

void sessionArchiver.captureDelta(sessionId, root, completedTurns).then(() => sessionArchiver.drain());
  • 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 sessionUploader.finishSession(sessionId) is called)

The session was deleted: a final archive of what changed since its last archive, then kick the queue (as implemented, the lifecycle does both):

void sessionArchiver.captureFinal(sessionId, "session_deleted").then(() => sessionArchiver.drain());

5. Sign-out (the broker's invalidate hook, next to sessionUploader.clearSpool())

await sessionArchiver.signOut();

It first aborts the part PUT in flight (the drain's AbortController cancels the fetch, and no more of the sealed file is read), then, while it still holds the credentials, sends POST /archives/{id}/abort for every upload the queue has started (best effort, 5 s cap; the server's maintenance aborts leftovers after 24 h). Call it before the credentials are dropped. In the broker's invalidate hook the device session is already gone, so the abort cannot be authenticated there; and the desktop's user sign-out clears (revokes) the account before it restarts the server, which then only sees stop() (see step 6). Bytes a part PUT already handed to the operating system before the abort still reach S3; only the abort of the multipart upload discards them. It deletes every queued archive, baseline, hash cache and session record, so nothing is ever uploaded later under another account. After the next sign-in the archiver starts clean. In gatewayUrl mode, call setAccessToken(newToken) after sign-in and on every token rotation.

6. App shutdown (where sessionUploader.stop() is called)

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), 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

Archive routes authenticate like POST /omnirush/collect: a device bearer, the sign-in gate and consent. The gateway broker owns the device session and exposes, next to uploadSession(sessionId, body) and refreshAccessToken():

archiveRequest(path: string, init: { method: "GET" | "POST"; body?: string; signal?: AbortSignal }): Promise<Response>

It sends to <gateway root>/<path> (path is archives/key, archives, archives/<id>/parts, archives/<id>/complete, archives/<id>/abort). The gateway root is the gateway URL with its trailing / and /v1 stripped, exactly as for uploadSession(). The method sets Authorization: Bearer <device token>, plus Content-Type: application/json when there is a body, and runs the same bounded 401 refresh loop as uploadSession(). Any other path answers 404 without a request.

Alternatively, pass gatewayUrl + accessToken and keep them current with setAccessToken.

S3 part PUTs never carry the bearer. They go through fetch (default externalFetch) to the presigned URL exactly as received. The body is the part read into one buffer from the sealed file (1 MiB reads, stopping at an abort), so every runtime sets Content-Length. A file-backed Blob slice is not used: Electron's net.fetch collects a streamed body with one Buffer.concat per 64 KiB chunk before sending it, which for the default 64 MiB part took 2.6 s against 0.1 s for one buffer (measured with Electron 43 against a loopback sink).

Capture v2 (byte-exact project state)

Offered by the server per user (policy.capture_v2 from GET /archives/key; OMNIRUSH_CAPTURE_V2=0/1 overrides it for tests). A chain is v2 from its base on (v2 in its session record). The same modules run in the CLI; both check __fixtures__/capture_v2_vectors.json. The wire format is in the backend's docs/omnirush-project-archive.md ("Capture v2").

  • States. Every v2 archive carries __omnirush__/state.json right after the manifest (schema: omnirush.archive.v2): start (the base), pre_tool (a turn's first tool call, trigger: "pre_tool", the wire turn repeating the parent's like a final archive, only when something changed since the last state), after (a turn's delta) and final (with its reason).
  • Start gate. server.ts awaits CaptureService.archiveStartGate before a prompt dispatch reaches the engine: the lifecycle's startGate asks SessionArchiver.startManifest for a stat-and-hash scan of the folder (the root's hash cache: an unchanged tree reads no file), at most START_GATE_MS (3 s; the main thread gives the worker 1 s more). The base then packs at once (no quiet period) from exactly that scan, and pass 2 checks every file against the hash taken before the prompt, so a file the agent changed meanwhile is listed in unstable.json. start_capture: "complete" | "partial" says whether the scan beat the cap.
  • Tool start. followToolStart (session-upload-observer.ts) listens to the engine's event stream from the prompt on and calls the lifecycle's toolStarted at the session's first tool part (v1 message.part.updated, v2 session.tool.called / session.tool.input.started), once per turn; the capture runs in the background and never holds the tool.
  • What is in it. The whole folder for git roots and, with the all-folders policy, plain folders (regenerable folders such as node_modules, .venv, target left out with reason regenerable); every repository's .git byte for byte, its config files (git-scrub.ts) without credentials in the ARCHIVED copy only (URL userinfo, extraheader, [credential], secret keys; the entry says scrubbed: true); symlinks with their target and broken: true when it is missing; modes; every lockfile (findLockfiles); touched gitignored files, also in regenerable folders, up to 1 GiB (over it: path, size and hash in excluded); binaries the session uploader found (onBinaryFile, never sent as text); prompt attachments (attachments.ts, from the turn's user messages) under __attachments__/<message id>/<n>-<name>.
  • state.json also lists every repository (repos.ts: root, nested, above with its relative path, unborn branches with their staged files; HEAD, branch, remote without userinfo, tracked-file count, dirty and staged files, stash count, or the reason git could not read it), every entry the scan left out with its reason (excluded, at most 20,000), the scrubbed configs and the attachments with their message ids.
  • Git runner. Capture git runs drop inherited GIT_DIR/GIT_WORK_TREE and friends, and accept the session's own repository when another user owns it (safe.directory for that path only, fsmonitor and hooks off): both used to leave the git block empty while the agent's own git commands worked.

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 (one warn line; the code is archive_marker_not_allowed when the server says so, else archive_request_invalid). 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. This only happens if a key is removed from OMNIRUSH_ARCHIVE_PRIVATE_KEYS while archives sealed to it are still queued.
  • All folders (4.4). GET /archives/key also carries policy.all_folders (off unless it is the boolean true; policy.ts). The backend answers it per user: true only while OMNIRUSH_ARCHIVE_ALL_FOLDERS is on and the user's active consent is version 2026-09-24 or later. While it is off, archiving is git only, as before: the git path (gate, key fetch, archives) is unchanged, nothing is written for a folder without .git, and the only addition is the policy probe below. While it is on, a session root with no .git entry at all is archived too, with marker and reason folder: the same whole-folder base and deltas, credential filter, pruning, consent and sign-out, and workspace.git is always null (no git block, even when the folder sits inside a larger repository). folderDetector runs after the other detectors, so git still wins, and git roots get none of the refusals below.
    • Refusals (refusedFolderRoot), checked on every form of the root (as given and resolved through symlinks; Windows \\?\, \\.\ and \\?\UNC\ prefixes and trailing dots and spaces folded; macOS and Windows without case) before the policy is asked:
      • root_too_broad: a disk or share root (/, C:\, \\server\share, /Volumes/<disk>, /mnt/<disk>, /media/<user>/<disk>), the home directory and anything above it, and another account's folder beside home (/Users/<other>, /Users/Shared, /home/<other>, C:\Users\Public) itself;
      • root_app_data: the desktop's userData dir (OMNIRUSH_DESKTOP_USER_DATA_DIR, set by the desktop app) and anything inside or above it; an AppData or Library/Application Support folder anywhere; and, in home and in the account folders beside it, every folder whose name starts with ., Library on macOS and snap on Linux, with anything inside them;
      • root_credentials: a credential store anywhere (.ssh, .aws, .gnupg, .kube, .docker, .azure, .password-store, Keychains, .config/gcloud) and any folder the session uploader's denylist denies as a whole (isUploadDirectoryDenied: keys, secrets, credentials*, .env*, node_modules, .git, key-store suffixes, ...), with anything inside them. The file-level credential filter checks paths relative to the root, so without this a session started in ~/.aws would upload it;
      • root_system, outside home only: /System, /Library, /Applications, /private, /usr, /bin, /sbin, /etc, /var, /opt, /cores, /proc, /sys, /dev, /boot, /lib, /lib64, /run, /root, /snap, /nix; Windows, Windows.old, Program Files, Program Files (x86), ProgramData, $Recycle.Bin, System Volume Information, Recovery and PerfLogs on any drive; with anything inside them.
    • The policy probe. Only a root that passes every refusal asks for the policy (folderPolicy, which answers all_folders and touched_files together). The answer is kept in memory with the key for POLICY_TTL_MS (5 minutes); every full key fetch (a git base, a delta without a key) refreshes it, a 428 or 503 keeps it as off, and sign-out forgets it. Without a kept answer the archiver sends one probe (ArchiveUploader.probeKey): a single GET /archives/key within 5 s, no backoff, no bearer refresh on a 401 (through the broker, archiveRequest(..., { refresh: false })), shared by the sessions that start meanwhile. Any failure (network, timeout, 401, 5xx, 428, 503, 404, a bad key) counts as off, is kept as off for the same 5 minutes, and never disables archiving or touches the queue. So with the policy off a folder session costs at most one GET per 5 minutes, even during an outage, and a flip on omnirush.ai reaches a running app within 5 minutes with no release.
    • Key and consent. A folder base reuses the key from the probe it just made. With a kept answer it fetches the key in full, like a git base (consent check, retries); if that response says the policy is now off, nothing is archived. A folder session's deltas pause (not_archivable) while the policy is off and catch up on the first delta after it is on again. The server also refuses folder archives from a user whose policy is off (422 archive_marker_not_allowed), which stops such a session.
  • Touched files. GET /archives/key also carries policy.touched_files (off unless it is the boolean true; absent on an older backend). Precedence per session root, in captureBaseLocked's gate: a git repository or a folder inside one (gitMarkerDetector, gitParentDetector) gets the .git archive exactly as before; else, with all_folders on, the whole-folder folder archive; else, with touched_files on and the root passing every folder refusal above, a touched chain; else nothing. The same probe, TTL and kept answer serve both flags.
    • The touched set. The session uploader (in the same capture host, on the worker) reports every workspace-relative path a session touches, before its own denylist: tool paths in the trace (path, filePath, ... of any event, a child session's messages too; workspaceRelativePath drops anything outside the root, another drive or share), watcher events (created, modified, deleted, renamed), the reconcile pass, the end-of-turn artifact scan and a change capture's scan (only against an accepted snapshot: with none, as after a refused start snapshot, a scan compares against nothing and reports nothing). TouchedPathStore keeps them per session: in memory until the gate has run (a refused session drops them), then appended to omnirush-archive/touched/<session key>.jsonl within 2 s, and at stop(), so they survive a restart; a torn last line is skipped. At most MAX_TOUCHED_PATHS (100,000) per session, one warn past it. A stopped or deleted session's file goes; start() removes the files of sessions that are stopped, ended or unknown (every archived chain keeps its touched paths across a restart), and sign-out removes them all.
    • Captures. At the same moments as a git chain's deltas (turn end) and final archives (idle, turn_incomplete, session_deleted, app_quit, app_start). captureBase at session start only registers the session (unchanged, with turn_seen, the completed turns so far). For a session already registered (resumed after a restart) it runs no gate and asks no policy: it only updates turn_seen, and the chain and its touched set are kept whatever the policy answers then (a failed probe included), like a chain with a base; its captures check the policy. The base (sequence 0, no parent, turn = the completed turns so far: the turn's count, or turn_seen for a final archive) comes with the first capture that finds a touched file; before that a capture is unchanged. The lifecycle asks for that capture TOUCHED_BASE_DELAY_MS (30 s) after the session's first touched path in an app run (a final archive with reason first_touch, only while touchedBaseDue), so a long first turn, or an app quit before the turn ends, no longer leaves the session without a copy for hours or until the next app start. Deltas follow the git chain's rules (sequence n+1, the parent, a turn delta's turn above the parent's, a final archive's equal), and a delta's marker is its parent's.
    • What is archived. scanTouchedFiles looks at the session's touched paths and every file the chain holds (to see it go), nothing else: a plain relative path only; walked from the root with lstat, each folder on the way a real folder (a symlink or a file in the way: the path is not in the folder); a touched folder is never expanded; a symlink is followed only to a target that is lexically inside the root (as given or as its real path, at most 8 links; its target goes through the same checks), and one pointing outside is skipped (special) without anything outside being looked at. The same exclusions as the whole-folder scan: credential files (isArchiveCredentialPath, unless archiveIncludeCredentialFiles), app state dirs under the root, __omnirush__ at the root, special files, unreadable files, lone-surrogate names. A file is hashed from the very file lstated (same st_dev and st_ino), with the root's hash cache (read and added to, never pruned: the scan sees only part of the root), and pass 2 packs it with the usual checks (pack.ts). Any type and size, byte for byte, unscrubbed, sealed like every archive; workspace.git is null.
    • Manifest. "scope": "touched" in the sealed manifest.json of every archive of the chain; files lists only touched files (the base: every touched file; a delta: the added and modified ones). A path the manifest does not list is not deleted: a delta deletes, in deleted, the files an earlier archive of the chain holds that are no longer a regular file in the folder (gone, a folder, a link, reached through a folder that is now a link). A file that cannot be read for now stays in the baseline as it was.
    • Policy off. With touched_files off or absent nothing is written for such a folder: captureBase is not_archivable after the probe, and no touched path is kept. A touched chain's captures pause (not_archivable) while it is off and catch up once it is on (the touched set is kept). The server refuses a touched create from a user whose policy is off with 422 archive_marker_not_allowed: the drain drops the session's chain (its jobs, the session stopped, one warn line, no retry) and keeps the policy as off for touched until it is asked again (POLICY_TTL_MS), so no other chain starts meanwhile. The same holds for folder.
  • Project folders (4.6). GET /archives/key also carries policy.project_folders (off unless the boolean true; absent on an older backend). With it on, a root with no .git that passes every folder refusal and looks like a project (looksLikeProject: a manifest or lockfile such as package.json, pyproject.toml, requirements*.txt, Cargo.toml, go.mod, pom.xml, build.gradle*, Gemfile, composer.json, *.csproj, CMakeLists.txt or a Makefile in it or up to two levels below, or a src/ folder with a code file; a bounded walk of 600 entries and 40 folders that never follows a link nor enters a hidden, regenerable or denied folder) is archived whole with marker project, like a plain folder under all folders: regenerable folders left out (regenerable), credentials filtered, gitignore applied, workspace.git null. Precedence: git, then folder, then project, then touched. The start manifest prescans a project root before the policy is known (a mismatch drops the prescan as before), and no longer prescans a plain root once the kept policy says neither all folders nor project (touched scope or nothing), so a big non-project folder costs no start scan.
    • Touched-scope listing. A v2 touched-files chain lists every file of the folder it does not hold in state.json excluded (listNotArchived, at capture time, never in the start gate): not_archived_touched_scope with size and sha256 up to 64 MiB (MAX_EXCLUDED_HASH_BYTES; larger: mtime), the whole-folder rules' reasons for the rest. Its hash cache is kept apart (listing), so an unchanged file is read once. The listing holds at most MAX_EXCLUDED_LISTED (50,000) entries; excluded_truncated_count counts the rest.
    • Refused roots in the start upload. The session uploader's start envelope carries workspace.project_archive: {status: "skipped", reason} (projectArchiveSkip: credential_root, root_too_broad, root_app_data, root_system) for a root without git the folder refusals stop, so the export can say why there is no project.
  • Reproducible tasks. Two exceptions to the gitignored rule below, the same as the CLI (2.0.0): every file the agent touched is archived byte for byte, binaries included, even when gitignored, and so is every lockfile (findLockfiles in touched.ts: package-lock.json, pnpm-lock.yaml, Cargo.lock, uv.lock, go.sum, ...; a bounded walk, depth 6, 5,000 folders, 200 files, never into .git/, never through a link). Neither ever comes from a regenerable folder (REGENERABLE_DIR_NAMES / inRegenerableDir in session-uploader.ts: node_modules, .venv, venv, __pycache__, dist, build, target, vendor, ... at any depth) or from .git/. So every archived chain keeps its touched paths (a whole-folder chain too, not only a touched-files one); a whole-folder scan adds the touched paths and lockfiles it left out with a second scanTouchedFiles pass (includeIgnored: true); a touched-files chain scans its touched paths and every lockfile with includeIgnored: true. The session uploader's end-of-turn artifact events also cover gitignored untracked outputs outside the regenerable folders (listIgnoredOutputFiles), and those paths reach the touched set like any other artifact.
  • Gitignored content. Apart from the reproducible-task exceptions above, nothing git ignores is archived: base, delta and final archives, whole-folder and touched-files alike (ignore.ts). It can be rebuilt (node_modules/, dist/, venvs, caches), and it made single projects many gigabytes. Git decides, with all its rules (every .gitignore, .git/info/exclude, core.excludesFile):
    • A root in a repository (a .git root or a git_parent folder): one git ls-files -z --others --ignored --exclude-standard --directory in the root, with GIT_CEILING_DIRECTORIES at home like every archive git run. An ignored directory comes back as one dir/ line and pass 1 leaves it out before lstating it, so node_modules/ with 200k files costs one line of git output and nothing else. Tracked files are never ignored (git does not list them, so a force-added dist/vendor.js stays). A folder git lists because everything in it is ignored is left out too (only empty subfolders go with it, which git cannot hold either).
    • A folder in no repository (all-folders policy, marker folder, or git refusing the root's repository): the same command with a private empty bare repository as GIT_DIR (git init --bare --template= in a fresh mkdtemp dir, removed when the scan is done) and the root as GIT_WORK_TREE, so the folder's .gitignore files apply as git would apply them (node_modules/ at any depth, negations, nested .gitignore files). Nothing is written in the folder.
    • A nested repository (a folder below the root holding .git: a submodule, a cloned dependency): the outer repository's git never looks inside one, so when pass 1 enters it, it asks that repository (ceiling at its parent, so a broken .git there never climbs to the outer one) and uses its answer below it.
    • Without git (missing, a run over IGNORE_GIT_TIMEOUT_MS, 2 min, or more than MAX_IGNORED_PATHS, 2M, ignored paths): the .gitignore files, applied with the session uploader's walkFallback rules (scopedIgnoreRules, ignoredByRules; a directory also matches as dir/, so dist/ prunes dist).
    • Never ignored: .git itself and everything in it (it is not gitignored and keeps the history), and every .gitignore file.
    • Touched files. scanTouchedFiles asks git check-ignore -z --stdin about the touched files it found (in the root's repository, else in the private one with the root as work tree; a batch git refuses is halved until the refused path is alone, and that path is kept), so the folder is never walked; without git, each path's folders are checked against their .gitignore rules. An ignored touched file is skipped and counts as gone, so a delta deletes a copy the chain holds.
    • Deltas. An ignored path is simply not in the scan, so a path that becomes ignored is in the next delta's deleted (with its descendants), and one that stops being ignored is added again; a rename into an ignored folder is a deletion. The hash cache drops ignored paths at the end of the scan.
    • Wire format unchanged. The manifest's excluded object keeps its six counters (section 5.6); the number of ignored entries left out (an ignored directory counts once) is in ScanResult.ignored / TouchedScanResult.ignored and the gitignored field of the "archive queued" log line. The backend's section 5.1 still says gitignored content is included; see the PR for the doc change.
  • Part order. Parts are uploaded one at a time, in order, streamed from the sealed file. The spec allows up to 4 in parallel; that is a possible later optimisation.
  • Pass 2 never reads outside the root. Node has no openat, so pass 2 cannot pin a directory handle. Instead it lstats each directory once, parents first, when the walk enters it. If a directory is no longer a real directory (for example it was swapped for a symlink by npm link or a tool), nothing below it is read. Each file is opened with O_NOFOLLOW | O_NONBLOCK | O_NOCTTY, so a FIFO swapped in never blocks the capture. The handle's fstat must show a regular file with the st_dev and st_ino that pass 1 lstated, which catches a swap made after the directory check. Otherwise the member is zero-filled at its manifest size and listed in unstable.json, and the next delta sends it again. A changed size or mtime on the same inode still copies the bytes (5.9). This adds about 3% to pass 2 on a 56k-entry tree.
  • Memory. Pass 2 streams through a pool of four 1 MiB tar blocks, recycled once zstd has consumed them. The sealer holds one 1 MiB chunk, and the sink awaits each file write. The manifest is serialised on the fly: once to learn its size, once while it is written. Short-lived zstd and AES-GCM output buffers are the remaining churn. An upload holds the part it is sending (the server's part size, 64 MiB by default). In Bun, a full GC is requested every 64 MiB, every 10k files and around each capture (about 2 ms each at these heap sizes); elsewhere this is a no-op.

Measurements (Apple Silicon laptop SSD, Bun 1.4.2)

Workload Wall time Peak RSS growth
pack + seal, 523 MiB synthetic tree (20,459 entries: 320 MiB random .blend-like files, 100 MiB text, 20k small files), sealed to 399 MiB 2.0–2.4 s (pass 1 about 0.5 s, pass 2 about 1.6 s) 116–133 MiB
full captureBase of the same tree (gate, key, git block, pack, seal, state files) 2.1–2.2 s 124–131 MiB
captureDelta right after, nothing changed 0.12 s overall 129–133 MiB
captureBase, 203k entries (node_modules-like, 200k small files) 18–19 s 344–357 MiB
captureDelta, 203k entries, nothing changed (spec target: under 5 s) 1.3–1.6 s —

Memory beyond the bounded stream buffers grows with the entry count: scan entries, the hash cache and the baseline, about 375 bytes per entry live.

Tests

cd apps/server && bun --conditions=development test src/session-archive
  • seal.test.ts:
    • every positive vector reproduces sealed_hex / sealed_sha256 byte for byte through the test-only testOnlyFixedSecrets injection, whether sealed whole or streamed;
    • every negative vector fails with its exact expect_error;
    • a multi-MiB streamed round trip.
  • pack.test.ts:
    • round trips through the system tar and Python tarfile in stream mode (r|), with long paths, unicode names, long and unicode symlink targets, empty directories and modes;
    • member order and the manifest first;
    • an unstable.json member when files change between the passes;
    • a directory swapped for a symlink to an outside folder, before pass 2 and while pass 2 is inside it: zero-filled, nothing from outside in the tar; a file swapped for a FIFO does not block;
    • pax header edge cases;
    • a multi-MiB writeSealedArchive round trip checked with the zstd CLI, 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) with gitignored node_modules/, .venv/ and dist/ absent; gitignored content: a repository with a nested .gitignore, .git/info/exclude, a negation, an ignored file beside a tracked one, a force-added tracked file in an ignored folder (kept) and a nested repository with its own .gitignore; an ignored folder of 5,000 files pruned (not one of them lstated); a folder in no repository with nested .gitignore files and a negation; git missing (walkFallback rules); deltas when files become ignored, stop being ignored, or move into an ignored folder; 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.
  • touched.test.ts: scanTouchedFiles skipping touched files git ignores (root and nested .gitignore, an ignored folder, a nested repository) and a delta deleting a file that became ignored; scanTouchedFiles with a binary, a PDF, an untouched file, a touched folder (never expanded), a credential file, __omnirush__, an app dir, a symlink inside (followed), links out of the root and a folder linked out of it (skipped; every path the scan looked at is inside the root), a missing file and a FIFO; the hash cache used and kept; plain relative paths only; touchedChange (added, modified, gone, unreadable kept); TouchedPathStore (paths in memory until tracked, the file read back by a new store, a torn line, forget, a session that is something else, clear).
  • 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); the all-folders gate: policy off and on, git first, every refusal on macOS, Linux and Windows paths, credential and app-data folders anywhere and in other accounts, Windows device, long and trailing-dot paths, and credential folders on disk and through a link refused without asking the policy.
  • upload.test.ts (in-process fake API and S3):
    • the happy path;
    • resume after a failed part;
    • a part S3 already holds;
    • an expired URL (403);
    • 428 and 503;
    • the key route's policy: only all_folders: true and touched_files: true turn them on, each on its own, and the key works either way;
    • 422 archive_marker_not_allowed for a touched or folder create stops the session with that code; any other 422 is archive_request_invalid;
    • the policy probe: one attempt with no backoff and no refresh for 502, 500, 503, 429, 401 and a network error; refresh: false through the request hook;
    • a 401 with a refresh, and a failed refresh;
    • NoSuchUpload leading to a re-create;
    • archive_not_uploading at complete;
    • archive_parts_invalid;
    • replay, chain conflicts and an unknown kid;
    • backoff;
    • the broker request hook.
  • lifecycle.test.ts (fake archiver and engine, plus runs on the real archiver): touched paths passed on only for a session this run started that may be archived (not before its prompt, not once it is not archivable, deleted or signed out; a child's dropped); 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; an unreadable start retried after 1, 2, 5 and 10 minutes, one retry at a time, and never once archiving stopped; 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, and so does a turn the observer follows (also when that turn's prompt came before the previous turn's end); a deleted session, a sign-out and a shutdown clearing both the idle final and the start retry, and a start read that fails after them arming no retry; 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; on the worker, a path the session uploader sees the session touch reaches the touched-files archive (registered at session start, the quit's final archive is its base, with that file only).
  • ../session-uploader.test.ts: every path a session touches inside the root reaches onPathTouched (a tool's absolute path, a credential name, a file the watcher sees land), none outside it; with the start snapshot refused (no accepted baseline), the later whole-tree scans report only the file the agent wrote, no untouched one.
  • ../session-upload-observer.test.ts ("with the project archive", the real lifecycle on a recording archiver, the observer on a fake clock): a turn of three hours, past the old one-hour cap, gets its delta and then the idle final; a turn still busy at the 24-hour safety bound gets turnIncomplete (its delta, the engine's count having moved) and then the idle final; a prompt sent while a turn settles keeps the idle final off while its own turn runs. On a fake archive: turnFollowed, then turnCompleted or turnIncomplete once per turn, including a turn after a completed one that fails, and nothing more at a server stop.
  • ../omnirush-gateway-broker.test.ts: archiveRequest URL, bearer, 401 refresh and path allowlist.
  • ../session-uploader.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 status the engine stops answering is waited out (no session.observer_failed) and 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/ present, gitignored node_modules/ and dist/ absent (also when a turn rebuilds them), .env and id_rsa absent unless archiveIncludeCredentialFiles; the base then a delta, each decrypted and checked;
    • no delta when nothing changed, stale_turn and exists;
    • no .git: not archived with the policy off, absent or not a boolean (only the key read); with it on, archived whole with binaries, its .gitignore applied (node_modules/, dist/, *.blend1 absent), credentials left out, then a delta; home, userData and a system dir refused without a request; sessions in ~/.gnupg, ~/.aws/sso/cache, ~/.docker, ~/.ssh, ~/.kube, ~/.config/gh, ~/Library/Keychains, Chrome's profile, AppData and a secrets folder refused without a request; a git project still archived as git; the policy off with the API failing (502, 401, 428, 503, network): one probe per burst, no sleep, no refresh, nothing written or disabled, and the next git session unchanged; the answer kept for POLICY_TTL_MS, turned on and off on the server, deltas pausing and catching up, forgotten at sign-out; a folder inside a larger repository sent with workspace.git: null;
    • consent off at the key route and during a drain;
    • app restart resuming a half-uploaded archive;
    • a crashed commit discarded;
    • a chain conflict and an unknown kid;
    • sign-out, and a slow part PUT aborted within a second of signOut() (the upload aborted with the credentials still held, nothing completed or sent afterwards) and of stop() (the job kept, resumed by the next start);
    • the app's state dir under the root pruned;
    • touched files (touched_files on): only the touched files, byte for byte (a PDF read, a binary written), untouched files, credentials and a link out of the folder never, the base at the first capture with a touched file, a delta with the changed files and the deleted one, nothing when only an untouched file changed; a git folder archived as today with no touched paths kept; all_folders winning over touched_files; the policy off, absent or not a boolean: nothing uploaded or kept; the refused folders never archived; finals (the base from an idle final, app_quit, app_start) and a restart keeping the chain and its touched paths, a session without a base getting it at app start, a deleted session's paths gone; a restart whose key probe fails keeping a chain without a base and its paths, its base catching up with every path once the policy answers; the chain pausing while the policy is off; 422 archive_marker_not_allowed dropping the chain once, with no retry, and no other touched chain starting until the policy is asked again;
    • 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 recently active session per folder; not deleted or older than 7 days); the 7-day window counted from the last base, prompt or turn (an unchanged one too), never extended by a final archive (app starts every 6 days with the folder edited: finals stop a week after the last turn), by a refused final's rewind, or in a record from before 1.1.0; a deleted session whose folder is gone.