totemlayer 0.1.15 → 0.1.16

package/bin/agent-runner.mjs

@@ -9,6 +9,7 @@ import { parseArgs } from "node:util";
 import { readAgentCredential, readAgentProfile, withAgentProfileLock } from "./agent-profile.mjs";
 import { localClientEnvironment } from "./platform-client.mjs";
 import { Totem } from "./sdk/index.js";
+import { RUNTIME_ERROR_CODES, runtimeErrorCode } from "./runtime-diagnostics.mjs";
 
 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;
@@ -29,7 +30,7 @@ const LABELS = {
   reconnecting: "Connection interrupted. Waiting to reconnect from saved progress.",
   working: "Working on an assigned Mission task.",
   waiting: "Connected and waiting for approved work.",
-  blocked: "A Mission needs attention. Open Missions to review the blocker.",
+  blocked: "Agent execution needs attention. Check status for the blocker.",
   stopping: "Stopping the agent and saving its progress…",
   stopped: "Agent stopped. Saved progress will be checked when it starts again.",
   failed:
@@ -230,6 +231,7 @@ export async function readAgentRuntimeStatus(profile, { isAlive = alive, now = D
         : "interrupted",
     runId: record.runId,
     updatedAt: record.updatedAt,
+    ...(RUNTIME_ERROR_CODES.has(record.blockerCode) ? { blockerCode: record.blockerCode } : {}),
     ...(UUID.test(record.missionId ?? "") ? { missionId: record.missionId } : {}),
     ...(UUID.test(record.workItemId ?? "") ? { workItemId: record.workItemId } : {}),
   };
@@ -254,6 +256,7 @@ function eventState(event) {
   if (!["connected", "working", "waiting", "blocked"].includes(phase)) return null;
   return {
     phase,
+    blockerCode: phase === "blocked" ? runtimeErrorCode({ code: event.code }) : undefined,
     ...(UUID.test(event.missionId ?? "") ? { missionId: event.missionId } : {}),
     ...(UUID.test(event.workItemId ?? "") ? { workItemId: event.workItemId } : {}),
   };
@@ -311,6 +314,7 @@ export async function runAgentSession(profile, options = {}) {
         phase: status.phase,
         message: LABELS[status.phase],
         ...(status.missionId ? { missionId: status.missionId } : {}),
+        ...(status.blockerCode ? { blockerCode: status.blockerCode } : {}),
       });
     } catch {
       persistenceFailed = true;

package/bin/agent-setup.mjs

@@ -12,10 +12,12 @@ import { installedClientInvocation, localClientEnvironment } from "./platform-cl
 import { inspectLocalRepository } from "./repository.mjs";
 import { Totem } from "./sdk/index.js";
 import { detectInstalledProvider } from "./provider-detection.mjs";
+import { RUNTIME_ERROR_CODES } from "./runtime-diagnostics.mjs";
 
 const execute = promisify(execFile);
 const ORIGIN = "https://totemlayer.com";
 const KEY_LIMIT = 8192;
+const IDENTITY_TIMEOUT_MS = 15000;
 
 export const AGENT_SETUP_HELP = `Connect your agent once
 
@@ -195,7 +197,8 @@ function dependencies(options) {
     stdin: process.stdin,
     stdout: process.stdout,
     stderr: process.stderr,
-    createClient: (config) => new Totem({ ...config, timeoutMs: 5000, maxRetries: 0 }),
+    createClient: (config) =>
+      new Totem({ ...config, timeoutMs: IDENTITY_TIMEOUT_MS, maxRetries: 0 }),
     fetch: globalThis.fetch,
     inspectRepository: inspectLocalRepository,
     installMcp: installTotemMcp,
@@ -224,20 +227,43 @@ function safeOutput(value, secret) {
 }
 
 function identityError(error) {
-  return error?.status === 401 || error?.status === 403
-    ? "The connection key was rejected. For a saved profile, rerun setup with --replace to enter a new key, or use --replace --key-file with the replacement key."
-    : "Totem identity could not be verified. Check the origin, connection key, and server availability.";
+  if (error?.status === 401 || error?.status === 403)
+    return [
+      "The connection key was rejected. For a saved profile, rerun setup with --replace to enter a new key, or use --replace --key-file with the replacement key.",
+      "CONNECTION_KEY_REJECTED",
+    ];
+  if (["TIMEOUT", "CANCELED"].includes(error?.code))
+    return [
+      "Totem identity verification timed out. Check connectivity and retry status; this does not mean the key was rejected.",
+      "IDENTITY_TIMEOUT",
+    ];
+  if (error?.code === "NETWORK_ERROR")
+    return [
+      "Totem identity verification could not reach the saved origin. Check connectivity, proxy and TLS settings.",
+      "IDENTITY_NETWORK_ERROR",
+    ];
+  if (error?.status >= 500)
+    return [
+      "Totem identity verification encountered a server error. Retry status; this does not mean the key was rejected.",
+      "IDENTITY_SERVER_ERROR",
+    ];
+  if (error?.code === "INVALID_RESPONSE")
+    return [
+      "The saved origin returned an invalid identity response. Check the origin and server availability.",
+      "IDENTITY_INVALID_RESPONSE",
+    ];
+  return [
+    "Totem identity could not be verified. Check the saved origin and server availability.",
+    "IDENTITY_VERIFICATION_FAILED",
+  ];
 }
 
 async function verifiedIdentity(client) {
   let identity;
   try {
-    identity = await client.agent({ signal: AbortSignal.timeout(5000) });
+    identity = await client.agent({ signal: AbortSignal.timeout(IDENTITY_TIMEOUT_MS) });
   } catch (error) {
-    fail(
-      identityError(error),
-      error?.status === 401 || error?.status === 403 ? "CONNECTION_KEY_REJECTED" : undefined,
-    );
+    fail(...identityError(error));
   }
   if (
     !identity ||
@@ -248,7 +274,10 @@ async function verifiedIdentity(client) {
     !["SANDBOX", "PRODUCTION"].includes(identity.environment) ||
     (identity.status && !["ACTIVE", "OFFLINE"].includes(identity.status))
   )
-    fail("Totem did not return an active agent identity. Check this agent in Totem.");
+    fail(
+      "Totem did not return an active agent identity. Check this agent in Totem.",
+      "IDENTITY_INVALID_RESPONSE",
+    );
   return identity;
 }
 
@@ -600,6 +629,7 @@ export async function agentStatusMain(args, options = {}) {
       )
         fail(
           "The saved key no longer matches this profile's agent. Run setup with a separate profile or explicitly replace it.",
+          "AGENT_IDENTITY_MISMATCH",
         );
       checks.credential = {
         state: "verified",
@@ -608,6 +638,9 @@ export async function agentStatusMain(args, options = {}) {
     } catch (error) {
       checks.credential = {
         state: "failed",
+        code: error?.setupSafe
+          ? (error.code ?? "IDENTITY_VERIFICATION_FAILED")
+          : "IDENTITY_VERIFICATION_FAILED",
         message: error?.setupSafe
           ? error.message
           : "The saved agent identity could not be verified.",
@@ -688,6 +721,7 @@ export async function agentStatusMain(args, options = {}) {
             : "needs_attention";
         checks.worker = {
           state,
+          ...(RUNTIME_ERROR_CODES.has(worker?.blockerCode) ? { code: worker.blockerCode } : {}),
           ...(phase ? { phase } : {}),
           message:
             state === "running"
@@ -697,7 +731,7 @@ export async function agentStatusMain(args, options = {}) {
                 : phase === "stopping"
                   ? "The worker is stopping and preserving progress. Wait for it to stop before changing setup or restarting."
                   : phase === "blocked"
-                    ? "The running worker has a Mission blocker. Open Missions to resolve it; starting another worker will not resolve the blocker."
+                    ? "The running worker has an execution blocker. Check its error code; starting another worker will not resolve an uncertain run."
                     : phase === "unresponsive"
                       ? "The worker process is present but its status is stale. Inspect or stop it before starting another worker."
                       : "The local worker is not confirmed ready. Check it with totem start for this profile.",

package/bin/connected-agent-service.mjs

@@ -11,13 +11,17 @@ export async function runConnectedAgentService(settings, dependencies = {}) {
     : controller.signal;
   const emit = settings.emit ?? (() => {});
   const phases = { messages: "starting", missions: "starting" };
+  const blockers = {};
   const report = (queue, event) => {
     phases[queue] = event.type === "completed" ? "waiting" : event.type;
+    if (event.type === "blocked") blockers[queue] = { code: event.code, messageId: event.messageId };
+    else delete blockers[queue];
     const values = Object.values(phases);
     const type =
       ["reconnecting", "starting", "blocked", "working"].find((phase) => values.includes(phase)) ??
       "waiting";
-    emit({ ...event, type });
+    const blocked = type === "blocked" ? blockers.messages ?? blockers.missions : undefined;
+    emit({ ...event, type, ...(blocked ?? {}) });
   };
   const messages = async () => {
     let attempts = 0;
@@ -36,7 +40,9 @@ export async function runConnectedAgentService(settings, dependencies = {}) {
               attempts = 0;
               report("messages", { type: "waiting" });
             } else if (event.type === "runtime_error")
-              report("messages", { type: "blocked", code: event.error?.code });
+              report("messages", { type: "blocked", code: event.error?.code, messageId: event.messageId });
+            else if (event.type === "message_started")
+              report("messages", { type: "working", messageId: event.data?.messageId });
             else if (["message_handled", "chat_completed"].includes(event.type))
               report("messages", { type: "waiting" });
           },

package/bin/executor-readiness.mjs

@@ -0,0 +1,37 @@
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { modelReply } from "./network-runtime.mjs";
+import { privateRead, privateWrite } from "./runtime-installation.mjs";
+import { runtimeErrorCode } from "./runtime-diagnostics.mjs";
+
+export async function verifyExecutorReady(profile, env = process.env, options = {}) {
+  const version = options.version ?? JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")).version;
+  const file = join(profile.stateDirectory, "executor-readiness.json");
+  const binding = JSON.stringify([profile.agentId, profile.provider, profile.client, profile.model, profile.command, profile.commandArgs, profile.agentUrl, profile.qwenUrl, profile.ollamaUrl, profile.nimUrl]);
+  const previous = await privateRead(file).catch(error => {
+    if (error.code !== "ENOENT") throw error;
+    return null;
+  });
+  if (previous?.version === version && previous.binding === binding && previous.ready === true) return previous;
+  let response;
+  try { response = await (options.generate ?? modelReply)({
+    provider: profile.client ?? profile.provider,
+    model: profile.client && profile.provider === "qwen-local" ? "default" : profile.model,
+    origin: profile.ollamaUrl ?? "http://127.0.0.1:11434",
+    qwenUrl: profile.qwenUrl,
+    nimUrl: profile.nimUrl,
+    adapterSettings: { ...profile, environment: env },
+    messages: [{ role: "user", content: "This is a connection readiness check. Reply READY. No tools, file reads or external actions are authorized." }],
+    tools: [],
+    signal: options.signal ?? new AbortController().signal,
+    timeoutMs: 30000,
+  }); } catch (error) {
+    await privateWrite(file, { version, binding, ready: false, code: runtimeErrorCode(error), checkedAt: new Date().toISOString() });
+    throw error;
+  }
+  if (typeof response?.content !== "string" || !response.content.trim())
+    throw Object.assign(new Error("The selected executor did not complete its readiness check."), { code: "INVALID_AGENT_RESULT" });
+  const record = { version, binding, ready: true, checkedAt: new Date().toISOString() };
+  await privateWrite(file, record);
+  return record;
+}

package/bin/installation.mjs

@@ -17,11 +17,25 @@ export async function activateConnection(profile, env = process.env, options = {
     ...(profile.agentTokenEnv ? { TOTEM_AGENT_TOKEN_ENV: profile.agentTokenEnv } : {}),
   });
   if (!enabled) return { state: "paused", ...service, entry: runtime.cli };
+  const { verifyExecutorReady } = await import("./executor-readiness.mjs");
+  try {
+    await (options.verifyExecutor ?? verifyExecutorReady)(profile, env);
+  } catch (error) {
+    return { state: "needs_attention", ...service, entry: runtime.cli,
+      code: error.code ?? "EXECUTOR_NOT_READY",
+      message: "Your connection is saved, but the selected agent could not complete its startup check. Run totem status to inspect the blocker." };
+  }
   const { agentStartMain } = await import("./agent-runner.mjs");
-  await (options.start ?? agentStartMain)(
+  const started = await (options.start ?? agentStartMain)(
     ["--profile", profile.profileName, "--background", "--json"],
     { env, automatic: true, stdout: { write() {} } },
   );
+  if (started !== 0)
+    return { state: "needs_attention", ...service, entry: runtime.cli, code: "WORKER_START_FAILED" };
+  const { readAgentRuntimeStatus } = await import("./agent-runner.mjs");
+  const state = await (options.readStatus ?? readAgentRuntimeStatus)(profile);
+  if (!state.running || !["connected", "working", "waiting"].includes(state.phase))
+    return { state: "needs_attention", ...service, entry: runtime.cli, code: state.blockerCode ?? "WORKER_NOT_READY", phase: state.phase };
   return { state: "running", ...service, entry: runtime.cli };
 }
 
@@ -108,25 +122,36 @@ export async function installationMain(args = [], options = {}) {
   // An upgrade reuses private profiles and starts their existing connections.
   const { opendir } = await import("node:fs/promises");
   let saved = false;
+  const savedProfiles = [];
   try {
     const profiles = await opendir(join(runtime.root, "connections"));
     for await (const entry of profiles)
       if (
         entry.isDirectory() &&
         (!environment.TOTEM_AGENT_ID || entry.name === environment.TOTEM_AGENT_ID)
-      )
+      ) {
         saved = true;
+        savedProfiles.push(entry.name);
+      }
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
   }
   if (saved && options.forceLogin !== true) {
-    const report = { installed: true, connection: "saved", automatic: true, service };
+    const { readAgentProfile } = await import("./agent-profile.mjs");
+    const results = [];
+    for (const name of savedProfiles) {
+      const profile = await readAgentProfile(name, { environment });
+      results.push({ profile: name, ...(await (options.activateConnection ?? activateConnection)(profile, environment)) });
+    }
+    const ready = results.every(result => ["running", "paused"].includes(result.state));
+    const report = { installed: true, connection: "saved", automatic: true, ready, profiles: results, service };
     stdout.write(
       flags.json
         ? JSON.stringify(report) + "\n"
-        : "Totem's automatic listener is installed and reuses your saved connections.\n",
+        : ready ? "Totem's automatic listener reuses your saved connections; startup checks passed.\n"
+          : "Totem is installed, but an agent failed its startup check. Run totem status to inspect it.\n",
     );
-    return 0;
+    return ready ? 0 : 1;
   }
   const connection = await (options.beginLogin ?? beginDeviceLogin)(runtime, environment, {
     openBrowser: !flags["no-browser"] && environment.TOTEM_NO_BROWSER !== "1",

package/bin/model-adapter.mjs

@@ -4,6 +4,16 @@ import { tmpdir } from "node:os";
 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";
+
+export function providerFailureCode(text) {
+  if (/unexpected argument|unknown option|unrecognized option|no such option|unknown flag/i.test(text)) return "AGENT_CLI_INCOMPATIBLE";
+  if (/not logged in|authentication required|invalid[_ ]api[_ ]key|unauthorized|refresh token.*(?:expired|reused)|sign in.*required/i.test(text)) return "AGENT_AUTH_REQUIRED";
+  if (/usage limit|rate limit|quota.*(?:exceeded|insufficient)|insufficient_quota|credit balance/i.test(text)) return "AGENT_QUOTA_EXCEEDED";
+  if (/sandbox.*(?:setup failed|not available|not configured|unsupported|error)|CreateProcessAsUser|error 1385/i.test(text)) return "AGENT_SANDBOX_UNAVAILABLE";
+  if (/model.*(?:not found|not supported|does not exist|not have access)|model_not_found/i.test(text)) return "AGENT_MODEL_UNAVAILABLE";
+  return "AGENT_EXIT_FAILED";
+}
 
 export const EXTERNAL_PROVIDERS = ["codex", "claude", "command", "http"];
 export const isExternalModelProvider = (provider) => EXTERNAL_PROVIDERS.includes(provider);
@@ -88,7 +98,7 @@ export async function externalModelReply({
             continue;
           }
           if (event.type === "turn.failed" || event.type === "error")
-            throw new Error("Codex turn failed.");
+            throw new WorkerError(providerFailureCode(event.error?.message ?? event.message ?? ""));
           if (event.type === "item.completed" && event.item?.type === "agent_message")
             final = event.item.text;
         }
@@ -113,7 +123,7 @@ export async function externalModelReply({
       ];
       parseResult = (output) => {
         const result = JSON.parse(output);
-        if (result.is_error || result.subtype !== "success") throw new Error("Claude turn failed.");
+        if (result.is_error || result.subtype !== "success") throw new WorkerError(providerFailureCode(String(result.result ?? "")));
         return {
           status: "completed",
           output: result.structured_output
@@ -153,6 +163,7 @@ export async function externalModelReply({
         env,
         timeoutMs,
         parseResult,
+        ...(["codex", "claude"].includes(provider) ? { classifyFailure: providerFailureCode } : {}),
       });
     }
     const result = await adapter.run({ prompt, signal, runId: randomUUID() });

package/bin/network-runtime.mjs

@@ -6,6 +6,7 @@ import { pause } from "./network.mjs";
 import { localModelEndpoint } from "./local-model-provider.mjs";
 import { runInboxQueue } from "./inbox-queue.mjs";
 import { customerInspector, inspectNetworkMessage } from "./local-inspector.mjs";
+import { runtimeErrorCode } from "./runtime-diagnostics.mjs";
 import {
   externalModelReply,
   isExternalModelProvider,
@@ -572,7 +573,12 @@ export async function runRuntime(settings) {
   let inbox;
   let humanDone = false;
   let fatalError;
+  let diagnosticsSupported = false;
+  let diagnostics = { phase: "starting" };
+  const packageVersion = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8")).version;
   const report = (error, context = {}) => {
+    diagnostics = { phase: "blocked", errorCode: runtimeErrorCode(error),
+      ...(typeof context.messageId === "string" ? { messageId: context.messageId } : {}) };
     if (settings.once) process.exitCode = 1;
     emit({
       type: "runtime_error",
@@ -591,11 +597,16 @@ export async function runRuntime(settings) {
     });
   };
   try {
-    const beat = async () =>
-      client.runtime.heartbeat(
-        { label: `${settings.provider}:${settings.model}`.slice(0, 100) },
+    const beat = async () => {
+      const result = await client.runtime.heartbeat(
+        { label: `${settings.provider}:${settings.model}`.slice(0, 100),
+          ...(diagnosticsSupported ? { diagnostics: { ...diagnostics, packageVersion, provider: settings.provider,
+            platform: ["darwin", "linux", "win32"].includes(process.platform) ? process.platform : "other" } } : {}) },
         { signal },
       );
+      diagnosticsSupported = result?.diagnosticsSupported === true;
+      return result;
+    };
     await beat();
     heartbeat = (async () => {
       while (!signal.aborted) {
@@ -623,6 +634,7 @@ export async function runRuntime(settings) {
         inspection: settings.inspector.mode,
       },
     });
+    diagnostics = { phase: "waiting" };
     // The A2A queue must keep moving while a human command waits on another agent.
     // ask_agent reads durable conversation history, so acknowledgments cannot steal a reply.
     inbox = runInboxQueue({
@@ -636,10 +648,14 @@ export async function runRuntime(settings) {
       eligible: async (message) => !(await journal.read(`message-blocker:${message.id}`)),
       handle: async (message, signal) => {
         try {
+          diagnostics = { phase: "working", messageId: message.id };
+          emit({ type: "message_started", data: { messageId: message.id } });
           await inspectNetworkMessage(settings.inspector, client, message, { signal });
           const continuation = autonomousReplyMetadata(message, settings, identity.address);
           if (message.inReplyToId && !continuation) {
             await client.messages.ack(message.id, { signal });
+            diagnostics = { phase: "waiting" };
+            emit({ type: "message_handled", data: { messageId: message.id } });
             return;
           }
           const thread = [];
@@ -696,6 +712,7 @@ export async function runRuntime(settings) {
             { signal },
           );
           await client.messages.ack(message.id, { signal });
+          diagnostics = { phase: "waiting" };
           emit({
             type: "message_handled",
             data: { messageId: message.id, conversationId: message.conversationId },

package/bin/platform-client.mjs

@@ -1,4 +1,5 @@
-import { join } from "node:path";
+import { join, dirname, isAbsolute, extname } from "node:path";
+import { existsSync } from "node:fs";
 
 const INHERITED_ENVIRONMENT = new Set(
   [
@@ -71,9 +72,36 @@ export function powershellInvocation(script, environment = process.env) {
 // base64-encoded JSON argument array is interpolated into the script, so a
 // Windows path can never become shell syntax.
 export function installedClientInvocation(command, args, environment = process.env) {
+  // Native executables inherit the pipe directly. For npm clients, launch the
+  // installed JavaScript entrypoint with Node rather than a .cmd/PowerShell
+  // pipeline, which can leave stdin open indefinitely on Windows.
+  const clientPackage = {
+    codex: ["@openai", "codex", "bin", "codex.js"],
+    claude: ["@anthropic-ai", "claude-code", "cli.js"],
+  }[command];
+  const pathValue =
+    environment.PATH ??
+    environment.Path ??
+    Object.entries(environment).find(([key]) => key.toUpperCase() === "PATH")?.[1] ??
+    "";
+  const candidates = isAbsolute(command)
+    ? [command]
+    : pathValue
+        .split(";")
+        .filter(Boolean)
+        .flatMap((dir) => [join(dir, `${command}.exe`), join(dir, `${command}.cmd`)]);
+  for (const path of candidates) {
+    if (!existsSync(path)) continue;
+    if (extname(path).toLowerCase() === ".exe") return { command: path, args };
+    if (clientPackage) {
+      const entry = join(dirname(path), "node_modules", ...clientPackage);
+      if (existsSync(entry)) return { command: process.execPath, args: [entry, ...args] };
+    }
+    break;
+  }
   const payload = Buffer.from(JSON.stringify([command, ...args]), "utf8").toString("base64");
   return powershellInvocation(
-    `$ErrorActionPreference = 'Stop'\n$items = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${payload}')) | ConvertFrom-Json\n$client = [string]$items[0]\n$clientArgs = @($items | Select-Object -Skip 1)\n& $client @clientArgs\nif ($null -eq $LASTEXITCODE) { exit 1 }\nexit $LASTEXITCODE`,
+    `$ErrorActionPreference = 'Stop'\n$items = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String('${payload}')) | ConvertFrom-Json\n$client = [string]$items[0]\n$clientArgs = @($items | Select-Object -Skip 1)\n$OutputEncoding = [Text.UTF8Encoding]::new($false)\n[Console]::OutputEncoding = $OutputEncoding\n$prompt = [Console]::In.ReadToEnd()\n$prompt | & $client @clientArgs\nif ($null -eq $LASTEXITCODE) { exit 1 }\nexit $LASTEXITCODE`,
     environment,
   );
 }

package/bin/runtime-diagnostics.mjs

@@ -0,0 +1,13 @@
+export const RUNTIME_ERROR_CODES = new Set([
+  "AGENT_START_FAILED", "AGENT_EXIT_FAILED", "AGENT_REPORTED_FAILURE", "INVALID_AGENT_RESULT",
+  "AGENT_CLI_INCOMPATIBLE", "AGENT_AUTH_REQUIRED", "AGENT_QUOTA_EXCEEDED", "AGENT_SANDBOX_UNAVAILABLE", "AGENT_MODEL_UNAVAILABLE",
+  "AGENT_OUTCOME_UNCERTAIN", "RUN_TIMEOUT", "RUN_CANCELLED", "OUTPUT_LIMIT_EXCEEDED",
+  "UNKNOWN_HTTP_OUTCOME", "HTTP_AGENT_FAILED", "INVALID_ADAPTER_CONFIG", "INVALID_ADAPTER_ENV",
+  "INSPECTION_BLOCKED", "INSPECTION_UNAVAILABLE", "INSPECTION_UNSUPPORTED_FILE",
+  "AGENT_REPLY_TIMEOUT", "INVALID_ASK", "TOOL_NOT_ALLOWED", "INVALID_PEER_REPLY",
+  "NETWORK_BUSY", "NETWORK_ERROR", "TIMEOUT", "CANCELED", "INVALID_NETWORK_CREDENTIAL",
+  "AGENT_IDENTITY_MISMATCH", "MODEL_ERROR", "MAX_STEPS", "INTERNAL_ERROR",
+]);
+export function runtimeErrorCode(error) {
+  return RUNTIME_ERROR_CODES.has(error?.code) ? error.code : "INTERNAL_ERROR";
+}

package/bin/worker-core/adapters.mjs

@@ -51,7 +51,8 @@ export function createCommandAdapter(config) {
     !Array.isArray(config.args ?? []) ||
     !(config.args ?? []).every((arg) => typeof arg === "string" && !arg.includes("\0")) ||
     typeof config.cwd !== "string" ||
-    !isAbsolute(config.cwd)
+    !isAbsolute(config.cwd) ||
+    (config.classifyFailure !== undefined && typeof config.classifyFailure !== "function")
   ) {
     throw new WorkerError("INVALID_ADAPTER_CONFIG");
   }
@@ -76,13 +77,25 @@ export function createCommandAdapter(config) {
         let child;
         let failure;
         let output = "";
+        let diagnosticOutput = "";
         let bytes = 0;
         let killTimer;
         // Also remove surviving descendants if the parent exits before escalation.
         const kill = (kind) => {
           try {
             if (process.platform !== "win32" && child?.pid) process.kill(-child.pid, kind);
-            else child?.kill(kind);
+            else if (child?.pid) {
+              // A Windows shim can outlive its parent and keep stdio open.
+              const killer = spawn("taskkill.exe", ["/pid", String(child.pid), "/t", "/f"], {
+                windowsHide: true,
+                stdio: "ignore",
+              });
+              killer.on("error", () => {
+                try {
+                  child.kill(kind);
+                } catch {}
+              });
+            }
           } catch {
             /* The process may already have exited. */
           }
@@ -122,6 +135,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");
         });
         child.stdin.on("error", () => {
           /* A failed child can close stdin early. */
@@ -137,7 +151,15 @@ export function createCommandAdapter(config) {
             kill("SIGKILL");
             return reject(failure);
           }
-          if (code !== 0) return reject(new WorkerError("AGENT_EXIT_FAILED"));
+          if (code !== 0) {
+            try {
+              return reject(
+                new WorkerError(config.classifyFailure?.(diagnosticOutput) ?? "AGENT_EXIT_FAILED"),
+              );
+            } catch {
+              return reject(new WorkerError("AGENT_EXIT_FAILED"));
+            }
+          }
           try {
             resolve(validateResult(parseResult(output)));
           } catch (error) {

package/bin/worker-core/errors.mjs

@@ -1,8 +1,4 @@
 const SAFE_CODES = new Set([
-  "INSPECTION_BLOCKED",
-  "INSPECTION_UNAVAILABLE",
-  "INSPECTION_LIMIT",
-  "INSPECTION_UNSUPPORTED_FILE",
   "INTERNAL_ERROR",
   "INVALID_AGENT_RESULT",
   "INVALID_ADAPTER_ENV",
@@ -30,6 +26,7 @@ const SAFE_CODES = new Set([
   "INVALID_PROMPT",
   "AGENT_START_FAILED",
   "AGENT_EXIT_FAILED",
+  "AGENT_CLI_INCOMPATIBLE", "AGENT_AUTH_REQUIRED", "AGENT_QUOTA_EXCEEDED", "AGENT_SANDBOX_UNAVAILABLE", "AGENT_MODEL_UNAVAILABLE",
   "AGENT_REPORTED_FAILURE",
   "UNKNOWN_HTTP_OUTCOME",
   "HTTP_AGENT_FAILED",

package/package.json

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