@wrongstack/cli 0.305.1 → 0.306.0

package/dist/{execution-QYFWDD3Y.js → execution-TTE7R5UY.js}

@@ -37,23 +37,24 @@ import {
   writeWebuiSessionChildReady
 } from "./chunk-3JPTNADJ.js";
 import {
-  resolveActiveApiKey
-} from "./chunk-SZ42FYPT.js";
-import {
-  activeProfileConfigPath
-} from "./chunk-YMXXOOFN.js";
+  CLI_VERSION
+} from "./chunk-XJXDOF63.js";
 import {
   terminalLink,
   terminalText
 } from "./chunk-KE7E7DPX.js";
 import {
-  CLI_VERSION
-} from "./chunk-XJXDOF63.js";
+  resolveActiveApiKey
+} from "./chunk-SZ42FYPT.js";
+import {
+  activeProfileConfigPath
+} from "./chunk-YMXXOOFN.js";
 import "./chunk-7OCVIDC7.js";
 
 // src/execution.ts
 import * as path13 from "node:path";
 import { effectiveFallbackChain as effectiveFallbackChain2, setQueuedMessagesSnapshot as setQueuedMessagesSnapshot2 } from "@wrongstack/core/agent";
+import { updateReviewReportEvidence } from "@wrongstack/core/plugin";
 import { attachTodosCheckpoint as attachTodosCheckpoint2 } from "@wrongstack/core/storage";
 import { normalizeTokenSavingTier as normalizeTokenSavingTier2 } from "@wrongstack/core/types";
 import { mergeCustomModelDefs } from "@wrongstack/core/utils";
@@ -2746,6 +2747,128 @@ import * as fsp from "node:fs/promises";
 import * as path10 from "node:path";
 import { emitReviewIfChanged } from "@wrongstack/core/plugin";
 
+// src/chimera-cascade-evidence.ts
+import { spawn as spawn2 } from "node:child_process";
+var JSON_BLOCK_RE = /```json\s*([\s\S]*?)```/gi;
+function extractCascadeEvidence(text) {
+  if (!text) return null;
+  for (const match of text.matchAll(JSON_BLOCK_RE)) {
+    const body = match[1]?.trim();
+    if (!body) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      continue;
+    }
+    const evidence = parseEvidenceObject(parsed);
+    if (evidence) return evidence;
+  }
+  return null;
+}
+function parseEvidenceObject(parsed) {
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const root = parsed;
+  const raw = root.verification_evidence;
+  if (typeof raw !== "object" || raw === null) return null;
+  const checks = raw;
+  const out = {};
+  let found = false;
+  for (const key of ["typecheck", "lint", "tests"]) {
+    const check = parseSingleCheck(checks[key]);
+    if (check) {
+      out[key] = check;
+      found = true;
+    }
+  }
+  return found ? out : null;
+}
+function parseSingleCheck(raw) {
+  if (typeof raw !== "object" || raw === null) return void 0;
+  const check = raw;
+  const command = check.command;
+  const exitCode = check.exitCode;
+  if (typeof command !== "string" || command.trim().length === 0) return void 0;
+  if (typeof exitCode !== "number" || !Number.isInteger(exitCode) || exitCode < 0 || exitCode > 255) {
+    return void 0;
+  }
+  const output = typeof check.output === "string" ? truncateOutput(check.output) : void 0;
+  return { command: command.trim(), exitCode, output };
+}
+var MAX_EVIDENCE_OUTPUT_CHARS = 2e3;
+function truncateOutput(output) {
+  return output.length > MAX_EVIDENCE_OUTPUT_CHARS ? `${output.slice(0, MAX_EVIDENCE_OUTPUT_CHARS)}
+\u2026 (truncated)` : output;
+}
+var SAFE_EXECUTABLES = /* @__PURE__ */ new Set([
+  "pnpm",
+  "npm",
+  "yarn",
+  "npx",
+  "bun",
+  "node",
+  "tsc",
+  "biome",
+  "eslint",
+  "vitest",
+  "jest"
+]);
+var CASCADE_EVIDENCE_COMMAND_TIMEOUT_MS = 12e4;
+var CASCADE_EVIDENCE_UNSAFE_EXIT = 126;
+var CASCADE_EVIDENCE_RUN_ERROR_EXIT = 127;
+function isSafeCascadeCommand(command) {
+  if (!command || command.length > 500) return false;
+  const tokens = command.trim().split(/\s+/);
+  if (tokens.length === 0) return false;
+  if (!SAFE_EXECUTABLES.has(tokens[0])) return false;
+  return tokens.every((token) => /^[A-Za-z0-9@/._:=~+*?\[\]-]+$/.test(token));
+}
+var runCascadeVerificationCommand = (command, cwd, timeoutMs) => {
+  if (!isSafeCascadeCommand(command)) {
+    return Promise.resolve({ exitCode: CASCADE_EVIDENCE_UNSAFE_EXIT });
+  }
+  const tokens = command.trim().split(/\s+/);
+  const executable = tokens[0];
+  const args = tokens.slice(1);
+  return new Promise((resolve3) => {
+    let child;
+    try {
+      child = spawn2(executable, args, {
+        cwd,
+        stdio: "ignore",
+        windowsHide: true,
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+    } catch {
+      resolve3({ exitCode: CASCADE_EVIDENCE_RUN_ERROR_EXIT });
+      return;
+    }
+    child.on("error", () => resolve3({ exitCode: CASCADE_EVIDENCE_RUN_ERROR_EXIT }));
+    child.on("close", (code) => resolve3({ exitCode: code ?? CASCADE_EVIDENCE_RUN_ERROR_EXIT }));
+  });
+};
+async function verifyCascadeEvidence(evidence, cwd, runCommand = runCascadeVerificationCommand, timeoutMs = CASCADE_EVIDENCE_COMMAND_TIMEOUT_MS) {
+  if (!evidence) return { status: "missing", checks: [] };
+  if (!evidence.typecheck) return { status: "failed", checks: [] };
+  const checks = [];
+  for (const name of ["typecheck", "lint", "tests"]) {
+    const claimed = evidence[name];
+    if (!claimed) continue;
+    const actual = await runCommand(claimed.command, cwd, timeoutMs);
+    const ok = claimed.exitCode === 0 && actual.exitCode === claimed.exitCode;
+    checks.push({
+      name,
+      command: claimed.command,
+      claimedExitCode: claimed.exitCode,
+      actualExitCode: actual.exitCode,
+      ok
+    });
+  }
+  if (checks.length === 0) return { status: "missing", checks };
+  const status = checks.every((c) => c.ok) ? "verified" : "failed";
+  return { status, checks };
+}
+
 // src/chimera-review-task.ts
 import { parseReviewSeverity } from "@wrongstack/core/plugin";
 function truncateAtCodePointBoundary(text, maxCodeUnits) {
@@ -2846,6 +2969,34 @@ function buildChimeraReviewTaskDescription(p) {
   lines.push("structured review report.");
   return lines.join("\n");
 }
+var CASCADE_EVIDENCE_INSTRUCTIONS = [
+  `After fixing, run the project's REAL verification commands on the code you changed`,
+  `(typecheck, lint, and the tests covering the fixed code) and return a machine-evidence`,
+  `block as the LAST section of your response. The block MUST be a fenced JSON block`,
+  `(exactly \`\`\`json ... \`\`\`) with this shape:`,
+  ``,
+  "```json",
+  "{",
+  '  "verification_evidence": {',
+  '    "typecheck": { "command": "pnpm typecheck", "exitCode": 0 },',
+  '    "lint":      { "command": "pnpm lint", "exitCode": 0 },',
+  '    "tests":     { "command": "pnpm test --filter affected", "exitCode": 0 }',
+  "  }",
+  "}",
+  "```",
+  ``,
+  `Rules:`,
+  `- \`command\` must be the EXACT command you ran (plain executable + args, no shell`,
+  `  chaining like \`&&\`/\`;\`/\`|\`, no redirection, no shell expansion). These commands are`,
+  `  re-run verbatim by the orchestrator to verify your work.`,
+  `- \`exitCode\` is the real process exit code you observed: 0 = passed, non-zero = failed.`,
+  `  Never invent or omit an exit code. If a command cannot be run, omit that key entirely`,
+  `  and explain why in your report text \u2014 an omitted key is honest, a fabricated 0 is not.`,
+  `- If your fix does not pass a command, report the true non-zero exit code; the`,
+  `  orchestrator will treat the fix as unverified and keep the finding open.`,
+  `- At least \`typecheck\` must be present; include \`lint\` and \`tests\` when the project`,
+  `  has them.`
+].join("\n");
 function buildChimeraCascadeTaskDescription(agentKind, p) {
   const fileList = p.bundle.files.map((f) => `- ${f.path}`).join("\n");
   const reportSlice = truncateAtCodePointBoundary(p.reviewText, 12e3);
@@ -2866,8 +3017,9 @@ function buildChimeraCascadeTaskDescription(agentKind, p) {
       `Investigate the security findings above. Read the flagged files, confirm or refute`,
       `each finding, and **apply fixes** for confirmed vulnerabilities using the edit tool.`,
       `Use severity (Critical/High/Medium), file:line citations, and remediation steps.`,
-      `After fixing, run the project's typecheck and linter to verify. If a finding is a`,
-      `false positive, say so and do not modify the file.`
+      `If a finding is a false positive, say so and do not modify the file.`,
+      ``,
+      CASCADE_EVIDENCE_INSTRUCTIONS
     ].join("\n");
   }
   return [
@@ -2884,9 +3036,10 @@ function buildChimeraCascadeTaskDescription(agentKind, p) {
     ``,
     `Hunt for the bugs flagged above. Read the affected files, trace each finding to its`,
     `root cause, and **apply minimal fixes** for confirmed bugs using the edit tool.`,
-    `Use severity (Critical/High/Medium), file:line citations. After fixing, run the`,
-    `project's typecheck and linter to verify. If a finding is a false positive, say so`,
-    `and do not modify the file.`
+    `Use severity (Critical/High/Medium), file:line citations. If a finding is a false`,
+    `positive, say so and do not modify the file.`,
+    ``,
+    CASCADE_EVIDENCE_INSTRUCTIONS
   ].join("\n");
 }
 
@@ -3003,7 +3156,9 @@ function installChimeraCascadeHandler({
   session,
   getPendingWork,
   trackWork,
-  buildLadder
+  buildLadder,
+  verifyEvidence = verifyCascadeEvidence,
+  persistEvidence
 }) {
   events.onPattern("chimera.cascade_needed", (_event, payload) => {
     const p = payload;
@@ -3016,6 +3171,7 @@ function installChimeraCascadeHandler({
         await previousWork;
       } catch {
       }
+      const agentEvidence = [];
       for (const agentKind of p.agents) {
         try {
           const taskDesc = buildChimeraCascadeTaskDescription(agentKind, p);
@@ -3059,6 +3215,10 @@ function installChimeraCascadeHandler({
           const result = outcome.result;
           if (result?.status === "success") {
             const resultText = typeof result.result === "string" ? result.result : JSON.stringify(result.result);
+            const claimed = extractCascadeEvidence(resultText);
+            if (claimed) {
+              agentEvidence.push({ agentKind, evidence: claimed });
+            }
             await session.append({
               type: "llm_response",
               ts: (/* @__PURE__ */ new Date()).toISOString(),
@@ -3089,7 +3249,21 @@ function installChimeraCascadeHandler({
           });
         }
       }
-      await maybeReReviewCascade({ events, session, bundle: p.bundle });
+      const accumulatedEvidence = {};
+      for (const { evidence } of agentEvidence) {
+        for (const name of ["typecheck", "lint", "tests"]) {
+          if (evidence[name]) accumulatedEvidence[name] = evidence[name];
+        }
+      }
+      await maybeReReviewCascade({
+        events,
+        session,
+        bundle: p.bundle,
+        reportId: p.reportId,
+        claimedEvidence: accumulatedEvidence,
+        verifyEvidence,
+        persistEvidence
+      });
     })();
     trackWork(pendingWork);
   });
@@ -3097,16 +3271,71 @@ function installChimeraCascadeHandler({
 async function maybeReReviewCascade({
   events,
   session,
-  bundle
+  bundle,
+  reportId,
+  claimedEvidence,
+  verifyEvidence,
+  persistEvidence
 }) {
   const maxDepth = bundle.maxCascadeDepth ?? 0;
   const currentDepth = bundle.cascadeDepth ?? 0;
+  const hasClaimedEvidence = Object.keys(claimedEvidence).length > 0;
+  const verification = hasClaimedEvidence ? await verifyEvidence(
+    claimedEvidence,
+    bundle.cwd,
+    void 0,
+    CASCADE_EVIDENCE_COMMAND_TIMEOUT_MS
+  ) : { status: "missing", checks: [] };
+  const evidenceBundle = {
+    ...bundle,
+    evidenceStatus: verification.status,
+    evidenceChecks: verification.checks
+  };
+  if (reportId && persistEvidence) {
+    try {
+      await persistEvidence(reportId, verification.status, verification.checks);
+    } catch (error) {
+      await session.append({
+        type: "error",
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        message: `Chimera cascade evidence persistence failed: ${errorText2(error)}`,
+        phase: "agent"
+      });
+    }
+  }
+  await session.append({
+    type: "llm_response",
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    content: [
+      {
+        type: "text",
+        text: renderEvidenceSummary(verification.status, verification.checks)
+      }
+    ],
+    stopReason: "end_turn",
+    usage: { input: 0, output: 0 }
+  });
+  if (verification.status !== "verified") {
+    await session.append({
+      type: "llm_response",
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      content: [
+        {
+          type: "text",
+          text: `\u{1F982} Chimera cascade evidence ${verification.status} \u2014 fix not confirmed, skipping re-review. Findings remain open.`
+        }
+      ],
+      stopReason: "end_turn",
+      usage: { input: 0, output: 0 }
+    });
+    return;
+  }
   if (maxDepth > 0 && currentDepth < maxDepth) {
     try {
       const reReadFiles = [];
-      for (const f of bundle.files) {
+      for (const f of evidenceBundle.files) {
         try {
-          const absPath = path10.join(bundle.cwd, f.path);
+          const absPath = path10.join(evidenceBundle.cwd, f.path);
           const content = await fsp.readFile(absPath, "utf8");
           reReadFiles.push({ path: f.path, status: "modified", content });
         } catch {
@@ -3114,7 +3343,7 @@ async function maybeReReviewCascade({
       }
       if (reReadFiles.length > 0) {
         const reReviewBundle = {
-          ...bundle,
+          ...evidenceBundle,
           files: reReadFiles,
           cascadeDepth: currentDepth + 1
         };
@@ -3172,18 +3401,28 @@ async function maybeReReviewCascade({
     });
   }
 }
+function renderEvidenceSummary(status, checks) {
+  if (status === "missing") return "no machine evidence supplied";
+  const summary = checks.map((check) => `${check.name}:${check.ok ? "pass" : "fail"}(${check.actualExitCode})`).join(", ");
+  return `${status}${summary ? ` \u2014 ${summary}` : ""}`;
+}
+function errorText2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
 
 // src/execution-chimera-review.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
 import path11 from "node:path";
-import { effectiveFallbackChain } from "@wrongstack/core/agent";
+import { effectiveFallbackChain, fallbackProfileChain as fallbackProfileChain2 } from "@wrongstack/core/agent";
 import {
   CHIMERA_REVIEW_PROMPT,
+  classifyChimeraReviewSource,
   integrateFindings,
   maybeCompactReviewStores,
   parseChimeraReviewReport,
   persistReviewReport,
-  recordCompletedReview
+  recordCompletedReview,
+  verifyFindingsAgainstDisk
 } from "@wrongstack/core/plugin";
 function normalizeFileKeyForCitation(raw, cwd) {
   const forward = raw.replace(/\\/g, "/").replace(/^\.\//, "");
@@ -3267,7 +3506,13 @@ function installChimeraReviewHandler({
           const rawModel = p.reviewFallbackModels ? p.config.model?.trim() || void 0 : tModel;
           const baseProvider = rawProvider || tProvider || config.provider;
           const baseModel = rawModel || tModel || config.model;
-          const baseFallbacks = p.reviewFallbackModels ? [...p.reviewFallbackModels] : resolveReviewerFallbackModels(void 0);
+          const configFallbacks = [...p.config.fallbackModels ?? []];
+          if (p.config.fallbackProfile) {
+            configFallbacks.push(...fallbackProfileChain2(config, p.config.fallbackProfile));
+          }
+          const baseFallbacks = p.reviewFallbackModels ? [...p.reviewFallbackModels] : resolveReviewerFallbackModels(
+            configFallbacks.length > 0 ? configFallbacks : void 0
+          );
           const assigned = assignReviewerModels(
             baseProvider,
             baseModel,
@@ -3368,18 +3613,34 @@ function installChimeraReviewHandler({
           }
           const reviewText = typeof result.result === "string" ? result.result.trim() : JSON.stringify(result.result);
           const reportId = randomUUID3();
+          const reviewSource = classifyChimeraReviewSource(p);
+          const winningAttempt = outcome.wonAt ? ladder[outcome.wonAt - 1] : void 0;
+          const parsedReport = parseChimeraReviewReport(reviewText, {
+            sessionId: reviewSessionId,
+            agentId: p.fileProvenance?.find((entry) => entry.agentId)?.agentId ?? "chimera-review",
+            reviewerModel: winningAttempt ? attemptLabel(winningAttempt) : void 0,
+            reviewType: reviewSource,
+            reportId
+          });
+          const verifiedFindings = await verifyFindingsAgainstDisk(parsedReport.findings, {
+            cwd: p.cwd
+          });
+          const verifiedParsedReport = {
+            ...parsedReport,
+            findings: verifiedFindings
+          };
           await persistAndEmitCompletion({
             bundle: p,
             reviewText,
             status: "success",
             cwd: p.cwd,
             sessionId: reviewSessionId,
-            reportId
+            reportId,
+            parsedReport: verifiedParsedReport
           });
           if (reviewText) {
             const reviewHasFindings = !isChimeraAllClearReview(reviewText);
-            const parsedReview = parseChimeraReviewReport(reviewText);
-            const citedFindings = parsedReview.findings.filter((finding) => finding.location);
+            const citedFindings = verifiedFindings.filter((finding) => finding.location);
             const citedPaths = new Set(
               p.files.map((file) => normalizeFileKeyForCitation(file.path, p.cwd))
             );
@@ -3391,14 +3652,28 @@ function installChimeraReviewHandler({
               if (bucket) bucket.push(normalized);
               else changedBasenameIndex.set(basename7, [normalized]);
             }
-            const droppedCitations = citedFindings.filter((finding) => {
+            const inScopeCited = citedFindings.filter((finding) => {
               const citedKey = normalizeFileKeyForCitation(finding.location.file, p.cwd);
-              if (citedPaths.has(citedKey)) return false;
+              if (citedPaths.has(citedKey)) return true;
               const basename7 = path11.basename(finding.location.file).toLowerCase();
               const bucket = changedBasenameIndex.get(basename7);
-              return !(bucket && bucket.length === 1);
+              return !!(bucket && bucket.length === 1);
             });
-            const effectiveHasFindings = reviewHasFindings && (parsedReview.findings.length === 0 || parsedReview.findings.length > droppedCitations.length);
+            const droppedCitations = citedFindings.filter(
+              (finding) => !inScopeCited.includes(finding)
+            );
+            const actionableFindings = inScopeCited.filter(
+              (finding) => finding.verification?.status === "verified"
+            );
+            const unverifiedInScope = inScopeCited.filter(
+              (finding) => finding.verification?.status === "unverified"
+            );
+            const failedVerificationCount = inScopeCited.filter(
+              (finding) => finding.verification?.status === "failed"
+            ).length;
+            const effectiveHasFindings = reviewHasFindings && actionableFindings.length > 0;
+            const verifiedCount = actionableFindings.length;
+            const unverifiedCount = unverifiedInScope.length;
             const hallucinationNote = droppedCitations.length > 0 ? `
 
 \u26A0\uFE0F Citation validation: ${droppedCitations.length} finding(s) cite files outside the changed-file set and should be verified before acting.` : "";
@@ -3441,7 +3716,7 @@ ${reviewBody}`;
                 reviewLength: reviewText.length,
                 messageId: reviewMailMessageId
               });
-              if (!effectiveHasFindings) {
+              if (!reviewHasFindings) {
                 try {
                   await mailbox.ack({
                     messageId: reviewMailMessageId,
@@ -3485,11 +3760,8 @@ ${reviewBody}`;
                 phase: "agent"
               });
             }
-            const findingCount = Math.max(
-              0,
-              parsedReview.findings.length - droppedCitations.length
-            );
-            const message = effectiveHasFindings ? `\u{1F982} Chimera report ready \u2014 ${findingCount || "unparsed"} potential finding(s) across ${p.files.length} file(s). No follow-up started; open the mailbox and explicitly ask the leader to act if wanted.` : `\u{1F982} Chimera report ready \u2014 ${p.files.length} file(s) checked, no actionable findings. No follow-up started.`;
+            const findingCount = actionableFindings.length;
+            const message = effectiveHasFindings ? `\u{1F982} Chimera report ready \u2014 ${findingCount || "unparsed"} potential finding(s) (${verifiedCount} verified against disk, ${unverifiedCount} unverified, ${failedVerificationCount} failed) across ${p.files.length} file(s). No follow-up started; open the mailbox and explicitly ask the leader to act if wanted.` : `\u{1F982} Chimera report ready \u2014 ${p.files.length} file(s) checked, no actionable findings. No follow-up started.`;
             events.emitCustom("chimera.report_available", {
               reportId,
               sessionId: reviewSessionId,
@@ -3711,7 +3983,7 @@ function parseSuggestionsFromOutput(finalText, todos) {
     setAutoSuggestions([]);
     return null;
   }
-  const { texts, autoTexts } = parseNextSteps(finalText, false);
+  const { texts, autoTexts } = parseNextSteps(finalText);
   if (autoTexts.length > 0) {
     setAutoSuggestions(autoTexts);
   }
@@ -4909,6 +5181,9 @@ async function execute(deps) {
       session: { provider: config.provider, model: config.model }
     }),
     getPendingWork: () => chimeraWork.pending(),
+    persistEvidence: async (reportId, status, checks) => {
+      await updateReviewReportEvidence(reportId, wpaths.projectDir, status, checks);
+    },
     trackWork: (work) => {
       chimeraWork.track(work);
     }
@@ -5347,4 +5622,4 @@ export {
   execute,
   resolveReviewerFallbackModels
 };
-//# sourceMappingURL=execution-QYFWDD3Y.js.map
+//# sourceMappingURL=execution-TTE7R5UY.js.map

package/dist/execution-chimera-cascade.d.ts

@@ -1,3 +1,5 @@
+import type { CascadeEvidenceCheckResult, CascadeEvidenceStatus } from '@wrongstack/core/plugin';
+import { verifyCascadeEvidence } from './chimera-cascade-evidence.js';
 import type { ReviewerAttempt } from './chimera-reviewer-policy.js';
 import type { ExecuteDeps } from './execute-deps.js';
 type Director = NonNullable<ExecuteDeps['fleet']['director']>;
@@ -14,7 +16,11 @@ export type InstallChimeraCascadeHandlerOptions = {
      * holds the live config. Omit to keep the single unpinned spawn.
      */
     buildLadder?: (() => ReviewerAttempt[]) | undefined;
+    /** Test seam; production defaults to the real safe command verifier. */
+    verifyEvidence?: typeof verifyCascadeEvidence | undefined;
+    /** Persist every evidence verdict on the source report, even when re-review stops. */
+    persistEvidence?: ((reportId: string, status: CascadeEvidenceStatus, checks: CascadeEvidenceCheckResult[]) => Promise<void>) | undefined;
 };
-export declare function installChimeraCascadeHandler({ events, director, session, getPendingWork, trackWork, buildLadder, }: InstallChimeraCascadeHandlerOptions): void;
+export declare function installChimeraCascadeHandler({ events, director, session, getPendingWork, trackWork, buildLadder, verifyEvidence, persistEvidence, }: InstallChimeraCascadeHandlerOptions): void;
 export {};
 //# sourceMappingURL=execution-chimera-cascade.d.ts.map

package/dist/{hq-5G6D5YIU.js → hq-ZK6PGN3W.js}

@@ -1,9 +1,9 @@
-import {
-  resolveAuditActor
-} from "./chunk-Q5GTM25S.js";
 import {
   parseTokenTtlValue
 } from "./chunk-BGFM3PD7.js";
+import {
+  resolveAuditActor
+} from "./chunk-Q5GTM25S.js";
 import "./chunk-7OCVIDC7.js";
 
 // src/subcommands/handlers/hq.ts
@@ -28,6 +28,10 @@ function resolveDataDir(deps) {
 }
 var hqCmd = async (args, deps) => {
   const sub = args[0];
+  if (deps.flags?.["help"] === true && (!sub || sub === "serve")) {
+    printHelp(deps);
+    return 0;
+  }
   if (!sub || sub === "serve") {
     return startServer(deps);
   }
@@ -160,6 +164,10 @@ HQ auth loaded from ${handle.firstRunSetup.dataDir}
 }
 async function hqTokenCmd(args, deps) {
   const action = args[0];
+  if (deps.flags?.["help"] === true || action === "help" || action === "--help") {
+    printTokenHelp(deps);
+    return 0;
+  }
   if (action === "create") {
     return tokenCreate(args.slice(1), deps);
   }
@@ -171,17 +179,21 @@ async function hqTokenCmd(args, deps) {
   }
   deps.renderer.writeError(`Unknown hq token subcommand: ${action ?? "(none)"}
 `);
-  deps.renderer.write("Usage: wstack hq token <create|list|revoke>\n");
+  printTokenHelp(deps);
   return 1;
 }
 async function hqAuditCmd(args, deps) {
   const action = args[0];
+  if (deps.flags?.["help"] === true || action === "help" || action === "--help") {
+    printAuditHelp(deps);
+    return 0;
+  }
   if (action === "verify" || action === void 0) {
     return hqAuditVerify(deps);
   }
   deps.renderer.writeError(`Unknown hq audit subcommand: ${action ?? "(none)"}
 `);
-  deps.renderer.write("Usage: wstack hq audit <verify>\n");
+  printAuditHelp(deps);
   return 1;
 }
 async function hqAuditVerify(deps) {
@@ -608,8 +620,85 @@ function printHelp(deps) {
   deps.renderer.write(`auth.json schema version: ${HQ_AUTH_FILE_VERSION}.
 `);
 }
+function printTokenHelp(deps) {
+  deps.renderer.write(`Usage: wstack hq token <create | list | revoke>
+`);
+  deps.renderer.write("\n");
+  deps.renderer.write(
+    `  wstack hq token create [label] [--ttl <dur>]          Mint a browser token (enters token mode).
+`
+  );
+  deps.renderer.write(
+    `  wstack hq token create --client [label] [--ttl <dur>] Mint a client token (/ws/client).
+`
+  );
+  deps.renderer.write(`  wstack hq token list                                 List issued browser tokens (alias: ls).
+`);
+  deps.renderer.write(`  wstack hq token list --client                         List issued client tokens.
+`);
+  deps.renderer.write(
+    `  wstack hq token revoke <id>                           Revoke a browser token (id prefix match).
+`
+  );
+  deps.renderer.write(`  wstack hq token revoke --client <id>                  Revoke a client token.
+`);
+  deps.renderer.write("\n");
+  deps.renderer.write(`The token secret is printed once at create time and cannot be recovered
+`);
+  deps.renderer.write(`from auth.json (only its SHA-256 verifier is persisted). Tokens live in
+`);
+  deps.renderer.write(`<dataDir>/auth.json (default ~/.wrongstack/hq/auth.json).
+`);
+  deps.renderer.write("\n");
+  deps.renderer.write(`Flags:
+`);
+  deps.renderer.write(
+    `  --data-dir <path>   Override HQ data directory (default ~/.wrongstack/hq).
+`
+  );
+  deps.renderer.write(`  --client, -c        Operate on client tokens instead of browser tokens.
+`);
+  deps.renderer.write(
+    `  --capabilities <csv>  Comma-separated capability grants (browser: control.enqueue; client: telemetry.publish,control.execute).
+`
+  );
+  deps.renderer.write(
+    `  --ttl <duration>    Stamp an expiresAt on the token (e.g. --ttl 1h, --ttl 7d, --ttl 3600s).
+`
+  );
+  deps.renderer.write("\n");
+  deps.renderer.write(`Run \`wstack hq --help\` for the full HQ command list.
+`);
+}
+function printAuditHelp(deps) {
+  deps.renderer.write(`Usage: wstack hq audit <verify>
+`);
+  deps.renderer.write("\n");
+  deps.renderer.write(
+    `  wstack hq audit verify   Re-derive the SHA-256 contentHash from the current
+`
+  );
+  deps.renderer.write(
+    `                           auth.json and print it so an operator can compare
+`
+  );
+  deps.renderer.write(
+    `                           it against a contentHash field in an audit-log entry.
+`
+  );
+  deps.renderer.write("\n");
+  deps.renderer.write(`Flags:
+`);
+  deps.renderer.write(
+    `  --data-dir <path>   Override HQ data directory (default ~/.wrongstack/hq).
+`
+  );
+  deps.renderer.write("\n");
+  deps.renderer.write(`Run \`wstack hq --help\` for the full HQ command list.
+`);
+}
 export {
   hqCmd,
   resolveAuditActor
 };
-//# sourceMappingURL=hq-5G6D5YIU.js.map
+//# sourceMappingURL=hq-ZK6PGN3W.js.map