token-harness 0.1.0 → 0.1.1

package/token-harness.mjs

@@ -155,6 +155,7 @@ function diagnostic(init) {
     severity: init.severity,
     code: init.code,
     message: init.message,
+    subject: init.subject ?? null,
     path: init.path ?? null,
     remediation: init.remediation ?? null
   };
@@ -263,6 +264,9 @@ function isStartableExecutable(resolved) {
 // packages/core/dist/src/domain/process.js
 var DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
 var DEFAULT_PROCESS_TIMEOUT_MS = 3e4;
+function processSucceeded(outcome2) {
+  return outcome2.failure === null && outcome2.exitCode === 0;
+}
 
 // packages/core/dist/src/domain/redaction.js
 var REDACTED = "[redacted]";
@@ -882,12 +886,12 @@ function isUsableSalt(value) {
 }
 
 // packages/core/dist/src/metrics/local-database.js
-function numberAt(row, column2) {
-  const value = row[column2];
+function numberAt(row2, column2) {
+  const value = row2[column2];
   return typeof value === "number" ? value : null;
 }
-function stringAt(row, column2) {
-  const value = row[column2];
+function stringAt(row2, column2) {
+  const value = row2[column2];
   return typeof value === "string" ? value : null;
 }
 
@@ -988,7 +992,7 @@ function aggregateEvents(input) {
   const managed = new Set(input.managedProviders ?? []);
   const modes = input.adapterModes ?? {};
   const classes = MEASUREMENT_CLASSES.map((measurementClass) => {
-    const rows = [...classTotals.values()].filter((row2) => row2.class === measurementClass);
+    const rows = [...classTotals.values()].filter((row3) => row3.class === measurementClass);
     if (rows.length > 1) {
       return {
         class: measurementClass,
@@ -996,11 +1000,11 @@ function aggregateEvents(input) {
         before: null,
         after: null,
         saved: null,
-        note: `recorded in ${rows.map((row2) => row2.unit).join(" and ")}, which are not addable`
+        note: `recorded in ${rows.map((row3) => row3.unit).join(" and ")}, which are not addable`
       };
     }
-    const row = rows[0];
-    if (row === void 0) {
+    const row2 = rows[0];
+    if (row2 === void 0) {
       return {
         class: measurementClass,
         unit: null,
@@ -1012,22 +1016,22 @@ function aggregateEvents(input) {
     }
     return {
       class: measurementClass,
-      unit: row.unit,
-      before: row.before,
-      after: row.after,
-      saved: row.before - row.after,
+      unit: row2.unit,
+      before: row2.before,
+      after: row2.after,
+      saved: row2.before - row2.after,
       note: null
     };
   });
-  const providers = [...providerTotals.values()].sort((left, right) => right.saved - left.saved || left.providerId.localeCompare(right.providerId)).map((row) => ({
-    providerId: row.providerId,
-    saved: row.saved,
-    unit: row.unit,
-    class: row.class,
-    operations: row.operations,
-    harnesses: [...row.harnesses].sort(),
-    managedByTokenHarness: managed.has(row.providerId),
-    adapterMode: modes[row.providerId] ?? null
+  const providers = [...providerTotals.values()].sort((left, right) => right.saved - left.saved || left.providerId.localeCompare(right.providerId)).map((row2) => ({
+    providerId: row2.providerId,
+    saved: row2.saved,
+    unit: row2.unit,
+    class: row2.class,
+    operations: row2.operations,
+    harnesses: [...row2.harnesses].sort(),
+    managedByTokenHarness: managed.has(row2.providerId),
+    adapterMode: modes[row2.providerId] ?? null
   }));
   const operations = realized + bypassed;
   return {
@@ -2037,6 +2041,139 @@ async function applyRemoveOwnedChange(action, context) {
   await fs.writeFile(action.target.path, UTF8.encode(removal.text), null);
   return outcome(action, "applied", { snapshots: [snapshot] });
 }
+async function scanTree(fs, path, entries = []) {
+  const stat3 = await fs.stat(path);
+  if (stat3 === null)
+    return entries;
+  const digest = stat3.kind === "file" ? digestBytes(await fs.readFile(path)) : null;
+  entries.push({ path, kind: stat3.kind, digest, byteLength: stat3.byteLength });
+  if (stat3.kind === "directory") {
+    for (const child of await fs.readDirectory(path)) {
+      await scanTree(fs, fs.join(path, child), entries);
+    }
+  }
+  return entries;
+}
+function equalTreeEntry(left, right) {
+  return left !== void 0 && right !== void 0 && left.kind === right.kind && left.digest === right.digest;
+}
+async function applyDelegatedProviderInstall(action, context) {
+  if (context.runner === null || context.runner === void 0 || context.cwd === void 0) {
+    return refusal(action, "process-runner-unavailable", action.executable, "A delegated provider install requires a process runner and working directory", "Run this command through the Token Harness CLI");
+  }
+  const before = /* @__PURE__ */ new Map();
+  for (const boundary of action.containmentBoundary) {
+    for (const entry of await scanTree(context.fs, boundary))
+      before.set(entry.path, entry);
+  }
+  if (action.expectedArtifacts.every((artifact) => before.get(artifact.path)?.kind === "file" && before.get(artifact.path)?.digest === artifact.digest)) {
+    return outcome(action, "already-satisfied");
+  }
+  const bytes = [...before.values()].reduce((total, entry) => total + entry.byteLength, 0);
+  if (bytes > action.snapshotSizeCapBytes) {
+    return refusal(action, "delegated-install-snapshot-too-large", action.containmentBoundary[0] ?? action.executable, `The delegated install boundary is ${String(bytes)} bytes, above its ${String(action.snapshotSizeCapBytes)} byte snapshot cap`, "Narrow the provider containment boundary before applying this plan");
+  }
+  const snapshots = [];
+  const capturedPaths = /* @__PURE__ */ new Set();
+  for (const boundary of action.containmentBoundary) {
+    const entries = await scanTree(context.fs, boundary);
+    if (entries.length === 0) {
+      snapshots.push(await context.snapshots.capture(boundary));
+      capturedPaths.add(boundary);
+      continue;
+    }
+    for (const entry of entries) {
+      snapshots.push(await context.snapshots.capture(entry.path));
+      capturedPaths.add(entry.path);
+    }
+  }
+  const result = await context.runner.run({
+    executable: action.executable,
+    args: action.args,
+    cwd: context.cwd,
+    timeoutMs: 3e4
+  });
+  if (!processSucceeded(result)) {
+    return outcome(action, "failed", {
+      snapshots,
+      diagnostics: [
+        diagnostic({
+          severity: "error",
+          code: "delegated-install-failed",
+          message: `${action.executable} did not complete its delegated install successfully`,
+          remediation: "Review the provider output and rerun the plan after correcting the problem"
+        })
+      ]
+    });
+  }
+  const after = /* @__PURE__ */ new Map();
+  for (const boundary of action.containmentBoundary) {
+    for (const entry of await scanTree(context.fs, boundary))
+      after.set(entry.path, entry);
+  }
+  for (const entry of after.values()) {
+    if (!before.has(entry.path) && !capturedPaths.has(entry.path)) {
+      snapshots.push(context.snapshots.captureAbsent(entry.path));
+      capturedPaths.add(entry.path);
+    }
+  }
+  const protectedPath = action.protectedPaths.find((path) => !equalTreeEntry(before.get(path), after.get(path)));
+  if (protectedPath !== void 0) {
+    return outcome(action, "failed", {
+      snapshots,
+      diagnostics: [
+        diagnostic({
+          severity: "error",
+          code: "delegated-install-protected-path-changed",
+          message: `The delegated installer changed the protected path ${protectedPath}`,
+          path: protectedPath,
+          remediation: "Do not apply this provider until its reviewed write set is updated"
+        })
+      ]
+    });
+  }
+  const changed = /* @__PURE__ */ new Set([...before.keys(), ...after.keys()]);
+  const undeclared = [...changed].map((path) => after.get(path) ?? before.get(path)).find((entry) => entry !== void 0 && !equalTreeEntry(before.get(entry.path), after.get(entry.path)) && !action.expectedArtifacts.some((artifact) => artifact.path === entry.path || entry.kind === "directory" && context.fs.isInside(artifact.path, entry.path)));
+  if (undeclared !== void 0) {
+    return outcome(action, "failed", {
+      snapshots,
+      diagnostics: [
+        diagnostic({
+          severity: "error",
+          code: "delegated-install-undeclared-write",
+          message: `The delegated installer changed an undeclared path inside its containment boundary: ${undeclared.path}`,
+          path: undeclared.path,
+          remediation: "Do not apply this provider until its reviewed write set is updated"
+        })
+      ]
+    });
+  }
+  const missing = action.expectedArtifacts.find((artifact) => after.get(artifact.path)?.kind !== "file" || after.get(artifact.path)?.digest !== artifact.digest);
+  if (missing !== void 0) {
+    return outcome(action, "failed", {
+      snapshots,
+      diagnostics: [
+        diagnostic({
+          severity: "error",
+          code: "delegated-install-artifact-mismatch",
+          message: `The delegated installer did not produce the reviewed artifact ${missing.path}`,
+          path: missing.path,
+          remediation: "Do not apply this provider until its reviewed artifact digests are updated"
+        })
+      ]
+    });
+  }
+  const ownership = [];
+  for (const artifact of action.expectedArtifacts) {
+    ownership.push({
+      kind: "owned-file",
+      path: artifact.path,
+      digest: artifact.digest,
+      mode: (await context.fs.stat(artifact.path))?.mode ?? null
+    });
+  }
+  return outcome(action, "applied", { snapshots, ownership });
+}
 function notImplemented(action) {
   return outcome(action, "failed", {
     diagnostics: [
@@ -2063,9 +2200,10 @@ async function applyAction(action, context) {
       return applyMergeJson(action, context);
     case "package-manager-install":
       return applyPackageManagerInstall(action, context);
+    case "delegated-provider-install":
+      return applyDelegatedProviderInstall(action, context);
     case "download-artifact":
     case "run-installer-command":
-    case "delegated-provider-install":
     case "merge-toml":
     case "merge-yaml":
     case "register-mcp-server":
@@ -2559,23 +2697,25 @@ var TransactionSnapshotStore = class _TransactionSnapshotStore {
     this.taken.push(snapshot);
     return snapshot;
   }
+  captureAbsent(path) {
+    return this.remember({
+      schemaVersion: 1,
+      path,
+      existed: false,
+      wasDirectory: false,
+      digest: null,
+      mode: null,
+      byteLength: null,
+      contentRef: null,
+      capturedAt: this.input.now()
+    });
+  }
   async capture(path) {
     const { fs } = this.input;
     const stat3 = await fs.stat(path);
     const capturedAt = this.input.now();
-    if (stat3 === null) {
-      return this.remember({
-        schemaVersion: 1,
-        path,
-        existed: false,
-        wasDirectory: false,
-        digest: null,
-        mode: null,
-        byteLength: null,
-        contentRef: null,
-        capturedAt
-      });
-    }
+    if (stat3 === null)
+      return this.captureAbsent(path);
     if (stat3.kind === "directory") {
       return this.remember({
         schemaVersion: 1,
@@ -3168,9 +3308,9 @@ async function readLocalDatabase(request) {
     database = new construct(request.path, { readOnly: true });
     const statement = database.prepare(request.sql);
     const raw = statement.all(...request.parameters);
-    const rows = raw.map((row) => {
+    const rows = raw.map((row2) => {
       const mapped = {};
-      for (const [column2, value] of Object.entries(row))
+      for (const [column2, value] of Object.entries(row2))
         mapped[column2] = toValue(value);
       return mapped;
     });
@@ -4447,9 +4587,20 @@ async function inspect(context) {
     diagnostics.push(diagnostic({
       severity: "warning",
       code: "tool-family-not-covered",
-      message: `No configured matcher covers the ${uncoveredToolFamilies.join(", ")} tool ${uncoveredToolFamilies.length === 1 ? "family" : "families"}, so commands routed through ${uncoveredToolFamilies.length === 1 ? "it" : "them"} bypass the pipeline`,
+      subject: CLAUDE,
+      /**
+       * Says whose gap it is, and that the tool is working.
+       *
+       * The first wording — "No configured matcher covers the PowerShell tool family" — read like a
+       * defect in Token Harness on a first run. It is not: the hook in the file below matches some
+       * tool families and not others, Claude Code routes shell commands through more than one on
+       * Windows, and the commands going through the uncovered ones never reach the provider at all.
+       */
+      // Short enough to survive the one-line human rendering without being cut.
+      message: `${uncoveredToolFamilies.join(", ")} has no hook, so those commands are not optimized`,
       path: configs.find((config) => config.configuredPoints.length > 0)?.path ?? null,
-      remediation: "Widen the matcher, or accept the gap and read coverage figures with it in mind"
+      // Short on purpose: a remediation nobody finishes reading is not one.
+      remediation: "Optional. Widen the matcher, or accept the gap"
     }));
   }
   return {
@@ -4743,6 +4894,7 @@ async function inspect2(context) {
     diagnostic({
       severity: "info",
       code: "hook-enablement-unobservable",
+      subject: CODEX,
       message: "Codex declares this hook, but its persisted enablement and trust state cannot be read outside the TUI",
       path: hook.path,
       remediation: "Open Codex and confirm the hook is enabled and trusted after any hook edit"
@@ -5072,6 +5224,15 @@ function listHarnessAdapters() {
 var HARNESSTRIM2 = providerId("harnesstrim");
 var CLAUDE2 = harnessId("claude");
 var CODEX2 = harnessId("codex");
+var CLAUDE_ARTIFACT_DIGESTS = {
+  "compact-handoff/SKILL.md": "sha256:0efbf35581c559359e755b204778b64a289dab4d20dadc1cba3d5b5c995b5f01",
+  "debug-log-slim/SKILL.md": "sha256:17f5ccc34d29d7aba083444e0e4d87fd3d49916ebcb4e6544caf8c89f13f0045",
+  "delegate-bulk/SKILL.md": "sha256:3753de2ad18271c24832e4cda63115d353620515d5d80f40e93bc07d2a7257d7",
+  "delta-response/SKILL.md": "sha256:b6a71f4bdcfcadde3b5242994baa017d0371fe11652dd763f55a2f6d3840cfa8",
+  "delta-response/references/examples.md": "sha256:c67a1f57e63550b396043c3072b7e1a3a0c1522376471f53d6829253339e64e7",
+  "review-delta/SKILL.md": "sha256:4dfbf9d6ec08dff27b4759726536b43928370e288706fa01f5b498648e741388",
+  "scaffold-fast/SKILL.md": "sha256:1a18d52c4d335fbd3f74e2559bc20d6346193a40eef7b85149f51f44f697d182"
+};
 var OPENCODE2 = harnessId("opencode");
 var HOOK_COMMAND_PATTERN = /(^|[\\/\s"'])harnesstrim(\.cmd|\.exe)?([\s"']|$)/i;
 var MANIFEST4 = {
@@ -5157,10 +5318,17 @@ var MANIFEST4 = {
     mode: "legacy",
     locations: [".harnesstrim/metrics.jsonl", "~/.hermes/harnesstrim-metrics.jsonl"]
   },
-  delegatedInstallReview: null
+  delegatedInstallReview: {
+    upstreamVersion: "0.0.7",
+    reviewedWriteSet: [
+      ...Object.keys(CLAUDE_ARTIFACT_DIGESTS).map((path) => `.claude/skills/${path}`)
+    ],
+    containmentBoundary: [".claude", "CLAUDE.md"],
+    upstreamUninstallAvailable: true
+  }
 };
-var TESTED_UPSTREAM = "0.0.5";
-var TESTED_VERSIONS = { minimum: TESTED_UPSTREAM, maximum: TESTED_UPSTREAM };
+var TESTED_UPSTREAM = "0.0.7";
+var TESTED_VERSIONS = { minimum: "0.0.5", maximum: TESTED_UPSTREAM };
 function identifiesCommand(command) {
   return HOOK_COMMAND_PATTERN.test(command);
 }
@@ -5412,7 +5580,7 @@ async function verify4(context) {
   checks.push({
     id: "canary-intercepted",
     status: receipt === null ? "not-exercised" : "pass",
-    summary: receipt === null ? "no telemetry file exists, so no interception has been recorded" : `${String(receipt.operations)} reductions recorded, most recently ${receipt.observedAt}`,
+    summary: receipt === null ? "no telemetry file yet, so nothing has been observed" : `${String(receipt.operations)} reductions recorded, most recently ${receipt.observedAt}`,
     // A recorded reduction is the provider witnessing its own interception, which is what `canary`
     // means in RFC 0007's tier table.
     achievedTier: receipt === null ? null : "canary",
@@ -5571,9 +5739,73 @@ async function collectMetrics(context, store) {
     diagnostics
   };
 }
-async function plan(_context, request) {
-  await Promise.resolve();
-  return { providerId: HARNESSTRIM2, desiredState: request.desiredState, actions: [] };
+async function plan(context, request) {
+  const claudeDirectory = context.fs.join(context.projectRoot, ".claude");
+  const skillsDirectory = context.fs.join(claudeDirectory, "skills");
+  const expectedArtifacts = Object.entries(CLAUDE_ARTIFACT_DIGESTS).map(([path, digest]) => ({
+    path: context.fs.join(skillsDirectory, ...path.split("/")),
+    digest
+  }));
+  if (!request.harnesses.some((harness) => harness.id === CLAUDE2)) {
+    return { providerId: HARNESSTRIM2, desiredState: request.desiredState, actions: [] };
+  }
+  if (request.desiredState === "absent") {
+    const actions = expectedArtifacts.map((artifact) => ({
+      kind: "remove-owned-change",
+      id: `harnesstrim-claude-skill-remove-${digestText(artifact.path).slice(7, 15)}`,
+      riskClass: "reversible",
+      requiresNetwork: false,
+      requiresElevation: false,
+      affectedPaths: [artifact.path],
+      affectedProcesses: [],
+      preconditions: ["the HarnessTrim skill still matches the reviewed 0.0.7 artifact"],
+      postconditions: ["the owned HarnessTrim skill is absent"],
+      rollbackData: "file-snapshot",
+      explanation: `Remove the owned HarnessTrim Claude skill ${context.fs.basename(context.fs.dirname(artifact.path))}`,
+      path: artifact.path,
+      reverses: `harnesstrim-claude-skills-${digestText(context.projectRoot).slice(7, 15)}`,
+      target: { kind: "owned-file", path: artifact.path, digest: artifact.digest, mode: null }
+    }));
+    return { providerId: HARNESSTRIM2, desiredState: "absent", actions };
+  }
+  const installed = await probeExecutable(context);
+  if (installed.version !== TESTED_UPSTREAM) {
+    return { providerId: HARNESSTRIM2, desiredState: "configured", actions: [] };
+  }
+  const review = MANIFEST4.delegatedInstallReview;
+  if (review === null)
+    throw new Error("HarnessTrim delegated-install review is missing");
+  const action = {
+    kind: "delegated-provider-install",
+    id: `harnesstrim-claude-skills-${digestText(context.projectRoot).slice(7, 15)}`,
+    riskClass: "delegated",
+    requiresNetwork: false,
+    requiresElevation: false,
+    affectedPaths: expectedArtifacts.map((artifact) => artifact.path),
+    affectedProcesses: ["harnesstrim"],
+    preconditions: [
+      "harnesstrim 0.0.7 is installed and on PATH",
+      "the reviewed installer writes only the declared Claude skill artifacts"
+    ],
+    postconditions: [
+      "HarnessTrim Claude skills match the reviewed 0.0.7 artifacts",
+      "no HarnessTrim hook or reduce-pipe instruction was added"
+    ],
+    rollbackData: "directory-snapshot",
+    explanation: "Install HarnessTrim Claude skills without a hook or reduce-pipe instruction",
+    executable: "harnesstrim",
+    args: ["install", "claude", context.projectRoot, "--apply", "--no-hook", "--no-instructions"],
+    containmentBoundary: review.containmentBoundary.map((path) => context.fs.join(context.projectRoot, path)),
+    expectedArtifacts,
+    protectedPaths: [
+      context.fs.join(claudeDirectory, "settings.json"),
+      context.fs.join(context.projectRoot, "CLAUDE.md")
+    ],
+    rollbackStrategy: "restore-snapshot",
+    snapshotSizeCapBytes: 1048576,
+    upstreamUninstallAvailable: review.upstreamUninstallAvailable
+  };
+  return { providerId: HARNESSTRIM2, desiredState: "configured", actions: [action] };
 }
 var harnesstrimAdapter = {
   manifest: MANIFEST4,
@@ -5581,7 +5813,8 @@ var harnesstrimAdapter = {
   identifiesCommand,
   verify: verify4,
   collectMetrics,
-  plan
+  plan,
+  plansWithoutOwnership: true
 };
 
 // packages/adapters/dist/src/providers/rtk-plan.js
@@ -6138,17 +6371,17 @@ function rtkDatabasePath(context) {
 function cursorGeneration(low) {
   return `rtk-history:low=${String(low ?? 0)}`;
 }
-function toEvent2(row, context) {
-  const id = numberAt(row, "id");
-  const timestamp = stringAt(row, "timestamp");
-  const before = numberAt(row, "input_tokens");
-  const after = numberAt(row, "output_tokens");
+function toEvent2(row2, context) {
+  const id = numberAt(row2, "id");
+  const timestamp = stringAt(row2, "timestamp");
+  const before = numberAt(row2, "input_tokens");
+  const after = numberAt(row2, "output_tokens");
   if (id === null || timestamp === null || before === null || after === null)
     return null;
   const instant = new Date(timestamp);
   if (Number.isNaN(instant.getTime()))
     return null;
-  const projectPath = stringAt(row, "project_path");
+  const projectPath = stringAt(row2, "project_path");
   return {
     schemaVersion: OPTIMIZATION_EVENT_SCHEMA_VERSION,
     // Native, not synthesized: RFC 0005 prefers the upstream identifier when there is one,
@@ -6292,11 +6525,11 @@ async function collectMetrics2(context, store) {
   const events = [];
   let skipped = 0;
   let highest = from;
-  for (const row of batch.rows) {
-    const id = numberAt(row, "id");
+  for (const row2 of batch.rows) {
+    const id = numberAt(row2, "id");
     if (id !== null && id > highest)
       highest = id;
-    const event = toEvent2(row, context);
+    const event = toEvent2(row2, context);
     if (event === null) {
       skipped += 1;
       continue;
@@ -6435,7 +6668,7 @@ async function computePlan(context) {
   if (providerContext !== null) {
     for (const adapter of providerAdapters) {
       const owned = resolution.ownership.filter((entry) => entry.owner === adapter.manifest.id);
-      if (owned.length === 0)
+      if (owned.length === 0 && adapter.plansWithoutOwnership !== true)
         continue;
       const providerPlan = await adapter.plan(providerContext, {
         ownership: owned,
@@ -7288,7 +7521,7 @@ async function runUpdate(context) {
   for (const adapter of providerAdapters) {
     const detection = await adapter.detect(providerContext);
     const channel = preferredInstallationChannel(adapter.manifest.installationChannels, context.platform.os);
-    const row = {
+    const row2 = {
       providerId: adapter.manifest.id,
       installed: detection.version,
       available: null,
@@ -7297,24 +7530,24 @@ async function runUpdate(context) {
       pin: pins.pins.get(adapter.manifest.id) ?? null
     };
     if (detection.state === "absent") {
-      row.verdict = "not-installed";
-      report.providers.push(row);
+      row2.verdict = "not-installed";
+      report.providers.push(row2);
       continue;
     }
-    if (row.pin !== null) {
-      row.verdict = "pinned";
-      report.providers.push(row);
+    if (row2.pin !== null) {
+      row2.verdict = "pinned";
+      report.providers.push(row2);
       diagnostics.push(diagnostic({
         severity: "info",
         code: "provider-pinned",
-        message: `${adapter.manifest.id} is pinned at ${row.pin}, so no update was planned for it`,
+        message: `${adapter.manifest.id} is pinned at ${row2.pin}, so no update was planned for it`,
         remediation: `Remove it from the pin file to allow updates`
       }));
       continue;
     }
     if (channel === null) {
-      row.verdict = "no-channel";
-      report.providers.push(row);
+      row2.verdict = "no-channel";
+      report.providers.push(row2);
       continue;
     }
     const packageName = channel.packageId ?? adapter.manifest.id;
@@ -7327,21 +7560,21 @@ async function runUpdate(context) {
     diagnostics.push(...query.diagnostics);
     if (query.destination !== null)
       destinations.add(query.destination);
-    row.available = query.version;
+    row2.available = query.version;
     if (query.status !== "found" || query.version === null) {
-      row.verdict = query.status === "unknown" ? "unknown" : "unavailable";
-      report.providers.push(row);
+      row2.verdict = query.status === "unknown" ? "unknown" : "unavailable";
+      report.providers.push(row2);
       continue;
     }
     const installed = detection.version === null ? null : parseSemanticVersion(detection.version);
     const offered = parseSemanticVersion(query.version);
     if (installed === null || offered === null || compareVersions(offered, installed) <= 0) {
-      row.verdict = "current";
-      report.providers.push(row);
+      row2.verdict = "current";
+      report.providers.push(row2);
       continue;
     }
-    row.verdict = "upgradable";
-    report.providers.push(row);
+    row2.verdict = "upgradable";
+    report.providers.push(row2);
     actions.push(upgradeAction({
       providerId: adapter.manifest.id,
       channel: channel.id,
@@ -7556,11 +7789,52 @@ function statusFor(achieved, declared) {
 }
 
 // apps/cli/dist/src/render/layout.js
+var MAX_WIDTH = 78;
+function wrap(text, indent, width = MAX_WIDTH) {
+  const limit = Math.max(20, width - indent);
+  const words = text.split(/\s+/).filter((word) => word !== "");
+  if (words.length === 0)
+    return [];
+  const lines = [];
+  let current = "";
+  for (const word of words) {
+    if (current === "") {
+      current = word;
+      continue;
+    }
+    if (`${current} ${word}`.length <= limit) {
+      current = `${current} ${word}`;
+      continue;
+    }
+    lines.push(current);
+    current = word;
+  }
+  lines.push(current);
+  const pad = " ".repeat(indent);
+  return lines.map((line, index) => index === 0 ? pad + line : pad + line);
+}
 function column(value, width, minimumGutter = 2) {
   if (value.length >= width)
     return value + " ".repeat(minimumGutter);
   return value.padEnd(width, " ");
 }
+function truncate(value, width) {
+  const characters = [...value];
+  if (characters.length <= width)
+    return value;
+  return `${characters.slice(0, Math.max(1, width - 1)).join("").trimEnd()}\u2026`;
+}
+var COLUMN_SEPARATOR = " - ";
+function row(cells) {
+  const rendered = cells.map(([value, width], index) => index === cells.length - 1 ? value : column(value, width, 0));
+  return rendered.join(COLUMN_SEPARATOR);
+}
+function truncatePath(value, width) {
+  const characters = [...value];
+  if (characters.length <= width)
+    return value;
+  return `\u2026${characters.slice(characters.length - (width - 1)).join("")}`;
+}
 function rightAlign(value, width) {
   return value.padStart(width, " ");
 }
@@ -7639,7 +7913,7 @@ var HEADERS = {
   rollback: "Rollback",
   uninstall: "Uninstall"
 };
-function renderApplyReport(report, _context, command = "apply") {
+function renderApplyReport(report, context, command = "apply") {
   const lines = [];
   const header = [HEADERS[command] ?? "Apply"];
   header.push(report.planId === null ? "no plan" : `plan ${report.planId}`);
@@ -7652,14 +7926,20 @@ function renderApplyReport(report, _context, command = "apply") {
   if (report.results.length > 0) {
     lines.push("Actions");
     for (const [index, result] of report.results.entries()) {
-      lines.push(`  ${String(index + 1)}. ${column(result.kind, KIND_WIDTH)}${column(result.status, STATUS_WIDTH)}${result.path ?? ""}`);
+      lines.push(`  ${String(index + 1)}. ${row([
+        [result.kind, KIND_WIDTH],
+        [result.status, STATUS_WIDTH],
+        // Abbreviated: an absolute Windows path under a long account name ran past 140
+        // characters, and `~/` is both shorter and what every other command shows.
+        [result.path === null ? "" : displayPath(result.path, context.home), 0]
+      ])}`);
     }
     lines.push("");
   }
   if (report.unrestored.length > 0) {
     lines.push("Not restored");
     for (const path of report.unrestored)
-      lines.push(`  ${path}`);
+      lines.push(`  ${displayPath(path, context.home)}`);
     lines.push("");
   }
   lines.push((OUTCOME_LINES[command] ?? OUTCOME_LINES["apply"])?.[report.outcome] ?? "");
@@ -7667,57 +7947,133 @@ function renderApplyReport(report, _context, command = "apply") {
 }
 
 // apps/cli/dist/src/render/doctor.js
-var HARNESS_ID_WIDTH = 12;
-var HARNESS_STATE_WIDTH = 12;
-var PROVIDER_ID_WIDTH = 14;
-var PROVIDER_STATE_WIDTH = 14;
-var PROVIDER_VERSION_WIDTH = 8;
-function harnessDetail(detection, context) {
-  if (detection.configPath === null)
-    return "";
-  return displayPath(detection.configPath, context.home);
-}
-function providerNote(detection) {
-  if (detection.state === "broken") {
-    return "installed but not usable";
-  }
-  if (detection.state === "absent" || detection.state === "available") {
-    return "";
-  }
-  if (detection.configuredHarnesses.length === 0) {
-    const qualifier = detection.supportsUnmanagedHarnesses ? "managed harness" : "harness";
-    return `not configured for any ${qualifier}`;
+var NAME_WIDTH = 15;
+var STATE_WIDTH = 12;
+var VERSION_WIDTH = 10;
+var WIRED_WIDTH = 14;
+function harnessState(detection) {
+  switch (detection.state) {
+    case "absent":
+      return "not found";
+    case "detected":
+      return "no hooks";
+    case "configured":
+      return "hooks";
+    case "broken":
+      return "unreadable";
+  }
+}
+function wiredTo(detection) {
+  if (detection.state === "broken")
+    return "cannot run";
+  if (detection.state === "absent")
+    return "not installed";
+  if (detection.configuredHarnesses.length === 0)
+    return "nothing yet";
+  return detection.configuredHarnesses.join(", ");
+}
+function setUpBy(detection) {
+  if (detection.state === "absent" || detection.configuredHarnesses.length === 0)
+    return "\u2014";
+  return detection.managedByTokenHarness ? "this tool" : "you";
+}
+function notes(report) {
+  const lines = [];
+  for (const harness of report.harnesses) {
+    if (harness.state === "broken") {
+      lines.push(`  ${row([
+        [harness.harnessId, NAME_WIDTH - 2],
+        ["configuration could not be read", 0]
+      ])}`);
+    }
+    if (harness.versionVerdict === "unknown-newer") {
+      lines.push(`  ${row([
+        [harness.harnessId, NAME_WIDTH - 2],
+        [`${harness.version ?? ""} is newer than any tested version`, 0]
+      ])}`);
+    }
+  }
+  for (const provider of report.providers) {
+    if (provider.state === "broken") {
+      lines.push(`  ${row([
+        [provider.providerId, NAME_WIDTH - 2],
+        ["installed but could not be run", 0]
+      ])}`);
+    }
+    if (provider.versionVerdict === "unknown-newer") {
+      lines.push(`  ${row([
+        [provider.providerId, NAME_WIDTH - 2],
+        [`${provider.version ?? ""} is newer than any tested version`, 0]
+      ])}`);
+    }
   }
-  const list = detection.configuredHarnesses.join(", ");
-  const adopted = detection.managedByTokenHarness ? "" : " (adopted, not managed)";
-  return `configured for ${list}${adopted}`;
+  return lines;
 }
 function renderDoctorReport(report, context) {
   const lines = [];
   lines.push(`Token Harness ${context.toolVersion} \u2014 ${renderPlatformSummary(report.platform)}, Node ${report.platform.nodeVersion}`);
   lines.push("");
-  lines.push("Harnesses");
+  lines.push(`  ${row([
+    ["HARNESSES", NAME_WIDTH - 2],
+    ["STATE", STATE_WIDTH],
+    ["CONFIG FILE", 0]
+  ])}`);
   if (report.harnesses.length === 0) {
-    lines.push("  no harness adapters registered");
+    lines.push("  none registered");
   } else {
     for (const harness of report.harnesses) {
-      lines.push(`  ${column(harness.harnessId, HARNESS_ID_WIDTH)}${column(harness.state, HARNESS_STATE_WIDTH)}${harnessDetail(harness, context)}`);
+      lines.push(`  ${row([
+        [harness.harnessId, NAME_WIDTH - 2],
+        [harnessState(harness), STATE_WIDTH],
+        [
+          harness.configPath === null ? "" : (
+            // The columns before this one, plus their separators, consume a fixed prefix; the
+            // path gets what is left and is cut from the left so the file name survives.
+            truncatePath(displayPath(harness.configPath, context.home), MAX_WIDTH - (2 + NAME_WIDTH - 2 + 3 + STATE_WIDTH + 3))
+          ),
+          0
+        ]
+      ])}`);
     }
   }
   lines.push("");
-  lines.push("Providers");
+  lines.push(`  ${row([
+    ["PROVIDERS", NAME_WIDTH - 2],
+    ["VERSION", VERSION_WIDTH],
+    ["WIRED TO", WIRED_WIDTH],
+    ["SET UP BY", 0]
+  ])}`);
   if (report.providers.length === 0) {
-    lines.push("  no provider adapters registered");
+    lines.push("  none registered");
   } else {
     for (const provider of report.providers) {
-      lines.push(`  ${column(provider.providerId, PROVIDER_ID_WIDTH)}${column(provider.state, PROVIDER_STATE_WIDTH)}${column(provider.version ?? "", PROVIDER_VERSION_WIDTH)}${providerNote(provider)}`);
+      lines.push(`  ${row([
+        [provider.providerId, NAME_WIDTH - 2],
+        [provider.version ?? "-", VERSION_WIDTH],
+        [wiredTo(provider), WIRED_WIDTH],
+        [setUpBy(provider), 0]
+      ])}`);
     }
   }
+  const notable = notes(report);
+  if (notable.length > 0) {
+    lines.push("");
+    lines.push("NOTES");
+    lines.push(...notable);
+  }
+  const unwired = report.providers.filter((provider) => provider.state !== "absent" && provider.configuredHarnesses.length === 0);
   lines.push("");
-  if (report.problemCount === 0) {
-    lines.push("Nothing is broken. Run `token-harness plan` to see what would change.");
-  } else {
-    lines.push(`${report.problemCount} ${pluralize(report.problemCount, "problem")} found. Fix ${pluralize(report.problemCount, "it", "them")} before running \`token-harness plan\`.`);
+  lines.push("NEXT");
+  const suggestions = report.providers.every((provider) => provider.state === "absent") || unwired.length > 0 ? [["token-harness plan", "see what would change \u2014 writes nothing"]] : [
+    ["token-harness verify", "check the pipeline actually intercepts"],
+    ["token-harness metrics --since 7d", "see what it saved"]
+  ];
+  const commandWidth = Math.max(...suggestions.map(([command]) => command.length));
+  for (const [command, description] of suggestions) {
+    lines.push(`  ${row([
+      [command, commandWidth],
+      [description, 0]
+    ])}`);
   }
   return document(lines);
 }
@@ -7725,11 +8081,10 @@ function renderDoctorReport(report, context) {
 // apps/cli/dist/src/render/metrics.js
 var CLASS_LABEL_WIDTH = 23;
 var FIGURE_BLOCK_GUTTER = 4;
-var PROVIDER_ID_WIDTH2 = 15;
-var PROVIDER_SAVED_WIDTH = 23;
-var PROVIDER_CLASS_WIDTH = 17;
-var PROVIDER_OPERATIONS_WIDTH = 19;
-var PROVIDER_CONTINUATION_INDENT = 2 + PROVIDER_ID_WIDTH2;
+var PROVIDER_ID_WIDTH = 13;
+var PROVIDER_SAVED_WIDTH = 21;
+var PROVIDER_CLASS_WIDTH = 15;
+var PROVIDER_CONTINUATION_INDENT = 2 + PROVIDER_ID_WIDTH;
 var CLASS_LABELS = {
   "exact-local": "Exact local",
   "estimated-local": "Estimated local",
@@ -7737,21 +8092,21 @@ var CLASS_LABELS = {
   "end-to-end-billed": "End-to-end billed"
 };
 function renderClassRows(report) {
-  const byClass = new Map(report.classes.map((row) => [row.class, row]));
-  const ordered = MEASUREMENT_CLASSES.map((id) => byClass.get(id)).filter((row) => row !== void 0);
-  const withFigures = ordered.filter((row) => row.before !== null && row.after !== null);
-  const beforeWidth = Math.max(0, ...withFigures.map((row) => formatCount(row.before).length));
-  const afterWidth = Math.max(0, ...withFigures.map((row) => formatCount(row.after).length));
-  const blocks = ordered.map((row) => {
-    if (row.before === null || row.after === null)
+  const byClass = new Map(report.classes.map((row2) => [row2.class, row2]));
+  const ordered = MEASUREMENT_CLASSES.map((id) => byClass.get(id)).filter((row2) => row2 !== void 0);
+  const withFigures = ordered.filter((row2) => row2.before !== null && row2.after !== null);
+  const beforeWidth = Math.max(0, ...withFigures.map((row2) => formatCount(row2.before).length));
+  const afterWidth = Math.max(0, ...withFigures.map((row2) => formatCount(row2.after).length));
+  const blocks = ordered.map((row2) => {
+    if (row2.before === null || row2.after === null)
       return "";
-    return `${rightAlign(formatCount(row.before), beforeWidth)} -> ${rightAlign(formatCount(row.after), afterWidth)} ${row.unit ?? ""}`;
+    return `${rightAlign(formatCount(row2.before), beforeWidth)} -> ${rightAlign(formatCount(row2.after), afterWidth)} ${row2.unit ?? ""}`;
   });
   const blockWidth = Math.max(0, ...blocks.map((block) => block.length)) + FIGURE_BLOCK_GUTTER;
-  return ordered.map((row, index) => {
-    const label = column(CLASS_LABELS[row.class], CLASS_LABEL_WIDTH);
+  return ordered.map((row2, index) => {
+    const label = column(CLASS_LABELS[row2.class], CLASS_LABEL_WIDTH);
     const block = (blocks[index] ?? "").padEnd(blockWidth, " ");
-    const tail = row.saved === null ? row.note ?? "" : `saved ${formatCount(row.saved)}`;
+    const tail = row2.saved === null ? row2.note ?? "" : `saved ${formatCount(row2.saved)}`;
     return `${label}${block}${tail}`;
   });
 }
@@ -7769,14 +8124,21 @@ function renderMetricsReport(report, _context) {
     lines.push("  no provider reported a measurable saving in this window");
   } else {
     for (const provider of report.providers) {
-      lines.push(`  ${column(provider.providerId, PROVIDER_ID_WIDTH2)}${column(`saved ${formatCount(provider.saved)} ${provider.unit}`, PROVIDER_SAVED_WIDTH)}${column(provider.class, PROVIDER_CLASS_WIDTH)}${column(`${formatCount(provider.operations)} operations`, PROVIDER_OPERATIONS_WIDTH)}${provider.harnesses.join(", ")}`);
-      const notes = [];
+      lines.push(`  ${row([
+        [provider.providerId, PROVIDER_ID_WIDTH],
+        [`saved ${formatCount(provider.saved)} ${provider.unit}`, PROVIDER_SAVED_WIDTH],
+        [provider.class, PROVIDER_CLASS_WIDTH],
+        [`${formatCount(provider.operations)} operations`, 0]
+      ])}`);
+      const notes2 = [];
+      if (provider.harnesses.length > 0)
+        notes2.push(`on ${provider.harnesses.join(", ")}`);
       if (!provider.managedByTokenHarness)
-        notes.push("adopted, not managed");
+        notes2.push("set up by you");
       if (provider.adapterMode !== null)
-        notes.push(`adapter mode ${provider.adapterMode}`);
-      if (notes.length > 0) {
-        lines.push(`${" ".repeat(PROVIDER_CONTINUATION_INDENT)}${notes.join(" \u2014 ")}`);
+        notes2.push(`mode ${provider.adapterMode}`);
+      if (notes2.length > 0) {
+        lines.push(`${" ".repeat(PROVIDER_CONTINUATION_INDENT)}${notes2.join(" \u2014 ")}`);
       }
     }
   }
@@ -7808,8 +8170,8 @@ function renderConflicts(report) {
       lines.push("");
     lines.push(`  ${column("conflict", CONFLICT_LABEL_WIDTH)}${conflict.code}`);
     for (const detail2 of conflict.detail)
-      lines.push(`    ${detail2}`);
-    lines.push(`    Fix: ${conflict.remediation}`);
+      lines.push(...wrap(detail2, 4));
+    lines.push(...wrap(`Fix: ${conflict.remediation}`, 4));
   }
   lines.push("");
   lines.push("No plan was produced.");
@@ -7852,13 +8214,24 @@ function renderPlanReport(report, context) {
   if (report.exclusions.length > 0) {
     lines.push("");
     lines.push("Excluded");
+    const grouped = /* @__PURE__ */ new Map();
     for (const exclusion of report.exclusions) {
-      const [first = "", ...rest] = exclusion.reason;
-      lines.push(`  ${column(exclusion.excluded, EXCLUSION_PROVIDER_WIDTH)}${column(exclusion.scope.capability, EXCLUSION_CAPABILITY_WIDTH)}${first}`);
-      for (const line of rest) {
-        lines.push(`${" ".repeat(EXCLUSION_CONTINUATION_INDENT)}${line}`);
+      const key = `${exclusion.excluded}\0${exclusion.scope.capability}`;
+      const existing = grouped.get(key);
+      if (existing === void 0) {
+        grouped.set(key, {
+          capability: exclusion.scope.capability,
+          harnesses: [exclusion.scope.harness]
+        });
+      } else if (!existing.harnesses.includes(exclusion.scope.harness)) {
+        existing.harnesses.push(exclusion.scope.harness);
       }
     }
+    for (const [key, entry] of grouped) {
+      const provider = key.slice(0, key.indexOf("\0"));
+      lines.push(`  ${column(provider, EXCLUSION_PROVIDER_WIDTH)}${column(entry.capability, EXCLUSION_CAPABILITY_WIDTH)}${entry.harnesses.join(", ")}`);
+      lines.push(...wrap("its installer cannot produce this in isolation, so it is measured but not given the scope", EXCLUSION_CONTINUATION_INDENT));
+    }
   }
   lines.push("");
   lines.push("Actions");
@@ -7934,22 +8307,22 @@ var VERDICT_WIDTH = 15;
 function widthOf(values, floor) {
   return Math.max(floor, ...values.map((value) => value.length + 2));
 }
-function detail(row) {
-  switch (row.verdict) {
+function detail(row2) {
+  switch (row2.verdict) {
     case "upgradable":
-      return `${String(row.installed)} \u2192 ${String(row.available)} via ${String(row.channel)}`;
+      return `${String(row2.installed)} \u2192 ${String(row2.available)} via ${String(row2.channel)}`;
     case "current":
-      return `${String(row.installed)} is the newest ${String(row.channel)} offers`;
+      return `${String(row2.installed)} is the newest ${String(row2.channel)} offers`;
     case "pinned":
-      return `held at ${String(row.pin)} by a pin`;
+      return `held at ${String(row2.pin)} by a pin`;
     case "not-installed":
       return "not installed, so there is nothing to update";
     case "no-channel":
       return "no installation channel on this platform";
     case "unknown":
-      return `${String(row.channel)} answered without a version this build can read`;
+      return `${String(row2.channel)} answered without a version this build can read`;
     case "unavailable":
-      return `${String(row.channel)} could not be asked`;
+      return `${String(row2.channel)} could not be asked`;
   }
 }
 function renderUpdateReport(report, _context) {
@@ -7958,16 +8331,20 @@ function renderUpdateReport(report, _context) {
     lines.push("No provider was inspected.");
     return document(lines);
   }
-  const providerWidth = widthOf(report.providers.map((row) => row.providerId), PROVIDER_WIDTH);
-  const verdictWidth = widthOf(report.providers.map((row) => row.verdict), VERDICT_WIDTH);
-  for (const row of report.providers) {
-    lines.push(`${column(row.providerId, providerWidth)}${column(row.verdict, verdictWidth)}${detail(row)}`);
+  const providerWidth = Math.min(20, widthOf(report.providers.map((entry) => entry.providerId), PROVIDER_WIDTH));
+  const detailStart = providerWidth + 3 + VERDICT_WIDTH + 3;
+  for (const entry of report.providers) {
+    lines.push(truncate(row([
+      [entry.providerId, providerWidth],
+      [entry.verdict, VERDICT_WIDTH],
+      [truncate(detail(entry), MAX_WIDTH - detailStart), 0]
+    ]), MAX_WIDTH));
   }
   if (report.network.length > 0) {
     lines.push("");
     lines.push(`Network: ${report.network.join(", ")}`);
   }
-  const upgradable = report.providers.filter((row) => row.verdict === "upgradable").length;
+  const upgradable = report.providers.filter((row2) => row2.verdict === "upgradable").length;
   const execution = report.execution;
   lines.push("");
   if (execution === null || execution.outcome === "nothing-to-do") {
@@ -7983,33 +8360,34 @@ function renderUpdateReport(report, _context) {
 }
 
 // apps/cli/dist/src/render/verify.js
-var CHECK_STATUS_WIDTH = 6;
-var CHECK_ID_WIDTH = 27;
-function statusWidth(report) {
-  const longest = Math.max(0, ...report.results.flatMap((result) => result.checks.map((check) => check.status.length)));
-  return Math.max(CHECK_STATUS_WIDTH, longest + 2);
+var STATUS_WIDTH2 = 16;
+var CHECK_WIDTH = 12;
+function shortCheck(id) {
+  return truncate(id.replace(/-resolves$|-registered$|-intercepted$/, ""), CHECK_WIDTH);
 }
 function renderVerifyReport(report, _context) {
   const lines = [];
-  const width = statusWidth(report);
-  lines.push(report.receiptId === null || report.appliedAt === null ? "No receipt \u2014 verifying the live configuration" : `Receipt ${report.receiptId} \u2014 applied ${report.appliedAt}`);
-  lines.push("");
+  lines.push(report.receiptId === null || report.appliedAt === null ? "No receipt: verifying what is on the machine now" : `Receipt ${report.receiptId} \u2014 applied ${report.appliedAt}`);
   for (const result of report.results) {
-    const header = [result.providerId, result.harnessId];
-    if (!result.managedByTokenHarness)
-      header.push("adopted, not managed");
-    header.push(`declared tier: ${result.declaredTier}`);
-    lines.push(header.join(" \u2014 "));
+    lines.push("");
+    lines.push(`${result.providerId} on ${result.harnessId} \u2014 set up by ${result.managedByTokenHarness ? "this tool" : "you"}, tier ${result.declaredTier}`);
     for (const check of result.checks) {
-      lines.push(`  ${column(check.status, width)}${column(check.id, CHECK_ID_WIDTH)}${check.summary}`);
+      const indent = 2 + CHECK_WIDTH + 3 + STATUS_WIDTH2 + 3;
+      const wrapped = wrap(check.summary, indent);
+      lines.push(`  ${row([
+        [shortCheck(check.id), CHECK_WIDTH],
+        [check.status, STATUS_WIDTH2],
+        [(wrapped[0] ?? "").trimStart(), 0]
+      ])}`);
+      lines.push(...wrapped.slice(1));
     }
   }
   lines.push("");
   if (report.healthyAtDeclaredTier) {
-    lines.push("Pipeline healthy at the declared tier for every provider.");
+    lines.push("Healthy at the declared tier for every provider.");
   } else {
     const failures = report.results.flatMap((result) => result.checks).filter((check) => check.status === "fail").length;
-    lines.push(`${failures} ${pluralize(failures, "check")} below the declared tier. The pipeline is not proven.`);
+    lines.push(`${String(failures)} ${pluralize(failures, "check")} below tier. Not proven.`);
   }
   return document(lines);
 }
@@ -8053,27 +8431,37 @@ function renderHuman(result, context) {
 }
 
 // apps/cli/dist/src/usage.js
-var ROOT_USAGE = `token-harness \u2014 one control plane for token-efficient coding agents
+var ROOT_USAGE = `token-harness \u2014 set up and measure token-saving tools for coding agents
+
+First time here
+  1  token-harness doctor        what is on this machine        writes nothing
+  2  token-harness plan          what would change              writes nothing
+  3  token-harness apply --yes   make those changes             WRITES
+  4  token-harness verify        is it actually intercepting    writes nothing
+  5  token-harness metrics       what it saved                  writes nothing
+
+  Steps 1 and 2 are safe to run right now. Nothing changes until step 3.
 
 Usage
   token-harness <command> [flags]
+  token-harness help <command>
 
-Commands
-  apply       Execute a plan inside a reversible transaction
-  doctor      Report detected harnesses and providers
-  metrics     Import provider records and report savings by measurement class
-  plan        Compute a dry-run plan; nothing is changed
+Commands, in the order you would use them
+  doctor      What is installed, what is wired up, what is worth knowing
+  plan        Compute what would change, file by file. Changes nothing
+  apply       Run that plan inside a transaction that can be rolled back
+  verify      Check the pipeline actually intercepts, at its declared tier
+  metrics     Report what was saved, labelled with how it was measured
   status      Report applied pipelines, drift, and importer modes
-  verify      Check that an integration actually intercepts, at its declared tier
-  rollback    Restore the files a transaction changed, as they were before it
-  uninstall   Remove what Token Harness owns, leaving everything else
-  update      Update the installed providers to what their channel offers
+  update      Update installed providers to what their channel offers
+  rollback    Restore the files a transaction changed, as they were before
+  uninstall   Remove what Token Harness set up, leaving everything else
 
 Flags
   --json               Emit one machine-readable envelope on stdout
   --harness <id>       Restrict the operation to one harness
   --provider <id>      Restrict the operation to one provider
-  --project <dir>      Operate on that project instead of the current directory
+  --project <dir>      Use that project instead of the current directory
   --since <window>     Report from this point: a duration like 7d, or a date
   --until <window>     Report up to this point; defaults to now
   --plan <id>          Apply a previously computed plan by id
@@ -8081,8 +8469,8 @@ Flags
   --version            Print the version and exit 0
   --help               Print usage and exit 0
 
-Mutating commands are dry-run by default and there is no flag that skips
-planning. Exit codes and the JSON envelope are specified in RFC 0006.`;
+Only apply, update, rollback and uninstall change anything, and none of
+them do without --yes. Exit codes and JSON are specified in RFC 0006.`;
 var COMMAND_USAGE = {
   apply: `token-harness apply \u2014 execute a plan inside a reversible transaction
 
@@ -8221,7 +8609,7 @@ function usageText(topic) {
 }
 
 // apps/cli/dist/src/version.js
-var TOOL_VERSION = "0.1.0";
+var TOOL_VERSION = "0.1.1";
 
 // apps/cli/dist/src/run.js
 var DEFAULT_COMMANDS = {
@@ -8235,12 +8623,31 @@ var DEFAULT_COMMANDS = {
   update: runUpdate,
   verify: runVerify
 };
-function formatDiagnostic(entry) {
-  const lines = [`${entry.severity}  ${entry.code}: ${entry.message}`];
-  if (entry.path !== null)
-    lines.push(`       ${entry.path}`);
-  if (entry.remediation !== null)
-    lines.push(`       Fix: ${entry.remediation}`);
+var SUBJECT_WIDTH = 12;
+function diagnosticLine(entry) {
+  const label = entry.subject ?? entry.code;
+  return truncate(`  ${row([
+    [label, SUBJECT_WIDTH],
+    [entry.message, 0]
+  ])}`, MAX_WIDTH);
+}
+function formatDiagnostics(diagnostics) {
+  const errors = diagnostics.filter((entry) => entry.severity === "error");
+  const warnings = diagnostics.filter((entry) => entry.severity === "warning");
+  if (errors.length === 0 && warnings.length === 0)
+    return "";
+  const lines = [];
+  for (const [title, group] of [
+    ["ERRORS", errors],
+    ["WARNINGS", warnings]
+  ]) {
+    if (group.length === 0)
+      continue;
+    lines.push("");
+    lines.push(title);
+    for (const entry of group)
+      lines.push(diagnosticLine(entry));
+  }
   return `${lines.join("\n")}
 `;
 }
@@ -8282,8 +8689,9 @@ function emit(result, options, renderContext, json) {
   const rendering = renderHuman(result, renderContext);
   if (rendering.report !== "")
     options.streams.out(rendering.report);
-  for (const entry of rendering.stderrDiagnostics)
-    options.streams.err(formatDiagnostic(entry));
+  const diagnostics = formatDiagnostics(rendering.stderrDiagnostics);
+  if (diagnostics !== "")
+    options.streams.err(diagnostics);
   return result.exitCode;
 }
 function emitHelpOrVersion(invocation, options) {