@agent-compose/sdk 0.5.6 → 0.5.8

package/src/agent/agent-context.ts

@@ -0,0 +1,212 @@
+/**
+ * Harness-agnostic agent context delivery.
+ *
+ * Every coding-agent harness we drive (Claude Code, Codex, Amp, Gemini, …)
+ * looks for an instruction file in its working directory — but they disagree
+ * on the NAME (Codex/Amp read `AGENTS.md`; Claude reads `CLAUDE.md`; Gemini
+ * reads `GEMINI.md`). So `agent()` writes the SAME platform manual under all
+ * three names at the agent's working dir, and every harness finds the one it
+ * knows. The manual is the single source of truth here; `base-env` bakes a
+ * static copy at `/workspace/AGENTS.md` for plain shell sessions, but the
+ * per-run copy `agent()` writes is the authoritative one — it carries the
+ * live connector list and lands at the run's working dir.
+ */
+
+import type { SandboxProvider } from "../types/sandbox.js";
+
+/**
+ * The platform manual delivered to every agent, regardless of harness.
+ * Covers the three things an agent must know: where files go (the factory
+ * drive + the persist-by-default working dir), how to pause for a human, and
+ * that credentials are network-injected (never in the env). The live
+ * "Connectors & access" section is appended per-run by `buildAgentContextDoc`.
+ */
+export const AGENT_COMPOSE_MANUAL = `# Working inside an Agent Compose sandbox
+
+You are an agent running in a per-run sandbox on the Agent Compose platform.
+Use the **\`agentc\` CLI** and the **\`@agent-compose/sdk\`** for everything below —
+do NOT hand-roll raw HTTP/curl calls against the platform API. The CLI is on
+your PATH and already authenticated from the environment
+(\`AGENT_COMPOSE_URL\` / \`AGENT_COMPOSE_API_KEY\` / \`AGENT_COMPOSE_FACTORY\` are
+injected for this run), so commands just work — no login, no keys to manage.
+
+The \`/ac:*\` skills are installed as Claude Code slash commands (\`/ac:invoke\`,
+\`/ac:events\`, \`/ac:logs\`, \`/ac:register\`, …) — reach for them too.
+
+## Files — your outputs persist by default
+
+Your working directory defaults to **\`\$AGENT_COMPOSE_RUN_DIR\`** — a per-run
+directory on the shared factory drive
+(\`\$AGENT_COMPOSE_FACTORY_DIR/<workflow>/<version>/<run-id>/\`) the platform
+creates and attributes to this run. **Files you write here persist by
+default** — they show up in the dashboard's Files tab and the run's Artifacts
+card, with no API calls to save them. The dir already exists and is writable.
+
+Need throwaway scratch — heavy build output, package caches, temp files?
+\`cd /tmp\` (or any path outside \`/factory\`): anything off the factory drive is
+ephemeral and discarded when the sandbox ends. In short: **stay in your working
+dir to keep something, \`cd\` out to throw it away.**
+
+The whole shared drive is POSIX-mounted at \`/factory\`; the dashboard-visible
+root is \`\$AGENT_COMPOSE_FACTORY_DIR\` (\`/factory/files\`). Earlier versions and
+runs live in sibling dirs under
+\`\$AGENT_COMPOSE_FACTORY_DIR/\$AGENT_COMPOSE_WORKFLOW/\` — read them for prior
+context. Other workflows' dirs are present but not your concern.
+
+## Events — the factory timeline
+
+Record something on the run/factory timeline (the dashboard renders these)
+with the CLI — your run id is \`$RUN_ID\`:
+
+    agentc events send "$RUN_ID" <name> --summary "<one line>" [--body '<json>']
+
+Names like \`note.created\` / \`brief.posted\` surface in the Workbench;
+\`agentc events list\` reads them back. \`/ac:events\` is the skill equivalent.
+
+## Runs
+
+    agentc list                          # registered workflows  (/ac:list)
+    agentc logs "$RUN_ID"                # a run's logs           (/ac:logs)
+    agentc invoke <workflow> -i '<json>' # dispatch a workflow    (/ac:invoke)
+
+## Writing workflow / agent code — the SDK
+
+\`@agent-compose/sdk\` is installed in \`/workspace\` — import it from any script
+you write there:
+
+    import { defineWorkflow, agent, AgentComposeClient } from "@agent-compose/sdk";
+
+Use \`/ac:generate-workflow\` / \`/ac:generate-agent\` to scaffold, then
+\`agentc register <file.ts>\` (or \`/ac:register\`).
+
+## Pausing to ask the human — \`agentc pause\`
+
+When you can't or shouldn't proceed without a human, run \`agentc pause\`. It
+blocks until they answer on the dashboard, then prints their answer to stdout:
+
+    ANSWER=$(agentc pause --reason "Notion returned 401 — connect Notion to continue" \\
+                          --option retry --option skip)
+
+Reach for it the moment you hit — or foresee — any of these:
+- **A wall only a human can clear:** a 401/403, a missing credential, an
+  unconnected provider, a host the network refuses. Do NOT retry blindly or try
+  to work around it — pause and say what needs enabling.
+- **A durable or outward-facing action that needs sign-off:** registering a
+  workflow, deploying, sending email/messages, deleting or overwriting shared
+  data, spending money. Prepare everything, then pause for approval BEFORE you
+  commit it.
+- **A judgment call only the human can settle:** an under-specified request,
+  several valid paths, a conflict with existing state, missing input only they have.
+
+You compose the \`--reason\` (the ask) yourself; pass \`--option\` choices when
+there are clear ones, omit them for a free-form answer. Read the printed answer
+and act on it. Each agent pauses independently — pausing doesn't stop the others.
+
+## Credentials
+
+Connector credentials (Google, GitHub, …) are NEVER in your environment.
+They're injected at the network layer when you call an allowed host — make the
+request **without** an Authorization header and the platform adds it. Don't try
+to read or exfiltrate tokens; they aren't here. The "Connectors & access"
+section below (when present) lists exactly which providers this run can reach.
+
+## Tools in this environment
+
+- \`agentc\` — Agent Compose CLI (your primary interface; authed from env)
+- \`@agent-compose/sdk\` — installed in /workspace for writing workflows
+- \`/ac:*\` Claude Code skills — slash commands for the above
+- \`archil\` (factory drive), \`rtk\`, \`bun\`
+- A world-writable \`/workspace\` working directory`;
+
+/**
+ * One connector this run can reach, as the agent should see it. Strictly
+ * NON-SECRET — hosts, methods, paths, identity only. The access token is
+ * injected at the network layer and never appears here. The server builds
+ * this list at dispatch from the run's connector grants × the provider
+ * catalogue and delivers it as the `AGENT_COMPOSE_CONNECTORS` env (JSON array).
+ */
+export interface AgentConnectorInfo {
+  /** Provider key (`github`, `notion`, …). */
+  provider: string;
+  /** Human label ("GitHub", "Notion"). */
+  name?: string;
+  /** API hosts the credential is injected for. */
+  hosts?: string[];
+  /** Allowed HTTP methods (Tier-2 narrowing). Empty/absent = any. */
+  methods?: string[];
+  /** Allowed path prefixes (Tier-2 narrowing). Empty/absent = any. */
+  pathPrefixes?: string[];
+  /** GitHub: the repository the minted token is scoped to. */
+  repository?: string;
+  /** Coarse capability the token was minted with. */
+  access?: string;
+  /** Human scope descriptions, when the provider declares them. */
+  scopes?: string[];
+}
+
+/** Render the per-run "Connectors & access" markdown section, or "" when the
+ *  run brokers no connectors. */
+function renderConnectorsSection(connectors: AgentConnectorInfo[]): string {
+  if (connectors.length === 0) return "";
+  const rows = connectors.map((c) => {
+    const host  = c.hosts?.length ? c.hosts.join(", ") : "(host set by the platform)";
+    const verbs = c.methods?.length ? c.methods.join("/") : "any method";
+    const paths = c.pathPrefixes?.length ? ` under ${c.pathPrefixes.join(", ")}` : "";
+    const repo  = c.repository ? ` — repo \`${c.repository}\` (${c.access ?? "read"})` : "";
+    const why   = c.scopes?.length ? `  \n  _scopes: ${c.scopes.join(", ")}_` : "";
+    return `- **${c.name ?? c.provider}** → \`${host}\` — ${verbs}${paths}${repo}${why}`;
+  });
+  return `
+
+## Connectors & access — what this run can reach
+
+These providers are connected for this run. Call their APIs with plain
+fetch/SDKs and **no Authorization header** — the platform injects the
+credential at the network layer. Requests outside the listed method/path are
+refused (403) and the token withheld. Anything NOT listed is unreachable; if
+you need it, \`agentc pause\` and ask for it to be connected.
+
+${rows.join("\n")}
+`;
+}
+
+/** Compose the full per-run agent doc: the static manual + the live
+ *  connectors section read from `AGENT_COMPOSE_CONNECTORS` (a JSON array;
+ *  malformed/absent → no section). */
+export function buildAgentContextDoc(env: Record<string, string | undefined>): string {
+  let connectors: AgentConnectorInfo[] = [];
+  const raw = env.AGENT_COMPOSE_CONNECTORS;
+  if (raw) {
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (Array.isArray(parsed)) connectors = parsed as AgentConnectorInfo[];
+    } catch { /* malformed manifest — render the manual without a connectors section */ }
+  }
+  return AGENT_COMPOSE_MANUAL + renderConnectorsSection(connectors);
+}
+
+/**
+ * Write the platform context at the agent's working dir under every harness's
+ * instruction-file name, so whichever CLI runs finds the one it reads. Codex
+ * and Amp read `AGENTS.md` natively; Claude reads `CLAUDE.md`; Gemini reads
+ * `GEMINI.md` — we write identical content to all three rather than detect the
+ * harness (the runtime's `kind` isn't known until after spawn, and a few extra
+ * small files in our own run dir are harmless).
+ *
+ * Best-effort: a write failure logs and is swallowed — never fail an agent
+ * because its context file couldn't be written.
+ */
+export async function writeAgentContext(args: {
+  sandbox: Pick<SandboxProvider, "files">;
+  cwd: string;
+  env: Record<string, string | undefined>;
+}): Promise<void> {
+  const doc = buildAgentContextDoc(args.env);
+  const dir = args.cwd.replace(/\/+$/, "") || "/workspace";
+  // AGENTS.md is the cross-harness standard; CLAUDE.md / GEMINI.md are the
+  // per-harness names. Same content under each — the harness that doesn't read
+  // a given name simply ignores it.
+  for (const name of ["AGENTS.md", "CLAUDE.md", "GEMINI.md"]) {
+    await args.sandbox.files.write(`${dir}/${name}`, doc);
+  }
+}

package/src/agent/agent-loop.ts

@@ -15,10 +15,16 @@ import { PauseManager } from "../pause/manager.js";
 import { PauseSignal, isPauseSignal } from "../pause/pause-core.js";
 import { SteerDecisionSchema, type SteerDecision, type SteerPayload } from "./steer-control.js";
 
-export const DEFAULT_CLAUDE_MODEL = "claude-opus-4-7";
+export const DEFAULT_CLAUDE_MODEL = "claude-fable-5";
 
 const SAME_BLOCKER_ITERATIONS = 3;
-const STALL_ITERATIONS        = 3;
+// Consecutive turns with NEITHER a <status> NOR a <response> before the loop
+// declares the agent wedged. Kept generous because the most common benign
+// cause is an agent that launched a useful BACKGROUND job and is waiting to be
+// "notified" — the corrective re-prompt (below) tells it to poll synchronously,
+// and these extra turns give that nudge (and the job) time to land before we
+// give up.
+const STALL_ITERATIONS        = 6;
 const MESSAGE_PREVIEW_CHARS   = 400;
 
 export function parseAgentStatus(text: string): AgentStatus | null {
@@ -47,7 +53,7 @@ export type AgentMessageSummary =
   | { type: "thinking"; text: string }
   | { type: "tool_use"; toolName: string; toolUseId: string; toolInput: Record<string, unknown>; toolInputPreview: string }
   | { type: "tool_result"; toolUseId: string; output: string; isError: boolean }
-  | { type: "usage"; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheCreationTokens: number; durationMs: number; numTurns: number }
+  | { type: "usage"; inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheCreationTokens: number; durationMs: number; numTurns: number; model?: string }
   | { type: "done"; sessionId: string }
   | { type: "error"; text: string };
 
@@ -152,8 +158,15 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
   const label              = opts.label ?? "agent";
   const logLabel           = opts.label ?? "[Agent Loop]";
   const startedAt          = Date.now();
-  const turnsPerIteration  = opts.turnsPerIteration ?? 40;
-  const maxIterations      = opts.maxIterations ?? 8;
+  // No budget ⇒ no turn cap: the harness runtime (Claude Code) decides when it's
+  // done. A numeric budget is an explicit caller choice, not a default we impose.
+  const turnsPerIteration  = opts.turnsPerIteration;
+  const maxIterations      = opts.maxIterations ?? (turnsPerIteration === undefined ? 1 : 8);
+  // A responseSchema is a CONTRACT, not a hope: when the agent's <response> fails
+  // validation, the loop re-prompts with the exact errors until it conforms —
+  // without consuming the caller's iteration budget. The backstop below only
+  // guards against a truly wedged agent (never reached in normal operation).
+  let schemaRetriesLeft    = 10;
   const processors         = opts.processors ?? [];
   const requestContext     = opts.requestContext ?? RequestContext.fromReserved({
     teamId: "", runId: "", workflowId: "",
@@ -171,7 +184,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
 
   if (!opts.runtime) throw new Error("agentLoop: opts.runtime is required");
   const client = opts.runtime({
-    maxTurns:     turnsPerIteration,
+    ...(turnsPerIteration !== undefined ? { maxTurns: turnsPerIteration } : {}),
     allowedTools: opts.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
     label: logLabel,
     cwd:          opts.cwd,
@@ -342,6 +355,14 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
 
     const procCtx = buildProcCtx(iteration + 1);
     let initialPrompt = opts.buildPrompt(lastStatus, iteration);
+    // CONTRACT FEEDBACK: when the previous turn's <response> failed schema
+    // validation, the violation goes BACK TO THE MODEL as its next turn (the
+    // session carries the prior context). Without this, contract retries
+    // re-run the identical prompt and the model repeats the identical mistake.
+    if (lastResponseValidationError) {
+      initialPrompt = `${initialPrompt}\n\n[response contract violation — fix and re-emit]\nYour previous <response> failed schema validation with these errors:\n${lastResponseValidationError.slice(0, 2000)}\nRe-emit the COMPLETE corrected <response> JSON now: every required field present, correctly named and typed (no omissions, no renames).`;
+      lastResponseValidationError = "";
+    }
     if (steerDecision) {
       // Deliver the human's answer as the agent's next user turn by appending
       // it to the iteration prompt. `sendMessage({ prompt })` is the one input
@@ -364,7 +385,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
 
     // Progress, not an error — write to stdout so dashboards and
     // log viewers don't visually flag it as a warning.
-    process.stdout.write(`${logLabel} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration} turns\n`);
+    process.stdout.write(`${logLabel} iteration ${iteration + 1}/${maxIterations} · ${turnsPerIteration !== undefined ? `${turnsPerIteration} turns` : "harness-decided turns"}\n`);
 
     let responseText = "";
     // The single `opts.inbox` is shared across iterations, but the
@@ -376,7 +397,11 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
     // semantics — buffered until consumed).
     for await (const rawMsg of client.sendMessage({
       prompt,
-      sessionId: iteration > 0 ? lastSessionId : undefined,
+      // Resume whenever a session exists — NOT keyed on `iteration > 0`, because a
+      // contract retry rolls `iteration` back to 0 while a session already exists;
+      // keying on the session id keeps the corrective re-prompt in the same session
+      // (otherwise it restarts the task in a fresh session and repeats side effects).
+      sessionId: lastSessionId ?? undefined,
       iteration: iteration + 1,
       ...(opts.inbox ? { inboxStream: opts.inbox } : {}),
     })) {
@@ -394,7 +419,13 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       }
       const msg = outputVerdict.value;
       opts.onAgentEvent?.(iteration, msg);
-      opts.onAgentLifecycleEvent?.({ event: "agent.message", at: Date.now(), agentId, label, iteration: iteration + 1, message: summarizeAgentMessage(msg) });
+      // Usage summaries carry the resolved model so the server can price
+      // token rows per model without correlating back to agent.spawned.
+      const summary = summarizeAgentMessage(msg);
+      opts.onAgentLifecycleEvent?.({
+        event: "agent.message", at: Date.now(), agentId, label, iteration: iteration + 1,
+        message: summary.type === "usage" && client.model != null ? { ...summary, model: client.model } : summary,
+      });
       if (msg.type === "init")  lastSessionId = msg.sessionId;
       if (msg.type === "text")  responseText += msg.text;
       if (msg.type === "error") throw new Error(`Agent error: ${msg.text}`);
@@ -447,6 +478,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
           process.stderr.write(`${logLabel} NO <response> BLOCK — response tail: ${responseText.slice(-400)}\n`);
           status = { ...status!, exit_signal: false, blockers: ["No <response> block found — emit a <response> block with the required JSON fields before setting exit_signal: true"] };
           opts.onIteration?.(iteration + 1, status);
+          if (schemaRetriesLeft-- > 0) iteration--; // contract enforcement — free, not billed to the iteration budget
           continue;
         }
         // Status-merged validation — the schema may reference status
@@ -458,6 +490,7 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
           process.stderr.write(`${logLabel} <response> SCHEMA FAILED: ${parsed.error.message}\nraw: ${JSON.stringify(rawResponse).slice(0, 400)}\n`);
           status = { ...status!, exit_signal: false, blockers: [`<response> schema validation failed: ${parsed.error.message}`] };
           opts.onIteration?.(iteration + 1, status);
+          if (schemaRetriesLeft-- > 0) iteration--; // contract enforcement — free, not billed to the iteration budget
           continue;
         }
         response = parsed.data;
@@ -487,10 +520,31 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       continue;
     }
 
-    if (!status) {
+    if (!status && rawResponse === null) {
       if (++iterationsWithoutStatus >= STALL_ITERATIONS)
         throw new Error(`${logLabel} stalled: no <status> block after ${iterationsWithoutStatus} iterations`);
+      // EMPTY-OUTPUT RE-PROMPT: a turn that emits neither <status> nor
+      // <response>. Refund the iteration and re-prompt with explicit feedback
+      // (bounded by the shared retry pool); the stall counter above still
+      // hard-bounds genuinely wedged agents. The directive call-out about
+      // BACKGROUND jobs is load-bearing: the dominant benign cause is an agent
+      // that ran `cmd &` and parked itself "waiting to be notified" — the loop
+      // delivers no such notification, so it must poll synchronously instead.
+      // Fires with or without a responseSchema (an agent with no schema still
+      // owes a <status>).
+      if (schemaRetriesLeft-- > 0) {
+        lastResponseValidationError =
+          "Your turn ended with no <status> block" + (opts.responseSchema ? " (and no <response> block)" : "") + ". " +
+          "If you launched a background job (`… &`) and are waiting to be notified when it finishes — STOP: nothing will notify you here. " +
+          "Poll it NOW (read its output / wait for it synchronously to completion), then emit your <status>" +
+          (opts.responseSchema ? " and the complete <response> JSON." : ".");
+        process.stdout.write(`${logLabel} empty turn (no <status>) — corrective re-prompt (${schemaRetriesLeft} retries left)\n`);
+        iteration--;
+        continue;
+      }
     } else {
+      // A parsed structured response (even one that failed schema validation)
+      // is real output, not a stall — the contract retry below handles it.
       iterationsWithoutStatus = 0;
     }
 
@@ -506,6 +560,20 @@ export async function agentLoop<TResponse = unknown>(opts: AgentLoopOpts<TRespon
       blockerStreak = null;
     }
 
+    // CONTRACT RETRY (catch-all): the agent EMITTED a <response> block this turn,
+    // it failed schema validation, and it didn't go through the <status> branches
+    // above (structured-only output, no <status>). Re-prompt with the validation
+    // errors as feedback, FREE of the iteration budget. Gated on an actual
+    // validation failure this turn AND on the agent not signalling it's still
+    // working (`exit_signal: false`) — an in-progress turn that happens to carry
+    // a draft <response> consumes its budget normally instead of draining the
+    // shared retry pool that genuine contract violations rely on.
+    if (opts.responseSchema && rawResponse !== null && lastResponseValidationError !== "" && status?.exit_signal !== false && schemaRetriesLeft-- > 0) {
+      process.stdout.write(`${logLabel} response contract not yet satisfied — corrective re-prompt (${schemaRetriesLeft} retries left)\n`);
+      iteration--;
+      continue;
+    }
+
     if (iteration + 1 < maxIterations)
       // Loop continuation — progress.
       process.stdout.write(`${logLabel} continuing to iteration ${iteration + 2}/${maxIterations}\n`);

package/src/agent/run-agent.ts

@@ -21,6 +21,7 @@ import { AsyncQueue } from "./async-queue.js";
 import type { AgentMessage, AgentStatus } from "../types/protocol.js";
 import type { AgentRuntime, RuntimeOptions } from "../types/runtime.js";
 import type { SandboxProvider } from "../types/sandbox.js";
+import { writeAgentContext } from "./agent-context.js";
 import type { AgentBudget } from "../types/workflow.js";
 import type { Processor } from "../processors/processor.js";
 import { RequestContext } from "../request-context/request-context.js";
@@ -232,7 +233,42 @@ export function resolveAgentId(explicitId?: string): string {
 }
 
 export async function agent<T = unknown>(opts: AgentOpts<T>): Promise<AgentLoopResult<T>> {
-  const workingDir = opts.workingDir ?? "";
+  // Persist-by-default: an agent's working dir is the run dir on the factory
+  // drive (the mount step creates it ahead of the run), so everything it
+  // writes is kept and attributed to this run; `cd /tmp` for throwaway
+  // scratch. Falls back to /workspace when this run has no factory drive.
+  // Never "" — an empty cwd is the one case the harnesses' instruction-file
+  // upward-walk can't resolve, and it left codex/amp without their AGENTS.md.
+  let workingDir = opts.workingDir || process.env.AGENT_COMPOSE_RUN_DIR || "/workspace";
+
+  // Deliver the platform context (file conventions, connectors & access, how to
+  // pause) as AGENTS.md / CLAUDE.md / GEMINI.md at the working dir — and use the
+  // write as a LIVENESS PROBE of the working dir. AGENT_COMPOSE_RUN_DIR points at
+  // the /factory FUSE drive, whose writes HANG (uninterruptible, no timeout) when
+  // the mount degraded — launching the agent there wedges it silently with zero
+  // output (no logs). Bound the write; on timeout/failure fall back to /workspace
+  // (always present + writable) so a degraded drive can never sink an agent.
+  const CONTEXT_WRITE_DEADLINE_MS = 15_000;
+  const tryWriteContext = (cwd: string): Promise<boolean> => {
+    // Capture the deadline timer so the fast path (write resolves first) can
+    // clear it in finally — otherwise each probe leaks a dangling 15s timer.
+    // Mirrors sandbox.ts's clear-in-finally pattern.
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    return Promise.race([
+      writeAgentContext({ sandbox: opts.sandbox, cwd, env: process.env }).then(() => true),
+      new Promise<boolean>((resolve) => { timer = setTimeout(() => resolve(false), CONTEXT_WRITE_DEADLINE_MS); }),
+    ]).catch((err: unknown) => {
+      console.error(`[agent] writeAgentContext(${cwd}) failed: ${err instanceof Error ? err.message : String(err)}`);
+      return false;
+    }).finally(() => { if (timer) clearTimeout(timer); });
+  };
+  if (!(await tryWriteContext(workingDir)) && workingDir !== "/workspace") {
+    console.error(
+      `[agent] working dir ${workingDir} not writable within ${CONTEXT_WRITE_DEADLINE_MS}ms ` +
+      `(factory drive degraded?) — falling back to /workspace so the agent can run`);
+    workingDir = "/workspace";
+    await tryWriteContext(workingDir);
+  }
 
   // Stable agentId for this invocation. Used by the inbox URL (server
   // scopes pending messages by agentId), the agentLoop (which would