@g9tm/app-pilot 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,16 @@
+MIT License
+
+Copyright (c) 2026 Iman Kari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@g9tm/app-pilot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "G9AppPilot core: the command registry and manifest, scopes, the dispatch order, actionable errors, event batching, the busy tracker, the lease, the tap recorder and the black box (logs, requests, stores, database, failure traces) — for full, signed control of an app by agents and test runners. Platform-free.",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./idle": {
+      "source": "./src/idle.ts",
+      "types": "./src/idle.ts",
+      "default": "./src/idle.ts"
+    },
+    "./lease": {
+      "source": "./src/lease.ts",
+      "types": "./src/lease.ts",
+      "default": "./src/lease.ts"
+    },
+    "./recorder": {
+      "source": "./src/recorder.ts",
+      "types": "./src/recorder.ts",
+      "default": "./src/recorder.ts"
+    },
+    "./blackbox": {
+      "source": "./src/blackbox.ts",
+      "types": "./src/blackbox.ts",
+      "default": "./src/blackbox.ts"
+    },
+    "./stage": {
+      "source": "./src/stage.ts",
+      "types": "./src/stage.ts",
+      "default": "./src/stage.ts"
+    },
+    "./design": {
+      "source": "./src/design.ts",
+      "types": "./src/design.ts",
+      "default": "./src/design.ts"
+    },
+    "./oracles": {
+      "source": "./src/oracles.ts",
+      "types": "./src/oracles.ts",
+      "default": "./src/oracles.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.18"
+  }
+}

package/src/args.ts

@@ -0,0 +1,26 @@
+// Argument readers (strings only from JSON strings, integers only from numbers — the semantics existing flows rely on).
+import { PilotError } from './errors.ts';
+import type { PilotArgs } from './registry.ts';
+
+export function requireString(args: PilotArgs, name: string): string {
+  const value = args[name];
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new PilotError(`This command needs a "${name}" argument.`, { code: 'INVALID_ARGS', hint: `Pass "${name}" as a non-empty string.` });
+  }
+  return value;
+}
+
+export function optionalString(args: PilotArgs, name: string): string | null {
+  const value = args[name];
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+export function optionalInt(args: PilotArgs, name: string, fallback: number): number {
+  const value = args[name];
+  return typeof value === 'number' && Number.isFinite(value) ? Math.trunc(value) : fallback;
+}
+
+export function optionalBool(args: PilotArgs, name: string, fallback: boolean): boolean {
+  const value = args[name];
+  return typeof value === 'boolean' ? value : fallback;
+}

package/src/blackbox.ts

@@ -0,0 +1,554 @@
+// The black box: what the app did while an agent drove it — the console, the network, the commands it answered, its
+// stores and its database — kept in small rings on the device and read on demand, plus a TRACE for every failed
+// command: the failure with what led to it (the last commands, logs, requests, the busy state and the app's own
+// sections, the screen first), so the agent that sees «not found» also sees why without asking five more questions.
+//
+//   installBlackbox({ console: true, fetch: true, autoTrace: true });
+//   registerStore('session', () => sessionStore.get(), { subscribe: sessionStore.subscribe });   // store.* / app.stores*
+//   registerDbQuery((sql, params) => db.all(sql, params));        // db.query (admin: rows can hold anything)
+//   registerTraceSection('screen', () => snapshotTree());          // part of every trace
+//   recordNet({ method, url, status, ms });                        // an app whose HTTP is native reports it itself
+//
+// Secrets never leave: values under a key that looks like a secret (token, password, authorization, cookie, key…) are
+// replaced, and a text loses its bearer tokens, JWTs and secret query values (pilot/AiGuides/03 «Black box»).
+// Debug builds only — like every pilot module, the app installs it behind its production switch.
+import { onAnswer, type PilotAnswer, type PilotRequest } from './dispatch.ts';
+import { emit, eventChannelOn, setEventChannel } from './events.ts';
+import { busySnapshot } from './idle.ts';
+import { optionalBool, optionalInt, optionalString, requireString } from './args.ts';
+import { PilotError } from './errors.ts';
+import { type PilotArgs, registerCommand } from './registry.ts';
+
+// ---- redaction -----------------------------------------------------------------------------------------------------
+
+const SECRET_KEY = /pass(word)?|secret|token|authori[sz]ation|cookie|api[-_]?key|private|signature|^sig$|otp|^pin$|credential|session[-_]?id/i;
+const REDACTED = '‹redacted›';
+
+/** A text without bearer tokens, JWTs and secret query values. */
+export function redactText(text: string, max = 2_000): string {
+  let s = text
+    .replace(/(bearer|basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi, `$1 ${REDACTED}`)
+    .replace(/eyJ[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}\.[A-Za-z0-9_-]{6,}/g, '‹jwt›')
+    .replace(/([?&;](?:[^=&\s]*(?:token|key|password|secret|sig|signature|code|otp)[^=&\s]*)=)[^&\s#"']+/gi, `$1${REDACTED}`);
+  if (s.length > max) s = `${s.slice(0, max)}… (${s.length - max} more characters)`;
+  return s;
+}
+
+/** A value safe to hand out: secrets replaced, long strings (over `maxString`) and lists cut, deep trees stopped. */
+export function redactValue(value: unknown, depth = 6, maxString = 500, seen: WeakSet<object> = new WeakSet()): unknown {
+  if (value === null || value === undefined) return value ?? null;
+  if (typeof value === 'string') return redactText(value, maxString);
+  if (typeof value === 'number' || typeof value === 'boolean') return value;
+  if (typeof value === 'bigint') return String(value);
+  if (typeof value === 'function') return '‹function›';
+  if (typeof value !== 'object') return String(value);
+  if (seen.has(value)) return '‹cycle›';
+  if (depth <= 0) return Array.isArray(value) ? `‹${value.length} items›` : '‹…›';
+  seen.add(value);
+  if (value instanceof Date) return value.toISOString();
+  if (value instanceof Map) return redactValue(Object.fromEntries(value), depth, maxString, seen);
+  if (value instanceof Set) return redactValue([...value], depth, maxString, seen);
+  if (Array.isArray(value)) {
+    const out: unknown[] = value.slice(0, 50).map((v) => redactValue(v, depth - 1, maxString, seen));
+    if (value.length > 50) out.push(`‹${value.length - 50} more›`);
+    return out;
+  }
+  const out: Record<string, unknown> = {};
+  let n = 0;
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    if (++n > 100) {
+      out['…'] = `‹${Object.keys(value).length - 100} more keys›`;
+      break;
+    }
+    out[k] = SECRET_KEY.test(k) && v !== null && v !== undefined && v !== '' ? REDACTED : redactValue(v, depth - 1, maxString, seen);
+  }
+  return out;
+}
+
+// ---- rings ---------------------------------------------------------------------------------------------------------
+
+/** A fixed-size list numbered from 1: `since(n)` is everything after entry n, so a reader polls without repeats. */
+export class Ring<T extends { readonly seq: number }> {
+  readonly capacity: number;
+  private items: T[] = [];
+  private next = 1;
+
+  constructor(capacity: number) {
+    this.capacity = capacity;
+  }
+
+  push(make: (seq: number) => T): T {
+    const item = make(this.next++);
+    this.items.push(item);
+    if (this.items.length > this.capacity) this.items.splice(0, this.items.length - this.capacity);
+    return item;
+  }
+
+  since(seq: number, limit: number, keep: (item: T) => boolean = () => true): T[] {
+    const out = this.items.filter((i) => i.seq > seq && keep(i));
+    return out.slice(Math.max(0, out.length - limit));
+  }
+
+  last(): number {
+    return this.next - 1;
+  }
+
+  clear(): void {
+    this.items = [];
+  }
+}
+
+export type LogLevel = 'debug' | 'log' | 'info' | 'warn' | 'error';
+const LEVELS: readonly LogLevel[] = ['debug', 'log', 'info', 'warn', 'error'];
+
+export interface LogEntry {
+  readonly seq: number;
+  readonly t: number;
+  readonly level: LogLevel;
+  readonly text: string;
+}
+
+export interface NetEntry {
+  readonly seq: number;
+  readonly t: number;
+  readonly method: string;
+  readonly url: string;
+  readonly status: number | null;
+  readonly ms: number;
+  readonly bytes?: number | null;
+  readonly error?: string | null;
+}
+
+export interface TrailEntry {
+  readonly seq: number;
+  readonly t: number;
+  readonly command: string;
+  readonly ok: boolean;
+  readonly ms: number;
+  readonly code?: string;
+  readonly error?: string;
+}
+
+export interface PilotTrace {
+  readonly id: string;
+  readonly at: string;
+  readonly reason: string;
+  readonly command: string | null;
+  readonly args: unknown;
+  readonly error: string | null;
+  readonly code: string | null;
+  readonly category: string | null;
+  readonly ms: number | null;
+  readonly busy: unknown;
+  readonly trail: readonly TrailEntry[];
+  readonly logs: readonly LogEntry[];
+  readonly net: readonly NetEntry[];
+  readonly sections: Readonly<Record<string, unknown>>;
+}
+
+const logs = new Ring<LogEntry>(400);
+const net = new Ring<NetEntry>(200);
+const trail = new Ring<TrailEntry>(100);
+const traces: PilotTrace[] = [];
+// Traces still being taken (a section takes up to its timeout): trace.list / trace.get wait for them, so an agent that
+// asks right after a failure gets that failure, not «no trace yet» (found by the evaluation suite, 2026-11-04).
+const inFlight = new Set<Promise<unknown>>();
+const settled = async () => {
+  // No Promise.allSettled: an app may compile for ES2019 (Lynx does), so each call is made unable to reject instead.
+  const quiet = [...inFlight].map((p) => p.then(() => undefined, () => undefined));
+  if (quiet.length) await Promise.race([Promise.all(quiet), new Promise((r) => setTimeout(r, 4_000))]);
+};
+const TRACE_KEEP = 5;
+let traceSeq = 0;
+
+const stores = new Map<string, () => unknown>();
+// Stores that say when they change: name → the change number of its last change (app.storesDiff {since}).
+const storeChanges = new Map<string, number>();
+let storeSeq = 0;
+const sections = new Map<string, { readonly read: () => unknown; readonly timeoutMs: number }>();
+let dbQuery: ((sql: string, params: readonly unknown[]) => unknown) | null = null;
+
+const textOf = (args: readonly unknown[]): string =>
+  args
+    .map((a) => {
+      if (typeof a === 'string') return a;
+      if (a instanceof Error) return `${a.name}: ${a.message}`;
+      try {
+        return JSON.stringify(redactValue(a, 3));
+      } catch {
+        return String(a);
+      }
+    })
+    .join(' ');
+
+const logListeners = new Set<(entry: LogEntry) => void>();
+
+/** Every line the box records (the oracles' `log.error` listens here). Returns the remover. */
+export function onLogRecorded(listener: (entry: LogEntry) => void): () => void {
+  logListeners.add(listener);
+  return () => logListeners.delete(listener);
+}
+
+/** One log line into the box (the console capture calls it; an app's own logger may too). */
+export function recordLog(level: LogLevel, ...args: unknown[]): void {
+  const entry = logs.push((seq) => ({ seq, t: Date.now(), level, text: redactText(textOf(args)) }));
+  for (const l of logListeners) {
+    try {
+      l(entry);
+    } catch {
+      // a listener never breaks the log
+    }
+  }
+  if (level === 'warn' || level === 'error') emit('log', { level, text: entry.text.slice(0, 300) });
+  // Every line, on the event stream, while someone asked for it (log.stream {on: true}).
+  if (eventChannelOn('log.line')) emit('log.line', { seq: entry.seq, level, text: entry.text });
+}
+
+/** One request into the box (the fetch capture calls it; an app whose HTTP runs natively reports its own). */
+export function recordNet(entry: Omit<NetEntry, 'seq' | 't'> & { readonly t?: number }): void {
+  const e = net.push((seq) => ({
+    seq,
+    t: entry.t ?? Date.now(),
+    method: entry.method.toUpperCase(),
+    url: redactText(entry.url, 400),
+    status: entry.status,
+    ms: Math.round(entry.ms),
+    ...(entry.bytes !== undefined ? { bytes: entry.bytes } : {}),
+    ...(entry.error ? { error: redactText(entry.error, 300) } : {}),
+  }));
+  emit('net', { method: e.method, url: e.url, status: e.status, ms: e.ms });
+}
+
+/**
+ * A store an agent may read (`store.get {name}`, `app.stores`): the getter is called on each read, its value redacted.
+ * With `subscribe` (a store's own subscribe) its changes are numbered for `app.storesDiff {since}` and, while
+ * `store.watch` is on, emitted as `store.change {name}` events.
+ */
+export function registerStore(name: string, read: () => unknown, options: { readonly subscribe?: (listener: () => void) => () => void } = {}): () => void {
+  stores.set(name, read);
+  const unsubscribe = options.subscribe?.(() => {
+    storeChanges.set(name, ++storeSeq);
+    emit('store.change', { name, seq: storeSeq });
+  });
+  if (options.subscribe) storeChanges.set(name, storeChanges.get(name) ?? 0);
+  return () => {
+    unsubscribe?.();
+    if (stores.get(name) === read) {
+      stores.delete(name);
+      storeChanges.delete(name);
+    }
+  };
+}
+
+/** The app's database, read-only (`db.query`): one SELECT / WITH / PRAGMA / EXPLAIN statement at a time. */
+export function registerDbQuery(run: (sql: string, params: readonly unknown[]) => unknown): () => void {
+  dbQuery = run;
+  return () => {
+    if (dbQuery === run) dbQuery = null;
+  };
+}
+
+/** Part of every trace (the screen, the route, the sync state…). A section that throws or is late says so. */
+export function registerTraceSection(name: string, read: () => unknown, options: { readonly timeoutMs?: number } = {}): () => void {
+  const entry = { read, timeoutMs: options.timeoutMs ?? 1_500 };
+  sections.set(name, entry);
+  return () => {
+    if (sections.get(name) === entry) sections.delete(name);
+  };
+}
+
+// ---- captures ------------------------------------------------------------------------------------------------------
+
+function installConsoleCapture(): () => void {
+  const target = (globalThis as unknown as { console?: Record<string, (...a: unknown[]) => void> }).console;
+  if (!target) return () => undefined;
+  const originals = new Map<LogLevel, (...a: unknown[]) => void>();
+  let inside = false;
+  for (const level of LEVELS) {
+    const original = target[level];
+    if (typeof original !== 'function') continue;
+    originals.set(level, original);
+    target[level] = (...args: unknown[]) => {
+      if (!inside) {
+        inside = true;
+        try {
+          recordLog(level, ...args);
+        } catch {
+          // the box never breaks the console
+        } finally {
+          inside = false;
+        }
+      }
+      original.apply(target, args);
+    };
+  }
+  return () => {
+    for (const [level, original] of originals) target[level] = original;
+  };
+}
+
+type FetchFn = (input: unknown, init?: { readonly method?: string }) => Promise<{ readonly status: number; readonly headers?: { get(name: string): string | null } }>;
+
+function installFetchCapture(): () => void {
+  const holder = globalThis as unknown as { fetch?: FetchFn };
+  const original = holder.fetch;
+  if (typeof original !== 'function') return () => undefined;
+  const wrapped: FetchFn = async (input, init) => {
+    const started = Date.now();
+    const url = typeof input === 'string' ? input : String((input as { url?: string })?.url ?? input);
+    const method = init?.method ?? (input as { method?: string })?.method ?? 'GET';
+    try {
+      const response = await original(input, init);
+      const length = Number(response.headers?.get('content-length') ?? NaN);
+      recordNet({ method, url, status: response.status, ms: Date.now() - started, bytes: Number.isFinite(length) ? length : null });
+      return response;
+    } catch (error) {
+      recordNet({ method, url, status: null, ms: Date.now() - started, error: error instanceof Error ? error.message : String(error) });
+      throw error;
+    }
+  };
+  holder.fetch = wrapped;
+  return () => {
+    if (holder.fetch === wrapped) holder.fetch = original;
+  };
+}
+
+// ---- traces --------------------------------------------------------------------------------------------------------
+
+const OWN = /^(trace|log|net|store|db)\.|^app\.stores|^pilot\.|^qa\.(ping|capabilities)$/;
+const NOT_A_FAILURE = new Set(['SCOPE', 'LEASE', 'SIG_MISSING', 'UNKNOWN_KID', 'SIG_INVALID', 'REPLAY', 'CLOCK_SKEW']);
+// A key, a lease or a signature refused: the caller's matter, not the app's — no trace.
+const QUIET_CATEGORIES = new Set(['scope', 'lease', 'auth']);
+
+async function withTimeout(read: () => unknown, ms: number): Promise<unknown> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      Promise.resolve().then(read),
+      new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ unavailable: `no answer within ${ms} ms` }), ms);
+      }),
+    ]);
+  } catch (error) {
+    return { unavailable: error instanceof Error ? error.message : String(error) };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/** Takes a trace now: what the box holds, the busy state and every registered section. */
+export async function captureTrace(reason: string, failed: { readonly request?: PilotRequest; readonly answer?: PilotAnswer; readonly ms?: number } = {}): Promise<PilotTrace> {
+  const answer = failed.answer && !failed.answer.ok ? failed.answer : null;
+  // What led to it is taken NOW, before the sections are awaited: a command answered meanwhile is not part of it.
+  const id = `T-${++traceSeq}`;
+  const before = { busy: redactValue(busySnapshot(), 4), trail: trail.since(0, 30), logs: logs.since(0, 80), net: net.since(0, 40) };
+  const read: Record<string, unknown> = {};
+  // A section is the app's own account (the screen tree is a long text, a small screenshot a longer one): up to
+  // 200 000 characters a string, not 500.
+  for (const [name, s] of sections) read[name] = redactValue(await withTimeout(s.read, s.timeoutMs), 8, 200_000);
+  const trace: PilotTrace = {
+    id,
+    at: new Date().toISOString(),
+    reason,
+    command: failed.request?.command ?? null,
+    args: failed.request ? redactValue(failed.request.args ?? {}, 4) : null,
+    error: answer ? redactText(answer.error, 1_000) : null,
+    code: answer?.code ?? null,
+    category: answer?.category ?? null,
+    ms: failed.ms ?? null,
+    ...before,
+    sections: read,
+  };
+  traces.push(trace);
+  if (traces.length > TRACE_KEEP) traces.splice(0, traces.length - TRACE_KEEP);
+  emit('trace', { id: trace.id, command: trace.command, error: trace.error?.slice(0, 200) ?? null });
+  return trace;
+}
+
+// ---- install -------------------------------------------------------------------------------------------------------
+
+export interface BlackboxOptions {
+  /** Capture console.* (default true). */
+  readonly console?: boolean;
+  /** Capture the JS `fetch` (default true; native HTTP reports through recordNet). */
+  readonly fetch?: boolean;
+  /** A trace for every failed command (default true). */
+  readonly autoTrace?: boolean;
+}
+
+const sinceArg = (args: PilotArgs) => Math.max(0, optionalInt(args, 'since', 0));
+
+/** Installs the captures and the commands log.tail, net.log, store.list/get, db.query, trace.list/get/capture. */
+export function installBlackbox(options: BlackboxOptions = {}): () => void {
+  const undo: (() => void)[] = [];
+  if (options.console !== false) undo.push(installConsoleCapture());
+  if (options.fetch !== false) undo.push(installFetchCapture());
+  undo.push(
+    onAnswer((request, answer, ms) => {
+      if (OWN.test(request.command)) return;
+      trail.push((seq) => ({
+        seq,
+        t: Date.now(),
+        command: request.command,
+        ok: answer.ok,
+        ms,
+        ...(answer.ok ? {} : { code: answer.code, error: redactText(answer.error, 200) }),
+      }));
+      if (options.autoTrace !== false && !answer.ok && !NOT_A_FAILURE.has(answer.code) && !QUIET_CATEGORIES.has(answer.category)) {
+        const taking = captureTrace('failed command', { request, answer, ms }).catch(() => undefined);
+        inFlight.add(taking);
+        void taking.finally(() => inFlight.delete(taking));
+      }
+    }),
+  );
+
+  undo.push(
+    registerCommand(
+      'log.tail',
+      (args) => {
+        const level = optionalString(args, 'level') as LogLevel | null;
+        if (level && !LEVELS.includes(level)) throw new PilotError(`Unknown level "${level}".`, { code: 'BAD_ARGS', hint: `One of ${LEVELS.join(', ')}.` });
+        const min = level ? LEVELS.indexOf(level) : 0;
+        return { entries: logs.since(sinceArg(args), Math.min(500, optionalInt(args, 'limit', 100)), (e) => LEVELS.indexOf(e.level) >= min), last: logs.last() };
+      },
+      { scope: 'observe', description: 'The app’s console since entry `since` (secrets removed); `level` warn shows warnings and errors only. Poll with the returned `last`.', example: { since: 0, level: 'warn' } },
+    ),
+    registerCommand(
+      'net.log',
+      (args) => {
+        const failedOnly = optionalBool(args, 'failedOnly', false);
+        const filter = optionalString(args, 'filter')?.toLowerCase() ?? null;
+        return {
+          entries: net.since(sinceArg(args), Math.min(200, optionalInt(args, 'limit', 50)), (e) => (!failedOnly || e.status === null || e.status >= 400) && (!filter || e.url.toLowerCase().includes(filter))),
+          last: net.last(),
+        };
+      },
+      { scope: 'observe', description: 'The app’s requests since entry `since`: method, address (secret values removed), status, time, size; `failedOnly` keeps errors and 4xx/5xx, `filter` a part of the address.', example: { failedOnly: true, filter: '/api/' } },
+    ),
+    registerCommand('store.list', () => ({ stores: [...stores.keys()].sort() }), { scope: 'observe', description: 'The stores the app lets an agent read.' }),
+    registerCommand(
+      'store.get',
+      (args) => {
+        const name = requireString(args, 'name');
+        const read = stores.get(name);
+        if (!read) throw new PilotError(`No store named "${name}" (not found).`, { code: 'NOT_FOUND', hint: `Known: ${[...stores.keys()].sort().join(', ') || 'none'}.`, fixExample: { command: 'store.list' } });
+        let value = read();
+        const path = optionalString(args, 'path');
+        for (const part of path ? path.split('.') : []) value = value === null || value === undefined ? undefined : (value as Record<string, unknown>)[part];
+        return { name, path, value: redactValue(value, optionalInt(args, 'depth', 6)) };
+      },
+      { scope: 'observe', description: 'One store’s value now (secrets removed), or a dotted `path` inside it.', example: { name: 'session', path: 'user' } },
+    ),
+    registerCommand(
+      'app.stores',
+      (args) => {
+        const only = optionalString(args, 'name');
+        const names = only ? [only] : [...stores.keys()].sort();
+        const out: Record<string, unknown> = {};
+        for (const name of names) {
+          const read = stores.get(name);
+          if (!read) throw new PilotError(`No store named "${name}" (not found).`, { code: 'NOT_FOUND', hint: `Known: ${[...stores.keys()].sort().join(', ') || 'none'}.` });
+          try {
+            out[name] = redactValue(read(), optionalInt(args, 'depth', 4));
+          } catch (error) {
+            out[name] = { unavailable: error instanceof Error ? error.message : String(error) };
+          }
+        }
+        return { stores: out, last: storeSeq };
+      },
+      { scope: 'observe', description: 'Every store’s value now (or one, `name`), secrets removed; `last` is the change number for app.storesDiff.' },
+    ),
+    registerCommand(
+      'app.storesDiff',
+      (args) => {
+        const since = sinceArg(args);
+        const changed: Record<string, unknown> = {};
+        for (const [name, seq] of storeChanges) if (seq > since) changed[name] = redactValue(stores.get(name)?.(), optionalInt(args, 'depth', 4));
+        return { changed, last: storeSeq, untracked: [...stores.keys()].filter((n) => !storeChanges.has(n)).sort() };
+      },
+      { scope: 'observe', description: 'The stores that changed after change number `since`, with their values now; `untracked` lists stores that do not say when they change.', example: { since: 0 } },
+    ),
+    registerCommand(
+      'store.watch',
+      (args) => {
+        const on = optionalBool(args, 'on', true);
+        setEventChannel('store.change', on);
+        return { watching: on };
+      },
+      { scope: 'observe', mutating: false, description: 'store.change events on the stream while on (heavy; off by default).' },
+    ),
+    registerCommand(
+      'log.stream',
+      (args) => {
+        const on = optionalBool(args, 'on', true);
+        setEventChannel('log.line', on);
+        return { streaming: on, last: logs.last() };
+      },
+      { scope: 'observe', mutating: false, description: 'Every log line as a log.line event on the stream while on (GET /pilot/events); warnings and errors are always there as `log`.' },
+    ),
+    registerCommand(
+      'db.query',
+      async (args) => {
+        if (!dbQuery) throw new PilotError('This app registered no database (not found).', { code: 'NOT_FOUND', hint: 'The app calls registerDbQuery at start.' });
+        const sql = requireString(args, 'sql').trim().replace(/;\s*$/, '');
+        if (!/^(select|with|pragma\s+(table_info|table_list|index_list|index_info|foreign_key_list|user_version)\b|explain)\b/i.test(sql) || sql.includes(';')) {
+          throw new PilotError('db.query reads only: one SELECT, WITH, EXPLAIN or a schema PRAGMA.', { code: 'BAD_ARGS', category: 'automation', fixExample: { command: 'db.query', args: { sql: 'SELECT name FROM sqlite_master WHERE type = \'table\'' } } });
+        }
+        if (/^with\b/i.test(sql) && /\b(insert|update|delete|replace|create|drop|alter|attach|vacuum)\b/i.test(sql)) {
+          throw new PilotError('db.query reads only: a WITH that writes is refused.', { code: 'BAD_ARGS' });
+        }
+        const limit = Math.min(1_000, optionalInt(args, 'limit', 200));
+        const params = Array.isArray(args.params) ? args.params : [];
+        const timeoutMs = Math.min(20_000, Math.max(500, optionalInt(args, 'timeoutMs', 5_000)));
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const rows = await Promise.race([
+          Promise.resolve(dbQuery(sql, params)),
+          new Promise<never>((_, reject) => {
+            timer = setTimeout(() => reject(new PilotError(`db.query took longer than ${timeoutMs} ms (timed out); a narrower WHERE or a LIMIT helps.`, { code: 'TIMEOUT', category: 'automation', retryable: true })), timeoutMs);
+          }),
+        ]).finally(() => timer && clearTimeout(timer));
+        const list = Array.isArray(rows) ? rows : [];
+        return { rows: redactValue(list.slice(0, limit), 4), count: list.length, truncated: list.length > limit };
+      },
+      { scope: 'admin', description: 'A read-only SQL query on the app’s database (rows can hold anything the app stores, so an admin key only).', example: { sql: 'SELECT count(*) AS n FROM sqlite_master' } },
+    ),
+    registerCommand('trace.list', async () => (await settled(), { traces: traces.map((t) => ({ id: t.id, at: t.at, reason: t.reason, command: t.command, error: t.error?.slice(0, 200) ?? null })) }), {
+      scope: 'observe',
+      description: 'The last failure traces (newest last).',
+    }),
+    registerCommand(
+      'trace.get',
+      async (args) => {
+        await settled();
+        const id = optionalString(args, 'id');
+        const trace = id ? traces.find((t) => t.id === id) : traces[traces.length - 1];
+        if (!trace) throw new PilotError(id ? `No trace ${id} (not found) — only the last ${TRACE_KEEP} are kept.` : 'No trace yet (not found): nothing has failed.', { code: 'NOT_FOUND', fixExample: { command: 'trace.list' } });
+        return trace;
+      },
+      { scope: 'observe', description: 'One failure trace (default the newest): the failed command, what led to it (commands, logs, requests), the busy state and the app’s sections — the screen first.', example: {} },
+    ),
+    registerCommand('trace.capture', async (args) => captureTrace(optionalString(args, 'reason') ?? 'asked'), {
+      scope: 'observe',
+      mutating: false,
+      description: 'A trace now, without a failure (to compare a good state with a bad one).',
+    }),
+  );
+  return () => {
+    for (const u of undo.reverse()) u();
+  };
+}
+
+/** For tests: empty rings, no traces, nothing registered. */
+export function resetBlackboxForTests(): void {
+  logs.clear();
+  net.clear();
+  trail.clear();
+  traces.length = 0;
+  inFlight.clear();
+  traceSeq = 0;
+  stores.clear();
+  storeChanges.clear();
+  storeSeq = 0;
+  sections.clear();
+  dbQuery = null;
+}