@allscale/cli 0.1.0 → 1.0.1

package/README.md

@@ -62,7 +62,8 @@ allscale whoami
 # What capabilities did this CLI session get? (chosen on the approval screen)
 allscale scope
 
-# Create a store for your business — returns its one-time API secret on stdout.
+# Create a store for your business — returns its API secret on stdout (shown
+# only once; it cannot be retrieved again, so save it now).
 # `payout send` requires a live store credential from Payout onboarding.
 allscale store create --name "My Shop"
 
@@ -101,12 +102,15 @@ allscale invoice send --to-email client@example.com \
   --line "Discovery (4h)|4|25.00" --line "Implementation (10h)|10|25.00" \
   --memo "Q2 engagement"
 
-# Mixed — explicit --amount + display-only lines. With single-field --line,
-# `--amount` is required (no way to derive); three-field display rows round
-# their quantity × rate to cents and warn if the visible total differs.
+# Explicit --amount + a display-only line. With single-field --line, `--amount`
+# is required (there is nothing to derive from). Note the ONE single-field line:
+# each such line is worth the FULL --amount, so two of them would sum to 2 x
+# --amount and print a totals-mismatch warning. Use the 3-field form above when
+# you want several rows.
 allscale invoice send --to-email client@example.com --amount 250 --wallet-id <wallet-id> \
-  --payment-type 2 --currency-label USDC --memo "January retainer" --due 2026-06-01 \
-  --line "Discovery (4h)" --line "Implementation (10h)"
+  --payment-type 2 --currency-label USDC --memo "January retainer" \
+  --due "$(node -p 'new Date(Date.now()+30*864e5).toISOString().slice(0,10)')" \
+  --line "Discovery + implementation"
 
 # First-time invoice to a new email? Add --auto-create-contact to create the
 # contact in one shot. Name defaults to the FULL email address (essentially
@@ -121,39 +125,44 @@ allscale invoice send --to-email newclient@example.com --amount 100 \
 allscale invoice send --to-email billing@acme.com --amount 100 \
   --wallet-id <wallet-id> --auto-create-contact --contact-name "Acme Inc"
 
-# Send a stablecoin from your AllScale wallet to an external EVM address
+# Send a stablecoin from your AllScale wallet to an external EVM address.
+# The transfer is confirmed in the browser, which waits for the on-chain
+# receipt; over SSH, open the printed URL on any device and paste the full
+# result JSON back.
 allscale wallet send --idempotency-key order-1042 \
   --to 0xabc... --amount 0.1 --chain base --stable-coin USDC
 
-# (`wallet send --headless` skips the browser, but it signs with the user token
-# of a legacy JWT session — a credential this build's logins never mint, so it
-# cannot succeed here. Use the browser-bridge form above.)
-
 # Drop credentials
 allscale logout
 ```
 
+> **Windows note.** The invoice examples above compute the due date with POSIX
+> command substitution. `sh`, `bash`, `zsh` and PowerShell all expand it;
+> `cmd.exe` passes the token through literally, so the CLI receives the text
+> itself and rejects it with a validation error. On `cmd.exe`, pass an explicit
+> ISO date instead.
+
 ## Commands
 
 ### Auth
 | Command | Description |
 |---|---|
-| `device-login` | **Recommended for AllScale Pay Accounts.** Opens the browser; use an existing web-app session or sign in there with **Passkey or Email**. On the Email path, enter the **Email OTP on the webpage**, not in the terminal, then approve the CLI. The backend mints a **scoped agent API key** — the credential issued by the current CLI login flows. Scopes chosen on the approval screen are **checked by the backend**. Scope controls reduce access but do not prevent credential compromise, misuse within a granted scope, configuration errors, or unauthorized actions by an otherwise authenticated caller. The key expires and does not refresh (re-run `device-login` when it does; the CLI prints the expiry). A **bare** `device-login` at a terminal first prints what it is about to do and asks to confirm; declining exits **12** (`user.cancelled`) having created nothing. The prompt is bare-invocation only — any flag (including `--yes`) skips it — and never appears for `--json`, a pipe, a sidecar, ordinary non-tty CI, or a redirected stderr. Automation that allocates a pty for all three streams *and* runs the command bare is indistinguishable from a human and is prompted; pass `--yes`. Polling stops at the pairing's expiry or **15 minutes**, whichever is earlier; the CLI prints that deadline before it starts waiting. |
+| `device-login` | **Recommended for AllScale Pay Accounts.** Opens the browser; use an existing web-app session or sign in there with **Passkey or Email**. On the Email path, enter the **Email OTP on the webpage**, not in the terminal, then approve the CLI. The backend mints a **scoped agent API key** — the credential issued by the current CLI login flows. Scopes chosen on the approval screen are **checked by the backend**. Scope controls reduce access but do not prevent credential compromise, misuse within a granted scope, configuration errors, or unauthorized actions by an otherwise authenticated caller. The key expires and does not refresh (re-run `device-login` when it does; the CLI prints the expiry). A **bare** `device-login` at a terminal first prints what it is about to do and asks to confirm; declining exits **12** (`user.cancelled`) having created nothing. The prompt is bare-invocation only — any flag (including `--yes`) skips it — and never appears for `--json`, a pipe, a sidecar, ordinary non-tty CI, or a redirected stderr. Automation that allocates a pty for all three streams *and* runs the command bare is indistinguishable from a human and is prompted; pass `--yes`. Polling stops at the pairing's expiry or **15 minutes**, whichever is earlier; the CLI prints that deadline before it starts waiting. With a sidecar configured, pairing initiation also appends a sidecar-v2 `type: "device_authorization"` event containing `verification_url`, `verification_code`, and `polling_deadline_at`, so a supervisor need not parse stderr. |
 | `otp-login` | **Terminal-only** Email-OTP path for headless / scripted shells. Works with **any account email** — external domains included, not just `@allscale.io` (the account must already exist — sign up in the web app first). Sends the code and reads it in the terminal (flag / env / stdin / interactive prompt), then mints the same **scoped agent API key** with the scopes passed via `--scopes` (required — there is deliberately no full-permission default). |
 | `otp-send` | Granular: send the email OTP only (login only, any account email). Returns the otp_id; pair with `otp-login --otp-id <id> --otp <code>` for scripted flows. |
 | `whoami` | Show the current authenticated identity. No network call. Agent-key sessions (the normal case) print the key-mode identity from the stored bundle: `credential: "agent_key"`, `business_id`, `user_type`, `scopes`, and the key expiry. |
 | `scope` | Show the capabilities granted to the current CLI session (chosen on the browser approval screen at `device-login`, or via `--scopes` on `otp-login`). Scopes are **checked by the backend** for each request. Scope controls reduce access but do not prevent credential compromise, misuse within a granted scope, configuration errors, or unauthorized actions by an otherwise authenticated caller; the key expiry is shown. No network call. |
-| `logout` | Drop cached session and store credentials for a profile. A bare logout requests a full plaintext + OS-keychain sweep and exits non-zero after file cleanup if the keychain cannot be inspected; `--insecure-storage` performs an explicit file-only cleanup and never probes keychain. |
+| `logout` | Drop cached session and store credentials for a profile. A bare logout requests a full plaintext + OS-keychain sweep and exits non-zero after file cleanup if the keychain cannot be inspected; `--insecure-storage` performs an explicit file-only cleanup and never probes keychain. JSON output keeps the legacy session-token-only `removed` boolean and adds `removal_status`: `removed` when any session or store credential was deleted, `nothing_to_remove` only when a complete sweep found none, or `skipped` when a file-only sweep deleted nothing because keychain inspection was intentionally skipped. |
 
 ### Authorization model
 
 One page, no archaeology:
 
 - **The current CLI auth flows issue a scoped agent API key.** Both `device-login` (browser approval) and `otp-login` (terminal OTP, for headless/CI) mint one. There is no cookie mode and no full-permission default — every key carries an explicit scope set.
-- **Scopes** are `<category>:<tier>` strings (e.g. `invoice:read_only`, `claim_link:all`), chosen on the browser approval screen (`device-login`) or via `--scopes` (`otp-login`). Requested scopes are clipped to your account's role at mint; the granted set is echoed back and recorded locally (`allscale scope` shows it without a network call). The backend **checks** the set on each request; an out-of-scope call is expected to fail with exit 6. Scope controls limit permitted call categories but do not verify the caller's authority, purpose, accuracy, legality, or safety.
+- **Scopes** are `<category>:<tier>` strings (e.g. `invoice:read_only`, `claim_link:all`), chosen on the browser approval screen (`device-login`) or via `--scopes` (`otp-login`). Requested scopes are clipped to your account's role at mint; the granted set is echoed back and recorded locally (`allscale scope` shows it without a network call). The backend **checks** the set on each request; an out-of-scope call is expected to fail with exit 6. Scope controls limit permitted call categories but do not verify the caller's authority, purpose, accuracy, legality, or safety. Both commands check the *values* locally first: an unrecognised `<category>:<tier>` string fails with `input.invalid` (exit 2) before anything is sent — no OTP, and no pairing session — so a script can rely on one contract for the flag whichever login it uses.
 - **Keys expire and do not refresh.** The CLI prints the expiry at login and in `scope` / `whoami`; re-run `device-login` or `otp-login` to mint a new key. Revoke keys in the AllScale web dashboard, then log in again for a fresh one — the CLI has no key-management command (see the Keys section).
-- **Some actions stay human-only by design.** Two of them are not CLI commands at all — key management lives in the dashboard (see the Keys section) and payout authorization lives in Store Settings → Payout Authorization. Headless Turnkey signing (`--headless` on either `wallet send` or `invoice pay`) is unavailable in this build at all: it needs the user token of a legacy JWT session, which neither login flow mints. The browser-bridge flows (`wallet send`, `invoice pay`) work under an agent key: the human approves in the browser — note `invoice pay` needs **two** scopes, `invoice:all` to create, report and confirm the pay intent and `wallet:read_only` to look up the payer address. Neither login flow grants `invoice:all` for you: on `device-login` the **Invoices** toggle starts at Read, so tick its write tier on the approval screen (the **Wallets** toggle that grants `wallet:read_only` *is* on by default); with `otp-login`, pass BOTH `--scopes invoice:all --scopes wallet:read_only`, because naming any scope turns every unnamed category off.
-- **Password login is not part of this CLI.** AllScale Pay Accounts are passkey-only and have no usable password; `device-login` and `otp-login` are the two ways in, and both mint a scoped agent key.
+- **Some actions stay human-only by design.** Two of them are not CLI commands at all — key management lives in the dashboard (see the Keys section) and payout authorization lives in Store Settings → Payout Authorization. The browser-bridge flows (`wallet send`, `invoice pay`) work under an agent key: the human approves in the browser — note `invoice pay` needs **two** scopes, `invoice:all` to create, report and confirm the pay intent and `wallet:read_only` to look up the payer address. Neither LOGIN flow grants `invoice:all` by default: on `device-login` the **Invoices** toggle starts at Read, so tick its write tier on the approval screen (the **Wallets** toggle that grants `wallet:read_only` *is* on by default); with `otp-login`, pass BOTH `--scopes invoice:all --scopes wallet:read_only`.
+- **Password login is not a public flow.** AllScale Pay Accounts are passkey-only and have no usable password; `device-login` and `otp-login` are the two ways in. Accounts specially provisioned with a password authenticate through an internal-only flow that mints the same scoped, expiring agent key (`--scopes` required, no full-permission default).
 
 ### Discovery
 
@@ -176,26 +185,25 @@ The CLI's user-facing surface matches the AllScale web app: what users call an *
 | `invoice get <id>` | Fetch one invoice by id. Wraps `payment`. |
 | `invoice sent` | Invoices where **you are the payer** — your business owes the money. Wraps `sender_payments` (the backend's `sender` is the payer). Invoices you issued with `invoice send` are **not** here; see `invoice received`. Same pagination defaults and the same `--status` / `--payment-type` / `--from` / `--to` filters as `invoice list`. **No `--to-email`**: an invoice's contact record belongs to the business that issued it, so your own contacts never appear on the invoices you owe — the flag is refused here with `input.invalid` rather than answering with a misleading empty page. |
 | `invoice received` | Invoices where **you are the payee** — the money is owed to your business. Wraps `recipient_payments` (the backend's `recipient` is the payee). **Includes everything you issued with `invoice send`.** Same pagination defaults and the same `--status` / `--payment-type` / `--from` / `--to` / `--to-email` filters as `invoice list`; this is the command `--to-email` fits exactly, since every row here is one you issued. |
-| `invoice send` | Issue an invoice by email. Resolves `--to-email` to a contact (auto-creates via `--auto-create-contact` if missing), renders the invoice HTML body locally, and submits `create_payment` through the authenticated session. USDT/USDC totals below 0.10 are rejected before contact or wallet lookup. Pass `--wallet-id` to pin receiving wallets (backend-resolved — works with an invoice-scope-only key), or omit it to auto-select from your wallets via the narrow `business_wallets` query (needs `wallet:read_only` on an agent key). **No browser ceremony** — the payer signs when paying; the inviter doesn't sign at issue. |
+| `invoice send` | Issue an invoice by email. Resolves `--to-email` to a contact (auto-creates via `--auto-create-contact` if missing), renders the invoice HTML body locally, and submits `create_payment` through the authenticated session. The recipient does **not** need any prior relationship with you — any valid email can be invoiced — but auto-creating its contact record needs `contact:all` on an agent key, which the approval screen leaves **OFF** by default (contact defaults to read-only); the CLI detects a key that can't create contacts and fails fast with the re-login remediation instead of relaying the backend's scope refusal. USDT/USDC totals below 0.10 are rejected before contact or wallet lookup. Pass `--wallet-id` to pin receiving wallets (backend-resolved — works with an invoice-scope-only key), or omit it to auto-select from your wallets via the narrow `business_wallets` query (needs `wallet:read_only` on an agent key). **No browser ceremony** — the payer signs when paying; the inviter doesn't sign at issue. |
 | `invoice update <id>` | Update an existing invoice. Wraps `update_payment`. |
-| `invoice pay <id>` | Pay a received invoice from your AllScale wallet. Resolves the invoice's destination + amount, moves the funds via the same signing path as `wallet send` (the transfer is confirmed in the browser at `/cli`), then reports and confirms the payment. **Needs TWO scopes** — `invoice:all` to create, report and confirm the pay intent, and `wallet:read_only` for the payer-address lookup (the narrow `business_wallets` query). Neither login flow grants `invoice:all` for you: on `device-login` the Invoices toggle starts at Read, so tick its write tier on the approval screen; on `otp-login` pass BOTH `--scopes invoice:all --scopes wallet:read_only`, because naming any scope turns every unnamed category off. |
-| `transaction list` | Paginated transactions. `--scope mine\|business\|activities`. Wraps `my_transactions` / `business_transaction_records` / `activities`. Defaults to the first 50 rows; pass `--input` (mine/business) or `--limit N` (activities) to override, or `--all` to request one unpaginated response (still capped at 32 MiB by the CLI). |
+| `invoice pay <id>` | Pay an invoice where **you are the payer**, from your AllScale wallet — list them with `invoice sent`, NOT `invoice received`. Resolves the invoice's destination + amount, moves the funds via the same signing path as `wallet send` (the transfer is confirmed in the browser at `/cli`), then reports and confirms the payment. **Needs TWO scopes** — `invoice:all` to create, report and confirm the pay intent, and `wallet:read_only` for the payer-address lookup (the narrow `business_wallets` query). Neither LOGIN flow grants `invoice:all` for you: on `device-login` the Invoices toggle starts at Read, so tick its write tier on the approval screen; on `otp-login` pass BOTH `--scopes invoice:all --scopes wallet:read_only`, because naming any scope turns every unnamed category off. |
+| `transaction list` | Paginated transactions. `--scope mine\|business\|activities`. Wraps `my_transactions` / `business_transaction_records` / `activities`. Defaults to the first 50 rows; pass `--input` (mine/business) or `--limit N` (activities) to override, or `--all` to request one unpaginated response (still capped at 32 MiB by the CLI). Filter by time with `--from` / `--to` in every scope — the same **half-open** range as `invoice list` (`--from` inclusive, `--to` exclusive, same accepted datetime spellings), applied to `created_at` under `mine`/`business` and to `transaction_time` under `activities`. Under `--scope business`, additionally filter with `--direction` (`INFLOW`/`OUTFLOW`), `--transaction-type` (`PAYMENT`, `WITHDRAWAL`, `CLAIM_LINK`, …) and `--status` (`NEW`/`SUCCESS`/`FAILED`/`CONFIRMING` — transaction statuses, not invoice statuses); these map to `business_transaction_records`' typed GraphQL arguments, each accepting the enum name (case-insensitive) or a raw integer. The other scopes reject them with the typed alternative they do have (`activities` takes list-valued `directions` / `transaction_types` / `transaction_statuses` via `--input`). |
 | `transaction get <id>` | Fetch one transaction by id. |
 | `wallet list` | Your noncustodial wallets and per-coin balances via the narrow `business_wallets` query. Works with an agent key holding `wallet:read_only`; the owner is derived from the authenticated identity. |
-| `wallet send` | Withdraw USDT/USDC from your AllScale wallet to an external EVM address. Registers a `withdraw_token` op with the broker, opens the browser at `/cli` for the passkey + Turnkey signing ceremony, returns `tx_hash` through the loopback listener. The browser is the only path this build offers: `--headless` exists but signs with the user token of a legacy JWT session, **which this build cannot create**, so it fails closed with exit 6 (`auth.permission_denied`). |
+| `wallet send` | Withdraw USDT/USDC from your AllScale wallet to an external EVM address. Registers a `withdraw_token` op with the broker, opens the browser at `/cli` for the passkey + Turnkey signing ceremony, and succeeds only after the browser confirms the on-chain receipt — the receipt-aware result comes back through the loopback listener (a mined revert exits `12`, an unconfirmable receipt exits `9`). The transfer is always confirmed in the browser; over SSH, open the printed URL on any device and paste the full result JSON back. |
 
 ### Claim links
 
 **Important:** The financial commands below are available only to eligible users in supported jurisdictions. Execution may be delayed, rejected, suspended, returned, or require additional information to comply with applicable law, sanctions, AML/CTF requirements, fraud controls, network conditions, or service-provider requirements.
 
-Sender-side reads (`get` / `list` / `preview`) need a CLI login and `claim_link:read_only` under an agent-key session. `claim-link create` needs `claim_link:all`: the CLI fixes the amount, stablecoin, chain, claim window, optional sender metadata, and caller-stable idempotency key before registering the `create_claim_link` broker op. The AllScale-hosted browser approval page shows that immutable intent as a read-only review, then performs creation, signing, and funding after the payer authorizes it; verify the exact AllScale origin before approval. It does not ask the payer to re-enter or edit the payment. Before opening the browser and again after any callback, cancellation, invalid receipt, or timeout, the CLI reconciles the complete intent through `claim_link_funding_by_idempotency_key`; the browser receipt is advisory. `status` and `claim` drive the public receiver-facing REST surface — no login; the bearer claim token IS the credential.
+Sender-side reads (`get` / `list`) need a CLI login and `claim_link:read_only` under an agent-key session. `claim-link create` needs `claim_link:all`: the CLI fixes the amount, stablecoin, chain, claim window, optional sender metadata, and caller-stable idempotency key before registering the `create_claim_link` broker op. The AllScale-hosted browser approval page shows that immutable intent as a read-only review, then performs creation, signing, and funding after the payer authorizes it; verify the exact AllScale origin before approval. It does not ask the payer to re-enter or edit the payment. Before opening the browser and again after any callback, cancellation, invalid receipt, or timeout, the CLI reconciles the complete intent through `claim_link_funding_by_idempotency_key`; the browser receipt is advisory. `status` and `claim` drive the public receiver-facing REST surface — no login; the bearer claim token IS the credential.
 
 | Command | Description |
 |---|---|
 | `claim-link create` | Create and fund a fixed-intent Claim Link through an AllScale-hosted browser approval flow. Verify the exact AllScale origin before approval. Requires `--idempotency-key` (1–128 trimmed characters), `--amount` (exact decimal string, 0.1–10000, at most 6 effective decimal places), `--chain`, and agent-key scope `claim_link:all`; `--stable-coin` defaults to USDT and `--expires` to 14d. `--no-browser` skips only local auto-open: the CLI still prints the `/cli` URL and waits for callback/paste. A recovered key must match every immutable field; a pre-browser mismatch exits 2 as `claim_link.intent_conflict` without opening the browser. Success is emitted only when the authoritative lookup returns the same intent, a validated AllScale claim URL, and either `LINK_SENT`, `CLAIMING`, or `CLAIMED`, or returns `EXPIRED` or `CANCELLED` with a validated non-empty funding transaction hash. A signed/broadcast/unknown, still-pending, failed-reconciliation, post-browser intent race, or `EXPIRED`/`CANCELLED` result without that funding proof exits 9 as `claim_link.funding_ambiguous`; follow its retry metadata and never substitute a new key. Only an explicit cancellation before creation plus a successful authoritative miss exits 12 as `claim_link.browser_cancelled`. |
 | `claim-link get <id>` | Fetch one of your own Claim Links by id. Wraps `claim_link`; a non-owned id is indistinguishable from an unknown one. Agent-key scope: `claim_link:read_only`. |
 | `claim-link list` | Your own Claim Links, newest first. Wraps `my_claim_links`. Defaults to the first 50 rows; `--input` paginates and `--all` requests one unpaginated response (still capped at 32 MiB by the CLI); `--status` filters. Agent-key scope: `claim_link:read_only`. |
-| `claim-link preview` | Fee breakdown for a would-be link without creating it. Wraps `claim_link_fee_preview`; mirrors create's asset validation. Agent-key scope: `claim_link:read_only`. |
 | `claim-link status` | Public receiver-facing status snapshot for a bearer claim token/URL. Canonical URLs are parsed locally; a same-origin `/s/` URL is resolved through one credential-free 302. No login — the token is the credential. |
 | `claim-link claim` | Claim a link from a raw token, canonical URL, or same-origin `/s/` short URL: Path A without AllScale account sign-in with `--to <0x address>` (no login), or `--to-wallet` into the authenticated business's AllScale wallet (cookie session). This does not make the transaction anonymous: network, request, compliance, and public blockchain data may still be processed or observable. Only the on-chain-proven `claimed` outcome exits 0; unavailable/expired links exit 12, while pending/unproven payouts exit 9 and must be reconciled before another claim. |
 
@@ -203,7 +211,7 @@ Sender-side reads (`get` / `list` / `preview`) need a CLI login and `claim_link:
 
 | Command | Description |
 |---|---|
-| `store create` | Create a store for the logged-in business (no store key, no browser ceremony). Wraps `create_store`. Defaults `--business-id` from the session token — the JWT `user_id` for cookie sessions, or the owner business id stored at login for agent-key sessions (re-run `device-login` if an older agent-key login has none stored); `--live` creates a live store (default is sandbox). Returns the API key and **one-time** API secret on stdout; capture it securely. This command does not enroll the store for Payout. Business must have checkout enabled; only one sandbox store is allowed per business. |
+| `store create` | Create a store for the logged-in business (no store key, no browser ceremony). Wraps `create_store`. Defaults `--business-id` from the session token — the JWT `user_id` for cookie sessions, or the owner business id stored at login for agent-key sessions (re-run `device-login` if an older agent-key login has none stored); `--live` creates a live store (default is sandbox). Returns the API key and an API secret that is **shown only once** on stdout (it cannot be retrieved later — capture it now; the credential itself stays valid). This command does not enroll the store for Payout. Business must have checkout enabled; only one sandbox store is allowed per business. |
 
 ### Payout
 
@@ -236,6 +244,8 @@ The CLI mints a key for its own session when you log in (`device-login` / `otp-l
 - **Default backend**: `https://app.allscale.io` (production). Published builds are configured for their bound AllScale environment. The current implementation accepts a credential-bearing api-base only for exact AllScale origins (plus an explicit loopback origin for development), and validates session credentials against the origin recorded at login. `payout send` uses a separate approved partner API origin selected with `--payout-api-base` / `ALLSCALE_PAYOUT_API_BASE`. Embedded URL userinfo (`user:password@host`) is rejected. Browser targets must be `https://`, or `http://` to loopback only. The current implementation is designed not to follow redirects when a request carries credentials; callers should still verify the destination origin and TLS before approving or transmitting sensitive data.
 - **Sidecar event log** (opt-in, off by default): set **`ALLSCALE_OUTPUT_FILE_PATH=/path/to/run.ndjson`** to append a machine-readable NDJSON event stream for the run, or **`ALLSCALE_OUTPUT_FILE_DIRECTORY=/path/to/dir`** to give every run its own randomly named file in that directory. Events may cover the command, argv fields designed to redact specified authentication secrets, request URLs, responses, refreshes, bridge steps, and errors — intended for agent supervisors and orchestrators that need structured progress without parsing stdout. Redaction is not a guarantee that the log contains no sensitive information.
 
+  `device-login` writes its short-lived pairing code and URL as the sidecar-v2 `device_authorization` event before polling. Treat that event as sensitive and do not publish it to an untrusted log sink.
+
   **Important:** Sidecar logs are designed to redact specified authentication secrets, but may still contain personal, business-confidential, and transaction data. Treat them as sensitive. Do not place them in shared directories or transmit them to third-party agents or support channels without review. Configure appropriate access controls, retention, and secure deletion.
 
   On POSIX systems, the current implementation attempts to create files with mode 0600. A directory selected through `ALLSCALE_OUTPUT_FILE_DIRECTORY` is intended to be created owner-only; if it already grants group/other access, the CLI is designed to refuse writing rather than change a potentially shared directory such as `/tmp`. For an explicit `_PATH`, the current implementation does not change permissions on an existing parent directory, so choose a private parent yourself; it is designed to refuse an existing output file unless it is owner-only (rotate/remove an older loose file first). Sidecar output is currently disabled on Windows because Node's mode APIs cannot reliably enforce or verify owner-only NTFS ACLs. **It is still a file on disk that describes your session**: prefer `_DIRECTORY`, which generates an unpredictable filename, over a fixed `_PATH` on a shared machine. A `_PATH` that is a symlink is designed to be refused rather than written through. The file is append-only with no rotation and is currently capped at 64 MB, after which the sidecar is designed to disable itself for the run with a warning on stderr.
@@ -287,7 +297,7 @@ $ allscale whoami
 {
   "error": {
     "code": "auth.no_token",
-    "message": "No tokens stored for profile 'default'. Run `allscale device-login --profile <profile>` with the same profile (recommended), use `allscale otp-login --profile <profile> --email <you@example.com> --scopes <scope> --otp-stdin` for headless automation."
+    "message": "No tokens stored for profile 'default'. Run `allscale device-login --profile default` (recommended), or use `allscale otp-login --profile default --email <you@example.com> --scopes <scope> --otp-stdin` for headless automation."
   }
 }
 # exit code: 4
@@ -303,30 +313,92 @@ exactly one of them, and a mapping is never renumbered once shipped.
 | `0`  | success | — |
 | `1`  | generic / unexpected | `internal` |
 | `2`  | caller-actionable input or local limit — fix the invocation and re-run | `input.invalid`, `storage.unavailable`, `transport.response_too_large`, `auth.unknown_profile`, `claim_link.intent_conflict`, `signing.key_unavailable` |
-| `3`  | network / transport failure (**see the retry warning below**) | `transport.network`, `transport.timeout`, `auth.credential_changed`, `wallet.bridge_timeout` |
+| `3`  | network / transport failure (**see the retry warning below**) | `transport.network`, `transport.timeout`, `auth.credential_changed`, `wallet.bridge_timeout`, `wallet.bridge_op_expired` |
 | `4`  | not authenticated — run `allscale device-login` | `auth.no_token` |
 | `5`  | credential expired — re-authenticate | `auth.token_expired` |
-| `6`  | not fixable by this invocation: permission denied, or a capability gap | `auth.permission_denied`, `wallet.requires_browser_auth`, `wallet.headless_not_supported`, `wallet.headless_setup_required`, `wallet.headless_config_missing` |
+| `6`  | not fixable by this invocation: permission denied, or a capability gap | `auth.permission_denied`, `wallet.requires_browser_auth` |
 | `7`  | not found — the object you named does not exist | `not_found` |
 | `8`  | rate limited | `rate_limited` |
-| `9`  | backend internal, or an **ambiguous** mutation result | `backend.internal`, `claim.payout_ambiguous`, `claim_link.funding_ambiguous`, `wallet.bridge_invalid_response`, `wallet.headless_sign_failed` |
+| `9`  | backend internal, or an **ambiguous** mutation or transaction result | `backend.internal`, `claim.payout_ambiguous`, `claim_link.funding_ambiguous`, `wallet.bridge_invalid_response`, `wallet.transaction_status_unknown` |
 | `10` | escape hatch disabled — export `ALLSCALE_ALLOW_RAW=1` | `raw.disabled` |
 | `11` | this build's request signature was rejected — **upgrade the CLI** (re-login does not help) | `auth.signature_rejected` |
-| `12` | did not complete; nothing was created | `claim.not_claimable`, `claim.expired`, `claim_link.browser_cancelled`, `user.cancelled` |
+| `12` | did not complete; nothing was created, or an on-chain attempt reverted without transferring | `claim.not_claimable`, `claim.expired`, `claim_link.browser_cancelled`, `user.cancelled`, `wallet.transaction_reverted` |
 
 > **An exit code is NOT a retry-safety signal. Branch on the `code` string when
 > you need to decide whether re-running is safe.**
 >
 > Exit `3` is the trap: `transport.network` never reached the server, but
-> `wallet.bridge_timeout` is **post-signing** — the browser may already have
-> signed and the backend may already have broadcast. Retrying blindly on exit
-> `3` can **double-pay**. Exit `9` mixes a plain 5xx with the `*_ambiguous`
-> codes and `wallet.headless_sign_failed`, all of which must be reconciled
-> against the original idempotency key rather than retried.
-
-Note that exit `6` and exit `9` each cover five distinct codes, so a branch that
-must tell them apart reads `error.code`. **Credential precedence** below states
-the same caveat for exit `2`.
+> `wallet.bridge_timeout` and `wallet.bridge_op_expired` are **post-signing** —
+> the browser may already have signed and the backend may already have
+> broadcast. Retrying blindly on exit `3` can **double-pay**. Exit `9` mixes a
+> plain 5xx with the `*_ambiguous` codes **and `wallet.transaction_status_unknown`**
+> (a broadcast whose receipt never confirmed — funds may already have moved),
+> all of which must be reconciled against the original idempotency key rather
+> than retried. Exit `12` now also carries a post-signing code:
+> `wallet.transaction_reverted` means the transaction was mined and reverted —
+> nothing transferred, but gas was spent — so treat any retry as a new
+> transfer decision.
+
+> **`wallet.bridge_timeout` vs `wallet.bridge_op_expired`.** Both mean "no
+> confirmation came back", but they need different follow-ups:
+>
+> - `wallet.bridge_timeout` — a deadline **the CLI itself** reached, which is not
+>   proof the link died. Which one it was decides what helps, and the message says
+>   so: your own `--bridge-timeout` running out while the link was still valid (a
+>   longer one genuinely helps next run); the link's own lifetime running out (a
+>   longer one cannot help, and this is the ONLY case the error message names — it
+>   tells you the link is expired or about to be, and that a longer wait is useless;
+>   the remedy itself comes later in the message, after the check-your-wallet
+>   warning); that same lifetime measured
+>   against your machine's clock, when the response carried no server timestamp to
+>   check it against (same remedy, but approximate — a fast local clock makes the
+>   wait short, a slow one makes it long); the fallback used when the server gave
+>   no usable expiry at all; or a clamp at Node's ~24.8-day timer limit.
+>   Apart from the lifetime case, these share one message, so don't try to tell
+>   them apart by parsing it — when the CLI shortens or ignores your value it says
+>   which constraint bound the wait in a `Note:` line on stderr as it starts.
+> - `wallet.bridge_op_expired` — **the server** reported the operation behind the
+>   link as expired, so the link is definitively dead. **Raising
+>   `--bridge-timeout` cannot help** — it is capped at the link's remaining life
+>   precisely because the link cannot outlive its operation. A fresh link is the
+>   remedy, but check the wallet/transfer first: this error means the browser may
+>   already have signed, so the message puts that warning before the retry advice.
+>
+> The link's remaining life is normally measured against the **server's** clock,
+> not your machine's — the CLI reads the server's own timestamp from the same
+> response — so a wrong local clock cannot shorten your wait or turn a live link
+> into a reported expiry. The CLI's own deadline is set slightly early on purpose,
+> which is why reaching it reports a timeout — saying the link "has expired or is
+> about to" — rather than asserting the link is gone; only the server does that.
+>
+> One exception, and the CLI tells you when you are in it: if something between you
+> and the server strips the timestamp (some proxies do), the CLI has to fall back to
+> your machine's clock, and says so in the note it prints. That reading is
+> approximate in both directions — a fast clock makes the wait shorter than the
+> link's real life, a slow one can make it longer — so it is treated as a bound,
+> never as a fact, and it is additionally capped at 15 minutes so a badly wrong
+> clock cannot buy an open-ended wait. If your waits look wrong, check the clock
+> (`sntp`/`timedatectl`) before anything else.
+>
+> In both cases check the wallet/invoice first: the browser may have signed just
+> before the deadline.
+
+Exit `7` covers both a REST `404` and a GraphQL response whose backend code
+means "no such object" — the two paths are deliberately aligned, so
+`allscale transaction get <unknown-id>` and a login for an unregistered
+account both exit `7`.
+
+One documented asymmetry, because "not found" does not always describe an
+object **you** named: on the login path, "this email has no AllScale account"
+is exit `7`, but a data query failing because the signed-in account has no
+business is exit `2` — there is no id you could supply to fix the second, so
+sending you hunting for one would be wrong. Two further backend "not found"
+conditions are likewise **not** exit `7` on the GraphQL path: an unknown agent
+key and an un-provisioned Turnkey wallet sub-org both fall into the generic
+exit `2` bucket there. (A *rejected* credential is a different thing and does
+exit `5`, but that comes from a real `401`, not from translating a backend
+"not found" code — so do not branch on exit 5 for these conditions on a
+GraphQL call.)
 
 **Under `--json`, stderr is parseable too — for `payout send` and
 `device-login`.** On those, human progress prose is suppressed entirely and
@@ -416,9 +488,9 @@ Highest priority first:
 2. `--profile <name>` flag → keychain entry for that profile. A name with no
    entry in `~/.allscale/config.toml` errors with `auth.unknown_profile`
    (exit 2) when no credential is found for it and at least one profile is
-   saved, listing the saved profiles — a typo'd profile is an input error,
-   not a login prompt. (An empty registry is a fresh machine: that stays
-   `auth.no_token`.)
+   saved. The error names only the requested profile; saved profile names are
+   not disclosed. A typo'd profile is an input error, not a login prompt. (An
+   empty registry is a fresh machine: that stays `auth.no_token`.)
 3. `ALLSCALE_PROFILE` env var → keychain entry (same `auth.unknown_profile`
    rule as the flag).
 4. Default profile from `~/.allscale/config.toml`
@@ -437,7 +509,7 @@ discriminator, not the exit number.
 - `device-login` (device-pairing OAuth) / `otp-login` (terminal OTP for headless shells), and `wallet send` (Turnkey-direct EVM withdraw through the `/cli` bridge).
 - Current CLI login flows issue scoped agent-key sessions: `device-login` and `otp-login` both mint an agent API key checked against its granted scopes; `scope` reports the granted set + key expiry.
 - Agent-key sessions store the owner `business_id` at login, so `--business-id` auto-fills (no JWT needed) and `whoami` prints a key-mode identity instead of erroring.
-- Store creation returns its one-time API secret through the structured stdout result.
+- Store creation returns its API secret (shown once, not retrievable later) through the structured stdout result.
 
 ## Security
 

package/bin/dev.js

@@ -7,5 +7,15 @@ require("ts-node/register");
 const oclif = require("@oclif/core");
 const { runOclif } = require("./run-oclif");
 
+// The audit-lifecycle module from src/, resolvable because ts-node is registered
+// above. Deliberately NOT dist/: a dev run must audit through the code it is
+// actually executing, or a stale build would be doing the writing.
+let audit;
+try {
+  audit = require("../src/lib/output/audit-lifecycle");
+} catch {
+  audit = undefined;
+}
+
 oclif.settings.debug = true;
-void runOclif(oclif, { dir: __dirname });
+void runOclif(oclif, { dir: __dirname, audit });

package/bin/run-oclif.js

@@ -15,41 +15,230 @@ function isUnknownCommandError(oclif, error) {
   );
 }
 
-function emitUnknownCommandError() {
-  // Match `serializeErrorEnvelope`'s mode-dependent rendering:
-  // compact for a machine reading stderr as one JSON object per line, indented
-  // for a human. This runs before oclif resolves a command, so `jsonEnabled()`
-  // does not exist yet — read the same two signals it would from argv/env,
-  // resolved exactly as `AllscaleHelp.jsonModeRequested` does (`help.ts`), the
-  // other place that has to answer this without a Command. Keeping the two
-  // answers identical is the point: a caller must not get compact output from
-  // one path and indented from the other for the same command line.
+const UNKNOWN_COMMAND_MESSAGE =
+  "Unknown command. Run `allscale --help` to list available commands.";
+
+// NOTE: this file ships VERBATIM in the npm tarball (`files: ["bin", …]`),
+// unlike `src/`, which reaches users only as minified `dist/`. Its comments are
+// therefore public artifact and must stay free of internal references — issue
+// numbers, review shorthand, `docs/*.md` paths, design-doc sections. The
+// publish gate enforces it (`scripts/public-content-policy.json`, tarball
+// scope); explain the WHY here and leave the provenance to the commit history.
+
+/**
+ * The two OPT-IN machine signals: `--json` (honouring the `--` separator) and
+ * `ALLSCALE_CONTENT_TYPE=json`.
+ *
+ * Extracted because TWO callers below need it and they are deliberately
+ * DIFFERENT predicates — collapsing them would be a bug, duplicating the parsing
+ * would be the drift this PR keeps closing:
+ *
+ *   - `machine` in `emitUnknownCommandError` — chooses the envelope's FORM
+ *     (compact vs indented). Only the declared signals belong
+ *     there: a caller who merely piped stdout did not ask for compact JSON.
+ *   - `isMachineCallerLauncher` — decides WHETHER a human-facing warning is
+ *     emitted at all, so it must also honour the non-opt-in signals (a
+ *     configured sidecar, non-TTY streams) exactly as `isMachineCaller` does.
+ *
+ * The `ALLSCALE_` prefix is hard-coded, and cannot not be: `help.ts` resolves the
+ * same vars through `config.scopedEnvVar("CONTENT_TYPE")`, which derives the
+ * prefix from the bin name, but this file runs BEFORE oclif loads and has no
+ * config to ask. It matches today (`oclif.bin` is `allscale`), and
+ * `tests/tsup-entries.test.ts` pins that bin name with a message pointing here,
+ * so a rename turns a test red instead of silently desyncing this file.
+ */
+function declaredMachineOutput() {
   const raw = process.argv.slice(2);
-  // After `--` everything is a passthrough operand, so a literal `--json`
-  // there is data, not a flag.
+  // After `--` everything is a passthrough operand, so a literal `--json` there
+  // is data, not a flag.
   const passThrough = raw.indexOf("--");
   const json = raw.indexOf("--json");
-  // Case-insensitive, matching oclif's own `CONTENT_TYPE` check and help.ts:
-  // a caller who exported `CONTENT_TYPE=JSON` gets machine output from every
-  // other path, and must not get an indented document from this one. The
-  // `ALLSCALE_` prefix is hard-coded because this file is plain JS and cannot
-  // import the TS helper or reach `config.scopedEnvVar`; it is safe because
-  // `oclif.bin` is pinned to "allscale" in package.json.
-  const machine =
-    (json !== -1 && (passThrough === -1 || json < passThrough)) ||
-    process.env.ALLSCALE_CONTENT_TYPE?.toLowerCase() === "json";
+  if (json !== -1 && (passThrough === -1 || json < passThrough)) return true;
+  // Case-insensitive, matching oclif's own CONTENT_TYPE check and help.ts.
+  return (process.env.ALLSCALE_CONTENT_TYPE ?? "").toLowerCase() === "json";
+}
+
+/**
+ * Is this caller a machine? A plain-CommonJS mirror of `isMachineCaller`
+ * (`src/lib/output/machine-mode.ts`), which this file cannot import: it runs
+ * before oclif loads, from a `.js` launcher with no TS pipeline.
+ *
+ * ALL THREE of that helper's signals, not just the TTY one. An earlier version
+ * checked only `interactive` while its comment claimed parity — and the gap was
+ * trivially reachable: an engineer at a real terminal with
+ * `ALLSCALE_OUTPUT_FILE_PATH` set is a MACHINE by `isMachineCaller`
+ * (`sidecarConfigured()` is OR'd ahead of `interactive`), yet the TTY-only gate
+ * called them human and wrote to their stderr — and that population is the one
+ * most likely to be exercising this path.
+ *
+ * If `isMachineCaller` gains a fourth signal, this must gain it too;
+ * `tests/launcher-unknown-command.test.ts` pins each one.
+ */
+function isMachineCallerLauncher() {
+  if (declaredMachineOutput()) return true;
+  // Truthiness, matching `sidecarConfigured()` — an empty value means no sidecar
+  // to both, so gate and opener cannot drift.
+  if (
+    process.env.ALLSCALE_OUTPUT_FILE_PATH ||
+    process.env.ALLSCALE_OUTPUT_FILE_DIRECTORY
+  ) {
+    return true;
+  }
+  const interactive =
+    process.stdin.isTTY === true && process.stdout.isTTY === true;
+  return !interactive;
+}
+
+/**
+ * A thrown value's CLASS as a bounded, identifier-shaped token — never its
+ * message.
+ *
+ * Three guards, each closing a hole the first version left open while its comment
+ * claimed otherwise:
+ *
+ *  - The read is WRAPPED. `e.name` is a property access, and a hostile or
+ *    instrumented getter throws — inside the `catch (e)` that calls this, where
+ *    nothing further would catch it, so the process would die on Node's default
+ *    handler with a raw stack and exit 1 instead of the `{error}` envelope and
+ *    exit 2. That is the failure mode this file already guards against twice.
+ *  - The value is SHAPE-CHECKED, not merely type-checked. `typeof === "string"`
+ *    bounds nothing: a thrown plain object, or a wrapped fs/Abort error, can carry
+ *    a `.name` holding a path or other caller-influenced text — which would
+ *    reopen on `.name` the very arbitrary-text leak that moving off `.message`
+ *    was meant to close.
+ *  - It is LENGTH-BOUNDED, so a pathological `name` cannot flood stderr.
+ *
+ * Anything failing those becomes the literal "Error", which loses nothing a
+ * reader needs: the actionable part is "the audit write failed", not the class.
+ */
+function errorClass(e) {
+  try {
+    const name = e && typeof e === "object" ? e.name : undefined;
+    if (typeof name === "string" && /^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(name)) {
+      return name;
+    }
+  } catch {
+    // A throwing getter is precisely why this is wrapped.
+  }
+  return "Error";
+}
+
+function warnAuditUnavailable(reason) {
+  // The gate call is INSIDE the try, for the same reason the `typeof` read below
+  // it is: it touches `process.argv`, two env vars, and two `.isTTY` properties,
+  // any of which could be an instrumented getter that throws. Called outside, a
+  // throw here would escape `emitUnknownCommandError` AND `runOclif`'s catch —
+  // and this function is invoked from that catch, so the second call would throw
+  // again with nothing left to catch it. That turns the FAIL-SOFT invariant this
+  // whole path is built on into the exact crash it promises to prevent.
+  //
+  // On a throw we treat the caller as a MACHINE (stay silent). Silence is the
+  // safe default: a spurious warning would corrupt the single-JSON-document
+  // contract for a consumer that may well be one, whereas a missing warning
+  // costs a human one diagnostic line on an already-broken build.
+  try {
+    if (isMachineCallerLauncher()) return;
+  } catch {
+    return;
+  }
+  try {
+    process.stderr.write(
+      `[allscale] audit lifecycle unavailable (${reason}); the refusal was ` +
+        "reported but no audit events were written.\n",
+    );
+  } catch {
+    // Even stderr can fail in pathological cases; swallow.
+  }
+}
+
+/**
+ * A refusal here must write the same sidecar audit lifecycle every other refusal
+ * writes (`session-start` + `error` + `command-end ok:false`), or a supervisor
+ * consuming the stream cannot tell `allscale bogus` from a CLI that never
+ * started — the defect this module exists to close, at the one refusal shape
+ * that never reaches the help class.
+ *
+ * `audit` is INJECTED by the entrypoint rather than required here because this
+ * file is shared by two entries that disagree about where the compiled code
+ * lives: `bin/run.js` runs `dist/`, `bin/dev.js` runs `src/` through ts-node.
+ * Guessing (try dist, fall back to src) would silently audit a dev run through
+ * a stale `dist/` build, so each entry passes the form it is actually executing.
+ *
+ * FAIL-SOFT BY DESIGN: a missing or throwing audit module must never turn a
+ * clean refusal into a crash. The `{error}` envelope and exit code are the
+ * contract; the audit stream is an additional channel, and losing it is strictly
+ * better than losing the refusal itself.
+ */
+function emitUnknownCommandError(audit) {
+  // Match `serializeErrorEnvelope`'s mode-dependent rendering: compact for a
+  // machine reading stderr as one JSON object per line, indented for a human
+  // Only the DECLARED signals decide the FORM — a piped caller
+  // did not ask for compact JSON — which is why this uses
+  // `declaredMachineOutput()` and not the wider `isMachineCallerLauncher()` that
+  // gates the warning.
+  const machine = declaredMachineOutput();
   process.stderr.write(
     `${JSON.stringify(
-      {
-        error: {
-          code: "input.invalid",
-          message: "Unknown command. Run `allscale --help` to list available commands.",
-        },
-      },
+      { error: { code: "input.invalid", message: UNKNOWN_COMMAND_MESSAGE } },
       null,
       machine ? undefined : 2,
     )}\n`,
   );
+  // FAIL-SOFT, BUT NOT SILENT — and the ABSENCE of the module is the case that
+  // actually matters, which is why it is tested for rather than caught.
+  //
+  // The entrypoint requires the audit module inside its own try/catch and passes
+  // `undefined` when that fails, so `audit?.auditRefusal?.(...)` would
+  // short-circuit and throw NOTHING: a catch block alone reports a broken
+  // `dist/` exactly never. That is the degraded state worth announcing — a
+  // shipped build with a stale or partial `dist/` silently reverting to "correct
+  // envelope, empty audit file", giving the supervisor no signal, which is the
+  // same defect returning one layer up. (Verified by deleting the
+  // built module: an earlier version of this code warned on zero of those runs.)
+  //
+  // `sidecar.ts` writes a one-line `[allscale] …` warning for every open/write
+  // failure it fails-soft on; a missing or unusable module is the same class of
+  // event, so it gets the same treatment and the same prefix.
+  // INSIDE the try, not above it. `typeof audit?.auditRefusal` reads a property,
+  // and a property read can throw — a getter on the module object would do it.
+  // Evaluated one line higher (as it was), that throw escaped
+  // emitUnknownCommandError AND runOclif's catch, so the process died on Node's
+  // default handler: a raw stack after the envelope and exit 1 instead of 2.
+  // Strictly worse than the silent stream this guard replaced, from the one line
+  // the fail-soft design forgot to cover. Not reachable through the plain data
+  // property `require()` yields today — which is exactly why it belongs inside
+  // the try rather than relying on that staying true.
+  try {
+    if (typeof audit?.auditRefusal === "function") {
+      // No command id: oclif could not resolve one, which is the whole reason we
+      // are here. rawArgv defaults to process.argv.slice(2) and is redacted
+      // inside the helper, so no secret reaches the file even though this call
+      // site is plain JS with no access to the redactor.
+      audit.auditRefusal({
+        code: "input.invalid",
+        message: UNKNOWN_COMMAND_MESSAGE,
+        exitCode: 2,
+      });
+    } else {
+      warnAuditUnavailable("the audit module did not load");
+    }
+  } catch (e) {
+    // A throw FROM the audit write (an unwritable sidecar path, say) is the same
+    // degradation from the caller's point of view, so it is reported the same
+    // way. It must never replace the refusal with a stack.
+    //
+    // SHAPE, NOT TEXT. Every `[allscale]` warning in sidecar.ts goes
+    // through `sanitizeDiagnosticString`, because free text can carry a
+    // credential-shaped value that key-name masking cannot reach — and the text
+    // available here is a filesystem error built from the caller-supplied
+    // ALLSCALE_OUTPUT_FILE_PATH. This launcher cannot import that scrubber (it
+    // runs before oclif loads — the same reason `auditRefusal` redacts argv
+    // internally), so the proportionate fix is not to reach for the scrubber but
+    // to stop passing arbitrary text through: report the error's CLASS only.
+    // Unreachable today, since initSidecar and writeSidecar both catch their own
+    // failures — which is precisely why it must not depend on that staying true.
+    warnAuditUnavailable(`the audit write threw ${errorClass(e)}`);
+  }
   process.exitCode = 2;
 }
 
@@ -59,7 +248,7 @@ async function runOclif(oclif, options = {}) {
     await oclif.flush();
   } catch (error) {
     if (isUnknownCommandError(oclif, error)) {
-      emitUnknownCommandError();
+      emitUnknownCommandError(options.audit);
       return;
     }
     await oclif.Errors.handle(error);

package/bin/run.js

@@ -3,4 +3,22 @@
 const oclif = require("@oclif/core");
 const { runOclif } = require("./run-oclif");
 
-void runOclif(oclif, { dir: __dirname });
+// The audit-lifecycle module, in the form THIS entry executes (compiled dist/).
+// Injected rather than resolved inside run-oclif.js, which is shared with the
+// ts-node dev entry — see the comment on emitUnknownCommandError. Wrapped
+// because an unknown-command refusal must still work if dist/ is incomplete.
+//
+// This path only exists because `src/lib/output/audit-lifecycle.ts` is a declared
+// tsup entry; tsup emits only declared entries, so without it the module lives
+// inside other bundles and is unreachable by path. With `splitting: false` this
+// bundle carries its own copy of the sidecar module state, which is correct here:
+// an unknown command never constructs a Command, so nothing else has opened the
+// stream, and this copy opens, writes, and closes it alone.
+let audit;
+try {
+  audit = require("../dist/lib/output/audit-lifecycle");
+} catch {
+  audit = undefined;
+}
+
+void runOclif(oclif, { dir: __dirname, audit });