@cmetech/otto 1.1.0 → 1.2.4

package/packages/coworker-artifacts/src/artifact-store.test.ts

@@ -0,0 +1,188 @@
+// packages/coworker-artifacts/src/artifact-store.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, existsSync, readFileSync, readdirSync, statSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ArtifactStore } from './artifact-store.js';
+import { ArtifactKindRejected, ArtifactNotFound, ArtifactSlugCollision } from './errors.js';
+
+function tmpWs(): string {
+  return mkdtempSync(join(tmpdir(), 'art-store-'));
+}
+
+function fixedNow(): () => string {
+  let n = Date.parse('2026-06-02T14:00:00Z');
+  return () => {
+    const v = new Date(n).toISOString();
+    n += 60_000;
+    return v;
+  };
+}
+
+describe('ArtifactStore.create', () => {
+  it('creates dir + metadata + empty primary + initial provenance + README', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    const h = await store.create('report', 'RCA: load balancer 503');
+    assert.equal(h.slug, 'rca-load-balancer-503');
+    assert.equal(h.kind, 'report');
+    assert.equal(h.uri, 'artifact://rca-load-balancer-503');
+    assert.ok(existsSync(h.dir));
+    assert.ok(existsSync(h.primaryPath));
+    assert.ok(existsSync(h.metadataPath));
+    assert.ok(existsSync(h.provenancePath));
+    assert.ok(existsSync(h.readmePath));
+    const meta = JSON.parse(readFileSync(h.metadataPath, 'utf8'));
+    assert.equal(meta._schema, 1);
+    assert.equal(meta.slug, 'rca-load-balancer-503');
+    assert.equal(meta.kind, 'report');
+    assert.equal(meta.primary_file, 'report.md');
+    assert.equal(meta.turn_count, 0);
+  });
+  it('rejects non-report kind', async () => {
+    const store = new ArtifactStore({ workspaceDir: tmpWs() });
+    await assert.rejects(() => store.create('workbook' as never, 'x'), ArtifactKindRejected);
+  });
+  it('suffixes slug on collision', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    const a = await store.create('report', 'RCA');
+    const b = await store.create('report', 'RCA');
+    const c = await store.create('report', 'RCA');
+    assert.equal(a.slug, 'rca');
+    assert.equal(b.slug, 'rca-2');
+    assert.equal(c.slug, 'rca-3');
+  });
+  it('throws ArtifactSlugCollision after exhausting suffixes', async () => {
+    const ws = tmpWs();
+    mkdirSync(join(ws, '.otto', 'artifacts'), { recursive: true });
+    mkdirSync(join(ws, '.otto', 'artifacts', 'rca'));
+    for (let n = 2; n <= 101; n++) mkdirSync(join(ws, '.otto', 'artifacts', `rca-${n}`));
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    await assert.rejects(() => store.create('report', 'RCA'), ArtifactSlugCollision);
+  });
+  it('writes files at mode 0o600 and dir at 0o700', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    const h = await store.create('report', 'sec');
+    const dirStat = statSync(h.dir);
+    const fileStat = statSync(h.metadataPath);
+    assert.equal((dirStat.mode & 0o777), 0o700);
+    assert.equal((fileStat.mode & 0o777), 0o600);
+  });
+});
+
+describe('ArtifactStore.update', () => {
+  it('writes files atomically; returns files_touched', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    const h = await store.create('report', 'r');
+    const out = await store.update(h, [{ path: 'report.md', content: '# hi\n' }]);
+    assert.deepEqual(out.files_touched.sort(), ['report.md']);
+    assert.equal(readFileSync(h.primaryPath, 'utf8'), '# hi\n');
+  });
+  it('rejects FileWrite path with .. or /', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    const h = await store.create('report', 'r');
+    await assert.rejects(() => store.update(h, [{ path: '../escape', content: 'x' }]));
+    await assert.rejects(() => store.update(h, [{ path: '/abs', content: 'x' }]));
+  });
+  it('detects added + modified files via DirSnapshot diff', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    const h = await store.create('report', 'r');
+    await store.update(h, [{ path: 'report.md', content: '# v1\n' }]);
+    await new Promise(r => setTimeout(r, 20));
+    const out = await store.update(h, [
+      { path: 'report.md', content: '# v2\n' },
+      { path: 'appendix.md', content: '## A\n' },
+    ]);
+    assert.deepEqual(out.files_touched.sort(), ['appendix.md', 'report.md']);
+  });
+  it('rejects empty FileWrite path', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    const h = await store.create('report', 'r');
+    await assert.rejects(() => store.update(h, [{ path: '', content: 'x' }]));
+  });
+  it('bumps last_updated_at + turn_count when paired with recordTurn', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    const h = await store.create('report', 'r');
+    const meta1 = JSON.parse(readFileSync(h.metadataPath, 'utf8'));
+    await store.recordTurn(h, {
+      action: 'create', turn_id: 't1', user_prompt: 'p1', files_touched: [],
+    });
+    const meta2 = JSON.parse(readFileSync(h.metadataPath, 'utf8'));
+    assert.equal(meta2.turn_count, 1);
+    assert.notEqual(meta1.last_updated_at, meta2.last_updated_at);
+  });
+});
+
+describe('ArtifactStore.recordTurn', () => {
+  it('appends to provenance.json', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    const h = await store.create('report', 'r');
+    await store.recordTurn(h, {
+      action: 'create', turn_id: 't1', user_prompt: 'p1', files_touched: [],
+    });
+    await store.recordTurn(h, {
+      action: 'update', turn_id: 't2', user_prompt: 'p2', files_touched: ['report.md'],
+    });
+    const prov = JSON.parse(readFileSync(h.provenancePath, 'utf8'));
+    assert.equal(prov.length, 2);
+    assert.equal(prov[0].turn_id, 't1');
+    assert.equal(prov[1].turn_id, 't2');
+  });
+});
+
+describe('ArtifactStore.list + get + remove', () => {
+  it('list returns all artifact handles, sorted by created_at desc', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    const a = await store.create('report', 'a');
+    const b = await store.create('report', 'b');
+    const list = await store.list();
+    assert.equal(list.length, 2);
+    // fixedNow increments — b is created after a, so b should be first
+    assert.equal(list[0]!.slug, 'b');
+    assert.equal(list[1]!.slug, 'a');
+  });
+  it('get returns handle or null', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    const h = await store.create('report', 'r');
+    assert.equal((await store.get('r'))!.slug, 'r');
+    assert.equal(await store.get('missing'), null);
+  });
+  it('remove deletes directory; throws ArtifactNotFound if missing', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    const h = await store.create('report', 'r');
+    await store.remove('r', true);
+    assert.equal(existsSync(h.dir), false);
+    await assert.rejects(() => store.remove('r', true), ArtifactNotFound);
+  });
+  it('remove rejects when confirm is not true', async () => {
+    const store = new ArtifactStore({ workspaceDir: tmpWs() });
+    await assert.rejects(() => store.remove('x', false as never));
+  });
+  it('remove rejects empty slug', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    await assert.rejects(() => store.remove('', true), ArtifactNotFound);
+  });
+  it('remove rejects slug with path separator', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    await assert.rejects(() => store.remove('foo/bar', true), ArtifactNotFound);
+  });
+  it('remove rejects slug containing ..', async () => {
+    const ws = tmpWs();
+    const store = new ArtifactStore({ workspaceDir: ws, now: fixedNow() });
+    await assert.rejects(() => store.remove('..', true), ArtifactNotFound);
+  });
+});

package/packages/coworker-artifacts/src/artifact-store.ts

@@ -0,0 +1,206 @@
+// packages/coworker-artifacts/src/artifact-store.ts
+import {
+  chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync,
+  rmSync, writeFileSync,
+} from 'node:fs';
+import { join, normalize } from 'node:path';
+import type {
+  ArtifactHandle, ArtifactKind, ArtifactMetadata, FileWrite,
+  Provenance, TurnEntry,
+} from './types.js';
+import { ARTIFACT_KINDS } from './types.js';
+import {
+  ArtifactKindRejected, ArtifactNotFound, ArtifactSlugCollision,
+} from './errors.js';
+import { deriveSlug, nextCollisionSlug } from './slug.js';
+import { takeSnapshot, diffSnapshots } from './dir-snapshot.js';
+import { renderReadme } from './readme-renderer.js';
+
+export interface ArtifactStoreOptions {
+  workspaceDir: string;
+  now?: () => string;
+}
+
+const ARTIFACTS_DIR_NAME = '.otto/artifacts';
+const PRIMARY_FILE = 'report.md';
+
+export class ArtifactStore {
+  private readonly workspaceDir: string;
+  private readonly now: () => string;
+
+  constructor(opts: ArtifactStoreOptions) {
+    this.workspaceDir = opts.workspaceDir;
+    this.now = opts.now ?? (() => new Date().toISOString());
+  }
+
+  private rootDir(): string {
+    return join(this.workspaceDir, ARTIFACTS_DIR_NAME);
+  }
+
+  private existingSlugs(): Set<string> {
+    const root = this.rootDir();
+    if (!existsSync(root)) return new Set();
+    return new Set(readdirSync(root, { withFileTypes: true })
+      .filter(e => e.isDirectory())
+      .map(e => e.name));
+  }
+
+  private handleFor(slug: string, kind: ArtifactKind, name: string): ArtifactHandle {
+    const dir = join(this.rootDir(), slug);
+    return {
+      slug, kind, name, dir,
+      uri: `artifact://${slug}`,
+      primaryPath: join(dir, PRIMARY_FILE),
+      metadataPath: join(dir, 'metadata.json'),
+      provenancePath: join(dir, 'provenance.json'),
+      readmePath: join(dir, 'README.md'),
+    };
+  }
+
+  private atomicWrite(path: string, content: string, mode = 0o600): void {
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, content, { mode });
+    chmodSync(tmp, mode);
+    renameSync(tmp, path);
+  }
+
+  private readMetadata(path: string): ArtifactMetadata {
+    return JSON.parse(readFileSync(path, 'utf8')) as ArtifactMetadata;
+  }
+
+  private readProvenance(path: string): Provenance {
+    if (!existsSync(path)) return [];
+    try {
+      return JSON.parse(readFileSync(path, 'utf8')) as Provenance;
+    } catch {
+      return [];
+    }
+  }
+
+  private fileStats(dir: string): Array<{ path: string; sizeBytes: number }> {
+    const snap = takeSnapshot(dir);
+    return [...snap.entries()]
+      .filter(([p]) => p !== 'metadata.json' && p !== 'provenance.json' && p !== 'README.md')
+      .map(([path, { sizeBytes }]) => ({ path, sizeBytes }));
+  }
+
+  async create(kind: ArtifactKind, name: string): Promise<ArtifactHandle> {
+    if (!ARTIFACT_KINDS.includes(kind)) throw new ArtifactKindRejected(kind);
+    mkdirSync(this.rootDir(), { recursive: true, mode: 0o700 });
+    const base = deriveSlug(name);
+    const slug = nextCollisionSlug(base, this.existingSlugs());
+    const handle = this.handleFor(slug, kind, name);
+    // Use mkdirSync (non-recursive) on the artifact dir for race detection,
+    // but the parent is created above; if this throws EEXIST, retry with bumped slug.
+    try { mkdirSync(handle.dir, { mode: 0o700 }); }
+    catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'EEXIST') {
+        // Race — recurse with refreshed slug set
+        return this.create(kind, name);
+      }
+      throw err;
+    }
+    const ts = this.now();
+    const meta: ArtifactMetadata = {
+      _schema: 1, slug, kind, name,
+      created_at: ts, last_updated_at: ts,
+      turn_count: 0, primary_file: PRIMARY_FILE,
+      uri: handle.uri,
+    };
+    this.atomicWrite(handle.metadataPath, JSON.stringify(meta, null, 2));
+    this.atomicWrite(handle.primaryPath, '');
+    this.atomicWrite(handle.provenancePath, '[]');
+    this.atomicWrite(handle.readmePath, renderReadme(meta, [], this.fileStats(handle.dir)));
+    return handle;
+  }
+
+  async update(handle: ArtifactHandle, files: FileWrite[]): Promise<{ files_touched: string[] }> {
+    if (!existsSync(handle.dir)) throw new ArtifactNotFound(handle.slug);
+    for (const f of files) {
+      const normalized = normalize(f.path);
+      if (!f.path || !normalized || normalized === '.' ||
+          normalized.startsWith('..') || normalized.startsWith('/') ||
+          normalized.includes('\0')) {
+        throw new Error(`Bad FileWrite path: ${f.path}`);
+      }
+    }
+    const before = takeSnapshot(handle.dir);
+    for (const f of files) {
+      const abs = join(handle.dir, f.path);
+      mkdirSync(join(abs, '..'), { recursive: true, mode: 0o700 });
+      this.atomicWrite(abs, f.content);
+    }
+    const after = takeSnapshot(handle.dir);
+    const diff = diffSnapshots(before, after);
+    const filesTouched = [...new Set([...diff.added, ...diff.modified])]
+      .filter(p => p !== 'metadata.json' && p !== 'provenance.json' && p !== 'README.md')
+      .sort();
+    // Bump metadata (last_updated_at; turn_count incremented by recordTurn)
+    const meta = this.readMetadata(handle.metadataPath);
+    meta.last_updated_at = this.now();
+    this.atomicWrite(handle.metadataPath, JSON.stringify(meta, null, 2));
+    const prov = this.readProvenance(handle.provenancePath);
+    this.atomicWrite(handle.readmePath, renderReadme(meta, prov, this.fileStats(handle.dir)));
+    return { files_touched: filesTouched };
+  }
+
+  async recordTurn(
+    handle: ArtifactHandle,
+    entry: Omit<TurnEntry, '_schema' | 'ts'> & Partial<Pick<TurnEntry, 'ts'>>,
+  ): Promise<void> {
+    if (!existsSync(handle.dir)) throw new ArtifactNotFound(handle.slug);
+    const prov = this.readProvenance(handle.provenancePath);
+    const ts = entry.ts ?? this.now();
+    const fullEntry: TurnEntry = {
+      _schema: 1, ts,
+      action: entry.action,
+      turn_id: entry.turn_id,
+      user_prompt: entry.user_prompt,
+      files_touched: entry.files_touched,
+      ...(entry.agent_turn_id !== undefined ? { agent_turn_id: entry.agent_turn_id } : {}),
+      ...(entry.scratchpad_name !== undefined ? { scratchpad_name: entry.scratchpad_name } : {}),
+    };
+    prov.push(fullEntry);
+    this.atomicWrite(handle.provenancePath, JSON.stringify(prov, null, 2));
+    // Bump metadata
+    const meta = this.readMetadata(handle.metadataPath);
+    meta.turn_count = prov.length;
+    meta.last_updated_at = ts;
+    this.atomicWrite(handle.metadataPath, JSON.stringify(meta, null, 2));
+    this.atomicWrite(handle.readmePath, renderReadme(meta, prov, this.fileStats(handle.dir)));
+  }
+
+  async list(): Promise<ArtifactHandle[]> {
+    const root = this.rootDir();
+    if (!existsSync(root)) return [];
+    const handles: Array<{ handle: ArtifactHandle; created_at: string }> = [];
+    for (const slug of this.existingSlugs()) {
+      const metaPath = join(root, slug, 'metadata.json');
+      if (!existsSync(metaPath)) continue;
+      try {
+        const meta = this.readMetadata(metaPath);
+        const h = this.handleFor(meta.slug, meta.kind, meta.name);
+        handles.push({ handle: h, created_at: meta.created_at });
+      } catch { /* skip malformed */ }
+    }
+    handles.sort((a, b) => b.created_at.localeCompare(a.created_at));
+    return handles.map(x => x.handle);
+  }
+
+  async get(slug: string): Promise<ArtifactHandle | null> {
+    const metaPath = join(this.rootDir(), slug, 'metadata.json');
+    if (!existsSync(metaPath)) return null;
+    const meta = this.readMetadata(metaPath);
+    return this.handleFor(meta.slug, meta.kind, meta.name);
+  }
+
+  async remove(slug: string, confirm: true): Promise<void> {
+    if (confirm !== true) throw new Error(`/artifacts remove requires --confirm`);
+    if (!slug || slug.includes('/') || slug.includes('..') || slug === '.') {
+      throw new ArtifactNotFound(slug);
+    }
+    const dir = join(this.rootDir(), slug);
+    if (!existsSync(dir)) throw new ArtifactNotFound(slug);
+    rmSync(dir, { recursive: true, force: true });
+  }
+}

package/packages/coworker-artifacts/src/artifacts-integration.test.ts

@@ -0,0 +1,109 @@
+// packages/coworker-artifacts/src/artifacts-integration.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, existsSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import coworkerVaultExtension from '../../../src/resources/extensions/coworker-vault/index.js';
+import coworkerMemoryExtension, { getMemoryRecorder, createMemoryBundle } from '../../../src/resources/extensions/coworker-memory/index.js';
+import coworkerArtifactsExtension, { getArtifactStore } from '../../../src/resources/extensions/coworker-artifacts/index.js';
+import coworkerScratchpadExtension from '../../../src/resources/extensions/coworker-scratchpad/index.js';
+import { makeFakeApi, fireSessionStart, fireSessionShutdown } from '../../../src/resources/extensions/coworker-vault/test-helpers.js';
+
+describe('Phase 4 — cross-extension integration', () => {
+  it('artifact created by store surfaces as kind:artifact drawer in memory and persists on disk', async () => {
+    const global = mkdtempSync(join(tmpdir(), 'p4-g-'));
+    const ws = mkdtempSync(join(tmpdir(), 'p4-w-'));
+    const sp = mkdtempSync(join(tmpdir(), 'p4-sp-'));
+    process.env.OTTO_COWORKER_GLOBAL_DIR = global;
+    process.env.OTTO_SCRATCHPAD_ROOT = sp;
+    try {
+      const vaultApi = makeFakeApi();
+      const memApi = makeFakeApi();
+      const artApi = makeFakeApi();
+      const spApi = makeFakeApi();
+      coworkerVaultExtension(vaultApi.api);
+      coworkerMemoryExtension(memApi.api);
+      coworkerArtifactsExtension(artApi.api);
+      coworkerScratchpadExtension(spApi.api);
+
+      await fireSessionStart(vaultApi, { cwd: ws });
+      await fireSessionStart(memApi, { cwd: ws });
+      await fireSessionStart(artApi, { cwd: ws });
+      await fireSessionStart(spApi, { cwd: ws });
+
+      const store = getArtifactStore();
+      const recorder = getMemoryRecorder();
+      assert.ok(store);
+      assert.ok(recorder);
+
+      // Simulate kernel→manager flow: store.create + recorder.recordArtifact
+      const handle = await store.create('report', 'RCA: load balancer 503');
+      await store.update(handle, [{ path: 'report.md', content: '# RCA\n\nbody\n' }]);
+      await recorder.recordArtifact({
+        scratchpadName: 'p1-incident',
+        slug: handle.slug,
+        kind: handle.kind,
+        uri: handle.uri,
+        turnId: 'turn-abc',
+      });
+
+      // Disk verification
+      assert.ok(existsSync(handle.dir));
+      assert.match(readFileSync(handle.primaryPath, 'utf8'), /# RCA/);
+      assert.match(readFileSync(handle.metadataPath, 'utf8'), /"slug": "rca-load-balancer-503"/);
+
+      // Memory recall via peek bundle
+      const peek = await createMemoryBundle({
+        globalDir: global, workspaceDir: ws,
+        scopeMode: 'per-project-tagged',
+        currentScratchpadName: () => null,
+      });
+      try {
+        const r = await peek.backend.recall({ query: 'rca-load-balancer-503', kind: 'artifact' });
+        assert.equal(r.length, 1);
+        const parsed = JSON.parse(r[0]!.drawer.content);
+        assert.equal(parsed.slug, 'rca-load-balancer-503');
+        assert.equal(parsed.uri, 'artifact://rca-load-balancer-503');
+        assert.equal(r[0]!.drawer.room, 'p1-incident');
+      } finally { await peek.dispose(); }
+
+      await fireSessionShutdown(spApi);
+      await fireSessionShutdown(artApi);
+      await fireSessionShutdown(memApi);
+      await fireSessionShutdown(vaultApi);
+    } finally {
+      delete process.env.OTTO_COWORKER_GLOBAL_DIR;
+      delete process.env.OTTO_SCRATCHPAD_ROOT;
+    }
+  });
+
+  it('artifact init failure does not break memory or vault', async () => {
+    // Skip artifact activation; vault + memory + scratchpad activate normally
+    const global = mkdtempSync(join(tmpdir(), 'p4-mix-'));
+    const ws = mkdtempSync(join(tmpdir(), 'p4-mix-ws-'));
+    const sp = mkdtempSync(join(tmpdir(), 'p4-mix-sp-'));
+    process.env.OTTO_COWORKER_GLOBAL_DIR = global;
+    process.env.OTTO_SCRATCHPAD_ROOT = sp;
+    try {
+      const vaultApi = makeFakeApi();
+      const memApi = makeFakeApi();
+      const spApi = makeFakeApi();
+      coworkerVaultExtension(vaultApi.api);
+      coworkerMemoryExtension(memApi.api);
+      coworkerScratchpadExtension(spApi.api);
+      await fireSessionStart(vaultApi, { cwd: ws });
+      await fireSessionStart(memApi, { cwd: ws });
+      await fireSessionStart(spApi, { cwd: ws });
+      assert.equal(getArtifactStore(), null);
+      assert.equal(getMemoryRecorder() !== null, true);
+      await fireSessionShutdown(spApi);
+      await fireSessionShutdown(memApi);
+      await fireSessionShutdown(vaultApi);
+    } finally {
+      delete process.env.OTTO_COWORKER_GLOBAL_DIR;
+      delete process.env.OTTO_SCRATCHPAD_ROOT;
+    }
+  });
+});

package/packages/coworker-artifacts/src/dir-snapshot.test.ts

@@ -0,0 +1,71 @@
+// packages/coworker-artifacts/src/dir-snapshot.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { takeSnapshot, diffSnapshots } from './dir-snapshot.js';
+
+function tmp(): string { return mkdtempSync(join(tmpdir(), 'ds-')); }
+
+describe('takeSnapshot', () => {
+  it('returns empty map for empty dir', () => {
+    const snap = takeSnapshot(tmp());
+    assert.equal(snap.size, 0);
+  });
+  it('captures relative path + size for each file', () => {
+    const dir = tmp();
+    writeFileSync(join(dir, 'a.md'), 'hello');
+    writeFileSync(join(dir, 'b.md'), 'world!');
+    const snap = takeSnapshot(dir);
+    assert.equal(snap.size, 2);
+    assert.equal(snap.get('a.md')!.sizeBytes, 5);
+    assert.equal(snap.get('b.md')!.sizeBytes, 6);
+    assert.equal(typeof snap.get('a.md')!.mtimeNs, 'bigint');
+  });
+  it('recurses into subdirs with forward-slash paths', () => {
+    const dir = tmp();
+    mkdirSync(join(dir, 'sub'));
+    writeFileSync(join(dir, 'sub', 'c.md'), 'nested');
+    const snap = takeSnapshot(dir);
+    assert.ok(snap.has('sub/c.md'));
+  });
+  it('returns empty map when dir does not exist', () => {
+    const snap = takeSnapshot(join(tmp(), 'nope'));
+    assert.equal(snap.size, 0);
+  });
+});
+
+describe('diffSnapshots', () => {
+  it('detects added files', () => {
+    const before = new Map();
+    const after = new Map([['a.md', { mtimeNs: 1n, sizeBytes: 5 }]]);
+    const d = diffSnapshots(before, after);
+    assert.deepEqual(d.added, ['a.md']);
+    assert.deepEqual(d.modified, []);
+    assert.deepEqual(d.removed, []);
+  });
+  it('detects removed files', () => {
+    const before = new Map([['a.md', { mtimeNs: 1n, sizeBytes: 5 }]]);
+    const after = new Map();
+    const d = diffSnapshots(before, after);
+    assert.deepEqual(d.removed, ['a.md']);
+  });
+  it('detects modified when sizeBytes differs', () => {
+    const before = new Map([['a.md', { mtimeNs: 1n, sizeBytes: 5 }]]);
+    const after = new Map([['a.md', { mtimeNs: 2n, sizeBytes: 7 }]]);
+    const d = diffSnapshots(before, after);
+    assert.deepEqual(d.modified, ['a.md']);
+  });
+  it('detects modified when mtimeNs differs (same size)', () => {
+    const before = new Map([['a.md', { mtimeNs: 1n, sizeBytes: 5 }]]);
+    const after = new Map([['a.md', { mtimeNs: 999n, sizeBytes: 5 }]]);
+    assert.deepEqual(diffSnapshots(before, after).modified, ['a.md']);
+  });
+  it('no diff when identical', () => {
+    const a = new Map([['a.md', { mtimeNs: 1n, sizeBytes: 5 }]]);
+    const b = new Map([['a.md', { mtimeNs: 1n, sizeBytes: 5 }]]);
+    const d = diffSnapshots(a, b);
+    assert.equal(d.added.length + d.modified.length + d.removed.length, 0);
+  });
+});

package/packages/coworker-artifacts/src/dir-snapshot.ts

@@ -0,0 +1,52 @@
+// packages/coworker-artifacts/src/dir-snapshot.ts
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+import type { DirSnapshot } from './types.js';
+
+export function takeSnapshot(dir: string): DirSnapshot {
+  const out: DirSnapshot = new Map();
+  if (!existsSync(dir)) return out;
+  walk(dir, dir, out);
+  return out;
+}
+
+function walk(root: string, current: string, out: DirSnapshot): void {
+  let entries;
+  try { entries = readdirSync(current, { withFileTypes: true }); }
+  catch { return; }
+  for (const entry of entries) {
+    const abs = join(current, entry.name);
+    if (entry.isDirectory()) {
+      walk(root, abs, out);
+    } else if (entry.isFile()) {
+      const stat = statSync(abs, { bigint: true });
+      const rel = relative(root, abs).split(sep).join('/');
+      out.set(rel, {
+        mtimeNs: stat.mtimeNs,
+        sizeBytes: Number(stat.size),
+      });
+    }
+  }
+}
+
+export function diffSnapshots(
+  before: DirSnapshot,
+  after: DirSnapshot,
+): { added: string[]; modified: string[]; removed: string[] } {
+  const added: string[] = [];
+  const modified: string[] = [];
+  const removed: string[] = [];
+  for (const [path, a] of after) {
+    const b = before.get(path);
+    if (!b) added.push(path);
+    else if (b.mtimeNs !== a.mtimeNs || b.sizeBytes !== a.sizeBytes) modified.push(path);
+  }
+  for (const path of before.keys()) {
+    if (!after.has(path)) removed.push(path);
+  }
+  return {
+    added: added.sort(),
+    modified: modified.sort(),
+    removed: removed.sort(),
+  };
+}

package/packages/coworker-artifacts/src/errors.test.ts

@@ -0,0 +1,37 @@
+// packages/coworker-artifacts/src/errors.test.ts
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  ArtifactNotFound, ArtifactKindRejected, ArtifactUriMalformed, ArtifactSlugCollision,
+} from './errors.js';
+
+describe('artifact errors', () => {
+  it('ArtifactNotFound carries slug', () => {
+    const e = new ArtifactNotFound('rca-1');
+    assert.equal(e.name, 'ArtifactNotFound');
+    assert.equal(e.slug, 'rca-1');
+    assert.match(e.message, /rca-1/);
+  });
+  it('ArtifactKindRejected carries kind', () => {
+    const e = new ArtifactKindRejected('workbook');
+    assert.equal(e.name, 'ArtifactKindRejected');
+    assert.equal(e.kind, 'workbook');
+    assert.match(e.message, /workbook/);
+    assert.match(e.message, /report/);
+  });
+  it('ArtifactUriMalformed carries uri + reason', () => {
+    const e = new ArtifactUriMalformed('artifact://../x', 'path traversal');
+    assert.equal(e.name, 'ArtifactUriMalformed');
+    assert.equal(e.uri, 'artifact://../x');
+    assert.equal(e.reason, 'path traversal');
+    assert.match(e.message, /path traversal/);
+  });
+  it('ArtifactSlugCollision carries base + attempts', () => {
+    const e = new ArtifactSlugCollision('rca', 100);
+    assert.equal(e.name, 'ArtifactSlugCollision');
+    assert.equal(e.base, 'rca');
+    assert.equal(e.attempts, 100);
+    assert.match(e.message, /rca/);
+    assert.match(e.message, /100/);
+  });
+});