holistic 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.5.5 - 2026-04-10
+
+Major Security & Trust Hardening (M005) to eliminate silent automation and improve auditability.
+
+- Added **Consent Gating** to `holistic bootstrap`: The CLI now displays a summary of system-modifying actions (daemon, hooks, Claude setup) and requires an explicit `--yes` flag to apply them.
+- Added `holistic doctor` command for repository setup diagnostics and background sync health monitoring.
+- Implemented **Privacy-First Defaults**: Remote portable-state syncing is now disabled by default. Users must explicitly opt-in by setting `"portableState": true` in the repo config.
+- Eliminated **Silent Error Suppression**: Background sync scripts (PowerShell & Bash) now use timestamped logging to `.holistic/system/sync.log`. Failures are now visible in `holistic doctor` and `holistic status`.
+- Hardened **Git-Native Snapshotting**: Refactored repo snapshotting to use `git ls-files`, ensuring $O(\text{changes})$ performance and native `.gitignore` compliance.
+- Gated **Handoff Commits by Default**: Removed automatic Git commits from the `handoff` command. Holistic now prepares a `pending-commit.txt` for manual review, with an optional `--commit` flag for automated workflows.
+
+## 0.5.4 - 2026-04-09
+
+Security hardening in response to socket.dev AI-based package scanner flags.
+
+- Removed `-WindowStyle Hidden` from the Windows daemon startup `.cmd` — the daemon now runs in a visible window, consistent with how macOS and Linux handle it.
+- Downgraded PowerShell execution policy from `-ExecutionPolicy Bypass` to `-ExecutionPolicy RemoteSigned` in all three generation sites (`setup.ts`, `sync.ts`, `bin/holistic.cmd`). `RemoteSigned` is sufficient for locally-generated scripts and does not suppress antivirus or security monitoring.
+- Fixed a real code quality bug in `bin/holistic.cmd`: the `COMMIT_MSG` variable read from `pending-commit.txt` was used unquoted in a `git commit -m` call. Special characters (`&`, `|`, `>`, `<`, `"`) are now stripped before use to prevent cmd.exe argument injection.
+- Added `SECURITY.md` with transparent disclosure of what Holistic installs (daemon, startup entries, git sync), what it does not do (no exfiltration, no credential access, no external services), and an explanation of known scanner false positives.
+- Added Security & Privacy section to `README.md` linking to `SECURITY.md`.
+
 ## 0.5.3 - 2026-04-09
 
 Hardened state management for fresh repos and path-moved environments, and added a repair command to regenerate stale machine-local helpers.

package/README.md

@@ -12,14 +12,32 @@ Your repo remembers, so your next agent doesn't have to guess.
 Shared memory for AI agents, built into your repo.
 ```
 
+[![npm version](https://img.shields.io/npm/v/holistic.svg)](https://www.npmjs.com/package/holistic)
+[![Tests](https://img.shields.io/github/actions/workflow/status/lweiss01/holistic/test.yml?branch=main&label=tests)](https://github.com/lweiss01/holistic/actions)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D24-339933.svg)](./package.json)
+
 ### One command. Every agent. Zero re-explaining. ✨
 
 Holistic gives your AI agents shared memory inside the repo itself. When you switch from Claude to Codex to Gemini, the next agent can see what happened last time, what not to break, and what should happen next.
 
-![Holistic demo: before and after workflow comparison](docs/demo.gif)
 
 ---
 
+
+### Why trust this?
+
+- 🔐 No known security vulnerabilities
+- 🧪 60+ automated tests covering core flows
+- 🛠️ Actively maintained (frequent releases)
+- 🔍 Transparent local setup (see `SECURITY.md`)
+
+> Early beta, but built to be safe, inspectable, and predictable.
+
+
+---
+
+
 ## Get started in 30 seconds ⚡
 
 Open your project repo in PowerShell, Terminal, Command Prompt, or whatever shell you normally use.
@@ -30,7 +48,7 @@ Run these two commands:
 
 ```bash
 npm install -g holistic
-holistic bootstrap
+holistic bootstrap --yes
 ```
 
 After that, open the repo in your agent app and use this startup prompt:
@@ -43,8 +61,10 @@ That is enough to get the basic Holistic workflow working.
 
 If you want the fuller install and setup details, jump to [Quick start](#quick-start-).
 
+
 ---
 
+
 ## The problem 😵
 
 If you use more than one AI coding assistant, the workflow usually falls apart:
@@ -57,8 +77,10 @@ If you use more than one AI coding assistant, the workflow usually falls apart:
 
 Holistic fixes that by making the repo the source of truth.
 
+
 ---
 
+
 ## What it feels like with HOLISTIC 🌿
 
 Run one setup command on a machine:
@@ -78,8 +100,10 @@ Most days, you do not need to keep a terminal process open or manually re-brief
 
 `holistic bootstrap` is a machine setup command, not just a repo setup command. By default it can install local startup helpers and configure Claude Desktop MCP on that machine.
 
+
 ---
 
+
 ## How it works 🧭
 
 ```text
@@ -98,8 +122,10 @@ Holistic checkpoints and handoffs keep repo memory current
 The next agent picks up without a long re-explanation
 ```
 
+
 ---
 
+
 ## Quick start 🚀
 
 ### Install 📦
@@ -138,8 +164,8 @@ npm link
 
 ```bash
 cd my-project
-holistic bootstrap --remote origin
-git add .gitattributes HOLISTIC.md AGENTS.md CLAUDE.md GEMINI.md HISTORY.md
+holistic bootstrap --remote origin --yes
+git add .gitattributes HOLISTIC.md AGENTS.md CLAUDE.md GEMINI.md
 git add .holistic/config.json .holistic/state.json
 git add .holistic/context/
 git commit -m "feat: add holistic"
@@ -172,8 +198,10 @@ holistic bootstrap --install-daemon false --configure-mcp false
 
 The portable repo memory is meant to be committed and synced. Machine-local helper scripts are generated for each machine and stay local.
 
+
 ---
 
+
 ## Daily workflow 🔄
 
 One-time machine setup:
@@ -202,8 +230,10 @@ If `holistic` is not on `PATH` in a given shell, every bootstrapped repo also ha
 - Windows: `.\.holistic\system\holistic.cmd <command>`
 - macOS/Linux: `./.holistic/system/holistic <command>`
 
+
 ---
 
+
 ## Regression protection 🛡️
 
 When an agent fixes something delicate, lock it in:
@@ -217,8 +247,10 @@ holistic checkpoint \
 
 Future agents will see that warning in the repo docs before they touch the risky area again.
 
+
 ---
 
+
 ## Works with multiple agent apps 🤝
 
 Holistic is model-agnostic. It works through repo files first, and can expose a thin MCP server where supported.
@@ -240,8 +272,10 @@ Use this table to decide whether startup should be automatic (MCP/tooling hook)
 | Other VS Code forks | `AGENTS.md` and repo docs | ❌ No | Treat as manual-start and run `/holistic` |
 | Web tools | repo docs pasted manually | ❌ No | Manual copy/paste recap from Holistic docs |
 
+
 ---
 
+
 ## What lives in your repo 🗂️
 
 ```text
@@ -250,7 +284,11 @@ my-project/
 |- AGENTS.md
 |- CLAUDE.md
 |- GEMINI.md
-|- HISTORY.md
+|- .cursorrules
+|- .windsurfrules
+|- .gitattributes
+|- .github/
+|  `- copilot-instructions.md
 `- .holistic/
    |- config.json
    |- state.json
@@ -263,20 +301,24 @@ my-project/
 
 The portable repo memory (config, state, context, sessions) is meant to be committed and synced. Machine-local helper scripts and repo-local CLI fallbacks under `.holistic/system/` are generated for each machine and stay local (already in `.gitignore`).
 
+
 ---
 
+
 ## Commands
 
-| Command | What it does |
-|---|---|
 | `holistic init` | Base repo setup and scaffolding |
-| `holistic bootstrap` | One-step machine setup for repo files, hooks, and by-default local daemon/MCP integration setup |
-| `holistic start --agent <name>` | Opens a session and prints the ASCII banner plus recap |
+| `holistic bootstrap` | One-step machine setup. Required `--yes` to apply system changes. |
+| `holistic doctor` | Runs health checks on machine setup and sync logs |
+| `holistic repair` | Regenerates `.holistic/system/` helpers |
+| `holistic resume / start --agent <name>` | Loads project recap and prints state |
+| `holistic start-new` | Starts a fresh session |
 | `holistic checkpoint --reason "..."` | Saves progress and context |
-| `holistic handoff` | Ends a session with a handoff |
-| `holistic status` | Shows the current state |
+| `holistic handoff` | Ends a session with a handoff message |
+| `holistic status` | Shows current state and recent sync activity |
 | `holistic diff --from <id> --to <id>` | Compares two sessions |
-| `holistic serve` | Runs the thin MCP server and prints a startup banner to `stderr` |
+| `holistic search --id <session-id>` | Finds and reactivates an archived session |
+| `holistic serve` | Runs the thin MCP server |
 | `holistic watch` | Foreground daemon mode for automatic checkpoints |
 
 ### Slash command helper text (agent-facing)
@@ -297,8 +339,10 @@ holistic handoff \
   --blocker "Need refresh token endpoint from backend team"
 ```
 
+
 ---
 
+
 ## Architecture
 
 Holistic is intentionally repo-first, not machine-first.
@@ -337,8 +381,10 @@ When you do run `holistic serve` manually in a terminal, Holistic prints its ASC
 }
 ```
 
+
 ---
 
+
 ## Why this matters
 
 If you are already using more than one AI coding assistant, you already have the continuity problem.
@@ -351,23 +397,60 @@ Holistic gives you:
 - A durable record of what changed and why
 - Agents that can get to work quickly
 
+
 ---
 
+
 ## Beta Feedback Welcome 🙏
 
 Holistic is in early beta. If you hit rough edges, unexpected behavior, or have ideas for improvement, please [open an issue](https://github.com/lweiss01/holistic/issues). Early adopter feedback directly shapes the direction of the project.
 
 For support and troubleshooting, see [SUPPORT.md](./SUPPORT.md).
 
+
+---
+
+
+## Security, Privacy, and Trust 🔒
+
+Holistic is designed to be **transparent, audit-safe, and consent-first**. It is a shared memory layer that stays in your repo, not a cloud service that watches your screen.
+
+### Trust Architecture:
+- **Explicit Consent**: `holistic bootstrap` will show you exactly what changes it wants to make to your machine (daemon installation, git hooks, Claude setup) and requires an explicit `--yes` to proceed.
+- **Privacy First**: Remote syncing is **disabled by default**. Set `"portableState": true` in `.holistic/config.json` only if you want to share memory across devices using a hidden git ref.
+- **Traceable Activity**: Background sync operations (PowerShell/Bash) are no longer silent. All activity is logged with timestamps and error details to `.holistic/system/sync.log`.
+- **Health Checks**: Use `holistic doctor` at any time to audit your machine-local setup and verify sync log health.
+- **Git-Native Snapshotting**: The repo snapshot logic uses native `git ls-files`, ensuring that your `.gitignore` rules are perfectly respected and performance stays $O(\text{repo size})$.
+- **Zero Shell Injection**: Internal commit logic has been stripped of shell wrappers to eliminate command injection risks.
+
+### What it does:
+- Writes session state into `.holistic/` inside your repo (committed files you control)
+- Installs a daemon via standard OS autostart (Windows Startup folder, macOS LaunchAgents, Linux systemd user)
+- Can push Holistic state to a hidden git ref on your configured remote (opt-in, your repo only)
+
+### What it does NOT do:
+- Does not read or transmit file contents outside your repo
+- Does not access credentials or tokens
+- Does not phone home to any external service
+- Does not use obfuscated scripts or hidden windows
+
+For the full technical disclosure, see [SECURITY.md](./SECURITY.md).
+
+
 ---
 
+
 ## Quick links
 
 - [Walkthrough](./docs/handoff-walkthrough.md)
+- [Security & Privacy](./SECURITY.md)
 - [Changelog](./CHANGELOG.md)
 - [Contributing](./CONTRIBUTING.md)
 - [License](./LICENSE)
 
+
+
 ---
 
+
 <p align="center"><em>Built for people who use more than one AI assistant and are tired of paying the context tax.</em></p>

package/bin/holistic

@@ -1,17 +1,10 @@
-#!/usr/bin/env sh
-SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
-node --experimental-strip-types "$SCRIPT_DIR/../src/cli.ts" "$@"
-status=$?
-if [ "$status" -ne 0 ]; then
-  exit "$status"
-fi
-if [ "$1" = "handoff" ] && [ -f "$PWD/.holistic/context/pending-commit.txt" ]; then
-  message=$(head -n 1 "$PWD/.holistic/context/pending-commit.txt")
-  if [ -n "$message" ]; then
-    git add -- HOLISTIC.md AGENTS.md .holistic && git commit -m "$message"
-    if [ "$?" -eq 0 ] && [ -f "$PWD/.holistic/system/sync-state.sh" ]; then
-      /bin/sh "$PWD/.holistic/system/sync-state.sh" || true
-      node --experimental-strip-types "$SCRIPT_DIR/../src/cli.ts" internal-mark-commit --message "$message"
-    fi
-  fi
-fi
+#!/usr/bin/env sh
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
+node --experimental-strip-types "$SCRIPT_DIR/../src/cli.ts" "$@"
+status=$?
+if [ "$status" -ne 0 ]; then
+  exit "$status"
+fi
+
+# Holistic: Sync logic is now handled inside the Node CLI or gated behind explicit flags.
+# This wrapper is kept simple to avoid shell variable expansion vulnerabilities.

package/bin/holistic.cmd

@@ -1,23 +1,8 @@
-@echo off
-setlocal
-set SCRIPT_DIR=%~dp0
-node --experimental-strip-types "%SCRIPT_DIR%..\src\cli.ts" %*
-if errorlevel 1 exit /b %errorlevel%
-if /I "%~1"=="handoff" (
-  set PENDING_FILE=%CD%\.holistic\context\pending-commit.txt
-  if exist "%PENDING_FILE%" (
-    set /p COMMIT_MSG=<"%PENDING_FILE%"
-    if defined COMMIT_MSG (
-      git add -- HOLISTIC.md AGENTS.md .holistic
-      if not errorlevel 1 (
-        git commit -m "%COMMIT_MSG%"
-        if not errorlevel 1 (
-          if exist "%CD%\.holistic\system\sync-state.ps1" (
-            powershell -NoProfile -ExecutionPolicy Bypass -File "%CD%\.holistic\system\sync-state.ps1"
-          )
-          node --experimental-strip-types "%SCRIPT_DIR%..\src\cli.ts" internal-mark-commit --message "%COMMIT_MSG%"
-        )
-      )
-    )
-  )
-)
+@echo off
+setlocal
+set SCRIPT_DIR=%~dp0
+node --experimental-strip-types "%SCRIPT_DIR%..\src\cli.ts" %*
+if errorlevel 1 exit /b %errorlevel%
+
+rem Holistic: Sync logic is now handled inside the Node CLI or gated behind explicit flags.
+rem This wrapper is kept simple to avoid shell variable injection vulnerabilities.

package/dist/cli.d.ts

@@ -3,5 +3,5 @@ export declare function renderHelpText(): string;
 export declare function renderResumeOutput(body: string): string;
 export declare function finalizeDraftHandoffInput(session: SessionRecord, input: HandoffInput): HandoffInput;
 export declare function renderDiff(fromSession: SessionRecord, toSession: SessionRecord, diff: SessionDiff): string;
-export declare function renderStatus(state: HolisticState): string;
+export declare function renderStatus(rootDir: string, state: HolisticState): string;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAA4C,YAAY,EAAE,aAAa,EAAgB,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AA2EvJ,wBAAgB,cAAc,IAAI,MAAM,CA2BvC;AAMD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AA4ED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,YAAY,GAAG,YAAY,CAcnG;AAMD,wBAAgB,UAAU,CAAC,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAoE1G;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CA4DzD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAA4C,YAAY,EAAE,aAAa,EAAgB,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AA2EvJ,wBAAgB,cAAc,IAAI,MAAM,CA4BvC;AAMD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AA4ED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,YAAY,GAAG,YAAY,CAcnG;AAMD,wBAAgB,UAAU,CAAC,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAoE1G;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CA8D1E"}

package/dist/cli.js

@@ -6,7 +6,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { renderRepoLocalCliCommands } from './core/cli-fallback.js';
 import { captureRepoSnapshot, clearPendingCommit, commitPendingChanges, writePendingCommit } from './core/git.js';
 import { writeDerivedDocs } from './core/docs.js';
-import { bootstrapHolistic, initializeHolistic, refreshHolisticHooks, repairHolistic } from './core/setup.js';
+import { bootstrapHolistic, getSetupStatus, initializeHolistic, refreshHolisticHooks, repairHolistic } from './core/setup.js';
 import { printSplash, printSplashError, renderSplash } from './core/splash.js';
 import { requestAutoSync } from './core/sync.js';
 import { runDaemonTick } from './daemon.js';
@@ -73,14 +73,15 @@ export function renderHelpText() {
 
 Usage:
   holistic init [--install-daemon] [--install-hooks] [--platform win32|darwin|linux] [--interval 30] [--remote origin] [--state-ref refs/holistic/state] [--state-branch holistic/state]
-  holistic bootstrap [--platform win32|darwin|linux] [--interval 30] [--remote origin] [--state-ref refs/holistic/state] [--state-branch holistic/state] [--install-daemon false] [--install-hooks false] [--configure-mcp false]
+  holistic bootstrap [--platform win32|darwin|linux] [--interval 30] [--yes]
+  holistic doctor
   holistic repair [--platform win32|darwin|linux] [--refresh-hooks false] [--install-daemon true] [--configure-mcp true]
   holistic start [--agent codex|claude|antigravity|gemini|copilot|cursor|goose|gsd|gsd2] [--continue] [--json]
   holistic resume [--agent codex|claude|antigravity|gemini|copilot|cursor|goose|gsd|gsd2] [--continue] [--json]
-  holistic checkpoint --reason "<reason>" [--goal "<goal>"] [--status "<status>"] [--plan "<step>"]... [--completion-kind natural-breakpoint|task-complete|slice-complete|milestone-complete] [--completion-source agent|system] [--completion-recorded-at <iso8601>]
+  holistic checkpoint --reason "<reason>" [--status "<status>"] [--plan "<step>"]... [--completion-kind natural-breakpoint|task-complete|slice-complete|milestone-complete] [--completion-source agent|system] [--completion-recorded-at <iso8601>]
   holistic checkpoint --fixed "<bug>" [--fix-files "<file>"] [--fix-risk "<what reintroduces it>"]
-  holistic handoff [--draft] [--summary "<summary>"] [--next "<step>"]...
-  holistic start-new --goal "<goal>" [--title "<title>"] [--plan "<step>"]...
+  holistic handoff [--draft] [--summary "<summary>"] [--next "<step>"]... [--commit]
+  holistic start-new [--goal "<goal>"] [--title "<title>"] [--plan "<step>"]...
   holistic status
   holistic diff --from "<session-id>" --to "<session-id>" [--format text|json]
   holistic search --id "<session-id>" [--format text|json]
@@ -245,10 +246,12 @@ export function renderDiff(fromSession, toSession, diff) {
     }
     return lines.join("\n") + "\n";
 }
-export function renderStatus(state) {
+export function renderStatus(rootDir, state) {
     const lines = [];
     lines.push("Holistic Status");
     lines.push("");
+    lines.push(renderSyncStatus(rootDir));
+    lines.push("");
     if (!state.activeSession) {
         lines.push("No active session.");
         if (state.lastHandoff) {
@@ -256,7 +259,7 @@ export function renderStatus(state) {
             lines.push(`Last handoff: ${state.lastHandoff.summary}`);
             lines.push(`Next action: ${state.lastHandoff.nextAction}`);
         }
-        if (state.pendingWork.length > 0) {
+        if (state.pendingWork && state.pendingWork.length > 0) {
             lines.push("");
             lines.push(`Pending work: ${state.pendingWork.length} item(s)`);
             for (const item of state.pendingWork.slice(0, 3)) {
@@ -341,12 +344,27 @@ Repo-local CLI: ${initFallback}
     return 0;
 }
 async function handleBootstrap(rootDir, parsed) {
-    printSplash({
-        message: "bootstrapping holistic on this machine...",
-    });
     const platformFlag = firstFlag(parsed.flags, "platform", process.platform);
     const platform = platformFlag === "windows" ? "win32" : platformFlag === "macos" ? "darwin" : platformFlag === "linux" ? "linux" : platformFlag;
     const intervalSeconds = Number.parseInt(firstFlag(parsed.flags, "interval", "30"), 10);
+    const confirmed = firstFlag(parsed.flags, "yes") === "true";
+    const status = getSetupStatus(rootDir, {
+        platform: platform,
+        intervalSeconds,
+    });
+    const pending = status.filter(s => s.status !== "ok");
+    if (pending.length > 0 && !confirmed) {
+        printSplash({
+            message: "bootstrap pre-flight: pending actions",
+        });
+        process.stdout.write("\nHolistic needs to make the following changes to your system:\n\n");
+        printSetupStatusTable(status);
+        process.stdout.write("\nRun with --yes to apply these changes.\n");
+        return 1;
+    }
+    printSplash({
+        message: "bootstrapping holistic on this machine...",
+    });
     const result = bootstrapHolistic(rootDir, {
         installDaemon: firstFlag(parsed.flags, "install-daemon", "true") !== "false",
         installGitHooks: firstFlag(parsed.flags, "install-hooks", "true") !== "false",
@@ -382,9 +400,37 @@ Git hooks: ${result.gitHooksInstalled ? result.gitHooks.join(", ") : "not instal
 MCP config: ${result.mcpConfigured ? result.mcpConfigFile : "skipped"}
 Checks: ${result.checks.join(", ")}
 Repo-local CLI: ${bootstrapFallback}
+
+[TIP] To enable remote syncing (Portable State), set "portableState": true in .holistic/config.json
 `);
     return 0;
 }
+async function handleDoctor(rootDir, parsed) {
+    printSplash({
+        message: "running holistic health check...",
+    });
+    const status = getSetupStatus(rootDir);
+    process.stdout.write("\nSystem Configuration:\n\n");
+    printSetupStatusTable(status);
+    process.stdout.write("\nSync Diagnostics:\n\n");
+    process.stdout.write(renderSyncStatus(rootDir));
+    const healthy = status.every(s => s.status === "ok");
+    if (healthy) {
+        process.stdout.write("\n\u2713 Holistic is healthy and correctly configured on this machine.\n");
+    }
+    else {
+        process.stdout.write("\n\u26A0 Some components require attention. Run 'holistic bootstrap' to fix.\n");
+    }
+    return 0;
+}
+function printSetupStatusTable(status) {
+    for (const s of status) {
+        const icon = s.status === "ok" ? "\u2713" : s.status === "missing" ? "\u25CB" : s.status === "outdated" ? "\u21BB" : s.status === "info" ? "\u2139" : "!";
+        const label = `${icon} ${s.component.padEnd(20)}`;
+        process.stdout.write(`${label} | ${s.status.padEnd(10)} | ${s.details}\n`);
+        process.stdout.write(`  ${s.description}\n\n`);
+    }
+}
 async function handleRepair(rootDir, parsed) {
     printSplash({
         message: "repairing holistic machine-local helpers...",
@@ -515,23 +561,16 @@ async function handleCheckpoint(rootDir, parsed) {
 async function handleStartNew(rootDir, parsed) {
     refreshHooksBeforeCommand(rootDir);
     const agent = asAgent(firstFlag(parsed.flags, "agent", "unknown"));
-    const rl = createInterface({ input, output });
-    try {
-        const goal = firstFlag(parsed.flags, "goal") || await ask("New session goal", "Capture the next task", rl);
-        const title = firstFlag(parsed.flags, "title");
-        const plan = listFlag(parsed.flags, "plan");
-        const finalPlan = plan.length > 0 ? plan : await promptList("Initial plan steps", ["Read HOLISTIC.md", "Confirm the next concrete step"], rl);
-        const mutateResult = mutateState(rootDir, (state) => startNewSession(rootDir, state, agent, goal, finalPlan, title));
-        if (!mutateResult.success || !mutateResult.state) {
-            process.stderr.write(`Error: Failed to start session: ${mutateResult.error}\n`);
-            return 1;
-        }
-        process.stdout.write(`Started ${mutateResult.state.activeSession?.id} for goal: ${mutateResult.state.activeSession?.currentGoal}\n`);
-        return 0;
-    }
-    finally {
-        rl.close();
+    const goal = firstFlag(parsed.flags, "goal");
+    const title = firstFlag(parsed.flags, "title");
+    const plan = listFlag(parsed.flags, "plan");
+    const mutateResult = mutateState(rootDir, (state) => startNewSession(rootDir, state, agent, goal, plan, title));
+    if (!mutateResult.success || !mutateResult.state) {
+        process.stderr.write(`Error: Failed to start session: ${mutateResult.error}\n`);
+        return 1;
     }
+    process.stdout.write(`Started ${mutateResult.state.activeSession?.id} for goal: ${mutateResult.state.activeSession?.currentGoal}\n`);
+    return 0;
 }
 async function handleHandoff(rootDir, parsed) {
     refreshHooksBeforeCommand(rootDir);
@@ -610,22 +649,33 @@ async function handleHandoff(rootDir, parsed) {
             process.exit(1);
         }
         const nextState = mutateResult.state;
+        const shouldCommit = firstFlag(parsed.flags, "commit") === "true";
         let commitResult = null;
-        if (nextState.pendingCommit) {
+        if (nextState.pendingCommit && shouldCommit) {
             commitResult = commitPendingChanges(rootDir, nextState.pendingCommit.message, nextState.pendingCommit.files);
             if (commitResult.success) {
-                const clearResult = mutateState(rootDir, (latestState, paths) => {
+                mutateState(rootDir, (latestState, paths) => {
                     clearPendingCommit(paths);
                     return {
                         ...latestState,
                         pendingCommit: null,
                     };
                 });
-                if (!clearResult.success) {
-                    process.stderr.write(`Warning: Failed to clear pending commit state: ${clearResult.error}\n`);
-                }
             }
         }
+        if (nextState.pendingCommit && !shouldCommit) {
+            process.stdout.write(`
+Handoff prepared successfully!
+Docs updated: ${nextState.pendingCommit.files.join(", ")}
+
+To complete the handoff, review your changes and commit:
+git add .
+git commit -F .holistic/context/pending-commit.txt
+
+Use 'holistic handoff --commit' next time to automate this step safely.
+`);
+            return 0;
+        }
         process.stdout.write(`Handoff complete.\nSummary: ${nextState.lastHandoff?.summary ?? "n/a"}\n`);
         if (commitResult) {
             if (commitResult.success) {
@@ -686,9 +736,7 @@ function renderSyncStatus(rootDir) {
 async function handleStatus(rootDir) {
     refreshHooksBeforeCommand(rootDir);
     const { state } = loadState(rootDir);
-    process.stdout.write(renderStatus(state));
-    process.stdout.write("\n");
-    process.stdout.write(renderSyncStatus(rootDir));
+    process.stdout.write(renderStatus(rootDir, state));
     return 0;
 }
 async function handleDiff(rootDir, parsed) {
@@ -822,6 +870,8 @@ async function main() {
             return handleInit(rootDir, parsed);
         case "bootstrap":
             return handleBootstrap(rootDir, parsed);
+        case "doctor":
+            return handleDoctor(rootDir, parsed);
         case "repair":
             return handleRepair(rootDir, parsed);
         case "start":