@cmetech/otto 1.1.1 → 1.2.4

package/packages/coworker-artifacts/dist/readme-renderer.d.ts

@@ -0,0 +1,5 @@
+import type { ArtifactMetadata, Provenance } from './types.js';
+export declare function renderReadme(metadata: ArtifactMetadata, provenance: Provenance, fileStats: Array<{
+    path: string;
+    sizeBytes: number;
+}>): string;

package/packages/coworker-artifacts/dist/readme-renderer.js

@@ -0,0 +1,47 @@
+const UNITS = ['B', 'KB', 'MB', 'GB'];
+function humanSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < UNITS.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${value.toFixed(1)} ${UNITS[unit]}`;
+}
+function escapeMarkdownPipe(s) {
+    return s.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+}
+export function renderReadme(metadata, provenance, fileStats) {
+    const firstTurn = provenance[0]?.turn_id ?? '';
+    const lastTurn = provenance.length > 0 ? provenance[provenance.length - 1].turn_id : '';
+    const lines = [];
+    lines.push(`# ${metadata.name}`);
+    lines.push('');
+    lines.push(`**Kind:** ${metadata.kind}`);
+    lines.push(`**URI:** \`${metadata.uri}\``);
+    lines.push(`**Created:** ${metadata.created_at}${firstTurn ? ` (turn \`${firstTurn}\`)` : ''}`);
+    lines.push(`**Last updated:** ${metadata.last_updated_at}${lastTurn ? ` (turn \`${lastTurn}\`)` : ''}`);
+    lines.push(`**Turns:** ${metadata.turn_count}`);
+    lines.push('');
+    lines.push('## Files');
+    lines.push('');
+    if (fileStats.length === 0) {
+        lines.push('(none)');
+    }
+    else {
+        for (const f of fileStats) {
+            lines.push(`- \`${f.path}\` — ${humanSize(f.sizeBytes)}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Provenance');
+    lines.push('');
+    lines.push('| # | ts | action | turn | prompt |');
+    lines.push('|---|---|---|---|---|');
+    provenance.forEach((e, i) => {
+        lines.push(`| ${i + 1} | ${e.ts} | ${e.action} | ${e.turn_id} | ${escapeMarkdownPipe(e.user_prompt)} |`);
+    });
+    return lines.join('\n') + '\n';
+}

package/packages/coworker-artifacts/dist/resolve-uri.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedArtifactUri } from './types.js';
+export declare const ARTIFACT_URI_SCHEME = "artifact://";
+export declare function resolveArtifactUri(uri: string, workspaceDir: string): ResolvedArtifactUri;

package/packages/coworker-artifacts/dist/resolve-uri.js

@@ -0,0 +1,29 @@
+// packages/coworker-artifacts/src/resolve-uri.ts
+import { join } from 'node:path';
+import { ArtifactUriMalformed } from './errors.js';
+export const ARTIFACT_URI_SCHEME = 'artifact://';
+const SLUG_REGEX = /^[a-z0-9]([a-z0-9-]{0,62}[a-z0-9])?$/;
+export function resolveArtifactUri(uri, workspaceDir) {
+    if (!uri.startsWith(ARTIFACT_URI_SCHEME)) {
+        throw new ArtifactUriMalformed(uri, `must start with ${ARTIFACT_URI_SCHEME}`);
+    }
+    const slug = uri.slice(ARTIFACT_URI_SCHEME.length);
+    if (!slug)
+        throw new ArtifactUriMalformed(uri, 'empty slug');
+    if (slug.includes('..'))
+        throw new ArtifactUriMalformed(uri, 'path traversal');
+    if (slug.length > 64)
+        throw new ArtifactUriMalformed(uri, 'slug exceeds 64 chars');
+    if (!SLUG_REGEX.test(slug)) {
+        throw new ArtifactUriMalformed(uri, 'slug must match ^[a-z0-9][a-z0-9-]*[a-z0-9]$');
+    }
+    const dir = join(workspaceDir, '.otto', 'artifacts', slug);
+    return {
+        slug,
+        dir,
+        primaryPath: join(dir, 'report.md'),
+        metadataPath: join(dir, 'metadata.json'),
+        provenancePath: join(dir, 'provenance.json'),
+        readmePath: join(dir, 'README.md'),
+    };
+}

package/packages/coworker-artifacts/dist/slug.d.ts

@@ -0,0 +1,4 @@
+export declare const MAX_SLUG_LENGTH = 64;
+export declare const MAX_COLLISION_ATTEMPTS = 100;
+export declare function deriveSlug(name: string): string;
+export declare function nextCollisionSlug(base: string, taken: Set<string>): string;

package/packages/coworker-artifacts/dist/slug.js

@@ -0,0 +1,32 @@
+// packages/coworker-artifacts/src/slug.ts
+import { ArtifactSlugCollision } from './errors.js';
+export const MAX_SLUG_LENGTH = 64;
+export const MAX_COLLISION_ATTEMPTS = 100;
+export function deriveSlug(name) {
+    let s = name.toLowerCase();
+    // Strip diacritics (NFKD + remove combining marks U+0300–U+036F)
+    s = s.normalize('NFKD').replace(/[̀-ͯ]/g, '');
+    // Replace non a-z 0-9 with dash
+    s = s.replace(/[^a-z0-9]+/g, '-');
+    // Collapse runs of dashes
+    s = s.replace(/-+/g, '-');
+    // Trim leading/trailing dashes
+    s = s.replace(/^-+|-+$/g, '');
+    // Truncate
+    if (s.length > MAX_SLUG_LENGTH)
+        s = s.slice(0, MAX_SLUG_LENGTH).replace(/-+$/, '');
+    // Fallback if empty
+    if (!s)
+        s = `artifact-${Date.now().toString(36)}`;
+    return s;
+}
+export function nextCollisionSlug(base, taken) {
+    if (!taken.has(base))
+        return base;
+    for (let n = 2; n <= MAX_COLLISION_ATTEMPTS + 1; n++) {
+        const candidate = `${base}-${n}`;
+        if (!taken.has(candidate))
+            return candidate;
+    }
+    throw new ArtifactSlugCollision(base, MAX_COLLISION_ATTEMPTS);
+}

package/packages/coworker-artifacts/dist/types.d.ts

@@ -0,0 +1,52 @@
+export type ArtifactKind = 'report';
+export declare const ARTIFACT_KINDS: readonly ["report"];
+export interface ArtifactHandle {
+    slug: string;
+    kind: ArtifactKind;
+    name: string;
+    dir: string;
+    uri: string;
+    primaryPath: string;
+    metadataPath: string;
+    provenancePath: string;
+    readmePath: string;
+}
+export interface ArtifactMetadata {
+    _schema: 1;
+    slug: string;
+    kind: ArtifactKind;
+    name: string;
+    created_at: string;
+    last_updated_at: string;
+    turn_count: number;
+    primary_file: string;
+    uri: string;
+}
+export interface TurnEntry {
+    _schema: 1;
+    ts: string;
+    action: 'create' | 'update';
+    turn_id: string;
+    agent_turn_id?: string;
+    user_prompt: string;
+    scratchpad_name?: string;
+    files_touched: string[];
+}
+export type Provenance = TurnEntry[];
+export interface DirSnapshotEntry {
+    mtimeNs: bigint;
+    sizeBytes: number;
+}
+export type DirSnapshot = Map<string, DirSnapshotEntry>;
+export interface FileWrite {
+    path: string;
+    content: string;
+}
+export interface ResolvedArtifactUri {
+    slug: string;
+    dir: string;
+    primaryPath: string;
+    metadataPath: string;
+    provenancePath: string;
+    readmePath: string;
+}

package/packages/coworker-artifacts/dist/types.js

@@ -0,0 +1 @@
+export const ARTIFACT_KINDS = ['report'];

package/packages/coworker-artifacts/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@otto/coworker-artifacts",
+  "version": "0.0.1",
+  "description": "Otto co-worker package: coworker-artifacts",
+  "type": "module",
+  "otto": { "linkable": true, "scope": "@otto", "name": "coworker-artifacts" },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+  },
+  "dependencies": {
+    "@otto/coworker-utils": "*"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "build:publish": "tsc -p tsconfig.publish.json"
+  },
+  "files": ["dist"]
+}

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 });
+  }
+}