@letta-ai/dreams 0.0.3 → 0.0.4

package/dist/skill.js

@@ -37,6 +37,8 @@ exports.skillDir = skillDir;
 exports.skillFilePath = skillFilePath;
 exports.initSnapshotTemplatePath = initSnapshotTemplatePath;
 exports.claudeHooksReferencePath = claudeHooksReferencePath;
+exports.codexHooksReferencePath = codexHooksReferencePath;
+exports.codexSyncHookScriptPath = codexSyncHookScriptPath;
 exports.installedSkillVersion = installedSkillVersion;
 exports.installSkill = installSkill;
 const crypto = __importStar(require("node:crypto"));
@@ -58,6 +60,12 @@ function initSnapshotTemplatePath() {
 function claudeHooksReferencePath() {
     return path.join(skillDir(), "references", "hooks-claude.md");
 }
+function codexHooksReferencePath() {
+    return path.join(skillDir(), "references", "hooks-codex.md");
+}
+function codexSyncHookScriptPath() {
+    return path.join(skillDir(), "references", "codex-sync-hook.cjs");
+}
 function skillContent(version) {
     return `---
 name: dreams-setup
@@ -67,7 +75,16 @@ version: ${version}
 
 # Dreams setup
 
-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.
+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. Never interpolate credential env vars into shell commands, even partially.
+
+## Invariants
+
+- Quote absolute \`cli_path\` from onboard in every hook/command.
+- Never print tokens. Never invent teammate emails — derive them from git (step 3).
+- Deny-by-default: without an approved directory, nothing uploads. Do not offer “continue without approving a directory.”
+- Live hooks require consent. Do not offer “skip hooks and continue setup” — if the user declines hooks, exit setup (they can re-enter later).
+- SessionStart → \`dreams wake\`; Stop → \`dreams sync\`. Do not install \`sync\` on SessionStart.
+- Prefer \`dreams hooks install --dry-run\` before writing hook files; CLI owns the merge.
 
 ## Step 0 — Local bootstrap (optional repair)
 
@@ -81,105 +98,144 @@ npx @letta-ai/dreams@latest onboard --json
 
 ## 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.
+1. Run \`"<cli_path>" auth status --json\` (or \`dreams auth status --json\` after onboard).
+2. Read the inventory, not only the top-level winner:
+   - \`credentials[]\` lists every discovered backend (\`env\`, \`keychain\`, \`file\`) with \`present\`, \`selected\`, masked token, and \`reason\`.
+   - \`active\` is which credential won for **this process** and why.
+   - \`hooks\` explains that live sync inherits the **coding-agent harness environment**. Verify the credential hooks will use, not only an interactive CLI.
+3. If unauthenticated, run \`dreams auth login --json\`, wait for browser approval (JSON Lines: \`awaiting_approval\` then \`authenticated\`), then re-check \`auth status\`.
+4. Prefer an existing usable credential; do not force a new login when already authenticated.
 
-## Step 2 — Detect and register source
+## Step 2 — Detect and register sources
 
-Run:
+Detect each registered harness with an **explicit** adapter. Do **not** install hooks here.
 
 \`\`\`bash
-dreams source detect --json
+"<cli_path>" source detect --source claude-code --json
+"<cli_path>" source detect --source codex --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.
+Record which harnesses were present (\`harness_present: true\` / exit 0). A missing harness is expected on machines that only run one coding agent — continue with whichever registered successfully.
+
+## Step 3 — Init snapshot (seed smarter memory)
 
-## Step 3 — Init snapshot
+**Why this step exists (tell the user):** A short workspace snapshot helps Dreams start with useful structure — so early memories are more targeted and relevant to their real repos, teammates, and tools — instead of a blank slate. Prefer asking over inventing. Memories are more meaningful when they begin from a smart seed of how this person actually works.
 
-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):
+1. Read \`references/init-snapshot.template.json\` (field ranking is in \`$comment\` / \`$field_guide\`).
+2. **Approved directories (required for later sync):** identify which work directories should be eligible (usually the user’s main code tree). You will approve them in step 4 with \`source approve-dir\`. Put the intended paths in \`scope.approved_roots\` (JSON key unchanged for Cloud; user-facing language is **directories**, not “roots”).
+3. **Repositories:** prefer deeper metadata for directories with recent Claude/Codex sessions; name-only or light metadata for the long tail is fine. Deduplicate multi-clone remotes (one logical repo + optional \`local_clone_count\`).
+4. **Skills:** recursively search the repositories you listed for skill directories (\`.claude/skills\`, \`.agents/skills\`, \`**/skills\` when clearly agent-skill trees). Prefer \`{ directory, skill_count, sample_names }\` over dumping every name when large.
+5. **Teammates — do not AskUserQuestion.** Derive from recent git commits in the target repos (\`git log\` / shortlog). Include display name + email identity signals. **Exclude bots and agents** (e.g. names/emails containing \`[bot]\`, \`dependabot\`, \`github-actions\`, \`renovate\`, \`cursoragent\`, \`noreply\` automation accounts). Cap to a reasonable set of frequent human contributors.
+6. **Omit unknowns** rather than writing \`0\` or empty arrays for optional fields. Do **not** invent \`letta_agent_count\`, \`letta_memory_artifact_count\`, or \`allowlisted_file_names\`.
+7. Include every harness detected in step 2. Write concrete JSON (no teammate \`role\`; no \`scope.mode\`).
+8. Show the JSON and obtain explicit approval, then submit:
 
 \`\`\`bash
-dreams snapshots create --type init --file /path/to/approved-init.json --client-request-id <unique-id> --json
+"<cli_path>" 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.
+Reuse the same \`client-request-id\` only when retrying the exact same approved payload. Snapshot submit stores the fact; it does not create the shared-memory repository. If snapshot submit fails with auth/role errors, explain briefly and **continue** — directories + hooks + history still deliver value.
+
+## Step 4 — Enable live sync (directories + hooks)
+
+This step turns on ongoing sync. There is no separate “activate / sync --force” ceremony afterward.
+
+### 4a — Approve directories (required)
+
+Deny-by-default: nothing leaves the machine until at least one work directory is approved.
 
-## Step 4 — Install live sync hooks (Claude Code)
+1. Explain in plain language: Dreams will only consider transcripts whose working directory sits under an approved folder.
+2. Obtain consent for specific paths (from step 3 intent / session inventory). **Do not** offer “proceed without approving a directory.”
+3. Approve with the preferred alias:
 
-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\`.
+\`\`\`bash
+"<cli_path>" source approve-dir "<path>" --json
+\`\`\`
 
-**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.
+(\`source approve-root\` still works as a synonym.)
 
-Then:
+### 4b — Install hooks (required for live sync)
 
-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\`).
+**Consent:** name which harnesses from step 2 will get live sync (Claude Code and/or Codex). Explain this enables **ongoing transcript sync** on future sessions. If the user declines, **exit setup** (do not continue as if onboarding succeeded). Per-harness opt-out is OK when both were detected (wire only the consented ones).
 
-Rules:
+1. **Dry-run first** — show the user the exact planned commands/files:
 
-- 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).
+\`\`\`bash
+"<cli_path>" hooks install --dry-run --json
+# or per source:
+"<cli_path>" hooks install --source claude-code --dry-run --json
+"<cli_path>" hooks install --source codex --dry-run --json
+\`\`\`
 
-### Hook diagnostics & repair
+2. After approval, install (CLI owns the merge — do not hand-edit when the CLI succeeds):
 
-When live sync seems broken, use this ladder (do **not** put version checks inside the hot hook command):
+\`\`\`bash
+"<cli_path>" hooks install --json
+\`\`\`
+
+3. Confirm wiring from references if you need detail: \`references/hooks-claude.md\`, \`references/hooks-codex.md\`, and the Codex launcher \`references/codex-sync-hook.cjs\`.
+   - **SessionStart → \`wake\`** (CLI/skill repair + kick pending backfill/sync worker)
+   - **Stop → \`sync\`** (live turn; stdin session hint)
+4. For Codex: ask the user to run \`/hooks\`, review, and **trust** the handlers. File write ≠ trusted ≠ Cloud upload succeeded.
 
-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.
+### Hook diagnostics (reference)
 
-## Step 5 — Activate live sync
+When live sync seems broken:
 
-With user consent for privacy roots:
+1. \`"<cli_path>" status --json\`
+2. \`"<cli_path>" sync status --source claude-code --json\` / \`--source codex\`
+   - \`paused\` / \`not_due\` → expected quiet wake
+   - \`pending\` / \`running\` → work in flight
+   - \`degraded\` → inspect \`last_error_code\` (e.g. \`spawn_failed\`)
+3. Claude hooks must stay silent (exit 0). Codex launcher prints only \`{}\`.
 
-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 5 — Optional: import recent history
 
-## Step 6 — Optional: import recent history in the background
+Only if the user wants older transcripts. Historical import is **optional**, runs in the **background**, and is **resumable** across later \`wake\`/\`sync\` — sleep and restarts are fine. Choose the history that is useful; do not pressure for a tiny window.
 
-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.
+**Copy for the user:** calm and encouraging. Avoid harsh openers like “Optional; drains in bounded slices over time.” Prefer: “We can import recent history in the background — it’s resumable, so a wider window is a safe pick.”
 
-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.
+**Window choices to offer:** 30 days · 90 days · 180 days · all available history (still bounded by what exists on disk; CLI freezes \`until_at = now\`). When possible, give a rough sense of scale (how many sessions / projects sit under approved directories) before they choose.
+
+Live-hook consent does **not** grant historical-import consent. Ask which **detected** sources should import history.
 
 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.
+1. Agree \`--since <RFC3339>\` (sessions modified since that time through now; selection is by transcript-file mtime).
+2. For each selected source, queue a slice, then **\`wake\`** so draining does not wait for the next session:
+
+\`\`\`bash
+"<cli_path>" backfill start --source claude-code --since <RFC3339> --json
+"<cli_path>" wake --source claude-code --json
+"<cli_path>" backfill start --source codex --since <RFC3339> --json
+"<cli_path>" wake --source codex --json
+\`\`\`
+
+3. Explain: live turns stay first; history continues in the background. Pause/resume without discarding progress:
+   \`"<cli_path>" sync pause\` / \`"<cli_path>" sync resume\`
+   Monitor: \`"<cli_path>" sync status --source claude-code --json\` (and codex as needed).
+
+Do **not** run unrestricted \`source scan\` or a ceremonial \`sync --force\` “smoke test” during setup. \`wake\` after backfill is the right kick; the first real Stop-hook \`sync\` under an approved directory confirms the live path.
 
 ## 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.
+Inspect durable facts (\`auth status\`, \`source list\`, \`status\`, per-source \`sync status\`) and continue at the first incomplete step. Repeated \`onboard\`, \`source detect\`, approved snapshot retries, \`hooks install\`, and \`approve-dir\` are safe when they follow the rules above.
 `;
 }
 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.",
+        $comment: "Non-enforced init snapshot template. Cloud accepts any JSON object + 256 KiB cap. User-facing language: approved directories (JSON key remains scope.approved_roots). Do NOT include teammate role or scope.mode. Omit unknown optional fields rather than inventing zeros.",
+        $field_guide: {
+            high_value: "repositories (with remotes/languages for active work), harnesses, identity_signals, teammates (from git, humans only), scope.approved_roots, transcript_inventory, skills (repo-scanned counts), cli_version",
+            repository_detail: "Full metadata for repos with recent agent sessions; name/remote/language is enough for the long tail. Deduplicate clones; optional local_clone_count.",
+            instruction_files: "Agent instruction docs found in the repo (AGENTS.md, CLAUDE.md, MEMORY.md, etc.). Include name + size_bytes when present.",
+            omit_if_unknown: [
+                "letta_agent_count",
+                "letta_memory_artifact_count",
+                "allowlisted_file_names",
+                "skill_names on repositories (use top-level skills instead)",
+            ],
+        },
         repositories: [
             {
                 display_name: "my-repo",
@@ -187,16 +243,18 @@ function initSnapshotTemplate() {
                 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" }],
+        skills: [
+            {
+                directory: "my-repo/.claude/skills",
+                skill_count: 1,
+                sample_names: ["deploy"],
+            },
+        ],
         identity_signals: [{ type: "git_email", value: "dev@acme.com" }],
-        transcript_inventory: [{ source_key: "sess-1", session_count: 3, segment_count: 10 }],
+        transcript_inventory: [{ source_key: "claude-code", session_count: 3 }],
         teammates: [
             {
                 display_name: "Alex",
@@ -204,17 +262,18 @@ function initSnapshotTemplate() {
             },
         ],
         scope: { approved_roots: [] },
-        cli_version: "0.0.3",
+        cli_version: (0, version_1.packageVersion)(),
     }, 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.
+Install **globally** in \`~/.claude/settings.json\` (user scope). Prefer \`dreams hooks install --dry-run\` / \`dreams hooks install\` so the CLI owns the merge. Manual merge is fallback only.
 
 ## 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.
+- **SessionStart → \`dreams wake\`** — repair managed CLI/skill quietly; kick pending sync/backfill worker (no live-turn stdin hint).
+- **Stop → \`dreams sync\`** — after each live turn; pipe hook JSON stdin so \`session_id\` can be a live hint.
 
 ## Platform-specific commands
 
@@ -222,27 +281,18 @@ 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" wake >/dev/null 2>&1 || true # dreams-sync-hook
 "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' wake *> $null; exit 0 # dreams-sync-hook
 & '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
@@ -253,7 +303,7 @@ Rules:
         "hooks": [
           {
             "type": "command",
-            "command": "\\"CLI_PATH\\" sync >/dev/null 2>&1 || true # dreams-sync-hook"
+            "command": "\\"CLI_PATH\\" wake >/dev/null 2>&1 || true # dreams-sync-hook"
           }
         ]
       }
@@ -283,7 +333,7 @@ Rules:
           {
             "type": "command",
             "shell": "powershell",
-            "command": "& 'CLI_PATH' sync *> $null; exit 0 # dreams-sync-hook"
+            "command": "& 'CLI_PATH' wake *> $null; exit 0 # dreams-sync-hook"
           }
         ]
       }
@@ -303,42 +353,82 @@ Rules:
 }
 \`\`\`
 
-## Idempotent merge checklist
+## Notes
 
-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\`
+- Prefer \`dreams hooks install\` (with \`--dry-run\` for consent). Keep \`# dreams-sync-hook\` markers; update in place; never append duplicates.
+- Hooks must stay silent and exit 0. Silence is not proof of Cloud upload success.
+- \`dreams sync pause\` / \`dreams sync resume\` toggle without uninstalling.
+- Diagnostics: \`dreams sync status --json\`.
+`;
+}
+function codexHooksReference() {
+    return `# Codex — Dreams live sync hooks
 
-## Notes
+Install **user-level** hooks in \`~/.codex/hooks.json\`. Prefer \`dreams hooks install --dry-run\` / \`dreams hooks install\`.
+
+Also ensure:
 
-### No-op contracts
+\`\`\`toml
+[features]
+hooks = true
+\`\`\`
+
+## Goal
+
+- **SessionStart → \`wake --source codex\`** via the Node launcher
+- **Stop → \`sync --source codex\`** via the Node launcher (forwards stdin; prints \`{}\`)
+
+## Why a Node launcher
+
+Codex Stop expects exactly one JSON object on stdout. Use \`references/codex-sync-hook.cjs\`:
+
+\`\`\`bash
+node "HOOK_SCRIPT" "CLI_PATH" wake # dreams-sync-hook-codex
+node "HOOK_SCRIPT" "CLI_PATH" sync # dreams-sync-hook-codex
+\`\`\`
 
-- 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
+## Example merge fragment
+
+\`\`\`json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \\"HOOK_SCRIPT\\" \\"CLI_PATH\\" wake # dreams-sync-hook-codex"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \\"HOOK_SCRIPT\\" \\"CLI_PATH\\" sync # dreams-sync-hook-codex"
+          }
+        ]
+      }
+    ]
+  }
+}
+\`\`\`
 
-### Robustness
+## Trust (\`/hooks\`)
 
-- \`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\`.
+Ask the user to run \`/hooks\`, review, and trust. File write ≠ trusted ≠ Cloud upload succeeded.
 
-### Other
+## Notes
 
-- 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.
+- Launcher stdout must be \`{}\\n\` with exit 0.
+- After backfill, kick with \`dreams wake --source codex --json\` (not a ceremonial sync --force smoke test).
 `;
 }
+function codexSyncHookScript() {
+    return fs.readFileSync(path.join(__dirname, "..", "bin", "dreams-codex-hook.cjs"), "utf8");
+}
 function readFile(file) {
     try {
         return fs.readFileSync(file, "utf8");
@@ -388,6 +478,8 @@ function desiredArtifacts() {
         { path: skillFilePath(), contents: skillContent((0, version_1.packageVersion)()) },
         { path: initSnapshotTemplatePath(), contents: initSnapshotTemplate() },
         { path: claudeHooksReferencePath(), contents: claudeHooksReference() },
+        { path: codexHooksReferencePath(), contents: codexHooksReference() },
+        { path: codexSyncHookScriptPath(), contents: codexSyncHookScript() },
     ];
 }
 function installSkill() {

package/dist/suppress-sqlite-warning.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * node:sqlite still emits ExperimentalWarning on load in Node 22.x even though
+ * the flag is no longer required at >= 22.13. Filter only that warning so agent
+ * transcripts and --json workflows stay clean; leave other warnings alone.
+ *
+ * Must run before the first `node:sqlite` import (see cli.ts import order and
+ * bin/dreams.cjs preflight).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.suppressSqliteExperimentalWarning = suppressSqliteExperimentalWarning;
+const SQLITE_EXPERIMENTAL = /SQLite is an experimental feature|ExperimentalWarning:.*SQLite|node:sqlite/i;
+let installed = false;
+function suppressSqliteExperimentalWarning() {
+    if (installed)
+        return;
+    installed = true;
+    const originalEmit = process.emit.bind(process);
+    function filteredEmit(event, ...args) {
+        if (event === "warning" && args.length > 0) {
+            const warning = args[0];
+            if (warning &&
+                typeof warning === "object" &&
+                warning.name === "ExperimentalWarning" &&
+                typeof warning.message === "string" &&
+                SQLITE_EXPERIMENTAL.test(warning.message)) {
+                return false;
+            }
+        }
+        return Reflect.apply(originalEmit, process, [event, ...args]);
+    }
+    process.emit = filteredEmit;
+}
+suppressSqliteExperimentalWarning();