@inixiative/archive 0.13.0 → 0.14.0

package/README.md

@@ -33,7 +33,7 @@ archive list
 archive search --query 'migration'
 ```
 
-Use `--source claude-code` for Claude histories. Collection matches the exact working-directory metadata recorded by the provider. Repeat `--project-root` to map several checkouts to one project; `--worktrees` also accepts every current git worktree of each root, re-read on each scan. Nested checkouts are separate mappings. Unknown directories, symlinks and sessions without usable metadata are skipped. Incomplete or changing files remain at source and retry on the next scan. The collector rescans files every 30 seconds; it deduplicates normalized content rather than maintaining byte-offset ingestion cursors. A watching collector waits out a server that is still starting.
+Use `--source claude-code` for Claude histories. Collection matches the exact working-directory metadata recorded by the provider. Repeat `--project-root` to map several checkouts to one project; `--worktrees` also accepts every current git worktree of each root, re-read on each scan. Nested checkouts are separate mappings unless `--subdirectories` lets a root also take the directories below it; the longest matching root wins. `--catch-all` (no roots) takes every session no other collector of that source claims, as projectId `unrouted`; no destination may take `unrouted`, so those sessions never leave the machine. Subdirectory and catch-all matches skip the exclusions: temp directories (test fixtures, agent scratchpads) and `.foundry/decision-receipts` by default, plus each `--exclude` (absolute paths match below them, relative ones match those path segments anywhere); an exact root is explicit and still matches. Unknown directories, symlinks and sessions without usable metadata are skipped. Incomplete or changing files remain at source and retry on the next scan. The collector rescans every 30 seconds. A session whose digest the server already holds is not sent again, and a watching collector does not re-read a file whose size and mtime have not moved since its last outcome (it re-checks a stored session against the server every 10 minutes, so one deleted there is captured again). A session is captured into one project; a collector refuses one another project holds, except one the catch-all holds as `unrouted`, which moves to the project that now claims it. Collectors compete only with collectors over the same history directory. A watching collector waits out a server that is still starting. `serve --sync` backs off failed deliveries: 30 seconds after the first failure, doubling to at most 30 minutes, cleared on delivery. An archive a destination refuses waits alone, and is tried again at once when it has a new revision; a destination that does not answer (or answers 5xx) is skipped for all its archives until it is due.
 
 To run the server without Docker, point `DATABASE_URL` at a Postgres with the `vector` and `pg_trgm` extensions available and run `archive serve [--port 4700] [--sync]`. Set `ARCHIVE_DEBUG=1` to see the underlying error when a command fails.
 
@@ -62,7 +62,7 @@ archive agents install
 archive agents status
 ```
 
-`add-collector` upserts by `--name` (lowercase letters, digits, `.` and `-`); `--directory` defaults to `~/.claude/projects` or `~/.codex/sessions`, and `--project-root`, `--worktrees` and `--atlas` behave as for `collect`. `remove-collector --name N` and `server --url URL` edit the same file. `install` writes one unit per collector, `com.inixiative.archive.collect.<name>`. Each runs the current Bun with this package's own `src/cli.ts`, restarts on exit (30 second throttle), works in the archive home and logs to `logs/<label>.{out,err}.log` there. Re-running `install` reloads only changed or stopped units and removes Archive units no longer declared (including the retired `local` and `sync` units); other launchd agents are untouched. `uninstall` removes every Archive unit; `status` reports each unit's load state, PID and last log entry. Re-run `install` after upgrading the package if its install path changes.
+`add-collector` upserts by `--name` (lowercase letters, digits, `.` and `-`); `--directory` defaults to `~/.claude/projects` or `~/.codex/sessions`, and `--project-root`, `--worktrees`, `--subdirectories`, `--catch-all` and `--atlas` behave as for `collect`. `remove-collector --name N`, `exclude [--exclude PATH ...]` (replaces the extra exclusions) and `server --url URL` edit the same file. `install` writes one unit per collector, `com.inixiative.archive.collect.<name>`, running `collect --agent <name> --watch`: the unit re-reads `agents.json` on every scan and routes each session against every collector of its source, so edits to roots and exclusions apply without a reinstall. Each runs the current Bun with this package's own `src/cli.ts`, restarts on exit (30 second throttle), works in the archive home and logs to `logs/<label>.{out,err}.log` there. Re-running `install` reloads only changed or stopped units and removes Archive units no longer declared. Units are written and loaded one at a time; a unit that fails to load gets its previous file back, so the next `install` loads it again, and `install` reports every failure after trying the rest (including the retired `local` and `sync` units); other launchd agents are untouched. `uninstall` removes every Archive unit; `status` reports each unit's load state, PID and last log entry. Re-run `install` after upgrading the package if its install path changes.
 
 `@inixiative/archive/agents` exports the pure pieces for integrations: `agentsConfigSchema`, `agentUnits`, `renderPlist`, `renderSystemdUnit` and `planAgents`, plus `installAgents`, `uninstallAgents` and `agentStatus` with an injectable command runner and supervisor directory.
 
@@ -128,7 +128,7 @@ The archive owns its tag system. It keeps two different things apart:
 bun run archive tag --id ARCHIVE_ID --tag reviewed --untag debugging
 ```
 
-Tag edits apply to that archive without a new revision, survive re-capture, and do not sync. Offered tags are defined archive-wide or for one actor. Each session can name its **actor**: a `user`, a `service` such as an API-key run, or a `job` (its id is the job name), with the `integrationId` it ran under when there is one. An organization's archive mostly holds its members' work, filterable per person. Entries the model produced record its `model` and `effort` (from Claude Code assistant records and Codex turn context, per turn); listings summarize them per session as `models` and filter by `model` and `effort`.
+Tag edits apply to that archive without a new revision, survive re-capture, and do not sync. Offered tags are defined archive-wide or for one actor. Each session can name its **actor**: a `user`, a `service` such as an API-key run, or a `job` (its id is the job name), with the `integrationId` it ran under when there is one. An organization's archive mostly holds its members' work, filterable per person. Entries the model produced record its `model` and `effort` (from Claude Code assistant records and Codex turn context, per turn); listings summarize them per session as `models` and filter by `model` and `effort`. Each session also records its `runtime`: `provider` (`anthropic` for Claude Code, Codex's `model_provider`) and `accessPath` (`subscription`, `api` or `unknown`), with `evidence` `transcript` when the transcript proves it (a subscription's rate-limit window: Claude Code `quotaLimits`, Codex `rate_limits.plan_type`) or `harness` when the collector read the harness login instead (Claude Code's `oauthAccount` unless its settings supply an API key; Codex `auth.json`). A subagent run is its own session with `lineage`: `kind` (`subagent` or `fork`), `parentSessionId`, and what the harness recorded (`agentType`, `agentName`, `description`, `toolUseId`, `depth`; Claude Code's `agent-<id>.meta.json`, Codex's subagent `session_meta`). Example: `models: [{model: 'claude-opus-5-5', effort: 'medium'}]`, `runtime: {provider: 'anthropic', accessPath: 'subscription', evidence: 'harness'}`.
 
 The **retention** setting (`retentionDays`, off by default) deletes archives whose latest capture is older than that, at server start and hourly. It deletes only from the archive it is set on; deletions never sync.
 
@@ -148,7 +148,7 @@ All data endpoints are `POST /api/v1/archive/<action>` with a JSON body and `Aut
 | `tags/list`, `tags/define`, `tags/remove` | `tag`, `actorId?`, `description?` | offered tags with usage counts |
 | `destinations/list`, `destinations/libraries`, `destinations/connect`, `destinations/remove`, `destinations/routes`, `destinations/sync` | see [Routing](#routing) | routes |
 
-Filters are `projectId`, `source`, `tag`, `actorId`, `model`, `effort` and `reference` (`{integration, ref}`). Jev integration is not enabled. Session content must not be sent to Jev without selecting that service for the relevant ownership boundary.
+Filters are `projectId`, `source`, `tag`, `actorId`, `model`, `effort`, `provider`, `accessPath` and `reference` (`{integration, ref}`); `archive list` and `archive search` take them as flags. Jev integration is not enabled. Session content must not be sent to Jev without selecting that service for the relevant ownership boundary.
 
 ## Limits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/archive",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",

package/prisma/migrations/20261012120000_runtime/migration.sql

@@ -0,0 +1,10 @@
+-- AlterTable
+ALTER TABLE "archives" ADD COLUMN     "accessPath" TEXT,
+ADD COLUMN     "provider" TEXT;
+
+-- CreateIndex
+CREATE INDEX "archives_provider_idx" ON "archives"("provider");
+
+-- CreateIndex
+CREATE INDEX "archives_accessPath_idx" ON "archives"("accessPath");
+

package/prisma/schema.prisma

@@ -28,6 +28,9 @@ model Archive {
   source     String
   projectId  String?
   actorId    String?
+  /// The model provider (anthropic, openai) and the access path (subscription, api, unknown).
+  provider   String?
+  accessPath String?
   capturedAt Float
   summary    Json
 
@@ -38,6 +41,8 @@ model Archive {
 
   @@index([projectId])
   @@index([actorId])
+  @@index([provider])
+  @@index([accessPath])
   @@map("archives")
 }
 

package/src/agents.ts

@@ -17,6 +17,7 @@ import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
+import { type CollectionSource, defaultExclusions, UNROUTED } from './collector';
 
 export const defaultHome = () => join(homedir(), '.local/share/archive');
 export const AGENT_LABEL_PREFIX = 'com.inixiative.archive.';
@@ -25,22 +26,40 @@ export const defaultHistoryDirectory = (source: 'claude-code' | 'codex') =>
   join(homedir(), source === 'codex' ? '.codex/sessions' : '.claude/projects');
 
 const absolute = z.string().max(4096).refine(isAbsolute, 'Path must be absolute');
-export const collectorAgentSchema = z.strictObject({
-  name: z
-    .string()
-    .max(64)
-    .regex(/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/),
-  source: z.enum(['claude-code', 'codex']),
-  directory: absolute,
-  projectId: z.string().min(1).max(256),
-  projectRoots: z.array(absolute).min(1).max(100),
-  worktrees: z.boolean().optional(),
-  atlas: z.boolean().optional(),
-});
+export const collectorAgentSchema = z
+  .strictObject({
+    name: z
+      .string()
+      .max(64)
+      .regex(/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/),
+    source: z.enum(['claude-code', 'codex']),
+    directory: absolute,
+    projectId: z.string().min(1).max(256),
+    projectRoots: z.array(absolute).max(100),
+    worktrees: z.boolean().optional(),
+    subdirectories: z.boolean().optional(),
+    /** Every session no other collector of this source claims; projectId `unrouted`, never synced. */
+    catchAll: z.boolean().optional(),
+    atlas: z.boolean().optional(),
+  })
+  .superRefine((c, ctx) => {
+    if (c.catchAll && (c.projectId !== UNROUTED || c.projectRoots.length))
+      ctx.addIssue({
+        code: 'custom',
+        message: `A catch-all collector has projectId ${UNROUTED} and no roots`,
+      });
+    if (!c.catchAll && (c.projectId === UNROUTED || !c.projectRoots.length))
+      ctx.addIssue({
+        code: 'custom',
+        message: `A collector needs a root and a projectId other than ${UNROUTED}`,
+      });
+  });
 export const agentsConfigSchema = z
   .strictObject({
     /** The Archive server collectors write to; the token is the home's `server.token`. */
     server: z.strictObject({ url: z.url() }).optional(),
+    /** Added to the default exclusions (temp directories, Foundry decision receipts). */
+    exclude: z.array(z.string().min(1).max(4096)).max(100).optional(),
     collectors: z.array(collectorAgentSchema).max(100),
   })
   .refine(
@@ -82,21 +101,36 @@ export interface AgentUnitOptions {
 }
 export const packageCliPath = () => fileURLToPath(new URL('./cli.ts', import.meta.url));
 
-export function collectorArgs(c: CollectorAgent, server?: { url: string }) {
-  return [
-    'collect',
-    ...(server ? ['--url', server.url] : []),
-    '--directory',
-    c.directory,
-    '--source',
-    c.source,
-    ...c.projectRoots.flatMap((root) => ['--project-root', root]),
-    ...(c.worktrees ? ['--worktrees'] : []),
-    ...(c.atlas ? ['--atlas'] : []),
-    '--project-id',
-    c.projectId,
-    '--watch',
-  ];
+/** A unit runs one named collector; it re-reads agents.json each scan, so edits apply live. */
+export function collectorArgs(c: CollectorAgent) {
+  return ['collect', '--agent', c.name, '--watch'];
+}
+
+/** A named collector, the peers it is routed against, its exclusions and server, from agents.json. */
+export function collectorPlan(config: AgentsConfig, name: string) {
+  const collector = config.collectors.find((c) => c.name === name);
+  if (!collector) throw new Error(`No collector named ${name} in agents.json`);
+  const source = (c: CollectorAgent): CollectionSource => ({
+    directory: c.directory,
+    source: c.source,
+    projectRoots: c.projectRoots,
+    projectId: c.projectId,
+    ...(c.worktrees ? { worktrees: true } : {}),
+    ...(c.subdirectories ? { subdirectories: true } : {}),
+    ...(c.catchAll ? { catchAll: true } : {}),
+    ...(c.atlas ? { atlas: true } : {}),
+  });
+  // Collectors over the same history compete for its sessions; another directory is another history.
+  const named = config.collectors.filter(
+    (c) => c.source === collector.source && resolve(c.directory) === resolve(collector.directory),
+  );
+  const peers = named.map(source);
+  return {
+    collector: peers[named.indexOf(collector)]!,
+    peers,
+    exclude: [...defaultExclusions(), ...(config.exclude ?? [])],
+    server: config.server,
+  };
 }
 
 /** One supervised unit per declared agent. */
@@ -114,7 +148,7 @@ export function agentUnits(config: AgentsConfig, options: AgentUnitOptions): Age
       stderr: join(home, 'logs', `${label}.err.log`),
     };
   };
-  return config.collectors.map((c) => unit(`collect.${c.name}`, collectorArgs(c, config.server)));
+  return config.collectors.map((c) => unit(`collect.${c.name}`, collectorArgs(c)));
 }
 
 const xml = (value: string) =>
@@ -310,23 +344,49 @@ export function installAgents(config: AgentsConfig, options: AgentHostOptions =
   }));
   const plan = planAgents(units, installed, h.platform, h.dir);
   h.remove(plan.remove);
-  for (const { file, content } of plan.write) {
+  const previous = new Map(installed.map((i) => [i.label, i.content]));
+  const write = (file: string, content: string) => {
     const temp = `${file}.${randomUUID()}.tmp`;
     writeFileSync(temp, content, { mode: 0o644, flag: 'wx' });
     renameSync(temp, file);
-  }
-  if (h.platform === 'linux' && plan.write.length) h.systemctl('daemon-reload');
+  };
+  const loaded: string[] = [];
+  const failed: { label: string; error: string }[] = [];
+  // Write and load one unit at a time. A unit that fails to load gets its old file back (or none),
+  // so the next install sees it as changed and loads it, instead of trusting a stale running copy.
+  const install = (label: string, content?: string) => {
+    try {
+      if (content !== undefined) {
+        write(h.file(label), content);
+        if (h.platform === 'linux') h.systemctl('daemon-reload');
+      }
+      h.load(label);
+      loaded.push(label);
+    } catch (error) {
+      failed.push({ label, error: error instanceof Error ? error.message : String(error) });
+      if (content === undefined) return;
+      const old = previous.get(label);
+      try {
+        if (old === undefined) rmSync(h.file(label), { force: true });
+        else write(h.file(label), old);
+        if (h.platform === 'linux') h.systemctl('daemon-reload');
+        // Loading stopped the unit that ran before; bring it back as it was.
+        if (old !== undefined) h.load(label);
+      } catch {}
+    }
+  };
+  for (const { label, content } of plan.write) install(label, content);
   // Unchanged units that are not running are loaded again.
-  const reload = [
-    ...plan.write.map((w) => w.label),
-    ...plan.unchanged.filter((label) => !h.loaded(label).loaded),
-  ];
-  for (const label of reload) h.load(label);
+  for (const label of plan.unchanged) if (!h.loaded(label).loaded) install(label);
+  if (failed.length)
+    throw new Error(
+      `Archive agents failed to load: ${failed.map((f) => `${f.label} (${f.error})`).join('; ')}`,
+    );
   return {
     platform: h.platform,
     dir: h.dir,
-    loaded: reload,
-    unchanged: plan.unchanged.filter((l) => !reload.includes(l)),
+    loaded,
+    unchanged: plan.unchanged.filter((l) => !loaded.includes(l)),
     removed: plan.remove,
   };
 }

package/src/cli.ts

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import {
   agentStatus,
+  collectorPlan,
   defaultHistoryDirectory,
   defaultHome,
   installAgents,
@@ -16,8 +17,8 @@ import {
   writeAgents,
 } from './agents';
 import { importChatGPTThread } from './chatgpt';
-import { archiveRequest, searchRemotes, syncArchives } from './client';
-import { collectSessions } from './collector';
+import { archiveRequest, type SyncBackoff, searchRemotes, syncArchives } from './client';
+import { type CollectorCache, collectSessions, defaultExclusions, UNROUTED } from './collector';
 import {
   archiveDestinationSchema,
   connectDestination,
@@ -66,6 +67,14 @@ export async function runCli(args = Bun.argv.slice(2)) {
       query: { type: 'string', default: '' },
       'project-root': { type: 'string', multiple: true },
       worktrees: { type: 'boolean', default: false },
+      subdirectories: { type: 'boolean', default: false },
+      'catch-all': { type: 'boolean', default: false },
+      exclude: { type: 'string', multiple: true },
+      agent: { type: 'string' },
+      provider: { type: 'string' },
+      model: { type: 'string' },
+      effort: { type: 'string' },
+      'access-path': { type: 'string' },
       atlas: { type: 'boolean', default: false },
       tag: { type: 'string', multiple: true },
       untag: { type: 'string', multiple: true },
@@ -91,14 +100,16 @@ export async function runCli(args = Bun.argv.slice(2)) {
         'up | down   (the local Archive: bundled compose.yaml with Postgres, data in --home)\n' +
         'serve [--port 4700 --hostname 127.0.0.1] [--sync]   (DATABASE_URL; token from ARCHIVE_SERVER_TOKEN or --token-file)\n' +
         'import --file PATH --source codex|claude-code|chatgpt --project-id ID [--tag TAG]\n' +
-        'collect --directory HISTORY --source codex|claude-code --project-root EXACT_CWD [--project-root ...] [--worktrees] [--atlas] --project-id ID [--watch]\n' +
-        'list | export --id ID | tag --id ID [--tag TAG ...] [--untag TAG ...] | search --query TEXT [--remote]\n' +
+        'collect --directory HISTORY --source codex|claude-code (--project-root CWD [--project-root ...] --project-id ID [--worktrees] [--subdirectories] | --catch-all) [--exclude PATH ...] [--atlas] [--watch]\n' +
+        'collect --agent NAME [--watch]   (one collector from agents.json, routed against the others, re-read each scan)\n' +
+        'list | search --query TEXT [--remote]   [--project-id ID] [--source S] [--tag T] [--provider P] [--model M] [--effort E] [--access-path subscription|api|unknown]\n' +
+        'export --id ID | tag --id ID [--tag TAG ...] [--untag TAG ...]\n' +
         'pair --kingdom KINGDOM_API_URL [--name NAME] [--yes]   (register this Archive with Kingdom; claim the review code there, then confirm the owner)\n' +
         'connect --url HTTPS_URL --project-id ID (--token-env ENV | --token-file PATH)   (a remote Archive, for serve --sync)\n' +
         'connect --kind kingdom --url KINGDOM_API_URL --credential-file PATH --integration-id UUID --resource-id UUID --project-id ID   (a hosted Archive through Kingdom)\n' +
         'sync | routes   (the server publishes to, or previews, its destinations once)\n' +
-        'agents add-collector --name N --source codex|claude-code --project-id ID --project-root DIR [--project-root ...] [--directory HISTORY] [--worktrees] [--atlas]\n' +
-        'agents remove-collector --name N | server --url URL | install | uninstall | status\n' +
+        'agents add-collector --name N --source codex|claude-code (--project-id ID --project-root DIR [--project-root ...] [--worktrees] [--subdirectories] | --catch-all) [--directory HISTORY] [--atlas]\n' +
+        'agents remove-collector --name N | exclude [--exclude PATH ...] | server --url URL | install | uninstall | status\n' +
         `Data commands talk to the Archive server at --url (default ${DEFAULT_URL}) with the token in --token-file (default <home>/server.token) or ARCHIVE_TOKEN.`,
     );
     return;
@@ -170,10 +181,12 @@ export async function runCli(args = Bun.argv.slice(2)) {
     output({ listening: instance.server.url.href, sync: v.sync });
     let stopped = false;
     // One process owns the database connection: the server and its sync share it.
+    // Failed deliveries back off across cycles instead of being re-sent every 30 seconds.
+    const backoff: SyncBackoff = new Map();
     const sync = (async () => {
       while (v.sync && !stopped) {
         try {
-          const results = await syncArchives(instance.store, readDestinations(config));
+          const results = await syncArchives(instance.store, readDestinations(config), { backoff });
           const failed = results.filter((r) => r.status.startsWith('failed'));
           if (failed.length) console.error(JSON.stringify({ sync: 'failed', archives: failed }));
         } catch {
@@ -258,8 +271,11 @@ export async function runCli(args = Bun.argv.slice(2)) {
     const action = positionals[1];
     const base = { collectors: [], ...current };
     if (action === 'add-collector') {
-      if (!v.name || !v['project-id'] || !v['project-root'] || !v.source)
-        throw new Error('add-collector requires --name, --source, --project-id and --project-root');
+      const catchAll = v['catch-all'];
+      if (!v.name || !v.source || (!catchAll && (!v['project-id'] || !v['project-root'])))
+        throw new Error(
+          'add-collector requires --name, --source, and --project-id with --project-root (or --catch-all)',
+        );
       const source = v.source as 'codex' | 'claude-code';
       output(
         writeAgents(
@@ -268,13 +284,18 @@ export async function runCli(args = Bun.argv.slice(2)) {
             name: v.name,
             source,
             directory: resolve(v.directory ?? defaultHistoryDirectory(source)),
-            projectId: v['project-id'],
-            projectRoots: v['project-root'].map((root) => resolve(root)),
+            projectId: catchAll ? UNROUTED : v['project-id']!,
+            projectRoots: catchAll ? [] : v['project-root']!.map((root) => resolve(root)),
             ...(v.worktrees ? { worktrees: true } : {}),
+            ...(v.subdirectories ? { subdirectories: true } : {}),
+            ...(catchAll ? { catchAll: true } : {}),
             ...(v.atlas ? { atlas: true } : {}),
           }),
         ),
       );
+    } else if (action === 'exclude') {
+      const { exclude: _, ...rest } = base;
+      output(writeAgents(file, { ...rest, ...(v.exclude?.length ? { exclude: v.exclude } : {}) }));
     } else if (action === 'remove-collector') {
       if (!v.name) throw new Error('remove-collector requires --name');
       output(
@@ -313,7 +334,21 @@ export async function runCli(args = Bun.argv.slice(2)) {
   }
   const token = process.env.ARCHIVE_TOKEN ?? readToken();
   if (!token) throw new Error('No Archive token: run `archive init` or set ARCHIVE_TOKEN');
+  const agentsFile = join(home, 'agents.json');
   const archive = new ArchiveClient({ url: v.url ?? DEFAULT_URL, token });
+  if ((command === 'list' || command === 'search') && (v.tag?.length ?? 0) > 1)
+    throw new Error('Filter by one --tag at a time');
+  const filter = {
+    ...(v['project-id'] ? { projectId: v['project-id'] } : {}),
+    ...(v.source ? { source: v.source as 'claude-code' | 'codex' | 'foundry' | 'chatgpt' } : {}),
+    ...(v.tag?.length ? { tag: v.tag[0] } : {}),
+    ...(v.provider ? { provider: v.provider } : {}),
+    ...(v.model ? { model: v.model } : {}),
+    ...(v.effort ? { effort: v.effort } : {}),
+    ...(v['access-path']
+      ? { accessPath: v['access-path'] as 'subscription' | 'api' | 'unknown' }
+      : {}),
+  };
   if (command === 'routes') output(await archive.routes());
   else if (command === 'sync') {
     const results = await archive.sync();
@@ -349,15 +384,48 @@ export async function runCli(args = Bun.argv.slice(2)) {
       entries: snapshot.entries.length,
       coverage: snapshot.coverage,
     });
-  } else if (command === 'list') output(await archive.list());
+  } else if (command === 'list') output(await archive.list(filter));
   else if (command === 'collect') {
-    if (
-      !v.directory ||
-      !v['project-root'] ||
-      !v['project-id'] ||
-      !['codex', 'claude-code'].includes(v.source ?? '')
-    )
-      throw new Error('Collect requires --directory, --source, --project-root and --project-id');
+    const flagged = () => {
+      const catchAll = v['catch-all'];
+      if (
+        !v.directory ||
+        !['codex', 'claude-code'].includes(v.source ?? '') ||
+        (!catchAll && (!v['project-root'] || !v['project-id']))
+      )
+        throw new Error(
+          'Collect requires --agent, or --directory, --source and --project-root with --project-id (or --catch-all)',
+        );
+      const collector = {
+        directory: v.directory,
+        source: v.source as 'codex' | 'claude-code',
+        projectRoots: catchAll ? [] : v['project-root']!,
+        projectId: catchAll ? UNROUTED : v['project-id']!,
+        worktrees: v.worktrees,
+        subdirectories: v.subdirectories,
+        catchAll,
+        atlas: v.atlas,
+        tags: v.tag,
+      };
+      return {
+        collector,
+        peers: [collector],
+        exclude: [...defaultExclusions(), ...(v.exclude ?? [])],
+        server: undefined as { url: string } | undefined,
+      };
+    };
+    // A named collector re-reads agents.json each scan, so its routing follows edits without a restart.
+    const plan = () => {
+      if (!v.agent) return flagged();
+      const config = readAgents(agentsFile);
+      if (!config) throw new Error('No agents.json; declare agents first');
+      return collectorPlan(config, v.agent);
+    };
+    plan();
+    const cache: CollectorCache = new Map();
+    // A named collector writes to the server agents.json declares (unless --url), re-read each scan.
+    let client = archive;
+    let clientUrl = v.url ?? DEFAULT_URL;
     let stopped = false;
     const stop = () => {
       stopped = true;
@@ -365,17 +433,27 @@ export async function runCli(args = Bun.argv.slice(2)) {
     process.once('SIGINT', stop);
     process.once('SIGTERM', stop);
     do {
+      let current: ReturnType<typeof plan>;
+      try {
+        current = plan();
+      } catch (error) {
+        if (!v.watch) throw error;
+        console.error(
+          JSON.stringify({ collect: 'agents.json unusable', error: (error as Error).message }),
+        );
+        for (let i = 0; !stopped && i < 30; i++) await Bun.sleep(1000);
+        continue;
+      }
       try {
-        const result = await collectSessions(archive, {
-          directory: v.directory,
-          source: v.source as 'codex' | 'claude-code',
-          projectRoots: v['project-root'],
-          worktrees: v.worktrees,
-          atlas: v.atlas,
-          projectId: v['project-id'],
-          tags: v.tag,
-        });
-        output(result);
+        const { collector, peers, exclude, server } = current;
+        const url = v.url ?? server?.url ?? DEFAULT_URL;
+        if (url !== clientUrl) {
+          client = new ArchiveClient({ url, token });
+          clientUrl = url;
+        }
+        const started = Date.now();
+        const result = await collectSessions(client, collector, { peers, exclude, cache });
+        output({ ...result, ms: Date.now() - started });
         if (!v.watch && result.failed) process.exitCode = 1;
       } catch (error) {
         // The server may be starting; a watching collector retries.
@@ -390,6 +468,7 @@ export async function runCli(args = Bun.argv.slice(2)) {
   } else if (command === 'search')
     output(
       await archive.search({
+        ...filter,
         query: v.query,
         limit: Number(v.limit) > 100 ? 100 : Number(v.limit),
       }),

package/src/client.ts

@@ -126,28 +126,81 @@ export async function routingPreview(
   }));
 }
 
+/**
+ * Deliveries that failed, and when each may be tried again: per archive and destination, and per
+ * destination while it is unreachable. A retry waits 30 seconds, doubling per failure up to 30
+ * minutes; a new revision of the archive is tried at once.
+ */
+export type SyncBackoff = Map<string, { failures: number; until: number; digest?: string }>;
+const BACKOFF_BASE_MS = 30_000;
+const BACKOFF_MAX_MS = 30 * 60_000;
+/** No HTTP answer, or a 5xx: the destination is down, not refusing this archive. */
+const outage = (message: string) => {
+  const status = Number(/\((\d{3})\)/.exec(message)?.[1]);
+  return !status || status >= 500;
+};
+
 export async function syncArchives(
   store: ArchiveStore,
   destinations: ArchiveDestination[],
+  options: { backoff?: SyncBackoff; now?: () => number } = {},
 ): Promise<SyncResult[]> {
+  const now = options.now ?? Date.now;
+  const backoff = options.backoff;
   const results: SyncResult[] = [];
-  for (const archive of await store.list())
+  const seen = new Set<string>();
+  const delay = (failures: number) =>
+    Math.min(BACKOFF_BASE_MS * 2 ** (failures - 1), BACKOFF_MAX_MS);
+  const archives = await store.list();
+  for (const archive of archives)
     for (const destination of destinations.filter((d) => d.projectId === archive.projectId)) {
+      const identity = destinationIdentity(destination);
+      const key = JSON.stringify([archive.id, identity]);
+      const down = JSON.stringify(['destination', identity]);
+      seen.add(key).add(down);
+      const deferred = (until: number) =>
+        results.push({
+          id: archive.id,
+          destination: destination.url,
+          status: `deferred until ${new Date(until).toISOString()}`,
+        });
+      const circuit = backoff?.get(down);
+      if (circuit && now() < circuit.until) {
+        deferred(circuit.until);
+        continue;
+      }
+      const waiting = backoff?.get(key);
+      if (waiting && now() < waiting.until && waiting.digest === archive.digest) {
+        deferred(waiting.until);
+        continue;
+      }
       try {
         const result = await publishArchive(store, archive.id, destination);
+        backoff?.delete(key);
+        backoff?.delete(down);
         results.push({
           id: archive.id,
           destination: destination.url,
           status: result.unchanged ? 'unchanged' : 'published',
         });
       } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (outage(message)) {
+          const failures = (circuit?.failures ?? 0) + 1;
+          backoff?.set(down, { failures, until: now() + delay(failures) });
+        } else {
+          const failures = (waiting?.failures ?? 0) + 1;
+          backoff?.set(key, { failures, until: now() + delay(failures), digest: archive.digest });
+        }
         results.push({
           id: archive.id,
           destination: destination.url,
-          status: `failed; local revision retained: ${error instanceof Error ? error.message : String(error)}`,
+          status: `failed; local revision retained: ${message}`,
         });
       }
     }
+  // Archives that were deleted, or routes that were removed, leave no entries behind.
+  for (const key of backoff?.keys() ?? []) if (!seen.has(key)) backoff?.delete(key);
   return results;
 }
 

package/src/collector.ts

@@ -1,10 +1,22 @@
-import { closeSync, existsSync, lstatSync, openSync, readdirSync, readSync } from 'node:fs';
-import { isAbsolute, join, resolve } from 'node:path';
+import {
+  closeSync,
+  existsSync,
+  lstatSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readSync,
+  realpathSync,
+} from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { importTranscriptFile } from './import-file';
-import { archiveKey } from './index';
+import { archiveKey, archiveSnapshotSchema, snapshotDigest, UNROUTED } from './index';
 import type { ArchiveClient } from './remote';
 import { type AtlasFileConcepts, atlasTags, provenanceReferences } from './tags';
 
+export { UNROUTED } from './index';
+
 export interface CollectionSource {
   directory: string;
   source: 'codex' | 'claude-code';
@@ -12,12 +24,42 @@ export interface CollectionSource {
   projectId: string;
   /** Also match the git worktrees of each root; nested checkouts stay separate. */
   worktrees?: boolean;
+  /** Also match directories below each root, unless a more specific root claims them. */
+  subdirectories?: boolean;
+  /** Take every session no other collector of this source claims, as projectId `unrouted`. */
+  catchAll?: boolean;
   /** Tag sessions with the Atlas concepts of files they touched, from `atlas graph` in the session's checkout. */
   atlas?: boolean;
   tags?: string[];
 }
 
-function files(directory: string): string[] {
+/**
+ * Where sessions are never swept in by a subdirectory or catch-all match: temp directories (test
+ * fixtures, agent scratchpads) and Foundry's decision receipts. An exact root is explicit and wins.
+ * Absolute entries match the directory and below; relative ones match those path segments anywhere.
+ */
+export const defaultExclusions = () => [
+  ...new Set(
+    ['/tmp', '/private/tmp', '/var/folders', '/private/var/folders', tmpdir()].flatMap((path) => {
+      try {
+        return [resolve(path), realpathSync(path)];
+      } catch {
+        return [resolve(path)];
+      }
+    }),
+  ),
+  '.foundry/decision-receipts',
+];
+export function excluded(cwd: string, exclusions: string[]) {
+  return exclusions.some((entry) =>
+    isAbsolute(entry)
+      ? cwd === resolve(entry) || cwd.startsWith(`${resolve(entry)}/`)
+      : `${cwd}/`.includes(`/${entry.replace(/^\/+|\/+$/g, '')}/`),
+  );
+}
+
+/** Every transcript (`.jsonl`) under a directory, in order, without following links. */
+export function transcriptFiles(directory: string): string[] {
   const result: string[] = [];
   const visit = (path: string) => {
     const stat = lstatSync(path);
@@ -29,10 +71,10 @@ function files(directory: string): string[] {
   return result;
 }
 
-type SessionMetadata = { cwd: string; branch?: string; repository?: string };
+export type SessionMetadata = { cwd: string; branch?: string; repository?: string };
 
-/** Match provider metadata, never text/tags/model suggestions. No implicit parent-directory routing. */
-function sessionMetadata(
+/** Provider metadata, never text/tags/model suggestions; `routeSession` decides where it goes. */
+export function sessionMetadata(
   file: string,
   source: CollectionSource['source'],
 ): SessionMetadata | undefined {
@@ -96,42 +138,204 @@ function worktreesOf(root: string): string[] {
 
 /** Exact directories this collection accepts, re-read each scan so new worktrees join. */
 export function collectionRoots(config: CollectionSource): Set<string> {
-  const roots = config.projectRoots.map((root) => resolve(root));
+  // Providers record the real path (macOS /tmp is /private/tmp), so roots match by it too.
+  const roots = config.projectRoots.flatMap((root) => {
+    try {
+      return [...new Set([resolve(root), realpathSync(root)])];
+    } catch {
+      return [resolve(root)];
+    }
+  });
   return new Set(config.worktrees ? [...roots, ...roots.flatMap(worktreesOf)] : roots);
 }
 
+/**
+ * The collector a session's cwd belongs to. The longest matching root wins: a root matches its own
+ * directory (and worktrees), and with `subdirectories` the directories below it. Ties go to the
+ * first declared. Excluded directories match only exact roots. Unclaimed sessions go to the first
+ * catch-all.
+ */
+export function routeSession(
+  cwd: string,
+  collectors: CollectionSource[],
+  options: { exclude?: string[]; roots?: (collector: CollectionSource) => Set<string> } = {},
+) {
+  const rootsOf = options.roots ?? collectionRoots;
+  const broad = !excluded(cwd, options.exclude ?? defaultExclusions());
+  let best: { collector: CollectionSource; length: number } | undefined;
+  for (const collector of collectors) {
+    if (collector.catchAll) continue;
+    for (const root of rootsOf(collector)) {
+      const matches =
+        cwd === root || (broad && collector.subdirectories && cwd.startsWith(`${root}/`));
+      if (matches && (!best || root.length > best.length))
+        best = { collector, length: root.length };
+    }
+  }
+  if (best) return best.collector;
+  return broad ? collectors.find((c) => c.catchAll) : undefined;
+}
+
 /** Where collected sessions go: an Archive server, or a store in-process. */
 export type ArchiveWriter = Pick<ArchiveClient, 'sourceId' | 'head' | 'capture'>;
 
-export async function collectSessions(archive: ArchiveWriter, config: CollectionSource) {
+/**
+ * The access path the harness's login implies when a transcript is silent, read from the harness
+ * home that owns the history directory (`<claude config>/projects`, `<codex home>/sessions`):
+ * Claude Code's subscription login (`oauthAccount`) unless its settings supply an API key, and
+ * Codex's `auth.json` mode. Undefined when neither says; throws when a file exists but cannot be
+ * read, so a bad read never relabels sessions.
+ */
+export function harnessAccess(
+  source: CollectionSource['source'],
+  directory: string,
+): 'subscription' | 'api' | undefined {
+  const json = (path: string) =>
+    existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : undefined;
+  const harnessHome = dirname(resolve(directory));
+  if (source === 'claude-code') {
+    const settings = json(join(harnessHome, 'settings.json'));
+    if (settings?.apiKeyHelper || settings?.env?.ANTHROPIC_API_KEY) return 'api';
+    // The default config directory keeps its login beside it, in ~/.claude.json.
+    const login =
+      harnessHome === join(homedir(), '.claude')
+        ? join(homedir(), '.claude.json')
+        : join(harnessHome, '.claude.json');
+    const account = json(login)?.oauthAccount;
+    return account && typeof account === 'object' ? 'subscription' : undefined;
+  }
+  const auth = json(join(harnessHome, 'auth.json'));
+  if (auth?.auth_mode === 'chatgpt' || auth?.tokens) return 'subscription';
+  if (auth?.auth_mode === 'apikey' || auth?.OPENAI_API_KEY) return 'api';
+  return undefined;
+}
+
+/**
+ * What a watching collector remembers between scans: each file's size and mtime with the outcome,
+ * so an untouched file is neither re-read nor re-sent. Keyed by the routing and archive it was
+ * decided under; a stored session is re-checked against the server now and then, so one deleted
+ * there is captured again.
+ */
+export type CollectorCache = Map<
+  string,
+  {
+    size: number;
+    mtimeMs: number;
+    routing: string;
+    outcome: 'unchanged' | 'skipped' | 'failed';
+    meta?: SessionMetadata;
+    stored?: { id: string; digest: string; checkedAt: number };
+  }
+>;
+const REVALIDATE_MS = 10 * 60_000;
+
+export interface CollectOptions {
+  /** Every collector of this source and directory, this one included; the most specific wins. */
+  peers?: CollectionSource[];
+  exclude?: string[];
+  cache?: CollectorCache;
+  /** The harness login's access path; defaults to reading the history directory's harness home. */
+  harness?: (
+    source: CollectionSource['source'],
+    directory: string,
+  ) => 'subscription' | 'api' | undefined;
+  now?: () => number;
+}
+
+/** A rejection the same snapshot will get again: invalid input or a refused write, not an outage. */
+const deterministic = (error: unknown) => {
+  const status = (error as { status?: unknown } | null)?.status;
+  return (
+    (error instanceof Error && error.name === 'ZodError') ||
+    (typeof status === 'number' && status >= 400 && status < 500 && status !== 409)
+  );
+};
+
+export async function collectSessions(
+  archive: ArchiveWriter,
+  config: CollectionSource,
+  options: CollectOptions = {},
+) {
   const sourceId = await archive.sourceId();
-  const roots = collectionRoots(config);
+  const now = options.now ?? Date.now;
+  const peers = options.peers ?? [config];
+  const exclude = options.exclude ?? defaultExclusions();
+  const cache: CollectorCache = options.cache ?? new Map();
+  const routing = JSON.stringify([sourceId, config, peers, exclude]);
   const result = { imported: 0, unchanged: 0, skipped: 0, failed: 0 };
   // Per scan: checkouts change between scans.
+  const rootSets = new Map<CollectionSource, Set<string>>();
+  const roots = (collector: CollectionSource) => {
+    if (!rootSets.has(collector)) rootSets.set(collector, collectionRoots(collector));
+    return rootSets.get(collector)!;
+  };
+  const routes = new Map<string, CollectionSource | undefined>();
   const repositories = new Map<string, string | undefined>();
   const graphs = new Map<string, AtlasFileConcepts | undefined>();
-  for (const file of files(config.directory)) {
+  let harness: 'subscription' | 'api' | undefined | null = null;
+  for (const file of transcriptFiles(config.directory)) {
     try {
-      const meta = sessionMetadata(file, config.source);
-      // Exact root selection avoids sweeping nested checkouts belonging to another organization.
-      if (!meta || !roots.has(meta.cwd)) {
+      const before = lstatSync(file);
+      const known = cache.get(file);
+      if (
+        known?.size === before.size &&
+        known.mtimeMs === before.mtimeMs &&
+        known.routing === routing
+      ) {
+        const stored = known.stored;
+        if (!stored || now() - stored.checkedAt < REVALIDATE_MS) {
+          result[known.outcome]++;
+          continue;
+        }
+        if ((await archive.head(stored.id))?.digest === stored.digest) {
+          stored.checkedAt = now();
+          result.unchanged++;
+          continue;
+        }
+      }
+      const remember = (
+        outcome: 'unchanged' | 'skipped' | 'failed',
+        meta?: SessionMetadata,
+        stored?: { id: string; digest: string },
+      ) =>
+        cache.set(file, {
+          size: before.size,
+          mtimeMs: before.mtimeMs,
+          routing,
+          outcome,
+          meta,
+          ...(stored ? { stored: { ...stored, checkedAt: now() } } : {}),
+        });
+      // A transcript's first cwd never changes, so it is read once per file.
+      const meta = known?.meta ?? sessionMetadata(file, config.source);
+      if (!meta) {
         result.skipped++;
+        remember('skipped');
         continue;
       }
-      const before = lstatSync(file);
-      const snapshot = importTranscriptFile(file, {
-        source: config.source,
-        sourceId,
-        projectId: config.projectId,
-      });
-      const after = lstatSync(file);
-      if (before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
+      if (!routes.has(meta.cwd))
+        routes.set(meta.cwd, routeSession(meta.cwd, peers, { exclude, roots }));
+      if (routes.get(meta.cwd) !== config) {
         result.skipped++;
+        remember('skipped', meta);
         continue;
       }
-      const old = await archive.head(archiveKey(snapshot));
-      if (old && old.projectId !== config.projectId) {
+      let snapshot: ReturnType<typeof importTranscriptFile>;
+      try {
+        snapshot = importTranscriptFile(file, {
+          source: config.source,
+          sourceId,
+          projectId: config.projectId,
+        });
+      } catch {
+        // The same bytes fail the same way; a partial file is retried once it changes.
         result.failed++;
+        remember('failed', meta);
+        continue;
+      }
+      const after = lstatSync(file);
+      if (before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
+        result.skipped++;
         continue;
       }
       const { cwd } = meta;
@@ -139,15 +343,54 @@ export async function collectSessions(archive: ArchiveWriter, config: Collection
       if (config.atlas && !graphs.has(cwd)) graphs.set(cwd, atlasGraph(cwd));
       const graph = graphs.get(cwd);
       snapshot.tags = [
-        ...new Set([...(config.tags ?? []), ...(graph ? atlasTags(snapshot, graph, roots) : [])]),
+        ...new Set([
+          ...(config.tags ?? []),
+          ...(graph ? atlasTags(snapshot, graph, roots(config)) : []),
+        ]),
       ].slice(0, 100);
       const references = provenanceReferences({
         branch: meta.branch,
         repository: meta.repository ?? repositories.get(cwd),
       });
       if (references.length) snapshot.references = references;
-      if ((await archive.capture(snapshot)).changed) result.imported++;
-      else result.unchanged++;
+      if (snapshot.runtime?.accessPath === 'unknown') {
+        if (harness === null)
+          harness = (options.harness ?? harnessAccess)(config.source, config.directory);
+        if (harness)
+          snapshot.runtime = { ...snapshot.runtime, accessPath: harness, evidence: 'harness' };
+      }
+      const id = archiveKey(snapshot);
+      const old = await archive.head(id);
+      // A session belongs to one project; only one the catch-all held moves to its routed project.
+      if (old && old.projectId !== config.projectId && old.projectId !== UNROUTED) {
+        result.failed++;
+        remember('failed', meta);
+        continue;
+      }
+      // An unchanged session is not sent again: the server already holds this digest.
+      // Digest what the server will: the schema orders keys, and fields set above were appended.
+      let digest: string;
+      try {
+        digest = snapshotDigest(archiveSnapshotSchema.parse(snapshot));
+      } catch {
+        // Over the archive's limits: the same bytes are refused again.
+        result.failed++;
+        remember('failed', meta);
+        continue;
+      }
+      if (old?.digest === digest) result.unchanged++;
+      else {
+        try {
+          const captured = await archive.capture(snapshot);
+          digest = captured.digest;
+          result[captured.changed ? 'imported' : 'unchanged']++;
+        } catch (error) {
+          result.failed++;
+          if (deterministic(error)) remember('failed', meta);
+          continue;
+        }
+      }
+      remember('unchanged', meta, { id, digest });
     } catch {
       result.failed++;
     } // Partial/malformed files remain intact and retry on the next scan.

package/src/config.ts

@@ -13,8 +13,13 @@ import {
 } from 'node:fs';
 import { dirname, isAbsolute, join } from 'node:path';
 import { z } from 'zod';
+import { UNROUTED } from './index';
 
-const projectId = z.string().min(1).max(256);
+const projectId = z
+  .string()
+  .min(1)
+  .max(256)
+  .refine((id) => id !== UNROUTED, `${UNROUTED} sessions stay on this machine`);
 /** A remote Archive this one syncs to directly with its server token. */
 const archiveDestination = z
   .strictObject({

package/src/import-file.ts

@@ -1,5 +1,6 @@
-import { closeSync, fstatSync, openSync, readSync } from 'node:fs';
+import { closeSync, existsSync, fstatSync, openSync, readFileSync, readSync } from 'node:fs';
 import { type ImportOptions, importTranscriptLines } from './import';
+import { archiveLineageSchema } from './index';
 
 /** Bound raw record memory while skipping unsupported payloads from long native histories. */
 export function importTranscriptFile(file: string, options: ImportOptions) {
@@ -41,5 +42,31 @@ export function importTranscriptFile(file: string, options: ImportOptions) {
       closeSync(descriptor);
     }
   }
-  return importTranscriptLines(lines(), options);
+  const snapshot = importTranscriptLines(lines(), options);
+  if (options.source === 'claude-code' && snapshot.lineage) {
+    const meta = subagentMeta(file);
+    if (meta) snapshot.lineage = archiveLineageSchema.parse({ ...snapshot.lineage, ...meta });
+  }
+  return snapshot;
+}
+
+/** Claude Code writes `agent-<id>.meta.json` beside a subagent transcript: its type, task and depth. */
+function subagentMeta(file: string) {
+  const path = file.replace(/\.jsonl$/, '.meta.json');
+  if (path === file || !existsSync(path)) return undefined;
+  let meta: Record<string, unknown>;
+  try {
+    meta = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return undefined;
+  }
+  const text = (value: unknown, max: number) =>
+    typeof value === 'string' && value ? value.slice(0, max) : undefined;
+  const fields = {
+    agentType: text(meta.agentType, 200),
+    description: text(meta.description, 500),
+    toolUseId: text(meta.toolUseId, 256),
+    depth: Number.isInteger(meta.spawnDepth) ? (meta.spawnDepth as number) : undefined,
+  };
+  return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
 }

package/src/import.ts

@@ -1,4 +1,9 @@
-import { type ArchiveEntry, type ArchiveSnapshot, archiveSnapshotSchema } from './index';
+import {
+  type ArchiveEntry,
+  type ArchiveLineage,
+  type ArchiveSnapshot,
+  archiveSnapshotSchema,
+} from './index';
 
 export interface ImportOptions {
   source: 'codex' | 'claude-code';
@@ -102,6 +107,14 @@ export function importTranscriptLines(
   let turn: { model?: string; effort?: string } = {};
   // A Codex session started by a script (codex exec, a custom originator) has no typed prompts.
   let scripted = false;
+  let metaSeen = false;
+  let lineage: ArchiveLineage | undefined;
+  let provider: string | undefined = options.source === 'claude-code' ? 'anthropic' : undefined;
+  // Only a subscription's rate-limit windows prove the access path; an API key leaves no mark.
+  let subscription = false;
+  const text = (value: unknown) => (typeof value === 'string' && value ? value : undefined);
+  const optional = <K extends string>(key: K, value: string | undefined) =>
+    (value ? { [key]: value } : {}) as Partial<Record<K, string>>;
   for (const rawLine of lines) {
     index++;
     const line = rawLine.trim();
@@ -115,17 +128,52 @@ export function importTranscriptLines(
     if (!row || typeof row !== 'object' || Array.isArray(row))
       throw new Error(`Invalid transcript record at line ${index + 1}`);
     if (options.source === 'codex' && row.type === 'session_meta') {
-      const id = row.payload?.id;
+      const meta = row.payload ?? {};
+      const id = meta.id;
+      // A subagent or forked rollout starts with its own meta, then replays its parent's history,
+      // parent meta included. The first meta is the session; a later one is lineage, not identity.
+      if (metaSeen && lineage) continue;
       if (sessionId && id && id !== sessionId)
         throw new Error('Transcript session identity mismatch');
       sessionId ??= id;
+      metaSeen = true;
       // Subagent and guardian threads, and `codex exec`, are driven by an agent or a script.
-      const { originator, source } = row.payload ?? {};
+      const { originator, source } = meta;
       if (typeof originator === 'string')
         scripted = !/^codex/i.test(originator) || /^codex_(?:exec|sdk|mcp)/.test(originator);
+      const spawn =
+        source && typeof source === 'object' && 'subagent' in source
+          ? source.subagent?.thread_spawn
+          : undefined;
       if (source === 'exec' || (source && typeof source === 'object' && 'subagent' in source))
         scripted = true;
+      const parent = text(spawn?.parent_thread_id) ?? text(meta.parent_thread_id);
+      const forked = text(meta.forked_from_id);
+      if (parent || forked)
+        lineage = {
+          kind: source && typeof source === 'object' && 'subagent' in source ? 'subagent' : 'fork',
+          parentSessionId: (parent ?? forked)!,
+          ...optional('agentType', text(spawn?.agent_role ?? meta.agent_role)),
+          ...optional('agentName', text(spawn?.agent_nickname ?? meta.agent_nickname)),
+          ...(Number.isInteger(spawn?.depth) ? { depth: spawn.depth } : {}),
+        };
+      const named = text(meta.model_provider)?.toLowerCase();
+      provider = named && /^[a-z0-9][a-z0-9_-]{0,63}$/.test(named) ? named : 'openai';
     }
+    if (
+      options.source === 'codex' &&
+      row.type === 'event_msg' &&
+      row.payload?.type === 'token_count' &&
+      text(row.payload.rate_limits?.plan_type)
+    )
+      subscription = true;
+    if (
+      options.source === 'claude-code' &&
+      row.quotaLimits &&
+      typeof row.quotaLimits === 'object' &&
+      text(row.quotaLimits.rateLimitType)
+    )
+      subscription = true;
     if (options.source === 'claude-code' && row.sessionId) {
       // Subagent transcripts reuse their parent's sessionId; each is its own archive.
       const id =
@@ -134,8 +182,9 @@ export function importTranscriptLines(
           : row.sessionId;
       if (sessionId && sessionId !== id) throw new Error('Mixed transcript sessions');
       sessionId = id;
+      if (row.isSidechain && typeof row.agentId === 'string')
+        lineage ??= { kind: 'subagent', parentSessionId: row.sessionId };
     }
-    const text = (value: unknown) => (typeof value === 'string' && value ? value : undefined);
     if (options.source === 'codex' && row.type === 'turn_context')
       turn = { model: text(row.payload?.model), effort: text(row.payload?.effort) };
     const producer =
@@ -287,6 +336,12 @@ export function importTranscriptLines(
     sessionId,
     title,
     projectId: options.projectId,
+    runtime: {
+      provider: provider ?? 'openai',
+      accessPath: subscription ? 'subscription' : 'unknown',
+      ...(subscription ? { evidence: 'transcript' } : {}),
+    },
+    ...(lineage ? { lineage } : {}),
     tags: [],
     capturedAt: Date.now(),
     coverage: {

package/src/index.ts

@@ -3,6 +3,8 @@ import { getEncoding } from 'js-tiktoken';
 import { z } from 'zod';
 
 const identifier = z.string().min(1).max(256);
+/** The projectId a catch-all collector gives sessions no other collector claims. It never leaves the machine. */
+export const UNROUTED = 'unrouted';
 export const archiveEntrySchema = z.strictObject({
   id: identifier,
   turnId: identifier.optional(),
@@ -28,6 +30,26 @@ export const archiveReferenceSchema = z.strictObject({
   integration: z.string().regex(/^[a-z0-9-]{1,64}$/),
   ref: z.string().min(1).max(300),
 });
+/**
+ * How the session reached its model: the provider, and whether it ran on a subscription or an API
+ * key. `evidence` says where the access path came from: the transcript itself, or the harness's
+ * login when the transcript is silent (its state at capture).
+ */
+export const archiveRuntimeSchema = z.strictObject({
+  provider: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,63}$/),
+  accessPath: z.enum(['subscription', 'api', 'unknown']),
+  evidence: z.enum(['transcript', 'harness']).optional(),
+});
+/** The session that started this one: a subagent's parent, or the thread a fork copied. */
+export const archiveLineageSchema = z.strictObject({
+  kind: z.enum(['subagent', 'fork']),
+  parentSessionId: identifier,
+  agentType: z.string().min(1).max(200).optional(),
+  agentName: z.string().min(1).max(200).optional(),
+  description: z.string().min(1).max(500).optional(),
+  toolUseId: identifier.optional(),
+  depth: z.number().int().nonnegative().max(100).optional(),
+});
 export const archiveSnapshotSchema = z
   .strictObject({
     schemaVersion: z.literal(1),
@@ -37,6 +59,8 @@ export const archiveSnapshotSchema = z
     title: z.string().min(1).max(500),
     projectId: identifier.optional(),
     actor: archiveActorSchema.optional(),
+    runtime: archiveRuntimeSchema.optional(),
+    lineage: archiveLineageSchema.optional(),
     /** Recorded references, such as the session's repository and branch. Linked ones are found in the text. */
     references: z.array(archiveReferenceSchema).max(100).optional(),
     tags: z.array(z.string().min(1).max(120)).max(100),
@@ -60,6 +84,8 @@ export type ArchiveSnapshot = z.infer<typeof archiveSnapshotSchema>;
 export type ArchiveEntry = z.infer<typeof archiveEntrySchema>;
 export type ArchiveActor = z.infer<typeof archiveActorSchema>;
 export type ArchiveReference = z.infer<typeof archiveReferenceSchema>;
+export type ArchiveRuntime = z.infer<typeof archiveRuntimeSchema>;
+export type ArchiveLineage = z.infer<typeof archiveLineageSchema>;
 export interface ArchiveChunk {
   id: string;
   entryId: string;

package/src/schemas.ts

@@ -37,4 +37,6 @@ export interface ArchiveFilter {
   reference?: { integration: string; ref: string };
   model?: string;
   effort?: string;
+  provider?: string;
+  accessPath?: 'subscription' | 'api' | 'unknown';
 }

package/src/server.ts

@@ -29,6 +29,8 @@ const filterFields = {
   reference: archiveReferenceSchema.optional(),
   model: z.string().min(1).max(200).optional(),
   effort: z.string().min(1).max(40).optional(),
+  provider: z.string().min(1).max(64).optional(),
+  accessPath: z.enum(['subscription', 'api', 'unknown']).optional(),
   limit: z.number().int().min(1).max(100).default(20),
   beforeId: archiveId.optional(),
 };
@@ -145,6 +147,8 @@ export function createArchiveHandler(
             title: a.title,
             projectId: a.projectId,
             actor: a.actor,
+            runtime: a.runtime,
+            lineage: a.lineage,
             models: a.models,
             tags: a.tags,
             suggestedTags: a.suggestedTags,

package/src/store.ts

@@ -144,6 +144,8 @@ export class ArchiveStore {
           source: snapshot.source,
           projectId: snapshot.projectId ?? null,
           actorId: snapshot.actor?.id ?? null,
+          provider: snapshot.runtime?.provider ?? null,
+          accessPath: snapshot.runtime?.accessPath ?? null,
           capturedAt: snapshot.capturedAt,
           summary: summarize(snapshot, settings) as Prisma.InputJsonValue,
         };
@@ -217,6 +219,8 @@ export class ArchiveStore {
           ...(filter.projectId ? { projectId: filter.projectId } : {}),
           ...(filter.source ? { source: filter.source } : {}),
           ...(filter.actorId ? { actorId: filter.actorId } : {}),
+          ...(filter.provider ? { provider: filter.provider } : {}),
+          ...(filter.accessPath ? { accessPath: filter.accessPath } : {}),
           ...(cursor === undefined ? {} : { seq: { lt: cursor } }),
         },
         include: { tagEdits: true },