@agent-finops/core 0.8.1 → 0.9.1

package/dist/glance.js

@@ -3,6 +3,7 @@ import { canPriceTokenUsageAtScope, estimateTokenCostUsd, PRICING_TABLE_AS_OF }
 import { subscriptionPlans } from "./planMath.js";
 import { buildContextHealth } from "./contextHealth.js";
 import { localAgentFormatDescriptors, localAgentFormatSupports } from "./localAgentFormats/registry.js";
+import { aibillImproveCommandV0 } from "./runtimeCommands.js";
 const HOUR_MS = 60 * 60 * 1_000;
 const DAY_MS = 24 * HOUR_MS;
 /**
@@ -55,17 +56,37 @@ export function buildUsageGlance(calls, options = {}) {
     const focusSessions = latest?.project && !isGenericProject(latest.project)
         ? windowSessions.filter((session) => session.project === latest.project)
         : windowSessions;
-    const focus = buildMainFocus(focusSessions, focusWindowDays, now);
-    const sessionHealth = suppliedContextHealth ?? buildContextHealth({ calls: safeCalls, now });
-    const anomaly = anomalyFromContextHealth(sessionHealth);
-    const primaryAction = buildPrimaryAction({
-        currentSession,
-        focus,
-        limits,
-        sessionHealth,
-        generatedAt: now.toISOString(),
-        filesParsed: options.filesParsed ?? 0
-    });
+    const qualitativeCoverage = options.qualitativeCoverage ?? {
+        status: "complete",
+        selectedFiles: options.filesParsed ?? 0,
+        readCompletely: options.filesParsed ?? 0,
+        skippedForBudget: 0
+    };
+    const qualitativeComplete = qualitativeCoverage.status === "complete";
+    const focus = qualitativeComplete
+        ? buildMainFocus(focusSessions, focusWindowDays, now)
+        : null;
+    const baseSessionHealth = suppliedContextHealth ?? buildContextHealth({ calls: safeCalls, now });
+    const sessionHealth = {
+        ...baseSessionHealth,
+        qualitativeCoverage
+    };
+    const anomaly = qualitativeComplete ? anomalyFromContextHealth(sessionHealth) : null;
+    const primaryAction = qualitativeComplete
+        ? buildPrimaryAction({
+            currentSession,
+            focus,
+            limits,
+            sessionHealth,
+            generatedAt: now.toISOString(),
+            filesParsed: options.filesParsed ?? 0
+        })
+        : buildCoverageLimitedPrimaryAction({
+            currentSession,
+            sessionHealth,
+            coverage: qualitativeCoverage
+        });
+    const tokenExperiment = sanitizeActionVerificationProjection(options.actionVerificationProjection);
     const detectedAgents = (options.detectedAgents ?? uniqueAgents(safeCalls))
         .filter((agent) => localAgentFormatSupports(agent, "glance"));
     const agentsWithCurrentLimits = new Set(limits.filter((limit) => limit.freshness === "current").map((limit) => limit.agent));
@@ -81,14 +102,19 @@ export function buildUsageGlance(calls, options = {}) {
         "A five-hour percentage is current for at most five hours after observation; a weekly percentage is current for at most 24 hours. Older transcript evidence is labeled stale and never drives an action.",
         "Main focus is a local summary of observed human prompts and tool activity, not elapsed time or spend; raw prompts are not returned.",
         "The primary action combines Context Health, Main focus, and reported runway locally. It only provides a copyable handoff prompt and never runs an agent automatically.",
+        "A token-test percentage compares matched local session cohorts guarded by explicit quality evidence; it is not certified savings, verified outcome ROI, or a provider bill.",
         "Claude Code transcripts do not report plan headroom. Missing limits remain unavailable instead of being inferred.",
-        "Cursor and GitHub Copilot require their provider connections because their local chat stores are not treated as authoritative billing transcripts."
+        "Cursor and GitHub Copilot require their provider connections because their local chat stores are not treated as authoritative billing transcripts.",
+        ...(qualitativeComplete ? [] : [
+            "Main focus, anomaly, and context-change handoff are unavailable because the bounded qualitative index is incomplete; no global driver was inferred from a selected subset."
+        ])
     ];
     return {
         dataMode: "local_transcripts",
         generatedAt: now.toISOString(),
         coverage: {
             filesParsed: options.filesParsed ?? 0,
+            qualitative: qualitativeCoverage,
             supportedTranscriptAgents: supportedFormats.map((descriptor) => descriptor.id),
             detectedAgents,
             rateLimitMetadata: supportedFormats.map((descriptor) => ({
@@ -146,6 +172,14 @@ export function buildUsageGlance(calls, options = {}) {
                 execution: "copy_prompt",
                 automaticExecution: false
             },
+            tokenExperiment: {
+                source: tokenExperiment
+                    ? "canonical_action_verification_projection"
+                    : "not_available",
+                calculation: "core_experiment_evaluator",
+                cohort: "matched_local_sessions",
+                automaticExecution: false
+            },
             network: {
                 uploaded: false
             }
@@ -157,9 +191,114 @@ export function buildUsageGlance(calls, options = {}) {
         anomaly,
         sessionHealth,
         primaryAction,
+        ...(tokenExperiment ? { tokenExperiment } : {}),
         caveats
     };
 }
+function buildCoverageLimitedPrimaryAction(input) {
+    const project = safeActionMetadata(input.currentSession?.project, 80);
+    const status = input.coverage.status === "partial" ? "partial" : "not available";
+    return {
+        kind: "session_handoff",
+        intent: "inspect_current_work",
+        label: project ? `Refresh evidence · ${project}` : "Refresh evidence",
+        detail: `Main focus unavailable · qualitative index ${status}`,
+        ...(project ? { project } : {}),
+        agentPrompt: [
+            "aibill's bounded qualitative evidence is incomplete.",
+            "Do not infer a global main focus, waste cause, or context change from the selected subset.",
+            `Run \`${aibillImproveCommandV0()}\` from the exact project root to refresh the private index, then review the new evidence before editing.`
+        ].join("\n"),
+        source: "context_health_focus_and_reported_runway",
+        confidence: "low",
+        execution: "copy_prompt",
+        requiresUserConfirmation: true,
+        evidenceWindowDays: input.sessionHealth.deadContext.windowDays
+    };
+}
+const actionVerificationStates = new Set([
+    "collect_baseline",
+    "approve_one_change",
+    "collect_post_change",
+    "review_measured_result",
+    "rollback",
+    "resolve_evidence",
+    "rolled_back",
+    "cancelled"
+]);
+const actionVerificationTones = new Set([
+    "neutral",
+    "attention",
+    "positive",
+    "negative"
+]);
+const actionVerificationEvidenceLabels = new Set([
+    "calculated",
+    "missing"
+]);
+const actionVerificationQualityLabels = new Set([
+    "held",
+    "regressed",
+    "insufficient"
+]);
+const actionVerificationQualityEvidence = new Set([
+    "verified",
+    "observed",
+    "user_declared",
+    "missing"
+]);
+const experimentIdPattern = /^tre_v0_[a-f0-9]{64}$/;
+const findingIdPattern = /^wf_v0_[a-f0-9]{64}$/;
+const candidateKeyPattern = /^wfc_v0_[a-f0-9]{64}$/;
+/**
+ * Treat the optional adapter input as untrusted at runtime. A malformed or
+ * internally inconsistent projection is omitted instead of becoming a stale
+ * or invented Glance claim. This function deliberately does not derive any
+ * experiment result.
+ */
+function sanitizeActionVerificationProjection(input) {
+    if (!input || typeof input !== "object")
+        return undefined;
+    const safe = sanitizeStringMetadata(input);
+    if (safe.schemaVersion !== 0 ||
+        !experimentIdPattern.test(safe.experimentId) ||
+        !findingIdPattern.test(safe.findingId) ||
+        !candidateKeyPattern.test(safe.candidateKey) ||
+        !actionVerificationStates.has(safe.state) ||
+        !actionVerificationTones.has(safe.tone) ||
+        !actionVerificationEvidenceLabels.has(safe.evidenceLabel) ||
+        !actionVerificationQualityLabels.has(safe.qualityLabel) ||
+        !actionVerificationQualityEvidence.has(safe.qualityEvidence) ||
+        !isSafeExperimentCount(safe.baselineSessions) ||
+        !isSafeExperimentCount(safe.postChangeSessions) ||
+        !isSafeExperimentCount(safe.minimumSessions) ||
+        safe.minimumSessions < 1 ||
+        (safe.reductionPercent !== null && (!Number.isFinite(safe.reductionPercent) ||
+            safe.reductionPercent > 100 ||
+            safe.reductionPercent < -1_000_000))) {
+        return undefined;
+    }
+    const measured = safe.state === "review_measured_result";
+    const claimQualityEvidence = safe.qualityEvidence === "verified" ||
+        safe.qualityEvidence === "observed" ||
+        safe.qualityEvidence === "user_declared";
+    if (safe.reductionPercent !== null) {
+        const claimEvidenceIsComplete = safe.evidenceLabel === "calculated" &&
+            safe.qualityLabel === "held" &&
+            claimQualityEvidence;
+        const signMatchesState = (measured && safe.reductionPercent >= 0) ||
+            (safe.state === "rollback" && safe.reductionPercent < 0);
+        if (!claimEvidenceIsComplete || !signMatchesState)
+            return undefined;
+    }
+    else if (measured) {
+        return undefined;
+    }
+    return safe;
+}
+function isSafeExperimentCount(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
 function toGlancePlan(agent, detectedPlans) {
     const detected = detectedPlans.find((plan) => plan.agent === agent);
     if (!detected)

package/dist/guidedAnswer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared guided-answer classifier for the aibill improve/identify flows.
+ *
+ * One function, three consumers: the CLI terminal prompts (typed input and
+ * Enter-kept prefills), the CLI agent-draft screening lane, and the MCP
+ * `draft_improve_command` preview. Keeping a single pure module in core is
+ * what makes the "same classifier at composition and at Enter-accept"
+ * invariant true by construction rather than by parity discipline.
+ *
+ * Design: P0B_FLOW_DESIGN.md §2/§3b/§3c and AGENT_NATIVE_LOOP_DESIGN.md §2f
+ * (moved here from packages/cli/src/guidedPrompt.ts, verbatim; the path and
+ * credential predicates moved with it from projectAccountabilityState.ts so
+ * the floor relationship can never drift).
+ */
+/**
+ * Exported as the classification FLOOR for the guided-prompt engine: the
+ * per-prompt classifier must reject at least everything these predicates
+ * reject, so `parseDisplayLabel` can never abort on an answer the prompt
+ * already accepted (the Aug 17 incident class).
+ */
+export declare function isPathLike(value: string): boolean;
+export declare function isCredentialLike(value: string): boolean;
+export type GuidedFieldKind = "prose" | "name" | "team" | "role" | "optional" | "time" | "choice" | "approve";
+export type ClassifyContext = {
+    example?: string;
+    /** Exact accepted tokens for choice fields, lowercase. */
+    choiceTokens?: readonly string[];
+    /** ISO instant the plan was approved (time fields). */
+    approvedAtIso?: string;
+    /** Clock override for tests. */
+    nowMs?: number;
+    /** Consecutive identical shell-rejections at this step (keep override). */
+    priorShellRejections?: number;
+};
+export type ClassifyResult = {
+    outcome: "accept";
+    value: string;
+} | {
+    outcome: "navigate";
+    action: "back" | "cancel";
+} | {
+    outcome: "skip";
+} | {
+    outcome: "reject";
+    code: RejectCode;
+    message: string;
+};
+export type RejectCode = "control" | "empty" | "shell" | "path" | "credential" | "reserved" | "timestamp_shaped" | "length" | "substance" | "time_invalid" | "time_before_approval" | "time_future" | "choice" | "approve_case";
+export declare function looksLikeCredential(answer: string): boolean;
+export declare function classifyGuidedAnswer(kind: GuidedFieldKind, rawInput: string, context?: ClassifyContext): ClassifyResult;
+//# sourceMappingURL=guidedAnswer.d.ts.map

package/dist/guidedAnswer.js

@@ -0,0 +1,352 @@
+/**
+ * Shared guided-answer classifier for the aibill improve/identify flows.
+ *
+ * One function, three consumers: the CLI terminal prompts (typed input and
+ * Enter-kept prefills), the CLI agent-draft screening lane, and the MCP
+ * `draft_improve_command` preview. Keeping a single pure module in core is
+ * what makes the "same classifier at composition and at Enter-accept"
+ * invariant true by construction rather than by parity discipline.
+ *
+ * Design: P0B_FLOW_DESIGN.md §2/§3b/§3c and AGENT_NATIVE_LOOP_DESIGN.md §2f
+ * (moved here from packages/cli/src/guidedPrompt.ts, verbatim; the path and
+ * credential predicates moved with it from projectAccountabilityState.ts so
+ * the floor relationship can never drift).
+ */
+/* ------------------------------------------------------------------ */
+/* Floor predicates (accountability backstop)                          */
+/* ------------------------------------------------------------------ */
+/**
+ * Exported as the classification FLOOR for the guided-prompt engine: the
+ * per-prompt classifier must reject at least everything these predicates
+ * reject, so `parseDisplayLabel` can never abort on an answer the prompt
+ * already accepted (the Aug 17 incident class).
+ */
+export function isPathLike(value) {
+    return /^(?:~?[\\/]|\.{1,2}(?:[\\/]|$)|[A-Za-z]:[\\/]|\\\\)/u.test(value) ||
+        /(?:^|[\\/])\.\.(?:[\\/]|$)/u.test(value) || value.includes("\\");
+}
+export function isCredentialLike(value) {
+    return /(?:sk-(?:ant-|proj-)?|sk_|gh[pousr]_|github_pat_|npm_|AIza|xox[baprs]-|glpat-|AKIA)[A-Za-z0-9_-]{8,}/i
+        .test(value) ||
+        /(?:api[_ -]?key|access[_ -]?token|auth[_ -]?token|secret|password)\s*[:=]\s*\S+/i
+            .test(value);
+}
+const unambiguousBinaries = new Set([
+    "node", "npm", "npx", "pnpm", "yarn", "bun", "bunx", "deno", "tsx", "ts-node",
+    "git", "gh", "curl", "wget", "bash", "sh", "zsh", "fish", "pwsh", "powershell",
+    "python", "python3", "pip", "pip3", "pipx", "uv", "uvx", "poetry", "pytest",
+    "vitest", "jest", "brew", "apt", "docker", "kubectl", "cargo", "rustc",
+    "dotnet", "mvn", "gradle", "terraform", "ssh", "scp", "rsync", "sudo",
+    "chmod", "chown", "xargs", "grep", "rg", "sed", "awk", "tar", "zip", "unzip",
+    "aibill", "ai-spend-agent", "vim", "nano", "code", "dir", "del", "robocopy"
+]);
+/** Common English verbs that are also binaries: reject only with corroboration. */
+const ambiguousVerbs = new Set([
+    "make", "open", "find", "go", "date", "kill", "top", "head", "tail", "touch",
+    "export", "source", "alias", "echo", "type", "cd", "ls", "cat", "cp", "mv",
+    "rm", "printf", "less", "ps", "copy", "move"
+]);
+const reservedVocabulary = new Set([
+    "held", "passed", "failed", "missing", "regressed", "approve", "approved",
+    "yes", "no", "y", "n", "p", "f", "h", "r", "m", "now", "skip", "keep"
+]);
+/**
+ * The accountability backstop predicate (`isCredentialLike`) is the FLOOR:
+ * this classifier must reject at least everything `parseDisplayLabel` would
+ * reject, or a validated answer could still abort later (B2 QA blocker B1).
+ * These extra patterns sit on top of the floor.
+ */
+const extraCredentialPattern = /(authorization\s*:\s*(?:bearer|basic)\s+\S+|-----BEGIN [A-Z ]*PRIVATE KEY-----|(?:api[ _-]?key|token|password|secret)\s*[:=]\s*\S+)/i;
+export function looksLikeCredential(answer) {
+    return isCredentialLike(answer) || extraCredentialPattern.test(answer);
+}
+const pathExtensionPattern = /\S+\.(?:js|ts|mjs|cjs|jsx|tsx|json|sh|bash|py|rb|go|rs|md|yml|yaml|toml|lock|xml|ps1|bat|cmd|gradle)(?:$|\s)/i;
+/** Strict full date-time with zone, mirroring the CLI's validIsoString. */
+const strictIsoPattern = /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:[Zz]|[+-]\d{2}:?\d{2})$/;
+const futureToleranceMs = 2 * 60 * 1000;
+/**
+ * Exact non-answer phrases (normalized: lowercase, punctuation stripped).
+ * A plan sentence must be actionable later; "i am not sure" passes the
+ * two-word substance bar but records a safety net that cannot be executed.
+ * Exact match only — a real sentence that merely CONTAINS one still passes.
+ */
+const nonAnswerPhrases = new Set([
+    "i am not sure", "im not sure", "not sure", "unsure", "i am unsure",
+    "idk", "i dont know", "dont know", "no idea", "dunno",
+    "no se", "no sé", "ni idea",
+    "whatever", "anything", "nothing", "none", "na", "tbd",
+    "help", "test", "testing", "asdf"
+]);
+function isNonAnswer(lowered) {
+    const normalized = lowered.replace(/[.,!?'’]/g, "").replace(/\s+/g, " ").trim();
+    return nonAnswerPhrases.has(normalized);
+}
+const choiceWordAliases = {
+    yes: "y",
+    no: "n",
+    passed: "p",
+    failed: "f",
+    held: "h",
+    regressed: "r",
+    missing: "m"
+};
+function stripQuotes(token) {
+    return token.replace(/^["'`]+/, "").replace(/["'`]+$/, "");
+}
+function stripEnvPrefixes(tokens) {
+    let index = 0;
+    while (index < tokens.length &&
+        (/^[A-Za-z_][A-Za-z0-9_]*=\S*$/.test(tokens[index]) ||
+            tokens[index] === "sudo" || tokens[index] === "env")) {
+        index += 1;
+    }
+    return tokens.slice(index);
+}
+/**
+ * §2f rule 2 (AGENT_NATIVE_LOOP_DESIGN.md): a pipe straight into an
+ * interpreter, spaced or not — `|sh`, `curl …|bash`, `|python3 -c …`.
+ */
+const pipeToInterpreterPattern = /\|\s*(?:sh|bash|zsh|fish|dash|node|python3?|perl|ruby|pwsh)\b/i;
+/** §2f rule 4: free-standing multi-letter short flag (` -rf`), corroboration only. */
+const multiLetterShortFlagPattern = /(?:^|\s)-[A-Za-z]{2,}(?=\s|$)/;
+function looksLikeShellCommand(answer) {
+    if (/^[$%#>] ?/.test(answer))
+        return true;
+    if (/&&|\|\||`|\$\(|>>|<<|2>&1| \| | > | < /.test(answer))
+        return true;
+    if (pipeToInterpreterPattern.test(answer))
+        return true;
+    if (/(?:^|\s)--[A-Za-z][\w-]*/.test(answer))
+        return true;
+    if (/(?:^|\s)-[A-Za-z](?=\s|$)/.test(answer))
+        return true;
+    // PowerShell Verb-Noun cmdlet shape (Get-ChildItem, Remove-Item …).
+    if (/^[A-Z][a-z]+-[A-Z][A-Za-z]+(?:\s|$)/.test(answer))
+        return true;
+    // §2f rule 1: strip any leading run of whitespace/quote/chain sigils
+    // before first-token analysis (covers `"; rm …`, `'; …`, `| sh`, `& …`
+    // fragments). If the strip removed a `;`, `|`, or `&`, the text STARTS
+    // like a command chain — that is a reject on its own. A plain leading
+    // quotation mark followed by words strips harmlessly and never rejects.
+    const leadingSigils = /^[\s"'`;|&]+/.exec(answer)?.[0] ?? "";
+    if (/[;|&]/.test(leadingSigils))
+        return true;
+    const body = answer.slice(leadingSigils.length);
+    const tokens = stripEnvPrefixes(body.split(/\s+/).filter(Boolean));
+    // Second signals, shared by first-token ambiguity and §2f rule 3: a
+    // path-like token, a file extension, or a multi-letter short flag
+    // (`rm -rf …` — rule 4; needs whitespace before the `-`, so hyphenated
+    // words like `well-known` or `re-use` can never match).
+    const hasPathToken = tokens.some((token) => /^(?:\/|\.\/|\.\.\/|~\/)/.test(token) || token.includes("/"));
+    const hasExtension = pathExtensionPattern.test(body);
+    const hasShortFlag = multiLetterShortFlagPattern.test(body);
+    const first = stripQuotes(tokens[0] ?? "").toLowerCase();
+    if (unambiguousBinaries.has(first))
+        return true;
+    if (ambiguousVerbs.has(first)) {
+        // Ambiguous English verbs reject only with a second signal: a path-like
+        // token, a file extension, a corroborating flag, or a terse
+        // all-lowercase fragment that reads like a command line, not a sentence.
+        const terseLowercase = tokens.length <= 2 && body === body.toLowerCase();
+        if (hasPathToken || hasExtension || hasShortFlag || terseLowercase)
+            return true;
+    }
+    // §2f rule 3: `;` chained command starts. A `;` followed by an unambiguous
+    // binary rejects outright; followed by an ambiguous verb it rejects only
+    // with a second signal — English semicolons ("…workflow; keep the earlier
+    // settings", "…change; go back to the prior flow") survive.
+    for (const chained of body.matchAll(/;\s*([^\s;|&]+)/g)) {
+        const chainedFirst = stripQuotes(chained[1]).toLowerCase();
+        if (unambiguousBinaries.has(chainedFirst))
+            return true;
+        if (ambiguousVerbs.has(chainedFirst) &&
+            (hasPathToken || hasExtension || hasShortFlag)) {
+            return true;
+        }
+    }
+    return false;
+}
+function looksLikePath(answer, kind) {
+    // The accountability backstop predicate is the floor: it covers leading
+    // slashes and dot-segments, drive letters, backslashes, and bare ".".
+    if (isPathLike(answer))
+        return true;
+    if (kind === "prose") {
+        if (pathExtensionPattern.test(answer))
+            return true;
+        const slashTokens = answer.split(/\s+/).filter((token) => token.includes("/"));
+        return slashTokens.length >= 2;
+    }
+    // Name-like fields: a slashed token is a path; a bare file-extension token
+    // counts only when it IS the whole answer — "Node.js Guild" is a team.
+    if (/\S+\/\S+/.test(answer))
+        return true;
+    return pathExtensionPattern.test(answer) && !/\s/.test(answer.trim());
+}
+function byteLength(value) {
+    return Buffer.byteLength(value.normalize("NFC"), "utf8");
+}
+function hasControlOrFormatCharacters(value) {
+    // C0/C1 controls including embedded newlines and DEL (tab and trailing
+    // CR are normalized earlier), plus the invisible/directional format
+    // characters that can spoof what the review screen appears to say.
+    // ZWNJ/ZWJ (U+200C/U+200D) are deliberately ALLOWED: they are standard
+    // orthography in Persian and other scripts and in emoji families.
+    if (/[\u0000-\u0008\u000A-\u001F\u007F-\u009F\u2028\u2029]/.test(value))
+        return true;
+    return /[\u00AD\u061C\u200B\u200E\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]/.test(value);
+}
+function hasUnpairedSurrogate(value) {
+    for (let index = 0; index < value.length; index += 1) {
+        const code = value.charCodeAt(index);
+        if (code >= 0xd800 && code <= 0xdbff) {
+            const next = value.charCodeAt(index + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return true;
+            index += 1;
+        }
+        else if (code >= 0xdc00 && code <= 0xdfff) {
+            return true;
+        }
+    }
+    return false;
+}
+export function classifyGuidedAnswer(kind, rawInput, context = {}) {
+    const normalizedTabs = rawInput.replace(/\t/g, " ").replace(/\r$/, "");
+    const answer = normalizedTabs.trim();
+    const lowered = answer.toLowerCase();
+    const reject = (code, message) => ({
+        outcome: "reject", code, message
+    });
+    const exampleSuffix = context.example ? ` e.g. ${context.example}` : "";
+    // Navigation pre-pass (every field).
+    if (lowered === "back" || lowered === "b")
+        return { outcome: "navigate", action: "back" };
+    if (lowered === "cancel" || lowered === "q" || lowered === "quit" || lowered === "exit") {
+        return { outcome: "navigate", action: "cancel" };
+    }
+    if (kind === "optional" && (answer === "" || lowered === "skip")) {
+        return { outcome: "skip" };
+    }
+    if (hasControlOrFormatCharacters(answer) || hasUnpairedSurrogate(answer)) {
+        return reject("control", "That answer carried hidden control characters (usually a stray paste). Type it as plain text.");
+    }
+    if (answer === "") {
+        if (kind === "approve") {
+            // An empty answer at the approval screen is a decline, not an error.
+            return { outcome: "navigate", action: "cancel" };
+        }
+        return reject("empty", "This step needs an answer in words. Type it, or type back or cancel.");
+    }
+    if (looksLikeCredential(answer)) {
+        // Never echo, never store: callers must discard this input entirely.
+        return reject("credential", "That looks like it contains a credential. aibill never stores credentials — that answer was discarded. Type it again without the secret.");
+    }
+    switch (kind) {
+        case "approve": {
+            if (answer === "APPROVE")
+                return { outcome: "accept", value: answer };
+            // Clear approval intent gets the nudge, never a silent decline:
+            // APPROVED, aprove, i approve, full-width IME APPROVE, yes/y.
+            const folded = answer.normalize("NFKC").toUpperCase();
+            if (folded.includes("APPROV") || folded.includes("APROVE") ||
+                lowered === "yes" || lowered === "y") {
+                return reject("approve_case", "Approval must be typed APPROVE, in capitals, so it cannot happen by accident.");
+            }
+            // Any other answer is a decline — an answer, not an error.
+            return { outcome: "navigate", action: "cancel" };
+        }
+        case "choice": {
+            const tokens = context.choiceTokens ?? [];
+            if (tokens.includes(lowered))
+                return { outcome: "accept", value: lowered };
+            // Exact full words map to their canonical letter, but only within
+            // their own question family: "no" at a p/f/n question must reprompt,
+            // never silently become "n". Never prefix-match either — "probably
+            // failed" or "not sure" reprompts, not guesses.
+            const alias = choiceWordAliases[lowered];
+            if (alias !== undefined && tokens.includes(alias)) {
+                const applies = lowered === "yes" || lowered === "no" ? tokens.includes("y") :
+                    lowered === "passed" || lowered === "failed" ? tokens.includes("p") :
+                        tokens.includes("h");
+                if (applies)
+                    return { outcome: "accept", value: alias };
+            }
+            if (tokens.includes("p")) {
+                return reject("choice", "Answer p (passed), f (failed), or n (not run yet).");
+            }
+            if (tokens.includes("h")) {
+                return reject("choice", "Answer h (held), r (regressed), or m (cannot say).");
+            }
+            return reject("choice", `Answer one of: ${tokens.join(", ")}.`);
+        }
+        case "time": {
+            if (lowered === "now") {
+                return { outcome: "accept", value: new Date(context.nowMs ?? Date.now()).toISOString() };
+            }
+            if (!strictIsoPattern.test(answer)) {
+                return reject("time_invalid", "That is not a UTC ISO-8601 time. e.g. 2026-08-17T14:03:00Z — or type now if it just finished.");
+            }
+            const parsed = Date.parse(answer);
+            if (!Number.isFinite(parsed)) {
+                return reject("time_invalid", "That is not a UTC ISO-8601 time. e.g. 2026-08-17T14:03:00Z — or type now if it just finished.");
+            }
+            const approvedAt = context.approvedAtIso ? Date.parse(context.approvedAtIso) : undefined;
+            if (context.approvedAtIso !== undefined && !Number.isFinite(approvedAt ?? Number.NaN)) {
+                // Fail closed: an unreadable approval time must never silently
+                // disable the after-approval check.
+                return reject("time_invalid", "The approval record's own time is unreadable, so this time cannot be checked. Type cancel and rerun this command.");
+            }
+            if (approvedAt !== undefined && parsed <= approvedAt) {
+                return reject("time_before_approval", `That time is not after the approval at ${context.approvedAtIso}. A change cannot be applied before it was approved. Paste the time the agent reported.`);
+            }
+            if (parsed > (context.nowMs ?? Date.now()) + futureToleranceMs) {
+                return reject("time_future", "That time is in the future. Paste the actual reported time.");
+            }
+            return { outcome: "accept", value: new Date(parsed).toISOString() };
+        }
+        default:
+            break;
+    }
+    if (looksLikeShellCommand(answer)) {
+        const message = kind === "prose"
+            ? "That looks like a shell command, not an answer. Nothing runs here — describe it in words."
+            : "That looks like a shell command, not a name. Answer with the name in words.";
+        return reject("shell", message);
+    }
+    if (kind === "prose" && lowered === "keep" && (context.priorShellRejections ?? 0) >= 2) {
+        // After repeated identical shell rejections the user may type `keep` to
+        // record their exact text as words. The caller substitutes the last
+        // rejected line; this sentinel value never reaches storage.
+        return { outcome: "accept", value: "keep" };
+    }
+    if (looksLikePath(answer, kind)) {
+        return reject("path", "That looks like a file path. Describe it in words instead — the answer must read as a sentence, not a location.");
+    }
+    if (kind === "name" || kind === "team" || kind === "role" || kind === "optional") {
+        if (reservedVocabulary.has(lowered)) {
+            const message = kind === "role"
+                ? `"${answer}" is aibill's own vocabulary, not a role. Answer with your real job role, in words.${exampleSuffix}`
+                : `That is aibill vocabulary, not a name. Answer in your own words.${exampleSuffix}`;
+            return reject("reserved", message);
+        }
+        if (strictIsoPattern.test(answer)) {
+            return reject("timestamp_shaped", `That is a time, not a name.${exampleSuffix}`);
+        }
+        if (byteLength(answer) > 192) {
+            return reject("length", "That name is longer than aibill can store (192 bytes). Use a shorter form.");
+        }
+        return { outcome: "accept", value: answer.normalize("NFC") };
+    }
+    // prose
+    if (answer.length > 1000) {
+        return reject("length", "Keep it to one or two short sentences (under 1,000 characters).");
+    }
+    if (answer.split(/\s+/).filter(Boolean).length < 2 || isNonAnswer(lowered)) {
+        return reject("substance", `That is not something aibill can hold you to later. Write what should actually happen — or type back or cancel if you are not ready.${exampleSuffix}`);
+    }
+    // NFC like the name fields: the rollback sentence is later re-typed and
+    // compared by hash, so composition differences must not fail the match.
+    return { outcome: "accept", value: answer.normalize("NFC") };
+}
+//# sourceMappingURL=guidedAnswer.js.map

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from "./analyze.js";
+export * from "./actionPlanner.js";
+export * from "./actionVerification.js";
 export * from "./agentInventory.js";
 export * from "./agentEconomicsReceipt.js";
 export * from "./activitySnapshot.js";
@@ -12,16 +14,26 @@ export * from "./discovery.js";
 export * from "./glance.js";
 export * from "./toolInvocations.js";
 export * from "./insights.js";
-export { aggregateCalls, dedupeCumulativeSessionCalls, latestObservedWorkingDirectory, loadLocalAgentFinancialUsage, loadLocalAgentUsage, parseClaudeCodeTranscript, parseCodexRollout, sanitizeLocalActivityText } from "./localAgentLogs.js";
-export type { LocalAgentActivity, LocalAgentCall, LocalAgentFinancialLogOptions, LocalAgentLogDiagnostic, LocalAgentLogDiagnosticCode, LocalAgentLogOptions, LocalAgentLogResult, LocalAgentRateLimitSnapshot, LocalAgentRateLimitWindow, LocalAgentSourceScan, LocalAgentTurnUsage } from "./localAgentLogs.js";
+export { aggregateCalls, codexHeaderProbesPerScan, dedupeCumulativeSessionCalls, defaultStreamedBytesPerRun, hasCompleteQualitativeCoverage, hasExactSelectedQualitativeEvidence, latestObservedWorkingDirectory, loadLocalAgentActionEvidence, loadLocalAgentFinancialUsage, loadLocalAgentUsage, localAgentQualitativeParserVersion, parseClaudeCodeTranscript, parseCodexRollout, SAFE_QUALITATIVE_SCAN_POLICY, sanitizeLocalActivityText } from "./localAgentLogs.js";
+export type { LocalAgentActivity, LocalAgentCall, LocalAgentCompletionEvidence, LocalAgentFinancialLogOptions, LocalAgentOwnershipIndexAdapter, LocalAgentOwnershipRecord, LocalAgentQualitativeIndexAdapter, LocalAgentQualitativeIndexKey, LocalAgentQualitativeIndexValue, LocalAgentQualitativeScanPolicy, LocalAgentStreamCheckpointAdapter, LocalAgentStreamCheckpointRecord, LocalAgentLogDiagnostic, LocalAgentLogDiagnosticCode, LocalAgentLogOptions, LocalAgentLogResult, LocalAgentRateLimitSnapshot, LocalAgentRateLimitWindow, LocalAgentSourceScan, LocalAgentTokenComponentEvidence, LocalAgentTurnUsage } from "./localAgentLogs.js";
 export * from "./localAgentFormats/registry.js";
 export type * from "./localAgentFormats/types.js";
 export * from "./modelPricing.js";
 export * from "./planDetection.js";
 export * from "./planMath.js";
+export * from "./projectEconomics.js";
+export * from "./resultCard.js";
+export * from "./projectEconomicsBuilder.js";
+export * from "./qualitativeIndexCache.js";
+export * from "./projectIndexStore.js";
+export * from "./runtimeCommands.js";
+export * from "./guidedAnswer.js";
+export * from "./agentDraftToken.js";
+export * from "./agentLoopContract.js";
 export * from "./sampleData.js";
 export * from "./scanGuard.js";
 export * from "./schema.js";
+export * from "./sessionVitals.js";
 export * from "./sourceRegistry.js";
 export * from "./sourceStatus.js";
 export * from "./stateTrust.js";