ai-spend-agent 0.9.0 → 0.9.2

package/dist/index.js

@@ -1,12 +1,15 @@
 #!/usr/bin/env node
+import { randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
-import { mkdir, readFile, rm, stat } from "node:fs/promises";
+import { lstat, mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
 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 { 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, 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, 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, readActivitySnapshot, recordActivitySnapshotRefreshFailure, refreshTokenReductionExperimentV0, resolveWasteFindingTargetV0, selectBestWasteFindingV0, sourceStatusDefinitions, writeActivitySnapshot } from "@agent-finops/core";
+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";
 import { StatuslineInstallerError, installClaudeStatusline, refreshOwnedStatuslineRunner, uninstallClaudeStatusline } from "./statuslineInstaller.js";
 import { readStatuslineCache, renderStatusline } from "./statuslineRuntime.js";
 import { chooseLatestTokenReductionExperiment, loadTokenVerificationState, upsertTokenReductionExperiment } from "./tokenVerificationState.js";
@@ -30,7 +33,7 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
         return ok(await cliVersion());
     }
     if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
-        return ok(helpText());
+        return ok(helpText(runtime.telemetryDisclosure));
     }
     const args = parseArgs(argv);
     if (args.parseErrors.length > 0) {
@@ -68,7 +71,7 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
         return quickstartCommand(args, runtime);
     }
     if (args.command === "doctor") {
-        return doctorCommand(args);
+        return doctorCommand(args, runtime);
     }
     if (args.command === "reset") {
         return resetCommand(args);
@@ -79,6 +82,12 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
     if (args.command === "statusline") {
         return statuslineCommand(args, runtime);
     }
+    if (args.command === "signup") {
+        return signupCommand(args, runtime);
+    }
+    if (args.command === "telemetry") {
+        return telemetryCommand(args, runtime);
+    }
     if (args.command === "scan") {
         return scanCommand(args);
     }
@@ -89,7 +98,7 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
         return watchCommand(args);
     }
     if (args.command === "report") {
-        return reportCommand(args);
+        return reportCommand(args, runtime);
     }
     if (args.command === "report-card") {
         return reportCardCommand(args);
@@ -98,7 +107,7 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
         return glanceCommand(args);
     }
     if (args.command === "context" || args.command === "context-health") {
-        return contextHealthCommand(args);
+        return contextHealthCommand(args, runtime);
     }
     if (args.command === "apply-artifact" || args.command === "apply") {
         return applyArtifactCommand(args);
@@ -133,13 +142,16 @@ export async function runCli(argv = process.argv.slice(2), runtime = {}) {
     if (args.command === "sync-provider") {
         return syncProviderCommand(args);
     }
+    if (args.command === "drop-slice") {
+        return dropSliceCommand(args);
+    }
     if (args.command === "confirm-mapping") {
         return confirmMappingCommand(args);
     }
     return {
         exitCode: 1,
         stdout: "",
-        stderr: `Unknown command: ${sanitizeSecretishError(args.command)}\n${helpText()}`
+        stderr: `Unknown command: ${sanitizeSecretishError(args.command)}\n${helpText(runtime.telemetryDisclosure)}`
     };
 }
 async function quickstartCommand(args, runtime = {}) {
@@ -153,14 +165,21 @@ async function quickstartCommand(args, runtime = {}) {
             stderr: `Unknown --plan "${sanitizeSecretishError(args.plan)}". Valid plans: ${subscriptionPlans.map((plan) => plan.id).join(", ")}`
         };
     }
-    const { records, mode, warnings, providerCoverage, codexInvocationFiles, actionEvidence, financialCoverageComplete } = await loadInstantReadData(args);
+    const { records, mode, warnings, providerCoverage, codexInvocationFiles, actionEvidence, localFinancialRecords, financialCoverageComplete } = await loadInstantReadData(args);
     if (records.length === 0) {
-        return noEvidenceResult("receipt", warnings, sinceDays);
+        return noEvidenceResult("receipt", warnings, sinceDays, runtime.telemetryDisclosure);
     }
     const summaryRecords = mode === "connected"
         ? selectProviderFinancialHeadlineRecords(records)
         : records;
     const summary = analyzeSpend(summaryRecords);
+    // Connected receipts stay billed-primary but never ERASE the estimated
+    // axis: local transcript records ride along so subscription rows keep
+    // their ~ API-equivalent figures next to billed money (C-lane §1.4). The
+    // renderer classifies each record by basis and never blends the totals.
+    const receiptRecords = mode === "connected" && (localFinancialRecords?.length ?? 0) > 0
+        ? [...summaryRecords, ...localFinancialRecords]
+        : summaryRecords;
     // For real local-log users the by-project view is the flagship table
     // ("which project burns my plan"); demo/connected keep by-model.
     const groupBy = args.groupBy ?? (mode === "local-logs" ? "project" : "model");
@@ -241,10 +260,14 @@ async function quickstartCommand(args, runtime = {}) {
         }).catch(() => undefined)
         : undefined;
     const summaryText = generatePlainEnglishSummary(summary, {
-        records: summaryRecords,
+        records: receiptRecords,
         groupBy,
         color,
         mode,
+        // Receipt-line truth: with telemetry enabled+noticed the receipt's
+        // privacy claim discloses the command counts instead of "nothing
+        // uploaded".
+        ...(runtime.telemetryDisclosure === true ? { telemetryDisclosureLine } : {}),
         ...(providerCoverage ? { providerCoverage } : {}),
         nextSteps,
         deadContext,
@@ -509,7 +532,7 @@ async function glanceCommand(args) {
     });
     return ok(JSON.stringify(snapshot));
 }
-async function contextHealthCommand(args) {
+async function contextHealthCommand(args, runtime = {}) {
     const sinceDays = args.sinceDays ?? 30;
     if (!validSinceDays(sinceDays))
         return invalidSinceDaysResult();
@@ -534,9 +557,9 @@ async function contextHealthCommand(args) {
     const qualitativeCoverage = summarizeCliQualitativeCoverage(logs);
     return ok(args.json
         ? JSON.stringify({ ...health, qualitativeCoverage })
-        : `${renderContextHealth(health)}\n\n${renderCliQualitativeCoverage(qualitativeCoverage)}`);
+        : `${renderContextHealth(health, runtime.telemetryDisclosure)}\n\n${renderCliQualitativeCoverage(qualitativeCoverage)}`);
 }
-function renderContextHealth(health) {
+function renderContextHealth(health, telemetryDisclosure) {
     const status = health.status.replace("_", " ").toUpperCase();
     const activation = health.activation;
     const dead = health.deadContext;
@@ -581,7 +604,7 @@ function renderContextHealth(health) {
             lines.push(`  - ${evidence.summary} [${evidence.confidence}; ${evidence.source}]`);
         }
     }
-    lines.push("", "Data: local agent configuration + local Claude Code/Codex transcripts; hook commands were not run.", "Privacy: this CLI run uploads nothing.");
+    lines.push("", "Data: local agent configuration + local Claude Code/Codex transcripts; hook commands were not run.", `Privacy: ${uploadsNothingLine(telemetryDisclosure, "this CLI run uploads nothing.")}`);
     return lines.join("\n");
 }
 function quickstartNextSteps(mode, detected) {
@@ -595,10 +618,17 @@ function quickstartNextSteps(mode, detected) {
         steps.push(`npx aibill connect ${detected[0].provider}   set up the admin connector, then sync provider-reported cost`);
     }
     steps.push(mode === "demo"
-        ? "npx aibill report --sample --path ./demo-workspace     write a clearly labeled demo report in an explicitly narrow workspace"
+        // Every printed command must run as printed: the demo workspace does
+        // not exist yet, so the command creates it first (shipped-audit fix).
+        ? "mkdir -p ./demo-workspace && npx aibill report --sample --path ./demo-workspace     write a clearly labeled demo report in an explicitly narrow workspace"
         : "npx aibill report              write a shareable Markdown + HTML report");
     steps.push("npx aibill --group-by project  see which project has the most observed activity");
     steps.push("Need team reconciliation, allocation, budgets, and approvals? Workspace design partners: https://asktilden.com");
+    if (mode === "demo") {
+        // Static pointer only — sample output is built for recordings and
+        // screenshots, so it never prompts (capture design moments map).
+        steps.push(signupCopy.samplePointer);
+    }
     return steps;
 }
 async function readPersistedSpend(rootPath, options = {}) {
@@ -714,6 +744,12 @@ async function loadInstantReadData(args) {
                 actionEvidence,
                 codexInvocationFiles: actionEvidence.codexInvocationFiles
             } : {}),
+            // Billed provider records are the headline, but the machine's local
+            // API-equivalent evidence is a separate axis the receipt must keep
+            // (per-subscription ~ figures) — connected mode never erases it.
+            ...(financialLogs && financialLogs.records.length > 0
+                ? { localFinancialRecords: financialLogs.records }
+                : {}),
             ...(persisted.providerCoverage ? { providerCoverage: persisted.providerCoverage } : {}),
             financialCoverageComplete: persisted.providerCoverage === "complete" &&
                 connectedHeadlineRecords.length > 0 &&
@@ -917,7 +953,183 @@ function renderCliQualitativeCoverage(coverage) {
         `${coverage.readCompletely}/${coverage.selectedFiles} selected files read completely · ` +
         `${coverage.skippedForBudget} eligible files skipped by budget`;
 }
-function noEvidenceResult(surface, warnings, sinceDays) {
+/**
+ * `aibill signup <email> [--ref <token>]` — the explicit, deliberate path to
+ * the launch list. Sends EXACTLY {email, ref} to the deployed waitlist route
+ * after showing the literal payload JSON and receiving a typed `y` on a real
+ * terminal. Never sends without the confirm; never retries, queues, or
+ * persists the typed email on failure. `--forget` clears local signup state;
+ * `--never` records never-ask without sending anything.
+ */
+async function signupCommand(args, runtime) {
+    const stateFile = signupStateFilePath(runtime.homeDirectory);
+    if (args.signupForget) {
+        const cleared = await clearSignupState(stateFile);
+        return cleared
+            ? ok(signupCopy.forgetLine)
+            : { exitCode: 1, stdout: "", stderr: "local signup state could not be cleared; check ~/.aibill permissions" };
+    }
+    const priorRead = await readSignupState(stateFile);
+    const priorAskCount = priorRead.kind === "ok" ? priorRead.state.askCount : 0;
+    if (args.signupNever) {
+        const written = await writeSignupState(stateFile, { version: 1, status: "never", askCount: priorAskCount });
+        return written
+            ? ok(signupCopy.neverLine)
+            : { exitCode: 1, stdout: "", stderr: "never-ask could not be persisted; check ~/.aibill permissions" };
+    }
+    if (!args.signupEmail) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: [
+                "signup needs an email: npx aibill signup you@work.com [--ref <token>]",
+                "Optional: signup --never (never ask again) · signup --forget (clear local signup state)"
+            ].join("\n")
+        };
+    }
+    // Consent requires a human at a real terminal; there is deliberately no
+    // --yes flag and no non-TTY path (QA 2).
+    if (runtime.interactive !== true || !runtime.prompt) {
+        return { exitCode: 1, stdout: "", stderr: signupCopy.nonInteractiveLine };
+    }
+    const email = normalizeWaitlistEmail(args.signupEmail);
+    if (email === undefined) {
+        return { exitCode: 1, stdout: "", stderr: signupCopy.invalidEmailLine };
+    }
+    // Deliverability (MX with A fallback, 1.5s budget, fail-open on DNS
+    // trouble): only a provable cannot-receive domain or a throwaway inbox is
+    // refused — never a slow or offline resolver.
+    const deliverability = await assessEmailDeliverability(email, {
+        ...(runtime.signupDns ? { resolver: runtime.signupDns } : {})
+    });
+    if (deliverability === "no_mx") {
+        return { exitCode: 1, stdout: "", stderr: signupCopy.noMxLine };
+    }
+    if (deliverability === "disposable") {
+        return { exitCode: 1, stdout: "", stderr: signupCopy.disposableLine };
+    }
+    if (priorRead.kind === "ok" && priorRead.state.status === "subscribed" && priorRead.state.email === email) {
+        // Cosmetic-local dedupe; the route itself is idempotent (201 on duplicate).
+        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();
+    if (consent !== "y" && consent !== "yes") {
+        return ok(signupCopy.nothingSentLine);
+    }
+    const outcome = await postWaitlistSignup(payload, { fetchImpl: runtime.waitlistFetch });
+    if (outcome === "sent") {
+        await writeSignupState(stateFile, { version: 1, status: "subscribed", askCount: priorAskCount, email });
+        return ok(signupCopy.sentLine);
+    }
+    return {
+        exitCode: 1,
+        stdout: "",
+        stderr: outcome === "invalid_email"
+            ? signupCopy.invalidEmailLine
+            : outcome === "rate_limited"
+                ? signupCopy.rateLimitedLine
+                : signupCopy.unreachableLine
+    };
+}
+/**
+ * `aibill telemetry [on|off]` — inspect or switch anonymous command-count
+ * telemetry. Status shows the EXACT last payload verbatim; state is
+ * fail-closed (corrupt/readonly ⇒ off).
+ */
+async function telemetryCommand(args, runtime) {
+    const filePath = telemetryStateFilePath(runtime.homeDirectory);
+    const read = await readTelemetryState(filePath);
+    const action = args.telemetryAction;
+    if (action !== undefined && action !== "on" && action !== "off") {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: `Unknown telemetry action: ${sanitizeSecretishError(action)}\nUse: aibill telemetry [on|off]`
+        };
+    }
+    if (action === "off") {
+        const state = {
+            version: 1,
+            installId: read.kind === "ok" ? read.state.installId : randomUUID(),
+            enabled: false,
+            ...(read.kind === "ok" && read.state.noticedAt !== undefined ? { noticedAt: read.state.noticedAt } : {}),
+            ...(read.kind === "ok" && read.state.lastPayload !== undefined ? { lastPayload: read.state.lastPayload } : {})
+        };
+        if (!await writeTelemetryState(filePath, state)) {
+            // FAIL CLOSED (QA M1): the off could not be persisted and the stored
+            // state may still say enabled — silence THIS process and point at the
+            // env kill-switches for a durable off.
+            killTelemetryForThisProcess();
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: [
+                    "telemetry off could not be persisted — nothing more will be sent by this run.",
+                    "For a durable off, set AI_SPEND_NO_TELEMETRY=1 or DO_NOT_TRACK=1, then fix ~/.aibill permissions."
+                ].join("\n")
+            };
+        }
+        killTelemetryForThisProcess();
+        return ok("telemetry off · nothing is sent");
+    }
+    if (action === "on") {
+        // Turning telemetry on explicitly IS the notice moment: the user is
+        // reading this command's output, so noticedAt is stamped now and
+        // events begin on the next run.
+        const state = {
+            version: 1,
+            installId: read.kind === "ok" ? read.state.installId : randomUUID(),
+            enabled: true,
+            noticedAt: new Date().toISOString(),
+            ...(read.kind === "ok" && read.state.lastPayload !== undefined ? { lastPayload: read.state.lastPayload } : {})
+        };
+        if (!await writeTelemetryState(filePath, state)) {
+            return {
+                exitCode: 1,
+                stdout: "",
+                stderr: "telemetry state could not be written — telemetry remains off (unreadable state fails closed)"
+            };
+        }
+        return ok([
+            "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"
+        ].join("\n"));
+    }
+    const lines = ["aibill telemetry"];
+    if (read.kind === "unreadable") {
+        lines.push("status: off (state unreadable — telemetry fails closed)");
+    }
+    else if (read.kind === "fresh") {
+        lines.push("status: not yet noticed · nothing has ever been sent");
+        lines.push("a one-time notice prints after your next interactive run; events begin only after it");
+    }
+    else if (!read.state.enabled) {
+        lines.push("status: off · nothing is sent");
+    }
+    else if (read.state.noticedAt === undefined) {
+        lines.push("status: on but not yet noticed · nothing has been sent");
+    }
+    else {
+        lines.push(`status: on · noticed ${read.state.noticedAt}`);
+    }
+    lines.push("counted: command name, version, os, arch, ci flag, duration bucket, ok flag, timestamp", "never: arguments, paths, file contents, project names, or your email");
+    if (read.kind === "ok" && read.state.lastPayload !== undefined) {
+        lines.push("last payload sent (verbatim):", read.state.lastPayload);
+    }
+    else {
+        lines.push("last payload sent: none");
+    }
+    lines.push("switch: aibill telemetry on · aibill telemetry off");
+    return ok(lines.join("\n"));
+}
+/** The run-level privacy claim: literal truth in both telemetry states. */
+function uploadsNothingLine(telemetryDisclosure, original) {
+    return telemetryDisclosure === true ? telemetryDisclosureLine : original;
+}
+function noEvidenceResult(surface, warnings, sinceDays, telemetryDisclosure) {
     const surfaceLine = surface === "watch"
         ? "Watch has no financial baseline yet; no zero total or sample activity was recorded."
         : surface === "report-card"
@@ -931,11 +1143,12 @@ function noEvidenceResult(surface, warnings, sinceDays) {
                 "",
                 surfaceLine,
                 "Looked for: Claude Code, Codex, and Gemini CLI local history.",
-                "Nothing was uploaded. No sample data was substituted.",
+                `${uploadsNothingLine(telemetryDisclosure, "Nothing was uploaded.")} No sample data was substituted.`,
                 ...warnings.map((warning) => `! ${warning}`),
                 "",
                 "Next",
-                "  npx aibill doctor --sources       see the exact evidence gap and setup paths"
+                "  npx aibill doctor --sources       see the exact evidence gap and setup paths",
+                `  ${signupCopy.receiptPointer}`
             ].join("\n")
             : "",
         stderr: surface === "receipt"
@@ -992,7 +1205,7 @@ function dataModeBanner(mode, records) {
         return "DATA MODE: connected provider billing";
     return "DATA MODE: demo sample (illustrative — not your real spend)";
 }
-async function doctorCommand(args) {
+async function doctorCommand(args, runtime = {}) {
     if (args.sources) {
         return doctorSourcesCommand(args);
     }
@@ -1057,7 +1270,9 @@ async function doctorCommand(args) {
         "aibill doctor",
         `node version: ${process.version}`,
         `cli version: ${await cliVersion()}`,
-        "local-first mode: enabled (no cloud upload, no telemetry)",
+        runtime.telemetryDisclosure === true
+            ? "local-first mode: enabled (evidence stays local · anonymous command counts shared · aibill telemetry off)"
+            : "local-first mode: enabled (no cloud upload, no telemetry)",
         `path: ${rootPath}`,
         `state directory: ${stateDir}`,
         `state mode: ${stateMode}`,
@@ -1171,10 +1386,22 @@ async function doctorSourcesCommand(args) {
             .sort((left, right) => right.approvedAt.localeCompare(left.approvedAt))[0];
         const stateCheckedAt = attempt?.checkedAt
             ?? (providerState.provider === id ? providerState.fetchedAt : undefined);
+        // Multi-account honesty: when this provider's records carry account
+        // slices (one Admin key covers ONE organization), name every slice so a
+        // second org's sync is visibly accumulated rather than silently merged.
+        const accountSliceNote = records.some((record) => typeof record.source.account === "string")
+            ? ` Account slices: ${formatProviderAccountSlices(providerAccountSlices(records, id))}.`
+            : "";
+        // QA M1: two slices holding identical records are almost certainly one
+        // organization synced under two references — the combined total counts
+        // it twice, so doctor must say so where the slices are listed.
+        const duplicateSliceNote = duplicateProviderAccountSliceWarnings(records, id)
+            .map((warning) => ` WARNING: ${warning}`)
+            .join("");
         observations.push({
             id,
             financialEvidence: evidence,
-            financialEvidenceNote: providerFinancialEvidenceNote(records, evidence),
+            financialEvidenceNote: `${providerFinancialEvidenceNote(records, evidence)}${accountSliceNote}${duplicateSliceNote}`,
             // A connector stub is only configuration, not a source check. Older
             // successful syncs predate source-status.json, so their non-missing
             // registry approval time is the conservative migration fallback.
@@ -1604,7 +1831,9 @@ async function installStatuslineCommand(args, runtime) {
                 ? "aibill statusline is already installed in Claude user settings."
                 : "aibill statusline installed in Claude user settings.",
             "Claude Code: run /status to verify the active setting and every managed source.",
-            "The renderer reads only the private aibill cache; it never reads Claude's session stdin as financial evidence."
+            "The renderer reads only the private aibill cache; it never reads Claude's session stdin as financial evidence.",
+            // Static pointer only — never a prompt (capture design moments map).
+            signupCopy.statuslinePointer
         ].join("\n"));
     }
     catch (error) {
@@ -1733,7 +1962,8 @@ async function initCommand(args, runtime = {}) {
         trustedProviderState: persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted === true,
         untrustedProviderState: persisted?.mode === "connected_provider" && persisted.connectedTrust?.trusted !== true,
         scanError,
-        cacheStatus
+        cacheStatus,
+        ...(runtime.telemetryDisclosure !== undefined ? { telemetryDisclosure: runtime.telemetryDisclosure } : {})
     });
     if (!args.statusline) {
         return ok(`${receipt}\noptional Claude Code status line: npx aibill statusline install`);
@@ -2170,15 +2400,37 @@ function expansionFreshness(snapshot, now) {
             : seconds < 48 * 3_600
                 ? `${Math.floor(seconds / 3_600)}h`
                 : `${Math.floor(seconds / 86_400)}d`;
-    return ageMs > 5 * 60 * 1_000 ? `stale ${age}` : `updated ${age}`;
+    // Same freshness vocabulary as the statusline runner: state the cache age
+    // as fact instead of calling minutes-old data "stale".
+    return ageMs > 5 * 60 * 1_000 ? `cache ${age} old` : `updated ${age}`;
 }
 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({
+        ...(cacheDirectory ? { cacheDirectory } : {})
+    })))) {
+        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) {
+    try {
+        const info = await lstat(path);
+        if (info.isSymbolicLink() || !info.isDirectory())
+            return false;
+        return (await readdir(path)).length === 0;
+    }
+    catch {
+        return false;
+    }
+}
 async function preserveOrCreateInitRegistry(stateDir, rootPath, asOf, existing) {
     if (existing) {
         // Leave the valid contract byte-for-byte alone. Rewriting would drop
@@ -2389,9 +2641,12 @@ function formatInitReceipt(input) {
         ...diagnosticLines,
         input.scanError ? `  ! scan failed: ${input.scanError}` : "",
         "",
-        `status cache: ${input.cacheStatus} · private local aggregate · nothing uploaded`,
+        `status cache: ${input.cacheStatus} · private local aggregate · ${uploadsNothingLine(input.telemetryDisclosure, "nothing uploaded")}`,
         "state: .ai-spend-agent",
         "manifest: written last",
+        // Static pointer only, ABOVE the strict single next-command exit line —
+        // init's `next:` line stays last (capture design moments map).
+        signupCopy.initPointer,
         "next: npx aibill doctor --sources"
     ].filter((line) => line !== "").join("\n");
 }
@@ -2844,7 +3099,9 @@ async function listSourcesCommand(args) {
 // not first-run blockers.
 const selfServeProviders = new Set(["openai", "anthropic"]);
 const adminUpgradeProviders = {
-    cursor: "requires a Cursor TEAM-ADMIN key (Business plan only)",
+    // Cursor's Admin API is gated to Enterprise teams (cursor.com/docs/api);
+    // Business/Teams keys are rejected with 401/403.
+    cursor: "requires a Cursor TEAM-ADMIN key (Enterprise teams only)",
     "github-copilot": "requires a GitHub BILLING-ADMIN token (org/enterprise)",
     copilot: "requires a GitHub BILLING-ADMIN token (org/enterprise)"
 };
@@ -2866,7 +3123,8 @@ function providerSyncSetupCommand(provider, adminRef) {
     if (provider === "github-copilot") {
         return `npx aibill sync-provider --provider github-copilot --auth-reference ${adminRef} --org <organization>`;
     }
-    return `npx aibill sync-provider --provider ${provider} --auth-reference ${adminRef} --start-time <unix>`;
+    const thirtyDaysAgoUnix = Math.floor(Date.now() / 1_000) - 30 * 24 * 60 * 60;
+    return `npx aibill sync-provider --provider ${provider} --auth-reference ${adminRef} --start-time ${thirtyDaysAgoUnix}`;
 }
 async function connectCommand(args) {
     const rootPath = resolve(args.path);
@@ -2954,6 +3212,10 @@ async function connectCommand(args) {
         lines.push("");
         lines.push(`next: export an admin key reference, e.g. ${adminRef}, then run:`);
         lines.push(`  ${providerSyncSetupCommand(provider, adminRef)}`);
+        lines.push("  (that start time is 30 days ago; change it to widen the window)");
+    }
+    if (provider === "openai") {
+        lines.push("multi-org: an Admin API key covers ONE organization; repeat the sync with a separate env reference per org (e.g. env:OPENAI_ADMIN_KEY_ORG2) — org totals accumulate");
     }
     lines.push(`missing: ${source.fieldsMissing.join(", ")}`);
     return ok(lines.join("\n"));
@@ -3064,7 +3326,18 @@ async function syncProviderCommand(args) {
             enterprise: args.enterprise,
             accountId: args.accountId
         });
-        const syncedRecords = applyProviderContractGate(result.records);
+        // Admin credentials are account-scoped (an OpenAI Admin key covers ONE
+        // organization). Each sync belongs to one account slice: different slices
+        // of the same provider accumulate, re-syncing the same slice replaces it,
+        // and unlabeled legacy rows are replaced fail-closed (never double-count).
+        const accountKey = providerAccountKey({
+            provider,
+            authReference: args.authReference,
+            org: args.org,
+            enterprise: args.enterprise,
+            accountId: args.accountId
+        });
+        const syncedRecords = tagProviderAccountRecords(applyProviderContractGate(result.records), accountKey);
         const syncedFinancials = summarizeProviderFinancials(syncedRecords);
         const syncedCompleteness = providerFinancialCompleteness(syncedRecords, result.coverage);
         const syncedSource = createProviderConnection({
@@ -3076,8 +3349,9 @@ async function syncProviderCommand(args) {
             completeness: syncedCompleteness,
             fetchedAt: new Date(result.fetchedAt)
         });
+        const retainedPriorRecords = retainProviderRecordsForNewSync(trustedPrior?.records ?? [], result.provider, accountKey, syncedRecords);
         const records = applyProviderContractGate([
-            ...(trustedPrior?.records ?? []).filter((record) => record.source.provider !== result.provider),
+            ...retainedPriorRecords,
             ...syncedRecords
         ]).sort((left, right) => left.timestamp.localeCompare(right.timestamp));
         const registry = await readSourceRegistry(stateDir, rootPath);
@@ -3085,27 +3359,59 @@ async function syncProviderCommand(args) {
         const headlineRecords = selectProviderFinancialHeadlineRecords(records);
         const summary = analyzeSpend(headlineRecords);
         const mappings = attributeUsageRecords(records);
+        // Whether prior account slices of THIS provider survived the merge. When
+        // they did, the provider-keyed accounting maps below must stay honest for
+        // the union of slices, not just the slice this run fetched.
+        const retainedSameProviderSlices = retainedPriorRecords.some((record) => record.source.provider === result.provider);
         const qaByProvider = {
             ...trustedAccountingMap(trustedPrior?.accounting, "qaByProvider"),
             [result.provider]: result.qa
         };
+        const priorProviderCoverage = trustedAccountingMap(trustedPrior?.accounting, "coverageByProvider")[result.provider];
+        // Fail-closed coverage: a provider is complete only when this sync AND
+        // every retained slice were complete. Known ratchet (QA m4): per-slice
+        // coverage is not persisted, so with other slices retained a prior
+        // "partial" sticks even after the offending slice re-syncs complete —
+        // it only UNDER-claims, and recovers when the provider merges with no
+        // other slices retained (single-slice re-sync), after `aibill
+        // drop-slice` removes the stale slice, or after `aibill reset`. The
+        // checkedAt merge below shares the same ratchet and recovery direction.
+        const mergedProviderCoverage = retainedSameProviderSlices && priorProviderCoverage === "partial"
+            ? "partial"
+            : result.coverage;
         const coverageByProvider = {
             ...trustedAccountingMap(trustedPrior?.accounting, "coverageByProvider"),
-            [result.provider]: result.coverage
+            [result.provider]: mergedProviderCoverage
         };
+        // Financials span every retained slice of the provider plus this sync —
+        // never just the account this run happened to fetch.
         const financialsByProvider = {
             ...trustedAccountingMap(trustedPrior?.accounting, "financialsByProvider"),
-            [result.provider]: syncedFinancials
+            [result.provider]: summarizeProviderFinancials(records.filter((record) => record.source.provider === result.provider))
         };
+        const priorProviderCheckedAt = trustedAccountingMap(trustedPrior?.accounting, "checkedAtByProvider")[result.provider];
+        // Freshness stays conservative: a retained slice keeps its older check
+        // time, so an old account slice is never claimed as freshly checked.
+        const mergedProviderCheckedAt = retainedSameProviderSlices &&
+            typeof priorProviderCheckedAt === "string" &&
+            validIsoString(priorProviderCheckedAt) &&
+            priorProviderCheckedAt < result.fetchedAt
+            ? priorProviderCheckedAt
+            : result.fetchedAt;
         const checkedAtByProvider = {
             ...trustedAccountingMap(trustedPrior?.accounting, "checkedAtByProvider"),
-            [result.provider]: result.fetchedAt
+            [result.provider]: mergedProviderCheckedAt
         };
         const priorCoverageIntervals = trustedAccountingMap(trustedPrior?.accounting, "coverageIntervalsByProvider");
         const coverageIntervalsByProvider = Object.fromEntries(Object.entries(priorCoverageIntervals).filter(([provider]) => provider !== result.provider));
         const requestedCoverageInterval = result.coverageInterval;
-        if (requestedCoverageInterval) {
-            coverageIntervalsByProvider[result.provider] = requestedCoverageInterval;
+        // The provider's claimed window must hold for EVERY retained slice, so it
+        // shrinks to the intersection — and disappears when slices do not overlap.
+        const mergedProviderInterval = retainedSameProviderSlices
+            ? intersectProviderCoverageIntervals(priorCoverageIntervals[result.provider], requestedCoverageInterval)
+            : requestedCoverageInterval;
+        if (mergedProviderInterval) {
+            coverageIntervalsByProvider[result.provider] = mergedProviderInterval;
         }
         // Invalidate any earlier receipt before the first mutation. If a later
         // local write fails, the partially updated repository state stays
@@ -3157,6 +3463,22 @@ async function syncProviderCommand(args) {
             `financial evidence: ${syncedSource.financialEvidence}`,
             `coverage: ${result.coverage}`,
             `records fetched: ${result.records.length}`,
+            `account: ${accountKey}`,
+            `provider accounts: ${formatProviderAccountSlices(providerAccountSlices(records, result.provider))}`,
+            // QA M2: billed dollars never disappear without a word — every dropped
+            // prior slice is named with its record count and billed sum.
+            ...providerSliceReplacementNotices({
+                provider: result.provider,
+                accountKey,
+                priorRecords: trustedPrior?.records ?? [],
+                retainedRecords: retainedPriorRecords,
+                syncedRecordCount: syncedRecords.length,
+                syncedBilledUsd: syncedFinancials.providerReportedBilledUsd
+            }).map((notice) => `notice: ${notice}`),
+            // QA M1: identical inner record ids across two named slices are the
+            // signature of one organization synced under two references.
+            ...duplicateProviderAccountSliceWarnings(records, result.provider)
+                .map((warning) => `warning: ${warning}`),
             provider === "cursor"
                 ? "source window: current team subscription cycle returned by Cursor"
                 : provider === "github-copilot"
@@ -3185,6 +3507,130 @@ async function syncProviderCommand(args) {
         };
     }
 }
+/**
+ * `aibill drop-slice --provider X --account KEY` — remove one named account
+ * slice from trusted connected state. This is the prune path for the
+ * duplicate-slice diagnostic (one organization synced under two references)
+ * and for a slice whose credential reference was renamed: without it the only
+ * cleanup is a full `aibill reset` plus re-sync of every org. Local-only; no
+ * provider is contacted; the re-signed state can only shrink totals.
+ */
+async function dropSliceCommand(args) {
+    const rootPath = resolve(args.path);
+    const requestedProvider = (args.provider ?? "").trim().toLowerCase();
+    const provider = providerAliases[requestedProvider] ?? requestedProvider;
+    const accountKey = (args.account ?? "").trim();
+    if (!provider || !supportedAdminProviders.has(provider) || !accountKey) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: [
+                "drop-slice requires --provider (openai, anthropic, cursor, github-copilot) and --account <slice key>.",
+                "List the slices first: npx aibill doctor --sources",
+                "example: npx aibill drop-slice --provider openai --account env:OPENAI_ADMIN_KEY_ORG2"
+            ].join("\n")
+        };
+    }
+    const stateDir = await resolveSafeStateDirectory(rootPath, { create: true });
+    const persisted = await readPersistedSpend(rootPath);
+    if (!persisted || persisted.mode !== "connected_provider" || persisted.connectedTrust?.trusted !== true) {
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: "drop-slice requires trusted connected provider state. Run `npx aibill sync-provider ...` first, or `npx aibill reset` to clear all local state."
+        };
+    }
+    const droppedRecords = persisted.records.filter((record) => (record.source.provider === provider && record.source.account === accountKey));
+    if (droppedRecords.length === 0) {
+        const slices = providerAccountSlices(persisted.records, provider);
+        return {
+            exitCode: 1,
+            stdout: "",
+            stderr: [
+                `No ${provider} slice matches account "${sanitizeSecretishError(accountKey)}".`,
+                slices.length > 0
+                    ? `Known ${provider} slices: ${formatProviderAccountSlices(slices)}`
+                    : `No ${provider} slices exist in local state.`,
+                "Unlabeled legacy rows cannot be dropped by account; re-syncing the provider replaces them."
+            ].join("\n")
+        };
+    }
+    const records = persisted.records.filter((record) => !(record.source.provider === provider && record.source.account === accountKey));
+    const summary = analyzeSpend(selectProviderFinancialHeadlineRecords(records));
+    const mappings = attributeUsageRecords(records);
+    const providerRemaining = records.filter((record) => record.source.provider === provider);
+    // Rebuild the provider-keyed accounting maps. Financials are recomputed
+    // over the remaining slices; coverage/checkedAt/intervals are left as-is —
+    // they can only UNDER-claim after a drop (partial stays partial, windows
+    // stay narrow) and recover on the provider's next sync. A provider with no
+    // remaining records loses its map entries entirely.
+    const accounting = isPlainObject(persisted.accounting)
+        ? { ...persisted.accounting }
+        : {};
+    for (const mapName of [
+        "coverageByProvider",
+        "checkedAtByProvider",
+        "coverageIntervalsByProvider",
+        "qaByProvider",
+        "financialsByProvider"
+    ]) {
+        const prior = trustedAccountingMap(persisted.accounting, mapName);
+        if (Object.keys(prior).length === 0)
+            continue;
+        const next = { ...prior };
+        if (providerRemaining.length === 0) {
+            delete next[provider];
+        }
+        else if (mapName === "financialsByProvider") {
+            next[provider] = summarizeProviderFinancials(providerRemaining);
+        }
+        if (Object.keys(next).length > 0)
+            accounting[mapName] = next;
+        else
+            delete accounting[mapName];
+    }
+    const droppedFinancials = summarizeProviderFinancials(droppedRecords);
+    const droppedBilled = droppedFinancials.providerReportedBilledUsd;
+    await invalidateConnectedSpendTrustReceipt(rootPath);
+    await writeLocalSpendState(stateDir, records, summary, mappings, "connected_provider", accounting, persisted.checkedAt ?? new Date().toISOString());
+    // Keep provider-records.json consistent with the receipt-bound spend state
+    // (same records + maps); a missing file is tolerable — spend.json is the
+    // receipt-bound truth.
+    try {
+        const providerFile = await readJson(join(stateDir, "provider-records.json"));
+        await writeJson(join(stateDir, "provider-records.json"), {
+            ...providerFile,
+            records,
+            ...(accounting.qaByProvider !== undefined ? { qaByProvider: accounting.qaByProvider } : {}),
+            ...(accounting.checkedAtByProvider !== undefined ? { checkedAtByProvider: accounting.checkedAtByProvider } : {}),
+            ...(accounting.coverageByProvider !== undefined ? { coverageByProvider: accounting.coverageByProvider } : {}),
+            ...(accounting.coverageIntervalsByProvider !== undefined
+                ? { coverageIntervalsByProvider: accounting.coverageIntervalsByProvider }
+                : {}),
+            ...(accounting.financialsByProvider !== undefined ? { financialsByProvider: accounting.financialsByProvider } : {})
+        });
+    }
+    catch {
+        // Diagnostic mirror only; never block the drop on it.
+    }
+    await appendAuditEvent(stateDir, {
+        timestamp: new Date().toISOString(),
+        action: "source_scanned",
+        sourceId: `${provider}-provider-api`,
+        detail: `drop-slice removed the ${provider} account slice "${accountKey}" (${droppedRecords.length} record(s), ${droppedBilled === null ? "no billed evidence" : `billed ${formatOptionalUsd(droppedBilled)}`}). Local state maintenance only; no provider was contacted.`
+    });
+    await writeConnectedSpendTrustReceipt(rootPath, await readSafeStateText(stateDir, "spend.json"), { sourceRegistryContents: await readSafeStateText(stateDir, "sources.json") });
+    const remainingSlices = providerAccountSlices(records, provider);
+    return ok([
+        "aibill drop-slice",
+        `provider: ${provider}`,
+        `dropped account: ${accountKey}`,
+        `records removed: ${droppedRecords.length} (${droppedBilled === null ? "no billed evidence" : `billed ${formatOptionalUsd(droppedBilled)}`})`,
+        `remaining provider accounts: ${remainingSlices.length > 0 ? formatProviderAccountSlices(remainingSlices) : "none"}`,
+        `combined headline spend: ${selectProviderFinancialHeadlineRecords(records).some((record) => typeof record.amountUsd === "number") ? formatOptionalUsd(summary.totalUsd) : "unavailable"}`,
+        "note: coverage and freshness labels stay conservative until the provider is re-synced"
+    ].join("\n"));
+}
 function formatOptionalUsd(value) {
     if (value === null)
         return "unavailable";
@@ -3252,7 +3698,7 @@ async function confirmMappingCommand(args) {
         `confidence: ${mapping.confidence}`
     ].join("\n"));
 }
-async function reportCommand(args) {
+async function reportCommand(args, runtime = {}) {
     const rootPath = resolve(args.path);
     try {
         const sinceDays = args.sinceDays ?? 30;
@@ -3289,9 +3735,11 @@ async function reportCommand(args) {
         const reportExperimentProjection = reportableExperiment
             ? buildActionVerificationProjectionV0(reportableExperiment)
             : undefined;
+        const telemetryDisclosure = runtime.telemetryDisclosure === true;
         const reportRenderInput = reportableExperiment
             ? {
                 ...reportInput,
+                telemetryDisclosure,
                 tokenExperiment: {
                     id: reportableExperiment.id,
                     lifecycle: reportableExperiment.lifecycle,
@@ -3301,7 +3749,7 @@ async function reportCommand(args) {
                     nextCommand: improveRuntimeCommand
                 }
             }
-            : reportInput;
+            : { ...reportInput, telemetryDisclosure };
         const qualitativeActionsSuppressed = reportInput.dataMode !== "sample" &&
             reportInput.qualitativeCoverage?.status !== "complete";
         const outBase = args.out ? resolve(rootPath, args.out) : join(stateDir, "report");
@@ -3352,7 +3800,9 @@ async function reportCommand(args) {
                     !(reportInput.allRecords ?? reportInput.providerRecords ?? []).some((record) => typeof record.amountUsd === "number")
                     ? "cost/value evidence total: Unavailable · no priced financial evidence; missing/null is not zero"
                     : `cost/value evidence total: ${formatOptionalUsd(reportInput.summary.totalUsd)}`,
-            "privacy: report rendered locally with no aibill telemetry; only explicit sync-provider contacts the selected provider",
+            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 with no aibill telemetry; only explicit sync-provider contacts the selected provider",
             "",
             "next:",
             `  open ${htmlPath}       view the full report in your browser`,
@@ -3497,23 +3947,121 @@ async function guardExactProjectRoot(commandName, requestedPath) {
         ].join("\n")
     };
 }
+/* ------------------------------------------------------------------ */
+/* Agent-draft screening copy (AGENT_NATIVE_LOOP_DESIGN.md §5, A1-A11)  */
+/* ------------------------------------------------------------------ */
+/**
+ * A1 · plan banner, printed once before step 1 when at least one
+ * agent-drafted sentence survived screening. The final line IS the shared
+ * `userSafetyLine` constant, rendered verbatim and unwrapped (n1) so QA 25
+ * can assert byte-identity across the CLI banner, `agentLoop`, and
+ * `draft_improve_command`.
+ */
+const agentDraftPlanBanner = [
+    "Your agent helped draft this plan. Nothing is approved yet: review each",
+    "sentence, press Enter to accept it or type your own, and only the APPROVE",
+    "you type at the end authorizes anything.",
+    IMPROVE_USER_SAFETY_LINE_V1
+].join("\n");
+/** A4 · whole-draft set-asides. */
+const agentDraftUnreadableNotice = [
+    "Your agent's draft could not be read (not a valid ab1 draft token).",
+    "Continuing with aibill's own suggestions. Ask your agent to call",
+    "draft_improve_command again and hand you the exact command it returns."
+].join("\n");
+const agentDraftStaleNotice = [
+    "Your agent's draft was made for a different test or an older revision of",
+    "this one, so it was set aside. Ask your agent to re-read",
+    "get_token_reduction_test and draft again."
+].join("\n");
+const agentDraftNoTestNotice = [
+    "There is no frozen baseline yet, so a drafted plan cannot attach to a test.",
+    "Finish the two start questions first; then ask your agent to draft against",
+    "the new test id."
+].join("\n");
+/** A5 · --draft while a plan awaits its record. */
+const agentDraftAfterApprovalNotice = [
+    "A plan is already approved and waiting for its result, so the draft was",
+    "not used. Record what happened below."
+].join("\n");
+/** A7 · record flags with no approved plan. */
+const recordFlagsNoApprovalNotice = [
+    "No plan is approved yet, so --record-applied-at/--record-canary were not",
+    "used. Approve a plan first."
+].join("\n");
+/** A7 · applied-at prefill set aside (reason = exact time-classifier copy). */
+function recordTimeSetAsideNotice(reason) {
+    return [
+        `Your agent's applied-at time was set aside: ${reason}`,
+        "Answer the question yourself below."
+    ].join("\n");
+}
+/** A8 · non-interactive run with any draft/record flag. */
+const agentFlagsNonInteractiveNote = [
+    "Agent drafts and record values only pre-fill the interactive flow; nothing",
+    "was recorded. Run this command in an interactive terminal."
+].join("\n");
+/** A10 · verify-flag confusion on improve. */
+const verifyFlagConfusionNote = [
+    "Note: --applied-at/--canary belong to the advanced verify commands. With",
+    "improve, use --record-applied-at and --record-canary."
+].join("\n");
+/** A9 · demo variant banner (binding is checked only in a real run). */
+const demoDraftBanner = [
+    "DEMO: your agent's draft is used for practice only. Draft binding to a real",
+    "test id and revision is checked only in a real run. Nothing is recorded."
+].join("\n");
+/**
+ * Screen a decoded draft with the SAME shared core path the MCP composition
+ * preview uses (`screenAgentDraftSentence`), field by field. A rejected
+ * field falls back to aibill's own suggestion — and to aibill's label; a
+ * surviving field carries `provenance: "agent"` so only genuinely
+ * agent-authored words ever render `Drafted with your agent` (B1, QA 17).
+ */
+function screenAgentDraftSentences(draft) {
+    const answers = {};
+    const setAsideNotices = [];
+    let survivors = 0;
+    for (const field of ["change", "rollback", "canary"]) {
+        const verdict = screenAgentDraftSentence(draft[field]);
+        if (verdict.ok) {
+            answers[field] = { value: verdict.value, provenance: "agent" };
+            survivors += 1;
+        }
+        else {
+            // A3 · the reason is the classifier's exact reprompt message; the
+            // credential path's message never contains the rejected text.
+            setAsideNotices.push([
+                `Your agent's ${field} draft was set aside: ${verdict.reason}`,
+                "aibill's own suggestion is shown for that step instead, labeled Suggested."
+            ].join("\n"));
+        }
+    }
+    return { answers, setAsideNotices, survivors };
+}
 /**
  * `improve --sample`: the full guided questionnaire against synthetic
  * evidence so a new user can practice every step safely. Fail-closed by
  * construction: this function never receives a draft store or persistence
  * path — no experiment, ownership, approval, draft, or file is written.
+ * With `--draft` (A9) the demo decodes and screens the token exactly like a
+ * real run — practicing the screening is the point — but skips the binding
+ * check, because there is no real test to bind to.
  */
-async function demoImproveCommand(runtime) {
+async function demoImproveCommand(args, runtime) {
     const demoNext = {
         reason: "run the real flow from inside one exact project",
         command: improveRuntimeCommand
     };
+    const hasAgentFlags = args.agentDraftToken !== undefined ||
+        args.recordAppliedAt !== undefined || args.recordCanary !== undefined;
     const guidedIo = runtime.interactive ? await createGuidedIo(runtime) : undefined;
     if (!runtime.interactive || !guidedIo) {
         return ok(renderCleanExit({
             lines: [
                 "aibill improve · DEMO · synthetic sample — practice run, nothing is recorded",
-                "Demo sample data can never start a token test."
+                "Demo sample data can never start a token test.",
+                ...(hasAgentFlags ? [agentFlagsNonInteractiveNote] : [])
             ],
             next: {
                 reason: "practice the guided token test safely in an interactive terminal",
@@ -3527,6 +4075,35 @@ async function demoImproveCommand(runtime) {
         demo: true
     };
     guidedIo.write("Demo sample data can never start a token test.");
+    // A9 · decode + screen exactly like a real run; binding is not checked.
+    const demoDraft = args.agentDraftToken !== undefined
+        ? decodeAgentDraftTokenV1(args.agentDraftToken)
+        : undefined;
+    let demoSuggestedAnswers = {
+        change: {
+            value: "Start with only the files and instructions this task needs.",
+            provenance: "aibill"
+        },
+        rollback: { value: "Restore the prior session workflow.", provenance: "aibill" },
+        canary: {
+            value: "The project tests pass and the requested output is accepted.",
+            provenance: "aibill"
+        }
+    };
+    const demoDraftNotices = [];
+    if (demoDraft !== undefined) {
+        guidedIo.write(demoDraftBanner);
+        if (!demoDraft.ok) {
+            demoDraftNotices.push(agentDraftUnreadableNotice);
+        }
+        else {
+            const screened = screenAgentDraftSentences(demoDraft.draft);
+            if (screened.survivors > 0)
+                demoDraftNotices.push(agentDraftPlanBanner);
+            demoDraftNotices.push(...screened.setAsideNotices);
+            demoSuggestedAnswers = { ...demoSuggestedAnswers, ...screened.answers };
+        }
+    }
     const demoComplete = (firstLine) => ok(renderCleanExit({
         lines: [
             firstLine,
@@ -3543,6 +4120,9 @@ async function demoImproveCommand(runtime) {
     if (start.action !== "start") {
         return demoComplete("DEMO ENDED · nothing was created or stored");
     }
+    if (demoDraftNotices.length > 0) {
+        guidedIo.write(demoDraftNotices.join("\n\n"));
+    }
     const plan = await runPlanSitting(guidedIo, {
         header,
         experimentId: "DEMO-tre_v0_0000000000000000",
@@ -3550,11 +4130,7 @@ async function demoImproveCommand(runtime) {
         sanitize: (value) => value,
         nowIso: () => new Date().toISOString(),
         approveExtraLine: "This is a practice approval. It is not recorded and creates no claim.",
-        suggestedAnswers: {
-            change: "Start with only the files and instructions this task needs.",
-            rollback: "Restore the prior session workflow.",
-            canary: "The project tests pass and the requested output is accepted."
-        }
+        suggestedAnswers: demoSuggestedAnswers
     });
     return demoComplete(plan.action === "approved"
         ? "DEMO COMPLETE · nothing was created or stored"
@@ -3622,21 +4198,48 @@ function createPlanDraftStore(rootPath) {
         }
     };
 }
+/**
+ * The approved-plan agent handoff (§2e): symmetric with the record leg. The
+ * record command placeholder line lives INSIDE the quoted agent text, not in
+ * a NEXT COMMAND block, so the one-command exit contract is untouched.
+ */
 function improveAgentInstruction(changeSentence) {
     return [
         `"Execute only the pre-approved reversible plan: ${changeSentence}`,
-        "Make no other optimization, preserve the approved rollback, run the",
-        "approved canary, and report the exact UTC ISO-8601 time the change was",
-        'applied plus whether that exact canary passed or failed."'
+        "Make no other optimization, preserve the approved rollback, and run the",
+        "approved canary. Then report the exact UTC ISO-8601 time the change was",
+        "applied and whether that exact canary passed or failed — if the canary has",
+        "not run, say so instead. Give the user this one command with the time",
+        "filled in:",
+        `  ${actionRuntimeCommand("improve --record-applied-at <time> --record-canary <passed|failed>")}`,
+        "That command only pre-fills the applied-at question; the user types the",
+        'canary answer themselves in their terminal."'
     ].join("\n");
 }
+/**
+ * m12c: the record-backedOut re-show restates the FINDING label — the exact
+ * approved sentence is unrecoverable by design (hash-only persistence) — and
+ * must say so under the quoted text.
+ */
+const improveAgentInstructionHashCaveat = [
+    "(aibill keeps only hashes of your approved sentences; the plan above",
+    "restates the finding, not your exact approved wording.)"
+].join("\n");
 async function improveCommand(args, runtime) {
     if (args.sample) {
-        return demoImproveCommand(runtime);
+        return demoImproveCommand(args, runtime);
     }
     const rootGuard = await guardExactProjectRoot("improve", args.path);
     if (rootGuard)
         return rootGuard;
+    // §2c dispatch inputs. Decoding never throws; every set-aside prints one
+    // notice and CONTINUES — a bad draft never ends the run (P0B principle 2).
+    let agentDraft = args.agentDraftToken !== undefined
+        ? decodeAgentDraftTokenV1(args.agentDraftToken)
+        : undefined;
+    const hasRecordFlags = args.recordAppliedAt !== undefined || args.recordCanary !== undefined;
+    const hasAgentFlags = agentDraft !== undefined || hasRecordFlags;
+    let recordFlagsNoticed = false;
     const sinceDays = args.sinceDays ?? 30;
     if (!validSinceDays(sinceDays))
         return invalidSinceDaysResult();
@@ -3712,14 +4315,39 @@ async function improveCommand(args, runtime) {
         });
         const guidedIo = runtime.interactive ? await createGuidedIo(runtime) : undefined;
         if (!runtime.interactive || !guidedIo) {
+            // A8 · drafts and record values are prefills for the interactive flow
+            // only; the read-only render must say nothing was recorded.
+            const readOnlyNote = "No experiment, approval, or project state changed. The private local evidence cache may refresh. Run this command in an interactive terminal to start or record a test." +
+                (hasAgentFlags ? `\n${agentFlagsNonInteractiveNote}` : "");
             return ok(renderImproveExperience(model, {
-                note: "No experiment, approval, or project state changed. The private local evidence cache may refresh. Run this command in an interactive terminal to start or record a test.",
+                note: readOnlyNote,
                 ...(improveProjectLine ? { projectLine: improveProjectLine } : {})
             }));
         }
         const commandTitle = "aibill improve · one reversible token test";
         const experimentTag = (id) => id ? `test ${id.slice(0, 15)}` : "test: none yet";
+        // A10 · the verify flags do not belong to improve; say so and ignore.
+        if (args.appliedAt !== undefined || args.canary !== undefined) {
+            guidedIo.write(verifyFlagConfusionNote);
+        }
+        // Phases past plan/record (collecting, rollback, terminal): the flags
+        // have no question to pre-fill; say so once instead of failing.
+        if (hasAgentFlags &&
+            model.phase !== "start" && model.phase !== "awaiting_intervention") {
+            guidedIo.write("The current step needs no draft or record values, so they were not used.");
+        }
         if (model.phase === "start" && !preferred) {
+            // §2c dispatch 2: a plan draft cannot bind before the freeze — the
+            // experimentId is created at freeze. The draft is set aside NOW; after
+            // the freeze the plan sitting uses aibill's own suggestions.
+            if (agentDraft !== undefined) {
+                guidedIo.write(agentDraftNoTestNotice);
+                agentDraft = undefined;
+            }
+            if (hasRecordFlags && !recordFlagsNoticed) {
+                guidedIo.write(recordFlagsNoApprovalNotice);
+                recordFlagsNoticed = true;
+            }
             const start = await runStartSitting(guidedIo, {
                 header: { commandTitle, experimentLabel: experimentTag() },
                 findingLabel: model.oneChange.label,
@@ -3786,6 +4414,54 @@ async function improveCommand(args, runtime) {
                     }
                     : undefined;
                 const draftStore = createPlanDraftStore(rootPath);
+                // §2c dispatch 3: record flags cannot apply before an approval.
+                if (hasRecordFlags && !recordFlagsNoticed) {
+                    guidedIo.write(recordFlagsNoApprovalNotice);
+                    recordFlagsNoticed = true;
+                }
+                // The machine drafts; the human approves. aibill already knows the
+                // change it found — never make the user re-type a worse version.
+                // Every fallback field carries aibill's OWN provenance so it can
+                // never render under the agent label (B1).
+                const aibillSuggestions = {
+                    change: {
+                        value: model.oneChange.label.endsWith(".")
+                            ? model.oneChange.label
+                            : `${model.oneChange.label}.`,
+                        provenance: "aibill"
+                    },
+                    rollback: {
+                        value: "Restore the prior session workflow.",
+                        provenance: "aibill"
+                    },
+                    canary: {
+                        value: "The project tests pass and the requested output is accepted.",
+                        provenance: "aibill"
+                    }
+                };
+                let suggestedAnswers = aibillSuggestions;
+                const draftNotices = [];
+                if (agentDraft !== undefined) {
+                    if (!agentDraft.ok) {
+                        draftNotices.push(agentDraftUnreadableNotice);
+                    }
+                    else if (agentDraft.draft.experimentId !== preferred.id ||
+                        agentDraft.draft.revisionId !== preferred.revisionId) {
+                        // Stale revision, wrong test, or a token replayed from another
+                        // project — the id simply does not match this project's test.
+                        draftNotices.push(agentDraftStaleNotice);
+                    }
+                    else {
+                        const screened = screenAgentDraftSentences(agentDraft.draft);
+                        if (screened.survivors > 0)
+                            draftNotices.push(agentDraftPlanBanner);
+                        draftNotices.push(...screened.setAsideNotices);
+                        suggestedAnswers = { ...aibillSuggestions, ...screened.answers };
+                    }
+                }
+                if (draftNotices.length > 0) {
+                    guidedIo.write(draftNotices.join("\n\n"));
+                }
                 const plan = await runPlanSitting(guidedIo, {
                     header,
                     experimentId: preferred.id,
@@ -3794,15 +4470,7 @@ async function improveCommand(args, runtime) {
                     draftStore,
                     sanitize: sanitizeLocalActivityText,
                     nowIso: () => new Date().toISOString(),
-                    // The machine drafts; the human approves. aibill already knows the
-                    // change it found — never make the user re-type a worse version.
-                    suggestedAnswers: {
-                        change: model.oneChange.label.endsWith(".")
-                            ? model.oneChange.label
-                            : `${model.oneChange.label}.`,
-                        rollback: "Restore the prior session workflow.",
-                        canary: "The project tests pass and the requested output is accepted."
-                    }
+                    suggestedAnswers
                 });
                 const rerunNext = { reason: "run this again to continue the plan", command: improveRuntimeCommand };
                 if (plan.action === "cancelled" || plan.action === "backedOut") {
@@ -3912,10 +4580,40 @@ async function improveCommand(args, runtime) {
             const approvedByLine = accountabilityState.ownership
                 ? `Approved ${approvedPlan.approvedAt} by ${accountabilityState.ownership.displayLabels.humanOwner} (${accountabilityState.ownership.approverRole.roleLabel})`
                 : `Approved ${approvedPlan.approvedAt}`;
+            // §2c dispatch 4: a plan is pre-approved — the draft (if any) is set
+            // aside (A5); the applied-at prefill is pre-screened with the FULL
+            // time classifier (approvedAtIso context) so before-approval/future
+            // values are set aside honestly NOW instead of at Enter (A7); the
+            // canary report NEVER prefills — claim line only, typed p/f/n (M6).
+            const recordNotices = [];
+            if (agentDraft !== undefined) {
+                recordNotices.push(agentDraftAfterApprovalNotice);
+            }
+            let suggestedRecord;
+            if (args.recordAppliedAt !== undefined) {
+                const timeVerdict = classifyGuidedAnswer("time", args.recordAppliedAt, {
+                    approvedAtIso: approvedPlan.approvedAt
+                });
+                if (timeVerdict.outcome === "accept") {
+                    suggestedRecord = { appliedAtIso: args.recordAppliedAt };
+                }
+                else {
+                    recordNotices.push(recordTimeSetAsideNotice(timeVerdict.outcome === "reject"
+                        ? timeVerdict.message
+                        : "the time could not be read"));
+                }
+            }
+            if (recordNotices.length > 0) {
+                guidedIo.write(recordNotices.join("\n\n"));
+            }
             const record = await runRecordSitting(guidedIo, {
                 header,
                 approvedAtIso: approvedPlan.approvedAt,
-                approvedByLine
+                approvedByLine,
+                ...(suggestedRecord !== undefined ? { suggested: suggestedRecord } : {}),
+                ...(args.recordCanary !== undefined
+                    ? { agentCanaryReport: args.recordCanary }
+                    : {})
             });
             if (record.action === "cancelled") {
                 return ok(renderCleanExit({
@@ -3927,9 +4625,12 @@ async function improveCommand(args, runtime) {
                 }));
             }
             if (record.action === "backedOut") {
+                // m12c: this path restates the FINDING label, not the approved
+                // sentence (hash-only persistence) — the caveat says so, indented
+                // inside the quoted block by renderForYourAgent.
                 return ok(renderCleanExit({
                     lines: [`${experimentTag(preferred.id)} · waiting for the applied change`],
-                    extraBlocks: [renderForYourAgent(improveAgentInstruction(model.oneChange.label))],
+                    extraBlocks: [renderForYourAgent(`${improveAgentInstruction(model.oneChange.label)}\n${improveAgentInstructionHashCaveat}`)],
                     next: { reason: "after the agent reports back, run exactly this", command: improveRuntimeCommand }
                 }));
             }
@@ -4652,7 +5353,8 @@ async function applyArtifactCommand(args) {
                 experiment.lifecycle !== "invalidated"));
             if (active) {
                 return tokenVerificationResult(active, false, [
-                    "An active token test already owns this project; Apply handed off to it and generated no conflicting candidate or artifacts."
+                    "An active token test already owns this project; Apply handed off to it and generated no conflicting candidate or artifacts.",
+                    `Use your agent normally on this project, then: ${improveRuntimeCommand}`
                 ]);
             }
         }
@@ -5219,13 +5921,17 @@ async function buildReportInput(stateDir, rootPath, sinceDays = 30, options = {}
         freshLocalCalls = freshActionLogs.calls;
         freshCodexInvocationFiles = freshActionLogs.codexInvocationFiles;
     }
+    // Financial and qualitative readers have separate truth contracts. Always
+    // read the bounded/streaming financial axis once: local mode uses it as the
+    // headline, while connected mode carries it into the saved report as a
+    // separate API-equivalent comparison that is never added to billed cost.
+    const freshFinancialLogs = await loadLocalAgentFinancialUsage({ financialIndex: cliFinancialIndex,
+        claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
+        codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
+        geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR,
+        sinceIso
+    }).catch(() => undefined);
     if (needsFreshLogs) {
-        const freshFinancialLogs = await loadLocalAgentFinancialUsage({ financialIndex: cliFinancialIndex,
-            claudeProjectsDir: process.env.AI_SPEND_CLAUDE_LOGS_DIR,
-            codexSessionsDir: process.env.AI_SPEND_CODEX_LOGS_DIR,
-            geminiSessionsDir: process.env.AI_SPEND_GEMINI_LOGS_DIR,
-            sinceIso
-        }).catch(() => undefined);
         if (freshFinancialLogs && freshFinancialLogs.records.length > 0) {
             const records = freshFinancialLogs.records;
             const summary = analyzeSpend(records);
@@ -5368,6 +6074,9 @@ async function buildReportInput(stateDir, rootPath, sinceDays = 30, options = {}
         allRecords: spendState.mode === "connected_provider"
             ? selectProviderFinancialHeadlineRecords(spendState.records ?? [])
             : spendState.records ?? [],
+        ...(spendState.mode === "connected_provider" && (freshFinancialLogs?.records.length ?? 0) > 0
+            ? { localFinancialRecords: freshFinancialLogs.records }
+            : {}),
         dataMode: spendState.mode,
         discovery,
         mappings: mappings ?? [],
@@ -5452,6 +6161,12 @@ function parseArgs(argv) {
         parsed.provider = rest[0];
         rest.shift();
     }
+    if (command === "signup" && rest[0] && !rest[0].startsWith("-")) {
+        parsed.signupEmail = rest.shift();
+    }
+    if (command === "telemetry" && rest[0] && !rest[0].startsWith("--")) {
+        parsed.telemetryAction = rest.shift();
+    }
     if (command === "verify") {
         const first = rest[0];
         if (first === "inspect" || first === "start" || first === "mark-applied" ||
@@ -5478,14 +6193,27 @@ function parseArgs(argv) {
         "--source-path", "--type", "--provider", "--source-id", "--team",
         "--person", "--client", "--cost-center", "--role", "--project", "--agent", "--workflow",
         "--evidence", "--confidence", "--label", "--auth-reference",
-        "--start-time", "--end-time", "--org", "--enterprise", "--account-id",
+        "--start-time", "--end-time", "--org", "--enterprise", "--account-id", "--account",
         "--interval", "--cycles", "--canary", "--quality", "--change-digest",
         "--rollback-digest", "--canary-digest", "--approved-at", "--applied-at",
-        "--pr", "--business-outcome"
+        "--pr", "--business-outcome",
+        "--draft", "--record-applied-at", "--record-canary",
+        "--ref"
     ]);
     const numericValueFlags = new Set([
         "--since-days", "--confidence", "--start-time", "--end-time", "--interval", "--cycles", "--pr"
     ]);
+    // A repeated --draft/--record-* flag means the pasted line was assembled
+    // from two commands: a parse error, never a silent last-wins (§2b, m11).
+    const seenOnceOnlyFlags = new Set();
+    const onceOnly = (flag) => {
+        if (seenOnceOnlyFlags.has(flag)) {
+            parsed.parseErrors.push(`${flag} may appear once`);
+            return false;
+        }
+        seenOnceOnlyFlags.add(flag);
+        return true;
+    };
     for (let index = 0; index < rest.length; index += 1) {
         const arg = rest[index];
         const nextValue = rest[index + 1];
@@ -5558,6 +6286,51 @@ function parseArgs(argv) {
             }
             continue;
         }
+        if (arg === "--draft") {
+            const next = rest[index + 1];
+            if (next) {
+                if (onceOnly("--draft")) {
+                    if (looksLikeAgentDraftToken(next)) {
+                        parsed.agentDraftToken = next;
+                    }
+                    else {
+                        parsed.parseErrors.push("--draft must be the single ab1.… token from draft_improve_command; do not hand-build or quote it");
+                    }
+                }
+                index += 1;
+            }
+            continue;
+        }
+        if (arg === "--record-applied-at") {
+            const next = rest[index + 1];
+            if (next) {
+                if (onceOnly("--record-applied-at")) {
+                    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2})?Z$/.test(next)) {
+                        parsed.recordAppliedAt = next;
+                    }
+                    else {
+                        parsed.parseErrors.push("--record-applied-at must be a UTC Z time, e.g. 2026-08-18T09:12:00Z");
+                    }
+                }
+                index += 1;
+            }
+            continue;
+        }
+        if (arg === "--record-canary") {
+            const next = rest[index + 1];
+            if (next) {
+                if (onceOnly("--record-canary")) {
+                    if (next === "passed" || next === "failed") {
+                        parsed.recordCanary = next;
+                    }
+                    else {
+                        parsed.parseErrors.push("--record-canary must be passed or failed");
+                    }
+                }
+                index += 1;
+            }
+            continue;
+        }
         if (arg === "--change-digest" || arg === "--rollback-digest" ||
             arg === "--canary-digest") {
             const next = rest[index + 1];
@@ -5576,6 +6349,30 @@ function parseArgs(argv) {
             parsed.ignoreState = true;
             continue;
         }
+        if (arg === "--forget") {
+            parsed.signupForget = true;
+            continue;
+        }
+        if (arg === "--never") {
+            parsed.signupNever = true;
+            continue;
+        }
+        if (arg === "--ref") {
+            const next = rest[index + 1];
+            if (next) {
+                // Allowlist sanitization happens here so nothing outside
+                // [a-z0-9-]{1,24} can ever reach the payload builder (QA 8).
+                const tag = sanitizeSignupRefTag(next);
+                if (tag === undefined) {
+                    parsed.parseErrors.push("--ref must be 1-24 lowercase letters, digits, or dashes (e.g. --ref starfund)");
+                }
+                else {
+                    parsed.signupRef = tag;
+                }
+                index += 1;
+            }
+            continue;
+        }
         if (arg === "--plan") {
             const next = rest[index + 1];
             if (next) {
@@ -5808,6 +6605,14 @@ function parseArgs(argv) {
             }
             continue;
         }
+        if (arg === "--account") {
+            const next = rest[index + 1];
+            if (next) {
+                parsed.account = next;
+                index += 1;
+            }
+            continue;
+        }
         if (arg === "--account-id") {
             const next = rest[index + 1];
             if (next) {
@@ -5862,8 +6667,13 @@ function parseArgs(argv) {
             }
             continue;
         }
+        // A11 (copy polish on the existing unknown-flag rejection): quoted
+        // per-sentence draft flags never existed — point at the one-token design.
+        const draftFlagHint = arg === "--draft-change" || arg === "--draft-rollback" || arg === "--draft-canary"
+            ? " — agent drafts travel as one --draft token from draft_improve_command, not as quoted sentences"
+            : "";
         parsed.parseErrors.push(arg.startsWith("-")
-            ? `unknown flag "${arg}"`
+            ? `unknown flag "${arg}"${draftFlagHint}`
             : `unexpected argument "${arg}"`);
     }
     return parsed;
@@ -5987,7 +6797,7 @@ function isNodeError(error, code) {
 function ok(stdout) {
     return { exitCode: 0, stdout, stderr: "" };
 }
-function helpText() {
+function helpText(telemetryDisclosure) {
     return [
         "aibill — your AI cost and usage evidence in one private view",
         "",
@@ -5997,11 +6807,11 @@ function helpText() {
         "  npx aibill --sample                  Show the clearly labeled illustrative demo (never implicit)",
         "  npx aibill --group-by agent          Drill down by source|model|client|project|agent|user|workspace|apiKey",
         "  npx aibill --plan <id>               Declare your plan when auto-detection can't (claude-max-5x|claude-max-20x|claude-pro|chatgpt-plus|chatgpt-pro)",
-        `  ${improveRuntimeCommand}    Source preview: test one personalized change and measure whether token usage fell`,
-        `  ${actionRuntimeCommand("index")}    Source preview: read very large agent histories to completion so results stop saying "indexing"`,
-        `  ${actionRuntimeCommand("identify")}    Source preview: confirm the human owner, team, client/cost center, and approval role`,
-        `  ${actionRuntimeCommand("outcome github")}    Source preview: attach one merged PR whose observed status checks passed`,
-        `  ${actionRuntimeCommand("accountability")}    Source preview: answer owner → outcome → approval → measured-result for this project`,
+        `  ${improveRuntimeCommand}    Test one personalized change and measure whether token usage fell`,
+        `  ${actionRuntimeCommand("index")}    Read very large agent histories to completion so results stop saying "indexing"`,
+        `  ${actionRuntimeCommand("identify")}    Confirm the human owner, team, client/cost center, and approval role`,
+        `  ${actionRuntimeCommand("outcome github")}    Attach one merged PR whose observed status checks passed`,
+        `  ${actionRuntimeCommand("accountability")}    Answer owner → outcome → approval → measured-result for this project`,
         "",
         "Add official provider-reported cost (ADMIN/owner-gated):",
         "  npx aibill connect openai            Requires an org-owner Admin credential reference",
@@ -6024,6 +6834,9 @@ function helpText() {
         "    [--replace]           Explicitly replace an existing statusLine while preserving it for uninstall",
         "  statusline uninstall    Remove only the owned setting and restore its preserved predecessor",
         "  statusline expand       Print every subscription with committed price, runways, and 7d API-equivalent",
+        "  signup <email> [--ref <token>]  Join the launch list · email only · the exact payload is shown before send",
+        "    [--never]             Never ask again (nothing is sent)   [--forget]  Clear local signup state",
+        "  telemetry [on|off]      Show anonymous command-count status + the exact last payload · switch it",
         "  doctor [--sources]      Launch diagnostics; --sources shows validation, evidence, freshness, and errors",
         "  reset [--path <dir>]    Clear persisted spend state (so sample state can't mask real logs)",
         "  --ignore-state          On the default/quickstart run, ignore persisted spend.json for this run",
@@ -6057,7 +6870,9 @@ function helpText() {
         "Cron (production watch): add a crontab entry such as:",
         "  0 * * * * cd /path/to/workspace && npx --yes aibill watch --interval 3600 --cycles 1 >> aibill-watch.log 2>&1",
         "",
-        "Privacy: local analysis and reports upload nothing. Only explicit sync-provider contacts the selected provider through an env: reference.",
+        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. 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");
 }
@@ -6093,10 +6908,40 @@ export async function runMain() {
     const argv = process.argv.slice(2);
     const command = argv[0];
     const isInstantDemo = !command || command === "quickstart" || command === "demo";
-    // Show a spinner only for the work-heavy instant-demo path, and only on a
-    // real TTY so piped output stays clean.
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const startedAtMs = Date.now();
+    // Bin-entry-only telemetry (notice-before-first-byte; see telemetry.ts).
+    // Embedded runCli callers and the MCP server never construct this, so
+    // they can never emit an event.
+    let telemetry;
+    try {
+        const { openCliTelemetry } = await import("./telemetry.js");
+        telemetry = await openCliTelemetry();
+    }
+    catch {
+        // Telemetry must never break the CLI.
+    }
+    // The during-scan signup ask (capture design, placement addendum
+    // 2026-08-24): on a qualifying interactive first run the ask fills the
+    // scan wait — it prints its own wait line, so the spinner stays off. A
+    // run that does not qualify (or whose signup state disallows the ask)
+    // takes the exact fast path below, byte-identical.
+    let preAsk;
+    if (interactive && !process.env.CI && !process.env.AI_SPEND_NO_PROMPT) {
+        try {
+            const signup = await import("./signup.js");
+            if (signup.qualifiesForPreReceiptSignupAsk(argv)) {
+                preAsk = await signup.openPreReceiptSignupAskInTerminal();
+            }
+        }
+        catch {
+            // The ask must never break the receipt path.
+        }
+    }
+    // Show a spinner only for the work-heavy instant-demo path, only on a
+    // real TTY so piped output stays clean, and never over the open ask.
     let spinner;
-    if (isInstantDemo && process.stdout.isTTY && !process.env.NO_COLOR) {
+    if (isInstantDemo && !preAsk && process.stdout.isTTY && !process.env.NO_COLOR) {
         try {
             const { default: yoctoSpinner } = await import("yocto-spinner");
             spinner = yoctoSpinner({ text: "Reading local AI evidence…" }).start();
@@ -6106,13 +6951,14 @@ export async function runMain() {
         }
     }
     let result;
+    let askOutcome = { kind: "no_ask" };
     let promptInterface;
     let guidedInterface;
     try {
-        const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
         let guidedIoShared;
-        result = await runCli(argv, {
+        const runPipeline = () => runCli(argv, {
             interactive,
+            ...(telemetry?.disclosureActive === true ? { telemetryDisclosure: true } : {}),
             ...(interactive ? {
                 prompt: async (question) => {
                     if (!promptInterface) {
@@ -6141,6 +6987,21 @@ export async function runMain() {
                 }
             } : {})
         });
+        if (preAsk) {
+            // Receipt renders only when BOTH the human's answer (bounded by the
+            // ask's own timeouts) and the pipeline have resolved; a pipeline
+            // error still waits for the bounded ask, then re-throws into the
+            // error voice below — never a hung prompt over a dead pipeline.
+            const { orchestratePreReceiptAsk } = await import("./signup.js");
+            const orchestrated = await orchestratePreReceiptAsk({ session: preAsk.session, runPipeline });
+            askOutcome = orchestrated.outcome;
+            if (!orchestrated.pipeline.ok)
+                throw orchestrated.pipeline.error;
+            result = orchestrated.pipeline.value;
+        }
+        else {
+            result = await runPipeline();
+        }
     }
     catch (error) {
         // The product's error voice, never a raw stack trace — and never an
@@ -6151,7 +7012,7 @@ export async function runMain() {
             stdout: "",
             stderr: [
                 `aibill hit an unexpected error: ${message}`,
-                "Nothing was uploaded. The command stopped without completing; run diagnostics before retrying.",
+                `${telemetry?.disclosureActive === true ? telemetryDisclosureLine : "Nothing was uploaded."} The command stopped without completing; run diagnostics before retrying.`,
                 "Try `npx aibill doctor` for diagnostics, or open an issue: https://github.com/futurastudio/ai-spend-agent/issues"
             ].join("\n")
         };
@@ -6161,6 +7022,11 @@ export async function runMain() {
         guidedInterface?.close();
         spinner?.stop();
     }
+    // A read that ended without the user pressing Enter (timeout / Ctrl-C)
+    // left the prompt line open; start the receipt on a fresh line.
+    if (preAsk?.needsFreshLine()) {
+        process.stdout.write("\n");
+    }
     if (result.stdout) {
         console.log(result.stdout);
     }
@@ -6168,6 +7034,29 @@ export async function runMain() {
         console.error(result.stderr);
     }
     process.exitCode = result.exitCode;
+    // Consent renders strictly AFTER the receipt: scope line, the literal
+    // payload JSON, a typed y, ONE POST. Nothing here can change the
+    // receipt's bytes or exit code.
+    if (preAsk && askOutcome.kind === "email") {
+        await preAsk.runConsent(askOutcome);
+    }
+    preAsk?.close();
+    // Telemetry LAST: on the first interactive run this prints the one-time
+    // notice (and stamps it); on later noticed runs it fires ONE
+    // fire-and-forget event with a hard 1500ms abort. Never blocks the
+    // receipt, never changes the exit code.
+    try {
+        await telemetry?.finish({
+            argv,
+            ok: result.exitCode === 0,
+            durationMs: Date.now() - startedAtMs,
+            interactive,
+            version: await cliVersion()
+        });
+    }
+    catch {
+        // Telemetry must never break the CLI.
+    }
 }
 if (invokedAsMain) {
     await runMain();