ai-spend-agent 0.9.2 → 0.9.3

package/dist/index.d.ts

@@ -18,6 +18,13 @@ export type CliRuntimeOptions = {
     interactive?: boolean;
     /** Foreground terminal prompt. Tests/embeddings must inject it explicitly. */
     prompt?: (question: string) => Promise<string>;
+    /**
+     * Consent-grade read for the explicit signup command (adversary SF1):
+     * buffered/type-ahead bytes never answer, EOF/^C resolve undefined. The
+     * bin wires signup.openTerminalConsentRead; tests inject stubs. When
+     * absent, `prompt` is the fallback with aborts mapped to "nothing sent".
+     */
+    consentRead?: (query: string, timeoutMs: number) => Promise<string | undefined>;
     /**
      * Guided-flow line IO for the improve/identify sittings. The foreground
      * terminal wires an arrival-timestamped readline source; tests inject

package/dist/index.js

@@ -6,7 +6,7 @@ import { homedir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { askGuidedQuestion, classifyGuidedAnswer, createInteractivePromptSource, renderForYourAgent } from "./guidedPrompt.js";
-import { assessEmailDeliverability, buildWaitlistRef, normalizeWaitlistEmail, postWaitlistSignup, readSignupState, clearSignupState, sanitizeSignupRefTag, serializeWaitlistPayload, signupCopy, signupStateFilePath, writeSignupState } from "./signup.js";
+import { assessEmailDeliverability, buildWaitlistRef, normalizeWaitlistEmail, postWaitlistSignup, readSignupState, clearSignupState, sanitizeSignupRefTag, serializeWaitlistPayload, signupAskTimeoutMs, signupCopy, signupStateFilePath, writeSignupState } from "./signup.js";
 import { killTelemetryForThisProcess, readTelemetryState, telemetryDisclosureLine, telemetryStateFilePath, writeTelemetryState } from "./telemetry.js";
 import { parsePlanDraft, renderCleanExit, runIdentitySequence, runPlanSitting, runQualitySitting, runRecordSitting, runRollbackSitting, runStartSitting, shortSittingHint } from "./improveFlow.js";
 import { analyzeSpend, APPROVAL_EVENT_V0_KIND, buildContextHealth, buildActionVerificationProjectionV0, buildProjectEconomicsProjectionV0, buildTokenReductionBaselineV0, aibillCommandV0, aibillImproveCommandV0, decodeAgentDraftTokenV1, IMPROVE_USER_SAFETY_LINE_V1, looksLikeAgentDraftToken, screenAgentDraftSentence, attributeUsageRecords, buildUsageGlance, buildActivitySnapshot, buildResultCard, buildResultCardProjectLine, formatBilledUsdExact, formatCommittedPerMonth, resultCardSchema, loadContextHealth, detectLocalCredentials, detectLocalPlans, redactSecrets, readSafeStateText, invalidateConnectedSpendTrustReceipt, resolveSafeScanRoot, resolveSafeStateDirectory, subscriptionPlans, unsafeScanRootReason, selectProviderFinancialHeadlineRecords, SAFE_QUALITATIVE_SCAN_POLICY, summarizeProviderFinancials, providerFinancialCompleteness, providerAccountKey, tagProviderAccountRecords, retainProviderRecordsForNewSync, providerAccountSlices, formatProviderAccountSlices, intersectProviderCoverageIntervals, duplicateProviderAccountSliceWarnings, providerSliceReplacementNotices, writeSafeStateText, verifyConnectedSpendTrustReceipt, verifyConnectedSourceRegistryTrustReceipt, writeConnectedSpendTrustReceipt, loadDeadContext, sampleDeadContext, sanitizeLocalActivityText, latestObservedWorkingDirectory, downgradeSampleUsageEvidence, isBundledSampleUsage, hasCompleteQualitativeCoverage, hasExactSelectedQualitativeEvidence, loadLocalAgentActionEvidence, extractSessionVitalsV0, loadLocalAgentFinancialUsage, localAgentFormatDescriptors, localAgentFormatLabel, localAgentFormatSupports, loadSampleUsageData, parseUsageRecord, scanLocalUsageSignals, buildMissingSourcePrompts, confirmMapping, createProjectIndexAdapters, createActionVerificationReference, createProjectEconomicsReference, createProjectEconomicsPlannedActionRefV0, PROJECT_ECONOMICS_V0_VERSION, createProviderConnectorStub, createProviderConnection, createLocalFolderSourceRegistry, createScanAuditLog, fetchProviderUsageRecords, addApprovedSource, normalizeSourceRegistry, downgradeUntrustedSourceRegistryClaims, buildSourceStatuses, applyProviderContractGate, applyProviderContractGateToSourceRegistry, slugifySourceId, financialEvidenceForRecords, formatSourceStatuses, markTokenReductionAppliedV0, invalidateTokenReductionExperimentV0, markTokenReductionRolledBackV0, activitySnapshotCachePath, readActivitySnapshot, recordActivitySnapshotRefreshFailure, refreshTokenReductionExperimentV0, resolveWasteFindingTargetV0, selectBestWasteFindingV0, sourceStatusDefinitions, writeActivitySnapshot } from "@agent-finops/core";
@@ -1013,7 +1013,27 @@ async function signupCommand(args, runtime) {
         return ok(signupCopy.alreadyLine);
     }
     const payload = { email, ref: buildWaitlistRef("signup", args.signupRef) };
-    const consent = (await runtime.prompt(`${signupCopy.scopeLine}\n${signupCopy.consentQuestion(serializeWaitlistPayload(payload))}`)).trim().toLowerCase();
+    const consentQuery = `${signupCopy.scopeLine}\n${signupCopy.consentQuestion(serializeWaitlistPayload(payload))}`;
+    // Adversary SF1: the consent question must never be answered by a
+    // buffered byte, and EOF/^C are a quiet "nothing sent", never the crash
+    // voice — this is the exact command the receipt advertises.
+    let consentAnswer;
+    if (runtime.consentRead) {
+        consentAnswer = await runtime.consentRead(consentQuery, signupAskTimeoutMs);
+    }
+    else {
+        try {
+            consentAnswer = await runtime.prompt(consentQuery);
+        }
+        catch {
+            // readline/promises rejects on Ctrl-D/Ctrl-C ("Aborted with Ctrl+D").
+            consentAnswer = undefined;
+        }
+    }
+    if (consentAnswer === undefined) {
+        return ok(signupCopy.nothingSentLine);
+    }
+    const consent = consentAnswer.trim().toLowerCase();
     if (consent !== "y" && consent !== "yes") {
         return ok(signupCopy.nothingSentLine);
     }
@@ -1045,7 +1065,7 @@ async function telemetryCommand(args, runtime) {
         return {
             exitCode: 1,
             stdout: "",
-            stderr: `Unknown telemetry action: ${sanitizeSecretishError(action)}\nUse: aibill telemetry [on|off]`
+            stderr: `Unknown telemetry action: ${sanitizeSecretishError(action)}\nUse: npx aibill telemetry [on|off]`
         };
     }
     if (action === "off") {
@@ -1095,7 +1115,7 @@ async function telemetryCommand(args, runtime) {
             "telemetry on · anonymous command counts only",
             `counted: command name, version, os, arch, ci flag, duration bucket, ok flag, timestamp`,
             "never: arguments, paths, file contents, project names, or your email",
-            "events start with your next run · see payloads anytime: aibill telemetry"
+            "events start with your next run · see payloads anytime: npx aibill telemetry"
         ].join("\n"));
     }
     const lines = ["aibill telemetry"];
@@ -1122,7 +1142,7 @@ async function telemetryCommand(args, runtime) {
     else {
         lines.push("last payload sent: none");
     }
-    lines.push("switch: aibill telemetry on · aibill telemetry off");
+    lines.push("switch: npx aibill telemetry on · npx aibill telemetry off");
     return ok(lines.join("\n"));
 }
 /** The run-level privacy claim: literal truth in both telemetry states. */
@@ -1271,7 +1291,7 @@ async function doctorCommand(args, runtime = {}) {
         `node version: ${process.version}`,
         `cli version: ${await cliVersion()}`,
         runtime.telemetryDisclosure === true
-            ? "local-first mode: enabled (evidence stays local · anonymous command counts shared · aibill telemetry off)"
+            ? `local-first mode: enabled (evidence stays local · ${telemetryDisclosureLine})`
             : "local-first mode: enabled (no cloud upload, no telemetry)",
         `path: ${rootPath}`,
         `state directory: ${stateDir}`,
@@ -1746,6 +1766,12 @@ async function cliVersion() {
     }
 }
 async function resetCommand(args) {
+    // NEW-B3 (cold-start audit): every project-scoped command reachable from a
+    // broad root produces the SAME friendly exact-project guidance — never the
+    // raw scan refusal, never the crash wrapper.
+    const rootGuard = await guardExactProjectRoot("reset", args.path);
+    if (rootGuard)
+        return rootGuard;
     const rootPath = await resolveSafeScanRoot(args.path);
     // The trust receipt is deliberately outside the repository. Reset must
     // clear it too so restoring an old spend.json cannot replay prior trust.
@@ -1809,7 +1835,7 @@ async function statuslineCommand(args, runtime) {
         exitCode: 1,
         stdout: "",
         stderr: `Unknown statusline action: ${sanitizeSecretishError(action)}\n` +
-            "Use: aibill statusline [refresh|install|uninstall|expand]"
+            "Use: npx aibill statusline [refresh|install|uninstall|expand]"
     };
 }
 async function packagedStatuslineRunner(runtime) {
@@ -1868,7 +1894,7 @@ function statuslineInstallerFailure(action, error) {
         ? error
         : new StatuslineInstallerError("unsafe-settings-file", `The local filesystem operation failed safely${safeFileSystemErrorCode(error)}; no successful settings change was claimed.`);
     const replacement = installerError.code === "statusline-conflict"
-        ? "\nTo replace an existing status line explicitly: aibill statusline install --replace"
+        ? "\nTo replace an existing status line explicitly: npx aibill statusline install --replace"
         : "";
     return {
         exitCode: 1,
@@ -1894,6 +1920,12 @@ async function initCommand(args, runtime = {}) {
             stderr: "aibill init only initializes from real local evidence; --sample was not used and no state or cache was changed. Run `npx aibill --sample` for the illustrative demo."
         };
     }
+    // NEW-B3 (cold-start audit): init from a broad root used to crash-wrap the
+    // raw scan refusal ("unexpected error … open an issue") — for a by-design
+    // guard, on the funnel's second command. Friendly guidance instead.
+    const rootGuard = await guardExactProjectRoot("init", args.path);
+    if (rootGuard)
+        return rootGuard;
     let detectedPlanOverride;
     if (args.plan) {
         const override = planOverrideFromFlag(args.plan);
@@ -2408,21 +2440,38 @@ async function preflightInitCache(cacheDirectory) {
     const existing = await readActivitySnapshot({ cacheDirectory });
     if (existing.status !== "error")
         return;
-    // A pre-created but EMPTY cache directory holds nothing to preserve —
-    // typically a user-made dir with default (non-0700) permissions. Init's
-    // own create path re-validates and tightens it to 0700, so proceeding is
-    // safe; only a directory with actual contents aborts (shipped-audit fix).
-    if (existing.code === "unsafe_directory" && await isEmptyRealDirectory(dirname(activitySnapshotCachePath({
+    const cacheDirectoryPath = dirname(activitySnapshotCachePath({
         ...(cacheDirectory ? { cacheDirectory } : {})
-    })))) {
+    }));
+    // A missing or pre-created-but-EMPTY cache directory holds nothing to
+    // preserve — typically a first run whose home state was stamped before
+    // any cache existed, or a user-made dir with default (non-0700)
+    // permissions. Init's own create path re-validates and tightens it to
+    // 0700, so proceeding is safe; only a directory with actual contents
+    // aborts (shipped-audit fix; cold-start audit NEW-B1: the old check
+    // required cache/ to EXIST, so first runs dead-ended here).
+    if (existing.code === "unsafe_directory" && await isMissingOrEmptyRealDirectory(cacheDirectoryPath)) {
         return;
     }
-    throw new Error(`Existing private activity cache is ${existing.code.replaceAll("_", " ")}; ` +
-        "it was preserved and init stopped. Remove the cache explicitly before rebuilding it.");
-}
-async function isEmptyRealDirectory(path) {
+    // NEW-B1(d): name the path and the one-line rescue — "remove the cache
+    // explicitly" with no path was unactionable.
+    const parentPath = dirname(cacheDirectoryPath);
+    const rescue = existing.code === "unsafe_directory"
+        ? ` One-line rescue: chmod 700 ${parentPath} ${cacheDirectoryPath} — then rerun init.`
+        : ` Remove it explicitly before rebuilding it.`;
+    throw new Error(`Existing private activity cache (${cacheDirectoryPath}) is ${existing.code.replaceAll("_", " ")}; ` +
+        `it was preserved and init stopped.${rescue}`);
+}
+async function isMissingOrEmptyRealDirectory(path) {
+    let info;
+    try {
+        info = await lstat(path);
+    }
+    catch (error) {
+        // Not there yet: nothing to preserve, init's create path builds it 0700.
+        return isNodeError(error, "ENOENT");
+    }
     try {
-        const info = await lstat(path);
         if (info.isSymbolicLink() || !info.isDirectory())
             return false;
         return (await readdir(path)).length === 0;
@@ -2769,15 +2818,13 @@ function emptyInitSourceScan(agent) {
     };
 }
 async function scanCommand(args) {
+    // NEW-B3 (cold-start audit): the bare raw refusal tier is gone — scan
+    // gives the same friendly exact-project guidance as every other
+    // project-scoped command.
+    const rootGuard = await guardExactProjectRoot("scan", args.path);
+    if (rootGuard)
+        return rootGuard;
     const rootPath = resolve(args.path);
-    const unsafeReason = unsafeScanRootReason(rootPath);
-    if (unsafeReason) {
-        return {
-            exitCode: 1,
-            stdout: "",
-            stderr: `Refusing to scan ${rootPath}: ${unsafeReason}. Choose a narrower approved folder with --path.`
-        };
-    }
     const stateDir = await resolveSafeStateDirectory(rootPath, { create: true });
     const registry = createLocalFolderSourceRegistry(rootPath);
     const startedAt = new Date().toISOString();
@@ -2870,6 +2917,12 @@ async function scanCommand(args) {
     return ok(lines.join("\n"));
 }
 async function watchCommand(args) {
+    // NEW-B3 (cold-start audit): every project-scoped command reachable from a
+    // broad root produces the SAME friendly exact-project guidance — never the
+    // raw scan refusal, never the crash wrapper.
+    const rootGuard = await guardExactProjectRoot("watch", args.path);
+    if (rootGuard)
+        return rootGuard;
     const rootPath = resolve(args.path);
     const stateDir = await resolveSafeStateDirectory(rootPath, { create: true });
     const intervalSeconds = Number.isFinite(args.interval) && (args.interval ?? 0) > 0 ? args.interval : 3600;
@@ -3127,6 +3180,12 @@ function providerSyncSetupCommand(provider, adminRef) {
     return `npx aibill sync-provider --provider ${provider} --auth-reference ${adminRef} --start-time ${thirtyDaysAgoUnix}`;
 }
 async function connectCommand(args) {
+    // NEW-B3 (cold-start audit): every project-scoped command reachable from a
+    // broad root produces the SAME friendly exact-project guidance — never the
+    // raw scan refusal, never the crash wrapper.
+    const rootGuard = await guardExactProjectRoot("connect", args.path);
+    if (rootGuard)
+        return rootGuard;
     const rootPath = resolve(args.path);
     const requestedProvider = (args.provider ?? "unknown").trim().toLowerCase();
     const provider = providerAliases[requestedProvider] ?? requestedProvider;
@@ -3699,6 +3758,15 @@ async function confirmMappingCommand(args) {
     ].join("\n"));
 }
 async function reportCommand(args, runtime = {}) {
+    // NEW-B3 + adversary F2: guard UNCONDITIONALLY. Even --sample writes
+    // project state into the root (resolveSafeStateDirectory below), so a
+    // broad root must refuse with the friendly guidance — the sample gate
+    // alone still leaked the raw "Refusing to scan" from home. report-card
+    // --sample differs: it writes only the SVG artifact and keeps its
+    // deliberate home exemption.
+    const rootGuard = await guardExactProjectRoot("report", args.path);
+    if (rootGuard)
+        return rootGuard;
     const rootPath = resolve(args.path);
     try {
         const sinceDays = args.sinceDays ?? 30;
@@ -3801,7 +3869,7 @@ async function reportCommand(args, runtime = {}) {
                     ? "cost/value evidence total: Unavailable · no priced financial evidence; missing/null is not zero"
                     : `cost/value evidence total: ${formatOptionalUsd(reportInput.summary.totalUsd)}`,
             runtime.telemetryDisclosure === true
-                ? "privacy: report rendered locally · anonymous command counts shared · aibill telemetry off; only explicit sync-provider contacts the selected provider"
+                ? `privacy: report rendered locally · ${telemetryDisclosureLine}; only explicit sync-provider contacts the selected provider`
                 : "privacy: report rendered locally with no aibill telemetry; only explicit sync-provider contacts the selected provider",
             "",
             "next:",
@@ -3839,6 +3907,14 @@ async function resolveReceiptPath(rootPath, out) {
     return extname(resolved) ? resolved : `${resolved}.svg`;
 }
 async function reportCardCommand(args) {
+    if (!args.sample) {
+        // NEW-B3 + founder repro (`npx aibill report-card` from home): the raw
+        // scan refusal used to surface wrapped in "Couldn't write the report
+        // card:". The friendly guard renders clean, BEFORE the try/wrapper.
+        const rootGuard = await guardExactProjectRoot("report-card", args.path);
+        if (rootGuard)
+            return rootGuard;
+    }
     try {
         // Explicit sample mode reads no workspace data, so a broad-root scan guard
         // would reject a harmless receipt written from the user's home directory.
@@ -5333,6 +5409,12 @@ function formatMeasuredPercent(value) {
     return `${value.toFixed(digits).replace(/\.00$/u, "").replace(/(\.\d)0$/u, "$1")}%`;
 }
 async function applyArtifactCommand(args) {
+    // NEW-B3 (cold-start audit): every project-scoped command reachable from a
+    // broad root produces the SAME friendly exact-project guidance — never the
+    // raw scan refusal, never the crash wrapper.
+    const rootGuard = await guardExactProjectRoot("apply", args.path);
+    if (rootGuard)
+        return rootGuard;
     const rootPath = resolve(args.path);
     try {
         const sinceDays = args.sinceDays ?? 30;
@@ -5418,6 +5500,12 @@ async function applyArtifactCommand(args) {
     }
 }
 async function tokenVerificationCommand(args) {
+    // NEW-B3 (cold-start audit): every project-scoped command reachable from a
+    // broad root produces the SAME friendly exact-project guidance — never the
+    // raw scan refusal, never the crash wrapper.
+    const rootGuard = await guardExactProjectRoot("verify", args.path);
+    if (rootGuard)
+        return rootGuard;
     if (args.sample) {
         return {
             exitCode: 1,
@@ -6871,7 +6959,7 @@ function helpText(telemetryDisclosure) {
         "  0 * * * * cd /path/to/workspace && npx --yes aibill watch --interval 3600 --cycles 1 >> aibill-watch.log 2>&1",
         "",
         telemetryDisclosure === true
-            ? "Privacy: local analysis and reports upload nothing; anonymous command counts shared · aibill telemetry off. Only explicit sync-provider contacts the selected provider through an env: reference."
+            ? `Privacy: local analysis and reports upload nothing; ${telemetryDisclosureLine}. Only explicit sync-provider contacts the selected provider through an env: reference.`
             : "Privacy: local analysis and reports upload nothing. Only explicit sync-provider contacts the selected provider through an env: reference.",
         "aibill never sits in the inference path and never stores, prints, or proxies provider credentials."
     ].join("\n");
@@ -6954,6 +7042,7 @@ export async function runMain() {
     let askOutcome = { kind: "no_ask" };
     let promptInterface;
     let guidedInterface;
+    let consentReader;
     try {
         let guidedIoShared;
         const runPipeline = () => runCli(argv, {
@@ -6967,6 +7056,15 @@ export async function runMain() {
                     }
                     return promptInterface.question(question);
                 },
+                // Consent-grade read for `signup <email>` (adversary SF1): buffered
+                // type-ahead never answers; EOF/^C resolve undefined quietly.
+                consentRead: async (query, timeoutMs) => {
+                    if (!consentReader) {
+                        const signup = await import("./signup.js");
+                        consentReader = await signup.openTerminalConsentRead();
+                    }
+                    return consentReader ? consentReader.read(query, timeoutMs) : undefined;
+                },
                 openGuidedIo: async () => {
                     if (!guidedIoShared) {
                         const { createInterface } = await import("node:readline");
@@ -7020,6 +7118,7 @@ export async function runMain() {
     finally {
         promptInterface?.close();
         guidedInterface?.close();
+        consentReader?.close();
         spinner?.stop();
     }
     // A read that ended without the user pressing Enter (timeout / Ctrl-C)

package/dist/signup.d.ts

@@ -1,9 +1,10 @@
 /**
  * CLI email capture — the launch-list signup lane (v0.9.2).
  *
- * Design: docs/qa-handoff/CLI_CAPTURE_DESIGN.md (see its dated placement
- * addendum). QA verdict (its B/M fixes are mandatory):
- * docs/qa-handoff/CLI_CAPTURE_QA_VERDICT.md.
+ * Design: the CLI capture design + its dated placement addendum
+ * (2026-08-24). The QA verdict's B/M fixes are mandatory and are encoded
+ * in the rules below — the verdict tags (B1, B2, M1…) cite it. The email
+ * promise each ref makes is anchored publicly in docs/EMAIL_SEND_POLICY.md.
  *
  * Placement (founder decision 2026-08-24): the ONE ask runs PRE-RECEIPT,
  * DURING the first evidence scan — it fills the first-run wait instead of
@@ -42,8 +43,8 @@ export declare function sanitizeSignupRefTag(raw: string): string | undefined;
 export declare function buildWaitlistRef(surface: WaitlistRefSurface, tag?: string): string;
 /**
  * The exact bytes sent — key order pinned. Payload creep (adding os/plan/
- * version data, or stuffing values into ref) fails the CI creep-guard test;
- * see docs/qa-handoff/CLI_CAPTURE_DESIGN.md §3c before touching this.
+ * version data, or stuffing values into ref) fails the CI creep-guard test
+ * (signup.test.ts); read that test's contract before touching this.
  */
 export declare function serializeWaitlistPayload(payload: WaitlistPayload): string;
 export type WaitlistPostOutcome = "sent" | "invalid_email" | "rate_limited" | "unreachable";
@@ -166,11 +167,37 @@ export declare function signupAskAllowed(read: SignupStateRead, now: Date): bool
 export type SignupAskIo = {
     /** Resolves the typed line, or undefined when the read timed out / aborted. */
     question: (query: string, timeoutMs: number) => Promise<string | undefined>;
+    /**
+     * Consent-grade read (0.9.3): drains every buffered byte before rendering
+     * and ignores lines that were already in flight when the prompt rendered —
+     * the same burst-guard discipline the APPROVE screen uses. A consent
+     * question may NEVER be answered by a buffered byte. Scripted/test IO may
+     * omit it; the consent step then falls back to `question`.
+     */
+    questionFresh?: (query: string, timeoutMs: number) => Promise<string | undefined>;
     write: (line: string) => void;
     /** Raw prompt redraw after a nudge line (no newline appended). */
     writeRaw?: (text: string) => void;
 };
 export declare const signupAskTimeoutMs = 30000;
+/**
+ * Consent burst-guard (0.9.3, founder incident 2026-08-24): lines arriving
+ * within this window of the previous line belong to the SAME burst and
+ * inherit its first timestamp — the guided prompt engine's convention
+ * (createInteractivePromptSource). Key-repeat Enters and paste chains can
+ * therefore never look "fresh" one line at a time.
+ */
+export declare const signupConsentBurstWindowMs = 75;
+/**
+ * Minimum time between the consent question rendering and a line that may
+ * answer it. The payload JSON is ~100 characters; no human reads it and
+ * decides faster than this. Anything quicker is an in-flight keypress from
+ * the email entry (the reproduced production failure: the follow-up Enter
+ * landed ~0.4–0.7s after the email and silently auto-declined consent).
+ * Discarded lines never re-render the prompt — the read simply keeps
+ * waiting for a deliberate keypress.
+ */
+export declare const signupConsentFreshKeypressMs = 1000;
 export type PreReceiptAskOutcome = {
     kind: "no_ask";
 } | {
@@ -215,6 +242,15 @@ export declare function openPreReceiptSignupAsk(options: {
  * The consent step, strictly AFTER the receipt has printed: scope line, the
  * literal payload JSON, a typed y — then ONE POST. Failures never persist,
  * retry, or queue the typed email.
+ *
+ * 0.9.3 contract (founder incident 2026-08-24 — production consent was
+ * auto-declined by the Enter that had submitted the email moments earlier):
+ * - The read goes through io.questionFresh when the binding provides it, so
+ *   a buffered or in-flight byte can never be the answer.
+ * - EVERY resolution prints exactly one final outcome line: sentLine on a
+ *   201, nothingSentLine on decline / timeout / interrupt / close / send
+ *   failure (failure detail prints above it). The human is never left
+ *   guessing whether anything left the machine.
  */
 export declare function runSignupConsentAfterReceipt(options: {
     io: SignupAskIo;
@@ -268,5 +304,23 @@ export type TerminalPreReceiptAsk = {
  * the receipt still renders. Returns undefined — with zero output — when
  * signup state disallows the ask.
  */
+/**
+ * Consent-grade terminal read for the explicit `aibill signup <email>`
+ * command (adversary SF1). The plain readline prompt let a buffered
+ * type-ahead `y` auto-consent and turned Ctrl-D/Ctrl-C into the crash
+ * voice. Same discipline as the pre-receipt binding's questionFresh:
+ * drain buffered input before rendering, render once, accept only a line
+ * whose burst began after the render AND that arrived past the
+ * fresh-keypress holdoff; EOF and ^C resolve undefined SILENTLY so the
+ * command's own "nothing sent" outcome line speaks.
+ *
+ * (Deliberately a compact standalone rather than a refactor of the
+ * pre-receipt binding two days before launch — the mechanics mirror
+ * questionFresh above; change them together.)
+ */
+export declare function openTerminalConsentRead(): Promise<{
+    read: (query: string, timeoutMs: number) => Promise<string | undefined>;
+    close: () => void;
+} | undefined>;
 export declare function openPreReceiptSignupAskInTerminal(): Promise<TerminalPreReceiptAsk | undefined>;
 //# sourceMappingURL=signup.d.ts.map

package/dist/signup.js

@@ -5,9 +5,10 @@ import { dirname, join } from "node:path";
 /**
  * CLI email capture — the launch-list signup lane (v0.9.2).
  *
- * Design: docs/qa-handoff/CLI_CAPTURE_DESIGN.md (see its dated placement
- * addendum). QA verdict (its B/M fixes are mandatory):
- * docs/qa-handoff/CLI_CAPTURE_QA_VERDICT.md.
+ * Design: the CLI capture design + its dated placement addendum
+ * (2026-08-24). The QA verdict's B/M fixes are mandatory and are encoded
+ * in the rules below — the verdict tags (B1, B2, M1…) cite it. The email
+ * promise each ref makes is anchored publicly in docs/EMAIL_SEND_POLICY.md.
  *
  * Placement (founder decision 2026-08-24): the ONE ask runs PRE-RECEIPT,
  * DURING the first evidence scan — it fills the first-run wait instead of
@@ -69,8 +70,8 @@ export function buildWaitlistRef(surface, tag) {
 }
 /**
  * The exact bytes sent — key order pinned. Payload creep (adding os/plan/
- * version data, or stuffing values into ref) fails the CI creep-guard test;
- * see docs/qa-handoff/CLI_CAPTURE_DESIGN.md §3c before touching this.
+ * version data, or stuffing values into ref) fails the CI creep-guard test
+ * (signup.test.ts); read that test's contract before touching this.
  */
 export function serializeWaitlistPayload(payload) {
     return JSON.stringify({ email: payload.email, ref: payload.ref });
@@ -320,7 +321,10 @@ export async function readSignupState(filePath) {
 /** Atomic-ish write; returns false instead of throwing so callers fail closed. */
 export async function writeSignupState(filePath, state) {
     try {
-        await mkdir(dirname(filePath), { recursive: true });
+        // 0o700 (NEW-B1): under the default umask a modeless mkdir left
+        // ~/.aibill at 755, which the private-cache guard then refused —
+        // dead-ending `init` on every fresh machine after the first ask stamp.
+        await mkdir(dirname(filePath), { recursive: true, mode: 0o700 });
         const temporaryPath = `${filePath}.tmp`;
         await writeFile(temporaryPath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
         await rename(temporaryPath, filePath);
@@ -370,6 +374,24 @@ export function signupAskAllowed(read, now) {
     return true;
 }
 export const signupAskTimeoutMs = 30_000;
+/**
+ * Consent burst-guard (0.9.3, founder incident 2026-08-24): lines arriving
+ * within this window of the previous line belong to the SAME burst and
+ * inherit its first timestamp — the guided prompt engine's convention
+ * (createInteractivePromptSource). Key-repeat Enters and paste chains can
+ * therefore never look "fresh" one line at a time.
+ */
+export const signupConsentBurstWindowMs = 75;
+/**
+ * Minimum time between the consent question rendering and a line that may
+ * answer it. The payload JSON is ~100 characters; no human reads it and
+ * decides faster than this. Anything quicker is an in-flight keypress from
+ * the email entry (the reproduced production failure: the follow-up Enter
+ * landed ~0.4–0.7s after the email and silently auto-declined consent).
+ * Discarded lines never re-render the prompt — the read simply keeps
+ * waiting for a deliberate keypress.
+ */
+export const signupConsentFreshKeypressMs = 1_000;
 /**
  * Opens the ONE ask, or returns undefined (with zero output) when state
  * disallows it — subsequent runs stay byte-identical to the fast path.
@@ -470,6 +492,9 @@ export async function openPreReceiptSignupAsk(options) {
         notifyReceiptReady: () => {
             if (settled)
                 return;
+            // Break off the pending prompt row first (PC-4a: without the leading
+            // newline the ready line rendered glued to the open "  > " prompt).
+            io.writeRaw?.("\n");
             io.write(`  ${signupCopy.receiptReadyLine}`);
             io.writeRaw?.(signupCopy.askPrompt);
         }
@@ -479,17 +504,32 @@ export async function openPreReceiptSignupAsk(options) {
  * The consent step, strictly AFTER the receipt has printed: scope line, the
  * literal payload JSON, a typed y — then ONE POST. Failures never persist,
  * retry, or queue the typed email.
+ *
+ * 0.9.3 contract (founder incident 2026-08-24 — production consent was
+ * auto-declined by the Enter that had submitted the email moments earlier):
+ * - The read goes through io.questionFresh when the binding provides it, so
+ *   a buffered or in-flight byte can never be the answer.
+ * - EVERY resolution prints exactly one final outcome line: sentLine on a
+ *   201, nothingSentLine on decline / timeout / interrupt / close / send
+ *   failure (failure detail prints above it). The human is never left
+ *   guessing whether anything left the machine.
  */
 export async function runSignupConsentAfterReceipt(options) {
     const { io, stamped } = options;
     io.write("");
     io.write(signupCopy.scopeLine);
-    const consent = await io.question(signupCopy.consentQuestion(serializeWaitlistPayload(options.payload)), signupAskTimeoutMs);
-    if (consent === undefined)
+    const read = io.questionFresh ?? io.question;
+    const consent = await read(signupCopy.consentQuestion(serializeWaitlistPayload(options.payload)), signupAskTimeoutMs);
+    if (consent === undefined) {
+        // Timeout / close / interrupt: no decision, no skip consumed (M3) —
+        // but the resolution is still announced.
+        io.write(signupCopy.nothingSentLine);
         return;
+    }
     const consentAnswer = consent.trim().toLowerCase();
     if (consentAnswer !== "y" && consentAnswer !== "yes") {
         await writeSignupState(options.stateFilePath, { ...stamped, askCount: stamped.askCount + 1 });
+        io.write(signupCopy.nothingSentLine);
         return;
     }
     const outcome = await postWaitlistSignup(options.payload, {
@@ -511,6 +551,7 @@ export async function runSignupConsentAfterReceipt(options) {
         : outcome === "rate_limited"
             ? signupCopy.rateLimitedLine
             : signupCopy.unreachableLine);
+    io.write(signupCopy.nothingSentLine);
 }
 /**
  * Which argv shapes qualify for the during-scan ask: the real receipt path
@@ -562,18 +603,120 @@ export async function orchestratePreReceiptAsk(input) {
  * the receipt still renders. Returns undefined — with zero output — when
  * signup state disallows the ask.
  */
+/**
+ * Consent-grade terminal read for the explicit `aibill signup <email>`
+ * command (adversary SF1). The plain readline prompt let a buffered
+ * type-ahead `y` auto-consent and turned Ctrl-D/Ctrl-C into the crash
+ * voice. Same discipline as the pre-receipt binding's questionFresh:
+ * drain buffered input before rendering, render once, accept only a line
+ * whose burst began after the render AND that arrived past the
+ * fresh-keypress holdoff; EOF and ^C resolve undefined SILENTLY so the
+ * command's own "nothing sent" outcome line speaks.
+ *
+ * (Deliberately a compact standalone rather than a refactor of the
+ * pre-receipt binding two days before launch — the mechanics mirror
+ * questionFresh above; change them together.)
+ */
+export async function openTerminalConsentRead() {
+    try {
+        const { createInterface } = await import("node:readline/promises");
+        const lineInterface = createInterface({ input: process.stdin, output: process.stdout });
+        lineInterface.setPrompt("");
+        let waiter;
+        let done = false;
+        const settleWaiter = (line) => {
+            const settle = waiter;
+            waiter = undefined;
+            if (settle)
+                settle(line);
+        };
+        const strayLines = [];
+        let lastArrivalMs;
+        let burstStartMs;
+        lineInterface.on("line", (line) => {
+            const arrivedAtMs = Date.now();
+            if (lastArrivalMs === undefined || arrivedAtMs - lastArrivalMs > signupConsentBurstWindowMs) {
+                burstStartMs = arrivedAtMs;
+            }
+            lastArrivalMs = arrivedAtMs;
+            const arrived = { text: line, arrivedAtMs, burstStartAtMs: burstStartMs ?? arrivedAtMs };
+            if (waiter)
+                settleWaiter(arrived);
+            else
+                strayLines.push(arrived);
+        });
+        lineInterface.on("close", () => {
+            done = true;
+            settleWaiter(undefined);
+        });
+        lineInterface.on("SIGINT", () => {
+            // No copy: the command's outcome line ("nothing sent") is the answer.
+            // Deliberately NO close() here — closing the interface from inside its
+            // own keypress processing leaves a piped stdin flowing (the process
+            // then never exits); the bin's finally owns the close, exactly like
+            // the answered path.
+            done = true;
+            process.stdout.write("\n");
+            settleWaiter(undefined);
+        });
+        return {
+            read: async (query, timeoutMs) => {
+                if (done)
+                    return undefined;
+                strayLines.length = 0;
+                try {
+                    const editable = lineInterface;
+                    editable.line = "";
+                    editable.cursor = 0;
+                }
+                catch {
+                    // Cosmetic only; the burst-guard below still refuses stale lines.
+                }
+                const renderedAtMs = Date.now();
+                process.stdout.write(query);
+                const timer = setTimeout(() => settleWaiter(undefined), timeoutMs);
+                timer.unref?.();
+                try {
+                    for (;;) {
+                        const answer = await new Promise((resolvePromise) => {
+                            waiter = resolvePromise;
+                        });
+                        if (answer === undefined)
+                            return undefined;
+                        if (answer.burstStartAtMs <= renderedAtMs)
+                            continue;
+                        if (answer.arrivedAtMs - renderedAtMs < signupConsentFreshKeypressMs)
+                            continue;
+                        return answer.text;
+                    }
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            },
+            close: () => {
+                lineInterface.close();
+            }
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function openPreReceiptSignupAskInTerminal() {
     try {
         const { createInterface } = await import("node:readline/promises");
         const lineInterface = createInterface({ input: process.stdin, output: process.stdout });
+        // Kill readline's own default "> " prompt: this interface never calls
+        // prompt() itself, but terminal-mode readline repaints its prompt on any
+        // internal refresh (backspace edits, cursor movement). With the default
+        // marker those repaints were the only in-process source of stray ">"
+        // markers over our output (founder incident 2026-08-24: the consent
+        // line rendered with the marker repeated and "[y/N]" overwritten). An
+        // empty prompt makes every internal repaint marker-free by construction.
+        lineInterface.setPrompt("");
         let interrupted = false;
         let abortedRead = false;
-        // Ctrl-C must SETTLE the pending read (closing the interface alone
-        // leaves the waiter unsettled, draining the loop before the receipt
-        // prints — the ask would eat the whole run). The interrupt closes the
-        // read deterministically; the ask resolves as a no-decision, one ack
-        // line explains that the scan continues (QA M2), and the receipt still
-        // renders.
         let waiter;
         const settleWaiter = (line) => {
             const settle = waiter;
@@ -586,40 +729,92 @@ export async function openPreReceiptSignupAskInTerminal() {
         // the guided engine's drain notice when the next read arms — they are
         // never used as answers, so pasted input can neither pre-answer the
         // consent step nor strand the user in 30s of silent dead air.
+        //
+        // 0.9.3: every line additionally carries its arrival time and the start
+        // time of the burst it belongs to (guided-engine convention: lines
+        // within signupConsentBurstWindowMs of the previous line inherit the
+        // burst's FIRST timestamp — key-repeat and paste chains count as one
+        // burst). The consent read uses this to refuse in-flight bytes.
         const strayLines = [];
+        let lastArrivalMs;
+        let burstStartMs;
         lineInterface.on("line", (line) => {
+            const arrivedAtMs = Date.now();
+            if (lastArrivalMs === undefined || arrivedAtMs - lastArrivalMs > signupConsentBurstWindowMs) {
+                burstStartMs = arrivedAtMs;
+            }
+            lastArrivalMs = arrivedAtMs;
+            const arrived = { text: line, arrivedAtMs, burstStartAtMs: burstStartMs ?? arrivedAtMs };
             if (waiter)
-                settleWaiter(line);
+                settleWaiter(arrived);
             else
-                strayLines.push(line);
+                strayLines.push(arrived);
         });
+        // NEW-B2 (cold-start audit): EOF must behave like a skip, never swallow
+        // the receipt. When stdin closes while NO read is armed (between ask
+        // reads, or before the first), the old code armed the next read against
+        // a dead interface with only an unref'd timer left — the event loop
+        // drained and the process exited 0 BEFORE the receipt printed. The
+        // closed flag makes every subsequent read resolve undefined instantly.
+        let closed = false;
         lineInterface.on("close", () => {
+            closed = true;
             settleWaiter(undefined);
         });
+        // SF2 (adversary): the interrupt copy is ask-phase copy. Once the flow
+        // has moved to the consent question, "skipped the ask · your receipt is
+        // still being read" is triple-false (email given, receipt rendered,
+        // exit imminent) — in consent phase a ^C settles the read silently and
+        // the consent step's own outcome line ("nothing sent") speaks.
+        let phase = "ask";
         lineInterface.on("SIGINT", () => {
             interrupted = true;
-            if (waiter) {
-                // A read was pending: skip the ask, keep the scan (QA M2).
-                process.stdout.write(`\n  ${signupCopy.interruptLine}\n`);
-                settleWaiter(undefined);
+            if (phase === "ask") {
+                if (waiter) {
+                    // A read was pending: skip the ask, keep the scan (QA M2).
+                    process.stdout.write(`\n  ${signupCopy.interruptLine}\n`);
+                }
+                else {
+                    // No read pending (already answered): readline was swallowing
+                    // the ^C — say so and stand aside so the NEXT ^C gets the
+                    // default kill behavior.
+                    process.stdout.write(`\n  ${signupCopy.interruptAfterAnswerLine}\n`);
+                }
             }
             else {
-                // No read pending (already answered / consent done): readline was
-                // swallowing the ^C — say so and stand aside so the NEXT ^C gets
-                // the default kill behavior.
-                process.stdout.write(`\n  ${signupCopy.interruptAfterAnswerLine}\n`);
+                // Consent phase: end the line the ^C landed on; nothing more.
+                process.stdout.write("\n");
             }
+            settleWaiter(undefined);
             lineInterface.close();
         });
+        const drainStrayLines = () => {
+            if (strayLines.length === 0)
+                return;
+            const discarded = strayLines.length;
+            strayLines.length = 0;
+            process.stdout.write(`  ${renderDrainNotice(discarded)}\n`);
+        };
         const io = {
             question: async (query, timeoutMs) => {
                 if (interrupted)
                     return undefined;
-                if (strayLines.length > 0) {
-                    const discarded = strayLines.length;
-                    strayLines.length = 0;
-                    process.stdout.write(`  ${renderDrainNotice(discarded)}\n`);
+                // PC-5/PC-4b (cold-start audit): a rapid second Enter lands while
+                // the ask loop is between reads (both keypresses can even share one
+                // stdin chunk) — discarding it as "paste" broke the double-Enter
+                // skip pair (askCount stayed 0), printed a drain notice the human
+                // never earned, and left a 30s dead prompt. Ask-phase lines typed
+                // between ask reads ARE the conversation: feed them in order (even
+                // after EOF, so a completed Enter-Enter pair still counts). The
+                // consent step never sees them — questionFresh drains + burst-guards
+                // (QA M4's actual goal).
+                const buffered = strayLines.shift();
+                if (buffered !== undefined) {
+                    abortedRead = false;
+                    return buffered.text;
                 }
+                if (closed)
+                    return undefined;
                 process.stdout.write(query);
                 const timer = setTimeout(() => settleWaiter(undefined), timeoutMs);
                 timer.unref?.();
@@ -628,7 +823,55 @@ export async function openPreReceiptSignupAskInTerminal() {
                         waiter = resolvePromise;
                     });
                     abortedRead = answer === undefined;
-                    return answer;
+                    return answer?.text;
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            },
+            // Consent-grade read (founder incident 2026-08-24: the Enter that had
+            // submitted the email answered — and silently declined — the consent
+            // question that armed a few hundred ms later). Contract:
+            // (a) drain EVERY buffered byte before rendering: whole stray lines
+            //     AND the half-typed remainder readline is still holding;
+            // (b) render the full line exactly once — discarded arrivals never
+            //     re-print the prompt, and nothing here redraws a marker;
+            // (c) only a FRESH keypress answers: lines whose burst began at or
+            //     before the render (key-repeat/paste chains), or that landed
+            //     faster than a human could have read the payload, are dropped
+            //     silently while the read keeps waiting.
+            questionFresh: async (query, timeoutMs) => {
+                if (interrupted || closed)
+                    return undefined;
+                drainStrayLines();
+                try {
+                    // Clear readline's in-progress line buffer without a repaint —
+                    // bytes typed before the question rendered must not seed its
+                    // answer. Internal fields, so cosmetic-only failure is fine.
+                    const editable = lineInterface;
+                    editable.line = "";
+                    editable.cursor = 0;
+                }
+                catch {
+                    // Best-effort; the burst-guard below still refuses stale lines.
+                }
+                const renderedAtMs = Date.now();
+                process.stdout.write(query);
+                const timer = setTimeout(() => settleWaiter(undefined), timeoutMs);
+                timer.unref?.();
+                try {
+                    for (;;) {
+                        const answer = await new Promise((resolvePromise) => {
+                            waiter = resolvePromise;
+                        });
+                        if (answer === undefined)
+                            return undefined;
+                        if (answer.burstStartAtMs <= renderedAtMs)
+                            continue;
+                        if (answer.arrivedAtMs - renderedAtMs < signupConsentFreshKeypressMs)
+                            continue;
+                        return answer.text;
+                    }
                 }
                 finally {
                     clearTimeout(timer);
@@ -655,8 +898,14 @@ export async function openPreReceiptSignupAskInTerminal() {
             session,
             needsFreshLine: () => abortedRead,
             runConsent: async (outcome) => {
-                if (interrupted)
+                phase = "consent";
+                if (interrupted) {
+                    // The ask was interrupted after the email was typed: consent never
+                    // renders, but the resolution is still announced (0.9.3 — an
+                    // email-shaped run must never end without an outcome line).
+                    io.write(signupCopy.nothingSentLine);
                     return;
+                }
                 try {
                     await runSignupConsentAfterReceipt({
                         io,

package/dist/statuslineRuntime.js

@@ -139,14 +139,14 @@ export function renderStatusline(result, options = {}) {
     const columns = normalizeColumns(options.columns ?? Number(process.env.COLUMNS));
     const tier = columns >= 80 ? "full" : columns >= 50 ? "compact" : "minimal";
     if (result.status === "missing")
-        return fitStatic("aibill · run aibill init", columns);
+        return fitStatic("aibill · run npx aibill init", columns);
     if (result.status === "error") {
-        return fitStatic("aibill · cache error · run aibill init", columns);
+        return fitStatic("aibill · cache error · run npx aibill init", columns);
     }
     const snapshot = result.snapshot;
     const freshness = freshnessSegment(snapshot, now);
     if (snapshot.mode === "error") {
-        return fitStatic(`aibill · ${freshness} · run aibill init`, columns);
+        return fitStatic(`aibill · ${freshness} · run npx aibill init`, columns);
     }
     if (snapshot.mode === "empty") {
         return assembleLine(["no usage yet"], freshness, columns);
@@ -169,7 +169,7 @@ export function renderStatusline(result, options = {}) {
             segments = renderUnresolved(snapshot, tier);
             break;
         default:
-            segments = ["cache error", "run aibill init"];
+            segments = ["cache error", "run npx aibill init"];
     }
     if (overage) {
         // Billed overage is the sole compact paid-alert bridge and must survive
@@ -248,7 +248,7 @@ export async function runStatuslineHook(options = {}) {
         stdout.on("error", () => undefined);
         guardedOutputs.add(stdout);
     }
-    let line = "aibill · cache error · run aibill init";
+    let line = "aibill · cache error · run npx aibill init";
     try {
         const [result] = await Promise.all([
             readStatuslineCache(options.cache),
@@ -1343,7 +1343,7 @@ if (isDirectInvocation()) {
         process.exitCode = 0;
     }).catch(() => {
         try {
-            process.stdout.write("aibill · cache error · run aibill init\n");
+            process.stdout.write("aibill · cache error · run npx aibill init\n");
         }
         catch {
             // No stderr or non-zero exit on a hook path.

package/dist/telemetry.d.ts

@@ -31,7 +31,7 @@ import { spawn } from "node:child_process";
  */
 export declare const telemetryUrl = "https://asktilden.com/api/telemetry";
 /** Server-allowlisted command labels; anything else is sent as "other". */
-export declare const telemetryCommands: readonly ["receipt", "full", "group-by", "improve", "improve-sample", "index", "identify", "accountability", "outcome", "statusline", "statusline-expand", "signup", "connect", "sync-provider", "doctor", "report", "report-card", "apply", "watch", "init", "verify", "drop-slice", "telemetry", "other"];
+export declare const telemetryCommands: readonly ["receipt", "full", "group-by", "improve", "improve-sample", "index", "identify", "accountability", "outcome", "statusline", "statusline-expand", "signup", "connect", "sync-provider", "doctor", "glance", "report", "report-card", "apply", "watch", "init", "verify", "drop-slice", "telemetry", "other"];
 export type TelemetryCommand = (typeof telemetryCommands)[number];
 export type TelemetryDurationBucket = "lt1s" | "lt5s" | "lt30s" | "gte30s";
 export type TelemetryOs = "darwin" | "linux" | "win32" | "other";
@@ -48,9 +48,14 @@ export type TelemetryEvent = {
     ok: boolean;
     ts: string;
 };
-/** Printed instead of "nothing uploaded" while telemetry is active. */
-export declare const telemetryDisclosureLine = "anonymous command counts shared \u00B7 aibill telemetry off";
-export declare const telemetryNoticeLines: readonly ["aibill counts which commands run — anonymous, never your data or content", "turn off: aibill telemetry off", "see payloads: aibill telemetry"];
+/**
+ * Printed instead of "nothing uploaded" while telemetry is active. The
+ * command is composed through the runtime command helper (aibillCommandV0,
+ * npx form): npx users have no bare `aibill` on PATH (0.9.2 founder
+ * incident — "command not found").
+ */
+export declare const telemetryDisclosureLine: string;
+export declare const telemetryNoticeLines: readonly ["aibill counts which commands run — anonymous, never your data or content", `turn off: ${string}`, `see payloads: ${string}`];
 export declare function telemetryOsLabel(platform?: string): TelemetryOs;
 export declare function telemetryArchLabel(arch?: string): TelemetryArch;
 export declare function telemetryDurationBucket(durationMs: number): TelemetryDurationBucket;

package/dist/telemetry.js

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { aibillCommandV0 } from "@agent-finops/core";
 /**
  * CLI telemetry — anonymous command counts, notice-before-first-byte.
  *
@@ -51,6 +52,7 @@ export const telemetryCommands = [
     "connect",
     "sync-provider",
     "doctor",
+    "glance",
     "report",
     "report-card",
     "apply",
@@ -61,12 +63,17 @@ export const telemetryCommands = [
     "telemetry",
     "other"
 ];
-/** Printed instead of "nothing uploaded" while telemetry is active. */
-export const telemetryDisclosureLine = "anonymous command counts shared · aibill telemetry off";
+/**
+ * Printed instead of "nothing uploaded" while telemetry is active. The
+ * command is composed through the runtime command helper (aibillCommandV0,
+ * npx form): npx users have no bare `aibill` on PATH (0.9.2 founder
+ * incident — "command not found").
+ */
+export const telemetryDisclosureLine = `anonymous command counts shared · ${aibillCommandV0("telemetry off")}`;
 export const telemetryNoticeLines = [
     "aibill counts which commands run — anonymous, never your data or content",
-    "turn off: aibill telemetry off",
-    "see payloads: aibill telemetry"
+    `turn off: ${aibillCommandV0("telemetry off")}`,
+    `see payloads: ${aibillCommandV0("telemetry")}`
 ];
 export function telemetryOsLabel(platform = process.platform) {
     return platform === "darwin" || platform === "linux" || platform === "win32" ? platform : "other";
@@ -116,6 +123,7 @@ export function telemetryCommandForArgv(argv) {
         case "connect": return "connect";
         case "sync-provider": return "sync-provider";
         case "doctor": return "doctor";
+        case "glance": return "glance";
         case "report": return "report";
         case "report-card": return "report-card";
         case "apply":
@@ -166,7 +174,10 @@ export async function readTelemetryState(filePath) {
 }
 export async function writeTelemetryState(filePath, state) {
     try {
-        await mkdir(dirname(filePath), { recursive: true });
+        // 0o700 (NEW-B1): under the default umask a modeless mkdir left
+        // ~/.aibill at 755, which the private-cache guard then refused —
+        // dead-ending `init` on every fresh machine after the notice stamp.
+        await mkdir(dirname(filePath), { recursive: true, mode: 0o700 });
         const temporaryPath = `${filePath}.tmp`;
         await writeFile(temporaryPath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
         await rename(temporaryPath, filePath);
@@ -305,6 +316,13 @@ export async function openCliTelemetry(options = {}) {
             try {
                 if (sessionTelemetryKilled)
                     return;
+                // `glance` is a machine-invoked poll (the Glance menu-bar app spawns
+                // it every ~30s), not a human command — counting it is noise by
+                // definition and would flood the anonymous command counts (~2,880
+                // events/day/user). Never emit for it, notice or not; the label
+                // still exists in the map so any stray event is at least honest.
+                if (telemetryCommandForArgv(input.argv) === "glance")
+                    return;
                 if (envDisabled || read.kind === "unreadable")
                     return;
                 if (read.kind === "ok" && !read.state.enabled)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spend-agent",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "funding": "https://asktilden.com",
   "description": "Local-first financial accountability CLI: Claude Code/Codex attribution, provenance, and next actions, plus experimental Gemini CLI cost evidence.",
   "type": "module",
@@ -55,8 +55,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@agent-finops/core": "0.9.2",
-    "@agent-finops/report": "0.9.2",
+    "@agent-finops/core": "0.9.3",
+    "@agent-finops/report": "0.9.3",
     "yocto-spinner": "^1.2.0"
   }
 }