@vgai/sdk 0.5.5 → 0.5.7

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/sdk",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "type": "module",
   "repository": {
     "type": "git",
@@ -24,12 +24,13 @@
     "./project-tool-catalog": "./src/project-tool-catalog.ts",
     "./project-inspection-node": "./src/project/inspection-node.ts",
     "./registry": "./src/registry.ts",
+    "./run-name": "./src/project/run-name.ts",
     "./session-journal": "./src/project/session-journal.ts",
     "./tools": "./src/tools.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@vgai/engine": "0.5.5",
+    "@vgai/engine": "0.5.7",
     "playwright": "^1.58.2",
     "zod": "^4.3.6"
   }

package/src/account.ts

@@ -32,6 +32,13 @@ export const AccountSpendPolicySchema = z.object({
     })
     .optional(),
 });
+export const AccountAlertSchema = z.object({
+  id: z.string().min(1),
+  kind: z.enum(['threshold', 'auto_reload_succeeded', 'auto_reload_failed']),
+  message: z.string().min(1),
+  createdAt: z.string().datetime(),
+  readAt: z.string().datetime().optional(),
+});
 export const AccountUserSchema = z.object({
   id: z.string().min(1),
   email: z.string().email(),
@@ -57,13 +64,46 @@ export const AccountOrganizationSchema = z.object({
 export const AccountUsageEntrySchema = z.object({
   id: z.string().min(1),
   occurredAt: z.string().datetime(),
-  kind: z.literal('generation'),
+  kind: z.enum(['inference', 'generation', 'workspace', 'storage', 'relay', 'deployment']),
   provider: z.string().min(1),
   operation: z.string().optional(),
   credits: z.number().nonnegative(),
   state: z.enum(['reserved', 'settled', 'released']),
   externalId: z.string().optional(),
 });
+export const AccountPlanIdSchema = z.enum(['free', 'creator', 'max', 'ultra']);
+export const AccountCatalogSchema = z.object({
+  plans: z.object({
+    free: z.object({
+      name: z.string().min(1),
+      includedCredits: z.number().int().nonnegative(),
+      monthlyPriceUsd: z.number().nonnegative().optional(),
+    }),
+    creator: z.object({
+      name: z.string().min(1),
+      includedCredits: z.number().int().nonnegative(),
+      monthlyPriceUsd: z.number().nonnegative().optional(),
+    }),
+    max: z.object({
+      name: z.string().min(1),
+      includedCredits: z.number().int().nonnegative(),
+      monthlyPriceUsd: z.number().nonnegative().optional(),
+    }),
+    ultra: z.object({
+      name: z.string().min(1),
+      includedCredits: z.number().int().nonnegative(),
+      monthlyPriceUsd: z.number().nonnegative().optional(),
+    }),
+  }),
+  creditPacks: z.record(
+    z.string().min(1),
+    z.object({
+      name: z.string().min(1),
+      credits: z.number().int().positive(),
+      expiresInDays: z.number().int().positive().optional(),
+    }),
+  ),
+});
 export const AccountSnapshotSchema = z.discriminatedUnion('authenticated', [
   z.object({ authenticated: z.literal(false), backend: AccountBackendSchema }),
   z.object({
@@ -74,6 +114,7 @@ export const AccountSnapshotSchema = z.discriminatedUnion('authenticated', [
     plan: AccountPlanSchema,
     credits: AccountCreditsSchema,
     spendPolicy: AccountSpendPolicySchema,
+    alerts: z.array(AccountAlertSchema).max(100).optional(),
     entitlements: z.object({
       generation: z.boolean(),
       dailyJobs: z.number().int().positive().optional(),
@@ -83,7 +124,12 @@ export const AccountSnapshotSchema = z.discriminatedUnion('authenticated', [
 /** Product-facing routes. Provider tools may translate BYOK to their native
  * transport name (`direct`) internally. */
 export const GenerationExecutionRouteSchema = z.enum(['mock', 'managed', 'byok']);
-export const ProviderCredentialIdSchema = z.enum(['fal', 'tripo', 'worldlabs']);
+export const ProviderCredentialIdSchema = z.enum(['fal', 'tripo', 'worldlabs', 'openrouter']);
+export const CodingInferenceSettingsSchema = z.object({
+  enabled: z.boolean(),
+  provider: z.literal('openrouter'),
+  model: z.string().trim().min(1).max(256),
+});
 export const ProviderCredentialSourceSchema = z.enum(['environment', 'system', 'session', 'none']);
 export const ProviderCredentialStatusSchema = z.object({
   provider: ProviderCredentialIdSchema,
@@ -106,21 +152,29 @@ export type AccountBackend = z.infer<typeof AccountBackendSchema>;
 export type AccountPlan = z.infer<typeof AccountPlanSchema>;
 export type AccountCredits = z.infer<typeof AccountCreditsSchema>;
 export type AccountSpendPolicy = z.infer<typeof AccountSpendPolicySchema>;
+export type AccountAlert = z.infer<typeof AccountAlertSchema>;
 export type AccountUser = z.infer<typeof AccountUserSchema>;
 export type AccountOrganization = z.infer<typeof AccountOrganizationSchema>;
 export type AccountOrganizationDomain = z.infer<typeof AccountOrganizationDomainSchema>;
 export type AccountUsageEntry = z.infer<typeof AccountUsageEntrySchema>;
+export type AccountPlanId = z.infer<typeof AccountPlanIdSchema>;
+export type AccountCatalog = z.infer<typeof AccountCatalogSchema>;
 export type AccountSnapshot = z.infer<typeof AccountSnapshotSchema>;
 export type GenerationExecutionRoute = z.infer<typeof GenerationExecutionRouteSchema>;
+export type CodingInferenceSettings = z.infer<typeof CodingInferenceSettingsSchema>;
 export type ProviderCredentialId = z.infer<typeof ProviderCredentialIdSchema>;
 export type ProviderCredentialSource = z.infer<typeof ProviderCredentialSourceSchema>;
 export type ProviderCredentialStatus = z.infer<typeof ProviderCredentialStatusSchema>;
 export type ProviderCredentialTestResult = z.infer<typeof ProviderCredentialTestResultSchema>;
 export type EditorAccountSnapshot = AccountSnapshot & {
+  /** Which identity/payment surface backs this editor session. The in-process
+   * mock value exists only for isolated unit tests. */
+  accountEnvironment: 'test-mock' | 'development-twin' | 'production';
   routes: { mock: true; managed: boolean; byok: boolean; byokProviders: string[] };
   preferredRoute: GenerationExecutionRoute;
   /** Editor-only metadata. Credential values never cross the server boundary. */
   providerCredentials: ProviderCredentialStatus[];
+  codingInference: CodingInferenceSettings;
 };
 export interface GenerationAccountProjection {
   routes: EditorAccountSnapshot['routes'];
@@ -142,6 +196,7 @@ export function generationAccountProjection(
 export const EditorAccountSnapshotSchema: z.ZodType<EditorAccountSnapshot> = z.intersection(
   AccountSnapshotSchema,
   z.object({
+    accountEnvironment: z.enum(['test-mock', 'development-twin', 'production']),
     routes: z.object({
       mock: z.literal(true),
       managed: z.boolean(),
@@ -150,5 +205,6 @@ export const EditorAccountSnapshotSchema: z.ZodType<EditorAccountSnapshot> = z.i
     }),
     preferredRoute: GenerationExecutionRouteSchema,
     providerCredentials: z.array(ProviderCredentialStatusSchema),
+    codingInference: CodingInferenceSettingsSchema,
   }),
 );

package/src/generations.ts

@@ -62,6 +62,9 @@ export const GenerationJobSchema = z.object({
   cancel: GenerationOperationReferenceSchema.optional(),
   accept: GenerationOperationReferenceSchema.optional(),
   acceptedAt: z.string().datetime().optional(),
+  /** Last time a human/agent opened the native result. A later provider
+   * update makes the terminal result unread again without changing status. */
+  readAt: z.string().datetime().optional(),
   provenanceOperationId: z.string().optional(),
   outputPaths: z.array(z.string()).optional(),
 });
@@ -103,6 +106,9 @@ export interface GenerationJobUpdate {
   message?: string;
   billing?: GenerationBilling;
   cancel?: { tool: string; input: unknown };
+  /** `null` withdraws an acceptance action after polling proves that a
+   * successful operation produced no downloadable project output. */
+  accept?: { tool: string; input: unknown } | null;
   accepted?: {
     provenanceOperationId: string;
     outputPaths: string[];

package/src/project/build-discipline.ts

@@ -44,8 +44,8 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { existsSync, readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 
 // ---------------------------------------------------------------------------
 // Shared vocabulary
@@ -146,27 +146,33 @@ function cadenceLine(work: UncommittedWork): string {
  * The escalating stderr line/banner for uncommitted work — pure, driven
  * directly by a test. `null` below NOTICE and whenever there is no batch at
  * all.
+ *
+ * THE TWO TIERS SAY DIFFERENT KINDS OF THING, deliberately. Notice DESCRIBES
+ * (`cadenceLine`): at ten minutes a reader is mid-slice and the useful signal
+ * is the clock. Loud PRESCRIBES: it opens with the imperative and the literal
+ * two commands, because the measured failure is not ignorance of the rule —
+ * three consecutive probes quoted "one commit per slice" back at the reader
+ * and then batch-committed anyway. A banner that restates a rule the reader
+ * already agrees with adds nothing; the one that names the next keystroke is
+ * the one that can change the outcome.
  */
 export function commitCadenceBanner(work: UncommittedWork | null): string | null {
   const tier = commitCadenceTier(work);
   if (!work || tier === 'silent') return null;
   if (tier === 'notice') return cadenceLine(work);
   const age = formatElapsed(work.ageMs);
-  const files = `${work.fileCount} file(s)`;
   return [
     '================================================================',
-    `  UNCOMMITTED WORK FOR ${age.toUpperCase()}`,
+    `  COMMIT NOW — UNCOMMITTED WORK FOR ${age.toUpperCase()}`,
     '================================================================',
-    `  ${files} have been dirty for ${age} with no commit behind them.`,
-    '',
-    '  The bar is ONE COMMIT PER SLICE. A build that lands as a single',
-    '  end-of-run commit cannot be reviewed, bisected, or partially',
-    '  recovered when a later step goes wrong — and a build that reaches',
-    '  this banner is on exactly that path.',
+    '  Commit NOW, one commit per slice (AGENTS.md):',
+    '    git add <your files> && git commit -m "<mechanic>"',
     '',
-    '  Commit what already works now, then keep going:',
-    '    git add <the files of the slice you finished>',
-    '    git commit -m "<the slice>"',
+    `  Uncommitted work is ${age} old across ${work.fileCount} file(s).`,
+    '  A build that lands as a single end-of-run commit cannot be',
+    '  reviewed, bisected, or partially recovered when a later step goes',
+    '  wrong — and a build that reaches this banner is on exactly that',
+    '  path. Commit the slice that already works, then keep going.',
     '================================================================',
   ].join('\n');
 }
@@ -571,3 +577,145 @@ export function advanceTripwireGate(
     gate: { evaluatedAtMs: now, announced: tier },
   };
 }
+
+// ---------------------------------------------------------------------------
+// The gate, across process restarts
+// ---------------------------------------------------------------------------
+
+/**
+ * WHY THE GATE IS ON DISK.
+ *
+ * Measured failure (the "foundry" blind probe, 45 minutes): the commit-cadence
+ * tripwire announced at NOTICE mid-run — `{"tier":"notice","ageMs":679238,
+ * "fileCount":23}` is in that session's journal — and the LOUD step never
+ * announced once across three editor-server restarts, while the agent went on
+ * to batch-commit all 23 files at the end. The gate above is correct and the
+ * process holding it is not: an editor server restarts (a crash, a config
+ * change, `vgai restart`) far more often than a dirty batch resolves, and each
+ * restart re-armed at `announced: 'silent'`, so a batch that had already been
+ * noticed simply got noticed AGAIN at the same tier — never escalated. The
+ * loudest step of the escalation was unreachable by construction for exactly
+ * the builds it exists to catch.
+ *
+ * WHAT IS KEYED, AND WHY IT IS NOT A TIMESTAMP. The persisted record carries a
+ * KEY alongside the announced tier, and a key that differs from the one being
+ * asked about reads as a fresh gate. The key is what "the tripwire went quiet"
+ * means for that tripwire — the same thing the in-memory gate re-arms on:
+ *   - `commit-cadence` — the last commit (`commitCadenceGateKey`). A commit
+ *     lands, the key changes, the next batch is heard from zero.
+ *   - `unplayed-session` — the newest live evidence
+ *     (`unplayedSessionGateKey`). A play happens, the key changes, the clock
+ *     starts over.
+ * `evaluatedAtMs` is deliberately NOT persisted: it is the read cap, a fact
+ * about one process's event rate, and carrying it across a restart would blind
+ * the first minute of the new session for no benefit.
+ */
+
+/** The tripwires with a persisted gate — the same names the session journal
+ *  uses, so a journal line and a gate entry can never disagree about which
+ *  tripwire is meant. */
+export type TripwireName = 'commit-cadence' | 'unplayed-session';
+
+/** One tripwire's persisted state. */
+interface PersistedGate {
+  readonly key: string;
+  readonly announced: TripwireTier;
+}
+
+/**
+ * Where the gate lives, project-relative.
+ *
+ * Under `.vgai/` beside the other machine-local caches (`check-idioms.json`),
+ * and inside a directory `newestSourceMtime` already skips — so the file the
+ * tripwire writes can never read as a source change and make the tripwire cry
+ * wolf on its own output. It is gitignored in the scaffold for the same
+ * reason it must never count: a gate write that dirtied the tree would add a
+ * file to the very `fileCount` it is reporting.
+ */
+export const TRIPWIRE_GATE_PATH = join('.vgai', 'tripwire-gate.json');
+
+function gateFilePath(projectRoot: string): string {
+  return join(projectRoot, TRIPWIRE_GATE_PATH);
+}
+
+/** The whole file, or an empty record. Corrupt, missing, unreadable and
+ *  not-an-object are ONE case: a fresh gate, never a throw. A discipline
+ *  banner that crashed a save would be worse than one that repeated itself. */
+function readGateFile(projectRoot: string): Record<string, PersistedGate> {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(gateFilePath(projectRoot), 'utf-8'));
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    return parsed as Record<string, PersistedGate>;
+  } catch {
+    return {};
+  }
+}
+
+/** Best-effort write. Same rule as the read: never throws. */
+function writeGateFile(projectRoot: string, file: Record<string, PersistedGate>): void {
+  const path = gateFilePath(projectRoot);
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`, 'utf-8');
+  } catch {
+    /* an unwritable project degrades to the in-memory gate */
+  }
+}
+
+/**
+ * The highest tier already announced for `name` under `key` — `silent` when
+ * nothing is recorded, when the file is unreadable, or when the recorded key
+ * is a different one (which is what "the tripwire went quiet" looks like on
+ * disk).
+ */
+export function readAnnouncedTier(
+  projectRoot: string,
+  name: TripwireName,
+  key: string,
+): TripwireTier {
+  const entry = readGateFile(projectRoot)[name];
+  if (!entry || entry.key !== key) return 'silent';
+  return entry.announced in TIER_RANK ? entry.announced : 'silent';
+}
+
+/** The commit-cadence key: the commit the current batch sits on top of.
+ *  A constant outside a work tree — the tripwire is silent there anyway. */
+export function commitCadenceGateKey(projectRoot: string | null): string {
+  if (!projectRoot) return 'no-project';
+  return git(projectRoot, ['rev-parse', 'HEAD'])?.trim() || 'unborn';
+}
+
+/** The unplayed-session key: the newest live evidence this project has, which
+ *  is precisely what makes that tripwire go quiet. */
+export function unplayedSessionGateKey(newestEvidence: number | null): string {
+  return newestEvidence === null ? 'never-played' : String(newestEvidence);
+}
+
+/**
+ * {@link advanceTripwireGate}, with the announced tier read from and written
+ * back to the project — so a crossing announces once per crossing rather than
+ * once per crossing PER PROCESS.
+ *
+ * The in-memory gate is still the caller's: it carries `evaluatedAtMs` (the
+ * read cap) and its own `announced` is folded in as a floor, so a failed write
+ * degrades to the old behavior rather than to a repeating banner. Persistence
+ * rides this call and nothing else — there is no poller, no watcher, and no
+ * second place that touches the file.
+ */
+export function advancePersistedTripwireGate(
+  projectRoot: string,
+  name: TripwireName,
+  key: string,
+  gate: TripwireGate,
+  tier: TripwireTier,
+  now: number,
+): { readonly announce: boolean; readonly gate: TripwireGate } {
+  const onDisk = readAnnouncedTier(projectRoot, name, key);
+  const announced = TIER_RANK[onDisk] > TIER_RANK[gate.announced] ? onDisk : gate.announced;
+  const step = advanceTripwireGate({ evaluatedAtMs: gate.evaluatedAtMs, announced }, tier, now);
+  writeGateFile(projectRoot, {
+    ...readGateFile(projectRoot),
+    [name]: { key, announced: step.gate.announced },
+  });
+  return step;
+}

package/src/project/run-name.ts

@@ -0,0 +1,53 @@
+/**
+ * What a run is CALLED — one owner of the bound, and of the fallback a run
+ * gets when nobody named it.
+ *
+ * WHY THIS EXISTS. `vgai play --name <text>` and `npm run playtest --
+ * '{"name":"…"}'` both exist so a run is findable by what it was testing, and
+ * the measured answer to an optional field is that it stays empty: every play
+ * event in the foundry probe's 45-minute session journal reads `"name":null`.
+ * A label nobody supplies indexes nothing, so the run that DOES know what it
+ * was testing supplies it — a route-targeted playtest is named after its
+ * routes, and a full-suite run is named `playtest`. Nothing is taught and no
+ * habit is required; the default carries the information.
+ *
+ * WHAT STAYS UNNAMED, deliberately: interactive `vgai play` with no `--name`.
+ * A person pressing play is not testing a named thing, and inventing a label
+ * for it would put noise in exactly the directory this makes greppable.
+ *
+ * Pure — no filesystem, no clock. `editor-server.ts`'s `playRunSlug` is the
+ * OTHER half (slugging a name into a filename segment) and reads the same
+ * bound from here, so the two can never disagree about how long a run name
+ * may be.
+ */
+
+/** Bound on a run's name — long enough to stay recognisable in a directory
+ *  listing, short enough that the timestamp beside it is still readable. */
+export const MAX_RUN_NAME = 40;
+
+/** The name a full-suite run gets: it targets no route in particular, and
+ *  "which run was that" is still a question worth being able to answer. */
+export const FULL_SUITE_RUN_NAME = 'playtest';
+
+/**
+ * The name for one playtest run.
+ *
+ * An explicit name always wins — it is the caller saying what this run was,
+ * and no derivation is better informed than that. Otherwise the routes name
+ * it, joined with `+` (a separator that survives being read back as a list,
+ * unlike the `-` that route names themselves use), bounded at
+ * {@link MAX_RUN_NAME}; and a run that named no route is
+ * {@link FULL_SUITE_RUN_NAME}.
+ *
+ * `null` is impossible by construction — every playtest run gets a name — but
+ * an explicit blank/whitespace name is treated as no name at all, the same
+ * case a missing one is.
+ */
+export function derivePlaytestRunName(
+  explicit: string | null | undefined,
+  routes: readonly string[],
+): string {
+  if (typeof explicit === 'string' && explicit.trim() !== '') return explicit.trim();
+  if (routes.length === 0) return FULL_SUITE_RUN_NAME;
+  return routes.join('+').slice(0, MAX_RUN_NAME).replace(/\+$/, '');
+}

package/src/project/session-journal.ts

@@ -32,7 +32,7 @@
  * grows unbounded, which is what an append-only record means.
  */
 
-import { appendFileSync, mkdirSync, readdirSync, unlinkSync } from 'node:fs';
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import type { TripwireTier } from './build-discipline';
 
@@ -101,6 +101,148 @@ export type SessionJournalEvent =
       readonly action: 'start' | 'stop';
       readonly name: string | null;
       readonly logFile: string | null;
+    }
+  /**
+   * THE TRANSPORT ARM. Everything below is one line per transport or
+   * presence fact, and it exists because the journal was BLIND to all of
+   * them: on 2026-08-09 a session refused five `vgai play` commands against
+   * a healthy connected tab and the whole file it left behind was
+   * `session-started` plus validation lines. A relay that can refuse has to
+   * be able to say who it refused, to which tab, and on what evidence.
+   *
+   * Ids are truncated to 8 characters (`clientId8`, `tabId8`, `requestId8`)
+   * — enough to correlate lines within one session, short enough that a
+   * human can scan a column of them. No payload bodies, ever: a state
+   * snapshot or a command argument list would turn an append-only record
+   * into a memory dump.
+   */
+  /** A control connection opened (either transport). */
+  | {
+      readonly kind: 'client-connected';
+      readonly clientId8: string;
+      readonly transport: 'ws' | 'sse';
+      readonly participant: string | null;
+    }
+  /** A control connection closed, and how many pending commands it settled. */
+  | {
+      readonly kind: 'client-disconnected';
+      readonly clientId8: string;
+      readonly transport: 'ws' | 'sse';
+      /** WebSocket close code, or null for SSE (which has none). */
+      readonly code: number | null;
+      readonly reason: string | null;
+      readonly commandsSettled: number;
+    }
+  /** The server granted a socket the duplex control capability. */
+  | { readonly kind: 'duplex-granted'; readonly clientId8: string }
+  /** A command left the relay for one tab's command channel. */
+  | {
+      readonly kind: 'command-relayed';
+      readonly command: string;
+      readonly requestId8: string;
+      readonly tabId8: string | null;
+      readonly clientId8: string | null;
+    }
+  /** The tab said its command listener PICKED THE COMMAND UP. */
+  | { readonly kind: 'command-receipt'; readonly requestId8: string }
+  /** The command settled — by the tab's own answer or by the relay refusing. */
+  | {
+      readonly kind: 'command-result';
+      readonly requestId8: string;
+      readonly ok: boolean;
+      /** Present only when `ok` is false; the refusal/failure text. */
+      readonly error?: string;
+    }
+  /**
+   * The relay HELD a command instead of refusing it: the target tab is
+   * present by heartbeat but its command channel is not carrying right now
+   * (mid-reload, or a channel that has not answered an echo).
+   */
+  | {
+      readonly kind: 'command-held';
+      readonly requestId8: string;
+      readonly tabId8: string;
+      readonly reason: 'no-channel' | 'unacknowledged';
+    }
+  /** The main-thread echo probe over a duplex socket. */
+  | {
+      readonly kind: 'echo-probe';
+      readonly clientId8: string;
+      readonly answered: boolean;
+      readonly waitedMs: number;
+    }
+  /** The blessed tab changed (or was chosen for the first time). */
+  | {
+      readonly kind: 'tab-blessed';
+      readonly tabId8: string;
+      readonly previousTabId8: string | null;
+      readonly reason: 'sticky' | 'oldest' | 'claimed';
+    }
+  /** An extra tab was told to yield. */
+  | { readonly kind: 'tab-yielded'; readonly tabId8: string }
+  /**
+   * PRESENCE, IN TAB VOCABULARY. These five say what the tab table saw, and
+   * they deliberately do NOT use socket words: a socket closing is not a tab
+   * leaving, and that conflation is what produced "editor tab lost —
+   * reopening" against a tab that had never gone anywhere.
+   */
+  /** A tabId beat for the first time. */
+  | {
+      readonly kind: 'tab-appeared';
+      readonly tabId8: string;
+      readonly visibility: 'visible' | 'hidden';
+    }
+  /** Beats stopped arriving for longer than the notice threshold. */
+  | { readonly kind: 'tab-heartbeat-gap'; readonly tabId8: string; readonly sinceMs: number }
+  /** A gap closed — the same tab resumed beating. `gapMs` is its full length. */
+  | { readonly kind: 'tab-gap-closed'; readonly tabId8: string; readonly gapMs: number }
+  /** Same tabId, new epoch: the page reloaded. The tab never left. */
+  | { readonly kind: 'tab-reloaded'; readonly tabId8: string; readonly epochCount: number }
+  /** Absent past its grace: this tab is gone. */
+  | { readonly kind: 'tab-departed'; readonly tabId8: string; readonly absentMs: number }
+  /**
+   * WHAT THE TAB WAS HOLDING WHEN IT DIED WITHOUT A GOODBYE.
+   *
+   * Emitted beside `client-disconnected` on an ABNORMAL close (1006 — the
+   * socket ended with no close frame, which is what a killed renderer process
+   * leaves behind; an ordinary tab close sends one). Measured 2026-08-10: a
+   * game tab's renderer was killed repeatedly at Chrome's undocumented
+   * per-process ceiling and the whole session record said `1006` and nothing
+   * else — the recovery worked perfectly and the CAUSE was unrecorded.
+   *
+   * `census` is the tab's last resource profile and `censusAgeMs` how stale it
+   * was; both null for a tab that never reported one (an older page, a
+   * tunnelled tab). Numbers only — this stays a journal line, not a dump.
+   */
+  | {
+      readonly kind: 'tab-death-profile';
+      readonly tabId8: string;
+      /** The abnormal close code that triggered the line. */
+      readonly code: number;
+      readonly censusAgeMs: number | null;
+      readonly census: {
+        readonly heapUsedMB: number | null;
+        readonly heapLimitMB: number | null;
+        readonly canvases: number;
+        readonly canvasMB: number;
+        readonly textures?: number;
+        readonly geometries?: number;
+        readonly programs?: number;
+      } | null;
+    }
+  /** Two epochs beating under one tabId — "Duplicate Tab" copied sessionStorage. */
+  | { readonly kind: 'tab-duplicated'; readonly tabId8: string }
+  /**
+   * The tab is present (its worker is beating) but its PAGE has never opened
+   * a command channel this page-load. A heartbeat proves the tab exists, not
+   * that the document works — a main thread that died after the inline
+   * bootstrap beats forever and can run nothing. Such a tab is passed over
+   * for blessing and named in the refusal.
+   */
+  | {
+      readonly kind: 'tab-unresponsive';
+      readonly tabId8: string;
+      readonly noChannelForMs: number;
     };
 
 /** A parsed journal line: the event plus when it was appended. */
@@ -194,6 +336,152 @@ export function newestSessionJournal(projectRoot: string): string | null {
   }
 }
 
+/**
+ * The newest journal's last `limit` lines of the requested kinds, oldest first.
+ *
+ * WHY A READER EXISTS AT ALL. The journal was written as a file an agent
+ * "can read at any time", and the measured answer to that invitation was: it
+ * doesn't. The foundry probe's journal held the notice-tier tripwire crossing
+ * that predicted its own end-of-run batch commit, and nothing that agent ran
+ * ever rendered a line of it. So the record grows a RENDERER on the command
+ * agents already poll (`vgai status`) — same principle as the tripwires' own
+ * origin: the mechanism was right and the delivery assumption was false.
+ *
+ * Every failure is the same case — no project, no journal, unreadable file, a
+ * line that will not parse — and it is the empty list, never a throw. A status
+ * command that crashed on a malformed log line would be a worse outcome than
+ * one that says nothing about it.
+ *
+ * The whole file is read, which is what bounds this: a journal is one editor
+ * session's surface-worthy transitions (the happy-path silence rule keeps
+ * clean saves out), the pruner caps how many exist, and the alternative — a
+ * reverse streaming reader over a file measured in kilobytes — is machinery
+ * with nothing to buy.
+ */
+export function readRecentJournalEvents(
+  projectRoot: string,
+  kinds: readonly SessionJournalEvent['kind'][],
+  limit: number,
+): SessionJournalLine[] {
+  const path = newestSessionJournal(projectRoot);
+  if (path === null || limit <= 0) return [];
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf-8');
+  } catch {
+    return [];
+  }
+  const wanted = new Set<string>(kinds);
+  const matched: SessionJournalLine[] = [];
+  for (const line of raw.split('\n')) {
+    if (line === '') continue;
+    let parsed: SessionJournalLine;
+    try {
+      parsed = JSON.parse(line) as SessionJournalLine;
+    } catch {
+      continue; // a torn final line is not a reason to report nothing
+    }
+    if (parsed && typeof parsed === 'object' && wanted.has(parsed.kind)) matched.push(parsed);
+  }
+  return matched.slice(-limit);
+}
+
+/**
+ * One journal line as a scannable terminal line: `HH:MM:SS`, the kind, and
+ * the few facts that line is about.
+ *
+ * ONE OWNER of this rendering, for `sessionJournalPointerLine`'s reason — the
+ * events already have exactly one wording as data, and a second prose form per
+ * caller is how a reader ends up believing there are two records.
+ */
+export function formatJournalLine(line: SessionJournalLine): string {
+  const at = line.at.slice(11, 19);
+  switch (line.kind) {
+    case 'tripwire':
+      return line.tripwire === 'commit-cadence'
+        ? `journal: ${at} tripwire commit-cadence ${line.tier} (${line.fileCount} files, ${Math.round(line.ageMs / 60_000)}m)`
+        : `journal: ${at} tripwire unplayed-session ${line.tier} (${Math.round(line.servingForMs / 60_000)}m)`;
+    case 'validation':
+      return `journal: ${at} validation ${line.ok ? 'ok' : 'FAILED'} ${line.path}`;
+    case 'play':
+      return `journal: ${at} play ${line.action}${line.name === null ? '' : ` [${line.name}]`}`;
+    case 'session-started':
+      return `journal: ${at} session-started pid ${line.pid}`;
+    case 'project-opened':
+      return `journal: ${at} project-opened ${line.project}`;
+    case 'session-shutdown':
+      return `journal: ${at} session-shutdown`;
+    // The TRANSPORT arm. One short line each, and every one of them names the
+    // TAB or the request it is about — a column of ids is how these lines get
+    // correlated, and a paragraph per line is how a reader stops reading.
+    case 'client-connected':
+      return `journal: ${at} client-connected ${line.clientId8} (${line.transport})`;
+    case 'client-disconnected':
+      return `journal: ${at} client-disconnected ${line.clientId8} code ${line.code ?? '-'} settled ${line.commandsSettled}`;
+    case 'duplex-granted':
+      return `journal: ${at} duplex-granted ${line.clientId8}`;
+    case 'command-relayed':
+      return `journal: ${at} command-relayed ${line.command} ${line.requestId8} -> tab ${line.tabId8 ?? 'none'}`;
+    case 'command-receipt':
+      return `journal: ${at} command-receipt ${line.requestId8}`;
+    case 'command-result':
+      return `journal: ${at} command-result ${line.requestId8} ${line.ok ? 'ok' : `FAILED ${line.error ?? ''}`}`;
+    case 'command-held':
+      return `journal: ${at} command-held ${line.requestId8} tab ${line.tabId8} (${line.reason})`;
+    case 'echo-probe':
+      return `journal: ${at} echo-probe ${line.clientId8} ${line.answered ? 'answered' : 'UNANSWERED'} in ${line.waitedMs}ms`;
+    case 'tab-blessed':
+      return `journal: ${at} tab-blessed ${line.tabId8} (${line.reason})`;
+    case 'tab-yielded':
+      return `journal: ${at} tab-yielded ${line.tabId8}`;
+    case 'tab-appeared':
+      return `journal: ${at} tab-appeared ${line.tabId8} (${line.visibility})`;
+    case 'tab-heartbeat-gap':
+      return `journal: ${at} tab-heartbeat-gap ${line.tabId8} ${Math.round(line.sinceMs / 100) / 10}s`;
+    case 'tab-gap-closed':
+      return `journal: ${at} tab-gap-closed ${line.tabId8} after ${Math.round(line.gapMs / 100) / 10}s`;
+    case 'tab-reloaded':
+      return `journal: ${at} tab-reloaded ${line.tabId8} (page load ${line.epochCount})`;
+    case 'tab-departed':
+      return `journal: ${at} tab-departed ${line.tabId8} absent ${Math.round(line.absentMs / 100) / 10}s`;
+    case 'tab-duplicated':
+      return `journal: ${at} tab-duplicated ${line.tabId8}`;
+    case 'tab-unresponsive':
+      return `journal: ${at} tab-unresponsive ${line.tabId8} no channel for ${Math.round(line.noChannelForMs / 1000)}s`;
+    case 'tab-death-profile':
+      return `journal: ${at} tab-death-profile ${line.tabId8} code ${line.code} — ${tabDeathProfileBody(line)}`;
+  }
+}
+
+/** The census half of a `tab-death-profile` line, split out so the switch above
+ *  stays one expression per case. */
+function tabDeathProfileBody(line: SessionJournalEvent & { kind: 'tab-death-profile' }): string {
+  const census = formatTabCensus(line.census);
+  if (line.censusAgeMs === null) return census;
+  return `${census} (sampled ${Math.round(line.censusAgeMs / 100) / 10}s before)`;
+}
+
+/** The resource profile a `tab-death-profile` line and a `vgai status` tab row
+ *  both quote. ONE wording, for `sessionJournalPointerLine`'s reason: two
+ *  phrasings of the same numbers is how a reader ends up believing there are
+ *  two measurements. Renderer counts appear only when the page could read them
+ *  (no mounted render-debug adapter = the words are absent, never a zero). */
+export function formatTabCensus(
+  census: (SessionJournalEvent & { kind: 'tab-death-profile' })['census'],
+): string {
+  if (census === null) return 'no resource census';
+  const parts = [
+    census.heapUsedMB === null
+      ? 'heap n/a'
+      : `heap ${census.heapUsedMB}MB${census.heapLimitMB === null ? '' : `/${census.heapLimitMB}MB`}`,
+    `canvas ${census.canvasMB}MB in ${census.canvases}`,
+  ];
+  if (census.textures !== undefined) parts.push(`tex ${census.textures}`);
+  if (census.geometries !== undefined) parts.push(`geo ${census.geometries}`);
+  if (census.programs !== undefined) parts.push(`prog ${census.programs}`);
+  return parts.join(', ');
+}
+
 /**
  * The ONE wording for "here is the journal" — printed by the editor server's
  * boot block, by `vgai edit`'s ready/detach lines, and by `vgai status`.