create-quiver 0.15.2 → 0.15.4

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-00-foundation-and-handoffs/slice.json

@@ -0,0 +1,61 @@
+{
+  "slice_id": "slice-00-foundation-and-handoffs",
+  "ticket": "QUIVER-36-00",
+  "type": "documentation",
+  "title": "Foundation and handoffs",
+  "objective": "Create the approved SDD package for the portable AI run watcher without implementing runtime code.",
+  "description": "Defines the spec, execution plan, evidence skeleton, PR body, and per-slice execution/closure handoffs.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v36-ai-run-watch-foundation",
+    "branch_name": "feature/QUIVER-36-00-v36-ai-run-watch-foundation"
+  },
+  "files": [
+    "specs/quiver-v36-ai-run-watch-portable/**"
+  ],
+  "expected_read_paths": [
+    "docs/INDEX.md.template",
+    "docs/CLI_UX_GUIDE.md",
+    "README_FOR_AI.md",
+    "specs/quiver-v35-compact-dashboard-version-ux/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "specs/quiver-v36-ai-run-watch-portable/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "This foundation defines all later slice contracts.",
+  "must": [
+    "Create the v36 spec package.",
+    "Create execution and closure briefs for every slice.",
+    "Create JSON handoff files for every slice.",
+    "Do not implement runtime code."
+  ],
+  "not_included": [
+    "Run schema implementation.",
+    "Provider streaming implementation.",
+    "Watcher command implementation."
+  ],
+  "acceptance": [
+    "Spec package exists under specs/quiver-v36-ai-run-watch-portable.",
+    "Each slice has EXECUTION_BRIEF.md, CLOSURE_BRIEF.md, and slice.json.",
+    "slice-00 is completed and slice-01 is ready.",
+    "No runtime code is changed."
+  ],
+  "tests": [
+    "node -e \"const fs=require('fs'); for (const f of process.argv.slice(1)) JSON.parse(fs.readFileSync(f,'utf8')); console.log('slice json ok')\" specs/quiver-v36-ai-run-watch-portable/slices/*/slice.json",
+    "npx create-quiver spec validate specs/quiver-v36-ai-run-watch-portable --strict",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Confirm every slice JSON parses.",
+    "Confirm no runtime implementation files changed."
+  ],
+  "estimated_hours": 1,
+  "status": "completed",
+  "started_at": "2026-05-28T00:00:00Z",
+  "completed_at": "2026-05-28T00:00:00Z",
+  "actual_hours": 1,
+  "blocked_reason": null
+}

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-01-run-schema-path-safety/CLOSURE_BRIEF.md

@@ -0,0 +1,18 @@
+# CLOSURE_BRIEF - slice-01 Run schema and path safety
+
+## Summary
+
+Pending implementation.
+
+## Validation
+
+- [ ] `node --test tests/lib/ai-run-state.test.js`
+- [ ] `git diff --check`
+
+## Pending
+
+- Implement run schema and path safety.
+
+## Remaining Risks
+
+- Prefix-only path checks would leave traversal risk; validate with realpath/path resolution and strict id regex.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-01-run-schema-path-safety/EXECUTION_BRIEF.md

@@ -0,0 +1,43 @@
+# EXECUTION_BRIEF - slice-01 Run schema and path safety
+
+## Context
+
+The watcher must never treat a user-provided run id as a file path. This slice creates the safe foundation for all run and event files.
+
+## Objective
+
+Define and implement run id validation, path-safe run lookup, run schema v1, event schema v1, and status normalization.
+
+## Scope
+
+- Run id generator and validator
+- Safe `.quiver/runs/<run-id>` path resolver
+- `run.json` schema v1
+- `events.jsonl` event schema v1
+- Status catalog for `pending`, `running`, `completed`, `failed`, `canceled`
+- Focused tests for valid/invalid ids and traversal rejection
+
+## Acceptance Criteria
+
+- Generated run ids match the approved regex.
+- `watch --run` style validation rejects traversal, absolutes, separators, empty ids, and malformed ids.
+- Safe path resolution guarantees resolved paths stay inside `.quiver/runs`.
+- `run.json` and event schema helpers produce required fields.
+- Stale is represented as derived state, not persisted status.
+
+## Technical Plan Summary
+
+Add small, testable helpers before any writer or watcher reads from disk.
+
+## Restrictions
+
+- Do not implement streaming writer yet.
+- Do not implement `ai run watch` yet.
+- Do not modify provider execution yet.
+
+## Completion Checklist
+
+- [ ] Run id helper added.
+- [ ] Safe path resolver added.
+- [ ] Schemas documented in code/tests.
+- [ ] Path-safety tests pass.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-01-run-schema-path-safety/slice.json

@@ -0,0 +1,65 @@
+{
+  "slice_id": "slice-01-run-schema-path-safety",
+  "ticket": "QUIVER-36-01",
+  "type": "feature",
+  "title": "Run schema and path safety",
+  "objective": "Define run id validation, safe run paths, run schema v1, event schema v1, and status normalization before persistence or watching.",
+  "description": "Creates the path-safe foundation for all portable AI run watch behavior.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v36-run-schema-path-safety",
+    "branch_name": "feature/QUIVER-36-01-v36-run-schema-path-safety"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/run-state.js",
+    "tests/lib/ai-run-state.test.js"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/ai/run-state.js",
+    "src/create-quiver/lib/paths.js",
+    "tests/lib/ai-run-state.test.js",
+    "specs/quiver-v36-ai-run-watch-portable/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/run-state.js",
+    "tests/lib/ai-run-state.test.js",
+    "specs/quiver-v36-ai-run-watch-portable/**"
+  ],
+  "depends_on": [
+    "slice-00-foundation-and-handoffs"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "All later slices depend on the schema and path-safety contract.",
+  "must": [
+    "Generate run ids with the approved format.",
+    "Validate run ids with a strict regex.",
+    "Reject traversal, absolute paths, separators, and malformed ids.",
+    "Resolve run paths inside .quiver/runs only.",
+    "Define run.json and event schema v1 helpers.",
+    "Keep stale as derived state."
+  ],
+  "not_included": [
+    "Event writer.",
+    "Provider streaming.",
+    "Watch command."
+  ],
+  "acceptance": [
+    "Valid generated run ids pass validation.",
+    "Invalid run ids fail with actionable errors.",
+    "Path traversal inputs cannot resolve outside .quiver/runs.",
+    "Schema helpers include required run and event fields.",
+    "Tests cover Windows-style separators and paths with spaces."
+  ],
+  "tests": [
+    "node --test tests/lib/ai-run-state.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Include tests for .., /, \\\\, absolute paths, empty values, and malformed ids.",
+    "Use path resolution rather than string prefix checks."
+  ],
+  "estimated_hours": 4,
+  "status": "ready",
+  "blocked_reason": null
+}

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-02-event-writer-redacted-logs/CLOSURE_BRIEF.md

@@ -0,0 +1,18 @@
+# CLOSURE_BRIEF - slice-02 Event writer and redacted logs
+
+## Summary
+
+Pending implementation.
+
+## Validation
+
+- [ ] `node --test tests/lib/ai-run-events.test.js`
+- [ ] `git diff --check`
+
+## Pending
+
+- Implement event writer and redacted logs.
+
+## Remaining Risks
+
+- Redacting only each raw chunk can leak secrets split across chunks; use line buffering or a sliding window.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-02-event-writer-redacted-logs/EXECUTION_BRIEF.md

@@ -0,0 +1,43 @@
+# EXECUTION_BRIEF - slice-02 Event writer and redacted logs
+
+## Context
+
+Provider output can contain secrets, ANSI redraw controls, and large logs. The writer must make persisted artifacts safe before provider streaming and watch are wired.
+
+## Objective
+
+Implement append-only event and log writing with redaction, sanitization, monotonic sequence numbers, concurrent-read tolerance, and log truncation.
+
+## Scope
+
+- Event writer module
+- Redacted stdout/stderr log appenders
+- Chunk-aware redaction
+- ANSI/control character sanitization
+- Log caps and `log_truncated` events
+- Tests for concurrent/partial reads and split secrets
+
+## Acceptance Criteria
+
+- Event `seq` is monotonic per run.
+- Events are append-only JSONL.
+- Watchers can read while the writer appends.
+- Secrets split across chunks are redacted before persistence.
+- ANSI and unsafe control chars are sanitized.
+- Log caps produce `log_truncated`.
+
+## Technical Plan Summary
+
+Build the persistence layer independent of provider execution so later slices can reuse it.
+
+## Restrictions
+
+- Do not modify provider execution yet.
+- Do not implement watcher CLI yet.
+
+## Completion Checklist
+
+- [ ] Event writer added.
+- [ ] Redacted log appenders added.
+- [ ] Split secret tests pass.
+- [ ] Partial JSONL read tests pass.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-02-event-writer-redacted-logs/slice.json

@@ -0,0 +1,66 @@
+{
+  "slice_id": "slice-02-event-writer-redacted-logs",
+  "ticket": "QUIVER-36-02",
+  "type": "feature",
+  "title": "Event writer and redacted logs",
+  "objective": "Implement safe append-only event and log persistence for AI runs.",
+  "description": "Adds the writer layer for events.jsonl, provider logs, redaction, sanitization, truncation, and sequence numbers.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v36-event-writer-redacted-logs",
+    "branch_name": "feature/QUIVER-36-02-v36-event-writer-redacted-logs"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/run-events.js",
+    "src/create-quiver/lib/evidence.js",
+    "tests/lib/ai-run-events.test.js"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/evidence.js",
+    "src/create-quiver/lib/ai/run-state.js",
+    "tests/lib/ai-run-events.test.js",
+    "specs/quiver-v36-ai-run-watch-portable/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/run-events.js",
+    "src/create-quiver/lib/evidence.js",
+    "tests/lib/ai-run-events.test.js",
+    "specs/quiver-v36-ai-run-watch-portable/**"
+  ],
+  "depends_on": [
+    "slice-01-run-schema-path-safety"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Provider streaming and watch rely on this writer contract.",
+  "must": [
+    "Write append-only events.jsonl.",
+    "Guarantee monotonic seq per run.",
+    "Redact secrets before writing logs/events.",
+    "Handle secrets split across chunks.",
+    "Sanitize ANSI and unsafe control characters.",
+    "Enforce log caps and emit log_truncated."
+  ],
+  "not_included": [
+    "Provider streaming integration.",
+    "Watch command UI."
+  ],
+  "acceptance": [
+    "Events are valid JSONL with schema_version, run_id, seq, timestamp, and type.",
+    "Concurrent reads do not crash while appending.",
+    "Partial trailing JSONL line is tolerated by readers.",
+    "Split secrets do not persist in clear text.",
+    "Log truncation is observable through an event."
+  ],
+  "tests": [
+    "node --test tests/lib/ai-run-events.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use fixtures with chunk boundaries inside tokens/passwords.",
+    "Use ANSI clear-screen and cursor movement examples."
+  ],
+  "estimated_hours": 6,
+  "status": "planned",
+  "blocked_reason": null
+}

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-03-provider-streaming-integration/CLOSURE_BRIEF.md

@@ -0,0 +1,18 @@
+# CLOSURE_BRIEF - slice-03 Provider streaming integration
+
+## Summary
+
+Pending implementation.
+
+## Validation
+
+- [ ] `node --test tests/lib/provider-streaming.test.js tests/commands/ai-plan.test.js`
+- [ ] `git diff --check`
+
+## Pending
+
+- Integrate run event writer with provider execution.
+
+## Remaining Risks
+
+- Provider execution changes can regress dry-run/print-prompt/JSON contracts; focused tests must cover those modes.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-03-provider-streaming-integration/EXECUTION_BRIEF.md

@@ -0,0 +1,41 @@
+# EXECUTION_BRIEF - slice-03 Provider streaming integration
+
+## Context
+
+Quiver currently runs providers through adapter code. This slice wires the safe writer into live provider execution without changing dry-run, print-prompt, JSON, CI, or no-TTY behavior.
+
+## Objective
+
+Stream provider stdout/stderr into events/logs for planner-oriented live commands.
+
+## Scope
+
+- Provider runner streaming hooks
+- Run creation for live provider execution
+- Heartbeat and stage events
+- Redacted `prompt.md`
+- `result.md` when applicable
+- Tests with simulated provider output
+
+## Acceptance Criteria
+
+- Live provider execution creates a run directory and run id.
+- Provider stdout/stderr stream to events and redacted logs.
+- Heartbeat or updated timestamps keep active runs observable.
+- Existing dry-run, print-prompt, JSON, CI, and no-TTY behavior stays clean.
+- Provider/model validation behavior is not weakened.
+
+## Technical Plan Summary
+
+Integrate through provider runner options or a narrow wrapper so AI commands do not duplicate streaming logic.
+
+## Restrictions
+
+- Do not implement watcher CLI in this slice.
+- Do not add required external terminal tools.
+
+## Completion Checklist
+
+- [ ] Provider streaming hooks added.
+- [ ] Planner-oriented live commands produce run artifacts.
+- [ ] Simulated streaming tests pass.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-03-provider-streaming-integration/slice.json

@@ -0,0 +1,71 @@
+{
+  "slice_id": "slice-03-provider-streaming-integration",
+  "ticket": "QUIVER-36-03",
+  "type": "feature",
+  "title": "Provider streaming integration",
+  "objective": "Persist live provider stdout, stderr, stages, heartbeat, prompt, and result artifacts for planner-oriented AI commands.",
+  "description": "Wires the event writer into live provider execution without changing clean automation modes.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v36-provider-streaming-integration",
+    "branch_name": "feature/QUIVER-36-03-v36-provider-streaming-integration"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/run-events.js",
+    "tests/lib/provider-streaming.test.js",
+    "tests/commands/ai-plan.test.js"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/run-events.js",
+    "src/create-quiver/lib/ai/run-state.js",
+    "specs/quiver-v36-ai-run-watch-portable/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/run-events.js",
+    "tests/lib/provider-streaming.test.js",
+    "tests/commands/ai-plan.test.js",
+    "specs/quiver-v36-ai-run-watch-portable/**"
+  ],
+  "depends_on": [
+    "slice-02-event-writer-redacted-logs"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Provider integration is central and affects several AI commands.",
+  "must": [
+    "Use child_process.spawn without shell.",
+    "Stream stdout/stderr to events and logs.",
+    "Write redacted prompt.md and result.md when applicable.",
+    "Emit heartbeat or updated_at events.",
+    "Preserve dry-run, print-prompt, JSON, CI, and no-TTY contracts.",
+    "Keep provider/model validation unchanged."
+  ],
+  "not_included": [
+    "Watcher command rendering.",
+    "Documentation updates."
+  ],
+  "acceptance": [
+    "Live planner-oriented commands create run artifacts.",
+    "Simulated stdout/stderr appears in redacted logs and events.",
+    "No provider output contaminates JSON mode.",
+    "Dry-run and print-prompt do not execute providers.",
+    "Provider errors are recorded and surfaced actionably."
+  ],
+  "tests": [
+    "node --test tests/lib/provider-streaming.test.js tests/commands/ai-plan.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use injected spawn/provider runners for deterministic tests.",
+    "Test both success and failure exits."
+  ],
+  "estimated_hours": 7,
+  "status": "planned",
+  "blocked_reason": null
+}

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-04-ai-run-watch-command/CLOSURE_BRIEF.md

@@ -0,0 +1,18 @@
+# CLOSURE_BRIEF - slice-04 AI run watch command
+
+## Summary
+
+Pending implementation.
+
+## Validation
+
+- [ ] `node --test tests/commands/ai-run-watch.test.js tests/lib/ai-run-watch.test.js`
+- [ ] `git diff --check`
+
+## Pending
+
+- Implement `ai run watch`.
+
+## Remaining Risks
+
+- JSONL mode can be contaminated by human headers if not routed separately.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-04-ai-run-watch-command/EXECUTION_BRIEF.md

@@ -0,0 +1,44 @@
+# EXECUTION_BRIEF - slice-04 AI run watch command
+
+## Context
+
+After runs and events are persisted safely, users need a portable command to replay and follow events from another terminal.
+
+## Objective
+
+Implement `npx create-quiver ai run watch --run <run-id>`, `--latest`, and `--json`.
+
+## Scope
+
+- CLI parsing/routing for `ai run watch`
+- Replay + follow behavior
+- Human output
+- JSONL output
+- `--latest` selection
+- Stale, missing, completed, failed, canceled, and legacy handling
+- `Ctrl+C` watcher-only cancellation
+
+## Acceptance Criteria
+
+- `watch --run <id>` replays history and follows active runs.
+- `watch --json` emits JSONL only.
+- `watch --latest` selects deterministically and reports the selected run in human mode.
+- Missing or malformed runs fail actionably.
+- Completed runs summarize and exit.
+- `Ctrl+C` stops only the watcher.
+
+## Technical Plan Summary
+
+Implement the watcher on top of run-state and run-event readers, not provider-specific code.
+
+## Restrictions
+
+- Do not add terminal multiplexer dependencies.
+- Do not embed provider TUI output.
+
+## Completion Checklist
+
+- [ ] Watch command routed.
+- [ ] Human replay/follow implemented.
+- [ ] JSONL replay/follow implemented.
+- [ ] Edge-case tests pass.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-04-ai-run-watch-command/slice.json

@@ -0,0 +1,73 @@
+{
+  "slice_id": "slice-04-ai-run-watch-command",
+  "ticket": "QUIVER-36-04",
+  "type": "feature",
+  "title": "AI run watch command",
+  "objective": "Add a portable watcher command that replays and follows run events in human and JSONL modes.",
+  "description": "Implements the public watcher surface for run ids, latest selection, legacy runs, stale runs, and terminal statuses.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v36-ai-run-watch-command",
+    "branch_name": "feature/QUIVER-36-04-v36-ai-run-watch-command"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/run-watch.js",
+    "src/create-quiver/index.js",
+    "tests/commands/ai-run-watch.test.js",
+    "tests/lib/ai-run-watch.test.js"
+  ],
+  "expected_read_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/index.js",
+    "src/create-quiver/lib/ai/run-state.js",
+    "src/create-quiver/lib/ai/run-events.js",
+    "specs/quiver-v36-ai-run-watch-portable/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/run-watch.js",
+    "src/create-quiver/index.js",
+    "tests/commands/ai-run-watch.test.js",
+    "tests/lib/ai-run-watch.test.js",
+    "specs/quiver-v36-ai-run-watch-portable/**"
+  ],
+  "depends_on": [
+    "slice-01-run-schema-path-safety",
+    "slice-02-event-writer-redacted-logs"
+  ],
+  "parallel_safe": "conditional",
+  "parallel_safe_reason": "Can proceed after the event contract is stable if it does not modify provider execution.",
+  "must": [
+    "Support --run <run-id>.",
+    "Support --latest.",
+    "Reject --run with --latest.",
+    "Support --json JSONL output.",
+    "Replay existing events and follow active runs.",
+    "Handle missing, legacy, stale, completed, failed, and canceled runs.",
+    "Ensure Ctrl+C stops only the watcher."
+  ],
+  "not_included": [
+    "Provider streaming integration.",
+    "Main command progress guidance."
+  ],
+  "acceptance": [
+    "Human watch output is useful for active and completed runs.",
+    "JSON watch output is pure JSONL.",
+    "--latest selection is deterministic.",
+    "Malformed run ids are rejected before file access.",
+    "Legacy runs do not crash the command."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-run-watch.test.js tests/lib/ai-run-watch.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Test partial trailing JSONL lines.",
+    "Test multiple active runs for latest tie-breaking."
+  ],
+  "estimated_hours": 7,
+  "status": "planned",
+  "blocked_reason": null
+}

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-05-main-progress-user-guidance/CLOSURE_BRIEF.md

@@ -0,0 +1,18 @@
+# CLOSURE_BRIEF - slice-05 Main progress and user guidance
+
+## Summary
+
+Pending implementation.
+
+## Validation
+
+- [ ] `node --test tests/commands/ai-plan.test.js tests/commands/ai-revise.test.js tests/commands/ai-run-watch.test.js`
+- [ ] `git diff --check`
+
+## Pending
+
+- Implement main command UX integration after provider streaming and watcher slices are complete.
+
+## Remaining Risks
+
+- Human progress can accidentally leak into JSON/no-TTY paths if output routing is not isolated.

package/specs/quiver-v36-ai-run-watch-portable/slices/slice-05-main-progress-user-guidance/EXECUTION_BRIEF.md

@@ -0,0 +1,44 @@
+# EXECUTION_BRIEF - slice-05 Main progress and user guidance
+
+## Context
+
+After provider runs persist events and `ai run watch` exists, the main command should make the feature discoverable without streaming raw provider output into the primary terminal.
+
+## Objective
+
+Update planner-oriented live AI commands so users see stable Quiver progress, the generated run id, and the exact watch command for the current run.
+
+## Scope
+
+- Main terminal progress for live provider-backed commands
+- Run id display
+- Watch command display
+- CI, no-TTY, `--json`, `--print-prompt`, and `--dry-run` behavior
+- Provider failure/cancel user guidance
+
+## Acceptance Criteria
+
+- Live provider-backed commands print the generated run id in human TTY mode.
+- Human TTY output prints `npx create-quiver ai run watch --run <run-id>`.
+- Main output remains stable and does not stream raw provider stdout/stderr by default.
+- CI, no-TTY, `--json`, and `--print-prompt` remain clean and automation-safe.
+- `--dry-run` does not create live run artifacts unless explicitly documented as a preview.
+- Provider failures keep actionable context without exposing secrets.
+- `Ctrl+C` in the main provider command marks the run canceled when a run was created.
+
+## Technical Plan Summary
+
+Wire the run metadata returned by provider execution into the existing command UX layer. Keep human progress and machine output on separate paths.
+
+## Restrictions
+
+- Do not change existing JSON contracts except to add documented fields only if the SPEC requires them.
+- Do not print provider raw logs in the main command by default.
+- Do not make the watcher mandatory for command completion.
+
+## Completion Checklist
+
+- [ ] Main commands show run id and watch command in human TTY mode.
+- [ ] Automation modes remain uncontaminated.
+- [ ] Dry-run and print-prompt behavior are preserved.
+- [ ] Failure and cancellation states update run metadata.