@letta-ai/dreams 0.0.1 → 0.0.3

package/dist/skill.js

@@ -35,6 +35,8 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.skillDir = skillDir;
 exports.skillFilePath = skillFilePath;
+exports.initSnapshotTemplatePath = initSnapshotTemplatePath;
+exports.claudeHooksReferencePath = claudeHooksReferencePath;
 exports.installedSkillVersion = installedSkillVersion;
 exports.installSkill = installSkill;
 const crypto = __importStar(require("node:crypto"));
@@ -50,6 +52,12 @@ function skillDir() {
 function skillFilePath() {
     return path.join(skillDir(), "SKILL.md");
 }
+function initSnapshotTemplatePath() {
+    return path.join(skillDir(), "references", "init-snapshot.template.json");
+}
+function claudeHooksReferencePath() {
+    return path.join(skillDir(), "references", "hooks-claude.md");
+}
 function skillContent(version) {
     return `---
 name: dreams-setup
@@ -59,28 +67,276 @@ version: ${version}
 
 # Dreams setup
 
-Start or repair the local setup with:
+CLI owns side effects. This skill owns sequencing and user conversation. There is no durable resume pointer: in a new conversation, start at step 1 and skip work that durable facts show is already satisfied. Never blindly repeat mutations. Never print or summarize access tokens, refresh tokens, credential files, or keychain contents.
+
+## Step 0 — Local bootstrap (optional repair)
+
+If the durable CLI or this skill may be missing, run:
 
 \`\`\`bash
 npx @letta-ai/dreams@latest onboard --json
 \`\`\`
 
-\`onboard\` installs an exact CLI version at a stable local path, creates or reuses the installation identity, installs this skill, initializes local SQLite, and checks authentication. It does not log in or run \`orient\` itself.
+\`onboard\` installs or repairs the durable CLI, installation identity, this skill (including reference files), and local SQLite. It does **not** check authentication or choose the next setup step. On success it returns \`status: "ready"\` with absolute \`cli_path\` and \`skill.path\`. Use that \`cli_path\` for later Dreams commands and for harness hook commands.
+
+## Step 1 — Authenticate
+
+1. Run \`dreams auth status --json\`.
+2. If unauthenticated, run \`dreams auth login --json\`, wait for browser approval (JSON Lines: \`awaiting_approval\` then \`authenticated\`), then re-check \`auth status\`.
+3. Prefer an existing usable credential; do not force a new login when status is already authenticated.
+
+## Step 2 — Detect and register source
+
+Run:
+
+\`\`\`bash
+dreams source detect --json
+\`\`\`
+
+This detects Claude Code from harness filesystem facts under \`~/.claude\` only (no transcript reads), registers the installation-scoped source with Cloud as \`detected\`, and persists workspace/source ids locally. It is idempotent: re-running refreshes metadata and must not regress lifecycle state. Do not scan, approve roots, or upload in this step.
+
+## Step 3 — Init snapshot
+
+1. Read the reference template at \`references/init-snapshot.template.json\` in this skill directory.
+2. Gather workspace facts with the user (repos, harnesses, skills, identity signals, teammates, approved roots intent). Prefer asking over inventing.
+3. Write a concrete JSON object (do **not** include teammate \`role\` or \`scope.mode\`; keep \`scope.approved_roots\`).
+4. Show the JSON to the user and obtain explicit approval.
+5. Submit with the narrow CLI transport (not raw HTTP). Workspace id comes from the local binding created in step 2 (override with \`--workspace-id\` only if needed):
+
+\`\`\`bash
+dreams snapshots create --type init --file /path/to/approved-init.json --client-request-id <unique-id> --json
+\`\`\`
+
+Reuse the same \`client-request-id\` only when retrying the exact same approved payload. Never resubmit a new or edited snapshot without showing it and getting approval again. Snapshot submit stores the fact; it does not create the shared-memory repository.
 
-## Follow the response
+## Step 4 — Install live sync hooks (Claude Code)
 
-1. Parse the single JSON document from stdout.
-2. Briefly explain \`agent_instructions\` to the user without pasting raw JSON.
-3. Run the exact command in \`next_action.command\`.
-4. Use the absolute \`cli_path\` from the response for later Dreams commands.
+Wire Claude Code hooks so live turns wake \`dreams sync\` through the durable CLI path from onboard (\`cli_path\`). There is **no** \`dreams hooks install\` command — you edit \`~/.claude/settings.json\` using \`references/hooks-claude.md\`.
 
-When \`state\` is \`awaiting_auth\`, run the returned \`auth login --json\` command and wait for the user to approve in the browser. That login command emits JSON Lines: first \`awaiting_approval\`, then \`authenticated\`. After it succeeds, run the stable CLI's \`onboard --json\` command again.
+**Consent first:** before editing global harness config, explicitly explain that this enables **ongoing transcript sync** on future Claude Code sessions, and obtain the user's approval. Do not install hooks without that consent. Hooks go in **before** root activation so live coverage has no setup gap.
 
-When \`state\` is \`ready_for_orient\`, run the returned \`orient\` command.
+Then:
 
-Repeated \`onboard\` calls are safe. They repair missing local setup and return the same next action until authentication state changes.
+1. Read \`references/hooks-claude.md\`.
+2. Substitute the absolute \`cli_path\` from onboard into every hook command (quote the path).
+3. Choose the **platform-appropriate** command from the reference (POSIX vs PowerShell). Do not install \`>/dev/null\` redirects on Windows.
+4. Merge **idempotently** into \`~/.claude/settings.json\`: if a Dreams sync hook is already present (command contains \`# dreams-sync-hook\` or the same \`cli_path\` + \`sync\`), **update that handler in place** and leave unrelated hooks untouched — never append duplicates.
+5. Confirm through the durable launcher: \`"<cli_path>" sync status --json\` (hooks themselves should remain silent and exit 0). Read \`sync.effective_state\` (\`paused\` / \`running\` / \`pending\` / \`not_due\` / \`degraded\` / \`idle\`).
 
-Never print or summarize access tokens, refresh tokens, credential files, or keychain contents.
+Rules:
+
+- Call the durable \`cli_path\` with \`sync\` (pipe hook stdin). Never \`npx\`, never \`jq\`.
+- Suppress stdout/stderr and force exit 0 so harnesses do not treat sync JSON as hook-control output.
+- Install Claude Code \`SessionStart\` + \`Stop\` only. **Codex hooks are deferred** until Dreams has a Codex source adapter (today's sync/live hints are Claude-only).
+
+### Hook diagnostics & repair
+
+When live sync seems broken, use this ladder (do **not** put version checks inside the hot hook command):
+
+1. Verify the durable launcher itself: \`"<cli_path>" status --json\` (expects a ready CLI + skill paths). A wrong or nonexistent path means Dreams never starts, so **no** sync diagnostics can be recorded — re-run \`npx @letta-ai/dreams@latest onboard --json\` and re-substitute the new absolute \`cli_path\` into hooks.
+2. Interpret local sync diagnostics: \`"<cli_path>" sync status --json\`
+   - \`effective_state: "paused"\` → expected no-op until \`sync resume\`
+   - \`not_due\` → cadence/backoff (including a retained trigger waiting for \`next_due_at\`); quiet hook wakes are expected
+   - \`pending\` → trigger is runnable now (forced, cadence due, or retry due) but no worker lease is held yet
+   - \`running\` → detached worker lease is active
+   - \`degraded\` → inspect \`last_error_code\` / \`last_error_message\` (structured \`spawn_failed\` when the parent could not detach a worker)
+   - \`idle\` → no pause, no pending trigger, and nothing waiting on cadence
+3. Silence from hooks is **required** (exit 0, no stdout/stderr). Silence means “don’t interrupt Claude,” **not** proof of a successful Cloud upload.
+
+## Step 5 — Activate live sync
+
+With user consent for privacy roots:
+
+1. Approve privacy roots: \`"<cli_path>" source approve-root "<path>" --json\` (repeat as needed). Deny-by-default: nothing leaves the machine until roots are approved.
+2. Wake live-only scheduling through the durable launcher:
+   \`"<cli_path>" sync --force --json\`
+   This records a durable trigger and may spawn the detached worker. It does **not** run an unrestricted historical scan — live mode only touches already-tracked sessions plus a validated current-session hint from hooks. Do **not** run \`dreams source scan\` here (it performs unrestricted historical discovery under approved roots). Do **not** invoke \`dreams upload\` separately during activation — \`sync\` owns live-first upload ordering for whatever is already queued.
+3. Treat this wake as a **local scheduling check**. Step 2's \`source detect\` already exercised Cloud registration; the first real hook-driven upload (when the user has an active Claude session under an approved root) confirms the end-to-end path. Do not present \`sync --force\` as a Cloud smoke test — on a fresh device with nothing queued it may perform no network I/O.
+
+## Step 6 — Optional: import recent history in the background
+
+Only if the user wants older transcripts included. Historical import is **optional**, runs in the **background**, and drains in **incremental bounded slices** across later \`dreams sync\` wakes (including SessionStart/Stop). It does **not** need to finish in one process — sleep, offline time, and restarts are fine; work resumes from durable local state. That steadiness is why a wider window is a reasonable choice: choose the history that is useful, not only what might finish tonight.
+
+When offering this step, use calm language. Watching the first background sync settle is a reassuring sign that imports are moving; it is not a separate scary connection ritual.
+
+If the user opts in:
+
+1. Agree a start bound. Describe it accurately as **sessions modified since \`<RFC3339>\` through now** (the CLI freezes \`until_at = now\`). Selection is by transcript-file mtime for whole sessions — not per-message timestamps inside a file.
+2. Obtain explicit consent to queue and upload those historical transcript bytes (approved roots + \`.dreamignore\` still apply). Do not start an open-ended “import everything” without a bound.
+3. Initialize the frozen window and queue one bounded local slice:
+   \`"<cli_path>" backfill start --since <RFC3339> --json\`
+4. Immediately wake the sync worker so draining does not wait for a future hook:
+   \`"<cli_path>" sync --force --json\`
+5. Explain what happens next: live turns stay first; remaining capacity steadily continues the historical frontier in the background (newer sessions in the window tend to be imported before older ones; bytes within a session still move forward). Users can pause or resume without discarding queued bytes or frontier progress:
+   \`"<cli_path>" sync pause\`
+   \`"<cli_path>" sync resume\`
+   \`"<cli_path>" sync status --json\` shows \`effective_state\` while import runs.
+
+## Re-entry
+
+If unsure what is already done, inspect durable facts (\`dreams auth status\`, \`dreams source list\`, \`dreams status\`, \`dreams sync status\`) and continue at the first incomplete step. Repeated \`onboard\`, \`source detect\`, approved snapshot retries, and idempotent hook merges are safe when they follow the rules above. Never “catch up” by running unrestricted \`source scan\` after hooks are installed — use live sync and, if desired, bounded background backfill instead.
+`;
+}
+function initSnapshotTemplate() {
+    return `${JSON.stringify({
+        $comment: "Non-enforced reference template for Dream init snapshots (LET-9833). Cloud accepts any JSON object + 256 KiB cap; this documents the expected Init fields for the skill/CLI. Do NOT include role on teammates, and do NOT include scope.mode — keep scope.approved_roots.",
+        repositories: [
+            {
+                display_name: "my-repo",
+                git_remote_sanitized: "github.com/acme/my-repo",
+                primary_language: "typescript",
+                build_system: "nx",
+                instruction_files: [{ name: "AGENTS.md", size_bytes: 1024 }],
+                skill_names: ["deploy"],
+                letta_agent_count: 2,
+                letta_memory_artifact_count: 0,
+                allowlisted_file_names: [],
+            },
+        ],
+        harnesses: [{ name: "claude-code", version: "1.2.3" }],
+        skills: [{ name: "deploy", description: "deploys things" }],
+        identity_signals: [{ type: "git_email", value: "dev@acme.com" }],
+        transcript_inventory: [{ source_key: "sess-1", session_count: 3, segment_count: 10 }],
+        teammates: [
+            {
+                display_name: "Alex",
+                identity_signals: [{ type: "git_email", value: "alex@acme.com" }],
+            },
+        ],
+        scope: { approved_roots: [] },
+        cli_version: "0.0.3",
+    }, null, 2)}\n`;
+}
+function claudeHooksReference() {
+    return `# Claude Code — Dreams live sync hooks
+
+Install **globally** in \`~/.claude/settings.json\` (user scope). Merge into the existing \`hooks\` object; never replace the whole file or delete unrelated hook entries.
+
+## Goal
+
+Wake the durable Dreams CLI on \`SessionStart\` (recover pending work after crashes/restarts) and \`Stop\` (after each live turn). Pipe the hook JSON stdin into \`dreams sync\` so the current \`session_id\` can be recorded as a live hint.
+
+## Platform-specific commands
+
+Replace \`CLI_PATH\` with the absolute \`cli_path\` from \`dreams onboard --json\`.
+
+### macOS / Linux (bash)
+
+Always quote the launcher path (it may contain spaces):
+
+\`\`\`bash
+"CLI_PATH" sync >/dev/null 2>&1 || true # dreams-sync-hook
+\`\`\`
+
+### Windows (PowerShell)
+
+Use Claude's \`shell: "powershell"\` so the command is not run through bash redirects:
+
+\`\`\`powershell
+& 'CLI_PATH' sync *> $null; exit 0 # dreams-sync-hook
+\`\`\`
+
+Rules:
+
+- Pipe stdin from the harness into that command (Claude already provides JSON on stdin to command hooks).
+- Do **not** use \`npx\`, \`jq\`, or shell JSON parsing.
+- Suppress stdout/stderr and force exit 0. Sync JSON must not enter Claude context.
+- Keep the \`# dreams-sync-hook\` marker. On re-run, **update** the existing Dreams handler in place (including switching POSIX ↔ PowerShell when the host OS differs) instead of appending another copy.
+
+## Example merge fragment (macOS / Linux)
+
+\`\`\`json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\\"CLI_PATH\\" sync >/dev/null 2>&1 || true # dreams-sync-hook"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\\"CLI_PATH\\" sync >/dev/null 2>&1 || true # dreams-sync-hook"
+          }
+        ]
+      }
+    ]
+  }
+}
+\`\`\`
+
+## Example merge fragment (Windows)
+
+\`\`\`json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "powershell",
+            "command": "& 'CLI_PATH' sync *> $null; exit 0 # dreams-sync-hook"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "powershell",
+            "command": "& 'CLI_PATH' sync *> $null; exit 0 # dreams-sync-hook"
+          }
+        ]
+      }
+    ]
+  }
+}
+\`\`\`
+
+## Idempotent merge checklist
+
+1. Obtain explicit user consent for ongoing transcript sync (see skill Step 4).
+2. Read \`~/.claude/settings.json\` (create \`{}\` if absent).
+3. Preserve every existing top-level key and every non-Dreams hook matcher/handler.
+4. For \`SessionStart\` and \`Stop\`, find a handler containing \`dreams-sync-hook\` (or the same \`CLI_PATH\` + \` sync\`) and update it in place; otherwise append one host-appropriate Dreams handler.
+5. Write the file back atomically.
+6. Optional check through the durable launcher:
+   - macOS / Linux: \`"CLI_PATH" sync status --json\`
+   - Windows PowerShell: \`& 'CLI_PATH' sync status --json\`
+
+## Notes
+
+### No-op contracts
+
+- Hook commands must stay **silent** and **exit 0** (including when sync is paused or not due). That silence protects Claude’s context; it is **not** proof the Cloud upload succeeded.
+- \`dreams sync pause\` / \`dreams sync resume\` toggle hook wakes without uninstalling handlers.
+- Distinguish expected no-ops from failure with \`dreams sync status --json\`:
+  - \`effective_state: "paused"\` or \`"not_due"\` → expected quiet wake
+  - \`pending\` / \`running\` → runnable work recorded or worker in flight
+  - \`idle\` → nothing waiting
+  - \`degraded\` + structured \`last_error_code\` (e.g. \`spawn_failed\`) → failure
+
+### Robustness
+
+- \`session_id\` in hook stdin is an **optional** live hint. Malformed/missing stdin must still issue a generic \`sync\` wake for tracked sessions (live mode — no silent historical ingest).
+- Always quote the durable absolute launcher path, suppress stdout/stderr, and force exit 0.
+- Preserve unrelated handlers; update the marked Dreams handler (\`# dreams-sync-hook\`) **in place** — never append duplicates.
+- Do not put version checks in the hot hook path. If the launcher path is wrong/nonexistent, Dreams never starts and cannot record diagnostics — repair with \`dreams onboard --json\` / \`dreams status --json\` and re-substitute \`cli_path\`.
+
+### Other
+
+- Users can pause hooks without uninstalling: \`dreams sync pause\` / \`dreams sync resume\`.
+- Codex hook wiring is intentionally deferred until Dreams ships a Codex source adapter.
 `;
 }
 function readFile(file) {
@@ -127,12 +383,21 @@ function installedSkillVersion() {
     const match = text.match(/^version:\s*(\S+)\s*$/m);
     return match ? match[1] : null;
 }
+function desiredArtifacts() {
+    return [
+        { path: skillFilePath(), contents: skillContent((0, version_1.packageVersion)()) },
+        { path: initSnapshotTemplatePath(), contents: initSnapshotTemplate() },
+        { path: claudeHooksReferencePath(), contents: claudeHooksReference() },
+    ];
+}
 function installSkill() {
     removeLegacyGeneratedSkill();
-    const desired = skillContent((0, version_1.packageVersion)());
-    const existing = readFile(skillFilePath());
-    if (existing === desired)
+    const artifacts = desiredArtifacts();
+    const existing = artifacts.map((artifact) => readFile(artifact.path));
+    const allSame = artifacts.every((artifact, index) => existing[index] === artifact.contents);
+    if (allSame)
         return "unchanged";
-    writeAtomic(skillFilePath(), desired);
-    return existing === null ? "installed" : "updated";
+    for (const artifact of artifacts)
+        writeAtomic(artifact.path, artifact.contents);
+    return existing[0] === null ? "installed" : "updated";
 }

package/dist/snapshots.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * `dreams snapshots create` — narrow CLI transport for skill-authored snapshots.
+ *
+ * Keeps credential handling, base URL selection, size checking, JSON-object
+ * validation, and idempotency keys inside the CLI. The skill authors the
+ * payload and obtains user approval before invoking this command.
+ *
+ * Workspace id is taken from the local binding written by `source detect`
+ * (or upload registration), matching the Cloud path
+ * POST /v1/dreams/workspaces/{workspaceId}/snapshots.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commandSnapshotsCreate = commandSnapshotsCreate;
+exports.commandSnapshots = commandSnapshots;
+const fs = __importStar(require("node:fs"));
+const index_1 = require("./auth/index");
+const client_1 = require("./cloud/client");
+const db_1 = require("./local/db");
+const state_lock_1 = require("./local/state-lock");
+const store_1 = require("./store");
+const MAX_SNAPSHOT_BYTES = 256 * 1024;
+const MAX_TYPE_LEN = 64;
+const MAX_CLIENT_REQUEST_ID_LEN = 128;
+const TYPE_RE = /^[a-z][a-z0-9_-]*$/;
+const CLIENT_REQUEST_ID_RE = /^[A-Za-z0-9._:-]+$/;
+function emit(json, payload, human) {
+    if (json)
+        console.log(JSON.stringify(payload, null, 2));
+    else
+        console.log(human());
+}
+function validateType(type) {
+    if (!TYPE_RE.test(type) || type.length > MAX_TYPE_LEN) {
+        return `invalid --type (expected <=${MAX_TYPE_LEN} chars matching ${TYPE_RE})`;
+    }
+    return null;
+}
+function validateClientRequestId(id) {
+    if (!CLIENT_REQUEST_ID_RE.test(id) || id.length > MAX_CLIENT_REQUEST_ID_LEN) {
+        return `invalid --client-request-id (expected <=${MAX_CLIENT_REQUEST_ID_LEN} chars matching ${CLIENT_REQUEST_ID_RE})`;
+    }
+    return null;
+}
+function loadPayload(file) {
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        return { ok: false, message: `could not read --file: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const bytes = Buffer.byteLength(raw, "utf8");
+    if (bytes > MAX_SNAPSHOT_BYTES) {
+        return { ok: false, message: `snapshot exceeds ${MAX_SNAPSHOT_BYTES} byte UTF-8 cap (${bytes} bytes)` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return { ok: false, message: `snapshot is not valid JSON: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return { ok: false, message: "snapshot payload must be a JSON object" };
+    }
+    return { ok: true, data: parsed, bytes };
+}
+function resolveWorkspaceId(explicit) {
+    if (explicit)
+        return explicit;
+    const installation = (0, store_1.loadOrCreateInstallation)();
+    const db = (0, db_1.openDb)({
+        installationId: installation.installation_id,
+        installationCreatedAt: installation.created_at,
+    });
+    try {
+        const row = db.prepare("SELECT workspace_id FROM workspace_bindings WHERE id = 1").get();
+        return row?.workspace_id ?? null;
+    }
+    finally {
+        (0, db_1.closeDb)();
+    }
+}
+async function commandSnapshotsCreate(args) {
+    if (!args.type || !args.file || !args.clientRequestId) {
+        process.stderr.write("Usage: dreams snapshots create --type <type> --file <path> --client-request-id <id> [--workspace-id <id>] [--json]\n");
+        return 1;
+    }
+    const typeError = validateType(args.type);
+    if (typeError) {
+        emit(args.json, { status: "error", code: "invalid_type", message: typeError }, () => typeError);
+        return 1;
+    }
+    const idError = validateClientRequestId(args.clientRequestId);
+    if (idError) {
+        emit(args.json, { status: "error", code: "invalid_client_request_id", message: idError }, () => idError);
+        return 1;
+    }
+    const loaded = loadPayload(args.file);
+    if (!loaded.ok) {
+        emit(args.json, { status: "error", code: "invalid_payload", message: loaded.message }, () => loaded.message);
+        return 1;
+    }
+    const lock = (0, state_lock_1.acquireLocalStateLock)();
+    if (lock === null) {
+        const message = "Another Dreams command is using local state. Try again after it finishes.";
+        emit(args.json, { status: "error", code: "local_state_busy", message }, () => message);
+        return 1;
+    }
+    try {
+        const workspaceId = resolveWorkspaceId(args.workspaceId);
+        if (!workspaceId) {
+            const message = "no workspace binding found; run `dreams source detect` first (or pass --workspace-id)";
+            emit(args.json, { status: "error", code: "workspace_unresolved", message }, () => message);
+            return 1;
+        }
+        try {
+            const result = await (0, client_1.createSnapshot)({
+                workspaceId,
+                type: args.type,
+                clientRequestId: args.clientRequestId,
+                data: loaded.data,
+            });
+            emit(args.json, {
+                status: "ok",
+                id: result.id,
+                type: result.type,
+                workspace_id: result.workspaceId,
+                client_request_id: result.clientRequestId,
+                snapshot_status: result.status,
+                created_at: result.createdAt,
+                bytes: loaded.bytes,
+            }, () => [
+                "Snapshot stored",
+                "",
+                `  Id:                 ${result.id}`,
+                `  Type:               ${result.type}`,
+                `  Workspace:          ${result.workspaceId}`,
+                `  Client request id:  ${result.clientRequestId}`,
+                `  Status:             ${result.status}`,
+                `  Bytes:              ${loaded.bytes}`,
+            ].join("\n"));
+            return 0;
+        }
+        catch (error) {
+            if (error instanceof index_1.NotAuthenticatedError) {
+                const message = "not authenticated: run `dreams auth login`";
+                emit(args.json, { status: "error", code: "not_authenticated", message }, () => message);
+                return 1;
+            }
+            if (error instanceof client_1.CloudAuthError) {
+                const message = `authentication failed: ${error.message}`;
+                emit(args.json, { status: "error", code: error.code ?? "auth_failed", message }, () => message);
+                return 1;
+            }
+            if (error instanceof client_1.CloudError) {
+                const message = error.message;
+                emit(args.json, { status: "error", code: error.retryable ? "retryable" : "cloud_error", message, retryable: error.retryable }, () => message);
+                return 1;
+            }
+            throw error;
+        }
+    }
+    finally {
+        (0, state_lock_1.releaseLocalStateLock)(lock);
+    }
+}
+async function commandSnapshots(subcommand, args) {
+    switch (subcommand) {
+        case "create":
+            return commandSnapshotsCreate(args);
+        default:
+            process.stderr.write(`Unknown snapshots subcommand: ${subcommand ?? "(none)"} — expected create\n`);
+            return 1;
+    }
+}