@cmetech/otto 1.1.1 → 1.2.4

package/dist/resources/extensions/subagent/launch.js

@@ -1,21 +1,53 @@
 // OTTO + Subagent launch contract and child process safety helpers.
+import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { SessionManager } from "@otto/pi-coding-agent";
 export const SUBAGENT_CHILD_ENV_VAR = "OTTO_SUBAGENT_CHILD";
 export const SUBAGENT_CHILD_ENV_VALUE = "1";
+export const SUBAGENT_SCRATCHPAD_ENV_VAR = "OTTO_SUBAGENT_SCRATCHPAD";
+const MAX_SCRATCHPAD_AGENT_PART = 32;
+export function mintSubagentScratchpadName(agentName) {
+    const hex = crypto.randomBytes(3).toString("hex");
+    // Sanitize: NFKD + strip combining marks + lowercase + non-[a-z0-9] → '-' + collapse + trim.
+    let sanitized = agentName
+        .normalize("NFKD")
+        .replace(/[̀-ͯ]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (sanitized.length > MAX_SCRATCHPAD_AGENT_PART) {
+        sanitized = sanitized.slice(0, MAX_SCRATCHPAD_AGENT_PART).replace(/-+$/, "");
+    }
+    if (!sanitized)
+        return `subagent-${hex}`;
+    return `subagent-${sanitized}-${hex}`;
+}
 export function isSubagentChildProcess(env = process.env) {
     return env[SUBAGENT_CHILD_ENV_VAR] === SUBAGENT_CHILD_ENV_VALUE;
 }
-export function buildSubagentProcessEnv(env = process.env) {
-    return {
+export function buildSubagentProcessEnv(env = process.env, scratchpadName) {
+    const next = {
         ...env,
         [SUBAGENT_CHILD_ENV_VAR]: SUBAGENT_CHILD_ENV_VALUE,
     };
+    if (scratchpadName) {
+        next[SUBAGENT_SCRATCHPAD_ENV_VAR] = scratchpadName;
+    }
+    return next;
 }
 export function buildShellEnvAssignments(env = process.env) {
-    const value = env[SUBAGENT_CHILD_ENV_VAR];
-    return value ? [`${SUBAGENT_CHILD_ENV_VAR}=${JSON.stringify(value)}`] : [];
+    const out = [];
+    const childValue = env[SUBAGENT_CHILD_ENV_VAR];
+    if (childValue) {
+        out.push(`${SUBAGENT_CHILD_ENV_VAR}=${JSON.stringify(childValue)}`);
+    }
+    const scratchpadValue = env[SUBAGENT_SCRATCHPAD_ENV_VAR];
+    if (scratchpadValue) {
+        out.push(`${SUBAGENT_SCRATCHPAD_ENV_VAR}=${JSON.stringify(scratchpadValue)}`);
+    }
+    return out;
 }
 export function buildSubagentProcessArgs(agent, task, tmpPromptPath, modelOverride, session = { mode: "fresh" }) {
     const args = ["--mode", "json", "-p"];
@@ -70,7 +102,7 @@ export function createSubagentLaunchPlan(input) {
     const session = input.session ?? resolveSubagentSessionArgs(input.contextMode ?? "fresh", input.parentSessionManager);
     return {
         args: buildSubagentProcessArgs(input.agent, input.task, input.tmpPromptPath, input.modelOverride, session),
-        env: buildSubagentProcessEnv(),
+        env: buildSubagentProcessEnv(process.env, input.scratchpadName),
         cwd: input.cwd ?? input.defaultCwd,
         session,
     };

package/dist/resources/extensions/subagent/run-store.js

@@ -131,6 +131,7 @@ export function createInitialRunRecord(input) {
             index,
             agent: child.agent,
             trackingName: child.trackingName,
+            scratchpadName: child.scratchpadName,
             task: child.task,
             cwd: child.cwd,
             status: "queued",

package/dist/resources/extensions/workflow/bootstrap/register-extension.js

@@ -19,6 +19,7 @@ import { logWarning } from "../workflow-logger.js";
 // session hook calling startAuto) would be silently dropped because Node's
 // EventEmitter does not buffer events for late subscribers.
 import { initCmuxEventListeners } from "../../cmux/index.js";
+import { registerPersonaCommands } from "../persona-status.js";
 import { BRAND } from "../strings.js";
 export { writeCrashLog } from "./crash-log.js";
 export function handleRecoverableExtensionProcessError(err) {
@@ -110,6 +111,7 @@ export function registerWorkflowExtension(pi) {
         ["memory-tools", () => registerMemoryTools(pi)],
         ["exec-tools", () => registerExecTools(pi)],
         ["schedule-wakeup-tool", () => registerScheduleWakeupTool(pi)],
+        ["persona-commands", () => registerPersonaCommands(pi)],
         ["shortcuts", () => registerShortcuts(pi)],
         // cmux is a library (no pi), so gsd sets up the event listeners on its
         // behalf using the shared event channel contract. Registration is

package/dist/resources/extensions/workflow/bootstrap/register-hooks.js

@@ -299,6 +299,15 @@ async function resetAskUserQuestionsTurnCache() {
     const { resetAskUserQuestionsCache } = await import("../../ask-user-questions.js");
     resetAskUserQuestionsCache();
 }
+async function initPersonaStatusChip(ctx) {
+    try {
+        const { initPersonaWidget } = await import("../persona-status.js");
+        await initPersonaWidget(ctx);
+    }
+    catch {
+        // Non-fatal: persona chip simply won't render if the registry is unavailable.
+    }
+}
 async function syncServiceTierStatus(ctx) {
     const { getEffectiveServiceTier, formatServiceTierFooterStatus } = await import("../service-tier.js");
     ctx.ui.setStatus("gsd-fast", formatServiceTierFooterStatus(getEffectiveServiceTier(), ctx.model?.id));
@@ -424,6 +433,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         approvalQuestionAbortInFlight = false;
         clearDeferredApprovalGate();
         await resetAskUserQuestionsTurnCache();
+        await initPersonaStatusChip(ctx);
         await syncServiceTierStatus(ctx);
         await applyDisabledModelProviderPolicy(ctx);
         await applyCompactionThresholdOverride(ctx);

package/dist/resources/extensions/workflow/persona-status.js

@@ -0,0 +1,87 @@
+// Wires /persona slash commands + the persona status-bar chip into Otto.
+// Spec §2.5 + §5.2. Lives inside the src/resources extension boundary, so it
+// imports only the @otto/coworker-persona package (never src/ modules).
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { PersonaRegistry, handleList, handleCurrent, handleSwitch, handleReset, handleInstall, handleUninstall, } from "@otto/coworker-persona";
+// Sorts ahead of alphabetic extension status keys so the chip lands leftmost
+// in the footer's extension-status block.
+const STATUS_KEY = "00-persona";
+const SUBCOMMANDS = ["list", "current", "switch", "install", "uninstall", "reset"];
+function ottoHome() {
+    return process.env.OTTO_HOME || join(homedir(), ".otto");
+}
+function getRegistry() {
+    return new PersonaRegistry({ ottoHome: ottoHome() });
+}
+function formatPersonaChip(persona) {
+    const { icon, label } = persona.status_line;
+    return `${icon} ${label}`.trim();
+}
+async function refreshPersonaChip(ctx, registry) {
+    if (!ctx.hasUI)
+        return;
+    try {
+        const active = await registry.activeInWorkspace(ctx.cwd);
+        ctx.ui.setStatus(STATUS_KEY, formatPersonaChip(active));
+    }
+    catch {
+        ctx.ui.setStatus(STATUS_KEY, undefined);
+    }
+}
+// Called on session_start to seed the default persona and render the chip.
+export async function initPersonaWidget(ctx) {
+    const registry = getRegistry();
+    try {
+        await registry.ensureDefaultInstalled();
+    }
+    catch {
+        // Non-fatal: chip simply won't render if the default can't be installed.
+    }
+    await refreshPersonaChip(ctx, registry);
+}
+export function registerPersonaCommands(pi) {
+    pi.registerCommand("persona", {
+        description: "Manage Otto co-worker personas (list, current, switch, install, uninstall, reset)",
+        getArgumentCompletions: (prefix) => SUBCOMMANDS.filter((s) => s.startsWith(prefix)).map((s) => ({ value: s, label: s })),
+        handler: async (args, ctx) => {
+            const registry = getRegistry();
+            await registry.ensureDefaultInstalled();
+            const [sub, ...rest] = args.trim().split(/\s+/).filter(Boolean);
+            const ws = ctx.cwd;
+            try {
+                let lines;
+                switch (sub ?? "current") {
+                    case "list":
+                        lines = await handleList(registry, ws);
+                        break;
+                    case "current":
+                        lines = await handleCurrent(registry, ws);
+                        break;
+                    case "switch":
+                        lines = await handleSwitch(registry, ws, rest[0]);
+                        await refreshPersonaChip(ctx, registry);
+                        break;
+                    case "reset":
+                        lines = await handleReset(registry, ws);
+                        await refreshPersonaChip(ctx, registry);
+                        break;
+                    case "install":
+                        lines = await handleInstall(registry, rest[0]);
+                        break;
+                    case "uninstall":
+                        lines = await handleUninstall(registry, rest[0], [ws]);
+                        await refreshPersonaChip(ctx, registry);
+                        break;
+                    default:
+                        ctx.ui.notify(`Unknown subcommand: ${sub}. Try: ${SUBCOMMANDS.join(", ")}`, "warning");
+                        return;
+                }
+                ctx.ui.notify(lines.join("\n"), "info");
+            }
+            catch (err) {
+                ctx.ui.notify(err instanceof Error ? err.message : String(err), "error");
+            }
+        },
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmetech/otto",
-  "version": "1.1.1",
+  "version": "1.2.4",
   "description": "Terminal-based developer chat assistant. Permanent hard fork of gsd-pi with LangFlow flow triggers, a flow builder, and optional gateway routing for compliance environments.",
   "keywords": [
     "ai",
@@ -65,10 +65,18 @@
     "build:pi-coding-agent": "npm run build:contracts && npm run build -w @otto/pi-coding-agent",
     "build:native-pkg": "npm run build -w @otto/native",
     "build:contracts": "npm run build -w @otto-build/contracts",
+    "build:coworker-types": "npm run build -w @otto/coworker-types",
+    "build:coworker-utils": "npm run build -w @otto/coworker-utils",
+    "build:coworker-memory": "npm run build -w @otto/coworker-memory",
+    "build:coworker-vault": "npm run build -w @otto/coworker-vault",
+    "build:coworker-artifacts": "npm run build -w @otto/coworker-artifacts",
+    "build:coworker-scratchpad": "npm run build -w @otto/coworker-scratchpad",
+    "build:coworker-persona": "npm run build -w @otto/coworker-persona",
+    "build:coworker": "npm run build:coworker-types && npm run build:coworker-utils && npm run build:coworker-memory && npm run build:coworker-vault && npm run build:coworker-artifacts && npm run build:coworker-scratchpad && npm run build:coworker-persona",
     "build:rpc-client": "npm run build -w @otto-build/rpc-client",
     "build:pi": "npm run build:contracts && npm run build:native-pkg && npm run build:pi-tui && npm run build:pi-ai && npm run build:pi-agent-core && npm run build:pi-coding-agent",
     "build:mcp-server": "npm run build -w @otto-build/mcp-server",
-    "build:core": "npm run build:contracts && npm run build:pi && npm run build:rpc-client && npm run build:mcp-server && tsc && npm run copy-resources && npm run copy-themes && npm run copy-export-html",
+    "build:core": "npm run build:contracts && npm run build:coworker && npm run build:pi && npm run build:rpc-client && npm run build:mcp-server && tsc && npm run copy-resources && npm run copy-themes && npm run copy-export-html",
     "prebuild": "node scripts/sync-brand-colors.mjs && node scripts/sync-piconfig.mjs && node scripts/sync-release-notes.mjs && node scripts/generate-theme-const.mjs",
     "build": "npm run build:core",
     "sync-brand-colors": "node scripts/sync-brand-colors.mjs",
@@ -86,7 +94,7 @@
     "baseline:refactor:phase0": "npm run baseline:refactor:gate && node --import ./src/resources/extensions/workflow/tests/resolve-ts.mjs --experimental-strip-types --test src/resources/extensions/workflow/tests/derive-state-db.test.ts src/resources/extensions/workflow/tests/single-writer-invariant.test.ts src/resources/extensions/workflow/tests/auto-recovery.test.ts src/resources/extensions/workflow/tests/auto-worktree-registry.test.ts",
     "legacy:cleanup:gate": "node scripts/legacy-cleanup-gate.mjs",
     "legacy:cleanup:evidence": "node scripts/legacy-cleanup-evidence.mjs",
-    "test:unit:compiled": "node --import ./scripts/dist-test-resolve.mjs --experimental-test-isolation=process --test-reporter=./scripts/test-reporter-compact.mjs --test \"dist-test/src/tests/*.test.js\" \"dist-test/src/resources/extensions/workflow/tests/*.test.js\" \"dist-test/src/resources/extensions/workflow/tests/*.test.mjs\" \"dist-test/src/resources/extensions/shared/tests/*.test.js\" \"dist-test/src/resources/extensions/subagent/tests/*.test.js\" \"dist-test/src/resources/extensions/claude-code-cli/tests/*.test.js\" \"dist-test/src/resources/extensions/github-sync/tests/*.test.js\" \"dist-test/src/resources/extensions/universal-config/tests/*.test.js\" \"dist-test/src/resources/extensions/visual-brief/tests/*.test.js\" \"dist-test/src/resources/extensions/voice/tests/*.test.js\" \"dist-test/src/resources/extensions/mcp-client/tests/*.test.js\" \"dist-test/src/resources/extensions/remote-questions/tests/*.test.js\"",
+    "test:unit:compiled": "node --import ./scripts/dist-test-resolve.mjs --experimental-test-isolation=process --test-reporter=./scripts/test-reporter-compact.mjs --test \"dist-test/src/tests/*.test.js\" \"dist-test/src/resources/extensions/workflow/tests/*.test.js\" \"dist-test/src/resources/extensions/workflow/tests/*.test.mjs\" \"dist-test/src/resources/extensions/shared/tests/*.test.js\" \"dist-test/src/resources/extensions/subagent/tests/*.test.js\" \"dist-test/src/resources/extensions/claude-code-cli/tests/*.test.js\" \"dist-test/src/resources/extensions/github-sync/tests/*.test.js\" \"dist-test/src/resources/extensions/universal-config/tests/*.test.js\" \"dist-test/src/resources/extensions/visual-brief/tests/*.test.js\" \"dist-test/src/resources/extensions/voice/tests/*.test.js\" \"dist-test/src/resources/extensions/mcp-client/tests/*.test.js\" \"dist-test/src/resources/extensions/remote-questions/tests/*.test.js\" \"dist-test/src/resources/extensions/coworker-memory/*.test.js\" \"dist-test/src/resources/extensions/coworker-vault/*.test.js\" \"dist-test/src/resources/extensions/coworker-scratchpad/*.test.js\" \"dist-test/src/resources/extensions/coworker-artifacts/*.test.js\"",
     "test:unit": "npm run test:compile && npm run test:unit:compiled",
     "test:changed:src": "node scripts/verify-changed-src-tests.mjs",
     "test:packages": "npm run test:compile && npm run test:packages:compiled",
@@ -147,17 +155,22 @@
     "@sinclair/typebox": "^0.34.41",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
+    "axios": "^1.16.1",
     "chalk": "^5.6.2",
     "chokidar": "^5.0.0",
+    "date-fns": "^4.4.0",
     "diff": "^8.0.2",
     "echarts": "^5.6.0",
+    "exceljs": "^4.4.0",
     "extract-zip": "^2.0.1",
     "file-type": "^21.1.1",
     "glob": "^13.0.1",
     "hosted-git-info": "^9.0.2",
     "ignore": "^7.0.5",
+    "lodash": "^4.18.1",
     "marked": "^15.0.12",
     "minimatch": "^10.2.3",
+    "nodejs-polars": "^0.24.1",
     "openai": "^6.26.0",
     "picomatch": "^4.0.3",
     "playwright": "^1.58.2",
@@ -167,9 +180,11 @@
     "sql.js": "^1.14.1",
     "strip-ansi": "^7.1.0",
     "undici": "^7.24.2",
-    "yaml": "^2.8.2"
+    "yaml": "^2.8.2",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@types/lodash": "^4.17.24",
     "@types/node": "^24.12.0",
     "@types/picomatch": "^4.0.2",
     "@types/proper-lockfile": "^4.1.4",
@@ -181,13 +196,13 @@
   },
   "optionalDependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.2.83",
+    "@cmetech/otto-engine-darwin-arm64": "1.2.4",
+    "@cmetech/otto-engine-darwin-x64": "1.2.4",
+    "@cmetech/otto-engine-linux-arm64-gnu": "1.2.4",
+    "@cmetech/otto-engine-linux-x64-gnu": "1.2.4",
+    "@cmetech/otto-engine-win32-x64-msvc": "1.2.4",
     "fsevents": "~2.3.3",
-    "koffi": "^2.9.0",
-    "@cmetech/otto-engine-darwin-arm64": "1.1.1",
-    "@cmetech/otto-engine-darwin-x64": "1.1.1",
-    "@cmetech/otto-engine-linux-arm64-gnu": "1.1.1",
-    "@cmetech/otto-engine-linux-x64-gnu": "1.1.1",
-    "@cmetech/otto-engine-win32-x64-msvc": "1.1.1"
+    "koffi": "^2.9.0"
   },
   "overrides": {
     "gaxios": "7.1.4",

package/packages/contracts/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@otto-build/contracts",
-  "version": "1.1.1",
+  "version": "1.2.4",
   "description": "Shared public contracts for OTTO workspace boundaries",
   "license": "MIT",
   "otto": {

package/packages/coworker-artifacts/dist/artifact-store.d.ts

@@ -0,0 +1,25 @@
+import type { ArtifactHandle, ArtifactKind, FileWrite, TurnEntry } from './types.js';
+export interface ArtifactStoreOptions {
+    workspaceDir: string;
+    now?: () => string;
+}
+export declare class ArtifactStore {
+    private readonly workspaceDir;
+    private readonly now;
+    constructor(opts: ArtifactStoreOptions);
+    private rootDir;
+    private existingSlugs;
+    private handleFor;
+    private atomicWrite;
+    private readMetadata;
+    private readProvenance;
+    private fileStats;
+    create(kind: ArtifactKind, name: string): Promise<ArtifactHandle>;
+    update(handle: ArtifactHandle, files: FileWrite[]): Promise<{
+        files_touched: string[];
+    }>;
+    recordTurn(handle: ArtifactHandle, entry: Omit<TurnEntry, '_schema' | 'ts'> & Partial<Pick<TurnEntry, 'ts'>>): Promise<void>;
+    list(): Promise<ArtifactHandle[]>;
+    get(slug: string): Promise<ArtifactHandle | null>;
+    remove(slug: string, confirm: true): Promise<void>;
+}

package/packages/coworker-artifacts/dist/artifact-store.js

@@ -0,0 +1,187 @@
+// 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 { ARTIFACT_KINDS } from './types.js';
+import { ArtifactKindRejected, ArtifactNotFound, } from './errors.js';
+import { deriveSlug, nextCollisionSlug } from './slug.js';
+import { takeSnapshot, diffSnapshots } from './dir-snapshot.js';
+import { renderReadme } from './readme-renderer.js';
+const ARTIFACTS_DIR_NAME = '.otto/artifacts';
+const PRIMARY_FILE = 'report.md';
+export class ArtifactStore {
+    workspaceDir;
+    now;
+    constructor(opts) {
+        this.workspaceDir = opts.workspaceDir;
+        this.now = opts.now ?? (() => new Date().toISOString());
+    }
+    rootDir() {
+        return join(this.workspaceDir, ARTIFACTS_DIR_NAME);
+    }
+    existingSlugs() {
+        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));
+    }
+    handleFor(slug, kind, name) {
+        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'),
+        };
+    }
+    atomicWrite(path, content, mode = 0o600) {
+        const tmp = `${path}.tmp`;
+        writeFileSync(tmp, content, { mode });
+        chmodSync(tmp, mode);
+        renameSync(tmp, path);
+    }
+    readMetadata(path) {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    readProvenance(path) {
+        if (!existsSync(path))
+            return [];
+        try {
+            return JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch {
+            return [];
+        }
+    }
+    fileStats(dir) {
+        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, name) {
+        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.code === 'EEXIST') {
+                // Race — recurse with refreshed slug set
+                return this.create(kind, name);
+            }
+            throw err;
+        }
+        const ts = this.now();
+        const meta = {
+            _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, files) {
+        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, entry) {
+        if (!existsSync(handle.dir))
+            throw new ArtifactNotFound(handle.slug);
+        const prov = this.readProvenance(handle.provenancePath);
+        const ts = entry.ts ?? this.now();
+        const fullEntry = {
+            _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() {
+        const root = this.rootDir();
+        if (!existsSync(root))
+            return [];
+        const handles = [];
+        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) {
+        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, confirm) {
+        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/dist/dir-snapshot.d.ts

@@ -0,0 +1,7 @@
+import type { DirSnapshot } from './types.js';
+export declare function takeSnapshot(dir: string): DirSnapshot;
+export declare function diffSnapshots(before: DirSnapshot, after: DirSnapshot): {
+    added: string[];
+    modified: string[];
+    removed: string[];
+};

package/packages/coworker-artifacts/dist/dir-snapshot.js

@@ -0,0 +1,54 @@
+// packages/coworker-artifacts/src/dir-snapshot.ts
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+export function takeSnapshot(dir) {
+    const out = new Map();
+    if (!existsSync(dir))
+        return out;
+    walk(dir, dir, out);
+    return out;
+}
+function walk(root, current, out) {
+    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, after) {
+    const added = [];
+    const modified = [];
+    const removed = [];
+    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/dist/errors.d.ts

@@ -0,0 +1,18 @@
+export declare class ArtifactNotFound extends Error {
+    readonly slug: string;
+    constructor(slug: string);
+}
+export declare class ArtifactKindRejected extends Error {
+    readonly kind: string;
+    constructor(kind: string);
+}
+export declare class ArtifactUriMalformed extends Error {
+    readonly uri: string;
+    readonly reason: string;
+    constructor(uri: string, reason: string);
+}
+export declare class ArtifactSlugCollision extends Error {
+    readonly base: string;
+    readonly attempts: number;
+    constructor(base: string, attempts: number);
+}

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

@@ -0,0 +1,37 @@
+// packages/coworker-artifacts/src/errors.ts
+export class ArtifactNotFound extends Error {
+    slug;
+    constructor(slug) {
+        super(`Artifact not found: ${slug}. /artifacts list to see available.`);
+        this.slug = slug;
+        this.name = 'ArtifactNotFound';
+    }
+}
+export class ArtifactKindRejected extends Error {
+    kind;
+    constructor(kind) {
+        super(`Artifact kind '${kind}' is not supported. v1 ships only 'report'.`);
+        this.kind = kind;
+        this.name = 'ArtifactKindRejected';
+    }
+}
+export class ArtifactUriMalformed extends Error {
+    uri;
+    reason;
+    constructor(uri, reason) {
+        super(`Bad artifact URI ${uri}: ${reason}.`);
+        this.uri = uri;
+        this.reason = reason;
+        this.name = 'ArtifactUriMalformed';
+    }
+}
+export class ArtifactSlugCollision extends Error {
+    base;
+    attempts;
+    constructor(base, attempts) {
+        super(`Slug collision: '${base}' has ${attempts} colliding suffixes (-2…-${attempts + 1}). Pick a different name.`);
+        this.base = base;
+        this.attempts = attempts;
+        this.name = 'ArtifactSlugCollision';
+    }
+}

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

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './slug.js';
+export * from './dir-snapshot.js';
+export * from './resolve-uri.js';
+export * from './readme-renderer.js';
+export * from './artifact-store.js';

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

@@ -0,0 +1,7 @@
+export * from './types.js';
+export * from './errors.js';
+export * from './slug.js';
+export * from './dir-snapshot.js';
+export * from './resolve-uri.js';
+export * from './readme-renderer.js';
+export * from './artifact-store.js';