@inixiative/archive 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Inixiative
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# Archive
+
+MIT-licensed, local-first session storage for Claude Code, Codex and Foundry. Run it independently or connect through Foundry and Kingdom/Kastles.
+
+## What runs today
+
+- Public transcript extraction, exact-project collection, immutable SQLite revisions, local lexical search and lossless text chunks.
+- A standalone authenticated HTTP server, Docker image, persistent Compose deployment, Railway configuration and a Render blueprint.
+- Multiple explicit destinations, durable publication receipts/outbox, conflict detection and retry after interruption.
+- Native Foundry capture and context retrieval; Kingdom's existing Archives browser, ownership and sharing APIs.
+
+This is an initial pilot, not a general multi-user standalone hosting service. Each standalone deployment is one ownership boundary with one access token. Kingdom supplies account-based sharing. Use distinct storage and credentials for personal and organization archives.
+
+## Local setup
+
+Install Bun 1.4.2 or later, then install the published CLI:
+
+```sh
+bun add --global @inixiative/archive
+archive init
+archive serve
+```
+
+For development from source:
+
+```sh
+bun install
+bun run archive init
+bun run archive serve
+```
+
+`init` creates a local database and a private `server.token` under `~/.local/share/archive`. It prints the token's file path, never its value. `serve` binds to loopback port 4411. The server requires bearer authentication for data endpoints; `/health` has no session data.
+
+```sh
+bun run archive preview --directory /path/to/history --source codex
+bun run archive import --file /path/to/session.jsonl --source codex --project-id inixiative --tag coding
+bun run archive collect --directory /path/to/history --source codex --project-root /exact/session/cwd --project-id inixiative --watch
+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.
+
+## 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.
+
+Place the destination's token in 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 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.
+
+`--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.
+
+## Connect through Kingdom
+
+Use Kingdom's existing runtime enrollment for a user who manages the destination Kastle, then:
+
+```sh
+bun run archive connect --kind kingdom --url https://your-kingdom.example --kastle-id UUID --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.
+
+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.
+
+## Routing, tagging and Jev
+
+Only explicit `projectId` matches authorize publication. An archive with no matching destination stays local. Multiple matches create deliberate separate copies. `routes` previews these destinations before upload.
+
+```sh
+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.
+
+## Limits
+
+- Public text/tool records only; no reconstruction of private reasoning or unsupported media. Coverage accompanies each snapshot.
+- No automatic secret scrubber. Publication includes recorded public session content.
+- Sync currently publishes local records to destinations; it does not mirror remote records locally or propagate deletions.
+- Local search budgets are per session; hosted search budgets are across a response. Remote search queries every configured route; each response identifies its destination.
+- No automatic remote deletion when routing changes. Existing copies keep their original owner's access rules.
+- Deployment credentials, operational receipts and machine-specific routing belong outside the repository.
+
+## Development
+
+```sh
+bun test
+bun run typecheck
+```
+
+See [provenance](docs/PROVENANCE.md), [license](LICENSE), and [goals](tickets/README.md). The historical tickets describe earlier scope; this implementation now includes explicit provider collection and authenticated standalone hosting.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@inixiative/archive",
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./local": "./src/local.ts",
+    "./import": "./src/import.ts",
+    "./client": "./src/client.ts",
+    "./config": "./src/config.ts",
+    "./server": "./src/server.ts",
+    "./import-file": "./src/import-file.ts",
+    "./preview": "./src/preview.ts",
+    "./cli": "./src/cli.ts",
+    "./collector": "./src/collector.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "bun test tests",
+    "typecheck": "tsc --noEmit",
+    "archive": "bun run src/cli.ts",
+    "start": "bun run src/cli.ts serve",
+    "check": "bun run typecheck && bun run lint && bun run test",
+    "prepublishOnly": "bun run check",
+    "lint": "biome check .",
+    "prepare": "lefthook install"
+  },
+  "dependencies": {
+    "js-tiktoken": "1.0.21",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.2",
+    "typescript": "6.0.3",
+    "@biomejs/biome": "2.5.2",
+    "@inixiative/config": "^0.5.33",
+    "lefthook": "2.1.9"
+  },
+  "bin": {
+    "archive": "src/cli.ts"
+  },
+  "license": "MIT",
+  "description": "Portable Claude Code, Codex and Foundry session archives: extraction, local storage, search and hosted sync",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/inixiative/archive.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.4.2"
+  },
+  "packageManager": "bun@1.4.2"
+}

package/src/cli.ts

@@ -0,0 +1,238 @@
+#!/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 {
+  archiveRequest,
+  publishArchive,
+  routingPreview,
+  searchRemotes,
+  syncArchives,
+} from './client';
+import { collectSessions } from './collector';
+import { archiveDestinationSchema, connectDestination, readDestinations } from './config';
+import { importTranscriptFile } from './import-file';
+import { archiveKey } from './index';
+import { LocalArchiveStore } from './local';
+import { previewImports } from './preview';
+import { startArchiveServer } from './server';
+
+export async function runCli(args = Bun.argv.slice(2)) {
+  const { values: v, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    options: {
+      home: { type: 'string', default: join(homedir(), '.local/share/archive') },
+      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' },
+      'token-file': { type: 'string' },
+      file: { type: 'string' },
+      directory: { type: 'string' },
+      source: { type: 'string' },
+      title: { type: 'string' },
+      'session-id': { type: 'string' },
+      id: { type: 'string' },
+      query: { type: 'string', default: '' },
+      'project-root': { type: 'string' },
+      tag: { type: 'string', multiple: true },
+      limit: { type: 'string', default: '100' },
+      port: { type: 'string', default: process.env.PORT ?? '4411' },
+      hostname: { type: 'string', default: '127.0.0.1' },
+      watch: { type: 'boolean', default: false },
+      remote: { type: 'boolean', default: false },
+      destination: { type: 'string' },
+      help: { type: 'boolean' },
+    },
+  });
+  const home = resolve(v.home!),
+    config = v.config ?? join(home, 'destinations.json');
+  const storePath = v.store ?? join(home, 'archives.sqlite');
+  const output = (value: unknown) => console.log(JSON.stringify(value, null, 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' +
+        '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' +
+        'sync [--watch] | routes | search --query TEXT [--remote]\n' +
+        'serve --home PATH [--port 4411 --hostname 127.0.0.1]\n' +
+        'All commands accept --home PATH; integrations may use --store FILE --config FILE.',
+    );
+    return;
+  }
+  if (command === 'init') {
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    const tokenFile = join(home, 'server.token');
+    if (!existsSync(tokenFile))
+      writeFileSync(tokenFile, randomBytes(32).toString('hex') + '\n', { mode: 0o600, flag: 'wx' });
+    chmodSync(tokenFile, 0o600);
+    const store = new LocalArchiveStore(storePath);
+    store.close();
+    output({ initialized: true, home, store: storePath, tokenFile });
+    return;
+  }
+  if (command === 'serve') {
+    const tokenFile = v['token-file'] ?? join(home, 'server.token');
+    const token =
+      process.env.ARCHIVE_SERVER_TOKEN ??
+      (existsSync(tokenFile) ? readFileSync(tokenFile, 'utf8').trim() : '');
+    const instance = startArchiveServer({
+      store: storePath,
+      token,
+      port: Number(v.port),
+      hostname: v.hostname,
+    });
+    output({ listening: instance.server.url.href, store: storePath });
+    const stop = async () => {
+      await instance.close();
+      process.exit(0);
+    };
+    process.once('SIGTERM', stop);
+    process.once('SIGINT', stop);
+    return;
+  }
+  if (command === 'connect' || command === 'setup') {
+    const destination = archiveDestinationSchema.parse({
+      projectId: v['project-id'],
+      url: v.url,
+      tokenEnv: v['token-env'],
+      kind: v.kind,
+      ...(v.kind === 'kingdom' ? { kastleId: v['kastle-id'], keepIds: v['keep-id'] ?? [] } : {}),
+    });
+    // Verify credentials and protocol before saving; no records uploaded by setup.
+    const probe = await archiveRequest(destination, 'search', {
+      query: '',
+      budget: 16,
+      limit: 1,
+      ...(destination.kind === 'archive'
+        ? { projectId: destination.projectId }
+        : { kastleId: destination.kastleId }),
+    });
+    if (!Array.isArray(probe.data?.archives))
+      throw new Error('Destination is not an Archive-compatible endpoint');
+    output(connectDestination(config, destination));
+    return;
+  }
+  if (command === 'preview') {
+    if (
+      Boolean(v.file) === Boolean(v.directory) ||
+      !['codex', 'claude-code'].includes(v.source ?? '')
+    )
+      throw new Error('Preview requires one --file or --directory and --source codex|claude-code');
+    output(
+      previewImports(v.file ?? v.directory!, v.source as 'codex' | 'claude-code', Number(v.limit)),
+    );
+    return;
+  }
+  if (command === 'search' && v.remote) {
+    const results = await searchRemotes(readDestinations(config), v.query!);
+    output(results);
+    if (results.some((r) => 'error' in r)) process.exitCode = 1;
+    return;
+  }
+  const store = new LocalArchiveStore(storePath);
+  try {
+    if (command === 'import') {
+      if (!v.file || !['codex', 'claude-code'].includes(v.source ?? '') || !v['project-id'])
+        throw new Error('Import requires --file, --source codex|claude-code and --project-id');
+      const snapshot = importTranscriptFile(v.file, {
+        source: v.source as 'codex' | 'claude-code',
+        sourceId: store.sourceId,
+        projectId: v['project-id'],
+        sessionId: v['session-id'],
+        title: v.title,
+      });
+      snapshot.tags = [
+        ...new Set([...(store.read(archiveKey(snapshot))?.snapshot.tags ?? []), ...(v.tag ?? [])]),
+      ];
+      output({
+        ...store.capture(snapshot),
+        entries: snapshot.entries.length,
+        coverage: snapshot.coverage,
+      });
+    } else if (command === 'list') output(store.list());
+    else if (command === 'routes') output(routingPreview(store, readDestinations(config)));
+    else if (command === 'sync' || command === 'collect') {
+      if (
+        command === 'collect' &&
+        (!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');
+      let stopped = false;
+      const stop = () => {
+        stopped = true;
+      };
+      process.once('SIGINT', stop);
+      process.once('SIGTERM', stop);
+      do {
+        if (command === 'collect') {
+          const result = await collectSessions(store, {
+            directory: v.directory!,
+            source: v.source as 'codex' | 'claude-code',
+            projectRoot: v['project-root']!,
+            projectId: v['project-id']!,
+            tags: v.tag,
+          });
+          output(result);
+          if (!v.watch && result.failed) process.exitCode = 1;
+        } else {
+          const results = await syncArchives(store, readDestinations(config));
+          output(results);
+          if (!v.watch && results.some((r) => r.status.startsWith('failed'))) process.exitCode = 1;
+        }
+        if (v.watch && !stopped) await Bun.sleep(1000);
+        // Short waits allow prompt shutdown; network requests have their own timeout.
+        for (let i = 1; v.watch && !stopped && i < 30; i++) await Bun.sleep(1000);
+      } while (v.watch && !stopped);
+      process.removeListener('SIGINT', stop);
+      process.removeListener('SIGTERM', stop);
+    } else if (command === 'publish') {
+      if (!v.id || !v.destination) throw new Error('Publish requires --id and --destination');
+      output(
+        await publishArchive(
+          store,
+          v.id,
+          archiveDestinationSchema.parse(JSON.parse(readFileSync(v.destination, 'utf8'))),
+        ),
+      );
+    } else if (command === 'search')
+      output(store.search(v.id ? [v.id] : store.list().map((a) => a.id), v.query!));
+    else if (command === 'export' || command === 'tag') {
+      const archive = v.id ? store.read(v.id) : undefined;
+      if (!archive) throw new Error('Valid --id required');
+      if (command === 'export') output(archive.snapshot);
+      else {
+        if (!v.tag?.length) throw new Error('Tag requires at least one --tag');
+        output(
+          store.capture({
+            ...archive.snapshot,
+            capturedAt: Date.now(),
+            tags: [...new Set([...archive.snapshot.tags, ...v.tag])],
+          }),
+        );
+      }
+    } else throw new Error('Unknown command; use --help');
+  } finally {
+    store.close();
+  }
+}
+
+if (import.meta.main)
+  runCli().catch(() => {
+    console.error(
+      'Archive command failed. Check arguments, destination access and local paths. Use --help for usage.',
+    );
+    process.exitCode = 1;
+  });

package/src/client.ts

@@ -0,0 +1,148 @@
+import {
+  type ArchiveDestination,
+  archiveDestinationSchema,
+  destinationIdentity,
+  destinationUrl,
+} from './config';
+import type { LocalArchiveStore } from './local';
+
+export { type ArchiveDestination, archiveDestinationSchema } from './config';
+
+export async function archiveRequest(
+  destination: ArchiveDestination,
+  action: string,
+  body: unknown,
+  transport: typeof fetch = fetch,
+) {
+  const url = destinationUrl(destination.url);
+  const token = process.env[destination.tokenEnv];
+  if (!token || (destination.kind !== 'archive' && !token.startsWith('kastle_runtime_')))
+    throw new Error('Archive runtime credential unavailable');
+  const response = await transport(new URL(`api/v1/archive/${action}`, url), {
+    method: 'POST',
+    redirect: 'error',
+    signal: AbortSignal.timeout(30_000),
+    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  if (!response.ok)
+    throw new Error(`Archive request rejected (${response.status}); local archive retained`);
+  return response.json() as Promise<{ data: any }>;
+}
+
+export async function publishArchive(
+  store: LocalArchiveStore,
+  id: string,
+  input: ArchiveDestination,
+  transport: typeof fetch = fetch,
+) {
+  const destination = archiveDestinationSchema.parse(input);
+  const archive = store.read(id);
+  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 });
+      pending = store.pending(id, receiptKey)!;
+    }
+    const queued = store.read(id, pending.revision);
+    if (!queued || queued.snapshot.projectId !== destination.projectId)
+      throw new Error('Pending archive is outside destination project');
+    const body = await archiveRequest(
+      destination,
+      'ingest',
+      {
+        ...(destination.kind === 'archive'
+          ? {}
+          : { kastleId: destination.kastleId, keepIds: pending.keepIds }),
+        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));
+    sent = true;
+  }
+  throw new Error('Archive changed repeatedly during publication; retry sync');
+}
+
+export function routingPreview(store: LocalArchiveStore, destinations: ArchiveDestination[]) {
+  return store.list().map((archive) => ({
+    id: archive.id,
+    projectId: archive.projectId,
+    tags: archive.tags,
+    suggestedTags: archive.suggestedTags,
+    destinations: destinations
+      .filter((d) => d.projectId === archive.projectId)
+      .map((d) => ({
+        kind: d.kind ?? 'kingdom',
+        url: d.url,
+        ...(d.kind === 'archive' ? {} : { kastleId: d.kastleId }),
+      })),
+  }));
+}
+
+export async function syncArchives(store: LocalArchiveStore, destinations: ArchiveDestination[]) {
+  const results: { id: string; destination: string; status: string }[] = [];
+  for (const archive of store.list())
+    for (const destination of destinations.filter((d) => d.projectId === archive.projectId)) {
+      try {
+        const result = await publishArchive(store, archive.id, destination);
+        results.push({
+          id: archive.id,
+          destination: destination.url,
+          status: result.unchanged ? 'unchanged' : 'published',
+        });
+      } catch {
+        results.push({
+          id: archive.id,
+          destination: destination.url,
+          status: 'failed; local revision retained',
+        });
+      }
+    }
+  return results;
+}
+
+export async function searchRemotes(
+  destinations: ArchiveDestination[],
+  query: string,
+  budget = 2048,
+) {
+  return Promise.all(
+    destinations.map(async (destination) => {
+      try {
+        const result = await archiveRequest(destination, 'search', {
+          query,
+          budget,
+          ...(destination.kind === 'archive'
+            ? { projectId: destination.projectId }
+            : { kastleId: destination.kastleId }),
+        });
+        return {
+          destination: destination.url,
+          projectId: destination.projectId,
+          data: result.data,
+        };
+      } catch {
+        return {
+          destination: destination.url,
+          projectId: destination.projectId,
+          error: 'Remote unavailable',
+        };
+      }
+    }),
+  );
+}

package/src/collector.ts

@@ -0,0 +1,85 @@
+import { createReadStream, lstatSync, readdirSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { importTranscriptFile } from './import-file';
+import { archiveKey } from './index';
+import type { LocalArchiveStore } from './local';
+
+export interface CollectionSource {
+  directory: string;
+  source: 'codex' | 'claude-code';
+  projectRoot: string;
+  projectId: string;
+  tags?: string[];
+}
+
+function files(directory: string): string[] {
+  const result: string[] = [];
+  const visit = (path: string) => {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) return;
+    if (stat.isDirectory()) for (const name of readdirSync(path).sort()) visit(join(path, name));
+    else if (stat.isFile() && path.endsWith('.jsonl')) result.push(path);
+  };
+  visit(resolve(directory));
+  return result;
+}
+
+/** 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 });
+  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);
+    }
+  } finally {
+    lines.close();
+    input.destroy();
+  }
+}
+
+export async function collectSessions(store: LocalArchiveStore, config: CollectionSource) {
+  const root = resolve(config.projectRoot);
+  const result = { imported: 0, unchanged: 0, skipped: 0, failed: 0 };
+  for (const file of files(config.directory)) {
+    try {
+      const cwd = await sessionDirectory(file, config.source);
+      // Exact root selection avoids sweeping nested checkouts belonging to another organization.
+      if (!cwd || relative(root, cwd) !== '') {
+        result.skipped++;
+        continue;
+      }
+      const before = lstatSync(file);
+      const snapshot = importTranscriptFile(file, {
+        source: config.source,
+        sourceId: store.sourceId,
+        projectId: config.projectId,
+      });
+      const after = lstatSync(file);
+      if (before.size !== after.size || before.mtimeMs !== after.mtimeMs) {
+        result.skipped++;
+        continue;
+      }
+      const old = store.read(archiveKey(snapshot));
+      if (old && old.snapshot.projectId !== config.projectId) {
+        result.failed++;
+        continue;
+      }
+      snapshot.tags = [...new Set([...(old?.snapshot.tags ?? []), ...(config.tags ?? [])])];
+      if (store.capture(snapshot).changed) result.imported++;
+      else result.unchanged++;
+    } catch {
+      result.failed++;
+    } // Partial/malformed files remain intact and retry on the next scan.
+  }
+  return result;
+}