@principles/pd-cli 1.143.0 → 1.145.0

package/src/commands/codex-ingest-catchup.ts

@@ -0,0 +1,114 @@
+/**
+ * pd codex ingest catch-up command implementation (Codex Governance Closure
+ * Slice C, PRI-624; SPEC §13/§15 recovery command).
+ *
+ * Performs ONE bounded non-destructive catch-up pass over the workspace's
+ * durable Codex checkpoints: resolves each previously-authenticated rollout
+ * by exact uuid, re-authorizes the transcript path, and resumes the bounded
+ * incremental ingestion from the checkpoint — then feeds any admission
+ * candidates through the same Slice B admission/continuation pass the hook
+ * uses. Flag-off (`codex_conversation_ingestion=false`) performs ZERO
+ * transcript filesystem I/O and reports a structured skip.
+ *
+ * This is the manual-mode counterpart of the Companion worker's catch-up
+ * step (worker cycle step 2); it creates no LLM execution.
+ *
+ * CLI gate compliance:
+ * - cli-1: --json outputs exactly one parseable JSON object on stdout.
+ * - cli-2: exit paths stop execution.
+ * - cli-5/6: skipped/degraded results carry reason + nextAction; nothing is
+ *   mutated on failure (the ingestion seam is transactional per rollout).
+ */
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { catchUpCodexIngestion, type CodexCatchUpResult } from '@principles/codex-adapter';
+
+interface CodexIngestCatchUpOptions {
+  workspace?: string;
+  json?: boolean;
+  maxRollouts?: number;
+}
+
+export interface CodexIngestCatchUpReport {
+  generatedAt: string;
+  host: 'codex';
+  workspace: string;
+  status: 'ok' | 'degraded' | 'skipped';
+  reason?: string;
+  nextAction?: string;
+  rolloutsProcessed: number;
+  remainingLagRollouts: string[];
+  unexaminedRollouts: string[];
+  degradations: string[];
+}
+
+function buildReport(generatedAt: string, workspace: string, result: CodexCatchUpResult): CodexIngestCatchUpReport {
+  if (result.status === 'skipped') {
+    return {
+      generatedAt,
+      host: 'codex',
+      workspace,
+      status: 'skipped',
+      reason: result.reason,
+      nextAction: result.nextAction,
+      rolloutsProcessed: 0,
+      remainingLagRollouts: [],
+      unexaminedRollouts: [],
+      degradations: [],
+    };
+  }
+  const degradations: string[] = [];
+  for (const rollout of result.rollouts) {
+    for (const degradation of rollout.admissionDegradations) {
+      degradations.push(`${rollout.rolloutIdentity}: ${degradation.reason}`);
+    }
+    if (rollout.outcome.status === 'degraded') {
+      degradations.push(`${rollout.rolloutIdentity}: ${rollout.outcome.reason}`);
+    }
+  }
+  return {
+    generatedAt,
+    host: 'codex',
+    workspace,
+    status: result.status,
+    rolloutsProcessed: result.rollouts.length,
+    remainingLagRollouts: [...result.remainingLagRollouts],
+    unexaminedRollouts: [...result.unexaminedRollouts],
+    degradations: degradations.slice(0, 10),
+    ...(degradations.length > 0 && result.status === 'degraded'
+      ? { reason: 'one or more rollouts degraded; committed observations remain durable', nextAction: 'Inspect the per-rollout degradations; re-run catch-up after fixing the underlying condition (Slice D adds the audited quarantine command).' }
+      : {}),
+  };
+}
+
+export async function handleCodexIngestCatchUp(options: CodexIngestCatchUpOptions): Promise<void> {
+  const generatedAt = new Date().toISOString();
+  const workspace = resolveWorkspaceDir(options.workspace);
+
+  const result = await catchUpCodexIngestion({
+    workspaceDir: workspace,
+    env: { CODEX_HOME: process.env.CODEX_HOME },
+    ...(typeof options.maxRollouts === 'number' ? { maxRollouts: options.maxRollouts } : {}),
+  });
+
+  const report = buildReport(generatedAt, workspace, result);
+  if (options.json) {
+    console.log(JSON.stringify(report));
+    if (report.status === 'degraded') process.exitCode = 1;
+    return;
+  }
+
+  const lines = [
+    `Codex ingestion catch-up (${workspace})`,
+    `  status:             ${report.status}`,
+    `  rollouts processed: ${report.rolloutsProcessed}`,
+    `  remaining lag:      ${report.remainingLagRollouts.length}`,
+    `  unexamined (bound): ${report.unexaminedRollouts.length}`,
+  ];
+  for (const degradation of report.degradations) {
+    lines.push(`  degradation: ${degradation}`);
+  }
+  if (report.reason !== undefined) lines.push(`  reason: ${report.reason}`);
+  if (report.nextAction !== undefined) lines.push(`  next action: ${report.nextAction}`);
+  console.log(lines.join('\n'));
+  if (report.status === 'degraded') process.exitCode = 1;
+}

package/src/commands/codex-reconcile.ts

@@ -0,0 +1,84 @@
+/**
+ * pd codex reconcile command implementation (Codex Governance Closure
+ * Slice B, PRI-623; SPEC §13/§20).
+ *
+ * Runs the narrow idempotent reconciliation pass between the governance
+ * admission markers (trajectory.db) and the Runtime V2 task store
+ * (.pd/state.db): creates missing Diagnostician tasks for admitted pains,
+ * repairs task links, retries pending promotion tails, and reports stale
+ * tails — without a background worker (the Slice C Companion worker will
+ * call the same seam).
+ *
+ * CLI gate compliance:
+ * - cli-1: --json outputs exactly one parseable JSON object on stdout.
+ * - cli-2: exit paths stop execution.
+ * - cli-6: degraded results include reason + nextAction.
+ */
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { reconcileGovernanceContinuation } from '@principles/host-runtime';
+
+interface CodexReconcileOptions {
+  workspace?: string;
+  json?: boolean;
+  limit?: number;
+}
+
+export interface CodexReconcileReport {
+  generatedAt: string;
+  host: 'codex';
+  workspace: string;
+  ok: boolean;
+  reason?: string;
+  nextAction?: string;
+  tasksEnsured: number;
+  linksRepaired: number;
+  pendingTails: number;
+  completedTails: number;
+  staleTails: number;
+  degradations: string[];
+}
+
+export async function handleCodexReconcile(options: CodexReconcileOptions): Promise<void> {
+  const generatedAt = new Date().toISOString();
+  const workspace = resolveWorkspaceDir(options.workspace);
+
+  const result = await reconcileGovernanceContinuation({
+    workspaceDir: workspace,
+    ...(typeof options.limit === 'number' ? { limit: options.limit } : {}),
+  });
+
+  const report: CodexReconcileReport = {
+    generatedAt,
+    host: 'codex',
+    workspace,
+    ok: result.ok,
+    tasksEnsured: result.tasksEnsured,
+    linksRepaired: result.linksRepaired,
+    pendingTails: result.pendingTails,
+    completedTails: result.completedTails,
+    staleTails: result.staleTails,
+    degradations: [...result.degradations],
+    ...(result.ok ? {} : { reason: result.reason ?? 'reconciliation_failed', nextAction: result.nextAction ?? 'Inspect the listed degradations; admitted pains and evidence remain durable.' }),
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(report));
+    if (!report.ok) process.exitCode = 1;
+    return;
+  }
+
+  const lines = [
+    `Codex governance reconciliation (${workspace})`,
+    `  tasks ensured:      ${report.tasksEnsured} (links repaired: ${report.linksRepaired})`,
+    `  promotion tails:    pending=${report.pendingTails} completed-now=${report.completedTails} stale=${report.staleTails}`,
+  ];
+  for (const degradation of report.degradations) {
+    lines.push(`  degradation: ${degradation}`);
+  }
+  if (!report.ok) {
+    lines.push(`  reason: ${report.reason}`);
+    lines.push(`  next action: ${report.nextAction}`);
+  }
+  console.log(lines.join('\n'));
+  if (!report.ok) process.exitCode = 1;
+}

package/src/commands/codex-worker.ts

@@ -0,0 +1,174 @@
+/**
+ * pd codex worker command implementation (Codex Governance Closure Slice C,
+ * PRI-624; SPEC §13/§15; ADR-0020 §11.1).
+ *
+ * Runs the Workspace-scoped worker cycle — catch-up → reconciliation → one
+ * Diagnostician execution → one bounded downstream consumer cycle — either
+ * once (manual / Companion-supervised restart mode) or continuously.
+ *
+ * `status` answers the SPEC §15 worker-mode question without executing
+ * anything: `manual_action_required` means no Companion-registered worker
+ * serves this workspace (it is not in the install manifest) and the manual
+ * commands below are the recovery path.
+ *
+ * CLI gate compliance:
+ * - cli-1: --json is restricted to the single-output forms (--once / --status)
+ *   so stdout is exactly one parseable JSON object; continuous mode streams
+ *   human-readable reports instead (review P2).
+ * - cli-2: exit paths stop execution.
+ * - cli-6: paused/degraded modes carry reason + nextAction.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveWorkspaceDir } from '../resolve-workspace.js';
+import { runCodexWorkspaceWorkerCycle, type CodexWorkerCycleResult } from '@principles/codex-adapter';
+import { getInstallLayoutPaths, parseInstallManifest } from '@principles/install-layout';
+
+const DEFAULT_INTERVAL_MS = 120_000;
+
+interface CodexWorkerOptions {
+  workspace?: string;
+  json?: boolean;
+  once?: boolean;
+  intervalMs?: number;
+  status?: boolean;
+}
+
+export interface CodexWorkerStatusReport {
+  generatedAt: string;
+  host: 'codex';
+  workspace: string;
+  mode: 'ready' | 'manual_action_required' | 'paused' | 'degraded';
+  registeredInInstallManifest: boolean;
+  reason?: string;
+  nextAction?: string;
+}
+
+async function printStatusReport(workspace: string, json: boolean): Promise<void> {
+  const generatedAt = new Date().toISOString();
+  const paths = getInstallLayoutPaths(os.homedir());
+  let registered = false;
+  let manifestError: string | undefined;
+  try {
+    const raw = JSON.parse(fs.readFileSync(paths.manifest, 'utf8')) as unknown;
+    const parsed = parseInstallManifest(raw);
+    if (parsed.manifest !== undefined) {
+      registered = parsed.manifest.workspaces?.some((entry) => path.resolve(entry) === path.resolve(workspace)) ?? false;
+    } else {
+      manifestError = parsed.error;
+    }
+  } catch {
+    manifestError = 'install_manifest_unreadable';
+  }
+
+  // The status scan itself delegates mode computation to the cycle module's
+  // flag/config semantics by running a paused-compatible evaluation: a real
+  // cycle is NOT run (no execution, no lease, no transcript I/O).
+  const { computeCodexWorkerStatusMode } = await import('@principles/codex-adapter');
+  const evaluation = computeCodexWorkerStatusMode({ workspaceDir: workspace, registeredInInstallManifest: registered });
+
+  const report: CodexWorkerStatusReport = {
+    generatedAt,
+    host: 'codex',
+    workspace,
+    mode: evaluation.mode,
+    registeredInInstallManifest: registered,
+    ...(evaluation.reason !== undefined ? { reason: evaluation.reason } : {}),
+    ...(evaluation.nextAction !== undefined ? { nextAction: evaluation.nextAction } : {}),
+    ...(manifestError !== undefined ? { reason: `${evaluation.reason ?? manifestError}` } : {}),
+  };
+  if (json) {
+    console.log(JSON.stringify(report));
+    return;
+  }
+  const lines = [
+    `Codex workspace worker status (${workspace})`,
+    `  mode: ${report.mode}`,
+    `  registered in install manifest: ${registered}`,
+  ];
+  if (report.reason !== undefined) lines.push(`  reason: ${report.reason}`);
+  if (report.nextAction !== undefined) lines.push(`  next action: ${report.nextAction}`);
+  console.log(lines.join('\n'));
+  if (report.mode === 'degraded') process.exitCode = 1;
+}
+
+function printCycleReport(result: CodexWorkerCycleResult, json: boolean): void {
+  if (json) {
+    console.log(JSON.stringify(result));
+    return;
+  }
+  const lines = [
+    `Codex workspace worker (${result.workspaceDir})`,
+    `  mode: ${result.mode}${result.reason !== undefined ? ` (${result.reason})` : ''}`,
+  ];
+  if (result.report !== undefined) {
+    const {catchUp} = result.report;
+    const catchUpSummary = catchUp.status === 'skipped' ? `skipped (${catchUp.reason})` : `${catchUp.status} — processed=${catchUp.rollouts.length} lag=${catchUp.remainingLagRollouts.length}`;
+    lines.push(`  catch-up:    ${catchUpSummary}`);
+    lines.push(`  reconcile:   ok=${result.report.reconcile.ok} ensured=${result.report.reconcile.tasksEnsured} linksRepaired=${result.report.reconcile.linksRepaired}`);
+    if (result.report.diagnostician !== null) {
+      lines.push(`  diagnostician: ${result.report.diagnostician.status} (${result.report.diagnostician.taskId})`);
+    } else {
+      lines.push('  diagnostician: none pending');
+    }
+    if (result.report.downstream !== null) {
+      lines.push(`  downstream:  ran=${result.report.downstream.ran}${result.report.downstream.taskKind !== undefined ? ` kind=${result.report.downstream.taskKind}` : ''}${result.report.downstream.skipReason !== undefined ? ` skip=${result.report.downstream.skipReason}` : ''}`);
+    }
+  }
+  if (result.nextAction !== undefined) lines.push(`  next action: ${result.nextAction}`);
+  console.log(lines.join('\n'));
+}
+
+export async function handleCodexWorker(options: CodexWorkerOptions): Promise<void> {
+  // cli-1: continuous mode streams one report per cycle — that is NOT one
+  // parseable JSON document. --json is only valid for the single-output
+  // forms (--once / --status), enforced here (review P2).
+  if (options.json === true && options.once !== true && options.status !== true) {
+    const error = {
+      generatedAt: new Date().toISOString(),
+      host: 'codex',
+      error: 'cli_contract',
+      reason: 'json_without_once_or_status',
+      nextAction: 'Use --json with --once (single cycle) or --status (no-op scan); continuous mode streams human-readable reports instead.',
+    };
+    console.log(JSON.stringify(error));
+    process.exitCode = 1;
+    return;
+  }
+
+  const workspace = resolveWorkspaceDir(options.workspace);
+
+  if (options.status === true) {
+    await printStatusReport(workspace, options.json === true);
+    return;
+  }
+
+  if (options.once === true) {
+    const result = await runCodexWorkspaceWorkerCycle({ workspaceDir: workspace, env: { CODEX_HOME: process.env.CODEX_HOME } });
+    printCycleReport(result, options.json === true);
+    if (result.mode === 'degraded') process.exitCode = 1;
+    return;
+  }
+
+  const interval = typeof options.intervalMs === 'number' && options.intervalMs >= 1000 ? options.intervalMs : DEFAULT_INTERVAL_MS;
+  let stopped = false;
+  const onSignal = (): void => {
+    stopped = true;
+  };
+  process.on('SIGINT', onSignal);
+  process.on('SIGTERM', onSignal);
+  try {
+    while (!stopped) {
+      const result = await runCodexWorkspaceWorkerCycle({ workspaceDir: workspace, env: { CODEX_HOME: process.env.CODEX_HOME } });
+      printCycleReport(result, false);
+      if (stopped) break;
+      await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+  } finally {
+    process.off('SIGINT', onSignal);
+    process.off('SIGTERM', onSignal);
+  }
+}
+
+/** SPEC §15 worker mode, evaluated without executing anything. */

package/src/commands/console.ts

@@ -369,7 +369,8 @@ export async function handleConsoleOpen(opts: ConsoleOpenOptions = {}): Promise<
   }
 
   // 4) Read auth token for health probes (PD_CONSOLE_TOKEN)
-  const token = opts.token ?? process.env.PD_CONSOLE_TOKEN;
+  const rawToken = opts.token ?? process.env.PD_CONSOLE_TOKEN;
+  const token = !opts.noAuth && rawToken?.trim() ? rawToken.trim() : undefined;
 
   // 5) Plan the launch (reuse or fresh bind)
   let plan;
@@ -461,6 +462,7 @@ export async function handleConsoleOpen(opts: ConsoleOpenOptions = {}): Promise<
       workspaceDir,
       reused: true,
       browserOpened,
+      ...(health.authenticationMode ? { authenticationMode: health.authenticationMode } : {}),
       nextAction: browserOpened
         ? 'Browser opened to the running Console.'
         : `Open ${plan.url} in your browser to access the Console.`,
@@ -535,10 +537,15 @@ export async function handleConsoleOpen(opts: ConsoleOpenOptions = {}): Promise<
   // 7) Wait for console ready (bounded poll)
   const readyDeadline = Date.now() + 15_000;
   let ready = false;
+  let readyAuthenticationMode: 'authenticated' | 'no_auth' | undefined;
   while (Date.now() < readyDeadline) {
     if (child.exitCode !== null) break;
     const h = await probeConsoleHealth({ host: plan.host, port: plan.port, timeoutMs: 1000, token });
-    if (h.healthy) { ready = true; break; }
+    if (h.healthy) {
+      ready = true;
+      readyAuthenticationMode = h.authenticationMode;
+      break;
+    }
     await sleep(250);
   }
 
@@ -587,6 +594,31 @@ export async function handleConsoleOpen(opts: ConsoleOpenOptions = {}): Promise<
     return;
   }
 
+  const expectedAuthenticationMode = token?.trim() ? 'authenticated' : 'no_auth';
+  if (readyAuthenticationMode !== expectedAuthenticationMode) {
+    try { child.kill('SIGTERM'); } catch { /* child may already have exited */ }
+    const result: ConsoleLaunchResult = {
+      status: 'refused',
+      url: '',
+      port: plan.port,
+      host: plan.host,
+      workspaceDir,
+      reused: false,
+      browserOpened: false,
+      authenticationMode: readyAuthenticationMode,
+      reason: 'console_authentication_mode_mismatch',
+      nextAction: 'Stop the Console, verify PD_CONSOLE_TOKEN propagation, and retry.',
+    };
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error(`error: ${result.reason}`);
+      console.error(`next:   ${result.nextAction}`);
+    }
+    process.exit(1);
+    return;
+  }
+
   // 7) Console is ready → optionally open browser, emit result, then keep child running
   let browserOpened = false;
   let browserWarning: string | undefined;
@@ -604,6 +636,7 @@ export async function handleConsoleOpen(opts: ConsoleOpenOptions = {}): Promise<
     workspaceDir,
     reused: false,
     browserOpened,
+    ...(readyAuthenticationMode ? { authenticationMode: readyAuthenticationMode } : {}),
     nextAction: browserOpened
       ? 'Browser opened to the Console. Press Ctrl+C to stop.'
       : `Open ${plan.url} in your browser. Press Ctrl+C to stop.`,

package/src/commands/pain-retry.ts

@@ -183,10 +183,12 @@ function parsePainDetectedData(value: unknown):
   }
   if (Object.hasOwn(obj, 'provenance')) {
     const prov = obj.provenance;
-    if (prov !== 'openclaw_context_bound' && prov !== 'owner_reported_no_host_trace' && prov !== 'automatic_hook') {
+    // host_context_bound is the current value (SPEC §12); the legacy
+    // openclaw_context_bound spelling remains valid for replay of old dead letters.
+    if (prov !== 'host_context_bound' && prov !== 'openclaw_context_bound' && prov !== 'owner_reported_no_host_trace' && prov !== 'automatic_hook') {
       return { valid: false, error: `painData.provenance is not a known literal (got ${JSON.stringify(prov)})` };
     }
-    data.provenance = prov;
+    data.provenance = prov === 'openclaw_context_bound' ? 'host_context_bound' : prov;
   }
   if (Object.hasOwn(obj, 'evidence')) {
     if (!Array.isArray(obj.evidence)) {

package/src/index.ts

@@ -563,6 +563,81 @@ runtimeHealthCmd
     await handleRuntimeHealthSnapshot({ workspace: opts.workspace, json: opts.json });
   });
 
+// ── pd codex reconcile — Codex governance continuation recovery ───────────────
+// Codex Governance Closure Slice B (PRI-623, SPEC §13/§20): runs the idempotent
+// cross-store reconciliation pass (admitted pain → missing Diagnostician task,
+// task-before-link, pending promotion tails) exposed for the CLI now and the
+// Slice C Companion worker later.
+const codexCmd = program
+  .command('codex')
+  .description('Codex host governance operations');
+
+codexCmd
+  .command('reconcile')
+  .description('Reconcile admitted Codex pains with Diagnostician tasks and promotion tails (idempotent)')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--limit <n>', 'Maximum admitted pains to reconcile per pass (1-200, default 50)')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    const { handleCodexReconcile } = await import('./commands/codex-reconcile.js');
+    const limit = typeof opts.limit === 'string' ? Number.parseInt(opts.limit, 10) : undefined;
+    await handleCodexReconcile({
+      workspace: opts.workspace,
+      json: opts.json === true,
+      ...(limit !== undefined && Number.isInteger(limit) ? { limit } : {}),
+    });
+  });
+
+// ── pd codex ingest catch-up — bounded manual transcript lag recovery ────────
+// Codex Governance Closure Slice C (PRI-624, SPEC §15): the manual-mode
+// counterpart of the Companion worker's catch-up step. Zero transcript I/O
+// when codex_conversation_ingestion is disabled.
+const codexIngestCmd = codexCmd
+  .command('ingest')
+  .description('Codex conversation-ingestion operations');
+
+codexIngestCmd
+  .command('catch-up')
+  .description('Catch up transcript lag from durable checkpoints (bounded, non-destructive, no LLM)')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--max-rollouts <n>', 'Maximum rollouts to catch up per pass (1-32, default 8)')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    const { handleCodexIngestCatchUp } = await import('./commands/codex-ingest-catchup.js');
+    const maxRollouts = typeof opts.maxRollouts === 'string' ? Number.parseInt(opts.maxRollouts, 10) : undefined;
+    await handleCodexIngestCatchUp({
+      workspace: opts.workspace,
+      json: opts.json === true,
+      ...(maxRollouts !== undefined && Number.isInteger(maxRollouts) ? { maxRollouts } : {}),
+    });
+  });
+
+// ── pd codex worker — Workspace-scoped governance worker ─────────────────────
+// Codex Governance Closure Slice C (PRI-624, SPEC §13; ADR-0020 §11.1): the
+// one Owner-approved background worker (catch-up → reconciliation → one
+// Diagnostician execution → one bounded downstream consumer cycle). The
+// Companion spawns this per registered workspace; --once is the manual and
+// supervised-restart form.
+codexCmd
+  .command('worker')
+  .description('Run the Codex workspace governance worker (catch-up, reconciliation, diagnostician, downstream)')
+  .option('-w, --workspace <path>', 'Workspace directory')
+  .option('--once', 'Run exactly one bounded cycle and exit')
+  .option('--interval <ms>', 'Cycle interval for continuous mode (default 120000, minimum 1000)')
+  .option('--status', 'Report the SPEC §15 worker mode without executing anything')
+  .option('--json', 'Output raw JSON')
+  .action(async (opts) => {
+    const { handleCodexWorker } = await import('./commands/codex-worker.js');
+    const intervalMs = typeof opts.interval === 'string' ? Number.parseInt(opts.interval, 10) : undefined;
+    await handleCodexWorker({
+      workspace: opts.workspace,
+      json: opts.json === true,
+      once: opts.once === true,
+      status: opts.status === true,
+      ...(intervalMs !== undefined && Number.isInteger(intervalMs) ? { intervalMs } : {}),
+    });
+  });
+
 runtimeHealthCmd
   .command('gfi')
   .description('GFI workspace snapshot — active vs stale session breakdown')

package/src/services/console-launcher.ts

@@ -21,6 +21,7 @@ import * as http from 'http';
 // ─── Public types ────────────────────────────────────────────────────────────
 
 export type ConsoleStatus = 'reused' | 'started' | 'failed' | 'refused';
+export type ConsoleAuthenticationMode = 'authenticated' | 'no_auth';
 
 export interface ConsoleLaunchResult {
   status: ConsoleStatus;
@@ -34,6 +35,8 @@ export interface ConsoleLaunchResult {
   reused: boolean;
   /** True when a browser should/has been opened (skipped in --json mode). */
   browserOpened: boolean;
+  /** Verified for successful launch/reuse; omitted when no server was reached. */
+  authenticationMode?: ConsoleAuthenticationMode;
   /**
    * PID of the freshly spawned console server process. Present only when
    * status === 'started'; absent on 'reused' (the server was started by
@@ -58,6 +61,10 @@ const DEFAULT_PORT = 3100;
 const DEFAULT_HOST = '127.0.0.1';
 const PORT_FALLBACK_LIMIT = 20; // try 3100..3119 before giving up
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 // ─── Loopback safety (ERR-049) ──────────────────────────────────────────────
 
 /** Returns true if the host resolves to a loopback address. */
@@ -138,13 +145,20 @@ export interface HealthProbeOptions {
 }
 
 /** Probe a port to see if it serves a healthy PD Console. */
-export async function probeConsoleHealth(opts: HealthProbeOptions): Promise<{ healthy: boolean; reason?: string }> {
+export interface ConsoleHealthProbeResult {
+  healthy: boolean;
+  authenticationMode?: ConsoleAuthenticationMode;
+  reason?: string;
+  failureKind?: 'unauthorized' | 'invalid_response' | 'unreachable';
+}
+
+export async function probeConsoleHealth(opts: HealthProbeOptions): Promise<ConsoleHealthProbeResult> {
   const { host, port, timeoutMs = 1500, token } = opts;
 
   if (Object.hasOwn(globalThis, '__mockProbeConsoleHealth')) {
     const mock = Reflect.get(globalThis, '__mockProbeConsoleHealth') as (
       o: HealthProbeOptions
-    ) => Promise<{ healthy: boolean; reason?: string }>;
+    ) => Promise<ConsoleHealthProbeResult>;
     return mock(opts);
   }
   return new Promise((resolve) => {
@@ -157,7 +171,7 @@ export async function probeConsoleHealth(opts: HealthProbeOptions): Promise<{ he
       (res) => {
         // 401 means auth required — treat as unhealthy, not a generic error
         if (res.statusCode === 401) {
-          resolve({ healthy: false, reason: 'console health endpoint returned 401 (unauthorized) — check PD_CONSOLE_TOKEN' });
+          resolve({ healthy: false, failureKind: 'unauthorized', reason: 'console health endpoint returned 401 (unauthorized) — check PD_CONSOLE_TOKEN' });
           return;
         }
         if (res.statusCode !== 200) {
@@ -170,13 +184,19 @@ export async function probeConsoleHealth(opts: HealthProbeOptions): Promise<{ he
         });
         res.on('end', () => {
           try {
-            const body = JSON.parse(data) as unknown;
-            if (body && typeof body === 'object') {
+            const body: unknown = JSON.parse(data);
+            if (isRecord(body)) {
               const isHealthy =
                 (Object.hasOwn(body, 'healthy') && Reflect.get(body, 'healthy') === true) ||
                 (Object.hasOwn(body, 'success') && Reflect.get(body, 'success') === true);
               if (isHealthy) {
-                resolve({ healthy: true });
+                const dataValue = Object.hasOwn(body, 'data') ? Reflect.get(body, 'data') : undefined;
+                const payloadRecord = isRecord(dataValue) ? dataValue : body;
+                const mode = Reflect.get(payloadRecord, 'authenticationMode');
+                resolve({
+                  healthy: true,
+                  ...(mode === 'authenticated' || mode === 'no_auth' ? { authenticationMode: mode } : {}),
+                });
               } else {
                 resolve({ healthy: false, reason: 'console health JSON was missing healthy/success markers' });
               }
@@ -387,6 +407,17 @@ export async function planConsoleLaunch(input: OrchestratorInput): Promise<Orche
   // Step 1: Is there already a healthy console on the preferred port?
   const health = await probeConsoleHealth({ host, port: preferredPort, token });
   if (health.healthy) {
+    if (token && health.authenticationMode !== 'authenticated') {
+      return {
+        status: 'refused',
+        url: '',
+        port: preferredPort,
+        host,
+        reused: false,
+        reason: 'console_authentication_mode_mismatch',
+        nextAction: `Stop the Console on port ${preferredPort}, then retry so Companion can start an authenticated Console.`,
+      };
+    }
     return {
       status: 'reused',
       url: buildConsoleUrl(host, preferredPort),
@@ -396,6 +427,18 @@ export async function planConsoleLaunch(input: OrchestratorInput): Promise<Orche
     };
   }
 
+  if (token && health.failureKind === 'unauthorized') {
+    return {
+      status: 'refused',
+      url: '',
+      port: preferredPort,
+      host,
+      reused: false,
+      reason: 'console_authentication_failed',
+      nextAction: 'Verify PD_CONSOLE_TOKEN matches the running Console, stop that Console, then retry.',
+    };
+  }
+
   // Step 2: Is the preferred port simply occupied by something else?
   const preferredInUse = await isPortInUse(host, preferredPort);