@wrongstack/cli 0.305.1 → 0.306.0

package/dist/{auth-EPERLKYI.js → auth-GVPYLJPS.js}

@@ -13,15 +13,12 @@ import {
   runOAuthLoginKind,
   runOAuthLoginMenu,
   validateFamily
-} from "./chunk-5KFLLTSQ.js";
-import "./chunk-SSSJQVUY.js";
-import {
-  restoreFlags
-} from "./chunk-CSAPOCBP.js";
+} from "./chunk-WC3DK6BI.js";
 import {
   parseAuthFlags
-} from "./chunk-2H47YMCV.js";
+} from "./chunk-5JW3XCRA.js";
 import "./chunk-3IC4IEZC.js";
+import "./chunk-SSSJQVUY.js";
 import {
   loadConfigProviders,
   maskedKey,
@@ -30,6 +27,9 @@ import {
   nowIso,
   writeKeysBack
 } from "./chunk-SZ42FYPT.js";
+import {
+  restoreFlags
+} from "./chunk-CSAPOCBP.js";
 import "./chunk-B4JLSXZB.js";
 import {
   activeProfileConfigPath
@@ -657,4 +657,4 @@ async function runAuthRemove(deps, providerId) {
 export {
   authCmd
 };
-//# sourceMappingURL=auth-EPERLKYI.js.map
+//# sourceMappingURL=auth-GVPYLJPS.js.map

package/dist/boot/short-circuit-flags.d.ts

@@ -1,9 +1,15 @@
 /**
  * Check argv for --help / --version and dispatch directly.
  *
- * Returns 0 when a flag fired, or null when neither was present.
+ * Returns 0 when a flag fired, or null when neither flag was present.
  * The renderer is a stub that writes to stdout — help text is plain
  * `write` calls, no TTY needed.
+ *
+ * When `--help` accompanies a known subcommand positional (e.g.
+ * `wstack hq --help`), this defers to the subcommand dispatcher
+ * (returns null) so the subcommand can print its own focused help.
+ * `--version` always fires globally — the CLI version is not
+ * subcommand-specific.
  */
 export declare function handleHelpVersionShortCircuit(argv: string[]): Promise<number | null>;
 //# sourceMappingURL=short-circuit-flags.d.ts.map

package/dist/boot/system-prompt-menu.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Interactive system-prompt selection menu — Lite / Standard / Pro.
+ *
+ * Shown at startup when the user did not pin a variant via
+ * `--system-lite`, `--system-pro`, or `--system-prompt <variant>`.
+ * Each option displays the estimated token count of the identity block
+ * that variant injects (resolved through the same bundled → global →
+ * project instruction dirs the SystemPromptBuilder uses, so a project
+ * or profile override is reflected in the count).
+ *
+ * Flow mirrors `runLaunchPrompts`:
+ *   - no saved variant (first run)      → show the numbered menu directly
+ *   - saved variant exists              → one-line "Continue with these?"
+ *     gate; `n` opens the full menu, `q` aborts the launch
+ *   - the caller persists the selection via `persistSystemPromptVariant`
+ *     so the next boot can offer the gate instead of re-asking.
+ *
+ * `q` at any prompt throws `LaunchAbortedError` (the same cancellation
+ * contract as the launch prompts), and the caller in boot.ts exits 0.
+ */
+import { type SystemInstructionVariant } from '@wrongstack/core/agent';
+import type { ReadlineInputReader } from '../input-reader.js';
+import type { TerminalRenderer } from '../renderer.js';
+/** Menu order + display labels. `default` is shown as "Standard". */
+export declare const SYSTEM_PROMPT_OPTIONS: ReadonlyArray<{
+    variant: SystemInstructionVariant;
+    label: string;
+    hint: string;
+}>;
+/** All selectable variants, in menu order. */
+export declare const SYSTEM_PROMPT_VARIANTS: readonly SystemInstructionVariant[];
+/** Instruction dirs used to resolve the identity text per variant. */
+export interface SystemPromptMenuPaths {
+    /** Profile override directory, e.g. `~/.wrongstack/profiles/<name>/instructions`. */
+    globalDir?: string | undefined;
+    /** Project override directory, e.g. `<project>/.wrongstack/instructions`. */
+    projectDir?: string | undefined;
+}
+/** True when any `--system-*` flag pins a variant (menu must not show). */
+export declare function isSystemPromptPinned(flags: Record<string, string | boolean>): boolean;
+/**
+ * Pure predicate — when to skip the system-prompt menu entirely. The boot
+ * caller additionally gates on interactive-TTY conditions; this covers the
+ * flag-level reasons so scripts can opt out with `--no-menu`/`--skip` and
+ * flag-pinned launches never prompt.
+ */
+export declare function shouldSkipSystemPromptMenu(flags: Record<string, string | boolean>): boolean;
+/**
+ * Estimate the tokens of the system identity block each variant injects.
+ *
+ * Resolution goes through the same `loadInstructionBundle` the
+ * SystemPromptBuilder runs (bundled → global → project, later layers override
+ * `system.identity`), and composition goes through the builder's own
+ * `buildIdentityLayer`. Calling the real composer matters: when the identity
+ * came from the *project* layer, WS-016 makes the builder emit the bundled
+ * identity PLUS a `<project-supplied-instructions>` delimiter block PLUS the
+ * project text rather than replacing the identity. Counting
+ * `bundle.system.identity` alone therefore under-reports a project override by
+ * the whole bundled prompt — which is exactly the case a repo that ships its
+ * own `system-pro.md` hits.
+ *
+ * The figure is an **upper bound**, not `/context` parity: `buildIdentityLayer`
+ * is called without an `InstructionTemplateContext`, which by its own contract
+ * keeps the full text, so `ws:if` blocks for tools the live request never
+ * registers are still counted. Erring high is the right direction for a menu
+ * whose purpose is comparing variant cost, and every figure is rendered with a
+ * leading `~`.
+ */
+export declare function countSystemPromptTokens(paths: SystemPromptMenuPaths): Promise<Record<SystemInstructionVariant, number>>;
+/**
+ * Read the variant the user explicitly saved to the profile config file.
+ *
+ * The config loader materializes `systemPrompt: { variant: 'default' }` for
+ * every config (see `@wrongstack/core` config-loader defaults), so the
+ * in-memory Config cannot distinguish "user chose Standard" from "never
+ * chose". Only the raw file can: {@link persistSystemPromptVariant} writes
+ * the key explicitly, so its presence on disk is the signal that a selection
+ * was made. Absence (first run, or a config edited before this feature
+ * existed) returns undefined and the caller shows the full menu instead of
+ * the summary gate.
+ */
+export declare function readSavedSystemPromptVariant(configPath: string): Promise<SystemInstructionVariant | undefined>;
+/**
+ * Run the interactive system-prompt selection. Returns the chosen variant.
+ * Throws {@link LaunchAbortedError} when the user presses `q` (the caller
+ * exits 0, matching the launch-prompts contract).
+ *
+ * @throws LaunchAbortedError when the user cancels.
+ */
+export declare function runSystemPromptMenu(deps: {
+    renderer: TerminalRenderer;
+    reader: ReadlineInputReader;
+    paths: SystemPromptMenuPaths;
+    /** Saved variant from config — enables the summary gate. */
+    lastVariant?: SystemInstructionVariant | undefined;
+}): Promise<SystemInstructionVariant>;
+/**
+ * Persist the chosen variant to the profile config file so the next boot
+ * can offer a one-line "Continue with these?" gate. Mirrors
+ * `persistLaunchChoices`: reads the existing JSON, mutates only the
+ * `systemPrompt` block, writes back atomically with mode 0600. Other fields
+ * (including encrypted secrets) pass through round-trip unchanged.
+ *
+ * @throws when the config file exists but is corrupt (same policy as the
+ * launch-choices writer — never overwrite unreadable user config silently).
+ */
+export declare function persistSystemPromptVariant(configPath: string, variant: SystemInstructionVariant): Promise<void>;
+/** Outcome of {@link maybeRunSystemPromptMenu}. */
+export interface SystemPromptMenuOutcome {
+    /**
+     * The variant the user selected, or `undefined` when the menu did not run
+     * (non-TTY / flag-skipped) or was aborted. `undefined` means "caller must
+     * not patch config" — it is not a synonym for `'default'`.
+     */
+    variant?: SystemInstructionVariant | undefined;
+    /** True when the user pressed `q`. The caller should exit cleanly. */
+    aborted: boolean;
+    /** True when the selection differs from what was saved on disk. */
+    changed: boolean;
+    /** Set when persistence failed; the caller surfaces it as a warning. */
+    persistError?: unknown;
+}
+/**
+ * The real enforcement point for the startup system-prompt menu.
+ *
+ * `isInteractiveTTY` is an explicit **parameter**, not read from
+ * `process.stdin` — that is the entire reason this function exists. While the
+ * gate lived as a bare `if (isInteractiveTTY)` wrapping an inline block in
+ * `boot.ts`, no test could reach it: the only importable symbol was
+ * `shouldSkipSystemPromptMenu`, which covers the *flag-level* reasons and is
+ * nested one level deeper. Coverage therefore stopped at the predicate and
+ * never touched the condition that actually suppresses the prompt.
+ *
+ * Behavior is intentionally identical to the inline block it replaces:
+ *   - non-TTY or flag-skipped  → return early, touch nothing, read nothing
+ *   - `q` at the prompt        → `aborted: true` (caller closes + exits 0)
+ *   - selection === saved      → `changed: false`, no config write
+ *   - persistence throws       → captured in `persistError`, never rethrown
+ *
+ * Persistence failure is deliberately non-fatal: a read-only config must not
+ * prevent the session from starting.
+ */
+export declare function maybeRunSystemPromptMenu(opts: {
+    isInteractiveTTY: boolean;
+    flags: Record<string, string | boolean>;
+    renderer: TerminalRenderer;
+    reader: ReadlineInputReader;
+    profileConfigPath: string;
+    paths: SystemPromptMenuPaths;
+}): Promise<SystemPromptMenuOutcome>;
+//# sourceMappingURL=system-prompt-menu.d.ts.map

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

@@ -0,0 +1,102 @@
+/**
+ * Machine-evidence contract for Chimera cascade fix agents (P0-3).
+ *
+ * Cascade agents (security-scanner / bug-hunter) must apply fixes and then
+ * run the project's real verification commands (typecheck / lint / tests),
+ * returning a structured JSON evidence block:
+ *
+ * ```json
+ * {
+ *   "verification_evidence": {
+ *     "typecheck": { "command": "pnpm typecheck", "exitCode": 0 },
+ *     "lint":      { "command": "pnpm lint", "exitCode": 0 },
+ *     "tests":     { "command": "pnpm test --filter affected", "exitCode": 0 }
+ *   }
+ * }
+ * ```
+ *
+ * The cascade handler extracts this block and, before the re-review step,
+ * re-runs the claimed commands against the working tree with a safe runner
+ * (plain spawn, no shell, allowlisted executables) and compares the observed
+ * exit codes. A fix only counts as verified when every claimed check ran and
+ * its exit code matches reality.
+ *
+ * @module chimera-cascade-evidence
+ */
+import type { CascadeEvidenceCheckResult, CascadeEvidenceStatus } from '@wrongstack/core/plugin';
+export type { CascadeEvidenceCheckResult, CascadeEvidenceStatus, } from '@wrongstack/core/plugin';
+/** One claimed verification check: the exact command and its observed exit code. */
+export interface CascadeEvidenceCheck {
+    command: string;
+    exitCode: number;
+    /** Optional truncated output the agent chose to include (informational). */
+    output?: string | undefined;
+}
+/** The three standard verification checks a cascade agent can claim. */
+export interface CascadeEvidence {
+    typecheck?: CascadeEvidenceCheck | undefined;
+    lint?: CascadeEvidenceCheck | undefined;
+    tests?: CascadeEvidenceCheck | undefined;
+}
+/** Result of verifying a cascade agent's claimed evidence. */
+export interface CascadeEvidenceVerification {
+    status: CascadeEvidenceStatus;
+    checks: CascadeEvidenceCheckResult[];
+}
+/**
+ * Extract a `verification_evidence` block from a cascade agent's response.
+ *
+ * Scans every fenced ```json block in the text and returns the first that
+ * parses as an object with a `verification_evidence` member whose value is an
+ * object of `{command, exitCode}` checks. Any malformed JSON fence is ignored
+ * (the agent may have used a fence for something else); when the evidence is
+ * genuinely absent, returns null so the caller can treat it as `missing`.
+ *
+ * The returned evidence is validated but NOT sanitized here — command safety
+ * is enforced by the verification runner (allowlist + no shell).
+ */
+export declare function extractCascadeEvidence(text: string | null | undefined): CascadeEvidence | null;
+/**
+ * Maximum wall-clock per verification command. Verification must never turn
+ * the cascade re-review into an unbounded wait, so a hung command is killed
+ * and reported as a mismatch (like a non-zero exit).
+ */
+export declare const CASCADE_EVIDENCE_COMMAND_TIMEOUT_MS = 120000;
+/** Exit code used when the re-run is refused (unsafe command). */
+export declare const CASCADE_EVIDENCE_UNSAFE_EXIT = 126;
+/** Exit code used when the re-run times out or cannot execute. */
+export declare const CASCADE_EVIDENCE_RUN_ERROR_EXIT = 127;
+export interface RunCommandResult {
+    exitCode: number;
+}
+export type RunCommandFn = (command: string, cwd: string, timeoutMs: number) => Promise<RunCommandResult>;
+/**
+ * Validate a claimed command against the safety contract: first token must be
+ * an allowlisted executable and every token must be a bare word/path (no shell
+ * metacharacters). Shell-free spawning is the second layer — even a validated
+ * command is run with `shell: false`.
+ */
+export declare function isSafeCascadeCommand(command: string): boolean;
+/**
+ * Run a single verification command against the working tree without a shell.
+ * Never throws — every failure mode (unsafe, timeout, spawn error) resolves to
+ * an exit code so the caller's comparison stays uniform.
+ */
+export declare const runCascadeVerificationCommand: RunCommandFn;
+/**
+ * Verify a cascade agent's claimed evidence by re-running each command against
+ * the working tree and comparing exit codes.
+ *
+ * Verdict rules:
+ *  - `missing`   — no evidence block was extracted (agent returned no checks).
+ *  - `verified`  — every claimed check re-ran, actual exit code matched the
+ *                  claim, and the claimed exit code was 0 (a passing check).
+ *  - `failed`    — any check was refused (unsafe), could not run, timed out,
+ *                  claimed a non-zero exit code, or actual ≠ claimed.
+ *
+ * An unsafe command is refused rather than executed — a cascade agent cannot
+ * make the orchestrator run arbitrary shell through a fabricated evidence
+ * block.
+ */
+export declare function verifyCascadeEvidence(evidence: CascadeEvidence | null | undefined, cwd: string, runCommand?: RunCommandFn, timeoutMs?: number): Promise<CascadeEvidenceVerification>;
+//# sourceMappingURL=chimera-cascade-evidence.d.ts.map

package/dist/chimera-review-task.d.ts

@@ -2,5 +2,12 @@ import type { CascadeAgentKind, ChimeraCascadeNeededPayload, ChimeraReviewNeeded
 export declare function truncateAtCodePointBoundary(text: string, maxCodeUnits: number): string;
 export declare function isChimeraAllClearReview(text: string): boolean;
 export declare function buildChimeraReviewTaskDescription(p: ChimeraReviewNeededPayload): string;
+/**
+ * The machine-evidence contract every cascade fix agent must satisfy before
+ * its work counts as verified. The agent runs the real verification commands
+ * and returns a JSON block with the exact commands and their exit codes; the
+ * re-review step re-runs those commands and compares.
+ */
+export declare const CASCADE_EVIDENCE_INSTRUCTIONS: string;
 export declare function buildChimeraCascadeTaskDescription(agentKind: CascadeAgentKind, p: ChimeraCascadeNeededPayload): string;
 //# sourceMappingURL=chimera-review-task.d.ts.map

package/dist/{chunk-2H47YMCV.js → chunk-5JW3XCRA.js}

@@ -131,7 +131,7 @@ function parseArgs(argv) {
       }
     } else if (a.startsWith("-") && a.length === 2) {
       const short = a.slice(1);
-      const expand = { v: "verbose", y: "yes" };
+      const expand = { v: "verbose", y: "yes", h: "help" };
       flags[expand[short] ?? short] = true;
     } else {
       positional.push(a);
@@ -155,7 +155,7 @@ function normalizeSurfaceAliases(flags, positional) {
     positional.splice(0, 1);
     return;
   }
-  if (first === "hq" && (positional.length === 1 || positional[1] === "serve")) {
+  if (first === "hq" && (positional.length === 1 || positional[1] === "serve") && flags["help"] !== true && flags["version"] !== true) {
     flags["hq"] = true;
     positional.splice(0, positional[1] === "serve" ? 2 : 1);
   }
@@ -1056,4 +1056,4 @@ export {
   runLiveProviderPicker,
   runPicker
 };
-//# sourceMappingURL=chunk-2H47YMCV.js.map
+//# sourceMappingURL=chunk-5JW3XCRA.js.map

package/dist/{chunk-5KFLLTSQ.js → chunk-WC3DK6BI.js}

@@ -1,12 +1,12 @@
+import {
+  LOCAL_LLM_PRESETS,
+  runLiveProviderPicker
+} from "./chunk-5JW3XCRA.js";
 import {
   openBrowser,
   runCodexOAuthLogin,
   startLoopbackServer
 } from "./chunk-SSSJQVUY.js";
-import {
-  LOCAL_LLM_PRESETS,
-  runLiveProviderPicker
-} from "./chunk-2H47YMCV.js";
 import {
   activeLabel,
   loadConfigProviders,
@@ -1374,4 +1374,4 @@ export {
   addCustomProvider,
   addKeyForProvider
 };
-//# sourceMappingURL=chunk-5KFLLTSQ.js.map
+//# sourceMappingURL=chunk-WC3DK6BI.js.map