projectstore-claude 0.28.2 → 0.29.0

package/README.md

@@ -6,7 +6,9 @@ The Claude Code installer for [projectstore](https://www.npmjs.com/package/proje
 npx projectstore-claude install --project "$PWD"
 ```
 
-It registers the plugin for that checkout at the host's local scope, previews every write and every host command before it runs, and asks for nothing else — naming the shell is the confirmation. Restart Claude Code afterwards.
+It registers the plugin for that checkout at the host's local scope. It prints its plan first — every write and every host command, verbatim — and at a terminal asks `Apply N changes? [Y/n]` before anything runs; then each step as it runs, and what to do next. Without a terminal (a script, CI, an agent's tool) naming the shell is the confirmation; `--json` never asks. Restart Claude Code afterwards.
+
+- See before you write: `npx projectstore-claude plan --project "$PWD"` prints the same plan and writes nothing; `--verbose` adds every row's reasoning; `npx projectstore-claude <verb> --help` lists a verb's options with examples.
 
 - Upgrade, or pin: `npx projectstore-claude@<version> upgrade --project "$PWD"` — the version you name is the version you run.
 - Uninstall: `npx projectstore-claude uninstall --project "$PWD"` — forgets the registration for that checkout and nothing else; your vault is plain markdown and stays yours.

package/bin/projectstore-claude.mjs

@@ -8,8 +8,10 @@
 // `--harness claude-code` inserted after a verb that takes it. Every other
 // argument passes through, so `projectstore-claude <verb> …` is exactly
 // `projectstore <verb> --harness claude-code …` — the same preview, the
-// same files, the same exit code. Naming the shell is the confirmation the
-// core's install gate asks for, exactly as naming --harness is.
+// same files, the same exit code. Naming the shell names the harness, exactly
+// as --harness does: without a terminal that is the confirmation the core's
+// install gate asks for; at a terminal the core shows the plan and asks (the
+// install spec, contract 9 as amended 2026-10-04).
 import { existsSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { constants as osConstants } from "node:os";
@@ -72,17 +74,20 @@ if (!core) {
     process.stderr.write(`${SHELL}: ${fixed.error}\n`);
     process.exitCode = 2;
   } else {
-    // stdio inherited: the core's install gate asks on a terminal and refuses
-    // without one, so the child must see the real stdin and stdout. No
-    // timeout — the child waits on a human at the preview. exitCode, not
-    // exit(): the core's own bin says why (a pending write on a pipe).
+    // stdio inherited: the core's install gate shows the plan and asks on a
+    // terminal, and refuses a bare run without one, so the child must see the
+    // real stdin and stdout. No timeout — the child waits on a human at the
+    // question. exitCode, not exit(): the core's own bin says why (a pending
+    // write on a pipe). PROJECTSTORE_SHELL lets the core's --help speak this
+    // shell's name; nothing the core plans or writes reads it.
     const r = spawnSync(process.execPath, [core, ...fixed.argv], {
       stdio: "inherit",
-      env: { ...process.env, PROJECTSTORE_DISTRIBUTION_ROOT: root },
+      env: { ...process.env, PROJECTSTORE_DISTRIBUTION_ROOT: root, PROJECTSTORE_SHELL: SHELL },
     });
     if (r.error) process.stderr.write(`${SHELL}: ${r.error.message}\n`);
-    // A signal is relayed the shell way (128 + its number): Ctrl-C at the
-    // preview is 130 here as it would be on the core itself.
+    // A signal is relayed the shell way (128 + its number): the core reads
+    // its answer in the terminal's line mode, so Ctrl-C at the question is a
+    // real SIGINT — 130 here as it would be on the core itself.
     process.exitCode = r.status ?? (r.signal ? 128 + (osConstants.signals[r.signal] || 0) : 2);
   }
 }

package/node_modules/projectstore/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "projectstore",
       "displayName": "projectstore",
       "description": "📚 Your agent runs the project through a verified loop: task → artifact (ADR · spec · epic · story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in an Obsidian-friendly vault, every write approved by you — and any model can pick the project up tomorrow.",
-      "version": "0.28.2",
+      "version": "0.29.0",
       "author": {
         "name": "Evgenii Konev",
         "email": "ekonev@smartandpoint.com",

package/node_modules/projectstore/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "projectstore",
   "displayName": "projectstore",
-  "version": "0.28.2",
+  "version": "0.29.0",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "author": {
     "name": "Evgenii Konev @ SmartAndPoint",

package/node_modules/projectstore/README.md

@@ -94,7 +94,7 @@ Contributors: `git clone` this repo, then `claude --plugin-dir ./ProjectStore`.
 npx projectstore-claude install --project "$PWD"
 ```
 
-The same tree is published to npm as [`projectstore`](https://www.npmjs.com/package/projectstore) — one source package carrying every harness's manifest — and `projectstore-claude` is its Claude Code shell: the core pinned at the same version and bundled inside, the harness fixed, so the one command has the same shape on every harness. It registers the plugin with Claude Code: it writes a small local marketplace of its own under your Claude home, then drives `claude plugin marketplace add` / `plugin install` **at local scope**, so the registration lands in this checkout's `.claude/settings.local.json` and nowhere else. Every host command is printed before it runs; naming the harness is the confirmation. Restart Claude Code afterwards. A git-marketplace copy already enabled for the checkout is silenced there (not globally) so the plugin does not load twice; `uninstall` turns it back on. Pin or upgrade with `npx projectstore-claude@<version> upgrade --project "$PWD"` — the version you name is the version you run. The core's low-level form, `npx projectstore <verb> --harness claude-code …`, is exactly what the shell runs. bun works the same on the packed bin.
+The same tree is published to npm as [`projectstore`](https://www.npmjs.com/package/projectstore) — one source package carrying every harness's manifest — and `projectstore-claude` is its Claude Code shell: the core pinned at the same version and bundled inside, the harness fixed, so the one command has the same shape on every harness. It registers the plugin with Claude Code: it writes a small local marketplace of its own under your Claude home, then drives `claude plugin marketplace add` / `plugin install` **at local scope**, so the registration lands in this checkout's `.claude/settings.local.json` and nowhere else. It prints its plan first — every file it writes and every host command, verbatim — and at a terminal asks `Apply N changes? [Y/n]`; then it shows each step as it runs and what to do next. Without a terminal (a script, CI, an agent's tool) naming the harness is the confirmation. `plan` prints the same plan and writes nothing; `--verbose` adds every row's reasoning; `npx projectstore-claude <verb> --help` lists a verb's options with examples. Restart Claude Code afterwards. A git-marketplace copy already enabled for the checkout is silenced there (not globally) so the plugin does not load twice; `uninstall` turns it back on. Pin or upgrade with `npx projectstore-claude@<version> upgrade --project "$PWD"` — the version you name is the version you run. The core's low-level form, `npx projectstore <verb> --harness claude-code …`, is exactly what the shell runs. bun works the same on the packed bin.
 
 **Codex has its own shell with the same one-command shape:**
 `npx projectstore-codex install --project "$PWD"`. It carries a Codex
@@ -120,7 +120,7 @@ The package also carries a `bin`. Without a session — in CI, or in a shell —
 
 ```
 npx projectstore doctor --json
-npx projectstore install --harness claude-code   # the low-level form the shell runs: previews, then writes the agents block and the status line; naming the harness is the confirmation, there is no --yes
+npx projectstore install --harness claude-code   # the low-level form the shell runs: shows the plan, asks at a terminal, then writes; without a terminal naming the harness is the confirmation — there is no --yes
 npx projectstore reconcile --write --only kanban
 ```
 

package/node_modules/projectstore/harnesses/claude-code.json

@@ -20,6 +20,9 @@
       "/plugin marketplace add SmartAndPoint/ProjectStore && /plugin install projectstore@SmartAndPoint   (git marketplace, user-wide)",
       "restart Claude Code"
     ],
+    "next": [
+      "restart Claude Code in this project"
+    ],
     "notes": [
       "Git marketplace only: auto-update is OFF by default for third-party plugins: /plugin -> Marketplaces -> SmartAndPoint -> toggle auto-update. The npm registration updates when you run `npx projectstore-claude upgrade --project <dir>`.",
       "Pin a git-marketplace release with: /plugin marketplace add SmartAndPoint/ProjectStore#<tag>; pin the npm registration with npx projectstore-claude@<version>.",

package/node_modules/projectstore/harnesses/codex.json

@@ -298,6 +298,10 @@
       "restart Codex and approve the ProjectStore hooks when prompted",
       "run `$projectstore-bind <vault-path>` in Codex"
     ],
+    "next": [
+      "restart Codex from a terminal and approve the ProjectStore hooks when it asks",
+      "in an unbound project, run `$projectstore-bind <vault-path>` in Codex"
+    ],
     "notes": [
       "The installation is user-global because Codex's marketplace, plugin row and cache live in CODEX_HOME; the AGENTS.md block is project-local.",
       "Upgrade with `npx projectstore-codex@<version> upgrade --project \"$PWD\"`; the named package version is also the plugin version.",

package/node_modules/projectstore/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore",
-  "version": "0.28.2",
+  "version": "0.29.0",
   "description": "Your agent runs the project through a verified loop: task → artifact (ADR / spec / epic / story) → adversarial critic → backlog → planner → reviewer → done. Plain markdown in git — any model can pick the project up tomorrow.",
   "keywords": [
     "project-management",

package/node_modules/projectstore/scripts/build-adapters.mjs

@@ -80,10 +80,11 @@ const COMMAND_OVERRIDES = {
 
 ## register / unregister
 
-Preview the requested change and ask for explicit approval. On approval, run the
-core's \`install\` or \`uninstall\` verb with \`--harness codex --surface
-agents_block --project "$PWD"\`. Print its output verbatim. Never edit the
-managed block by hand.
+Preview the requested change with \`plan --harness codex --surface agents_block
+--project "$PWD"\` and ask for explicit approval. On approval, run the core's
+\`install\` or \`uninstall\` verb with \`--harness codex --surface agents_block
+--project "$PWD" --json\` — \`--json\` never waits on a terminal's question — and
+report the envelope's result. Never edit the managed block by hand.
 
 ## status
 
@@ -134,7 +135,9 @@ arguments and \`--json\`. Summarize every finding without re-deriving it.
 When \`--fix\` is absent, remain read-only. When it is present, separate fixes
 by owner: derived vault views use \`$projectstore-reconcile\`; Codex plugin or
 agents-block drift uses the core's \`upgrade --harness codex\` path. Preview
-each mutation and ask for explicit approval before running it. Unsupported
+each mutation with \`plan --harness codex\` and ask for explicit approval before
+running it; then run \`upgrade --harness codex --json\`, whose envelope is the
+result — \`--json\` never waits on a terminal's question. Unsupported
 surfaces remain unsupported; do not create host configuration by hand. Never
 claim a fix after a non-zero exit.`,
   },

package/node_modules/projectstore/scripts/cli.mjs

@@ -41,7 +41,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
-import { createInterface } from "node:readline/promises";
+import * as term from "./term.mjs";
 import { projectRootDeclared, childEnv, harnessIds, harnessForOverlay, pinPluginRoot } from "./harness.mjs";
 import { readConfigAt, readOverlayAt, resolveAgentModel, writeOverlayAt, overlayId, layoutRoster } from "./lib.mjs";
 import { READ_OPERATIONS, LINEAGE_KINDS, LINEAGE_DEFAULT_DEPTH, SEARCH_DEFAULT_LIMIT, GRAPH_EDGE_CAP, DIRECTIONS } from "./query.mjs";
@@ -83,14 +83,15 @@ export function resolveProject({ project = null, env = process.env, cwd = proces
 const opt = (name, arg, summary, multiple = false) => Object.freeze({ name, arg, summary, multiple });
 const JSON_OPT = opt("json", false, "the envelope");
 const READ_JSON = [JSON_OPT];
-const HARNESS_OPT = opt("harness", "<id>", "the harness — and, non-interactively, the confirmation; there is no --yes", true);
+const HARNESS_OPT = opt("harness", "<id>", "the harness — and, without a terminal, the confirmation (a terminal is asked); there is no --yes", true);
 const SURFACE_OPT = opt("surface", "<key>", "one surface and those beneath it", true);
 // The layout move's remedy names this for any copy but the package's own
 // registration (the layout spec, contract 12 as amended 2026-10-03): it makes
 // "no host command" true by construction instead of by recognising the root.
 const NO_REGISTER_OPT = opt("no-register", false, "leave the plugin registration alone: change only this project's files");
-const INSTALL_OPTS = [HARNESS_OPT, SURFACE_OPT, NO_REGISTER_OPT, JSON_OPT];
-const UNINSTALL_OPTS = [HARNESS_OPT, SURFACE_OPT, opt("global", false, "also remove the harness-global plugin registration"), JSON_OPT];
+const VERBOSE_OPT = opt("verbose", false, "every row's reasoning, each step's why and the host's own notes");
+const INSTALL_OPTS = [HARNESS_OPT, SURFACE_OPT, NO_REGISTER_OPT, VERBOSE_OPT, JSON_OPT];
+const UNINSTALL_OPTS = [HARNESS_OPT, SURFACE_OPT, opt("global", false, "also remove the harness-global plugin registration"), VERBOSE_OPT, JSON_OPT];
 
 export const VERBS = Object.freeze([
   Object.freeze({
@@ -195,17 +196,141 @@ export const VERBS = Object.freeze([
 // story that adds a verb in slices.
 export const PLANNED_VERBS = Object.freeze([]);
 
-export function usage() {
-  const lines = ["usage: projectstore <verb> [options] [--project <dir>] [--json]", "", "verbs:"];
-  for (const v of VERBS) {
-    lines.push(`  ${v.verb.padEnd(11)} ${v.summary}`);
-    for (const o of v.options) lines.push(`    --${o.name}${o.arg ? " " + o.arg : ""}${o.multiple ? " (repeatable)" : ""}  ${o.summary}`);
+// The verbs as a person meets them: setting a project up, reading the vault,
+// keeping it consistent, serving it. A verb not listed lands in "Other", so a
+// new row is never hidden by this table.
+const HELP_GROUPS = [
+  ["Set up", ["install", "upgrade", "uninstall", "plan", "bind", "init", "agents"]],
+  ["Read", ["status", "search", "show", "graph", "codemap", "orientation"]],
+  ["Check and repair", ["doctor", "reconcile"]],
+  ["Serve", ["mcp", "version"]],
+];
+
+// Examples per verb. `{cmd}` is how this run was invoked (a shell's own name
+// when PROJECTSTORE_SHELL says so, else the core — a shell passes the read
+// verbs through, so its name serves them too), `{h}` the harness argument the
+// core needs and a shell fixes.
+const EXAMPLES = {
+  install: ["{cmd} install{h}", "{cmd} plan{h}  # the same plan; nothing is written"],
+  upgrade: ["{cmd}@<version> upgrade{h}  # the version you name is the version that runs", "{cmd} upgrade{h} --verbose"],
+  uninstall: ["{cmd} uninstall{h}", "{cmd} uninstall{h} --surface statusline"],
+  plan: ["{cmd} plan{h}", "{cmd} plan{h} --json  # one envelope, for scripts and agents"],
+  status: ["{cmd} status", "{cmd} status --json"],
+  orientation: ["{cmd} orientation --json"],
+  search: ['{cmd} search "entry rule" --kind spec', "{cmd} search queue --status accepted --limit 5"],
+  show: ["{cmd} show adr/README.md", "{cmd} show epics/PS-CORE/epic.md --section acceptance"],
+  graph: ["{cmd} graph neighbors adr/README.md --direction out", "{cmd} graph lineage epics/PS-CORE/epic.md --depth 2"],
+  codemap: ["{cmd} codemap --for PS-CORE", "{cmd} codemap --for scripts/lib.mjs --reverse"],
+  doctor: ["{cmd} doctor", "{cmd} doctor --install --json"],
+  reconcile: ["{cmd} reconcile  # what would change; nothing is written", "{cmd} reconcile --write"],
+  bind: ["{cmd} bind ~/vaults/my-project", "{cmd} bind ~/vaults/other --rebind"],
+  init: ["{cmd} init ~/vaults/new-project --language ru"],
+  agents: ["{cmd} agents show", "{cmd} agents configure{h} --default opus --agent clerk=sonnet"],
+  mcp: ['{cmd} mcp --project "$PWD"'],
+};
+
+// Positional arguments a summary does not already name.
+const ARGS = { search: "<phrase>", show: "<path>" };
+
+// "bind <vault> — bind this project…" names its own form; "graph neighbors
+// <path> | graph lineage <path> — …" names two.
+function forms(row) {
+  const m = /^(.+?) — (.+)$/.exec(row.summary);
+  if (m && m[1].startsWith(row.verb + " ")) {
+    const list = m[1].split(" | ").map((f) => f.replace(new RegExp(`^${row.verb} `), ""));
+    return { forms: list, about: m[2][0].toUpperCase() + m[2].slice(1) };
+  }
+  return { forms: [ARGS[row.verb] || ""], about: row.summary };
+}
+
+function invocation(env = process.env) {
+  const shell = env.PROJECTSTORE_SHELL || null;
+  return { shell, cmd: shell ? `npx ${shell}` : "npx projectstore" };
+}
+
+function optionLines(options) {
+  const rows = options.map((o) => [`--${o.name}${o.arg ? " " + o.arg : ""}`, `${o.summary}${o.multiple ? " (repeatable)" : ""}`]);
+  const w = Math.min(28, Math.max(0, ...rows.map(([l]) => l.length)));
+  return rows.map(([l, r]) => (l.length > w ? `  ${l}\n  ${" ".repeat(w)}  ${r}` : `  ${l.padEnd(w)}  ${r}`));
+}
+
+const EXIT_CODES = "Exit codes  0 ok · 1 findings or a refusal · 2 usage · 3 not bound";
+
+export function usage(env = process.env) {
+  const { cmd } = invocation(env);
+  const lines = [
+    "projectstore — project memory for coding agents: decisions, specs, epics and stories as plain markdown.",
+    "",
+    "Usage",
+    `  ${cmd} <verb> [options]`,
+    `  ${cmd} <verb> --help       one verb's options and examples`,
+  ];
+  const seen = new Set();
+  const groups = HELP_GROUPS.map(([title, names]) => [title, names.map((n) => VERBS.find((v) => v.verb === n)).filter(Boolean)]);
+  for (const [, rows] of groups) for (const r of rows) seen.add(r.verb);
+  const other = VERBS.filter((v) => !seen.has(v.verb));
+  if (other.length) groups.push(["Other", other]);
+  for (const [title, rows] of groups) {
+    if (!rows.length) continue;
+    lines.push("", title);
+    for (const v of rows) lines.push(`  ${v.verb.padEnd(12)} ${v.summary}`);
   }
-  if (PLANNED_VERBS.length) lines.push("", `  planned: ${PLANNED_VERBS.map((v) => `${v.verb} (${v.lands})`).join(", ")}`);
-  lines.push("", `  harnesses: ${harnessIds().join(", ")}`, "  --version  print the package version", "  exit codes: 0 ok, 1 findings or refusal, 2 usage, 3 not bound");
+  if (PLANNED_VERBS.length) lines.push("", `Planned: ${PLANNED_VERBS.map((v) => `${v.verb} (${v.lands})`).join(", ")}`);
+  lines.push(
+    "",
+    "Every verb",
+    "  --project <dir>  the project (default: the host session's project, else the current directory)",
+    "  --json           one envelope { schema_version, verb, project, ok, result } — for scripts and agents",
+    "  --version        the package version",
+    "",
+    "Tips",
+    "  install, upgrade and uninstall show their plan first; `plan` prints the same plan and writes nothing.",
+    "  At a terminal they ask before writing. Without one, --harness is the confirmation — there is no --yes.",
+    "  Unattended in a terminal (a script, a Makefile): pass --json, set CI=1, or give stdin no terminal (`</dev/null`).",
+    "  --verbose on those verbs adds every row's reasoning and the host's own notes.",
+    "",
+    `Harnesses   ${harnessIds().join(", ")}`,
+    EXIT_CODES,
+  );
   return lines.join("\n");
 }
 
+// One verb: what it does, how to call it, every option, examples.
+export function verbHelp(row, env = process.env) {
+  const { shell, cmd } = invocation(env);
+  const fixed = Boolean(shell) && row.options.some((o) => o.name === "harness");
+  const opts = row.options.filter((o) => !(fixed && o.name === "harness"));
+  const { forms: list, about } = forms(row);
+  const lines = [`${cmd} ${row.verb} — ${about}`, "", "Usage"];
+  for (const f of list) lines.push(`  ${cmd} ${row.verb}${f ? " " + f : ""}${opts.length ? " [options]" : ""}`);
+  if (opts.length) lines.push("", "Options", ...optionLines(opts));
+  if (fixed) lines.push("", `${shell} names the harness itself: without a terminal, the verb is its own confirmation.`);
+  else if (row.options.some((o) => o.name === "harness")) lines.push("", `Harnesses   ${harnessIds().join(", ")}`);
+  const ex = EXAMPLES[row.verb] || [];
+  const h = fixed ? "" : " --harness <id>";
+  const rendered = ex.map((e) => e.split("{cmd}").join(cmd).split("{h}").join(h).split("  # "));
+  const col = Math.max(0, ...rendered.filter((r) => r.length > 1).map(([c]) => c.length));
+  if (ex.length) lines.push("", "Examples", ...rendered.map(([c, note]) => `  ${note ? `${c.padEnd(col)}   # ${note}` : c}`));
+  lines.push("", EXIT_CODES);
+  return lines.join("\n");
+}
+
+// The nearest name within two edits — for a mistyped verb or option.
+export function nearest(word, names) {
+  const d = (a, b) => {
+    const m = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 1; j <= b.length; j++) m[0][j] = j;
+    for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) m[i][j] = Math.min(m[i - 1][j] + 1, m[i][j - 1] + 1, m[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    return m[a.length][b.length];
+  };
+  let best = null, score = 3;
+  for (const n of names) {
+    const k = n.startsWith(word) && word.length >= 3 ? 0 : d(word, n);
+    if (k < score) { best = n; score = k; }
+  }
+  return best;
+}
+
 // ─── run ───────────────────────────────────────────────────────────────
 
 export async function run(argv, { env = process.env, cwd = process.cwd(), stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, ask = null } = {}) {
@@ -217,7 +342,7 @@ export async function run(argv, { env = process.env, cwd = process.cwd(), stdin
       strict: true,
       options: {
         project: { type: "string" }, json: { type: "boolean" }, help: { type: "boolean", short: "h" }, version: { type: "boolean", short: "v" },
-        harness: { type: "string", multiple: true }, surface: { type: "string", multiple: true }, global: { type: "boolean" }, "no-register": { type: "boolean" },
+        harness: { type: "string", multiple: true }, surface: { type: "string", multiple: true }, global: { type: "boolean" }, "no-register": { type: "boolean" }, verbose: { type: "boolean" },
         write: { type: "boolean" }, only: { type: "string" }, install: { type: "boolean" }, vault: { type: "boolean" },
         kind: { type: "string", multiple: true }, status: { type: "string" }, limit: { type: "string" }, "include-derived": { type: "boolean" }, "case-sensitive": { type: "boolean" },
         body: { type: "boolean" }, section: { type: "string" }, direction: { type: "string" }, depth: { type: "string" }, for: { type: "string" }, reverse: { type: "boolean" },
@@ -228,7 +353,14 @@ export async function run(argv, { env = process.env, cwd = process.cwd(), stdin
   } catch (e) {
     // --json cannot be known before parsing; a raw scan is enough here.
     if (argv.includes("--json")) stdout.write(JSON.stringify(envelope(argv.find((a) => !a.startsWith("-")) || null, null, false, { error: e.message }), null, 2) + "\n");
-    stderr.write(`${e.message}\n${usage()}\n`);
+    // Node's own wording for an unknown option explains "--" positionals; a
+    // person who typed --verbos wants the option they meant.
+    const unknown = e.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION" ? /'(-{1,2}[^']+)'/.exec(e.message)?.[1] : null;
+    const row = VERBS.find((v) => v.verb === argv.find((a) => !a.startsWith("-")));
+    const names = [...(row ? row.options.map((o) => o.name) : VERBS.flatMap((v) => v.options.map((o) => o.name))), "project", "json", "help", "version"];
+    const hint = unknown ? nearest(unknown.replace(/^-+/, ""), [...new Set(names)]) : null;
+    const message = unknown ? `${row ? row.verb + " does not take" : "unknown option"} ${unknown}${hint ? ` — did you mean --${hint}?` : ""}` : e.message;
+    stderr.write(`${message}\nRun ${row ? `\`${row.verb} --help\`` : "--help"} for the options.\n`);
     return 2;
   }
   const { values, positionals } = parsed;
@@ -236,7 +368,7 @@ export async function run(argv, { env = process.env, cwd = process.cwd(), stdin
   // a consumer (the MCP server, a script) always has something to parse.
   const fail = (verb, project, message, code, { help = false } = {}) => {
     if (values.json) stdout.write(JSON.stringify(envelope(verb, project, false, { error: message, exit: code }), null, 2) + "\n");
-    stderr.write(message + "\n" + (help ? usage() + "\n" : ""));
+    stderr.write(message + "\n" + (help ? usage(env) + "\n" : ""));
     return code;
   };
   // In-process reads resolve layouts and registries from THIS package, as the
@@ -244,11 +376,17 @@ export async function run(argv, { env = process.env, cwd = process.cwd(), stdin
   // session's variable points at.
   pinPluginRoot(PACKAGE_ROOT);
   if (values.version) return runVersion({ values, stdout });
-  if (values.help || !positionals.length) { (values.help ? stdout : stderr).write(usage() + "\n"); return values.help ? 0 : 2; }
+  if (values.help && positionals.length) {
+    const row = VERBS.find((v) => v.verb === positionals[0]);
+    if (row) { stdout.write(verbHelp(row, env) + "\n"); return 0; }
+  }
+  if (values.help || !positionals.length) { (values.help ? stdout : stderr).write(usage(env) + "\n"); return values.help ? 0 : 2; }
   const verb = positionals[0];
   const row = VERBS.find((v) => v.verb === verb);
   if (!row) {
     const planned = PLANNED_VERBS.find((v) => v.verb === verb);
+    const guess = planned ? null : nearest(verb, VERBS.map((v) => v.verb));
+    if (guess) return fail(verb, null, `unknown verb: ${verb} — did you mean ${guess}?\nRun --help for every verb.`, 2);
     return fail(verb, null, (planned ? `${verb} lands with roadmap ${planned.lands}; not in this release.` : `unknown verb: ${verb}`), 2, { help: true });
   }
   // The options map is global (parseArgs), the rows are not: an option a row
@@ -257,7 +395,10 @@ export async function run(argv, { env = process.env, cwd = process.cwd(), stdin
   const GLOBAL = new Set(["project", "json", "help", "version"]);
   const declared = new Set(row.options.map((o) => o.name));
   const stray = Object.keys(values).filter((k) => !GLOBAL.has(k) && !declared.has(k));
-  if (stray.length) return fail(verb, null, `${verb} does not take --${stray[0]}`, 2, { help: true });
+  if (stray.length) {
+    const guess = nearest(stray[0], row.options.map((o) => o.name));
+    return fail(verb, null, `${verb} does not take --${stray[0]}${guess ? ` — did you mean --${guess}?` : ""}\nRun \`${verb} --help\` for the options.`, 2);
+  }
   const project = resolveProject({ project: values.project, env, cwd });
   const cfg = readConfigAt(project);
   if (row.requiresBinding && !cfg) return fail(verb, project, `${project} is not bound to a vault — run /projectstore:bind <vault> in a session, or \`projectstore bind <vault>\` (\`projectstore init <vault>\` also creates the vault).`, 3);
@@ -285,8 +426,9 @@ function ownEnv(env, project) {
 async function confirmWrite(question, { stdin, stdout, ask }) {
   if (ask) return /^y(es)?$/i.test(String(await ask(question)).trim());
   if (!(stdin && stdin.isTTY && stdout && stdout.isTTY)) return null; // no terminal: refuse
-  const rl = createInterface({ input: stdin, output: stdout });
-  try { return /^y(es)?$/i.test(String(await rl.question(question)).trim()); } finally { rl.close(); }
+  // End of input is a no (term.mjs askLine), never a question left pending.
+  const answer = await term.askLine(question, stdin, stdout);
+  return answer !== null && /^y(es)?$/i.test(answer.trim());
 }
 
 // ─── verbs ─────────────────────────────────────────────────────────────
@@ -573,23 +715,28 @@ async function runReconcile({ values, project, env, stdin, stdout, stderr, ask }
 
 async function runInstallVerb({ row, values, project, env, stdin, stdout, ask }) {
   const ih = await import("./install-harness.mjs");
-  const opts = { harnesses: values.harness || [], surfaces: values.surface && values.surface.length ? values.surface : null, globalRemoval: Boolean(values.global), register: !values["no-register"], root: PACKAGE_ROOT, env: ownEnv(env, project), stdin, stdout, ask };
+  const opts = { harnesses: values.harness || [], surfaces: values.surface && values.surface.length ? values.surface : null, globalRemoval: Boolean(values.global), register: !values["no-register"], root: PACKAGE_ROOT, env: ownEnv(env, project), stdin, stdout, ask, json: Boolean(values.json), verbose: Boolean(values.verbose) };
   if (row.verb === "plan") {
     const p = ih.plan(project, opts);
-    stdout.write(values.json ? JSON.stringify(envelope("plan", project, p.ok && !p.incomplete, { ...p, items: p.items.map(ih.publicItem) }), null, 2) + "\n" : ih.renderPreview(p));
+    if (values.json) stdout.write(JSON.stringify(envelope("plan", project, p.ok && !p.incomplete, { ...p, items: p.items.map(ih.publicItem) }), null, 2) + "\n");
+    else {
+      const c = term.caps(stdout, env);
+      stdout.write(ih.renderPreview(p, { verbose: opts.verbose, verb: "plan", paint: term.painter(c), icon: (n) => term.icon(c, n), width: c.live ? c.width : 0 }));
+    }
     return p.ok && !p.incomplete ? 0 : 1;
   }
-  const r = await ih.runVerb(row.verb, project, opts);
+  // Text mode hands runVerb the stream: the plan is printed before any
+  // question, then each step, then DONE (install spec contracts 9 and 18).
+  const r = await ih.runVerb(row.verb, project, values.json ? opts : { ...opts, out: stdout });
   // A registration the plan could not make (no host CLI) or a host command
   // that failed is exit 1 with the rest applied (install spec contract 4′).
   const ok = r.plan.ok && !r.plan.incomplete && !r.failed && (r.gate.confirmed || r.gate.why === "nothing-to-do");
   if (values.json) {
     stdout.write(JSON.stringify(envelope(row.verb, project, ok, { gate: r.gate, applied: r.applied, failed: r.failed, incomplete: r.plan.incomplete, plannedAgainst: r.plan.plannedAgainst, items: r.plan.items.map(ih.publicItem), refusals: r.plan.refusals, reports: r.plan.reports }), null, 2) + "\n");
-  } else {
-    stdout.write(r.preview);
-    if (r.gate.confirmed) stdout.write(ih.appliedLine(r));
-    else if (r.gate.why === "non-tty") stdout.write(`a bare ${row.verb} in a non-TTY refuses; name a harness to confirm: --harness ${r.plan.detected.map((d) => d.id).join(" | ") || harnessIds().join(" | ")}\n`);
-    else if (r.gate.why === "declined") stdout.write("nothing written.\n");
+  } else if (r.gate.why === "non-tty") {
+    stdout.write(`Nothing written: without a terminal, a bare ${row.verb} refuses. Name the harness to confirm: --harness ${r.plan.detected.map((d) => d.id).join(" | ") || harnessIds().join(" | ")}\n`);
+  } else if (r.gate.why === "declined") {
+    stdout.write("Nothing written.\n");
   }
   return ok ? 0 : 1;
 }

package/node_modules/projectstore/scripts/install-harness.mjs

@@ -23,12 +23,14 @@
 // pure string. confirm() takes its streams as parameters. apply() is the only
 // function that writes, and it writes only through lib.mjs writeFileAtomic.
 //
-// The gate (contract 9, distribution ADR decision 6): an interactive call
-// prints the plan and asks; a non-interactive call that NAMES its harness
-// counts as the confirmation; a bare install in a non-TTY refuses. There is
-// no --yes flag. --surface narrows the plan (by prefix, so `statusline`
-// covers the launcher too); it confirms nothing — except that naming the
-// statusline surface is how a user opts into it without the config flag.
+// The gate (contract 9 as amended 2026-10-04, distribution ADR decision 6):
+// the plan is always printed first. A person at a terminal is then asked,
+// even when the harness is named; without one (a pipe, an agent's tool, CI,
+// --json, a host session) a call that NAMES its harness is the confirmation
+// and a bare one refuses. There is no --yes flag. --surface narrows the plan
+// (by prefix, so `statusline` covers the launcher too); it confirms nothing —
+// except that naming the statusline surface is how a user opts into it
+// without the config flag.
 //
 // Surface handlers are keyed by the manifest's surfaces.<kind>.format, never
 // by a harness id: adding a harness is adding harnesses/<id>.json, and this
@@ -56,13 +58,13 @@
 // (MultiProjectStore); the host-managed report shape is Maxim
 // Podreshetnikov's (PR #13, installElsewhere). Pure node, no external deps.
 
-import { mkdirSync, unlinkSync, rmdirSync, readdirSync, existsSync, readFileSync, openSync, closeSync, statSync } from "node:fs";
-import { join, resolve, dirname, relative, isAbsolute } from "node:path";
+import { mkdirSync, unlinkSync, rmdirSync, readdirSync, existsSync, readFileSync, openSync, closeSync, statSync, realpathSync } from "node:fs";
+import { join, resolve, dirname, relative, isAbsolute, basename } from "node:path";
 import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
-import { createInterface } from "node:readline/promises";
 import { spawnSync } from "node:child_process";
+import { caps as termCaps, painter, icon as termIcon, duration, stepReporter, wrap, askLine } from "./term.mjs";
 import { loadHarness, loadHarnesses, harnessIds, sourceHarness, detectHarnesses, harnessRefusal, packageCommand } from "./harness.mjs";
 import { FOREIGN_TEXT, GRAMMAR_VERSION } from "./provenance.mjs";
 import { analyseBlock, analyseJsonEntry, analyseStampedFile, analyseRegistration, analysePortableRegistration, analyseLayout, isOurFile, readText } from "./surfaces.mjs";
@@ -141,8 +143,9 @@ function planAgentsBlock(ctx, key, s) {
       .filter((m) => m.id !== ctx.harness?.id)
       .some((m) => (m.surfaces?.agents_block?.files || []).includes(file));
     for (const e of withBlock) {
-      // Naming the surface IS the confirmation, as it is for every other
-      // write this bin makes: `--surface agents_block` removes it regardless.
+      // Naming the surface removes it regardless: `--surface agents_block`
+      // is the confirmation without a terminal, and a terminal is asked
+      // (contract 9 as amended 2026-10-04).
       if (!(ctx.surfaces || []).includes(key) && alsoRead(e.file)) {
         items.push({ surface: key, kind: "shared", path: e.path, entry: `projectstore:agents v${e.block.v}`, state: "ours-current", action: "skip",
           reason: `${e.file} is read by another harness too — a per-harness uninstall leaves the project's block alone. Remove it with --surface ${key}` });
@@ -658,7 +661,14 @@ export function plan(projectDir, { harnesses = [], mode = "install", env = proce
       // Items planned before the render root was known (none today: the registration sorts first) are not re-planned.
     }
     if (ctx.incomplete) out.incomplete = true;
-    if (hostRows.length && !surfaces) out.reports.push(hostManagedReport(harness, hostRows, registration));
+    if (hostRows.length && !surfaces) {
+      out.reports.push(hostManagedReport(harness, hostRows, registration));
+      // The same fact in one line, for the compact preview (contract 18). Not
+      // enumerable: the preview reads it, and plan --json keeps the shape it
+      // had (the planner's review, 2026-10-05).
+      if (!Object.hasOwn(out, "hostManaged")) Object.defineProperty(out, "hostManaged", { value: [], enumerable: false });
+      out.hostManaged.push({ harness: harness.id, display: harness.display_name, rows: hostRows, entry: registration?.entry || null, action: registration?.action || null });
+    }
     // An unsupported host surface gets the same row shape a shared one does
     // (planJsonEntry's unsupported branch): state "unsupported", action "skip",
     // and the manifest's own reason. One treatment for one fact, so a reader —
@@ -729,12 +739,14 @@ function planLayout(ctx) {
   return { first, last };
 }
 
-function applyLayout(p, i, { failed, home = homedir() }) {
+function applyLayout(p, i, { failed, home = homedir(), onStep = null }) {
   const out = { path: i.path, action: i.action, surface: i.surface, steps: [] };
   const within = p.projectDir;
   if (i.action === "cleanup" && failed) { out.action = "skipped"; out.reason = "an earlier item failed; the legacy files stay until the next run"; return out; }
   const fail = (step, message) => { out.failed = { step, status: null, stderr: message }; return out; };
   for (const st of i.steps || []) {
+    const seen = out.steps.length;
+    if (onStep) onStep(st, "start");
     try {
       if (st.kind === "ensure") { ensureRuntimeDir(within); out.steps.push({ kind: st.kind, ok: true }); }
       else if (st.kind === "move-state") { const r = moveStateDir(st.from, st.to, within); ensureStateDir(within); out.steps.push({ kind: st.kind, ok: true, ...r }); }
@@ -788,10 +800,18 @@ function applyLayout(p, i, { failed, home = homedir() }) {
       }
       else if (st.kind === "remove-legacy-runtime") { removeInside(st.path, within, { recursive: true }); out.steps.push({ kind: st.kind, ok: true, removed: true }); }
     } catch (e) { return fail(st.kind, e && e.message ? e.message : String(e)); }
+    finally { if (onStep) onStep(st, "end", stepResult(out, seen)); }
   }
   return out;
 }
 
+// What one step left behind, for the APPLY line: its record when it pushed
+// one, and a failure when the item failed under it.
+function stepResult(out, seen) {
+  const rec = out.steps.length > seen ? out.steps[out.steps.length - 1] : null;
+  return { ok: !out.failed && (!rec || rec.ok !== false), kept: Boolean(rec && rec.removed === false && rec.reason) };
+}
+
 // Does any settings file the host reads run this file as its status line?
 // Compared by identity (device and inode), so a path spelled through a symlink
 // or in another case still counts; the project-directory variable a command
@@ -856,96 +876,183 @@ function hostManagedReport(m, rows, registration = null) {
 const isWrite = (i) => !["skip", "refuse"].includes(i.action);
 
 // ─── preview ───────────────────────────────────────────────────────────
+//
+// Contract 18: a header, then PLAN — one line per item (what, where, the state
+// transition) with its steps beneath. Every path written and every host argv
+// with the files it touches stays in the default view: that is contract 9's
+// consent content, and a reader that is an agent needs it as much as a person.
+// The explanations — the host-managed report, per-row reasons, each step's why,
+// the planned-against note — are folded behind `--verbose`. Colour comes from
+// the caller (term.mjs decides); the default is plain text.
+
+// Every action a plan item can carry. A write never wears the skip glyph:
+// `add` and `replace-entry` are changes as much as `create` and `update`.
+const ACTION_ICON = { create: "create", add: "create", update: "update", "replace-entry": "update", migrate: "migrate", disable: "update", cleanup: "cleanup", remove: "remove", prune: "remove", skip: "skip", refuse: "refuse" };
+const ACTION_COLOR = { create: "green", add: "green", update: "cyan", "replace-entry": "cyan", migrate: "cyan", disable: "cyan", cleanup: "yellow", remove: "yellow", prune: "yellow", skip: "gray", refuse: "red" };
+
+// One step of an item as the lines it shows: always the action and its target,
+// then — under --verbose — why it runs.
+function stepLines(p, st, { verbose, paint, width = 0 }) {
+  const r = (x) => rel(p.projectDir, x);
+  const lead = "      ";
+  const sub = "          ";
+  const why = verbose && st.why ? wrap(st.why, width, sub).split("\n").map((l, k) => (k ? "" : sub) + paint("gray", l)) : [];
+  switch (st.kind) {
+    case "host": {
+      const out = [`${lead}${paint("cyan", "$")} ${[st.bin, ...st.argv].join(" ")}`];
+      if (st.touches.length) out.push(`${sub}${paint("gray", `touches ${st.touches.map(r).join(", ")}`)}`);
+      return [...out, ...why];
+    }
+    case "note": return wrap(`note: ${st.why}`, width, sub).split("\n").map((l, k) => (k ? l : lead + paint("yellow", "note:") + l.slice(5)));
+    case "write": return [`${lead}write ${st.path}${st.manifestOnly ? " (manifest only)" : ` (${st.files} files + the manifest)`}`, ...why];
+    case "portable-write": return [`${lead}stage ${st.path} (${st.files.length} payload files + catalogue + ownership)`, ...why];
+    case "portable-remove":
+    case "remove": return [`${lead}remove ${st.path}`, ...why];
+    case "unregister": return [`${lead}edit ${r(st.path)}  [${st.pointer}.${st.name}] → removed`, ...why];
+    case "ensure": return [`${lead}ensure ${r(st.path)}/`, ...why];
+    case "move-state": return [`${lead}move ${r(st.from)}/ → ${r(st.to)}/ (${st.files} entries)`, ...why];
+    case "merge-log": return [`${lead}merge ${r(st.from)} → ${r(st.to)}`, ...why];
+    case "delete": return [`${lead}delete ${r(st.path)}`, ...why];
+    case "move-marker": return [`${lead}move ${r(st.from)} → ${r(st.to)}`, ...why];
+    case "move-binding": return [`${lead}move ${r(st.from)} → ${r(st.to)}  (agents → ${r(st.overlay)})`, ...why];
+    case "remove-legacy-launcher":
+    case "rmdir-legacy":
+    case "remove-legacy-runtime": return [`${lead}remove ${r(st.path)}`, ...why];
+    default: return [];
+  }
+}
+
+// The harnesses a plan names, by their display names — for the header.
+function displayNames(p) {
+  return p.harnesses.map((id) => loadHarness(id)?.display_name || id).join(", ") || "(no harness)";
+}
+
+const tilde = (path) => {
+  const h = homedir();
+  return path === h || path.startsWith(h + "/") ? "~" + path.slice(h.length) : path;
+};
 
-export function renderPreview(p) {
-  const lines = [`projectstore ${p.mode} — ${p.harnesses.join(", ") || "(no harness)"} — ${p.projectDir}`, ""];
-  for (const [h, r] of Object.entries(p.plannedAgainst || {})) lines.push(`  ${h}: the surfaces below are planned against the host's install path ${r}, not this package at ${p.root}.`, "");
-  for (const r of p.reports) lines.push(...r.split("\n").map((l) => "  " + l), "");
+export function renderPreview(p, { verbose = false, verb = null, paint = (_style, text) => String(text), icon = null, width = 0 } = {}) {
+  const glyph = icon || ((name) => ({ create: "+", update: "↻", migrate: "↻", cleanup: "✕", remove: "✕", skip: "·", refuse: "!" }[name] || "·"));
   const writes = p.items.filter(isWrite);
+  const lines = [
+    `${paint("bold", "projectstore")} · ${verb || p.mode} · ${displayNames(p)}`,
+    `  ${paint("gray", tilde(p.projectDir))}`,
+    "",
+  ];
+  // Prose, wrapped to the terminal with every line indented; a path or a
+  // command inside it is one word and never broken (term.mjs wrap).
+  const prose = (indent, text, style = "gray") => wrap(text, width, indent).split("\n").map((l, k) => (k ? "" : indent) + paint(style, l));
+  if (verbose) {
+    for (const [h, r] of Object.entries(p.plannedAgainst || {})) lines.push(...prose("  ", `${h}: the surfaces below are planned against the host's install path ${r}, not this package at ${p.root}.`), "");
+    for (const r of p.reports) lines.push(...r.split("\n").flatMap((l) => (l.trim() ? prose("  ", l) : [""])), "");
+  }
+  const count = writes.length === 1 ? "1 change" : `${writes.length} changes`;
+  lines.push(`${paint("bold", "PLAN")} — ${p.ok ? count : "refused"}`);
+  // Unsupported host rows (no path, nothing this harness has) fold into one
+  // line per harness by default; --verbose lists each with the manifest's reason.
+  const folded = new Map();
   for (const i of p.items) {
-    const target = i.path === null
-      ? `harness=${i.harness}  surface=${i.surface}  [no filesystem path]`
-      : rel(p.projectDir, i.path);
+    if (!verbose && i.path === null && i.state === "unsupported" && i.action === "skip") {
+      const k = loadHarness(i.harness)?.display_name || i.harness;
+      if (!folded.has(k)) folded.set(k, []);
+      folded.get(k).push(i.surface);
+      continue;
+    }
+    const target = i.path === null ? `${i.surface} [${i.harness}, no filesystem path]` : rel(p.projectDir, i.path);
     const where = target + (i.entry ? `  [${i.entry}]` : "");
     let state = i.state;
     if (i.state === "current" && i.writtenBy && !i.sameProject) state = `current, last written by ${i.writtenBy}`;
+    // A row's reason is shown whenever it has one: a row of something
+    // already right carries none, and every other reason — a change, a skip
+    // that needs a terminal or a PATH, a block kept for another harness —
+    // is something the reader acts on (the reviewer's pass, 2026-10-05).
     if (i.reason && i.action !== "refuse") state += ` (${i.reason})`;
-    lines.push(`  ${i.kind.padEnd(9)} ${where}`);
-    lines.push(`            ${state.padEnd(44)} → ${i.action}${i.action === "refuse" && i.reason ? ": " + i.reason : ""}`);
-    for (const st of i.steps || []) {
-      if (st.kind === "host") lines.push(`            $ ${[st.bin, ...st.argv].join(" ")}`, `              ${st.why}${st.touches.length ? `; touches ${st.touches.map((t) => rel(p.projectDir, t)).join(", ")}` : ""}`);
-      else if (st.kind === "write") lines.push(`            write ${st.path}${st.manifestOnly ? " (manifest only)" : ` (${st.files} files + the manifest)`}`, `              ${st.why}`);
-      else if (st.kind === "portable-write") lines.push(`            stage ${st.path} (${st.files.length} payload files + catalogue + ownership)`, `              ${st.why}`);
-      else if (st.kind === "portable-remove") lines.push(`            remove ${st.path}`, `              ${st.why}`);
-      else if (st.kind === "remove") lines.push(`            remove ${st.path}`, `              ${st.why}`);
-      else if (st.kind === "unregister") lines.push(`            edit ${rel(p.projectDir, st.path)}  [${st.pointer}.${st.name}] → removed`, `              ${st.why}`);
-      else if (st.kind === "note") lines.push(`            note: ${st.why}`);
-      else if (st.kind === "ensure") lines.push(`            ensure ${rel(p.projectDir, st.path)}/`, `              ${st.why}`);
-      else if (st.kind === "move-state") lines.push(`            move ${rel(p.projectDir, st.from)}/ → ${rel(p.projectDir, st.to)}/ (${st.files} entries)`, `              ${st.why}`);
-      else if (st.kind === "merge-log") lines.push(`            merge ${rel(p.projectDir, st.from)} → ${rel(p.projectDir, st.to)}`, `              ${st.why}`);
-      else if (st.kind === "delete") lines.push(`            delete ${rel(p.projectDir, st.path)}`, `              ${st.why}`);
-      else if (st.kind === "move-marker") lines.push(`            move ${rel(p.projectDir, st.from)} → ${rel(p.projectDir, st.to)}`, `              ${st.why}`);
-      else if (st.kind === "move-binding") lines.push(`            move ${rel(p.projectDir, st.from)} → ${rel(p.projectDir, st.to)}  (agents → ${rel(p.projectDir, st.overlay)})`, `              ${st.why}`);
-      else if (st.kind === "remove-legacy-launcher" || st.kind === "rmdir-legacy" || st.kind === "remove-legacy-runtime") lines.push(`            remove ${rel(p.projectDir, st.path)}`, `              ${st.why}`);
-    }
-    if (i.kind === "registration" && i.home && i.surface && !i.surface.endsWith("_others")) lines.push(`            (harness home ${i.home}${i.scope ? `, scope ${i.scope}` : ""})`);
-    if (i.deleteIfEmpty && typeof i.after === "string" && !i.after.trim()) lines.push(`            (the file would hold nothing else and is removed)`);
+    const color = ACTION_COLOR[i.action] || (isWrite(i) ? "cyan" : "gray");
+    const mark = paint(color, glyph(ACTION_ICON[i.action] || (isWrite(i) ? "update" : "skip")));
+    const transition = `${state} → ${i.action}${i.action === "refuse" && i.reason ? ": " + i.reason : ""}`;
+    lines.push(`  ${mark} ${paint("bold", i.kind.padEnd(12))} ${where}`);
+    lines.push(...prose("      ", transition));
+    for (const st of i.steps || []) lines.push(...stepLines(p, st, { verbose, paint, width }));
+    if (i.kind === "registration" && i.home && i.surface && !i.surface.endsWith("_others")) lines.push(`      ${paint("gray", `(harness home ${i.home}${i.scope ? `, scope ${i.scope}` : ""})`)}`);
+    if (i.deleteIfEmpty && typeof i.after === "string" && !i.after.trim()) lines.push(`      ${paint("gray", "(the file would hold nothing else and is removed)")}`);
+  }
+  const hostLine = (text) => { const [first, ...rest] = wrap(text, width, " ".repeat(17)).split("\n"); return [`  ${paint("gray", glyph("skip"))} ${paint("bold", "host".padEnd(12))} ${first}`, ...rest]; };
+  for (const h of p.hostManaged || []) {
+    const from = h.entry ? `from the registration ${h.entry}` : "from the host's own plugin system";
+    lines.push(...hostLine(`${h.display} installs ${h.rows.join(", ")} itself, ${from}`));
   }
+  for (const [display, rows] of folded) lines.push(...hostLine(`not on ${display}: ${rows.join(", ")} — unsupported → skip ${paint("gray", "(--verbose says why)")}`));
   const exclusiveRemoval = p.items.find((i) => i.action === "remove" && i.kind === "exclusive");
-  if (exclusiveRemoval) lines.push(`            (an emptied ${rel(p.projectDir, dirname(exclusiveRemoval.path))}/ is pruned)`);
-  for (const r of p.refusals) lines.push(`  refused   ${r}`);
-  lines.push("", "  Nothing outside a marked entry is read, rewritten or removed.");
-  if (p.items.some((i) => (i.steps || []).some((s) => s.kind === "host"))) lines.push("  Each $ line runs the host's own CLI, which writes the host-owned files named after it.");
-  if (!p.ok) lines.push("", "  Nothing will be written: resolve the refusals above first.");
+  if (exclusiveRemoval) lines.push(`      ${paint("gray", `(an emptied ${rel(p.projectDir, dirname(exclusiveRemoval.path))}/ is pruned)`)}`);
+  for (const r of p.refusals) { const [first, ...rest] = wrap(r, width, " ".repeat(17)).split("\n"); lines.push(`  ${paint("red", glyph("refuse"))} ${paint("bold", "refused".padEnd(12))} ${first}`, ...rest); }
+  lines.push("", `  ${paint("gray", "Nothing outside a marked entry is read, rewritten or removed.")}`);
+  if (p.items.some((i) => (i.steps || []).some((s) => s.kind === "host"))) lines.push(`  ${paint("gray", "Each $ line runs the host's own CLI, which writes the host-owned files named after it.")}`);
+  if (!p.ok) lines.push("", `  ${paint("red", "Nothing will be written: resolve the refusals above first.")}`);
   else if (!writes.length) lines.push("", "  Nothing to change." + (p.incomplete ? " One surface could not be planned (see above)." : ""));
-  else lines.push("", `  ${writes.length} change(s) to apply.${p.incomplete ? " One surface could not be planned (see above); the rest proceeds." : ""}`);
+  else if (p.incomplete) lines.push("", "  One surface could not be planned (see above); the rest proceeds.");
   return lines.join("\n") + "\n";
 }
 
 // ─── gate ──────────────────────────────────────────────────────────────
 
-// A named harness is the explicit confirmation (contract 9). Otherwise ask on
-// a TTY, and refuse without one. Streams are parameters so the TTY branch is
-// testable without a pseudo-terminal.
-export async function confirm(p, { stdin = process.stdin, stdout = process.stdout, ask = null } = {}) {
+// Contract 9, amended 2026-10-04: a person at a terminal is asked, even when
+// the harness is named — the shells always name it, so naming alone had
+// stopped meaning a person agreed. Without one (a pipe, an agent's tool call,
+// CI, --json, a command run inside a host session) a named harness is the
+// confirmation and a bare one refuses, exactly as before.
+export function isInteractive({ stdin = null, stdout = null, env = process.env, json = false } = {}) {
+  if (json) return false;
+  if (!(stdin && stdin.isTTY && stdout && stdout.isTTY)) return false;
+  if (env.CI && !["0", "false"].includes(String(env.CI).toLowerCase())) return false;
+  // A host session's own tool may run us in a pseudo-terminal; the manifests'
+  // session markers say when that is happening — every manifest's, not only
+  // the planned harness's: a Claude Code agent running the Codex shell is
+  // still an agent. (Codex's own markers are unmeasured; for it the TTY test
+  // above carries the rule.)
+  if ([...loadHarnesses().values()].some((m) => insideHostSession(env, m))) return false;
+  return true;
+}
+
+// Streams and `ask` are parameters so the terminal branch is testable without
+// a pseudo-terminal; passing `ask` means "this is a terminal". Without streams
+// the library never asks — the bin and main() pass theirs.
+export async function confirm(p, { stdin = null, stdout = null, ask = null, env = process.env, json = false, paint = (_style, text) => String(text) } = {}) {
   if (!p.ok) return { confirmed: false, why: "refused" };
   const writes = p.items.filter(isWrite);
   if (!writes.length) return { confirmed: false, why: "nothing-to-do" };
-  if (p.named) return { confirmed: true, why: "named" };
-  const interactive = Boolean(stdin && stdin.isTTY && stdout && stdout.isTTY);
-  if (!interactive && !ask) return { confirmed: false, why: "non-tty" };
-  const answer = ask ? await ask(`Apply these ${writes.length} change(s)? [y/N] `) : await (async () => {
-    const rl = createInterface({ input: stdin, output: stdout });
-    try { return await rl.question(`Apply these ${writes.length} change(s)? [y/N] `); } finally { rl.close(); }
-  })();
-  return /^y(es)?$/i.test(String(answer).trim()) ? { confirmed: true, why: "answered" } : { confirmed: false, why: "declined" };
+  const interactive = !json && (ask ? true : isInteractive({ stdin, stdout, env, json }));
+  if (!interactive) return p.named ? { confirmed: true, why: "named" } : { confirmed: false, why: "non-tty" };
+  const question = `${paint("bold", `Apply ${writes.length === 1 ? "1 change" : `${writes.length} changes`}?`)} ${paint("gray", "[Y/n]")} `;
+  const answer = ask ? await ask(question) : await askLine(question, stdin, stdout);
+  if (answer === null || answer === undefined) return { confirmed: false, why: "declined" };
+  return /^(y(es)?)?$/i.test(String(answer).trim()) ? { confirmed: true, why: "answered" } : { confirmed: false, why: "declined" };
 }
 
 // ─── apply ─────────────────────────────────────────────────────────────
 
-export function apply(p, { env = process.env, spawn = spawnSync, home = homedir() } = {}) {
+export function apply(p, { env = process.env, spawn = spawnSync, home = homedir(), onItem = null, onStep = null } = {}) {
   if (!p.ok) throw new Error("apply: the plan carries refusals; nothing is written");
   const done = [];
   let registrationFailed = false;
   let layoutFailed = false;
-  for (const i of p.items) {
-    if (!isWrite(i)) continue;
+  // One item's writes, returning the record apply reports for it. The order
+  // and the failure rules are the loop's; onItem only watches (contract 18).
+  const one = (i) => {
     if (i.kind === "layout") {
-      const r = applyLayout(p, i, { failed: layoutFailed || registrationFailed || Boolean(done.failed), home });
-      done.push(r);
+      const r = applyLayout(p, i, { failed: layoutFailed || registrationFailed || Boolean(done.failed), home, onStep });
       if (r.failed) { done.failed = r.failed; layoutFailed = true; }
-      continue;
+      return r;
     }
     if (i.kind === "registration") {
-      const r = applyRegistration(p, i, { env, spawn, home });
-      done.push(r);
+      const r = applyRegistration(p, i, { env, spawn, home, onStep });
       // A registration that did not complete leaves the surfaces planned against
       // its install path unwritten: a launcher pointing at nothing is worse than
       // none. Surfaces rendered from the package root (the block) still apply.
       if (r.failed) { done.failed = r.failed; registrationFailed = true; }
-      continue;
+      return r;
     }
-    if (registrationFailed && i.plannedAgainst) { done.push({ path: i.path, action: "skipped", surface: i.surface, reason: "the registration did not complete; this surface was planned against its install path" }); continue; }
+    if (registrationFailed && i.plannedAgainst) return { path: i.path, action: "skipped", surface: i.surface, reason: "the registration did not complete; this surface was planned against its install path" };
     if (i.kind === "shared" && typeof i.after === "object" && i.after !== null && !Array.isArray(i.after)) {
       mkdirSync(dirname(i.path), { recursive: true });
       // Re-read at write time: a host command run earlier in this apply (the
@@ -970,7 +1077,16 @@ export function apply(p, { env = process.env, spawn = spawnSync, home = homedir(
       mkdirSync(dirname(i.path), { recursive: true });
       writeFileAtomic(i.path, i.after, { sweep: false });
     }
-    done.push({ path: i.path, action: i.action, surface: i.surface });
+    return { path: i.path, action: i.action, surface: i.surface };
+  };
+  for (const i of p.items) {
+    if (!isWrite(i)) continue;
+    if (onItem) onItem(i, "start");
+    let r;
+    try { r = one(i); }
+    catch (e) { if (onItem) onItem(i, "abort"); throw e; }
+    done.push(r);
+    if (onItem) onItem(i, "end", r);
   }
   return done;
 }
@@ -980,7 +1096,7 @@ export function apply(p, { env = process.env, spawn = spawnSync, home = homedir(
 // same home the plan was read from — and with the project as its cwd, which is
 // how the host resolves `--scope local`. A non-zero exit stops the item and
 // is recorded, never retried, never masked.
-function applyRegistration(p, i, { env, spawn, home }) {
+function applyRegistration(p, i, { env, spawn, home, onStep = null }) {
   const out = { path: i.path, action: i.action, surface: i.surface, steps: [] };
   const harness = loadHarness(i.harness);
   const childEnv = { ...env, [homeEnvName(i.harness)]: i.home || claudeHome(home) };
@@ -1187,6 +1303,11 @@ function applyRegistration(p, i, { env, spawn, home }) {
     return out;
   };
   for (const st of i.steps || []) {
+    // Host commands report through the spawn the caller passed (one line per
+    // argv, rollbacks included); the filesystem steps report here.
+    const seen = out.steps.length;
+    const watched = onStep && st.kind !== "host";
+    if (watched) onStep(st, "start");
     try {
     if (st.kind === "portable-write") {
       const token = `${process.pid}-${randomUUID()}`;
@@ -1242,6 +1363,8 @@ function applyRegistration(p, i, { env, spawn, home }) {
     }
     } catch (e) {
       return fail(st.kind, null, e && e.message ? e.message : String(e));
+    } finally {
+      if (watched) onStep(st, "end", stepResult(out, seen));
     }
   }
   // The host's registry is read back: the install path the rest of the plan
@@ -1298,24 +1421,151 @@ function pruneEmptyDir(dir, projectDir) {
 export async function runVerb(verb, projectDir, opts = {}) {
   const mode = verb === "uninstall" ? "uninstall" : "install"; // upgrade is install re-run (contract 14)
   const p = plan(projectDir, { ...opts, mode });
-  const preview = renderPreview(p);
-  const gate = await confirm(p, opts);
-  const result = { verb, plan: p, preview, gate, applied: [], failed: null };
+  const env = opts.env || process.env;
+  // `out` is the text-mode caller's stdout. With it, this prints: the plan
+  // first, then the question, then each step as it runs, then DONE.
+  const out = opts.out || null;
+  const c = out ? termCaps(out, env) : null;
+  const paint = c ? painter(c) : (_style, text) => String(text);
+  const glyph = c ? (name) => termIcon(c, name) : null;
+  const preview = renderPreview(p, { verbose: Boolean(opts.verbose), verb, paint, icon: glyph, width: c && c.live ? c.width : 0 });
+  if (out) out.write(preview + "\n");
+  const gate = await confirm(p, { ...opts, env, paint });
+  const result = { verb, plan: p, preview, gate, applied: [], failed: null, elapsed: 0 };
   if (gate.confirmed) {
-    result.applied = apply(p, { env: opts.env || process.env, spawn: opts.spawn || spawnSync, home: opts.home || homedir() });
+    const t0 = Date.now();
+    const reporter = out ? applyReporter(out, c, p) : null;
+    const spawn = opts.spawn || spawnSync;
+    result.applied = apply(p, { env, spawn: reporter ? reporter.spawn(spawn) : spawn, home: opts.home || homedir(), onItem: reporter ? reporter.onItem : null, onStep: reporter ? reporter.onStep : null });
     result.failed = result.applied.failed || null;
+    result.elapsed = Date.now() - t0;
+    if (out) out.write(renderDone(result, { paint, glyph: glyph || undefined, verbose: Boolean(opts.verbose) }));
   }
   return result;
 }
 
+// APPLY, one line per step (contract 18). An item with steps — a
+// registration, the layout move — prints its name, then one line per step
+// beneath it: each host command, staging write, write and move. Any other
+// item is one line.
+function applyReporter(out, c, p) {
+  const paint = painter(c);
+  const item = stepReporter(out, c, { indent: 2 });
+  const step = stepReporter(out, c, { indent: 6 });
+  let opened = false;
+  const open = () => { if (!opened) { out.write(`${paint("bold", "APPLY")}\n`); opened = true; } };
+  const label = (i) => {
+    const target = i.path === null ? i.surface : rel(p.projectDir, i.path);
+    return `${i.kind} ${target}${i.entry ? ` [${i.entry}]` : ""}`;
+  };
+  const stepped = (i) => i.kind === "registration" || i.kind === "layout";
+  return {
+    onItem(i, phase, r) {
+      open();
+      if (stepped(i)) {
+        if (phase === "start") out.write(`  ${paint(ACTION_COLOR[i.action] || "cyan", termIcon(c, ACTION_ICON[i.action] || "update"))} ${label(i)}\n`);
+        else if (phase === "abort") step.abort();
+        else if (r && (r.action === "skipped" || r.action === "skip")) out.write(`      ${paint("gray", termIcon(c, "skip"))} ${paint("gray", `${r.action === "skip" ? "nothing to do" : "skipped"}: ${r.reason || "an earlier item failed"}`)}\n`);
+        else if (r && r.failed) out.write(`      ${paint("red", termIcon(c, "fail"))} ${paint("red", "stopped")}\n`);
+        return;
+      }
+      if (phase === "start") item.start(label(i));
+      else if (phase === "abort") item.abort();
+      else item.end(!(r && (r.failed || r.action === "skipped")), r && r.action === "skipped" ? "skipped" : "");
+    },
+    onStep(st, phase, r) {
+      const text = stepLabel(p, st);
+      if (!text) return;
+      if (phase === "start") step.start(text);
+      else step.end(r ? r.ok : true, r && r.kept ? "kept" : "", { kept: Boolean(r && r.kept) });
+    },
+    spawn(inner) {
+      return (bin, argv, o) => {
+        open();
+        step.start(`$ ${basename(String(bin))} ${argv.join(" ")}`);
+        let r;
+        try { r = inner(bin, argv, o); }
+        catch (e) { step.abort(); throw e; }
+        step.end(!r.error && r.status === 0);
+        return r;
+      };
+    },
+  };
+}
+
+// A step as its APPLY line names it: the verb and the target, short. The
+// full form — file counts, entry pointers — was in PLAN.
+function stepLabel(p, st) {
+  const r = (x) => tilde(rel(p.projectDir, x));
+  switch (st.kind) {
+    case "portable-write": return `stage ${r(st.path)}`;
+    case "write": return `write ${r(st.path)}`;
+    case "unregister": return `edit ${r(st.path)} [${st.pointer}.${st.name}]`;
+    case "ensure": return `ensure ${r(st.path)}/`;
+    case "move-state": return `move ${r(st.from)}/ → ${r(st.to)}/`;
+    case "merge-log": return `merge ${r(st.from)} → ${r(st.to)}`;
+    case "move-marker":
+    case "move-binding": return `move ${r(st.from)} → ${r(st.to)}`;
+    case "delete":
+    case "portable-remove":
+    case "remove":
+    case "remove-legacy-launcher":
+    case "rmdir-legacy":
+    case "remove-legacy-runtime": return `remove ${r(st.path)}`;
+    default: return null;
+  }
+}
+
+// DONE: what happened, how long it took, what to do next — from the manifests,
+// never from a harness-id branch — and at most two tips.
+export function renderDone(r, { paint = (_style, text) => String(text), glyph = (n) => termIcon({ ascii: false }, n), verbose = false } = {}) {
+  const p = r.plan;
+  // What applied: a record that neither failed nor was skipped — a recheck
+  // that found the work already done is not a change.
+  const n = r.applied.filter((a) => !a.failed && !["skipped", "skip"].includes(a.action)).length;
+  const changes = n === 1 ? "1 change" : `${n} changes`;
+  const lines = [""];
+  if (r.failed) {
+    const f = r.failed;
+    const record = r.applied.find((a) => a.failed);
+    const item = record ? p.items.find((i) => i.surface === record.surface && i.path === record.path) : null;
+    const what = f.argv ? "a host command failed" : `${f.step} failed`;
+    lines.push(`${paint("bold", "STOPPED")} — ${changes} applied, then ${what}`);
+    if (f.argv) lines.push(`  ${paint("red", glyph("fail"))} $ ${f.argv.join(" ")}${f.status === null || f.status === undefined ? "" : ` exited ${f.status}`}`);
+    else lines.push(`  ${paint("red", glyph("fail"))} ${f.step}${item ? ` (${item.kind} ${item.path === null ? item.surface : rel(p.projectDir, item.path)})` : ""}`);
+    if (f.stderr) for (const l of String(f.stderr).split("\n")) lines.push(`      ${l}`);
+    if (item && item.kind === "registration") lines.push("  The surfaces planned against its install path were not written; run the verb again once it succeeds.");
+    else lines.push("  Run the verb again once the cause is fixed: its plan starts from what is on disk now.");
+    return lines.join("\n") + "\n";
+  }
+  lines.push(`${paint("bold", "DONE")} — ${changes} in ${duration(r.elapsed || 0)}`);
+  const next = [], tips = [];
+  const here = (() => { try { return realpathSync(p.projectDir) === realpathSync(process.cwd()); } catch { return p.projectDir === process.cwd(); } })();
+  for (const id of p.harnesses) {
+    const m = loadHarness(id);
+    if (!m) continue;
+    const steps = r.verb === "uninstall" ? [`restart ${m.display_name}`] : (m.install?.next || []);
+    for (const s of steps) if (!next.includes(s)) next.push(s);
+    // `plan` previews an install: after an uninstall it would preview the
+    // opposite of what just ran.
+    if (r.verb === "uninstall") continue;
+    const preview = packageCommand(m, "plan", { args: `--project ${here ? '"$PWD"' : `"${p.projectDir}"`}` });
+    if (!tips.some((t) => t.includes(preview))) tips.push(`preview without writing: ${preview}`);
+  }
+  if (!verbose) tips.push("every row's reasoning: add --verbose");
+  for (const s of next) lines.push(`  ${paint("cyan", "next")}  ${s}`);
+  for (const t of tips.slice(0, 2)) lines.push(`  ${paint("gray", "tip")}   ${paint("gray", t)}`);
+  return lines.join("\n") + "\n";
+}
+
 // ─── main ──────────────────────────────────────────────────────────────
 
 function usage() {
   return [
-    "usage: install-harness.mjs <install|uninstall|upgrade|plan> [--harness <id>]... [--surface <key>]... [--project <dir>] [--global] [--no-register] [--json]",
+    "usage: install-harness.mjs <install|uninstall|upgrade|plan> [--harness <id>]... [--surface <key>]... [--project <dir>] [--global] [--no-register] [--verbose] [--json]",
     `  harnesses: ${harnessIds().join(", ")}`,
     "  --surface narrows the plan to a surface and the surfaces beneath it (statusline covers statusline_launcher)",
-    "  --harness names the harness — and, non-interactively, is the confirmation; there is no --yes",
+    "  --harness names the harness — and, without a terminal, is the confirmation (a terminal is asked); there is no --yes",
   ].join("\n");
 }
 
@@ -1344,7 +1594,7 @@ async function main() {
   const verb = argv[0];
   if (!["install", "uninstall", "upgrade", "plan"].includes(verb)) { process.stderr.write(usage() + "\n"); process.exit(2); }
   const harnesses = [], surfaces = [];
-  let projectDir = null, json = false, globalRemoval = false, register = true;
+  let projectDir = null, json = false, globalRemoval = false, register = true, verbose = false;
   for (let i = 1; i < argv.length; i++) {
     const a = argv[i];
     const value = () => { const v = argv[++i]; if (v === undefined || v.startsWith("--")) { process.stderr.write(`${a} needs a value\n${usage()}\n`); process.exit(2); } return v; };
@@ -1354,34 +1604,27 @@ async function main() {
     else if (a === "--global") globalRemoval = true;
     else if (a === "--no-register" && verb !== "uninstall") register = false;
     else if (a === "--json") json = true;
+    else if (a === "--verbose") verbose = true;
     else { process.stderr.write(`unknown argument ${a}\n${usage()}\n`); process.exit(2); }
   }
   const src = sourceHarness();
   projectDir = resolve(projectDir || (src && process.env[src.runtime?.project_dir_env]) || process.cwd());
-  const opts = { harnesses, surfaces: surfaces.length ? surfaces : null, globalRemoval, register };
+  const opts = { harnesses, surfaces: surfaces.length ? surfaces : null, globalRemoval, register, json, verbose, stdin: process.stdin, stdout: process.stdout };
   if (verb === "plan") {
     const p = plan(projectDir, opts);
-    process.stdout.write(json ? JSON.stringify({ ...p, items: p.items.map(publicItem) }, null, 2) + "\n" : renderPreview(p));
+    const c = termCaps(process.stdout, process.env);
+    process.stdout.write(json ? JSON.stringify({ ...p, items: p.items.map(publicItem) }, null, 2) + "\n" : renderPreview(p, { verbose, verb, paint: painter(c), icon: (n) => termIcon(c, n), width: c.live ? c.width : 0 }));
     process.exit(p.ok && !p.incomplete ? 0 : 1);
   }
-  const r = await runVerb(verb, projectDir, opts);
+  const r = await runVerb(verb, projectDir, json ? opts : { ...opts, out: process.stdout });
   if (json) {
     process.stdout.write(JSON.stringify({ verb, ok: r.plan.ok && !r.plan.incomplete && !r.failed, gate: r.gate, applied: r.applied, failed: r.failed, incomplete: r.plan.incomplete, items: r.plan.items.map(publicItem), refusals: r.plan.refusals, reports: r.plan.reports }, null, 2) + "\n");
-  } else {
-    process.stdout.write(r.preview);
-    if (r.gate.confirmed) process.stdout.write(appliedLine(r));
-    else if (r.gate.why === "non-tty") process.stdout.write(`a bare ${verb} in a non-TTY refuses; name a harness to confirm: --harness ${r.plan.detected.map((d) => d.id).join(" | ") || harnessIds().join(" | ")}\n`);
-    else if (r.gate.why === "declined") process.stdout.write("nothing written.\n");
+  } else if (r.gate.why === "non-tty") {
+    process.stdout.write(`Nothing written: without a terminal, a bare ${verb} refuses. Name the harness to confirm: --harness ${r.plan.detected.map((d) => d.id).join(" | ") || harnessIds().join(" | ")}\n`);
+  } else if (r.gate.why === "declined") {
+    process.stdout.write("Nothing written.\n");
   }
   process.exit(r.plan.ok && !r.plan.incomplete && !r.failed && (r.gate.confirmed || r.gate.why === "nothing-to-do") ? 0 : 1);
 }
 
-// What apply did, for a terminal: the count, and a failed host command with
-// its stderr — the user sees what the host said, verbatim.
-export function appliedLine(r) {
-  let s = `applied ${r.applied.length} change(s).\n`;
-  if (r.failed) s += `stopped: ${r.failed.argv ? "$ " + r.failed.argv.join(" ") : r.failed.step} exited ${r.failed.status ?? "without running"}${r.failed.stderr ? "\n  " + r.failed.stderr.split("\n").join("\n  ") : ""}\n  the surfaces planned against its install path were not written; run the verb again once it succeeds.\n`;
-  return s;
-}
-
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main();

package/node_modules/projectstore/scripts/term.mjs

@@ -0,0 +1,147 @@
+// projectstore — term.mjs: terminal presentation for the write verbs, with no
+// dependency (the zero-dependency property the MCP and link-graph ADRs keep).
+//
+// One question decides everything here: is this a person at a terminal? Then
+// colour and in-place step lines. Otherwise — a pipe, an agent's tool call,
+// CI — the same layout as plain text, so a reader that is not a terminal loses
+// nothing but the escapes (install spec, contract 18).
+//
+//   caps(stream, env)            → { color, live, width, ascii }
+//   painter(caps)                → paint(style, text)
+//   icon(caps, name)             → the glyph for an action or a result
+//   duration(ms)                 → "0.4s", "12s", "1m 03s"
+//   wrap(text, width, indent)    → prose broken at spaces, hanging indent
+//   stepReporter(stream, caps)   → { start(label), end(ok, note), abort() }
+//   askLine(question, in, out)   → the answer, or null on end of input
+
+import { createInterface } from "node:readline/promises";
+
+// FORCE_COLOR decides when it is set, as Node's own tty reads it: "", "1",
+// "2", "3" or "true" turn colour on even without a terminal, anything else
+// ("0", "false") turns it off. Otherwise NO_COLOR (https://no-color.org) turns
+// colour off when set to anything non-empty, and TERM=dumb means a terminal
+// that understands no escapes.
+export function caps(stream = process.stdout, env = process.env) {
+  const tty = Boolean(stream && stream.isTTY);
+  const dumb = env.TERM === "dumb";
+  const off = env.NO_COLOR !== undefined && env.NO_COLOR !== "";
+  const color = env.FORCE_COLOR !== undefined ? ["", "1", "2", "3", "true"].includes(String(env.FORCE_COLOR)) : tty && !dumb && !off;
+  const columns = tty && Number(stream.columns) > 0 ? Number(stream.columns) : 100;
+  // `width` lays out prose (never below 40); `columns` is the terminal's
+  // real width, which a live line must not reach.
+  return { color, live: tty && !dumb, width: Math.max(40, Math.min(columns, 120)), columns, ascii: dumb };
+}
+
+const SGR = {
+  bold: [1, 22], dim: [2, 22], red: [31, 39], green: [32, 39], yellow: [33, 39],
+  blue: [34, 39], magenta: [35, 39], cyan: [36, 39], gray: [90, 39],
+};
+
+// Raw SGR rather than util.styleText: that arrived in Node 20.12 and 21.7, and
+// the package promises >=20.0.0.
+export function painter(c) {
+  return (style, text) => {
+    const s = String(text);
+    if (!c.color || !SGR[style] || !s) return s;
+    return `\x1b[${SGR[style][0]}m${s}\x1b[${SGR[style][1]}m`;
+  };
+}
+
+const ICONS = {
+  create: ["+", "+"], update: ["↻", "~"], migrate: ["↻", "~"], refresh: ["↻", "~"],
+  remove: ["✕", "x"], cleanup: ["✕", "x"], skip: ["·", "."], refuse: ["!", "!"],
+  ok: ["✓", "ok"], fail: ["✗", "FAIL"], running: ["…", "..."], note: ["!", "!"],
+};
+export function icon(c, name) {
+  const pair = ICONS[name] || ICONS.update;
+  return c.ascii ? pair[1] : pair[0];
+}
+
+export function duration(ms) {
+  if (ms < 10_000) return `${(ms / 1000).toFixed(1)}s`;
+  if (ms < 60_000) return `${Math.round(ms / 1000)}s`;
+  const m = Math.floor(ms / 60_000), s = Math.round((ms % 60_000) / 1000);
+  return `${m}m ${String(s).padStart(2, "0")}s`;
+}
+
+// Strip SGR escapes — for measuring a painted string and for tests.
+export const plain = (s) => String(s).replace(/\x1b\[[0-9;]*m/g, "");
+
+// Prose only: broken at spaces to `width` columns, every line after the first
+// indented by `indent`. A word longer than the line — a path, a command — is
+// never broken: a path cut in two cannot be copied back. Width 0 is a reader
+// that is not a terminal: nothing is broken, so a search never meets a split.
+export function wrap(text, width, indent = "") {
+  if (!width) return String(text);
+  const room = Math.max(20, width - indent.length);
+  const lines = [];
+  let line = "";
+  for (const word of String(text).split(" ")) {
+    if (line && plain(line).length + 1 + plain(word).length > room) { lines.push(line); line = word; }
+    else line = line ? `${line} ${word}` : word;
+  }
+  lines.push(line);
+  return lines.map((l, k) => (k ? indent + l : l)).join("\n");
+}
+
+// A live line must fit one physical row: "\r\x1b[2K" clears only the row the
+// cursor is on, so a label that wrapped would leave its first half behind.
+const fit = (text, room) => (text.length <= room ? text : text.slice(0, Math.max(1, room - 1)) + "…");
+
+// One line per step. On a live terminal the line appears when the step starts
+// (ending in "…") and is rewritten in place with the result and duration when
+// it ends; anything else gets the finished line only. Steps run synchronously
+// (spawnSync), so nothing animates in between — the "…" is the honest state.
+export function stepReporter(stream = process.stdout, c = caps(stream), { indent = 2 } = {}) {
+  const paint = painter(c);
+  let open = null;
+  // One column short of the terminal: a line that fills the last column
+  // leaves some terminals waiting to wrap.
+  const width = Math.min(c.width, c.columns || c.width, 100) - 1;
+  const line = (mark, label, right) => {
+    const room = width - indent - 2 - plain(right).length - 1;
+    const left = `${" ".repeat(indent)}${mark} ${c.live ? fit(label, room) : label}`;
+    const gap = Math.max(1, width - plain(left).length - plain(right).length);
+    return left + " ".repeat(gap) + right;
+  };
+  const self = {
+    start(label) {
+      // A step started while another is still open (a host command run by a
+      // rollback) closes the open line where it stands rather than overwrite it.
+      if (open && c.live) stream.write("\n");
+      open = { label, t0: Date.now() };
+      if (c.live) stream.write(line(paint("gray", icon(c, "running")), label, ""));
+    },
+    end(ok = true, note = "", { kept = false } = {}) {
+      if (!open) return;
+      const ms = Date.now() - open.t0;
+      // A step that ran and left its target in place is neither ✓ nor ✗.
+      const mark = !ok ? paint("red", icon(c, "fail")) : kept ? paint("gray", icon(c, "skip")) : paint("green", icon(c, "ok"));
+      const right = paint("gray", [note, duration(ms)].filter(Boolean).join("  "));
+      const text = line(mark, open.label, right);
+      stream.write((c.live ? "\r\x1b[2K" : "") + text + "\n");
+      open = null;
+    },
+    // An exception left a step open: end its line as failed, so whatever is
+    // printed next starts on a line of its own.
+    abort() { if (open) self.end(false); },
+  };
+  return self;
+}
+
+// One line of input, read the way a shell's own prompt is: in the terminal's
+// line mode, so readline writes nothing but the question (no cursor escapes),
+// the terminal does the editing, and Ctrl+C is a real SIGINT (exit 130, before
+// anything is written). End of input — Ctrl+D, a closed pipe — is null, which
+// every caller reads as no; it never leaves the question pending (an unsettled
+// promise is exit 13 with a warning). The promise API rejects on close in
+// some Node versions and stays pending in others; both settle here.
+export async function askLine(question, input, output) {
+  const rl = createInterface({ input, output, terminal: false });
+  return await new Promise((settle) => {
+    let done = false;
+    const finish = (answer) => { if (done) return; done = true; settle(answer); rl.close(); };
+    rl.on("close", () => finish(null));
+    rl.question(question).then((a) => finish(a), () => finish(null));
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projectstore-claude",
-  "version": "0.28.2",
+  "version": "0.29.0",
   "description": "Installs projectstore for Claude Code from npm: the core pinned and bundled, the harness fixed — npx projectstore-claude install --project \"$PWD\".",
   "keywords": [
     "projectstore",
@@ -37,7 +37,7 @@
     "README.md"
   ],
   "dependencies": {
-    "projectstore": "=0.28.2"
+    "projectstore": "=0.29.0"
   },
   "bundleDependencies": [
     "projectstore"