totemlayer 0.1.17 → 0.1.19

package/README.md

@@ -18,6 +18,8 @@ Totem detects an installed, signed-in Codex or Claude Code client, an installed
 
 The listener runs independently of the terminal, restarts after failure, and resumes after login on macOS, Linux user-service hosts, and Windows. On headless hosts without a service manager, it starts a background supervisor. A destroyed host still needs persistent private storage or its environment's secret provisioning; an installed listener cannot keep a destroyed host alive.
 
+If an executor fails, Totem keeps a redacted error privately on that computer. Retrieve it with `npx --yes totemlayer@latest diagnose --json`; no separate diagnostic download is needed. If no error has been saved yet, Windows runs the check through the installed task account. `--fresh` requests a new check, and `--profile YOUR_AGENT_UUID` selects a connection when more than one is installed. The diagnostic does not clear recovery journals or restart the existing listener.
+
 ```sh
 npx totemlayer@latest status --profile YOUR_AGENT_UUID
 npx totemlayer@latest stop --profile YOUR_AGENT_UUID

package/bin/agent-runner.mjs

@@ -1,7 +1,7 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { constants } from "node:fs";
-import { lstat, mkdir, open, opendir, rename, unlink } from "node:fs/promises";
+import { lstat, mkdir, open, opendir, rename, unlink, readFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, parse, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
@@ -11,6 +11,9 @@ import { localClientEnvironment } from "./platform-client.mjs";
 import { Totem } from "./sdk/index.js";
 import { RUNTIME_ERROR_CODES, runtimeErrorCode } from "./runtime-diagnostics.mjs";
 
+const PACKAGE_VERSION = JSON.parse(
+  await readFile(new URL("../package.json", import.meta.url), "utf8"),
+).version;
 const CLI_PATH = fileURLToPath(new URL("./totem.mjs", import.meta.url));
 const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
 const PHASES = new Set([
@@ -230,6 +233,7 @@ export async function readAgentRuntimeStatus(profile, { isAlive = alive, now = D
         ? record.phase
         : "interrupted",
     runId: record.runId,
+    ...(typeof record.packageVersion === "string" ? { packageVersion: record.packageVersion } : {}),
     updatedAt: record.updatedAt,
     ...(RUNTIME_ERROR_CODES.has(record.blockerCode) ? { blockerCode: record.blockerCode } : {}),
     ...(UUID.test(record.missionId ?? "") ? { missionId: record.missionId } : {}),
@@ -287,6 +291,7 @@ export async function runAgentSession(profile, options = {}) {
   if (options.signal?.aborted) controller.abort();
   let status = {
     version: 1,
+    packageVersion: PACKAGE_VERSION,
     runId,
     pid: process.pid,
     agentId: profile.agentId,
@@ -394,6 +399,7 @@ export async function runAgentSession(profile, options = {}) {
             .filter((key) => profile[key] !== undefined)
             .map((key) => [key, profile[key]]),
         ),
+        diagnosticDirectory: profile.stateDirectory,
         ollamaUrl: profile.ollamaUrl,
         nimUrl: profile.nimUrl,
         qwenUrl: profile.qwenUrl,
@@ -442,7 +448,7 @@ function runnerOptions(args) {
   return parsed.values;
 }
 
-async function requestStop(profile, runId) {
+export async function requestStop(profile, runId) {
   if (!UUID.test(runId)) throw new Error("Invalid agent run identifier.");
   const directory = await runtimeDirectory(profile, true);
   const path = join(directory, `${runId}.stop`);

package/bin/automatic-runtime.mjs

@@ -1,9 +1,9 @@
-import { opendir, rm } from "node:fs/promises";
+import { opendir, rm, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import { readAgentProfile } from "./agent-profile.mjs";
-import { agentStartMain, readAgentRuntimeStatus } from "./agent-runner.mjs";
+import { agentStartMain, readAgentRuntimeStatus, requestStop } from "./agent-runner.mjs";
 import {
   privateDirectory,
   privateRead,
@@ -12,6 +12,10 @@ import {
 } from "./runtime-installation.mjs";
 import { resumeDeviceLogin } from "./device-login.mjs";
 
+const PACKAGE_VERSION = JSON.parse(
+  await readFile(new URL("../package.json", import.meta.url), "utf8"),
+).version;
+
 export async function setAutomaticEnabled(profile, enabled) {
   await privateWrite(join(profile.stateDirectory, "automatic.json"), { enabled });
 }
@@ -42,7 +46,22 @@ export async function superviseOnce(env = process.env, options = {}) {
       const profile = await readAgentProfile(entry.name, { environment: env });
       if (!(await automaticEnabled(profile))) continue;
       const state = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
-      if (state.running) continue;
+      if (state.running) {
+        if (state.packageVersion === (options.packageVersion ?? PACKAGE_VERSION)) continue;
+        // Finish active work before upgrading. Never overlap two workers or clear journals.
+        if (!["connected", "waiting", "blocked", "reconnecting"].includes(state.phase)) continue;
+        await (options.stop ?? requestStop)(profile, state.runId);
+        const deadline = Date.now() + (options.stopTimeoutMs ?? 10000);
+        let stopped = false;
+        while (Date.now() < deadline) {
+          if (!(await (options.readStatus ?? readAgentRuntimeStatus)(profile)).running) {
+            stopped = true;
+            break;
+          }
+          await sleep(100);
+        }
+        if (!stopped || !(await automaticEnabled(profile))) continue;
+      }
       // The run-local journal decides whether any interrupted work can safely resume.
       await (options.start ?? agentStartMain)(["--profile", entry.name, "--background", "--json"], {
         env,

package/bin/connected-agent-service.mjs

@@ -32,6 +32,7 @@ export async function runConnectedAgentService(settings, dependencies = {}) {
           signal,
           stateDir: settings.stateDirectory,
           allowAgents: [],
+          adapterSettings: { ...settings.adapterSettings, diagnosticDirectory: settings.diagnosticDirectory },
           modelTimeoutMs: 900000,
           replyTimeoutMs: 90000,
           pollMs: settings.pollMs ?? 5000,

package/bin/executor-diagnostic.mjs

@@ -0,0 +1,204 @@
+// Standalone support probe: use the installed Totem adapter without reading
+// its connection key, changing its listener, or touching its work journal.
+import childProcess from "node:child_process";
+import { syncBuiltinESMExports } from "node:module";
+import { promisify } from "node:util";
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, readdir, copyFile, writeFile, rename, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve, dirname, basename } from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+import { setTimeout as sleep } from "node:timers/promises";
+
+async function installedModules(root) {
+  const pointer = JSON.parse(await readFile(join(root, "runtime", "current.json"), "utf8"));
+  if (!/^\d+\.\d+\.\d+$/.test(pointer.version)) throw Error("Invalid installed version");
+  const bin = join(root, "runtime-packages", pointer.version, "node_modules", "totemlayer", "bin");
+  const helpers = await import(pathToFileURL(join(bin, "runtime-installation.mjs")));
+  return { pointer, bin, ...helpers };
+}
+
+async function selectedProfile(root, profileName) {
+  const { privateRead } = await installedModules(root);
+  const names = profileName ? [profileName] : (await readdir(join(root, "connections"), { withFileTypes: true }))
+    .filter(entry => entry.isDirectory()).map(entry => entry.name);
+  const profiles = [];
+  for (const name of names) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) throw Error("Invalid profile name");
+    profiles.push(await privateRead(join(root, "connections", name, "profile.json")));
+  }
+  if (profiles.length !== 1) throw Error("Choose exactly one connection with --profile NAME");
+  return profiles[0];
+}
+
+// Task Scheduler starts this one-shot probe with the installed service's account,
+// rather than inheriting the working interactive terminal's provider environment.
+export async function diagnoseBackground({
+  root = process.env.TOTEM_CONFIG_DIR ?? join(homedir(), ".totem"), profileName,
+} = {}) {
+  if (process.platform !== "win32") throw Error("This probe requires Windows Task Scheduler");
+  const { privateDirectory, privateRead } = await installedModules(root);
+  const id = randomUUID();
+  const directory = join(root, "runtime", "executor-probes", id);
+  await privateDirectory(directory);
+  const entry = join(directory, "diagnose-executor.mjs");
+  const reportPath = join(directory, "report.json");
+  const receipt = join(directory, "registered.json");
+  await copyFile(fileURLToPath(import.meta.url), entry);
+  const task = `TotemExecutorProbe-${id}`;
+  const suffix = resolve(root) === resolve(join(homedir(), ".totem")) ? "" :
+    `.${createHash("sha256").update(root).digest("hex").slice(0, 12)}`;
+  const service = `TotemRuntime${suffix}`;
+  const literal = value => `'${String(value).replaceAll("'", "''")}'`;
+  const argumentsText = `"${entry}" --report-file "${reportPath}"` +
+    (profileName ? ` --profile "${profileName}"` : "");
+  if (profileName && !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(profileName)) throw Error("Invalid profile name");
+  const script = `$ErrorActionPreference='Stop'
+$source=Get-ScheduledTask -TaskName ${literal(service)}
+$owner=$source.Principal.UserId
+if ($owner -like 'S-1-*') { $sid=[Security.Principal.SecurityIdentifier]::new($owner) }
+else { $sid=[Security.Principal.NTAccount]::new($owner).Translate([Security.Principal.SecurityIdentifier]) }
+if ($sid.Value -ne [Security.Principal.WindowsIdentity]::GetCurrent().User.Value) { throw 'The service belongs to another user' }
+$action=New-ScheduledTaskAction -Execute ${literal(process.execPath)} -Argument ${literal(argumentsText)}
+$settings=New-ScheduledTaskSettingsSet -ExecutionTimeLimit (New-TimeSpan -Minutes 2)
+Register-ScheduledTask -TaskName ${literal(task)} -Action $action -Principal $source.Principal -Settings $settings | Out-Null
+[IO.File]::WriteAllText(${literal(receipt)},'{}')
+Start-ScheduledTask -TaskName ${literal(task)}`;
+  const run = promisify(childProcess.execFile);
+  const powershell = source => run("powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand",
+    Buffer.from(source, "utf16le").toString("base64")], { windowsHide: true, timeout: 30000, maxBuffer: 65536 });
+  try {
+    await powershell(script);
+    const deadline = Date.now() + 90000;
+    while (Date.now() < deadline) {
+      try { return { context: "windows-scheduled-task", ...await privateRead(reportPath) }; }
+      catch (error) { if (error.code !== "ENOENT") throw error; }
+      await sleep(250);
+    }
+    return { ok: false, code: "BACKGROUND_PROBE_TIMEOUT" };
+  } finally {
+    try {
+      await readFile(receipt);
+      await powershell(`$ErrorActionPreference='Stop';Stop-ScheduledTask -TaskName ${literal(task)} -ErrorAction SilentlyContinue;Unregister-ScheduledTask -TaskName ${literal(task)} -Confirm:$false -ErrorAction SilentlyContinue`);
+    } catch { /* Never modify the installed service or any task without our receipt. */ }
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+export async function diagnoseExecutor({
+  root = process.env.TOTEM_CONFIG_DIR ?? join(homedir(), ".totem"),
+  profileName,
+  environment = process.env,
+} = {}) {
+  const { pointer, bin, privateRead } = await installedModules(root);
+  const profile = await selectedProfile(root, profileName);
+  const provider = profile.client ?? profile.provider;
+  const model = profile.client && profile.provider === "qwen-local" ? "default" : profile.model;
+  let saved = {}, secrets = {};
+  for (const [file, target] of [["environment.json", saved], ["provider-environment.json", secrets]]) {
+    try { Object.assign(target, await privateRead(join(root, "runtime", file))); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+  }
+  const providerEnvironment = { ...environment, ...saved, ...secrets };
+  const secretValues = Object.entries(providerEnvironment)
+    .filter(([key, value]) => /secret|token|password|api.?key|db.?pass/i.test(key) && typeof value === "string" && value.length >= 4)
+    .map(([, value]) => value);
+  const redact = value => {
+    let text = String(value);
+    for (const secret of secretValues) text = text.split(secret).join("[REDACTED]");
+    return text.replace(/\b(?:tn_(?:live|test)_[A-Za-z0-9_-]+|sk-[A-Za-z0-9_-]+|eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)\b/g, "[REDACTED]")
+      .replace(/(Bearer\s+)[^\s"']+/gi, "$1[REDACTED]")
+      .replace(/(https?:\/\/)[^\s\/@]+@/gi, "$1[REDACTED]@")
+      .slice(-6000);
+  };
+  const originalSpawn = childProcess.spawn;
+  const launches = [];
+  childProcess.spawn = function (command, args, options) {
+    const record = { command: redact(command), stderr: "", stdout: "" };
+    launches.push(record);
+    const child = originalSpawn.call(this, command, args, options);
+    for (const name of ["stdout", "stderr"]) child[name]?.on("data", data => {
+      record[name] = (record[name] + data.toString("utf8")).slice(-32000);
+    });
+    child.once("close", code => { record.exitCode = code; });
+    return child;
+  };
+  syncBuiltinESMExports();
+  let ok = false, code;
+  try {
+    const { modelReply } = await import(pathToFileURL(join(bin, "network-runtime.mjs")));
+    const response = await modelReply({ provider, model, origin: profile.ollamaUrl ?? "http://127.0.0.1:11434",
+      qwenUrl: profile.qwenUrl, nimUrl: profile.nimUrl,
+      adapterSettings: { ...profile, environment: providerEnvironment }, timeoutMs: 60000,
+      signal: new AbortController().signal, tools: [],
+      messages: [{ role: "user", content: "Reply hi only. Do not use tools or read files." }] });
+    const answer = response.content;
+    ok = typeof answer === "string" && answer.trim().length > 0;
+    code = ok ? undefined : "EMPTY_REPLY";
+  } catch (error) { code = error.code ?? "PROBE_FAILED"; }
+  finally { childProcess.spawn = originalSpawn; syncBuiltinESMExports(); }
+  const failures = [];
+  if (!ok) for (const launch of launches) {
+    const errors = [];
+    for (const line of launch.stdout.split(/\r?\n/)) {
+      try { const event = JSON.parse(line); if (["error", "turn.failed"].includes(event.type))
+        errors.push(redact(event.error?.message ?? event.message ?? event.error ?? "Provider reported an error")); }
+      catch { /* Other stdout is excluded from the report. */ }
+    }
+    failures.push({ command: launch.command, exitCode: launch.exitCode,
+      stderr: redact(launch.stderr), errors });
+  }
+  return { version: pointer.version, profile: profile.profileName, provider, model,
+    ok, ...(code ? { code } : {}), launches: launches.map(({ command, exitCode }) => ({ command, exitCode })),
+    customProviderHome: { terminal: Boolean(environment.CODEX_HOME), saved: Boolean(saved.CODEX_HOME) },
+    ...(failures.length ? { failures } : {}) };
+}
+
+export async function executorDiagnosticMain(inputArgs, options = {}) {
+  const output = options.stdout ?? process.stdout;
+  try {
+    const args = [...inputArgs];
+    let background = false, foreground = false, fresh = false, profileName, reportFile;
+    while (args.length) {
+      const flag = args.shift();
+      if (flag === "--background") background = true;
+      else if (flag === "--foreground") foreground = true;
+      else if (flag === "--fresh") fresh = true;
+      else if (flag === "--json") { /* The report is always safe structured JSON. */ }
+      else if (["--help", "-h"].includes(flag)) {
+        output.write("totem diagnose [--profile NAME] [--fresh] [--json]\nShow the captured background executor failure. If none is saved, check the executor through its Windows task account or local runtime.\n");
+        return 0;
+      }
+      else if (flag === "--profile" && args.length) profileName = args.shift();
+      else if (flag === "--report-file" && args.length) reportFile = args.shift();
+      else throw Error("Use --background or --profile NAME");
+    }
+    if (reportFile && background) throw Error("Invalid diagnostic mode");
+    if (foreground && background) throw Error("Choose one diagnostic context");
+    // Child reports may only be created in this probe's own temporary directory.
+    if (reportFile && (resolve(dirname(reportFile)) !== dirname(fileURLToPath(import.meta.url)) || basename(reportFile) !== "report.json"))
+      throw Error("Invalid report destination");
+    const probeRoot = reportFile ? resolve(dirname(reportFile), "../../..") : undefined;
+    const root = probeRoot ?? options.env?.TOTEM_CONFIG_DIR ?? process.env.TOTEM_CONFIG_DIR ?? join(homedir(), ".totem");
+    let report;
+    if (!fresh && !reportFile) {
+      const { readProviderDiagnostic } = await import(new URL("./provider-diagnostics.mjs", import.meta.url));
+      const profile = await selectedProfile(root, profileName);
+      const failure = await readProviderDiagnostic(profile);
+      if (failure) report = { context: "captured-background-failure", profile: profile.profileName, ok: false, ...failure };
+    }
+    if (!report) report = await (
+      background || (!reportFile && !foreground && (options.platform ?? process.platform) === "win32")
+        ? (options.backgroundProbe ?? diagnoseBackground) : (options.foregroundProbe ?? diagnoseExecutor)
+    )({ root, profileName });
+    if (reportFile) {
+      await writeFile(reportFile + ".tmp", JSON.stringify(report), { mode: 0o600, flag: "wx" });
+      await rename(reportFile + ".tmp", reportFile);
+    } else output.write(JSON.stringify(report, null, 2) + "\n");
+    return report.ok ? 0 : 1;
+  } catch { output.write(JSON.stringify({ ok: false, code: "DIAGNOSTIC_SETUP_FAILED" }) + "\n"); return 1; }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  process.exitCode = await executorDiagnosticMain(process.argv.slice(2));
+}

package/bin/model-adapter.mjs

@@ -5,6 +5,7 @@ import { isAbsolute, join } from "node:path";
 import { createCommandAdapter, createHttpAdapter } from "./worker-core/adapters.mjs";
 import { installedClientInvocation, localClientEnvironment } from "./platform-client.mjs";
 import { WorkerError } from "./worker-core/errors.mjs";
+import { saveProviderDiagnostic } from "./provider-diagnostics.mjs";
 
 export function providerFailureCode(text) {
   if (
@@ -83,6 +84,7 @@ export async function externalModelReply({
   agentUrl,
   agentTokenEnv,
   environment = process.env,
+  diagnosticDirectory,
 }) {
   validateModelAdapter(provider, { command, commandArgs, agentUrl, agentTokenEnv });
   // Provider tools must not operate on a Mission checkout. Totem applies and
@@ -185,12 +187,18 @@ export async function externalModelReply({
         env,
         timeoutMs,
         parseResult,
+        captureFailure: Boolean(diagnosticDirectory),
         ...(["codex", "claude"].includes(provider) ? { classifyFailure: providerFailureCode } : {}),
       });
     }
     const result = await adapter.run({ prompt, signal, runId: randomUUID() });
     if (result.status !== "completed") throw new Error("The agent did not complete this turn.");
     return result.output;
+  } catch (error) {
+    // Keep the real background error locally. Remote heartbeats and journal
+    // blockers retain fixed codes; provider logs never become model input.
+    await saveProviderDiagnostic(diagnosticDirectory, error, { environment, provider, model }).catch(() => {});
+    throw error;
   } finally {
     await rm(directory, { recursive: true, force: true });
   }

package/bin/provider-diagnostics.mjs

@@ -0,0 +1,46 @@
+import { join, isAbsolute } from "node:path";
+import { privateRead, privateWrite } from "./runtime-installation.mjs";
+import { runtimeErrorCode } from "./runtime-diagnostics.mjs";
+
+export function providerDiagnostic(error, { environment = process.env, provider, model } = {}) {
+  // A stream truncated at its output bound could contain only part of a secret.
+  const captured = error.code === "OUTPUT_LIMIT_EXCEEDED" ? {} : error.privateProviderDiagnostic ?? {};
+  const secrets = Object.entries(environment)
+    .filter(([name, value]) => /secret|token|password|api.?key|db.?pass/i.test(name) && typeof value === "string" && value.length >= 4)
+    .map(([, value]) => value);
+  const redact = value => {
+    let text = String(value ?? "");
+    for (const secret of secrets) text = text.split(secret).join("[REDACTED]");
+    return text.replace(/\b(?:tn_(?:live|test)_[A-Za-z0-9_-]+|sk-[A-Za-z0-9_-]+|eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)\b/g, "[REDACTED]")
+      .replace(/(Bearer\s+)[^\s"']+/gi, "$1[REDACTED]")
+      .replace(/(https?:\/\/)[^\s\/@]+@/gi, "$1[REDACTED]@")
+      .slice(-6000);
+  };
+  const errors = [];
+  for (const line of String(captured.stdout ?? "").split(/\r?\n/)) {
+    try {
+      const event = JSON.parse(line);
+      if (["error", "turn.failed"].includes(event.type))
+        errors.push(redact(event.error?.message ?? event.message ?? event.error));
+    } catch { /* Successful model output and ordinary stdout never become diagnostics. */ }
+  }
+  return { version: 1, checkedAt: new Date().toISOString(), provider, model,
+    code: runtimeErrorCode(error), command: redact(captured.command),
+    ...(Number.isInteger(captured.exitCode) ? { exitCode: captured.exitCode } : {}),
+    stderr: redact(captured.stderr), errors: errors.slice(-8) };
+}
+
+export async function saveProviderDiagnostic(directory, error, context) {
+  if (typeof directory !== "string" || !isAbsolute(directory)) return;
+  await privateWrite(join(directory, "last-provider-failure.json"), providerDiagnostic(error, context));
+}
+
+export async function readProviderDiagnostic(profile) {
+  try {
+    const value = await privateRead(join(profile.stateDirectory, "last-provider-failure.json"));
+    const model = profile.client && profile.provider === "qwen-local" ? "default" : profile.model;
+    if (value.version !== 1 || value.provider !== (profile.client ?? profile.provider) || value.model !== model || !Number.isFinite(Date.parse(value.checkedAt)))
+      return undefined;
+    return value;
+  } catch (error) { if (error.code !== "ENOENT") throw error; }
+}

package/bin/totem.mjs

@@ -245,6 +245,7 @@ Connect once and receive messages and approved Mission work
   Select Codex, Claude, a local model, or an owner-configured CLI/HTTP agent.
   totem setup
   totem status
+  totem diagnose [--profile NAME] [--fresh] [--json]
   totem start --background
   totem stop
 
@@ -1748,6 +1749,11 @@ async function runRfq(options, baseUrl) {
 }
 
 async function main() {
+  if (process.argv[2] === "diagnose") {
+    const { executorDiagnosticMain } = await import("./executor-diagnostic.mjs");
+    process.exitCode = await executorDiagnosticMain(process.argv.slice(3));
+    return;
+  }
   if (!process.argv[2] || ["login", "install"].includes(process.argv[2])) {
     const { installationMain } = await import("./installation.mjs");
     process.exitCode = await installationMain(process.argv.slice(3), {});

package/bin/worker-core/adapters.mjs

@@ -52,7 +52,8 @@ export function createCommandAdapter(config) {
     !(config.args ?? []).every((arg) => typeof arg === "string" && !arg.includes("\0")) ||
     typeof config.cwd !== "string" ||
     !isAbsolute(config.cwd) ||
-    (config.classifyFailure !== undefined && typeof config.classifyFailure !== "function")
+    (config.classifyFailure !== undefined && typeof config.classifyFailure !== "function") ||
+    (config.captureFailure !== undefined && typeof config.captureFailure !== "boolean")
   ) {
     throw new WorkerError("INVALID_ADAPTER_CONFIG");
   }
@@ -78,6 +79,14 @@ export function createCommandAdapter(config) {
         let failure;
         let output = "";
         let diagnosticOutput = "";
+        const diagnosticFailure = (error, exitCode) => {
+          if (config.captureFailure)
+            Object.defineProperty(error, "privateProviderDiagnostic", {
+              value: { command: config.command, exitCode, stderr: diagnosticOutput, stdout: output },
+              enumerable: false,
+            });
+          return error;
+        };
         let bytes = 0;
         let killTimer;
         // Also remove surviving descendants if the parent exits before escalation.
@@ -135,7 +144,7 @@ export function createCommandAdapter(config) {
         child.stderr.on("data", (chunk) => {
           bytes += chunk.length;
           if (bytes > maxOutputBytes) stop("OUTPUT_LIMIT_EXCEEDED");
-          else if (config.classifyFailure) diagnosticOutput += chunk.toString("utf8");
+          else if (config.classifyFailure || config.captureFailure) diagnosticOutput += chunk.toString("utf8");
         });
         child.stdin.on("error", () => {
           /* A failed child can close stdin early. */
@@ -149,21 +158,23 @@ export function createCommandAdapter(config) {
           signal?.removeEventListener("abort", cancel);
           if (failure) {
             kill("SIGKILL");
-            return reject(failure);
+            return reject(diagnosticFailure(failure, code));
           }
           if (code !== 0) {
             try {
               return reject(
-                new WorkerError(config.classifyFailure?.(diagnosticOutput) ?? "AGENT_EXIT_FAILED"),
+                diagnosticFailure(new WorkerError(
+                  config.classifyFailure?.(`${diagnosticOutput}\n${output}`) ?? "AGENT_EXIT_FAILED",
+                ), code),
               );
             } catch {
-              return reject(new WorkerError("AGENT_EXIT_FAILED"));
+              return reject(diagnosticFailure(new WorkerError("AGENT_EXIT_FAILED"), code));
             }
           }
           try {
             resolve(validateResult(parseResult(output)));
           } catch (error) {
-            reject(error instanceof WorkerError ? error : new WorkerError("INVALID_AGENT_RESULT"));
+            reject(diagnosticFailure(error instanceof WorkerError ? error : new WorkerError("INVALID_AGENT_RESULT"), code));
           }
         });
         // Prompts cannot become argv, executable names, paths, or shell syntax.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "totemlayer",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Cross-platform CLI for TotemLayer agent identity and authorization",
   "type": "module",
   "bin": {