@tokenoftrust/cli 2.0.12 → 2.0.14

package/bin/tot.mjs

@@ -21,6 +21,12 @@ import { printError } from "../src/errors.mjs";
 import { recordActivity, redactArgs } from "../src/activity-log.mjs";
 import { emitActivity, capRendered } from "../src/activity.mjs";
 import { maybeNotifyUpdate } from "../src/update-check.mjs";
+import {
+  currentInvocationDiagnostics,
+  hasRequiredInvocationDiagnostic,
+  recordDiagnostic,
+  resetInvocationDiagnostics,
+} from "../src/diagnostics.mjs";
 
 const BUILD_ORDER = ["clone", "validate", "dev", "preview"];
 
@@ -305,6 +311,7 @@ async function main() {
   const ctx = detectContext();
   const startedAt = Date.now();
   const command = cmd || "(none)";
+  resetInvocationDiagnostics({ command, cliVersion: VERSION });
   const subcommand = safeSubcommand(cmd, rest);
   let code = 0;
   let errMsg = null;
@@ -323,10 +330,18 @@ async function main() {
     return code;
   } catch (e) {
     errMsg = e?.message || String(e);
+    recordDiagnostic(e, { command, operation: command, cliVersion: VERSION, required: true });
     throw e;
   } finally {
-    const exitCode = errMsg ? 1 : (code ?? 0);
+    const exitCode = errMsg ? 1 : (Number.isInteger(code) ? code : 0);
     const durationMs = Date.now() - startedAt;
+    if (exitCode !== 0 && !hasRequiredInvocationDiagnostic()) {
+      recordDiagnostic(new Error(errMsg || `command exited ${exitCode}`), {
+        command, operation: command, category: "handled_exit", required: true,
+      });
+    }
+    const diagnostics = currentInvocationDiagnostics();
+    const diagnosticIds = diagnostics.map((entry) => entry.diagnosticId).filter(Boolean);
     // Best-effort activity breadcrumb (never throws, never blocks). `feedback`'s own
     // free-text message is omitted — it's user-typed and belongs only in the report.
     recordActivity({
@@ -337,6 +352,7 @@ async function main() {
       code: exitCode,
       ms: durationMs,
       ...(errMsg ? { err: String(errMsg).slice(0, 200) } : {}),
+      ...(diagnosticIds.length ? { diagnosticId: diagnosticIds.at(-1), diagnosticIds } : {}),
     });
     // Emit `cli.command.result` (exit code + duration + a bounded/redacted
     // rendered field). The house-style error text is capped + run through the JS
@@ -347,9 +363,12 @@ async function main() {
     // when there's no credential.
     const resultEmit = emitActivity({
       action: "cli.command.result",
-      outcome: { status: errMsg ? "failed" : "succeeded", durationMs },
+      outcome: { status: exitCode === 0 ? "succeeded" : "failed", durationMs },
       payload: {
-        args: { command, ...(subcommand ? { subcommand } : {}), cliVersion: VERSION, exitCode, durationMs },
+        args: {
+          command, ...(subcommand ? { subcommand } : {}), cliVersion: VERSION,
+          exitCode, durationMs, ...(diagnosticIds.length ? { diagnosticId: diagnosticIds.at(-1) } : {}),
+        },
         ...(errMsg ? { rendered: { output: capRendered(errMsg) } } : {}),
       },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/cli",
-  "version": "2.0.12",
+  "version": "2.0.14",
   "description": "Token of Trust developer CLI — clone a tenant store, run it locally with save→reload, and submit it for preview. Installs the `tot` command.",
   "license": "Apache-2.0",
   "author": "Token of Trust",

package/src/activity-log.mjs

@@ -4,7 +4,8 @@
  * (sent through the Token of Trust MCP's `feedback_submit` tool).
  *
  * ONE file, `~/.tot/activity.log` (JSON-lines), beside the credential cache. Each
- * line is one command invocation: { ts, v, cmd, args, code, ms, err? }. Bounded to
+ * line is one command invocation: { ts, v, cmd, args, code, ms, err?, diagnosticId?,
+ * diagnosticIds? }. Bounded to
  * the most recent MAX_ENTRIES so it never grows without limit.
  *
  * NEVER records secrets: the value after `--code` / `--token` (the single-use

package/src/activity.mjs

@@ -63,7 +63,7 @@ export const CLI_ACTION_CATALOG = {
     renderedAllow: [],
   },
   "cli.command.result": {
-    argsAllow: ["command", "subcommand", "cliVersion", "exitCode", "durationMs"],
+    argsAllow: ["command", "subcommand", "cliVersion", "exitCode", "durationMs", "diagnosticId"],
     renderedAllow: [],
   },
   "cli.obstacle.reported": {

package/src/commands/clone.mjs

@@ -55,6 +55,7 @@ import { CliError, fail, formatError } from "../errors.mjs";
 import { writeNvmrc } from "../sample.mjs";
 import { emitObstacle } from "../obstacle.mjs";
 import { splitAuthedRemote, basicAuthExtraHeader, installForgeCredentialHelper } from "../git-credential.mjs";
+import { recordDiagnostic } from "../diagnostics.mjs";
 
 const execFileP = promisify(execFile);
 
@@ -364,6 +365,7 @@ async function cloneRepo(gitRemote, dir, redact) {
     await emitObstacle("clone-failed");
     throw new CliError(`clone failed: ${redact(String(e.stderr || e.message || e))}`, {
       next: `check the target dir is empty and you can reach the remote, then re-run`,
+      cause: e,
     });
   }
   // Install the HOST-SCOPED helper, not a bare `credential.helper`. A bare one is appended to
@@ -376,9 +378,12 @@ async function cloneRepo(gitRemote, dir, redact) {
     const gitSync = (/** @type {string[]} */ cargs) =>
       execFileSync("git", ["-C", dir, ...cargs], { encoding: "utf8" });
     installForgeCredentialHelper(gitSync, { host: new URL(gitRemote).host });
-  } catch {
+  } catch (error) {
     // Best-effort — never fail a good clone over credential plumbing. The next
     // `tot preview`/`tot sync` installs it, and the fetch that needs it says why.
+    recordDiagnostic(error, {
+      command: "clone", operation: "credential_helper_install", required: false, degraded: true,
+    });
   }
   const head = (await git(["-C", dir, "log", "-1", "--oneline"])).trim();
   writeNvmrc(dir); // version-manager hooks land on a supported Node on cd

package/src/commands/dev.mjs

@@ -53,6 +53,7 @@ import {
 import { startHeartbeatFromEnv } from "../dev-heartbeat.mjs";
 import { streamDevLogs } from "../dev-logs.mjs";
 import { cockpitUrlFrom } from "../banner.mjs";
+import { recordDiagnostic } from "../diagnostics.mjs";
 
 /** The published runner image (--docker fallback). Override with --image / TOT_DEV_IMAGE. */
 const DEFAULT_DEV_IMAGE =
@@ -874,7 +875,10 @@ export function probeRunnerVersion(runnerDir, { timeoutMs = 4000 } = {}) {
     });
     const v = String(out).trim().split(/\s+/)[0];
     return /^\d+\.\d+\.\d+/.test(v) ? v : null;
-  } catch {
+  } catch (error) {
+    recordDiagnostic(error, {
+      command: "dev", operation: "runner_version_probe", required: false, degraded: true,
+    });
     return null; // old runner (no --version), timeout, or spawn failure → treat as unversioned
   }
 }
@@ -1323,7 +1327,10 @@ export async function publishedRunnerIntegrity(env, version, { timeoutMs = 2000,
     if (!res.ok) return null;
     const dist = (await res.json())?.versions?.[version]?.dist;
     return dist?.integrity || dist?.shasum || null;
-  } catch {
+  } catch (error) {
+    recordDiagnostic(error, {
+      command: "dev", operation: "runner_integrity_probe", required: false, degraded: true,
+    }, env);
     return null;
   }
 }
@@ -1809,6 +1816,9 @@ export async function ensureRegistryLogin(image, args, { client: providedClient
     });
     console.error(`~ registry sign-in ok (${reg})`);
   } catch (e) {
+    recordDiagnostic(e, {
+      command: "dev", operation: "dev_image_pull_token", required: false, degraded: true,
+    });
     console.error(
       `~ (using existing docker login for ${registry} — MCP pull-token not available: ${String(e?.message || e)})`,
     );

package/src/commands/feedback.mjs

@@ -26,6 +26,7 @@ import { establishSession, AuthUnavailableError } from "../auth.mjs";
 import { readActivity, formatActivity } from "../activity-log.mjs";
 import { defaultCredentialsPath, readCredentials } from "../token-store.mjs";
 import { fail } from "../errors.mjs";
+import { formatDiagnostics, readDiagnostics, recordDiagnostic } from "../diagnostics.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 const TYPES = new Set(["bug", "feature", "improvement"]);
@@ -57,9 +58,14 @@ Requires a signed-in session — run \`tot login\` first if needed.`;
  * `traceId` link) is unit-testable without driving the MCP handshake. Both extras
  * are OMITTED when their source is absent — never sent as null/empty.
  * @param {{ type: string, category: string, severity: string, title: string,
- *   description: string, activityText?: string|null, traceId?: string|null }} f
+ *   description: string, activityText?: string|null, diagnosticsText?: string|null,
+ *   traceId?: string|null }} f
  */
-export function buildFeedbackPayload({ type, category, severity, title, description, activityText, traceId }) {
+export function buildFeedbackPayload({ type, category, severity, title, description, activityText, diagnosticsText, traceId }) {
+  const attachments = [
+    activityText ? `tot CLI activity (most recent last):\n${activityText}` : null,
+    diagnosticsText ? `tot CLI diagnostics (redacted, most recent last):\n${diagnosticsText}` : null,
+  ].filter(Boolean);
   return {
     type,
     category,
@@ -67,9 +73,9 @@ export function buildFeedbackPayload({ type, category, severity, title, descript
     title,
     description,
     scenario: "tot-cli",
-    // Activity → `sensitive` (ToT-admins-only, never clustered/shared). It's already
-    // secret-redacted; `sensitive` is the belt-and-suspenders home for it.
-    ...(activityText ? { sensitive: `tot CLI activity (most recent last):\n${activityText}` } : {}),
+    // CLI context → `sensitive` (ToT-admins-only, never clustered/shared). It is
+    // redacted before attachment; `sensitive` is the belt-and-suspenders home for it.
+    ...(attachments.length ? { sensitive: attachments.join("\n\n") } : {}),
     // Invite→terminal→problem trace link (omitted when this wasn't an invite login).
     ...(traceId ? { traceId } : {}),
   };
@@ -138,6 +144,8 @@ export async function run(argv) {
 
   const entries = args.activity ? readActivity(env, { limit: 40 }) : [];
   const activityText = entries.length ? formatActivity(entries) : null;
+  const diagnostics = args.activity ? readDiagnostics(env, { limit: 20 }) : [];
+  const diagnosticsText = diagnostics.length ? formatDiagnostics(diagnostics) : null;
   const title = message.length > 80 ? `${message.slice(0, 79)}…` : message;
 
   // The invite→terminal→problem trace id `tot login` cached from the pasted invite
@@ -153,9 +161,9 @@ export async function run(argv) {
   console.error(`  ${args.type} · ${args.category} · ${args.severity}`);
   console.error(`  "${title}"`);
   console.error(
-    activityText
-      ? `  + your last ${entries.length} CLI command(s) — secret-redacted, ToT-admins-only`
-      : "  (no activity log attached)",
+    activityText || diagnosticsText
+      ? `  + ${entries.length} recent command(s) and ${diagnostics.length} diagnostic(s) — redacted, ToT-admins-only`
+      : "  (no activity or diagnostics attached)",
   );
 
   if (!args.yes) {
@@ -192,6 +200,7 @@ export async function run(argv) {
       title,
       description: message,
       activityText,
+      diagnosticsText,
       traceId,
     });
     const res = await client.callTool("feedback_submit", payload);
@@ -199,6 +208,7 @@ export async function run(argv) {
     console.log(`\n+ sent — thank you.${id ? ` (report ${id})` : ""}`);
     return 0;
   } catch (e) {
+    recordDiagnostic(e, { command: "feedback", operation: "feedback_submit", required: true }, env);
     if (e instanceof AuthUnavailableError) {
       console.error(fail(`can't send feedback: ${e.message}`, e.hint || "run `tot login` first."));
       return 1;

package/src/commands/grants.mjs

@@ -29,6 +29,7 @@ import { createMcpClient } from "../mcp.mjs";
 import { storeListError, noStoresGuidance } from "./clone.mjs";
 import { offerSignIn } from "./login.mjs";
 import { recordServerPolicy } from "../update-check.mjs";
+import { recordDiagnostic } from "../diagnostics.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
@@ -169,7 +170,10 @@ async function tryIntrospect(client) {
     const r = await client.callTool("grant_introspect", {});
     if (r && typeof r === "object" && Array.isArray(r.grants)) return r;
     return null;
-  } catch {
+  } catch (error) {
+    recordDiagnostic(error, {
+      command: "grants", operation: "grant_introspect", required: false, degraded: true,
+    });
     return null;
   }
 }

package/src/commands/link.mjs

@@ -25,6 +25,7 @@ import { offerSignIn } from "./login.mjs";
 import { openBrowser } from "../open.mjs";
 import { CliError, fail, formatError } from "../errors.mjs";
 import { normalizeStores } from "./clone.mjs";
+import { recordDiagnostic } from "../diagnostics.mjs";
 
 const DEFAULT_MCP_URL = "https://mcp.tokenoftrust.com";
 
@@ -131,6 +132,7 @@ export async function run(argv, _ctx) {
     } catch (e) {
       throw new CliError(`couldn't start the identity link: ${String(e?.message || e)}`, {
         next: "your MCP may not support `tot link` yet — run `tot whoami` for the current guidance",
+        cause: e,
       });
     }
     const { authUrl, pollHandle } = linkBeginFields(begin);
@@ -172,7 +174,10 @@ export async function run(argv, _ctx) {
       } else {
         console.log("  Next: `tot start` — if it still shows no stores, ask your ToT contact for a store invite.");
       }
-    } catch {
+    } catch (error) {
+      recordDiagnostic(error, {
+        command: "link", operation: "client_list", required: false, degraded: true,
+      }, env);
       console.log("  Next: `tot start` to build your store.");
     }
     return 0;
@@ -205,6 +210,9 @@ export async function pollLink(client, pollHandle, { timeoutMs = 120000, interva
       res = await client.callTool("identity_link_poll", { pollHandle });
     } catch (e) {
       // A transient poll error isn't fatal — keep trying until the deadline.
+      recordDiagnostic(e, {
+        command: "link", operation: "identity_link_poll", required: false, degraded: true,
+      });
       await delay(intervalMs);
       continue;
     }

package/src/commands/submit.mjs

@@ -17,7 +17,8 @@
  * exits non-zero and keeps its stable retry identity. Step 3 calls
  * the MCP `preview_status` read-back: given the commit just pushed it returns
  * { status, reconcile, compliance, previewUrl } and we poll it while reconcile is
- * pending. A read-back failure after the candidate exists is reported separately.
+ * pending. A later read-back failure preserves the candidate receipt and returns a
+ * successful but explicitly degraded result with a diagnostic ID.
  *
  * Polling (E2): every call carries `waitMs` so a preview_status-aware MCP long-polls
  * (blocks up to waitMs, waking immediately on arrival) instead of us sleeping blind
@@ -53,6 +54,11 @@ import { openBrowser } from "../open.mjs";
 import { startProgress } from "../progress.mjs";
 import { fail } from "../errors.mjs";
 import { emitActivity } from "../activity.mjs";
+import {
+  diagnosticReference,
+  invocationDegradedResult,
+  recordDiagnostic,
+} from "../diagnostics.mjs";
 import {
   defaultCandidateStatePath,
   readActiveChangeId,
@@ -500,7 +506,13 @@ export async function runBornRebased(client, { repo, changeId, strategy }) {
     const raw = await client.callTool("candidate_refresh", { repo, changeId, strategy });
     return normalizeRefreshResult(raw);
   } catch (e) {
-    return { ...normalizeRefreshResult(null), status: "error", message: String(e?.message || e) };
+    const diagnostic = recordDiagnostic(e, {
+      command: "submit", operation: "candidate_refresh", required: false, degraded: true,
+    });
+    return {
+      ...normalizeRefreshResult(null), status: "error", message: String(e?.message || e),
+      degraded: true, diagnosticId: diagnostic.diagnosticId,
+    };
   }
 }
 
@@ -959,7 +971,10 @@ export async function candidateStateFor(client, { repo, changeId }) {
         ? r.candidates.find((x) => x?.changeId === changeId)
         : r;
     return c && typeof c.state === "string" ? c.state : null;
-  } catch {
+  } catch (error) {
+    recordDiagnostic(error, {
+      command: "submit", operation: "candidate_status", required: false, degraded: true,
+    });
     return null;
   }
 }
@@ -1012,8 +1027,8 @@ const REQUIRED_ATTRIBUTION_REFUSALS = new Set([
 ]);
 
 export class CandidateRegistrationError extends Error {
-  constructor(message) {
-    super(message);
+  constructor(message, cause) {
+    super(message, cause === undefined ? undefined : { cause });
     this.name = "CandidateRegistrationError";
   }
 }
@@ -1071,7 +1086,7 @@ export async function submitCandidate(client, { repo, changeId, ref, headSha, ch
     return result;
   } catch (e) {
     if (e instanceof CandidateRegistrationError) throw e;
-    throw new CandidateRegistrationError(`Candidate not created: ${describeReadbackError(e)}`);
+    throw new CandidateRegistrationError(`Candidate not created: ${describeReadbackError(e)}`, e);
   }
 }
 
@@ -1120,9 +1135,10 @@ function reportCandidate(result, changeId, { quiet = false } = {}) {
  *   status?: {status?: string, reconcile?: object|null, compliance?: object|null,
  *     previewUrl?: string|null, shipped?: object|null, dispatched?: boolean|null,
  *     notDispatched?: boolean, delivery?: object|null}|null,
- *   previewPrUrl?: string|null, error?: string|null, note?: string|null, noChanges?: boolean }} input
+ *   previewPrUrl?: string|null, error?: string|null, note?: string|null, noChanges?: boolean,
+ *   degraded?: boolean, diagnosticId?: string|null }} input
  */
-export function buildJsonResult({ ok, ref = null, commit = null, changeId = null, candidate = null, status = null, previewPrUrl = null, error = null, note = null, noChanges = false }) {
+export function buildJsonResult({ ok, ref = null, commit = null, changeId = null, candidate = null, status = null, previewPrUrl = null, error = null, note = null, noChanges = false, degraded = false, diagnosticId = null }) {
   return {
     ok,
     ref,
@@ -1145,6 +1161,8 @@ export function buildJsonResult({ ok, ref = null, commit = null, changeId = null
     forwardFailed: /** @type {any} */ (status)?.forwardFailed ?? false,
     delivery: status?.delivery ?? null,
     previewPrUrl,
+    ...(degraded ? { degraded: true } : {}),
+    ...(diagnosticId ? { diagnosticId } : {}),
     // Honest-diagnosis parity with the human-readable formatNotDispatchedBlock: a
     // `--json` caller gets the SAME "why" signal a human sees on the console. Without
     // this, `candidate:null, notDispatched:true, delivery:null` reads identically for
@@ -1157,6 +1175,45 @@ export function buildJsonResult({ ok, ref = null, commit = null, changeId = null
   };
 }
 
+export function candidateFailureOutcome({
+  error, candidateRequired, candidate, operation, command, env,
+  ref, commit, changeId, previewPrUrl,
+}) {
+  const required = candidateRequired && !candidate;
+  const diagnostic = recordDiagnostic(error, {
+    command, operation, required, degraded: !required,
+  }, env);
+  if (required) {
+    const detail = error instanceof CandidateRegistrationError
+      ? error.message
+      : String(error?.message || error);
+    const note = `push succeeded but no review candidate was created: ${detail}`;
+    return {
+      required,
+      exitCode: 1,
+      note,
+      diagnostic,
+      result: buildJsonResult({
+        ok: false, ref, commit, changeId, candidate: null, error: note,
+        diagnosticId: diagnostic.diagnosticId,
+      }),
+    };
+  }
+  const note = error instanceof AuthUnavailableError
+    ? `candidate created; sign in to read its reconcile/compliance result — ${error.hint || "developer sign-in pending"}`
+    : `candidate created; result read-back is degraded: ${describeReadbackError(error)}`;
+  return {
+    required,
+    exitCode: 0,
+    note,
+    diagnostic,
+    result: buildJsonResult({
+      ok: true, ref, commit, changeId, candidate, previewPrUrl, note,
+      degraded: true, diagnosticId: diagnostic.diagnosticId,
+    }),
+  };
+}
+
 /**
  * The sha `preview_status` actually resolves against. The candidate the forge opened
  * may carry a DIFFERENT head than the commit you pushed (it is rebuilt onto the
@@ -1272,8 +1329,10 @@ export async function run(argv, ctx, {
   // expired. Best-effort — never blocks the actual preview on a migration hiccup.
   try {
     ensureTokenlessRemote(git);
-  } catch {
-    /* best-effort — see above */
+  } catch (error) {
+    recordDiagnostic(error, {
+      command: verb, operation: "credential_helper_install", required: false, degraded: true,
+    }, env);
   }
 
   // How far the base has drifted since this candidate forked (unit c2), hoisted to the
@@ -1455,11 +1514,20 @@ export async function run(argv, ctx, {
   try {
     session = await establish(client, { env, prefer: args.identity || undefined });
   } catch (e) {
+    const diagnostic = recordDiagnostic(e, {
+      command: verb, operation: "session_establish", required: true, degraded: false,
+    }, env);
     const note = e instanceof AuthUnavailableError
       ? `Candidate not created: ${e.hint || "developer sign-in is required"}.`
       : `Candidate not created: couldn't reach Token of Trust (${describeReadbackError(e)}).`;
-    if (!args.json) console.error(fail(note, "run `tot login`, then re-run; no candidate ref was pushed"));
-    emitJson(args, buildJsonResult({ ok: false, commit, error: note }));
+    if (!args.json) {
+      console.error(fail(note, "run `tot login`, then re-run; no candidate ref was pushed"));
+      console.error(`  → ${diagnosticReference(diagnostic, env)}`);
+    }
+    emitJson(args, buildJsonResult({
+      ok: false, commit, candidate: null, error: note,
+      diagnosticId: diagnostic.diagnosticId,
+    }));
     return 1;
   }
 
@@ -1474,7 +1542,11 @@ export async function run(argv, ctx, {
   if (active && repo && !args.forkCandidate) {
     try {
       await client.callTool("client_switch", { tenant });
-    } catch { /* scope bind is best-effort; candidateStateFor tolerates a miss */ }
+    } catch (error) {
+      recordDiagnostic(error, {
+        command: verb, operation: "client_switch", required: false, degraded: true,
+      }, env);
+    }
     const resolved = await resolveActivePointer(client, { repo, active });
     if (resolved.dropped) {
       console.error(
@@ -1521,10 +1593,18 @@ export async function run(argv, ctx, {
   }
   try {
     writeActiveChangeId(statePath, { mcpUrl: baseUrl, repo, branch, changeId });
-  } catch {
+  } catch (error) {
     const note = "Candidate not created: couldn't persist retry identity.";
-    if (!args.json) console.error(fail(note, "fix ~/.tot permissions, then re-run; no candidate ref was pushed"));
-    emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: note }));
+    const diagnostic = recordDiagnostic(error, {
+      command: verb, operation: "candidate_pointer_write", required: true, degraded: false,
+    }, env);
+    if (!args.json) {
+      console.error(fail(note, "fix ~/.tot permissions, then re-run; no candidate ref was pushed"));
+      console.error(`  → ${diagnosticReference(diagnostic, env)}`);
+    }
+    emitJson(args, buildJsonResult({
+      ok: false, ref, commit, changeId, error: note, diagnosticId: diagnostic.diagnosticId,
+    }));
     return 1;
   }
 
@@ -1540,6 +1620,9 @@ export async function run(argv, ctx, {
       const res = await checkout(client, { tenant, tag, cloneDir: null, redact: redactUrl });
       return res.gitRemote || null;
     } catch (e) {
+      recordDiagnostic(e, {
+        command: verb, operation: "tenant_checkout", required: false, degraded: true,
+      }, env);
       console.error(
         `~ couldn't mint a fresh push credential (${redactUrl(String(e?.message || e))}) — using the checkout's remote`,
       );
@@ -1558,8 +1641,14 @@ export async function run(argv, ctx, {
       errorClass: isForgeAuthError(e?.stderr || e?.message || e) ? "forge_auth" : "git_push_failed",
     });
     const msg = `push failed: ${redactUrl(String(e.stderr || e.message || e))}`;
+    const diagnostic = recordDiagnostic(new Error(msg, { cause: e }), {
+      command: verb, operation: "git_push", required: true, degraded: false,
+    }, env);
     console.error(fail(msg, "check your commit and that the checkout's remote is reachable, then re-run"));
-    emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: msg }));
+    if (!args.json) console.error(`  → ${diagnosticReference(diagnostic, env)}`);
+    emitJson(args, buildJsonResult({
+      ok: false, ref, commit, changeId, error: msg, diagnosticId: diagnostic.diagnosticId,
+    }));
     return 1;
   }
   if (!args.json) console.log(`\n+ submitted ${short} to ${ref}.`);
@@ -1568,18 +1657,26 @@ export async function run(argv, ctx, {
   // 2b + 3. open/update the PR-backed candidate, then report reconcile +
   // compliance + preview URL from the MCP — reusing the session established above.
   let progress = null;
+  let candidate = null;
+  let previewPrUrl = null;
+  let operation = "client_switch";
+  const candidateRequired = changedEntries.length > 0;
   try {
     // Bind the active tenant so preview_status/candidate_open read the right scope
     // (idempotent — checkoutTenant already switched when the fresh mint succeeded).
     try {
       await client.callTool("client_switch", { tenant });
     } catch (e) {
-      throw new CandidateRegistrationError(`Candidate not created: tenant scope could not be bound (${describeReadbackError(e)}).`);
+      throw new CandidateRegistrationError(
+        `Candidate not created: tenant scope could not be bound (${describeReadbackError(e)}).`,
+        e,
+      );
     }
 
     // 2b. Register the exact ref and asserted commit that git just pushed. No file
     // bytes cross MCP and the server does not reconstruct or replace these commits.
-    const candidate = await submitCandidate(client, {
+    operation = "candidate_open";
+    candidate = await submitCandidate(client, {
       repo, changeId, ref, headSha: commit, changeSummary,
       hasChanges: changedEntries.length > 0, quiet: args.json,
     });
@@ -1602,6 +1699,7 @@ export async function run(argv, ctx, {
     // never blocking the push that already landed. Gated on --skip-freshness via
     // baseDrift (0 when skipped).
     if (repo && baseDrift > 0 && candidate && !isTerminalCandidateState(candidate.state) && changeId) {
+      operation = "candidate_refresh";
       const rebased = await runBornRebased(client, { repo, changeId, strategy: bornRebasedStrategy });
       if (rebased.ok) {
         for (const line of formatBornRebasedSuccess({ behind: baseDrift, strategy: rebased.strategy || bornRebasedStrategy, refreshedFiles: rebased.refreshedFiles })) {
@@ -1619,6 +1717,7 @@ export async function run(argv, ctx, {
           candidate: { ...candidate, prNumber: freshPr ?? candidate.prNumber },
           previewPrUrl: freshPrUrl,
           note: `born-rebased on the current base (${rebased.strategy || bornRebasedStrategy})`,
+          ...invocationDegradedResult(),
         }));
         return 0;
       }
@@ -1639,7 +1738,7 @@ export async function run(argv, ctx, {
     // the server-minted `previewUrl` (formatShareableUrlBlock) that only shows
     // up once reconcile actually completes. Honest framing: it's printed as
     // "building", never as "ready".
-    const previewPrUrl =
+    previewPrUrl =
       candidate && !isTerminalCandidateState(candidate.state) && typeof candidate.prNumber === "number"
         ? shareablePrUrl(env.TOT_STOREFRONT_URL || env.STOREFRONT_BASE_URL || DEFAULT_STOREFRONT_URL, tenant, candidate.prNumber)
         : null;
@@ -1657,6 +1756,7 @@ export async function run(argv, ctx, {
     }
 
     let status;
+    operation = "preview_status";
     if (args.noWait) {
       status = normalizePreviewStatus(await client.callTool("preview_status", { commit: statusSha }));
     } else {
@@ -1702,22 +1802,38 @@ export async function run(argv, ctx, {
     const noChanges = changedEntries.length === 0;
     reportStatus(status, tenant, { open: !args.noOpen && !args.json, quiet: args.json, commit: statusSha, ref, verb, noChanges });
     const ok = previewSubmitSucceeded(status);
-    emitJson(args, buildJsonResult({ ok, ref, commit, changeId, candidate, status, previewPrUrl, noChanges }));
+    const degradation = invocationDegradedResult();
+    if (degradation.degraded && !args.json) {
+      console.log(`  ~ completed with degraded optional diagnostics — ${diagnosticReference({ diagnosticId: degradation.diagnosticId }, env)}`);
+    }
+    emitJson(args, buildJsonResult({
+      ok, ref, commit, changeId, candidate, status,
+      previewPrUrl, noChanges, ...degradation,
+    }));
     return ok ? 0 : 1;
   } catch (e) {
     progress?.stop();
-    if (e instanceof CandidateRegistrationError) {
-      const note = `${e.message} Your preview push is in, but no review PR was created.`;
-      if (!args.json) console.error(fail(note, `re-run \`tot submit\`; retry will reuse ${ref}`));
-      emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: note }));
-      return 1;
+    const outcome = candidateFailureOutcome({
+      error: e, candidateRequired, candidate, operation, command: verb, env,
+      ref, commit, changeId, previewPrUrl,
+    });
+    if (outcome.required) {
+      if (!args.json) {
+        const next = e instanceof CandidateRegistrationError
+          ? `re-run \`tot ${verb}\`; retry will reuse ${ref}`
+          : `fix the reported MCP failure, then re-run \`tot ${verb}\``;
+        console.error(fail(outcome.note, next));
+        console.error(`  → ${diagnosticReference(outcome.diagnostic, env)}`);
+      }
+      emitJson(args, outcome.result);
+      return outcome.exitCode;
     }
-    const note = e instanceof AuthUnavailableError
-      ? `Preview result unavailable: ${e.hint || "developer sign-in is required"}.`
-      : `Preview result unavailable: ${describeReadbackError(e)}.`;
-    if (!args.json) console.error(fail(note, `the candidate ref remains at ${ref}; fix the error and re-run`));
-    emitJson(args, buildJsonResult({ ok: false, ref, commit, changeId, error: note }));
-    return 1;
+    if (!args.json) {
+      console.log(`  (${outcome.note})`);
+      console.log(`  ${diagnosticReference(outcome.diagnostic, env)}`);
+    }
+    emitJson(args, outcome.result);
+    return outcome.exitCode;
   }
 }
 

package/src/commands/sync.mjs

@@ -32,6 +32,7 @@
 import { execFileSync } from "node:child_process";
 import { fail } from "../errors.mjs";
 import { ensureTokenlessRemote } from "../git-credential.mjs";
+import { recordDiagnostic } from "../diagnostics.mjs";
 
 /** The protected branch `tot sync` fetches + merges from by default. */
 export const DEFAULT_SYNC_BRANCH = "preview";
@@ -173,6 +174,9 @@ export async function run(argv, ctx) {
     // missing repo, with nothing pointing back here.
     console.error(`~ could not repair this checkout's forge credentials: ${e?.message || e}`);
     console.error("  a fetch failure below is likely this, not a missing repo.");
+    recordDiagnostic(e, {
+      command: "sync", operation: "credential_helper_install", required: false, degraded: true,
+    });
   }
 
   // Refuse a dirty tree up front — a merge on top of uncommitted edits is how