@inixiative/archive 0.2.1 → 0.4.0

package/README.md

@@ -39,35 +39,62 @@ bun run archive list
 bun run archive search --query 'migration'
 ```
 
-Use `--source claude-code` for Claude histories. Collection matches the exact working-directory metadata recorded by the provider. 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 initial collector rescans files every 30 seconds; it deduplicates normalized content rather than maintaining byte-offset ingestion cursors. It retains prior manually assigned tags. It does not upload: run sync separately.
+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 initial collector rescans files every 30 seconds; it deduplicates normalized content rather than maintaining byte-offset ingestion cursors. It retains prior manually assigned tags. It does not upload: run sync separately.
 
 ## Connect to BYO hosting
 
-Deploy the included Dockerfile with a persistent volume mounted at `/data`, HTTPS, and a unique `ARCHIVE_SERVER_TOKEN` of at least 32 characters. Compose binds only to loopback; put an HTTPS reverse proxy in front for remote use. Railway needs a `/data` volume. The Render blueprint provisions a dedicated disk and generated token.
+Deploy the included Dockerfile with a persistent volume mounted at `/data`, HTTPS, and a unique `ARCHIVE_SERVER_TOKEN` of at least 32 characters. Compose bind-mounts `./data` (or `ARCHIVE_DATA_DIR`) at `/data`, so the store survives rebuilds, `down -v` and volume prunes, and binds only to loopback on port 4411 (or `ARCHIVE_PORT`); put an HTTPS reverse proxy in front for remote use. Railway needs a `/data` volume. The Render blueprint provisions a dedicated disk and generated token.
 
-Place the destination's token in an environment variable, then run:
+Place the destination's token in a private file (`chmod 600`, owned by you) or an environment variable, then run:
 
 ```sh
-bun run archive connect --url https://your-archive.example --project-id inixiative --token-env INIXIATIVE_ARCHIVE_TOKEN
+bun run archive connect --url https://your-archive.example --project-id inixiative --token-file ~/.local/share/archive/credentials/inixiative.token
 bun run archive routes
 bun run archive sync
 bun run archive sync --watch
 bun run archive search --remote --query 'migration'
 ```
 
-`setup` is an alias for `connect`. Setup verifies access before saving configuration and does not upload. The URL locates the server; the token grants access. Configuration stores only the environment variable name. Secrets must be available in the collector/sync process environment. Redirects are refused; only HTTPS or loopback HTTP is allowed.
+`setup` is an alias for `connect`. Setup verifies access before saving configuration and does not upload. The URL locates the server; the token grants access. Configuration stores only the token file path (`tokenFile`) or environment variable name (`--token-env`, `tokenEnv`), never the token. A token file is read on every request, so rotating it needs no restart; symlinks and files readable by group or others are refused. An environment variable must be set in the sync process environment. Redirects are refused; only HTTPS or loopback HTTP is allowed.
 
 `--home PATH`, `--store FILE` and `--config FILE` support custom paths. Keep the database with its source UUID when moving machines. Back up the entire database; a new store creates a new source identity.
 
+## Always-on local archiving
+
+`archive agents` declares long-running agents in `~/.local/share/archive/agents.json` and installs them as launchd agents (macOS) or systemd user units (Linux):
+
+```sh
+archive init
+archive connect --url https://your-archive.example --project-id inixiative --token-file ~/.local/share/archive/credentials/inixiative.token
+archive agents add-collector --name claude-code.inixiative --source claude-code --project-id inixiative --project-root ~/code/inixiative --worktrees
+archive agents add-collector --name codex.inixiative --source codex --project-id inixiative --project-root ~/code/inixiative --worktrees
+archive agents serve on
+archive agents sync on
+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`, `serve on|off [--port P]` and `sync on|off` edit the same file. `install` writes one unit per agent: `com.inixiative.archive.local` (serve), `com.inixiative.archive.sync` (`sync --watch`) and `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; other launchd agents are untouched. `uninstall` removes every Archive unit; `status` reports each unit's load state, PID and last log entry. One archive home per user account: units are named by agent, not by home. Sync reads destination token files itself, so no wrapper script is needed. Re-run `install` after upgrading the package if its install path changes.
+
+Docker Compose is the alternative for the server: `docker compose up -d` bind-mounts `./data` (or `ARCHIVE_DATA_DIR`) at `/data` and binds loopback port 4411. It is a separate store, so connect it as a destination and let the `sync` agent publish to it; do not bind-mount the store the host agents are writing, since SQLite locking across the Docker VM boundary is unreliable. Collectors run on the host, where the session histories are.
+
+`@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.
+
 ## Connect through Kingdom
 
-Use Kingdom's existing runtime enrollment for a user who manages the destination Kastle, then:
+Pair a runtime with Kingdom (Foundry: Settings → Kingdom) and expose its `kastle_runtime_` credential in an environment variable, then either let Kingdom store the archives:
 
 ```sh
-bun run archive connect --kind kingdom --url https://your-kingdom.example --kastle-id UUID --project-id inixiative --token-env KINGDOM_ARCHIVE_TOKEN
+bun run archive connect --kind kingdom --url https://your-kingdom.example --project-id inixiative --token-env KINGDOM_ARCHIVE_TOKEN
 ```
 
-Optional repeated `--keep-id UUID` places sessions in Keeps owned by that Kastle. A Kingdom runtime credential is distinct from a standalone Archive token. Kingdom retains responsibility for user memberships, shares, revocation and hosted browsing. Connecting directly to Archive does not automatically register that server as a Kastle resource or mirror it into Kingdom; these are separate destinations.
+or forward them through Kingdom to a hosted Archive it has bound for that project:
+
+```sh
+bun run archive connect --kind kingdom --url https://your-kingdom.example --connection-id inixiative --project-id inixiative --token-env KINGDOM_ARCHIVE_TOKEN
+```
+
+Kingdom takes the owner from the runtime credential; `--owner-model`, `--organization-id` and `--space-id` narrow it to an organization or space that owner manages. A forwarding connection accepts only its bound `projectId`, and the hosted Archive's own token stays in Kingdom's server environment. A Kingdom runtime credential is distinct from a standalone Archive token. Kingdom retains responsibility for memberships, shares, revocation and hosted browsing.
 
 Foundry exposes the same commands through `bun run archive`. Its defaults remain `.foundry/archives/archives.sqlite` and `.foundry/archives.json`. Its durable journal capture automatically publishes matching projects once destination credentials are in the viewer's environment. Restart the viewer after changing destination configuration.
 
@@ -79,7 +106,9 @@ Only explicit `projectId` matches authorize publication. An archive with no matc
 bun run archive tag --id ARCHIVE_ID --tag reviewed
 ```
 
-Tags and heuristic category suggestions do not change ownership or routing. Jev integration is not enabled: the next step is labeled, shadow-mode tag/destination proposals, scored for accuracy and cross-organization mistakes before any automatic action. Session content must not be sent to Jev without selecting that service for the relevant ownership boundary.
+Collectors add explicit tags from recorded session metadata: `repo:owner/name` and `branch:name` from git context, and with `--atlas` the `atlas:<concept>` of repository files the session's tool calls touched (from `atlas graph --json` in the session's checkout). Suggestions are computed on read and never stored: heuristic categories, plus `reference` suggestions for linked GitHub pull requests, issues and commits (`github:owner/repo#24`, `github:owner/repo@sha`) and Linear issues (`linear:KEY-12`). A link is a mention, not proof of work, so references stay suggestions.
+
+Tags and suggestions do not change ownership or routing. Jev integration is not enabled: the next step is labeled, shadow-mode tag/destination proposals, scored for accuracy and cross-organization mistakes before any automatic action. 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.2.1",
+  "version": "0.4.0",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -13,7 +13,9 @@
     "./preview": "./src/preview.ts",
     "./cli": "./src/cli.ts",
     "./collector": "./src/collector.ts",
-    "./chatgpt": "./src/chatgpt.ts"
+    "./chatgpt": "./src/chatgpt.ts",
+    "./tags": "./src/tags.ts",
+    "./agents": "./src/agents.ts"
   },
   "files": [
     "src"
@@ -34,7 +36,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.34",
+    "@inixiative/config": "^0.5.37",
     "@types/bun": "1.4.2",
     "lefthook": "2.1.9",
     "typescript": "6.0.3"

package/src/agents.ts

@@ -0,0 +1,386 @@
+import { randomUUID } from 'node:crypto';
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+
+export const defaultHome = () => join(homedir(), '.local/share/archive');
+export const AGENT_LABEL_PREFIX = 'com.inixiative.archive.';
+/** History each provider writes by default. */
+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 agentsConfigSchema = z
+  .strictObject({
+    serve: z.strictObject({ port: z.number().int().min(1).max(65535).optional() }).optional(),
+    sync: z.boolean().optional(),
+    collectors: z.array(collectorAgentSchema).max(100),
+  })
+  .refine(
+    (c) => new Set(c.collectors.map((x) => x.name)).size === c.collectors.length,
+    'Collector names must be unique',
+  );
+export type AgentsConfig = z.infer<typeof agentsConfigSchema>;
+export type CollectorAgent = z.infer<typeof collectorAgentSchema>;
+
+export const readAgents = (file: string): AgentsConfig | undefined =>
+  existsSync(file) ? agentsConfigSchema.parse(JSON.parse(readFileSync(file, 'utf8'))) : undefined;
+export function writeAgents(file: string, input: AgentsConfig) {
+  const config = agentsConfigSchema.parse(input);
+  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+  const temp = `${file}.${randomUUID()}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+  renameSync(temp, file);
+  chmodSync(file, 0o600);
+  return config;
+}
+export function upsertCollector(config: AgentsConfig | undefined, collector: CollectorAgent) {
+  const collectors = (config?.collectors ?? []).filter((c) => c.name !== collector.name);
+  return { ...config, collectors: [...collectors, collectorAgentSchema.parse(collector)] };
+}
+
+export interface AgentUnit {
+  label: string;
+  /** Full argv: runtime, CLI entrypoint, command. */
+  args: string[];
+  workingDirectory: string;
+  stdout: string;
+  stderr: string;
+}
+export interface AgentUnitOptions {
+  home: string;
+  execPath?: string;
+  /** Defaults to this package's own CLI, wherever it is installed. */
+  cliPath?: string;
+}
+export const packageCliPath = () => fileURLToPath(new URL('./cli.ts', import.meta.url));
+
+export function collectorArgs(c: CollectorAgent) {
+  return [
+    'collect',
+    '--directory',
+    c.directory,
+    '--source',
+    c.source,
+    ...c.projectRoots.flatMap((root) => ['--project-root', root]),
+    ...(c.worktrees ? ['--worktrees'] : []),
+    ...(c.atlas ? ['--atlas'] : []),
+    '--project-id',
+    c.projectId,
+    '--watch',
+  ];
+}
+
+/** One supervised unit per declared agent. */
+export function agentUnits(config: AgentsConfig, options: AgentUnitOptions): AgentUnit[] {
+  const home = resolve(options.home);
+  const base = [options.execPath ?? process.execPath, options.cliPath ?? packageCliPath()];
+  const homeArgs = home === resolve(defaultHome()) ? [] : ['--home', home];
+  const unit = (suffix: string, command: string[]): AgentUnit => {
+    const label = AGENT_LABEL_PREFIX + suffix;
+    return {
+      label,
+      args: [...base, ...command, ...homeArgs],
+      workingDirectory: home,
+      stdout: join(home, 'logs', `${label}.out.log`),
+      stderr: join(home, 'logs', `${label}.err.log`),
+    };
+  };
+  return [
+    ...(config.serve
+      ? [
+          unit('local', [
+            'serve',
+            ...(config.serve.port ? ['--port', String(config.serve.port)] : []),
+          ]),
+        ]
+      : []),
+    ...(config.sync ? [unit('sync', ['sync', '--watch'])] : []),
+    ...config.collectors.map((c) => unit(`collect.${c.name}`, collectorArgs(c))),
+  ];
+}
+
+const xml = (value: string) =>
+  value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+export function renderPlist(unit: AgentUnit) {
+  const string = (value: string) => `<string>${xml(value)}</string>`;
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  ${string(unit.label)}
+  <key>ProgramArguments</key>
+  <array>
+${unit.args.map((arg) => `    ${string(arg)}`).join('\n')}
+  </array>
+  <key>WorkingDirectory</key>
+  ${string(unit.workingDirectory)}
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ThrottleInterval</key>
+  <integer>30</integer>
+  <key>StandardOutPath</key>
+  ${string(unit.stdout)}
+  <key>StandardErrorPath</key>
+  ${string(unit.stderr)}
+</dict>
+</plist>
+`;
+}
+
+// systemd expands % specifiers and $ variables even inside quotes.
+const systemdEscape = (value: string) => value.replace(/%/g, '%%').replace(/\$/g, '$$$$');
+const systemdQuote = (arg: string) =>
+  `"${systemdEscape(arg.replace(/\\/g, '\\\\').replace(/"/g, '\\"'))}"`;
+export function renderSystemdUnit(unit: AgentUnit) {
+  return `[Unit]
+Description=Archive ${unit.label.slice(AGENT_LABEL_PREFIX.length)}
+
+[Service]
+ExecStart=${unit.args.map(systemdQuote).join(' ')}
+WorkingDirectory=${systemdEscape(unit.workingDirectory)}
+Restart=always
+RestartSec=30
+StandardOutput=append:${systemdEscape(unit.stdout)}
+StandardError=append:${systemdEscape(unit.stderr)}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export type AgentPlatform = 'darwin' | 'linux';
+export const unitFileName = (label: string, platform: AgentPlatform) =>
+  label + (platform === 'darwin' ? '.plist' : '.service');
+const ownedLabel = (label: string) =>
+  label === `${AGENT_LABEL_PREFIX}local` ||
+  label === `${AGENT_LABEL_PREFIX}sync` ||
+  label.startsWith(`${AGENT_LABEL_PREFIX}collect.`);
+/** Labels of Archive units present in a supervisor directory. */
+export function installedLabels(dir: string, platform: AgentPlatform) {
+  const extension = unitFileName('', platform);
+  return existsSync(dir)
+    ? readdirSync(dir)
+        .filter((file) => file.endsWith(extension))
+        .map((file) => file.slice(0, -extension.length))
+        .filter(ownedLabel)
+        .sort()
+    : [];
+}
+
+export interface AgentPlan {
+  write: { label: string; file: string; content: string }[];
+  unchanged: string[];
+  remove: string[];
+}
+/** Pure: which unit files to write, keep, or remove, given what is on disk. */
+export function planAgents(
+  units: AgentUnit[],
+  installed: { label: string; content?: string }[],
+  platform: AgentPlatform,
+  dir: string,
+): AgentPlan {
+  const current = new Map(installed.map((i) => [i.label, i.content]));
+  const render = platform === 'darwin' ? renderPlist : renderSystemdUnit;
+  const plan: AgentPlan = { write: [], unchanged: [], remove: [] };
+  for (const unit of units) {
+    const content = render(unit);
+    if (current.get(unit.label) === content) plan.unchanged.push(unit.label);
+    else
+      plan.write.push({
+        label: unit.label,
+        file: join(dir, unitFileName(unit.label, platform)),
+        content,
+      });
+  }
+  const wanted = new Set(units.map((u) => u.label));
+  plan.remove = installed.map((i) => i.label).filter((l) => ownedLabel(l) && !wanted.has(l));
+  return plan;
+}
+
+export type AgentRunner = (argv: string[]) => { code: number; stdout: string; stderr: string };
+const spawnRunner: AgentRunner = (argv) => {
+  const run = Bun.spawnSync(argv, { stdout: 'pipe', stderr: 'pipe' });
+  return { code: run.exitCode ?? 1, stdout: run.stdout.toString(), stderr: run.stderr.toString() };
+};
+export interface AgentHostOptions {
+  home?: string;
+  platform?: AgentPlatform;
+  /** Supervisor directory; defaults to ~/Library/LaunchAgents or ~/.config/systemd/user. */
+  dir?: string;
+  run?: AgentRunner;
+  uid?: number;
+  sleep?: (ms: number) => void;
+  execPath?: string;
+  cliPath?: string;
+}
+function host(options: AgentHostOptions) {
+  const platform =
+    options.platform ??
+    (process.platform === 'darwin' || process.platform === 'linux'
+      ? process.platform
+      : (() => {
+          throw new Error('Agents support macOS launchd and Linux systemd only');
+        })());
+  const home = resolve(options.home ?? defaultHome());
+  const dir =
+    options.dir ??
+    join(homedir(), platform === 'darwin' ? 'Library/LaunchAgents' : '.config/systemd/user');
+  const run = options.run ?? spawnRunner;
+  const domain = `gui/${options.uid ?? process.getuid?.()}`;
+  const sleep = options.sleep ?? Bun.sleepSync;
+  const file = (label: string) => join(dir, unitFileName(label, platform));
+  const systemctl = (...args: string[]) => run(['systemctl', '--user', ...args]);
+  const unload = (label: string) => {
+    if (platform === 'darwin') run(['launchctl', 'bootout', `${domain}/${label}`]);
+    else systemctl('disable', '--now', `${label}.service`);
+  };
+  const load = (label: string) => {
+    if (platform === 'linux') {
+      const enabled = systemctl('enable', `${label}.service`);
+      const started = systemctl('restart', `${label}.service`);
+      if (enabled.code || started.code) throw new Error(`systemctl failed for ${label}`);
+      return;
+    }
+    run(['launchctl', 'bootout', `${domain}/${label}`]);
+    // bootout returns before launchd finishes tearing down; bootstrap then fails with I/O error 5.
+    for (let attempt = 1; ; attempt++) {
+      const result = run(['launchctl', 'bootstrap', domain, file(label)]);
+      if (!result.code) return;
+      if (attempt >= 5 || (result.code !== 5 && !/Input\/output error/.test(result.stderr)))
+        throw new Error(`launchctl bootstrap failed for ${label}: ${result.stderr.trim()}`);
+      sleep(1000);
+    }
+  };
+  const loaded = (label: string) => {
+    if (platform === 'darwin') {
+      const result = run(['launchctl', 'print', `${domain}/${label}`]);
+      if (result.code) return { loaded: false };
+      const pid = /\bpid = (\d+)/.exec(result.stdout)?.[1];
+      return { loaded: true, pid: pid ? Number(pid) : undefined };
+    }
+    const result = systemctl('show', `${label}.service`, '--property=ActiveState,MainPID');
+    const state = /ActiveState=(\w+)/.exec(result.stdout)?.[1];
+    const pid = Number(/MainPID=(\d+)/.exec(result.stdout)?.[1] ?? 0);
+    return { loaded: state === 'active' || state === 'activating', pid: pid || undefined };
+  };
+  const remove = (labels: string[]) => {
+    for (const label of labels) {
+      unload(label);
+      rmSync(file(label), { force: true });
+    }
+    if (platform === 'linux' && labels.length) systemctl('daemon-reload');
+  };
+  return { platform, home, dir, file, load, loaded, remove, systemctl };
+}
+
+/** Writes and (re)loads declared agents; removes Archive units no longer declared. */
+export function installAgents(config: AgentsConfig, options: AgentHostOptions = {}) {
+  const h = host(options);
+  const units = agentUnits(config, {
+    home: h.home,
+    execPath: options.execPath,
+    cliPath: options.cliPath,
+  });
+  mkdirSync(join(h.home, 'logs'), { recursive: true, mode: 0o700 });
+  mkdirSync(h.dir, { recursive: true });
+  const installed = installedLabels(h.dir, h.platform).map((label) => ({
+    label,
+    content: readFileSync(h.file(label), 'utf8'),
+  }));
+  const plan = planAgents(units, installed, h.platform, h.dir);
+  h.remove(plan.remove);
+  for (const { file, content } of plan.write) {
+    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');
+  // 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);
+  return {
+    platform: h.platform,
+    dir: h.dir,
+    loaded: reload,
+    unchanged: plan.unchanged.filter((l) => !reload.includes(l)),
+    removed: plan.remove,
+  };
+}
+
+export function uninstallAgents(options: AgentHostOptions = {}) {
+  const h = host(options);
+  const labels = installedLabels(h.dir, h.platform);
+  h.remove(labels);
+  return { platform: h.platform, dir: h.dir, removed: labels };
+}
+
+/** Last log entry: CLI output is pretty JSON, so the last top-level value, compacted; else the last line. */
+function lastEntry(file: string) {
+  if (!existsSync(file)) return undefined;
+  const fd = openSync(file, 'r');
+  try {
+    const size = fstatSync(fd).size;
+    const buffer = Buffer.alloc(Math.min(size, 65_536));
+    readSync(fd, buffer, 0, buffer.length, size - buffer.length);
+    const lines = buffer.toString('utf8').trimEnd().split('\n');
+    const start = lines.findLastIndex((line) => line === '{' || line === '[');
+    if (start >= 0)
+      try {
+        return JSON.stringify(JSON.parse(lines.slice(start).join('\n'))).slice(0, 500);
+      } catch {}
+    return lines.at(-1) || undefined;
+  } finally {
+    closeSync(fd);
+  }
+}
+
+export function agentStatus(config: AgentsConfig | undefined, options: AgentHostOptions = {}) {
+  const h = host(options);
+  const units = config
+    ? agentUnits(config, { home: h.home, execPath: options.execPath, cliPath: options.cliPath })
+    : [];
+  const declared = new Set(units.map((u) => u.label));
+  const labels = [...new Set([...declared, ...installedLabels(h.dir, h.platform)])].sort();
+  return labels.map((label) => ({
+    label,
+    declared: declared.has(label),
+    installed: existsSync(h.file(label)),
+    ...h.loaded(label),
+    lastOut: lastEntry(join(h.home, 'logs', `${label}.out.log`)),
+    lastErr: lastEntry(join(h.home, 'logs', `${label}.err.log`)),
+  }));
+}

package/src/cli.ts

@@ -1,12 +1,22 @@
 #!/usr/bin/env bun
 import { randomBytes } from 'node:crypto';
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
+import {
+  agentStatus,
+  defaultHistoryDirectory,
+  defaultHome,
+  installAgents,
+  readAgents,
+  uninstallAgents,
+  upsertCollector,
+  writeAgents,
+} from './agents';
 import { importChatGPTThread } from './chatgpt';
 import {
   archiveRequest,
+  kingdomFields,
   publishArchive,
   routingPreview,
   searchRemotes,
@@ -25,15 +35,17 @@ export async function runCli(args = Bun.argv.slice(2)) {
     args,
     allowPositionals: true,
     options: {
-      home: { type: 'string', default: join(homedir(), '.local/share/archive') },
+      home: { type: 'string', default: defaultHome() },
       store: { type: 'string' },
       config: { type: 'string' },
       url: { type: 'string' },
       kind: { type: 'string', default: 'archive' },
       'project-id': { type: 'string' },
-      'kastle-id': { type: 'string' },
-      'keep-id': { type: 'string', multiple: true },
-      'token-env': { type: 'string', default: 'ARCHIVE_TOKEN' },
+      'connection-id': { type: 'string' },
+      'owner-model': { type: 'string' },
+      'organization-id': { type: 'string' },
+      'space-id': { type: 'string' },
+      'token-env': { type: 'string' },
       'token-file': { type: 'string' },
       file: { type: 'string' },
       directory: { type: 'string' },
@@ -42,10 +54,13 @@ export async function runCli(args = Bun.argv.slice(2)) {
       'session-id': { type: 'string' },
       id: { type: 'string' },
       query: { type: 'string', default: '' },
-      'project-root': { type: 'string' },
+      'project-root': { type: 'string', multiple: true },
+      worktrees: { type: 'boolean', default: false },
+      atlas: { type: 'boolean', default: false },
       tag: { type: 'string', multiple: true },
       limit: { type: 'string', default: '100' },
-      port: { type: 'string', default: process.env.PORT ?? '4411' },
+      port: { type: 'string' },
+      name: { type: 'string' },
       hostname: { type: 'string', default: '127.0.0.1' },
       watch: { type: 'boolean', default: false },
       remote: { type: 'boolean', default: false },
@@ -60,12 +75,14 @@ export async function runCli(args = Bun.argv.slice(2)) {
   const command = positionals[0];
   if (v.help || !command) {
     console.log(
-      'Archive: init | serve | connect (setup) | preview | import | collect | list | export | tag | routes | sync | search\n' +
-        'connect --url HTTPS_URL --project-id ID --token-env ENV [--kind kingdom --kastle-id UUID]\n' +
+      'Archive: init | serve | connect (setup) | preview | import | collect | list | export | tag | routes | sync | search | agents\n' +
+        'connect --url HTTPS_URL --project-id ID (--token-env ENV | --token-file PATH) [--kind kingdom [--connection-id ID] [--owner-model M --organization-id UUID --space-id UUID]]\n' +
         'import --file PATH --source codex|claude-code --project-id ID [--tag TAG]\n' +
-        'collect --directory HISTORY --source codex|claude-code --project-root EXACT_CWD --project-id ID [--watch]\n' +
+        'collect --directory HISTORY --source codex|claude-code --project-root EXACT_CWD [--project-root ...] [--worktrees] [--atlas] --project-id ID [--watch]\n' +
         'sync [--watch] | routes | search --query TEXT [--remote]\n' +
         'serve --home PATH [--port 4411 --hostname 127.0.0.1]\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 | serve on|off [--port P] | sync on|off | install | uninstall | status\n' +
         'All commands accept --home PATH; integrations may use --store FILE --config FILE.',
     );
     return;
@@ -89,7 +106,7 @@ export async function runCli(args = Bun.argv.slice(2)) {
     const instance = startArchiveServer({
       store: storePath,
       token,
-      port: Number(v.port),
+      port: Number(v.port ?? process.env.PORT ?? 4411),
       hostname: v.hostname,
     });
     output({ listening: instance.server.url.href, store: storePath });
@@ -102,12 +119,21 @@ export async function runCli(args = Bun.argv.slice(2)) {
     return;
   }
   if (command === 'connect' || command === 'setup') {
+    const tokenFile = v['token-file'] && resolve(v['token-file']);
     const destination = archiveDestinationSchema.parse({
       projectId: v['project-id'],
       url: v.url,
-      tokenEnv: v['token-env'],
+      tokenEnv: v['token-env'] ?? (tokenFile ? undefined : 'ARCHIVE_TOKEN'),
+      tokenFile,
       kind: v.kind,
-      ...(v.kind === 'kingdom' ? { kastleId: v['kastle-id'], keepIds: v['keep-id'] ?? [] } : {}),
+      ...(v.kind === 'kingdom'
+        ? {
+            connectionId: v['connection-id'],
+            ownerModel: v['owner-model'],
+            organizationId: v['organization-id'],
+            spaceId: v['space-id'],
+          }
+        : {}),
     });
     // Verify credentials and protocol before saving; no records uploaded by setup.
     const probe = await archiveRequest(destination, 'search', {
@@ -116,13 +142,65 @@ export async function runCli(args = Bun.argv.slice(2)) {
       limit: 1,
       ...(destination.kind === 'archive'
         ? { projectId: destination.projectId }
-        : { kastleId: destination.kastleId }),
+        : kingdomFields(destination)),
     });
     if (!Array.isArray(probe.data?.archives))
       throw new Error('Destination is not an Archive-compatible endpoint');
     output(connectDestination(config, destination));
     return;
   }
+  if (command === 'agents') {
+    const file = join(home, 'agents.json');
+    const current = readAgents(file);
+    const [action, state] = positionals.slice(1);
+    const toggle = () => {
+      if (state !== 'on' && state !== 'off') throw new Error(`agents ${action} requires on|off`);
+      return state === 'on';
+    };
+    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 source = v.source as 'codex' | 'claude-code';
+      output(
+        writeAgents(
+          file,
+          upsertCollector(current, {
+            name: v.name,
+            source,
+            directory: resolve(v.directory ?? defaultHistoryDirectory(source)),
+            projectId: v['project-id'],
+            projectRoots: v['project-root'].map((root) => resolve(root)),
+            ...(v.worktrees ? { worktrees: true } : {}),
+            ...(v.atlas ? { atlas: true } : {}),
+          }),
+        ),
+      );
+    } else if (action === 'remove-collector') {
+      if (!v.name) throw new Error('remove-collector requires --name');
+      output(
+        writeAgents(file, {
+          ...base,
+          collectors: base.collectors.filter((c) => c.name !== v.name),
+        }),
+      );
+    } else if (action === 'serve') {
+      const { serve: _, ...rest } = base;
+      output(
+        writeAgents(
+          file,
+          toggle() ? { ...rest, serve: v.port ? { port: Number(v.port) } : {} } : rest,
+        ),
+      );
+    } else if (action === 'sync') output(writeAgents(file, { ...base, sync: toggle() }));
+    else if (action === 'install') {
+      if (!current) throw new Error('No agents.json; declare agents first');
+      output(installAgents(current, { home }));
+    } else if (action === 'uninstall') output(uninstallAgents({ home }));
+    else if (action === 'status') output(agentStatus(current, { home }));
+    else throw new Error('Unknown agents command; use --help');
+    return;
+  }
   if (command === 'preview') {
     if (
       Boolean(v.file) === Boolean(v.directory) ||
@@ -195,7 +273,9 @@ export async function runCli(args = Bun.argv.slice(2)) {
           const result = await collectSessions(store, {
             directory: v.directory!,
             source: v.source as 'codex' | 'claude-code',
-            projectRoot: v['project-root']!,
+            projectRoots: v['project-root']!,
+            worktrees: v.worktrees,
+            atlas: v.atlas,
             projectId: v['project-id']!,
             tags: v.tag,
           });

package/src/client.ts

@@ -2,12 +2,24 @@ import {
   type ArchiveDestination,
   archiveDestinationSchema,
   destinationIdentity,
+  destinationToken,
   destinationUrl,
 } from './config';
 import type { LocalArchiveStore } from './local';
 
 export { type ArchiveDestination, archiveDestinationSchema } from './config';
 
+/** Identifies the Kingdom owner and forwarding connection; standalone Archive needs neither. */
+export function kingdomFields(destination: ArchiveDestination) {
+  if (destination.kind === 'archive') return {};
+  const { ownerModel, organizationId, spaceId, connectionId } = destination;
+  return Object.fromEntries(
+    Object.entries({ ownerModel, organizationId, spaceId, connectionId }).filter(
+      ([, value]) => value !== undefined,
+    ),
+  );
+}
+
 export async function archiveRequest(
   destination: ArchiveDestination,
   action: string,
@@ -15,10 +27,12 @@ export async function archiveRequest(
   transport: typeof fetch = fetch,
 ) {
   const url = destinationUrl(destination.url);
-  const token = process.env[destination.tokenEnv];
-  if (!token || (destination.kind !== 'archive' && !token.startsWith('kastle_runtime_')))
+  const token = destinationToken(destination);
+  if (!token || (destination.kind === 'kingdom' && !token.startsWith('kastle_runtime_')))
     throw new Error('Archive runtime credential unavailable');
-  const response = await transport(new URL(`api/v1/archive/${action}`, url), {
+  const path =
+    destination.kind === 'kingdom' && destination.connectionId ? `remote/${action}` : action;
+  const response = await transport(new URL(`api/v1/archive/${path}`, url), {
     method: 'POST',
     redirect: 'error',
     signal: AbortSignal.timeout(30_000),
@@ -41,19 +55,14 @@ export async function publishArchive(
   if (!archive || archive.snapshot.projectId !== destination.projectId)
     throw new Error('Archive is outside destination project');
   const receiptKey = destinationIdentity(destination);
-  const keepIds = [...new Set(destination.keepIds)].sort();
   let sent = false;
   for (let attempt = 0; attempt < 8; attempt++) {
     const latest = store.read(id)!;
     const previousDigest = store.receipt(id, receiptKey);
     let pending = store.pending(id, receiptKey);
     if (!pending) {
-      if (
-        previousDigest === latest.digest &&
-        store.receipt(id, `${receiptKey}:keeps`) === JSON.stringify(keepIds)
-      )
-        return { unchanged: !sent };
-      store.enqueue(id, receiptKey, { revision: latest.revision, keepIds });
+      if (previousDigest === latest.digest) return { unchanged: !sent };
+      store.enqueue(id, receiptKey, { revision: latest.revision, keepIds: [] });
       pending = store.pending(id, receiptKey)!;
     }
     const queued = store.read(id, pending.revision);
@@ -63,16 +72,14 @@ export async function publishArchive(
       destination,
       'ingest',
       {
-        ...(destination.kind === 'archive'
-          ? {}
-          : { kastleId: destination.kastleId, keepIds: pending.keepIds }),
+        ...kingdomFields(destination),
         previousDigest,
         snapshot: queued.snapshot,
       },
       transport,
     );
     if (body.data?.digest !== queued.digest) throw new Error('Archive acknowledgement mismatch');
-    store.delivered(id, receiptKey, queued.digest, JSON.stringify(pending.keepIds));
+    store.delivered(id, receiptKey, queued.digest, '[]');
     sent = true;
   }
   throw new Error('Archive changed repeatedly during publication; retry sync');
@@ -87,9 +94,9 @@ export function routingPreview(store: LocalArchiveStore, destinations: ArchiveDe
     destinations: destinations
       .filter((d) => d.projectId === archive.projectId)
       .map((d) => ({
-        kind: d.kind ?? 'kingdom',
+        kind: d.kind,
         url: d.url,
-        ...(d.kind === 'archive' ? {} : { kastleId: d.kastleId }),
+        ...kingdomFields(d),
       })),
   }));
 }
@@ -129,7 +136,7 @@ export async function searchRemotes(
           budget,
           ...(destination.kind === 'archive'
             ? { projectId: destination.projectId }
-            : { kastleId: destination.kastleId }),
+            : kingdomFields(destination)),
         });
         return {
           destination: destination.url,

package/src/collector.ts

@@ -1,15 +1,19 @@
-import { createReadStream, lstatSync, readdirSync } from 'node:fs';
-import { isAbsolute, join, relative, resolve } from 'node:path';
-import { createInterface } from 'node:readline';
+import { closeSync, existsSync, lstatSync, openSync, readdirSync, readSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
 import { importTranscriptFile } from './import-file';
 import { archiveKey } from './index';
 import type { LocalArchiveStore } from './local';
+import { type AtlasFileConcepts, atlasTags, provenanceTags } from './tags';
 
 export interface CollectionSource {
   directory: string;
   source: 'codex' | 'claude-code';
-  projectRoot: string;
+  projectRoots: string[];
   projectId: string;
+  /** Also match the git worktrees of each root; nested checkouts stay separate. */
+  worktrees?: boolean;
+  /** Tag sessions with the Atlas concepts of files they touched, from `atlas graph` in the session's checkout. */
+  atlas?: boolean;
   tags?: string[];
 }
 
@@ -25,36 +29,88 @@ function files(directory: string): string[] {
   return result;
 }
 
+type SessionMetadata = { cwd: string; branch?: string; repository?: string };
+
 /** Match provider metadata, never text/tags/model suggestions. No implicit parent-directory routing. */
-async function sessionDirectory(file: string, source: CollectionSource['source']) {
-  const input = createReadStream(file, { encoding: 'utf8', end: 1_000_000 });
-  const lines = createInterface({ input, crlfDelay: Infinity });
+function sessionMetadata(
+  file: string,
+  source: CollectionSource['source'],
+): SessionMetadata | undefined {
+  // A bounded synchronous read: streamed readline could leave a watch loop waiting forever.
+  const buffer = Buffer.alloc(Math.min(lstatSync(file).size, 1_000_000));
+  const fd = openSync(file, 'r');
   try {
-    for await (const line of lines) {
-      let row: any;
-      try {
-        row = JSON.parse(line);
-      } catch {
-        return undefined;
-      }
-      const cwd =
-        source === 'codex' ? (row.type === 'session_meta' ? row.payload?.cwd : undefined) : row.cwd;
-      if (typeof cwd === 'string' && isAbsolute(cwd)) return resolve(cwd);
-    }
+    readSync(fd, buffer, 0, buffer.length, 0);
   } finally {
-    lines.close();
-    input.destroy();
+    closeSync(fd);
+  }
+  for (const line of buffer.toString('utf8').split('\n')) {
+    if (!line) continue;
+    let row: any;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      return undefined;
+    }
+    const meta = source === 'codex' ? (row.type === 'session_meta' ? row.payload : undefined) : row;
+    if (typeof meta?.cwd !== 'string' || !isAbsolute(meta.cwd)) continue;
+    const text = (value: unknown) => (typeof value === 'string' && value ? value : undefined);
+    return source === 'codex'
+      ? {
+          cwd: resolve(meta.cwd),
+          branch: text(meta.git?.branch),
+          repository: text(meta.git?.repository_url),
+        }
+      : { cwd: resolve(meta.cwd), branch: text(meta.gitBranch) };
   }
 }
 
+const git = (cwd: string, ...args: string[]) => {
+  const run = Bun.spawnSync(['git', '-C', cwd, ...args], { stderr: 'ignore' });
+  return run.success ? run.stdout.toString().trim() : undefined;
+};
+
+function atlasGraph(cwd: string): AtlasFileConcepts | undefined {
+  if (!existsSync(`${cwd}/.atlas`)) return;
+  const run = Bun.spawnSync([process.execPath, 'x', 'atlas', 'graph', '--json'], {
+    cwd,
+    stderr: 'ignore',
+  });
+  if (!run.success) return;
+  try {
+    return JSON.parse(run.stdout.toString()).fileToConcepts;
+  } catch {}
+}
+
+function worktreesOf(root: string): string[] {
+  const listed = Bun.spawnSync(['git', '-C', root, 'worktree', 'list', '--porcelain'], {
+    stderr: 'ignore',
+  });
+  if (!listed.success) return [];
+  return listed.stdout
+    .toString()
+    .split('\n')
+    .filter((line) => line.startsWith('worktree '))
+    .map((line) => resolve(line.slice('worktree '.length)));
+}
+
+/** 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));
+  return new Set(config.worktrees ? [...roots, ...roots.flatMap(worktreesOf)] : roots);
+}
+
 export async function collectSessions(store: LocalArchiveStore, config: CollectionSource) {
-  const root = resolve(config.projectRoot);
+  const roots = collectionRoots(config);
   const result = { imported: 0, unchanged: 0, skipped: 0, failed: 0 };
+  // Per scan: checkouts change between scans.
+  const repositories = new Map<string, string | undefined>();
+  const graphs = new Map<string, AtlasFileConcepts | undefined>();
   for (const file of files(config.directory)) {
     try {
-      const cwd = await sessionDirectory(file, config.source);
+      const meta = sessionMetadata(file, config.source);
       // Exact root selection avoids sweeping nested checkouts belonging to another organization.
-      if (!cwd || relative(root, cwd) !== '') {
+      if (!meta || !roots.has(meta.cwd)) {
         result.skipped++;
         continue;
       }
@@ -74,7 +130,21 @@ export async function collectSessions(store: LocalArchiveStore, config: Collecti
         result.failed++;
         continue;
       }
-      snapshot.tags = [...new Set([...(old?.snapshot.tags ?? []), ...(config.tags ?? [])])];
+      const { cwd } = meta;
+      if (!repositories.has(cwd)) repositories.set(cwd, git(cwd, 'remote', 'get-url', 'origin'));
+      if (config.atlas && !graphs.has(cwd)) graphs.set(cwd, atlasGraph(cwd));
+      const graph = graphs.get(cwd);
+      snapshot.tags = [
+        ...new Set([
+          ...(old?.snapshot.tags ?? []),
+          ...(config.tags ?? []),
+          ...provenanceTags({
+            branch: meta.branch,
+            repository: meta.repository ?? repositories.get(cwd),
+          }),
+          ...(graph ? atlasTags(snapshot, graph, roots) : []),
+        ]),
+      ].slice(0, 100);
       if (store.capture(snapshot).changed) result.imported++;
       else result.unchanged++;
     } catch {

package/src/config.ts

@@ -1,28 +1,74 @@
 import { randomUUID } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import {
+  chmodSync,
+  closeSync,
+  constants,
+  existsSync,
+  fstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, isAbsolute } from 'node:path';
 import { z } from 'zod';
 
 const common = {
   projectId: z.string().min(1).max(256),
   url: z.url(),
-  tokenEnv: z.string().regex(/^[A-Z][A-Z0-9_]+$/),
+  tokenEnv: z
+    .string()
+    .regex(/^[A-Z][A-Z0-9_]+$/)
+    .optional(),
+  tokenFile: z.string().max(4096).refine(isAbsolute, 'tokenFile must be absolute').optional(),
 };
-export const archiveDestinationSchema = z.union([
-  z.strictObject({
-    ...common,
-    kind: z.literal('archive'),
-    keepIds: z.array(z.string()).max(0).default([]),
-  }),
-  z.strictObject({
-    ...common,
-    kind: z.literal('kingdom').optional(),
-    kastleId: z.uuid(),
-    keepIds: z.array(z.uuid()).max(50).default([]),
-  }),
-]);
+/** Kingdom derives the owner from the runtime credential; these narrow it to a space or organization it manages. */
+export const kingdomOwnerFields = {
+  ownerModel: z.enum(['User', 'OrganizationUser', 'Organization', 'Space', 'SpaceUser']).optional(),
+  organizationId: z.uuid().optional(),
+  spaceId: z.uuid().optional(),
+};
+export const archiveDestinationSchema = z
+  .union([
+    z.strictObject({
+      ...common,
+      kind: z.literal('archive'),
+      keepIds: z.array(z.string()).max(0).optional(),
+    }),
+    z.strictObject({
+      ...common,
+      kind: z.literal('kingdom'),
+      /** A hosted Archive that Kingdom forwards to; omitted, Kingdom stores the archive itself. */
+      connectionId: z
+        .string()
+        .regex(/^[a-z0-9-]+$/)
+        .max(120)
+        .optional(),
+      ...kingdomOwnerFields,
+    }),
+  ])
+  .refine(
+    (d) => Boolean(d.tokenEnv) !== Boolean(d.tokenFile),
+    'Set exactly one of tokenEnv or tokenFile',
+  );
 export type ArchiveDestination = z.infer<typeof archiveDestinationSchema>;
 
+/** Private regular file owned by this user; a symlink or group/world access is refused. */
+export function readTokenFile(path: string) {
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.uid !== process.getuid?.() || stat.mode & 0o077)
+      throw new Error('Token file must be a regular file owned by you with mode 0600');
+    return readFileSync(fd, 'utf8').trim();
+  } finally {
+    closeSync(fd);
+  }
+}
+export const destinationToken = (destination: ArchiveDestination) =>
+  destination.tokenFile ? readTokenFile(destination.tokenFile) : process.env[destination.tokenEnv!];
+
 export function destinationUrl(input: string) {
   const url = new URL(input);
   if (
@@ -52,7 +98,14 @@ export function destinationIdentity(destination: ArchiveDestination) {
   return JSON.stringify([
     url.origin,
     new URL(destination.url).pathname,
-    destination.kind === 'archive' ? 'standalone' : destination.kastleId,
+    destination.kind === 'archive'
+      ? 'standalone'
+      : [
+          destination.connectionId ?? 'kingdom',
+          destination.ownerModel ?? null,
+          destination.organizationId ?? null,
+          destination.spaceId ?? null,
+        ],
   ]);
 }
 export function connectDestination(file: string, input: unknown) {
@@ -72,9 +125,11 @@ export function connectDestination(file: string, input: unknown) {
   chmodSync(file, 0o600);
   return {
     configured: true,
-    kind: destination.kind ?? 'kingdom',
+    kind: destination.kind,
     projectId: destination.projectId,
     url: destination.url,
-    tokenEnv: destination.tokenEnv,
+    ...(destination.tokenFile
+      ? { tokenFile: destination.tokenFile }
+      : { tokenEnv: destination.tokenEnv }),
   };
 }

package/src/import.ts

@@ -40,8 +40,13 @@ export function importTranscriptLines(
       sessionId ??= id;
     }
     if (options.source === 'claude-code' && row.sessionId) {
-      if (sessionId && sessionId !== row.sessionId) throw new Error('Mixed transcript sessions');
-      sessionId = row.sessionId;
+      // Subagent transcripts reuse their parent's sessionId; each is its own archive.
+      const id =
+        row.isSidechain && typeof row.agentId === 'string'
+          ? `${row.sessionId}/agent-${row.agentId}`
+          : row.sessionId;
+      if (sessionId && sessionId !== id) throw new Error('Mixed transcript sessions');
+      sessionId = id;
     }
     const timestamp = typeof row.timestamp === 'number' ? row.timestamp : Date.parse(row.timestamp);
     const add = (kind: ArchiveEntry['kind'], content: unknown, suffix: string, callId?: string) => {

package/src/local.ts

@@ -7,11 +7,11 @@ import {
   type ArchiveSnapshot,
   archiveKey,
   archiveSnapshotSchema,
-  categorySuggestions,
   chunkArchive,
   selectChunks,
   snapshotDigest,
 } from './index';
+import { suggestTags } from './tags';
 
 export class LocalArchiveStore {
   private readonly db: Database;
@@ -94,7 +94,7 @@ export class LocalArchiveStore {
         digest: archive.digest,
         ...snapshot,
         entries: entries.length,
-        suggestedTags: categorySuggestions(archive.snapshot),
+        suggestedTags: suggestTags(archive.snapshot),
       };
     });
   }

package/src/tags.ts

@@ -0,0 +1,78 @@
+import { type ArchiveSnapshot, categorySuggestions } from './index';
+
+export type TagSuggestion = { tag: string; origin: 'heuristic' | 'reference' };
+
+const references: [RegExp, (match: RegExpExecArray) => string][] = [
+  [
+    /github\.com\/([\w.-]+)\/([\w.-]+)\/(?:pull|issues)\/(\d+)/g,
+    (m) => `github:${m[1]}/${m[2]}#${m[3]}`.toLowerCase(),
+  ],
+  [
+    /github\.com\/([\w.-]+)\/([\w.-]+)\/commit\/([0-9a-f]{7,40})\b/g,
+    (m) => `github:${m[1]}/${m[2]}@${m[3].slice(0, 7)}`.toLowerCase(),
+  ],
+  [
+    /linear\.app\/[\w-]+\/issue\/([A-Za-z][A-Za-z0-9]*-\d+)/g,
+    (m) => `linear:${m[1].toUpperCase()}`,
+  ],
+];
+
+/** Issues, pull requests and commits the transcript links to, most-referenced first. A mention is not proof of work, so these stay suggestions. */
+export function referenceSuggestions(snapshot: ArchiveSnapshot, limit = 25): TagSuggestion[] {
+  const counts = new Map<string, number>();
+  for (const entry of snapshot.entries)
+    for (const [pattern, tag] of references)
+      for (const match of entry.text.matchAll(pattern)) {
+        const value = tag(match);
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+      }
+  return [...counts]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([tag]) => ({ tag, origin: 'reference' }));
+}
+
+/** Every computed suggestion for an archive. Suggestions never route or authorize. */
+export function suggestTags(snapshot: ArchiveSnapshot): TagSuggestion[] {
+  return [...categorySuggestions(snapshot), ...referenceSuggestions(snapshot)];
+}
+
+/** Recorded git context of a session, as explicit tags. */
+export function provenanceTags(context: { repository?: string; branch?: string }): string[] {
+  const repository = context.repository?.match(/github\.com[:/]([\w.-]+\/[\w.-]+?)(?:\.git)?\/?$/);
+  return [
+    ...(repository ? [`repo:${repository[1].toLowerCase()}`] : []),
+    ...(context.branch && context.branch !== 'HEAD' ? [`branch:${context.branch}`] : []),
+  ].filter((tag) => tag.length <= 120);
+}
+
+/** `atlas graph --json`: repository-relative file paths to the concepts they are part of. */
+export type AtlasFileConcepts = Record<string, { partOf: string[] }>;
+
+/** Atlas concepts of the repository files a session's tool calls touched. */
+export function atlasTags(
+  snapshot: ArchiveSnapshot,
+  fileToConcepts: AtlasFileConcepts,
+  roots: Iterable<string>,
+  limit = 20,
+): string[] {
+  // Longest first: worktrees can live inside their main checkout.
+  const prefixes = [...roots]
+    .map((root) => `${root.replace(/\/+$/, '')}/`)
+    .sort((a, b) => b.length - a.length);
+  const counts = new Map<string, number>();
+  for (const entry of snapshot.entries) {
+    if (entry.kind !== 'tool-call') continue;
+    for (const [path] of entry.text.matchAll(/[\w@.~/-]+\.[A-Za-z]{1,6}\b/g)) {
+      const prefix = prefixes.find((candidate) => path.startsWith(candidate));
+      const relative = prefix ? path.slice(prefix.length) : path;
+      for (const concept of fileToConcepts[relative]?.partOf ?? [])
+        counts.set(concept, (counts.get(concept) ?? 0) + 1);
+    }
+  }
+  return [...counts]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, limit)
+    .map(([concept]) => `atlas:${concept}`)
+    .filter((tag) => tag.length <= 120);
+}