@topogram/cli 0.3.72 → 0.3.74

package/src/cli/commands/import/plan.js

@@ -40,6 +40,15 @@ export const BROWNFIELD_BROAD_ADOPT_SELECTORS = [
   },
   { selector: "workflows", kind: "track", label: "workflows", matches: (/** @type {AnyRecord} */ item) => item.track === "workflows" || item.kind === "decision" },
   { selector: "verification", kind: "kind", label: "verification", matches: (/** @type {AnyRecord} */ item) => item.kind === "verification" },
+  {
+    selector: "cli",
+    kind: "track",
+    label: "CLI surfaces",
+    matches: (/** @type {AnyRecord} */ item) =>
+      item.bundle === "cli" ||
+      item.track === "cli" ||
+      item.suggested_action === "promote_cli_surface"
+  },
   {
     selector: "ui",
     kind: "track",

package/src/cli/commands/import/workspace.js

@@ -116,6 +116,9 @@ export function importCandidateCounts(summary) {
     uiRoutes: candidates.ui?.routes?.length || 0,
     uiWidgets: candidates.ui?.widgets?.length || candidates.ui?.components?.length || 0,
     uiShapes: candidates.ui?.shapes?.length || 0,
+    cliCommands: candidates.cli?.commands?.length || 0,
+    cliCapabilities: candidates.cli?.capabilities?.length || 0,
+    cliSurfaces: candidates.cli?.surfaces?.length || 0,
     workflows: candidates.workflows?.workflows?.length || 0,
     verifications: candidates.verification?.verifications?.length || 0
   };

package/src/cli/commands/query/definitions.js

@@ -32,21 +32,22 @@
  * @returns {QueryDefinition[]}
  */
 export function queryDefinitions() {
+  const contextSelectors = ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "domain", "pitch", "requirement", "acceptance", "task", "plan", "bug", "document", "from-topogram"];
   return [
     {
       name: "slice",
       purpose: "Give an agent the smallest graph slice needed to reason about one selected semantic surface.",
       description: "Return a focused semantic context slice for one selected surface.",
-      selectors: ["capability", "workflow", "projection", "widget", "entity", "journey", "domain"],
+      selectors: ["capability", "workflow", "projection", "widget", "entity", "journey", "domain", "pitch", "requirement", "acceptance", "task", "plan", "bug", "document"],
       args: ["[path]", "[selectors]", "[--json]"],
       output: "context_slice",
-      example: "topogram query slice ./topo --widget widget_data_grid"
+      example: "topogram query slice ./topo --task task_implement_audit_writer"
     },
     {
       name: "verification-targets",
       purpose: "Map a selected change or mode to the smallest verification set worth running.",
       description: "Return the smallest verification target set for a mode, selector, or diff.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "from-topogram"],
+      selectors: contextSelectors.filter((selector) => selector !== "surface" && selector !== "domain" && selector !== "pitch" && selector !== "requirement" && selector !== "acceptance" && selector !== "plan" && selector !== "bug" && selector !== "document"),
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "verification_targets",
       example: "topogram query verification-targets ./topo --widget widget_data_grid"
@@ -64,7 +65,7 @@ export function queryDefinitions() {
       name: "change-plan",
       purpose: "Summarize what a selected change affects before code or Topogram edits start.",
       description: "Return the semantic change plan, generator targets, risk, and alignment recommendations.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      selectors: contextSelectors,
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "change_plan_query",
       example: "topogram query change-plan ./topo --widget widget_data_grid"
@@ -73,7 +74,7 @@ export function queryDefinitions() {
       name: "review-packet",
       purpose: "Bundle the context a human or agent needs to review a selected semantic change.",
       description: "Return the review packet for a selected change or diff.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      selectors: contextSelectors,
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "review_packet_query",
       example: "topogram query review-packet ./topo --widget widget_data_grid"
@@ -82,7 +83,7 @@ export function queryDefinitions() {
       name: "resolved-workflow-context",
       purpose: "Resolve workflow guidance and artifact load order for a selected mode or change.",
       description: "Return resolved workflow guidance, artifact load order, preset policy, and recommended artifact queries.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "provider", "preset", "from-topogram"],
+      selectors: [...contextSelectors.filter((selector) => selector !== "document"), "provider", "preset"],
       args: ["[path]", "[--mode <id>]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "resolved_workflow_context_query",
       example: "topogram query resolved-workflow-context ./topo --mode modeling --widget widget_data_grid --json"
@@ -91,7 +92,7 @@ export function queryDefinitions() {
       name: "single-agent-plan",
       purpose: "Give one coding agent a bounded plan, artifact set, and write guidance.",
       description: "Return a single-agent operating plan for a mode and optional selector.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      selectors: contextSelectors.filter((selector) => selector !== "document"),
       args: ["[path]", "[--mode <id>]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "single_agent_plan_query",
       example: "topogram query single-agent-plan ./topo --mode modeling --widget widget_data_grid --json"
@@ -100,7 +101,7 @@ export function queryDefinitions() {
       name: "risk-summary",
       purpose: "Surface behavioral, ownership, and verification risks for a selected change.",
       description: "Return the risk summary for a selected change, mode, or diff.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      selectors: contextSelectors,
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "risk_summary_query",
       example: "topogram query risk-summary ./topo --widget widget_data_grid"
@@ -109,7 +110,7 @@ export function queryDefinitions() {
       name: "proceed-decision",
       purpose: "Tell a human or agent whether enough context and proof exist to proceed.",
       description: "Return a proceed/no-go decision for the current selected work.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "surface", "from-topogram"],
+      selectors: contextSelectors,
       args: ["[path]", "[--mode <id>]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "proceed_decision_query",
       example: "topogram query proceed-decision ./topo --mode verification"
@@ -118,7 +119,7 @@ export function queryDefinitions() {
       name: "write-scope",
       purpose: "Define where an agent may edit for a selected semantic surface.",
       description: "Return safe edit boundaries for a selected mode or semantic surface.",
-      selectors: ["mode", "capability", "workflow", "projection", "widget", "entity", "journey", "from-topogram"],
+      selectors: contextSelectors.filter((selector) => selector !== "surface" && selector !== "document"),
       args: ["[path]", "[selectors]", "[--from-topogram <path>]", "[--json]"],
       output: "write_scope_query",
       example: "topogram query write-scope ./topo --widget widget_data_grid"

package/src/cli/commands/query/workspace.js

@@ -74,6 +74,13 @@ export function importAdoptOnlyRequested(options = {}) {
     options.journeyId ||
     options.surfaceId ||
     options.domainId ||
+    options.pitchId ||
+    options.requirementId ||
+    options.acceptanceId ||
+    options.taskId ||
+    options.planId ||
+    options.bugId ||
+    options.documentId ||
     options.fromTopogramPath
   );
 }
@@ -202,7 +209,14 @@ export function hasSelectors(options) {
     options.entityId ||
     options.journeyId ||
     options.surfaceId ||
-    options.domainId
+    options.domainId ||
+    options.pitchId ||
+    options.requirementId ||
+    options.acceptanceId ||
+    options.taskId ||
+    options.planId ||
+    options.bugId ||
+    options.documentId
   );
 }
 
@@ -228,7 +242,14 @@ export function selectorOptions(options) {
     entityId: options.entityId,
     journeyId: options.journeyId,
     surfaceId: options.surfaceId,
-    domainId: options.domainId
+    domainId: options.domainId,
+    pitchId: options.pitchId,
+    requirementId: options.requirementId,
+    acceptanceId: options.acceptanceId,
+    taskId: options.taskId,
+    planId: options.planId,
+    bugId: options.bugId,
+    documentId: options.documentId
   };
 }
 

package/src/cli/commands/release-rollout.js

@@ -16,6 +16,7 @@ import {
   expectedConsumerWorkflowName,
   hasStagedGitChanges,
   inspectConsumerCi,
+  inspectGitUpstreamAhead,
   inspectGitWorktreeClean,
   messageFromError,
   runGit,
@@ -24,12 +25,101 @@ import {
 
 /**
  * @typedef {Record<string, any>} AnyRecord
+ * @typedef {{ consumer?: string, step: string, status: "start"|"ok"|"skip"|"waiting"|"error", message: string, elapsedMs?: number, [key: string]: any }} ReleaseRollProgress
  */
 
+/**
+ * @param {{ onProgress?: ((event: ReleaseRollProgress) => void)|null, captureProgress?: boolean }} options
+ * @param {ReleaseRollProgress} event
+ * @returns {void}
+ */
+function notifyProgress(options, event) {
+  if (typeof options.onProgress === "function") {
+    options.onProgress(event);
+  }
+}
+
+/**
+ * @param {AnyRecord} item
+ * @param {{ onProgress?: ((event: ReleaseRollProgress) => void)|null, captureProgress?: boolean }} options
+ * @param {ReleaseRollProgress["step"]} step
+ * @param {ReleaseRollProgress["status"]} status
+ * @param {string} message
+ * @param {AnyRecord} [detail]
+ * @returns {ReleaseRollProgress}
+ */
+function recordProgress(item, options, step, status, message, detail = {}) {
+  /** @type {ReleaseRollProgress} */
+  const event = {
+    consumer: item.name,
+    step,
+    status,
+    message
+  };
+  if (typeof detail.elapsedMs === "number") {
+    event.elapsedMs = detail.elapsedMs;
+  }
+  if (typeof detail.headSha === "string") {
+    event.headSha = detail.headSha;
+  }
+  if (typeof detail.expectedWorkflow === "string") {
+    event.expectedWorkflow = detail.expectedWorkflow;
+  }
+  if (detail.run && typeof detail.run === "object") {
+    event.run = {
+      workflowName: detail.run.workflowName || null,
+      status: detail.run.status || null,
+      conclusion: detail.run.conclusion || null,
+      headSha: detail.run.headSha || null,
+      url: detail.run.url || null
+    };
+  }
+  if (options.captureProgress !== true) {
+    notifyProgress(options, event);
+    return event;
+  }
+  if (!Array.isArray(item.progress)) {
+    item.progress = [];
+  }
+  item.progress.push(event);
+  notifyProgress(options, event);
+  return event;
+}
+
+/**
+ * @param {Array<AnyRecord>} consumers
+ * @param {{ version: string, push: boolean, watch: boolean, noWatch?: boolean }} options
+ * @returns {AnyRecord}
+ */
+function buildRecoverySummary(consumers, options) {
+  /**
+   * @param {(consumer: AnyRecord) => boolean} predicate
+   * @returns {string[]}
+   */
+  const namesFor = (predicate) => consumers.filter(predicate).map((consumer) => String(consumer.name));
+  return {
+    version: options.version,
+    alreadyCurrent: namesFor((consumer) => consumer.alreadyCurrent === true),
+    alreadyPushed: namesFor((consumer) => consumer.alreadyPushed === true),
+    updated: namesFor((consumer) => consumer.updated === true),
+    committed: namesFor((consumer) => consumer.committed === true),
+    pushed: namesFor((consumer) => consumer.pushed === true),
+    recoveredPushes: namesFor((consumer) => consumer.recoveredPush === true),
+    needsAttention: namesFor((consumer) => (
+      /** @type {Array<AnyRecord>} */ (consumer.diagnostics || [])
+    ).some((diagnostic) => diagnostic.severity === "error")),
+    resumeCommand: `topogram release roll-consumers ${options.version}${options.push ? "" : " --no-push"}${options.watch ? " --watch" : options.noWatch ? " --no-watch" : ""}`,
+    asyncVerificationCommand: "topogram release status --strict",
+    watchGuidance: options.watch
+      ? "If CI waiting is too slow or interrupted, rerun roll-consumers with --no-watch, then verify with release status --strict."
+      : "This rollout did not wait for CI. Verify consumers after workflows finish with release status --strict."
+  };
+}
+
 /**
  * @param {string} requested
- * @param {{ cwd?: string, push?: boolean, watch?: boolean }} [options]
- * @returns {{ ok: boolean, packageName: string, requestedVersion: string, requestedLatest: boolean, pushed: boolean, watched: boolean, consumers: Array<AnyRecord>, diagnostics: Array<AnyRecord>, errors: string[] }}
+ * @param {{ cwd?: string, push?: boolean, watch?: boolean, noWatch?: boolean, onProgress?: ((event: ReleaseRollProgress) => void)|null, captureProgress?: boolean }} [options]
+ * @returns {{ ok: boolean, packageName: string, requestedVersion: string, requestedLatest: boolean, pushed: boolean, watched: boolean, consumers: Array<AnyRecord>, diagnostics: Array<AnyRecord>, errors: string[], recovery: AnyRecord|null }}
  */
 export function buildReleaseRollConsumersPayload(requested, options = {}) {
   const cwd = options.cwd || process.cwd();
@@ -44,7 +134,7 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
       severity: "error",
       message: "`topogram release roll-consumers --watch` requires pushing consumer commits.",
       path: "release roll-consumers",
-      suggestedFix: "Remove --no-push or run without --watch and verify consumer CI separately."
+      suggestedFix: "Remove --no-push or use --no-watch and verify consumer CI separately."
     });
     return {
       ok: false,
@@ -55,7 +145,8 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
       watched: watch,
       consumers: [],
       diagnostics,
-      errors: diagnostics.map((diagnostic) => diagnostic.message)
+      errors: diagnostics.map((diagnostic) => diagnostic.message),
+      recovery: null
     };
   }
   const version = requestedLatest
@@ -79,9 +170,14 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
       commit: null,
       update: null,
       ci: null,
+      alreadyCurrent: false,
+      alreadyPushed: false,
+      recoveredPush: false,
+      upstreamAhead: null,
       diagnostics: []
     };
     consumers.push(item);
+    recordProgress(item, options, "inspect", "start", `${consumer.name}: inspecting repository and package metadata.`);
     if (!consumer.root || !fs.existsSync(consumer.root)) {
       item.diagnostics.push({
         code: "release_consumer_repo_missing",
@@ -91,6 +187,7 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
         suggestedFix: `Clone ${consumer.name} beside the topogram repo, then rerun roll-consumers.`
       });
       diagnostics.push(...item.diagnostics);
+      recordProgress(item, options, "inspect", "error", `${consumer.name}: repository not found.`);
       continue;
     }
     const packagePath = path.join(consumer.root, "package.json");
@@ -103,6 +200,7 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
         suggestedFix: "Only package-backed first-party consumers can be rolled by this command."
       });
       diagnostics.push(...item.diagnostics);
+      recordProgress(item, options, "inspect", "error", `${consumer.name}: package.json missing.`);
       continue;
     }
     const clean = inspectGitWorktreeClean(consumer.root);
@@ -115,11 +213,15 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
         suggestedFix: "Commit, stash, or discard unrelated consumer changes before rolling the CLI version."
       });
       diagnostics.push(...item.diagnostics);
+      recordProgress(item, options, "inspect", "error", `${consumer.name}: worktree is dirty.`);
       continue;
     }
+    recordProgress(item, options, "inspect", "ok", `${consumer.name}: worktree is clean.`);
     try {
+      recordProgress(item, options, "update", "start", `${consumer.name}: updating ${CLI_PACKAGE_NAME} to ${version} and running package checks.`);
       item.update = buildPackageUpdateCliPayload(version, { cwd: consumer.root });
       item.updated = true;
+      recordProgress(item, options, "update", "ok", `${consumer.name}: package update/check completed.`);
     } catch (error) {
       item.diagnostics.push({
         code: "release_consumer_update_failed",
@@ -129,10 +231,12 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
         suggestedFix: "Fix the consumer update/check failure, then rerun roll-consumers."
       });
       diagnostics.push(...item.diagnostics);
+      recordProgress(item, options, "update", "error", `${consumer.name}: package update/check failed.`);
       continue;
     }
     const filesToStage = ["package.json", "package-lock.json", "topogram-cli.version"]
       .filter((file) => fs.existsSync(path.join(consumer.root || "", file)));
+    recordProgress(item, options, "stage", "start", `${consumer.name}: staging package pin changes.`);
     const addResult = runGit(["add", ...filesToStage], consumer.root);
     if (addResult.status !== 0) {
       item.diagnostics.push(commandDiagnostic({
@@ -144,6 +248,7 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
         result: addResult
       }));
       diagnostics.push(...item.diagnostics);
+      recordProgress(item, options, "stage", "error", `${consumer.name}: staging failed.`);
       continue;
     }
     const staged = hasStagedGitChanges(consumer.root);
@@ -157,16 +262,63 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
         result: staged.result
       }));
       diagnostics.push(...item.diagnostics);
+      recordProgress(item, options, "stage", "error", `${consumer.name}: could not inspect staged changes.`);
       continue;
     }
     if (!staged.changed) {
+      item.alreadyCurrent = true;
+      item.commit = currentGitHead(consumer.root);
+      recordProgress(item, options, "stage", "skip", `${consumer.name}: already pinned to ${CLI_PACKAGE_NAME}@${version}; no commit needed.`);
+      if (push) {
+        const ahead = inspectGitUpstreamAhead(consumer.root);
+        item.upstreamAhead = ahead.ok ? ahead.ahead : null;
+        if (!ahead.ok) {
+          item.diagnostics.push(commandDiagnostic({
+            code: "release_consumer_git_upstream_unavailable",
+            severity: "warning",
+            message: `Could not inspect whether ${consumer.name} has unpushed commits.`,
+            path: consumer.root,
+            suggestedFix: "Inspect git status manually; if the consumer branch is ahead, push it before verifying CI.",
+            result: ahead.result
+          }));
+          diagnostics.push(...item.diagnostics.slice(-1));
+        } else if ((ahead.ahead || 0) > 0) {
+          recordProgress(item, options, "push", "start", `${consumer.name}: branch is ahead of upstream; pushing existing rollout commit.`);
+          const pushResult = runGit(["push", "origin", "main"], consumer.root);
+          if (pushResult.status !== 0) {
+            item.diagnostics.push(commandDiagnostic({
+              code: "release_consumer_git_push_failed",
+              severity: "error",
+              message: `Failed to push ${consumer.name} existing CLI update.`,
+              path: consumer.root,
+              suggestedFix: "Push the consumer update manually, then confirm its verification workflow passes.",
+              result: pushResult
+            }));
+            diagnostics.push(...item.diagnostics);
+            recordProgress(item, options, "push", "error", `${consumer.name}: push failed.`);
+            continue;
+          }
+          item.pushed = true;
+          item.recoveredPush = true;
+          recordProgress(item, options, "push", "ok", `${consumer.name}: pushed existing rollout commit.`);
+        } else {
+          item.alreadyPushed = true;
+          recordProgress(item, options, "push", "skip", `${consumer.name}: branch already matches upstream.`);
+        }
+      }
+      recordProgress(item, options, watch ? "watch-ci" : "check-ci", "start", `${consumer.name}: ${watch ? "watching" : "checking"} verification workflow.`);
       item.ci = watch
-        ? waitForConsumerCi(consumer)
+        ? waitForConsumerCi(consumer, {
+            onProgress: (event) => recordProgress(item, options, "watch-ci", event.status === "ok" ? "ok" : event.status === "error" ? "error" : "waiting", event.message, event)
+          })
         : inspectConsumerCi(consumer, { strict: false });
       item.diagnostics.push(...item.ci.diagnostics);
       diagnostics.push(...item.ci.diagnostics);
+      recordProgress(item, options, watch ? "watch-ci" : "check-ci", item.ci.ok === false ? "error" : "ok", `${consumer.name}: verification ${item.ci.ok === false ? "reported issues" : "checked"}.`);
       continue;
     }
+    recordProgress(item, options, "stage", "ok", `${consumer.name}: staged CLI pin changes.`);
+    recordProgress(item, options, "commit", "start", `${consumer.name}: committing CLI rollout.`);
     const commitResult = runGit(["commit", "-m", `Update Topogram CLI to ${version}`], consumer.root);
     if (commitResult.status !== 0) {
       item.diagnostics.push(commandDiagnostic({
@@ -178,11 +330,14 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
         result: commitResult
       }));
       diagnostics.push(...item.diagnostics);
+      recordProgress(item, options, "commit", "error", `${consumer.name}: commit failed.`);
       continue;
     }
     item.committed = true;
     item.commit = currentGitHead(consumer.root);
+    recordProgress(item, options, "commit", "ok", `${consumer.name}: committed ${item.commit || "CLI rollout"}.`);
     if (push) {
+      recordProgress(item, options, "push", "start", `${consumer.name}: pushing rollout commit.`);
       const pushResult = runGit(["push", "origin", "main"], consumer.root);
       if (pushResult.status !== 0) {
         item.diagnostics.push(commandDiagnostic({
@@ -194,15 +349,21 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
           result: pushResult
         }));
         diagnostics.push(...item.diagnostics);
+        recordProgress(item, options, "push", "error", `${consumer.name}: push failed.`);
         continue;
       }
       item.pushed = true;
+      recordProgress(item, options, "push", "ok", `${consumer.name}: pushed rollout commit.`);
     }
+    recordProgress(item, options, watch ? "watch-ci" : "check-ci", "start", `${consumer.name}: ${watch ? "watching" : "checking"} verification workflow.`);
     item.ci = watch
-      ? waitForConsumerCi(consumer)
+      ? waitForConsumerCi(consumer, {
+          onProgress: (event) => recordProgress(item, options, "watch-ci", event.status === "ok" ? "ok" : event.status === "error" ? "error" : "waiting", event.message, event)
+        })
       : inspectConsumerCi(consumer, { strict: false });
     item.diagnostics.push(...item.ci.diagnostics);
     diagnostics.push(...item.ci.diagnostics);
+    recordProgress(item, options, watch ? "watch-ci" : "check-ci", item.ci.ok === false ? "error" : "ok", `${consumer.name}: verification ${item.ci.ok === false ? "reported issues" : "checked"}.`);
   }
   const errors = diagnostics
     .filter((diagnostic) => diagnostic.severity === "error")
@@ -216,10 +377,19 @@ export function buildReleaseRollConsumersPayload(requested, options = {}) {
     watched: watch,
     consumers,
     diagnostics,
-    errors
+    errors,
+    recovery: buildRecoverySummary(consumers, { version, push, watch, noWatch: options.noWatch === true })
   };
 }
 
+/**
+ * @param {ReleaseRollProgress} event
+ * @returns {void}
+ */
+export function printReleaseRollProgress(event) {
+  console.error(`[roll-consumers] ${event.message}`);
+}
+
 /**
  * @param {ReturnType<typeof buildReleaseRollConsumersPayload>} payload
  * @returns {void}
@@ -233,9 +403,11 @@ export function printReleaseRollConsumers(payload) {
   console.log(`Push: ${payload.pushed ? "enabled" : "disabled"}`);
   console.log(`Watch: ${payload.watched ? "enabled" : "disabled"}`);
   for (const consumer of payload.consumers) {
-    const state = consumer.committed
-      ? consumer.pushed ? "pushed" : "committed"
-      : consumer.updated ? "updated" : "skipped";
+    const state = consumer.alreadyCurrent
+      ? consumer.pushed ? "pushed existing commit" : consumer.alreadyPushed ? "current" : "current"
+      : consumer.committed
+        ? consumer.pushed ? "pushed" : "committed"
+        : consumer.updated ? "updated" : "skipped";
     console.log(`- ${consumer.name}: ${state}`);
     if (consumer.update) {
       console.log(`  Checks run: ${consumer.update.scriptsRun.join(", ") || "none"}`);
@@ -254,4 +426,13 @@ export function printReleaseRollConsumers(payload) {
       console.log(`  ${label}: ${diagnostic.message}`);
     }
   }
+  if (payload.recovery) {
+    console.log("Recovery:");
+    console.log(`  Resume: ${payload.recovery.resumeCommand}`);
+    console.log(`  Verify: ${payload.recovery.asyncVerificationCommand}`);
+    if ((payload.recovery.needsAttention || []).length > 0) {
+      console.log(`  Needs attention: ${payload.recovery.needsAttention.join(", ")}`);
+    }
+    console.log(`  ${payload.recovery.watchGuidance}`);
+  }
 }

package/src/cli/commands/release-shared.js

@@ -19,6 +19,7 @@ const REPO_ROOT = decodeURIComponent(new URL("../../../../", import.meta.url).pa
 
 /**
  * @typedef {Record<string, any>} AnyRecord
+ * @typedef {{ consumer?: string, step?: string, status?: string, message: string, elapsedMs?: number, headSha?: string|null, expectedWorkflow?: string|null, run?: AnyRecord|null }} ReleaseProgressEvent
  */
 
 /**
@@ -157,6 +158,23 @@ export function currentGitHead(cwd) {
   return result.status === 0 ? String(result.stdout || "").trim() || null : null;
 }
 
+/**
+ * @param {string} cwd
+ * @returns {{ ok: boolean, ahead: number|null, result: ReturnType<typeof childProcess.spawnSync> }}
+ */
+export function inspectGitUpstreamAhead(cwd) {
+  const result = runGit(["rev-list", "--count", "@{u}..HEAD"], cwd);
+  if (result.status !== 0) {
+    return { ok: false, ahead: null, result };
+  }
+  const ahead = Number.parseInt(String(result.stdout || "").trim(), 10);
+  return {
+    ok: Number.isFinite(ahead),
+    ahead: Number.isFinite(ahead) ? ahead : null,
+    result
+  };
+}
+
 /**
  * @param {{ code: string, severity: "error"|"warning", message: string, path: string|null, suggestedFix: string, result: ReturnType<typeof childProcess.spawnSync> }} input
  * @returns {{ code: string, severity: "error"|"warning", message: string, path: string|null, suggestedFix: string }}
@@ -205,7 +223,7 @@ function positiveIntegerEnv(name, fallback) {
 
 /**
  * @param {{ name: string, root?: string|null, workflow?: string|null }} consumer
- * @param {{ timeoutMs?: number, intervalMs?: number }} [options]
+ * @param {{ timeoutMs?: number, intervalMs?: number, onProgress?: ((event: ReleaseProgressEvent) => void)|null }} [options]
  * @returns {ReturnType<typeof inspectConsumerCi>}
  */
 export function waitForConsumerCi(consumer, options = {}) {
@@ -213,12 +231,23 @@ export function waitForConsumerCi(consumer, options = {}) {
   const intervalMs = options.intervalMs || positiveIntegerEnv("TOPOGRAM_RELEASE_WATCH_INTERVAL_MS", 5000);
   const startedAt = Date.now();
   let latest = inspectConsumerCi(consumer, { strict: false });
+  const notify = typeof options.onProgress === "function" ? options.onProgress : null;
   while (true) {
     const currentRun = latest.run &&
       latest.headSha &&
       latest.run?.headSha &&
       latest.run.headSha === latest.headSha;
     if (currentRun && latest.run?.status === "completed") {
+      notify?.({
+        consumer: consumer.name,
+        step: "watch-ci",
+        status: "ok",
+        message: `${consumer.name}: verification workflow completed on current commit.`,
+        elapsedMs: Date.now() - startedAt,
+        headSha: latest.headSha,
+        expectedWorkflow: latest.expectedWorkflow,
+        run: latest.run
+      });
       return inspectConsumerCi(consumer, { strict: true });
     }
     if (Date.now() - startedAt >= timeoutMs) {
@@ -228,11 +257,31 @@ export function waitForConsumerCi(consumer, options = {}) {
         severity: "error",
         message: `${consumer.name} verification workflow did not complete on the current commit before the watch timeout.`,
         path: strictLatest.run?.url || consumerGithubRepoSlug(consumer),
-        suggestedFix: "Open the consumer workflow, fix failures if needed, then rerun release status."
+        suggestedFix: "Open the consumer workflow, fix failures if needed, then rerun release status. If you only need to push and verify later, rerun roll-consumers with --no-watch."
       });
       strictLatest.ok = false;
+      notify?.({
+        consumer: consumer.name,
+        step: "watch-ci",
+        status: "error",
+        message: `${consumer.name}: verification watch timed out; rerun with --no-watch to continue asynchronously.`,
+        elapsedMs: Date.now() - startedAt,
+        headSha: strictLatest.headSha,
+        expectedWorkflow: strictLatest.expectedWorkflow,
+        run: strictLatest.run
+      });
       return strictLatest;
     }
+    notify?.({
+      consumer: consumer.name,
+      step: "watch-ci",
+      status: "waiting",
+      message: `${consumer.name}: waiting for ${latest.expectedWorkflow || "verification workflow"} on ${latest.headSha || "HEAD"} (${Math.round((Date.now() - startedAt) / 1000)}s elapsed).`,
+      elapsedMs: Date.now() - startedAt,
+      headSha: latest.headSha,
+      expectedWorkflow: latest.expectedWorkflow,
+      run: latest.run
+    });
     sleepSync(intervalMs);
     latest = inspectConsumerCi(consumer, { strict: false });
   }

package/src/cli/commands/release.js

@@ -6,6 +6,7 @@ import path from "node:path";
 import { stableStringify } from "../../format.js";
 import {
   buildReleaseRollConsumersPayload,
+  printReleaseRollProgress,
   printReleaseRollConsumers
 } from "./release-rollout.js";
 import {
@@ -19,10 +20,11 @@ import {
  */
 export function printReleaseHelp() {
   console.log("Usage: topogram release status [--json] [--strict] [--markdown|--write-report <path>]");
-  console.log("   or: topogram release roll-consumers <version|--latest> [--json] [--no-push] [--watch]");
+  console.log("   or: topogram release roll-consumers <version|--latest> [--json] [--no-push] [--watch|--no-watch]");
   console.log("");
   console.log("Checks the local CLI version, latest published package version, release tag, first-party consumer pins, and strict consumer CI state.");
   console.log("Rolls first-party consumers to a published CLI version, runs their checks, commits, pushes, and can wait for current workflow runs.");
+  console.log("Rollout progress prints to stderr in human mode; JSON output stays final-only. Use --no-watch to push and verify later with release status --strict.");
   console.log("");
   console.log("Examples:");
   console.log("  topogram release status");
@@ -88,13 +90,24 @@ export function runReleaseCommand(context) {
 
   if (command === "roll-consumers") {
     const push = !args.includes("--no-push");
+    const noWatch = args.includes("--no-watch");
     const watch = args.includes("--watch");
+    if (watch && noWatch) {
+      console.error("Use either --watch or --no-watch, not both.");
+      printReleaseHelp();
+      return 1;
+    }
     if (watch && !push) {
-      console.error("Use either --watch or --no-push, not both.");
+      console.error("Use either --watch or --no-push, not both. Use --no-watch with --no-push when CI will be verified separately.");
       printReleaseHelp();
       return 1;
     }
-    const payload = buildReleaseRollConsumersPayload(commandArgs.releaseRollVersion, { push, watch });
+    const payload = buildReleaseRollConsumersPayload(commandArgs.releaseRollVersion, {
+      push,
+      watch,
+      noWatch,
+      onProgress: json ? null : printReleaseRollProgress
+    });
     if (json) {
       console.log(stableStringify(payload));
     } else {