flipstream 0.5.0 → 0.6.0

package/dist/lib/errors.js

@@ -1,16 +1,42 @@
 import { ExitCode } from './exit-codes.js';
 import { redact } from './output/redact.js';
+import { sanitizeTerminal } from './output/sanitize.js';
+// {retryable: true} + the server-stated wait — the one shape every retryable
+// mapping site uses, so the policy pair can never half-apply.
+export function retryPolicy(retryAfterMs) {
+    return { retryable: true, retryAfterMs };
+}
 // Base class for every CLI error. Carries a stable string `code` (for agent
 // branching under --json) and the deterministic `exitCode` from ExitCode.
+// `details` is read-only from outside; withDetails is the ONLY mutator, so the
+// merge semantics below cannot be bypassed by direct assignment.
 export class CliError extends Error {
     code;
     exitCode;
+    #details = {};
     constructor(message, code, exitCode) {
         super(message);
         this.name = 'CliError';
         this.code = code;
         this.exitCode = exitCode;
     }
+    get details() {
+        return this.#details;
+    }
+    // Merge remediation details in. Scalars: later wins. `next`: CONCATENATED
+    // (deduped) — enrichment layers add commands, they never silently replace an
+    // earlier layer's guidance. An empty `next` normalizes to absent so there is
+    // exactly one representation of "no suggestion".
+    withDetails(details) {
+        const merged = { ...this.#details, ...details };
+        const next = [...(this.#details.next ?? []), ...(details.next ?? [])];
+        if (next.length > 0)
+            merged.next = [...new Set(next)];
+        else
+            delete merged.next;
+        this.#details = merged;
+        return this;
+    }
 }
 // Not authenticated (or session expired) — exit 4. Two distinct codes let an
 // agent tell "never logged in" apart from "token expired, re-login".
@@ -20,10 +46,18 @@ export class AuthRequiredError extends CliError {
         this.name = 'AuthRequiredError';
     }
     static notLoggedIn(message = 'Not logged in. Run `flipstream auth login`.') {
-        return new AuthRequiredError(message, 'not_logged_in');
+        return new AuthRequiredError(message, 'not_logged_in').withDetails({
+            hint: 'Log in once; the session then refreshes itself.',
+            next: ['flipstream auth login'],
+            retryable: false,
+        });
     }
     static sessionExpired(message = 'Session expired. Run `flipstream auth login`.') {
-        return new AuthRequiredError(message, 'session_expired');
+        return new AuthRequiredError(message, 'session_expired').withDetails({
+            hint: 'The refresh token could not renew the session — a new login is needed.',
+            next: ['flipstream auth login'],
+            retryable: false,
+        });
     }
 }
 // Authentication attempt failed (bad state/iss, token exchange rejected) — exit 5.
@@ -33,18 +67,24 @@ export class AuthFailedError extends CliError {
         this.name = 'AuthFailedError';
     }
 }
-// Network/transport failure (incl. discovery) — exit 7.
+// Network/transport failure (incl. discovery) — exit 7. Retryable BY CLASS:
+// the contract names transport as retryable, and a class default is how the
+// fourteenth mapping site can't forget it (per-site literals are how the first
+// thirteen almost did).
 export class NetworkError extends CliError {
     constructor(message, code = 'network_error') {
         super(message, code, ExitCode.NETWORK);
         this.name = 'NetworkError';
+        this.withDetails({ retryable: true });
     }
 }
 // Operation timed out (e.g. user never finished the browser flow) — exit 8.
+// Retryable by class, like NetworkError.
 export class TimeoutError extends CliError {
     constructor(message, code = 'timeout') {
         super(message, code, ExitCode.TIMEOUT);
         this.name = 'TimeoutError';
+        this.withDetails({ retryable: true });
     }
 }
 // Bad invocation — exit 2 (aligns with oclif's usage exit).
@@ -78,12 +118,17 @@ export class LoopbackError extends CliError {
 // mapper can assign a deterministic exit code. Default exit is GENERIC until E4-3.
 export class DataHttpError extends CliError {
     bodyText;
+    // Milliseconds from the response's Retry-After header, when one was sent.
+    // Carried structurally so the mapper can put it in the envelope rather than
+    // requiring consumers to parse it out of a human-readable message (E11-1).
+    retryAfterMs;
     status;
-    constructor(status, bodyText) {
+    constructor(status, bodyText, retryAfterMs) {
         super(`Data request failed: HTTP ${status}`, 'data_http_error', ExitCode.GENERIC);
         this.name = 'DataHttpError';
         this.status = status;
         this.bodyText = bodyText;
+        this.retryAfterMs = retryAfterMs;
     }
 }
 // Map any thrown value to a deterministic exit code. Known CliErrors carry their
@@ -106,13 +151,9 @@ export function toExitCode(error) {
     }
     return ExitCode.GENERIC;
 }
-// Render an error (redacted) and return its exit code. AGENT CONTRACT: under
-// --json/--ndjson the error envelope IS the machine output, so a single
-// {error:{code,message,exit}} JSON document is written to STDOUT — this is what
-// makes `<cmd> --json 2>/dev/null | jq .` work on failure paths too. Human mode
-// writes a line to STDERR. Both routes pass the message through redaction so
-// tokens never leak.
-export function renderError(error, options = {}) {
+// One classification for every consumer of a thrown value: the renderer below,
+// and the E11-6 sidecar's command-failed entry. Message comes back REDACTED.
+export function classifyError(error) {
     const exitCode = toExitCode(error);
     let code = 'error';
     if (error instanceof CliError)
@@ -122,12 +163,79 @@ export function renderError(error, options = {}) {
     else if (error instanceof Error)
         code = error.name;
     const rawMessage = error instanceof Error ? error.message : String(error);
-    const message = redact(rawMessage);
-    if (options.json) {
-        process.stdout.write(`${JSON.stringify({ error: { code, exit: exitCode, message } })}\n`);
+    return {
+        code,
+        details: error instanceof CliError ? error.details : {},
+        exitCode,
+        message: redact(rawMessage),
+    };
+}
+// Render an error (redacted) and return its exit code. AGENT CONTRACT: under
+// --json/--ndjson the error envelope IS the machine output, so a single
+// {error:{code,message,exit}} JSON document is written to STDOUT — this is what
+// makes `<cmd> --json 2>/dev/null | jq .` work on failure paths too. Human mode
+// writes a line to STDERR. Both routes pass the message through redaction so
+// tokens never leak.
+export function renderError(error, options = {}) {
+    const { code, details, exitCode, message } = classifyError(error);
+    if (options.json)
+        writeJsonEnvelope(code, exitCode, message, details);
+    else
+        writeHumanError(message, details);
+    return exitCode;
+}
+// Machine mode is left byte-faithful: JSON.stringify already escapes control
+// characters, so the document stays valid and an agent sees exactly what the
+// service said. Envelope v3 fields are ADDITIVE and absent unless set, so a
+// pre-E11 consumer sees the exact same document it always did.
+function writeJsonEnvelope(code, exitCode, message, details) {
+    const envelope = { code, exit: exitCode, message };
+    // EVERY details string is redacted here, unconditionally — not because any
+    // current producer is untrusted, but so "no upstream content reaches stdout
+    // unredacted" is an invariant of the writer rather than an audit result.
+    if (details.hint !== undefined)
+        envelope.hint = redact(details.hint);
+    if (details.next !== undefined && details.next.length > 0) {
+        envelope.next = details.next.map((command) => redact(command));
     }
-    else {
-        process.stderr.write(`Error: ${message}\n`);
+    if (details.docs !== undefined)
+        envelope.docs = redact(details.docs);
+    if (details.retryable !== undefined)
+        envelope.retryable = details.retryable;
+    // The contract promises retry_after_ms only ever appears alongside
+    // retryable: true — enforce it here so the code makes the doc's promise.
+    if (details.retryable === true && details.retryAfterMs !== undefined) {
+        envelope.retry_after_ms = details.retryAfterMs;
+    }
+    if (details.upstreamCode !== undefined)
+        envelope.upstream_code = redact(details.upstreamCode);
+    process.stdout.write(`${JSON.stringify({ error: envelope })}\n`);
+}
+// Human mode goes to a terminal, where a service-supplied message could carry
+// ANSI/OSC sequences that rewrite the display or reach terminal features.
+function writeHumanError(message, details) {
+    process.stderr.write(`Error: ${sanitizeTerminal(message)}\n`);
+    if (details.hint !== undefined) {
+        process.stderr.write(`  hint: ${sanitizeTerminal(redact(details.hint))}\n`);
+    }
+    for (const command of details.next ?? []) {
+        process.stderr.write(`  next: ${sanitizeTerminal(command)}\n`);
+    }
+    if (details.docs !== undefined)
+        process.stderr.write(`  docs: ${sanitizeTerminal(details.docs)}\n`);
+    if (details.retryable === true) {
+        const wait = details.retryAfterMs === undefined ? '' : ` after ${Math.ceil(details.retryAfterMs / 1000)}s`;
+        process.stderr.write(`  retry: yes — safe to retry${wait}\n`);
+    }
+    else if (details.retryable === false) {
+        // The anti-retry-loop notice (E11-4). The copy follows the data: when a
+        // `next:` step exists the INVOCATION is usually fine (not_logged_in — run
+        // the other command first, then re-run this one unchanged); only without
+        // one is "change the invocation" the right instruction. `retry: yes/no`
+        // is a stable stderr discriminator; the JSON envelope stays the contract.
+        const hasNext = (details.next ?? []).length > 0;
+        process.stderr.write(hasNext
+            ? '  retry: no — not retryable as-is; run the next: step above, then re-run this command\n'
+            : '  retry: no — re-running this unchanged will fail again; change the invocation, or report it\n');
     }
-    return exitCode;
 }

package/dist/lib/output/dialogs.d.ts

@@ -0,0 +1,27 @@
+import { UsageError } from '../errors.js';
+export declare class NoDefaultValueProvided extends UsageError {
+    constructor(unblockFlag?: string);
+}
+export interface DialogStreams {
+    input?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    output?: NodeJS.WritableStream & {
+        isTTY?: boolean;
+    };
+}
+export declare function readAnswer(promptText: string, streams?: DialogStreams): Promise<string>;
+export interface ConfirmOptions {
+    defaultValue?: boolean;
+    fallbackValue?: boolean;
+    streams?: DialogStreams;
+    unblockFlag?: string;
+}
+export declare function confirm(question: string, options?: ConfirmOptions): Promise<boolean>;
+export interface PromptTextOptions {
+    defaultValue?: string;
+    fallbackValue?: string;
+    streams?: DialogStreams;
+    unblockFlag?: string;
+}
+export declare function promptText(question: string, options?: PromptTextOptions): Promise<string>;

package/dist/lib/output/dialogs.js

@@ -0,0 +1,94 @@
+import { createInterface } from 'node:readline';
+import { UsageError } from '../errors.js';
+import { isNonInteractiveOrCI } from './interactivity.js';
+import { sanitizeTerminal } from './sanitize.js';
+// Prompt primitives (E11-4, #103), ported from wrangler's dialogs.ts semantics:
+//
+//   - `defaultValue`  is the HUMAN pre-selection (what Enter means at a TTY).
+//   - `fallbackValue` is what happens when NO human is present. These are
+//     different questions — conflating them is the classic bug (a destructive
+//     prompt whose Enter-default of "yes" silently becomes the CI answer).
+//   - Non-interactive runs NEVER hang and NEVER decide silently: the question
+//     AND the chosen fallback are printed to stderr.
+//   - No safe fallback -> typed NoDefaultValueProvided (exit 2) naming the flag
+//     that unblocks, thrown immediately instead of blocking forever.
+//   - EOF and Ctrl-C at an interactive prompt SETTLE: a readline that closes
+//     without an answer rejects (prompt_aborted, exit 2) — never a silent
+//     exit 0 and never an unresolved await.
+//
+// All prompt text goes to STDERR: prompts are conversation, never data.
+// This module is the ONE prompt chokepoint (headless.ts paste-back included)
+// the way redact.ts is for secrets.
+export class NoDefaultValueProvided extends UsageError {
+    constructor(unblockFlag = '--yes') {
+        super(`This prompt cannot be answered in a non-interactive context. Pass ${unblockFlag} (or run interactively).`, 'non_interactive');
+        this.name = 'NoDefaultValueProvided';
+        this.withDetails({
+            hint: `Re-run with ${unblockFlag} to accept, or run from an interactive terminal.`,
+            retryable: false,
+        });
+    }
+}
+function announceFallback(question, fallback, output) {
+    output.write(`? ${sanitizeTerminal(question)}\n`);
+    output.write(`Using fallback value in non-interactive context: ${sanitizeTerminal(fallback)}\n`);
+}
+// One readline question that ALWAYS settles: resolves with the answer, or
+// rejects when the interface closes unanswered (EOF, Ctrl-C — readline in
+// terminal mode swallows SIGINT and just closes, so `close` is the one signal
+// both paths share).
+export async function readAnswer(promptText, streams = {}) {
+    const input = streams.input ?? process.stdin;
+    const output = streams.output ?? process.stderr;
+    const rl = createInterface({ input, output });
+    try {
+        return await new Promise((resolve, reject) => {
+            let answered = false;
+            rl.on('SIGINT', () => rl.close());
+            rl.on('close', () => {
+                if (!answered) {
+                    reject(new UsageError('Prompt aborted — no answer on stdin.', 'prompt_aborted').withDetails({ retryable: false }));
+                }
+            });
+            rl.question(promptText, (answer) => {
+                answered = true;
+                resolve(answer);
+            });
+        });
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function confirm(question, options = {}) {
+    const { defaultValue = true, fallbackValue, streams = {}, unblockFlag } = options;
+    const output = streams.output ?? process.stderr;
+    if (isNonInteractiveOrCI(process.env, { stderr: streams.output ?? process.stderr, stdin: streams.input ?? process.stdin })) {
+        if (fallbackValue === undefined)
+            throw new NoDefaultValueProvided(unblockFlag);
+        announceFallback(question, fallbackValue ? 'yes' : 'no', output);
+        return fallbackValue;
+    }
+    const suffix = defaultValue ? '[Y/n]' : '[y/N]';
+    const answer = (await readAnswer(`? ${sanitizeTerminal(question)} ${suffix} `, streams)).trim().toLowerCase();
+    if (answer === '')
+        return defaultValue;
+    return answer === 'y' || answer === 'yes';
+}
+// NOTE: an interactive empty answer with no defaultValue resolves to '' — the
+// caller owns validation/re-prompting; this primitive never loops.
+export async function promptText(question, options = {}) {
+    const { defaultValue, fallbackValue, streams = {}, unblockFlag } = options;
+    const output = streams.output ?? process.stderr;
+    if (isNonInteractiveOrCI(process.env, { stderr: streams.output ?? process.stderr, stdin: streams.input ?? process.stdin })) {
+        if (fallbackValue === undefined)
+            throw new NoDefaultValueProvided(unblockFlag);
+        announceFallback(question, fallbackValue, output);
+        return fallbackValue;
+    }
+    const suffix = defaultValue === undefined ? '' : ` (${sanitizeTerminal(defaultValue)})`;
+    const answer = (await readAnswer(`? ${sanitizeTerminal(question)}${suffix} `, streams)).trim();
+    if (answer === '')
+        return defaultValue ?? '';
+    return answer;
+}

package/dist/lib/output/interactivity.d.ts

@@ -0,0 +1,11 @@
+export interface InteractivityProbe {
+    stderr?: {
+        isTTY?: boolean;
+    };
+    stdin?: {
+        isTTY?: boolean;
+    };
+}
+export declare function isInteractive(probe?: InteractivityProbe): boolean;
+export declare function isCI(env?: NodeJS.ProcessEnv): boolean;
+export declare function isNonInteractiveOrCI(env?: NodeJS.ProcessEnv, probe?: InteractivityProbe): boolean;

package/dist/lib/output/interactivity.js

@@ -0,0 +1,48 @@
+// Three-tier interactivity (E11-4, #103) — three DIFFERENT questions, ported
+// from wrangler's split, including the tier most CLIs miss:
+//
+//   isInteractive()        gates CAPABILITIES  (prompts can be answered and
+//                                               SEEN — stdin for answers,
+//                                               stderr because that is where
+//                                               prompts go in this repo)
+//   isNonInteractiveOrCI() gates DECISIONS     (ask, or fall back + announce)
+//   isCI()                 gates DISCLOSURE    (public build logs — redact
+//                                               account identifiers there, but
+//                                               NOT for a local non-interactive
+//                                               agent, which is non-interactive
+//                                               yet not public)
+//
+// A fourth tier — "an LLM is driving", detectable via am-i-vibing — is
+// DEFERRED to E11-5 (#104), which introduces that dependency; agents that
+// allocate a pty can look interactive until then. The escape hatch below
+// (FLIPSTREAM_NO_INPUT) exists for exactly that gap: any wrapper can force the
+// deterministic no-prompt path regardless of what the TTY claims.
+// stdin (can the user answer?) AND stderr (can they SEE the prompt?). stdout
+// is deliberately not consulted: piping stdout is this CLI's DESIGNED usage
+// (`query --json > out.json`), and a human at a terminal doing that can still
+// be prompted — the prompt stream is not the data stream here, which is why
+// this diverges from wrangler's stdin+stdout pair.
+export function isInteractive(probe = {}) {
+    const stdin = probe.stdin ?? process.stdin;
+    const stderr = probe.stderr ?? process.stderr;
+    return Boolean(stdin.isTTY) && Boolean(stderr.isTTY);
+}
+// CI by VALUE, not mere presence: `CI=false`/`CI=0` count as not-CI. This
+// deliberately diverges from ci-info (which treats presence as truth, `false`
+// excepted) — a stale `export CI=true` nearly deploying to the wrong account
+// is the failure class wrangler#9001 documents, and honoring an explicit
+// opt-out is the fix. Vendors that never set CI get explicit checks.
+export function isCI(env = process.env) {
+    const value = env.CI;
+    if (value !== undefined && value !== '' && value !== 'false' && value !== '0')
+        return true;
+    // CI vendors that do not set CI= at all.
+    return Boolean(env.JENKINS_URL ?? env.BUILD_ID ?? env.TEAMCITY_VERSION ?? env.bamboo_buildKey);
+}
+export function isNonInteractiveOrCI(env = process.env, probe = {}) {
+    // The explicit force-deterministic switch: never prompt, take fallbacks.
+    if (env.FLIPSTREAM_NO_INPUT !== undefined && env.FLIPSTREAM_NO_INPUT !== '' && env.FLIPSTREAM_NO_INPUT !== '0') {
+        return true;
+    }
+    return !isInteractive(probe) || isCI(env);
+}

package/dist/lib/output/redact.d.ts

@@ -1 +1,2 @@
+export declare function maskAccount(account: string): string;
 export declare function redact(value: unknown): unknown;

package/dist/lib/output/redact.js

@@ -29,6 +29,18 @@ const JWT_SHAPE = /eyJ[\w-]*\.[\w-]+\.[\w-]+/g;
 function redactString(value) {
     return value.replaceAll(SECRET_PARAMS, `$1$2=${MASK}`).replaceAll(JWT_SHAPE, MASK);
 }
+// Account mask for PUBLIC-log contexts (E11-4's CI disclosure tier):
+// 'michel@flipstream.io' -> '***@flipstream.io'; anything not email-shaped ->
+// '***'. The local part is dropped ENTIRELY — on a small team an initial plus
+// the domain identifies exactly one person, which defeats the point. This is
+// deliberately NOT part of redact(): an account name is not a secret, and the
+// human line is the only consumer — --json keeps the stable value by contract.
+export function maskAccount(account) {
+    const at = account.lastIndexOf('@');
+    if (at > 0 && at < account.length - 1)
+        return `***${account.slice(at)}`;
+    return '***';
+}
 // Return a redacted deep copy of `value` (never mutates the input). Applied to
 // every log/debug/error path so tokens never reach stdout/stderr/logs.
 export function redact(value) {

package/dist/lib/output/runlog.d.ts

@@ -0,0 +1,3 @@
+export declare function currentRunLogPath(): null | string;
+export declare function resetRunLog(): void;
+export declare function appendRunLog(line: string): void;

package/dist/lib/output/runlog.js

@@ -0,0 +1,72 @@
+import { appendFileSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// Per-run log file (E11-6, #105) under the XDG state dir. EVERY line offered is
+// written regardless of terminal verbosity — post-mortems need context and
+// order, not just the lines that happened to be shown. Contents pass through
+// the caller's redaction before they get here (trace.ts / base.ts).
+//
+// Lazy: no file is created until the first line, so commands that log nothing
+// leave nothing behind.
+const MAX_LOG_FILES = 20;
+function stateDir() {
+    const xdg = process.env.XDG_STATE_HOME?.trim();
+    const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.local', 'state');
+    return join(base, 'flipstream-cli', 'logs');
+}
+let runLogPath = null;
+let runLogBroken = false;
+// The current run's log path — null until something has been written.
+export function currentRunLogPath() {
+    return runLogPath;
+}
+// Test seam + long-lived-process hygiene.
+export function resetRunLog() {
+    runLogPath = null;
+    runLogBroken = false;
+}
+function timestampName() {
+    const iso = new Date().toISOString().replaceAll(':', '-').replace(/\..+$/, '');
+    return `${iso}-${process.pid}.log`;
+}
+// ISO-prefixed names sort chronologically, so pruning is a name sort — no
+// stat() calls needed.
+function prune(dir) {
+    try {
+        const logs = readdirSync(dir)
+            .filter((name) => name.endsWith('.log'))
+            .sort();
+        // +1: prune runs BEFORE the new file is created, so keep MAX-1 old ones.
+        for (const name of logs.slice(0, Math.max(0, logs.length + 1 - MAX_LOG_FILES))) {
+            rmSync(join(dir, name), { force: true });
+        }
+    }
+    catch {
+        // Pruning is hygiene, never worth failing a command over.
+    }
+}
+export function appendRunLog(line) {
+    if (runLogBroken)
+        return;
+    try {
+        if (runLogPath === null) {
+            const dir = stateDir();
+            // 0700/0600: these files hold argv and error messages that echo request
+            // payloads — not for other local users (the Python reference used 0600).
+            mkdirSync(dir, { mode: 0o700, recursive: true });
+            prune(dir);
+            const candidate = join(dir, timestampName());
+            appendFileSync(candidate, `${new Date().toISOString()} ${line}\n`, { mode: 0o600 });
+            runLogPath = candidate;
+            return;
+        }
+        appendFileSync(runLogPath, `${new Date().toISOString()} ${line}\n`);
+    }
+    catch {
+        // A read-only or exotic filesystem must never break the actual command.
+        // Null the path too: never point currentRunLogPath() at a file that the
+        // failed write means does not exist.
+        runLogBroken = true;
+        runLogPath = null;
+    }
+}

package/dist/lib/output/sanitize.d.ts

@@ -0,0 +1,2 @@
+export declare function sanitizeTerminal(value: string): string;
+export declare function sanitizeDeep<T>(value: T): T;

package/dist/lib/output/sanitize.js

@@ -0,0 +1,57 @@
+// Strip terminal control sequences from text the SERVER chose.
+//
+// `redact()` masks token-shaped content but leaves control bytes intact, so any
+// human-mode path that prints a service-supplied string trusts those bytes. A
+// hostile or malformed value can then rewrite what the terminal displays —
+// overwrite earlier lines, hide text, fake a prompt — or reach terminal features
+// like clipboard-setting OSC sequences.
+//
+// TWO RULES make this safe to apply broadly:
+//
+// 1. It runs on INPUT, never on rendered output. @oclif/table adds its own ANSI
+//    for borders and colour; sanitizing the finished table would strip that too.
+//    So cell VALUES are cleaned before rendering, not the rendered string.
+//
+// 2. It never touches machine output. JSON.stringify already escapes control
+//    characters, so --json is structurally safe without help — and it must stay
+//    byte-faithful to what the service sent. Redaction is the machine-mode
+//    protection; this is the human-mode one. Deliberately separate.
+// ESC- and CSI-introduced sequences: colour, cursor movement, and OSC (which can
+// carry a payload terminated by BEL or ST). Matching the introducer AND its
+// payload matters - stripping a bare ESC would leave "[31m" as visible garbage.
+// This is the well-known ansi-regex pattern, inlined rather than depended on.
+// OSC gets its own pattern because its payload is free text up to a terminator
+// (BEL, or ST as ESC-backslash / 0x9C) and can contain spaces — a window title
+// does. The generic CSI pattern below stops at the first space, which would leave
+// the tail of an OSC visible. Non-greedy, so an unterminated OSC simply does not
+// match and its ESC is removed by CONTROL instead.
+// eslint-disable-next-line no-control-regex
+const OSC = /[\u001B\u009D]\][\S\s]*?(?:\u0007|\u001B\\|\u009C)/g;
+const ANSI = 
+// eslint-disable-next-line no-control-regex
+/[\u001B\u009B][[\]()#;?]*(?:(?:(?:(?:;[\w#&./:=?@~-]+)*|[\dA-Za-z]+(?:;[\w#&./:=?@~-]*)*)?\u0007)|(?:(?:\d{1,4}(?:;\d{0,4})*)?[\dA-PR-TZcf-nqry=><~]))/g;
+// Whatever survives: C0 minus \t and \n (legitimate inside a message), DEL, and
+// C1. \r IS stripped - a carriage return overwrites the line just printed, which
+// is one of the cheaper ways to hide text. Also catches a lone ESC or CSI that
+// did not form a complete sequence above.
+// eslint-disable-next-line no-control-regex
+const CONTROL = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F]/g;
+export function sanitizeTerminal(value) {
+    return value.replaceAll(OSC, '').replaceAll(ANSI, '').replaceAll(CONTROL, '');
+}
+// Sanitize every string in a structure, preserving its shape. Used for table rows,
+// where the values are service-supplied but the keys are ours.
+export function sanitizeDeep(value) {
+    if (typeof value === 'string')
+        return sanitizeTerminal(value);
+    if (Array.isArray(value)) {
+        return value.map((item) => sanitizeDeep(item));
+    }
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [key, val] of Object.entries(value))
+            out[key] = sanitizeDeep(val);
+        return out;
+    }
+    return value;
+}

package/dist/lib/output/sidecar.d.ts

@@ -0,0 +1,30 @@
+interface SessionEntry {
+    argv: string[];
+    cli_version: string;
+    contract_version: string;
+    log_file_path: null | string;
+    type: 'session';
+    version: 1;
+}
+interface ResultEntry {
+    command: string;
+    duration_ms: number;
+    exit: 0;
+    type: 'result';
+    version: 1;
+}
+interface CommandFailedEntry {
+    command: string;
+    error_code: string;
+    exit: number;
+    log_file_path: null | string;
+    message: string;
+    retry_after_ms?: number;
+    type: 'command-failed';
+    version: 1;
+}
+export type OutputEntry = CommandFailedEntry | ResultEntry | SessionEntry;
+export declare function resetSidecar(): void;
+export declare function sidecarEnabled(): boolean;
+export declare function writeOutputEntry(entry: OutputEntry): void;
+export {};

package/dist/lib/output/sidecar.js

@@ -0,0 +1,58 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { redact } from './redact.js';
+let cachedPath;
+let warned = false;
+// Test seam (env changes between tests).
+export function resetSidecar() {
+    cachedPath = undefined;
+    warned = false;
+}
+function timestampName() {
+    const iso = new Date().toISOString().replaceAll(':', '-').replace(/\..+$/, '');
+    return `flipstream-output-${iso}-${process.pid}.ndjson`;
+}
+function resolvePath() {
+    const file = process.env.FLIPSTREAM_OUTPUT_FILE?.trim();
+    if (file)
+        return file;
+    const dir = process.env.FLIPSTREAM_OUTPUT_FILE_DIRECTORY?.trim();
+    if (dir) {
+        mkdirSync(dir, { mode: 0o700, recursive: true });
+        return join(dir, timestampName());
+    }
+    return null;
+}
+export function sidecarEnabled() {
+    try {
+        cachedPath ??= resolvePath();
+    }
+    catch {
+        cachedPath = null;
+    }
+    return cachedPath !== null;
+}
+// Append one entry. Failures are swallowed after one warning-free attempt —
+// a broken sidecar path must never break the actual command.
+export function writeOutputEntry(entry) {
+    try {
+        cachedPath ??= resolvePath();
+        if (cachedPath === null)
+            return;
+        const record = { ...redact(entry), timestamp: new Date().toISOString() };
+        // 0600: the sidecar holds argv and command outcomes — not for other local
+        // users. mode applies only at creation, which is what we want.
+        appendFileSync(cachedPath, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+    }
+    catch (error) {
+        // A truncated sidecar reads to the supervisor like a run that crashed
+        // before its result entry — so say so ONCE, then go quiet. Only the CLI
+        // knows the difference, and only at the moment it happens.
+        if (!warned) {
+            warned = true;
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`sidecar write failed (${cachedPath ?? 'unknown path'}): ${message}; disabling for this run\n`);
+        }
+        cachedPath = null;
+    }
+}