A desktop coding agent with free access to frontier models.
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 nextcaptureDeltacaptures the base instead.stale_turn:turnis not greater than the last archived turn. A turn delta must move the turn on (the server answersarchive_parent_mismatchto 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): thesignalaborted 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 onewarnline and never reaches the request. - A base waits for a quiet moment. The server passes
baseIdleMs2 s andbaseMaxDeferMs10 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, andstop()orsignOut()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 aparentIDis 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 onewarn, withretryInMswhen 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/messageor the v2/api/session/:id/contextlist. 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 asstale_turnand the changes go into the first delta whose count is higher again. - Real path. The root is
realpathed beforecaptureBase, 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
disabledcapture result, or a drain that reportsdisabled, 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/keyagain. No log line: the archiver logs the oneinfo. - Signed out stays out. After
signOut()orstop(), 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, assessionEndedclears 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, defaultFINAL_IDLE_MS, 10 minutes), a turn that ends without completing, a deleted session, shutdown (quitBudgetMs, defaultQUIT_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:sequenceis the parent's plus one,parent_archive_idthe previous archive, andturnequal 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 sealedmanifest.jsontells them apart: every delta carries"trigger": "turn"or"trigger": "final", and a final archive its"reason":idle,turn_incomplete,session_deleted,app_quitorapp_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 withinfinalIdleMs(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'sturnCompleteddoes, 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 areapp_quit). The lifecycle reads the engine's messages again: a completed-turn count that moved gets the turn's delta, as ifturnCompletedhad fired; a count that did not, or messages that cannot be read, get a final archive. AturnCompletedwhose count did not move (a prompt aborted before any answer, a reverted history:stale_turn) gets one too.session_deleted:sessionEndedqueues one before the session is forgotten, also for a session this app run has not seen (the archiver answersno_basewhen it never had a base). The session's record is markedended.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, toSessionArchiver.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()asksstartFinalCandidates()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_duein 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 (captureBaseon 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_atin its record. A final archive, a rewind and other record updates moveupdated_atbut 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 itsupdated_at(its last archive), and keeps that time from then on.
- Guards.
captureFinalneeds a base (no_baseotherwise, 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_mismatchto 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 (rewindin the session record, with that archive's baseline, whichstart()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 laterarchive_parent_mismatchends 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());
rootis the folder the agent started in (input.workspace.path), as a real path: the gatelstats it and refuses a symlinked root. The home directory, a filesystem root and the app's own directories are always refused.completedTurnsis 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 fewlstatcalls: 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 fetchesGET /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
Setof session ids already handed tocaptureBase.startSessionruns on every prompt dispatch, and eachcaptureBasecall 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());
completedTurnsmust strictly increase per session, across app restarts too. A turn delta needsturn > 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 asstale_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.jsonright 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) andfinal(with its reason). - Start gate.
server.tsawaitsCaptureService.archiveStartGatebefore a prompt dispatch reaches the engine: the lifecycle'sstartGateasksSessionArchiver.startManifestfor a stat-and-hash scan of the folder (the root's hash cache: an unchanged tree reads no file), at mostSTART_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 inunstable.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'stoolStartedat the session's first tool part (v1message.part.updated, v2session.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,targetleft out with reasonregenerable); every repository's.gitbyte for byte, its config files (git-scrub.ts) without credentials in the ARCHIVED copy only (URL userinfo,extraheader,[credential], secret keys; the entry saysscrubbed: true); symlinks with their target andbroken: truewhen it is missing; modes; every lockfile (findLockfiles); touched gitignored files, also in regenerable folders, up to 1 GiB (over it: path, size and hash inexcluded); 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,abovewith 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_TREEand friends, and accept the session's own repository when another user owns it (safe.directoryfor 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 asdisableduntil a latercaptureBasefinds 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
warnline; the code isarchive_marker_not_allowedwhen the server says so, elsearchive_request_invalid). A 7-day-old job does the same. The next session starts over with a new base. The exception isarchive_parent_mismatchon 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
captureDeltapacks 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_KEYSwhile archives sealed to it are still queued.
- on a base, the job is dropped and the session goes back to base-pending: the next
- All folders (4.4). GET /archives/key also carries
policy.all_folders(off unless it is the booleantrue;policy.ts). The backend answers it per user: true only whileOMNIRUSH_ARCHIVE_ALL_FOLDERSis 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.gitentry at all is archived too, with marker and reasonfolder: the same whole-folder base and deltas, credential filter, pruning, consent and sign-out, andworkspace.gitis alwaysnull(no git block, even when the folder sits inside a larger repository).folderDetectorruns 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; anAppDataorLibrary/Application Supportfolder anywhere; and, in home and in the account folders beside it, every folder whose name starts with.,Libraryon macOS andsnapon 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~/.awswould 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,RecoveryandPerfLogson any drive; with anything inside them.
- The policy probe. Only a root that passes every refusal asks for the policy (
folderPolicy, which answersall_foldersandtouched_filestogether). The answer is kept in memory with the key forPOLICY_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 refusesfolderarchives from a user whose policy is off (422 archive_marker_not_allowed), which stops such a session.
- Refusals (
- Touched files. GET /archives/key also carries
policy.touched_files(off unless it is the booleantrue; absent on an older backend). Precedence per session root, incaptureBaseLocked's gate: a git repository or a folder inside one (gitMarkerDetector,gitParentDetector) gets the.gitarchive exactly as before; else, withall_folderson, the whole-folderfolderarchive; else, withtouched_fileson and the root passing every folder refusal above, atouchedchain; 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;workspaceRelativePathdrops 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).TouchedPathStorekeeps them per session: in memory until the gate has run (a refused session drops them), then appended toomnirush-archive/touched/<session key>.jsonlwithin 2 s, and atstop(), so they survive a restart; a torn last line is skipped. At mostMAX_TOUCHED_PATHS(100,000) per session, onewarnpast 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).
captureBaseat session start only registers the session (unchanged, withturn_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 updatesturn_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, orturn_seenfor a final archive) comes with the first capture that finds a touched file; before that a capture isunchanged. The lifecycle asks for that captureTOUCHED_BASE_DELAY_MS(30 s) after the session's first touched path in an app run (a final archive with reasonfirst_touch, only whiletouchedBaseDue), 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.
scanTouchedFileslooks 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 withlstat, 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, unlessarchiveIncludeCredentialFiles), app state dirs under the root,__omnirush__at the root, special files, unreadable files, lone-surrogate names. A file is hashed from the very filelstated (samest_devandst_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.gitisnull. - Manifest.
"scope": "touched"in the sealedmanifest.jsonof every archive of the chain;fileslists 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, indeleted, 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_filesoff or absent nothing is written for such a folder:captureBaseisnot_archivableafter 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 atouchedcreate from a user whose policy is off with422 archive_marker_not_allowed: the drain drops the session's chain (its jobs, the session stopped, onewarnline, no retry) and keeps the policy as off fortoucheduntil it is asked again (POLICY_TTL_MS), so no other chain starts meanwhile. The same holds forfolder.
- 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 (
- Project folders (4.6). GET /archives/key also carries
policy.project_folders(off unless the booleantrue; absent on an older backend). With it on, a root with no.gitthat passes every folder refusal and looks like a project (looksLikeProject: a manifest or lockfile such aspackage.json,pyproject.toml,requirements*.txt,Cargo.toml,go.mod,pom.xml,build.gradle*,Gemfile,composer.json,*.csproj,CMakeLists.txtor aMakefilein it or up to two levels below, or asrc/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 markerproject, like a plain folder under all folders: regenerable folders left out (regenerable), credentials filtered, gitignore applied,workspace.gitnull. Precedence: git, thenfolder, thenproject, thentouched. 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.jsonexcluded(listNotArchived, at capture time, never in the start gate):not_archived_touched_scopewithsizeandsha256up 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 mostMAX_EXCLUDED_LISTED(50,000) entries;excluded_truncated_countcounts 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.
- Touched-scope listing. A v2 touched-files chain lists every file of the folder it does not hold in
- 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 (
findLockfilesintouched.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/inRegenerableDirinsession-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 secondscanTouchedFilespass (includeIgnored: true); a touched-files chain scans its touched paths and every lockfile withincludeIgnored: 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
.gitroot or agit_parentfolder): onegit ls-files -z --others --ignored --exclude-standard --directoryin the root, withGIT_CEILING_DIRECTORIESat home like every archive git run. An ignored directory comes back as onedir/line and pass 1 leaves it out beforelstating it, sonode_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-addeddist/vendor.jsstays). 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 asGIT_DIR(git init --bare --template=in a freshmkdtempdir, removed when the scan is done) and the root asGIT_WORK_TREE, so the folder's.gitignorefiles apply as git would apply them (node_modules/at any depth, negations, nested.gitignorefiles). 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.gitthere 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 thanMAX_IGNORED_PATHS, 2M, ignored paths): the.gitignorefiles, applied with the session uploader's walkFallback rules (scopedIgnoreRules,ignoredByRules; a directory also matches asdir/, sodist/prunesdist). - Never ignored:
.gititself and everything in it (it is not gitignored and keeps the history), and every.gitignorefile. - Touched files.
scanTouchedFilesasksgit check-ignore -z --stdinabout 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.gitignorerules. 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
excludedobject keeps its six counters (section 5.6); the number of ignored entries left out (an ignored directory counts once) is inScanResult.ignored/TouchedScanResult.ignoredand thegitignoredfield 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.
- A root in a repository (a
- 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 itlstats 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 bynpm linkor a tool), nothing below it is read. Each file is opened withO_NOFOLLOW | O_NONBLOCK | O_NOCTTY, so a FIFO swapped in never blocks the capture. The handle'sfstatmust show a regular file with thest_devandst_inothat pass 1lstated, which catches a swap made after the directory check. Otherwise the member is zero-filled at its manifest size and listed inunstable.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_sha256byte for byte through the test-onlytestOnlyFixedSecretsinjection, whether sealed whole or streamed; - every negative vector fails with its exact
expect_error; - a multi-MiB streamed round trip.
- every positive vector reproduces
pack.test.ts:- round trips through the system
tarand Pythontarfilein 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.jsonmember 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
writeSealedArchiveround trip checked with thezstdCLI, and a stopped writer rejecting.
- round trips through the system
manifest.test.ts: UTF-8 byte order; the credential filter; the exclusions (credential, FIFO, app state,__omnirush__, unreadable, non-UTF-8) with gitignorednode_modules/,.venv/anddist/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 themlstated); a folder in no repository with nested.gitignorefiles 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;.gitchanges; manifest JSON, with a delta'striggerand a final archive'sreason; the git block and itspath;git statusnever rewriting.git/index.touched.test.ts:scanTouchedFilesskipping touched files git ignores (root and nested.gitignore, an ignored folder, a nested repository) and a delta deleting a file that became ignored;scanTouchedFileswith 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.gitdir; a gitfile; no.git; an invalid gitfile; a.gitsymlink; home,/and app dirs refused;root_not_directory; detector plug-ins;git_parent(nearest parent wins, a.gitfolder withoutHEADthere qualifies nothing, root.gitpreferred, dotfiles home, system dirs, posix andpath.win32walks 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: trueandtouched_files: trueturn them on, each on its own, and the key works either way; 422 archive_marker_not_allowedfor atouchedorfoldercreate stops the session with that code; any other 422 isarchive_request_invalid;- the policy probe: one attempt with no backoff and no refresh for 502, 500, 503, 429, 401 and a network error;
refresh: falsethrough the request hook; - a 401 with a refresh, and a failed refresh;
- NoSuchUpload leading to a re-create;
archive_not_uploadingat 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'sarchiveRequestinto<state dir>/omnirush-archive/;OMNIRUSH_ARCHIVE_ENABLED=0and 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 reachesonPathTouched(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 getsturnIncomplete(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, thenturnCompletedorturnIncompleteonce per turn, including a turn after a completed one that fails, and nothing more at a server stop.../omnirush-gateway-broker.test.ts:archiveRequestURL, 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 (nosession.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, gitignorednode_modules/anddist/absent (also when a turn rebuilds them),.envandid_rsaabsent unlessarchiveIncludeCredentialFiles; the base then a delta, each decrypted and checked; - no delta when nothing changed,
stale_turnandexists; - 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.gitignoreapplied (node_modules/,dist/,*.blend1absent), 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,AppDataand asecretsfolder 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 forPOLICY_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 withworkspace.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 ofstop()(the job kept, resumed by the next start); - the app's state dir under the root pruned;
- touched files (
touched_fileson): 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_folderswinning overtouched_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_alloweddropping 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,
triggerandreasonin 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.
- the whole folder: