feat(usage): default-on telemetry, and the emitters it was missing

Three separate defects, all of which had to be fixed for a single row to
reach production.

1. THE CLIENT FLAG COULD NEVER BE SET

UsageOutbox.isEnabled() read NATIVELY_USAGE_OUTBOX_ENABLED from process.env.
An app launched from the Dock or the Start menu inherits no environment and
nothing in this repo set it, so the outbox shipped inert on 2026-08-14 and
record() returned 'disabled' — the events were never even written locally, so
they are gone rather than undelivered. Polarity is inverted: absent means ON,
an explicit 0/false/off/no disables, and '' reads as absent so a mis-templated
launcher config cannot silently kill it.

Be honest about what that costs: =0 is now reachable only in dev, CI and a
terminal launch, so the client half is NOT a production kill switch and the
docblock that promised "a client can stop emitting without a server change" is
gone. The lever that reaches a shipped fleet is the server's
BYOK_CLIENT_EVENTS_ENABLED=0 → 503, which the outbox retries for ~15 days
rather than acking away. One working lever is enough.

2. operational_telemetry_events HAD ZERO EMITTERS

A migration, a route, an allowlist, a 45-day sweep — and nothing in this
application ever called usageOutbox.recordTelemetry(). runTracked neither calls
tracker.telemetry() nor hands the tracker to the handler. Turning
OPS_TELEMETRY_ENABLED on would have changed nothing, because "enabled" and
"emitting" are different facts and only one had been built.

recordTurnTelemetry(trace) now maps the AnswerTrace the pipeline already
produces, called from recordTurnMetrics() — the one funnel where both engines
hand over a finished trace, so it needs no new instrumentation on the answer
path and cannot miss a surface.

That hook was chosen carefully. recordLegacyTurn() looks live (three call sites
in ipcHandlers and IntelligenceEngine) but is gated on NATIVELY_CI_V3_TRACE,
which a packaged app never sees — an emitter there would have shipped into dead
code, the exact bug this commit exists to fix. recordTurnMetrics is reached via
buildV3Prompt → orchestrate() because DEFAULT_ENABLED has been true since
2026-07-30.

SUPERSEDED maps to 'interrupted', never 'completed': auto-answer supersedes
turns routinely and counting them as completions inflates every rate built on
the table. Metadata is 5 keys with 3 spare under MAX_METADATA_KEYS=8, because
overflow does not strip — the server rejects the whole event and the outbox
then drops it permanently as a poison row. llm_ttfb_ms is named for what the
trace measures (time to first byte), not the llm_duration_ms the migration
comment suggested.

3. recordAppStarted / recordAppShutdown HAD ZERO CALLERS

Both written 2026-08-14, both unreferenced. Wired in main.ts: started once the
outbox is up, shutdown as the FIRST statement in will-quit — ahead of
checkpointDatabase('will-quit'), because record() is a synchronous INSERT into
the file about to be checkpointed and it swallows its own errors, so writing
afterwards would lose the row with no signal. SIGTERM/SIGINT call app.exit()
and bypass will-quit, so a killed app records no shutdown; that is the honest
outcome, not a bug to fix.

KNOWN LIMITATION: the telemetry row and the _tracked() ledger row for one turn
share no feature_session_id — different wrappers. Correlate on time plus
app_session_id until that matters enough to thread an id.

TESTING. UsageTelemetryEmission.test.mjs imports natively-api's REAL
validateAuditBatch and asserts every emitted payload is accepted: the two
allowlists live in different repos and drift, and a refused event is dropped
rather than retried. Mutation-probed — injecting a prose metadata value turns
it red with metadata_bad_value. It is a separate FILE because the emitter
reaches DatabaseManager through the bundle inlined into usageInstrumentation.js,
which holds its own per-process singleton; sharing a process meant earlier
describes deleted the userData dir out from under it and every assertion read
zero rows.

Verified on macOS: 30/30 UsageOutbox + 12/12 UsageTelemetryEmission under
ELECTRON_RUN_AS_NODE=1 electron, 1897/1897 test:intelligence, typecheck clean.
No process.platform branch exists in this path (it appears once, as a data
field), but the packaged-launch environment and the Windows shutdown path were
reviewed, not executed.

Submodule: natively-api 6217f1f..35e5a4d (the three server flags, same
polarity).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013FjZgLYK8eDRv9zRMBVLVS

Author: Hardening v2.7

electron/context-intelligence/observability/rollout-metrics.ts

@@ -127,6 +127,20 @@ const bump = (m: Record<string, number>, k: string | undefined) => {
  * the answer. Callers are not expected to wrap it.
  */
 export function recordTurnMetrics(trace: AnswerTrace | null | undefined): void {
+  // Operational telemetry (layer B), emitted from the same funnel for the same
+  // reason the counters are: this is the ONE place both engines hand over a
+  // finished trace, so an emitter here needs no new instrumentation on the
+  // answer path and cannot miss a surface.
+  //
+  // Lazily required and independently wrapped. UsageOutbox reaches
+  // InstallPingManager, which touches app.getPath('userData') — an eager import
+  // would throw in every context without a ready Electron app, which is exactly
+  // the offline evaluators and replay harnesses that load this module.
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    require('../../services/usageInstrumentation').recordTurnTelemetry(trace);
+  } catch { /* observability only */ }
+
   try {
     if (!trace) return;
     const t = trace as unknown as Record<string, any>;

electron/main.ts

@@ -8425,15 +8425,30 @@ async function initializeApp() {
   //
   // Started AFTER credentials are loaded, but the key is passed as a GETTER
   // rather than a value: a user who pastes their Natively key ten minutes from
-  // now must not need a restart before their queued events can drain. Inert
-  // unless NATIVELY_USAGE_OUTBOX_ENABLED is set, so shipping this changes
-  // nothing until the flag is switched on.
+  // now must not need a restart before their queued events can drain.
+  //
+  // ON BY DEFAULT since 2026-08-27. It was gated behind an unset env var from
+  // 2026-08-14 until then, which meant the whole ledger shipped inert and
+  // collected nothing in production for the entire period. Setting
+  // NATIVELY_USAGE_OUTBOX_ENABLED=0 turns it back off, but only where an
+  // environment can actually be set (dev, CI, a terminal launch) — a packaged
+  // app inherits none. The production kill switch is server-side; see
+  // UsageOutbox.isEnabled().
   try {
     const { usageOutbox } = require('./services/UsageOutbox');
     usageOutbox.start(() => CredentialsManager.getInstance().getNativelyApiKey());
     // Drain anything queued while the app was closed, without waiting a full
     // dispatch interval. Deliberately not awaited — startup must not block on it.
     setTimeout(() => { void usageOutbox.dispatchOnce(); }, 5000);
+
+    // §5 application lifecycle. recordAppStarted/recordAppShutdown were written
+    // on 2026-08-14 and had ZERO callers until 2026-08-27 — the functions
+    // existed, the taxonomy reserved app_started/app_shutdown, and nothing ever
+    // emitted either. Started is recorded here rather than at whenReady so it
+    // means "the app came up far enough to be usable", which is the only
+    // reading a launch-failure investigation can act on.
+    const { recordAppStarted } = require('./services/usageInstrumentation');
+    recordAppStarted();
   } catch (err: any) {
     console.warn('[UsageOutbox] startup failed (non-fatal):', err?.message || err);
   }
@@ -8992,6 +9007,19 @@ if (process.env.THINKING_MATRIX === '1') {
   }
 
   app.on('will-quit', () => {
+    // FIRST, and deliberately so: record() is a synchronous INSERT into the
+    // same SQLite file that checkpointDatabase('will-quit') below is about to
+    // checkpoint, and record() swallows its own errors — so writing after the
+    // checkpoint would lose the row with no signal at all. Ordering is the
+    // whole correctness argument here.
+    //
+    // Only the graceful path emits this. SIGTERM/SIGINT call app.exit(), which
+    // bypasses will-quit — so a killed app records no shutdown, which is the
+    // honest outcome rather than a fabricated one.
+    try {
+      const { recordAppShutdown } = require('./services/usageInstrumentation');
+      recordAppShutdown();
+    } catch { /* instrumentation must never block a quit */ }
     appState.stopNativeOomTraceSampling();
     nativeOomTrace.stop('will-quit');
     stopAppManagedHindsight('will-quit');

electron/services/UsageOutbox.ts

@@ -32,7 +32,9 @@
  *      and returns. No network, no await for the caller.
  *   2. Never throws into a caller. Every entry point is wrapped. An audit bug
  *      must not be able to fail a meeting.
- *   3. Inert unless enabled. Two flags, checked per call.
+ *   3. On by default, killable server-side. Both flags are checked per call;
+ *      each defaults ON and is turned off with an explicit `=0`. The lever that
+ *      reaches a shipped fleet is the server's, not this one — see isEnabled().
  *   4. Bounded. 10,000 rows / oldest-undelivered dropped past the cap, counted.
  *   5. No content. Only identifiers, enums, counts and durations — the server
  *      allowlist rejects anything else, and this file must never try to send it.
@@ -93,6 +95,21 @@ const BACKOFF_MS = [
     20 * 60_000, 30 * 60_000, 60 * 60_000,
 ];
 
+/**
+ * Flag polarity for this subsystem: **absent means ON**. Only an explicit
+ * off-value disables.
+ *
+ * `''` is treated as absent on purpose. `FOO=$UNSET_VAR` exports an empty
+ * string, which is how a mis-templated CI or launcher config silently kills a
+ * subsystem it never meant to touch. An empty value is missing information, not
+ * an instruction to stop recording.
+ */
+export function usageFlagEnabled(v: string | undefined): boolean {
+    if (v === undefined || v === '') return true;
+    const s = v.trim().toLowerCase();
+    return !(s === '0' || s === 'false' || s === 'off' || s === 'no');
+}
+
 export type UsageLayer = 'ledger' | 'telemetry';
 
 export interface UsageEventInput {
@@ -143,13 +160,24 @@ export class UsageOutbox {
     }
 
     /**
-     * Both flags must be on. The client half is separately switchable from the
-     * server half so a bad client release can be silenced server-side without a
-     * client update, and a client can stop emitting without a server change.
+     * On by default. `NATIVELY_USAGE_OUTBOX_ENABLED=0` (or `false`/`off`/`no`)
+     * turns it off.
+     *
+     * HONEST LIMIT OF THIS SWITCH. It reads `process.env`, and a packaged app
+     * launched from the Dock or the Start menu inherits no environment — so
+     * once this defaults ON, `=0` is reachable only in development, in CI, and
+     * from a terminal launch. It is NOT a production kill switch, and the
+     * previous claim here that "a client can stop emitting without a server
+     * change" is no longer true. Do not rely on it during an incident.
+     *
+     * The switch that still works against a shipped fleet is the server's
+     * `BYOK_CLIENT_EVENTS_ENABLED=0`: /v1/usage/audit answers 503, and this
+     * outbox treats 503 as retryable and HOLDS the events (~15 days, see
+     * MAX_ATTEMPTS) instead of acking them away. Silencing a bad client release
+     * therefore costs no data, which is why one lever is enough.
      */
     public isEnabled(): boolean {
-        const v = process.env.NATIVELY_USAGE_OUTBOX_ENABLED;
-        return v === '1' || v === 'true';
+        return usageFlagEnabled(process.env.NATIVELY_USAGE_OUTBOX_ENABLED);
     }
 
     /**

electron/services/__tests__/UsageOutbox.test.mjs

@@ -400,3 +400,87 @@ describe('runTracked outcome classification', () => {
     }
   });
 });
+
+// ── Flag polarity (2026-08-27) ───────────────────────────────────────────────
+//
+// The outbox shipped on 2026-08-14 gated behind NATIVELY_USAGE_OUTBOX_ENABLED,
+// a variable a packaged Electron app can never see — it is not set by the app,
+// and a launch from the Dock or the Start menu inherits no environment. The
+// result was a subsystem that looked shipped and recorded nothing at all in
+// production. These tests pin the inverted default so that cannot recur.
+describe('outbox flag polarity', { skip: HAVE_BUILD ? false : 'run `npm run build:electron` first' }, () => {
+    const OUTBOX_PATH = path.join(REPO, 'dist-electron/electron/services/UsageOutbox.js');
+    const ORIGINAL = process.env.NATIVELY_USAGE_OUTBOX_ENABLED;
+
+    after(() => {
+        if (ORIGINAL === undefined) delete process.env.NATIVELY_USAGE_OUTBOX_ENABLED;
+        else process.env.NATIVELY_USAGE_OUTBOX_ENABLED = ORIGINAL;
+    });
+
+    test('an absent flag enables the outbox', () => {
+        const { usageOutbox } = require(OUTBOX_PATH);
+        delete process.env.NATIVELY_USAGE_OUTBOX_ENABLED;
+        assert.equal(usageOutbox.isEnabled(), true, 'absent must mean on');
+    });
+
+    test('only an explicit off-value disables it', () => {
+        const { usageOutbox } = require(OUTBOX_PATH);
+        for (const off of ['0', 'false', 'FALSE', 'off', 'no', ' 0 ']) {
+            process.env.NATIVELY_USAGE_OUTBOX_ENABLED = off;
+            assert.equal(usageOutbox.isEnabled(), false, `${JSON.stringify(off)} must disable`);
+        }
+        for (const on of ['1', 'true', 'yes', 'anything-else']) {
+            process.env.NATIVELY_USAGE_OUTBOX_ENABLED = on;
+            assert.equal(usageOutbox.isEnabled(), true, `${JSON.stringify(on)} must not disable`);
+        }
+    });
+
+    test('an empty value reads as absent, not as off', () => {
+        // `FOO=$UNSET_VAR` exports an empty string. A mis-templated launcher or
+        // CI config must not be able to silently take the outbox dark.
+        const { usageOutbox } = require(OUTBOX_PATH);
+        process.env.NATIVELY_USAGE_OUTBOX_ENABLED = '';
+        assert.equal(usageOutbox.isEnabled(), true, 'empty must mean absent');
+    });
+
+    // The three tests above only prove a boolean. This one proves the thing the
+    // boolean is FOR: that with no flag set, a recorded event actually lands in
+    // the local table. That is the exact failure that went unnoticed for two
+    // weeks — record() returned 'disabled' and wrote nothing, so the events were
+    // gone rather than merely undelivered, and no amount of fixing the server
+    // could get them back.
+    test('with no flag set, record() actually persists a row to the outbox table', () => {
+        const tdir = fs.mkdtempSync(path.join(os.tmpdir(), 'natively-polarity-test-'));
+        const prevUserData = process.env.NATIVELY_TEST_USERDATA;
+        process.env.NATIVELY_TEST_USERDATA = tdir;
+        delete process.env.NATIVELY_USAGE_OUTBOX_ENABLED;
+
+        const { DatabaseManager } = require(DBM_PATH);
+        DatabaseManager.instance = null;
+        const pdb = DatabaseManager.getInstance();
+        try {
+            const { usageOutbox } = require(OUTBOX_PATH);
+            const result = usageOutbox.record({
+                event_type: 'feature_completed',
+                event_status: 'completed',
+                feature: 'mode_execution',
+                reported_duration_ms: 1234,
+            });
+            assert.notEqual(result, 'disabled', 'an absent flag must not disable recording');
+
+            const rows = pdb.claimUsageOutboxBatch(100, Date.now() + 10 ** 12);
+            assert.equal(rows.length, 1, 'exactly one row must be queued for delivery');
+            const payload = rows[0].payload;
+            assert.equal(payload.layer, 'ledger');
+            assert.equal(payload.event_type, 'feature_completed');
+            assert.equal(payload.feature, 'mode_execution');
+            assert.equal(payload.reported_duration_ms, 1234);
+        } finally {
+            try { pdb?.close?.(); } catch { /* ignore */ }
+            DatabaseManager.instance = null;
+            if (prevUserData === undefined) delete process.env.NATIVELY_TEST_USERDATA;
+            else process.env.NATIVELY_TEST_USERDATA = prevUserData;
+            try { fs.rmSync(tdir, { recursive: true, force: true }); } catch { /* ignore */ }
+        }
+    });
+});