@felixdotgo/aidlc-kit 0.2.0 → 0.3.0

package/dist/assets/.agents/aidlc/scripts/lib/loop-env.mjs

@@ -0,0 +1,279 @@
+/**
+ * Zero-config environment for the local loop daemon.
+ *
+ * Merges three sources, highest priority first:
+ *   1. the invoking shell (`process.env`) — never overridden;
+ *   2. the AIDLC env file (`AIDLC_ENV_FILE`, default `.agents/loop.env`), a minimal dotenv;
+ *   3. values derived from the configured providers' own config files:
+ *      - `AIDLC_LOOP_EVENT_LOG` → `.agents/data/loop/ui-events.jsonl` (dashboard live log);
+ *      - `AIDLC_OPENCODE_MODEL` → `model` of the OpenCode config (project > OPENCODE_CONFIG > global);
+ *      - worker credentials → OpenCode `auth.json`, Codex `$CODEX_HOME/auth.json`
+ *        (`OPENAI_API_KEY`), Claude Code settings `env.ANTHROPIC_API_KEY` (local > project > user).
+ *
+ * Only providers listed in `loop.agents` are inspected. Secret values are never printed,
+ * logged, written to disk, or returned in a report; the report names their source only.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { isLoopProvider, OPENCODE_MODEL } from "./loop-drivers.mjs";
+import { workerCredentialKeys } from "./loop-worker-docker.mjs";
+
+export const DEFAULT_ENV_FILE = ".agents/loop.env";
+const KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const MAX_FILE_BYTES = 1024 * 1024;
+/** The only values a report may show; every other variable (any env-file key) is "set"/"missing". */
+const DISPLAY_KEYS = new Set(["AIDLC_OPENCODE_MODEL", "AIDLC_LOOP_EVENT_LOG", "AIDLC_WORKER_DOCKER_IMAGE", "AIDLC_LOCAL_WORKTREES_ROOT", "AIDLC_ENV_FILE"]);
+
+export const isSecretKey = (key) => !DISPLAY_KEYS.has(key);
+
+/** Minimal dotenv: `KEY=VALUE`, optional `export `, `#` comments, single/double quotes. No expansion. */
+export function parseEnvFile(text, label = "env file") {
+  const values = {};
+  const lines = String(text).replace(/^/, "").split(/\r?\n/);
+  lines.forEach((raw, index) => {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) return;
+    const match = /^(?:export\s+)?([^=\s]+)\s*=\s*(.*)$/.exec(line);
+    if (!match || !KEY.test(match[1])) throw new Error(`${label}:${index + 1}: expected KEY=VALUE`);
+    const [, key, rest] = match;
+    let value = rest;
+    const quote = value[0];
+    if (quote === '"' || quote === "'") {
+      const end = value.indexOf(quote, 1);
+      if (end < 0) throw new Error(`${label}:${index + 1}: unterminated ${quote === '"' ? "double" : "single"} quote`);
+      const tail = value.slice(end + 1).trim();
+      if (tail && !tail.startsWith("#")) throw new Error(`${label}:${index + 1}: unexpected text after the closing quote`);
+      value = value.slice(1, end);
+      if (quote === '"') value = value.replace(/\\n/g, "\n").replace(/\\"/g, '"');
+    } else {
+      value = value.replace(/\s+#.*$/, "").trim();
+    }
+    values[key] = value;
+  });
+  return values;
+}
+
+/** The env file to load: `AIDLC_ENV_FILE` (relative to root) or the default; `explicit` marks a user choice. */
+export function resolveEnvFile(root, env = process.env) {
+  const chosen = typeof env.AIDLC_ENV_FILE === "string" && env.AIDLC_ENV_FILE.trim() ? env.AIDLC_ENV_FILE.trim() : "";
+  return { path: resolve(root, chosen || DEFAULT_ENV_FILE), explicit: Boolean(chosen) };
+}
+
+const realOrSelf = (path) => { try { return realpathSync(path); } catch { return resolve(path); } };
+const within = (base, target) => { const rel = relative(base, target); return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)); };
+
+/**
+ * Reads a small regular file (symlinks are followed). With `confine`, a symlinked file must
+ * resolve inside the project or the home directory, both compared by their real paths so a
+ * project reached through a symlink (macOS /tmp, ~/code -> /mnt/...) still works.
+ */
+function readTrustedFile(path, { root, home }, { confine = false } = {}) {
+  if (!existsSync(path)) return undefined;
+  const real = realpathSync(path);
+  if (confine && lstatSync(path).isSymbolicLink() && !within(realOrSelf(root), real) && !(home && within(realOrSelf(home), real))) throw new Error(`${path} links outside the project and home directory`);
+  const stat = statSync(real);
+  if (!stat.isFile()) throw new Error(`${path} is not a regular file`);
+  if (stat.size > MAX_FILE_BYTES) throw new Error(`${path} is larger than 1 MiB`);
+  return readFileSync(real, "utf8");
+}
+
+/** JSON with `//` and block comments and trailing commas (OpenCode `.jsonc`). Strings are kept intact. */
+export function parseJsonc(text) {
+  let out = "";
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === '"') {
+      let j = i + 1;
+      while (j < text.length && text[j] !== '"') j += text[j] === "\\" ? 2 : 1;
+      out += text.slice(i, j + 1); i = j; continue;
+    }
+    if (char === "/" && text[i + 1] === "/") { while (i < text.length && text[i] !== "\n") i += 1; out += "\n"; continue; }
+    if (char === "/" && text[i + 1] === "*") { const end = text.indexOf("*/", i + 2); i = end < 0 ? text.length : end + 1; continue; }
+    out += char;
+  }
+  return JSON.parse(out.replace(/,(\s*[}\]])/g, "$1"));
+}
+
+const readJson = (path, context, { jsonc = false } = {}) => {
+  try {
+    const text = readTrustedFile(path, context);
+    return text === undefined ? undefined : jsonc ? parseJsonc(text) : JSON.parse(text);
+  } catch (error) {
+    // Never echo a parser message: V8 quotes the source text around the error, which may be a key.
+    const reason = error instanceof SyntaxError ? "not valid JSON" : error instanceof Error ? error.message : String(error);
+    context.problems.push({ level: "warning", key: "", message: `ignored ${path}: ${reason}` });
+    return undefined;
+  }
+};
+
+/** Unique providers of `loop.agents` (lead first), and the worker subset. */
+export function loopProviders(config) {
+  const lead = config?.loop?.agents?.lead;
+  const workers = Object.values(config?.loop?.agents?.workers ?? {}).filter(isLoopProvider);
+  return { lead: isLoopProvider(lead) ? lead : undefined, workers: [...new Set(workers)], all: [...new Set([...(isLoopProvider(lead) ? [lead] : []), ...workers])] };
+}
+
+const xdg = (env, name, home, fallback) => (env[name] && isAbsolute(env[name]) ? env[name] : join(home, fallback));
+
+/** OpenCode `model`, following its documented precedence (later wins): global < OPENCODE_CONFIG < project. */
+function opencodeModel(context) {
+  const { root, env, home } = context;
+  const configDir = join(xdg(env, "XDG_CONFIG_HOME", home, ".config"), "opencode");
+  const candidates = [
+    join(configDir, "opencode.json"), join(configDir, "opencode.jsonc"),
+    ...(env.OPENCODE_CONFIG ? [resolve(root, env.OPENCODE_CONFIG)] : []),
+    join(root, "opencode.json"), join(root, "opencode.jsonc"),
+  ];
+  let found;
+  for (const path of candidates) {
+    const config = readJson(path, context, { jsonc: true });
+    if (typeof config?.model === "string" && config.model.trim()) found = { value: config.model.trim(), source: `derived:${path}` };
+  }
+  return found;
+}
+
+/** Worker credentials a provider's own login/config can supply, as `{ key, value, source }`. */
+function providerCredentials(provider, env, context) {
+  const { root, home } = context;
+  if (provider === "opencode") {
+    const path = join(xdg(env, "XDG_DATA_HOME", home, join(".local", "share")), "opencode", "auth.json");
+    const auth = readJson(path, context);
+    if (!auth || typeof auth !== "object") return [];
+    const prefix = String(env.AIDLC_OPENCODE_MODEL ?? "").split("/")[0];
+    const keys = workerCredentialKeys("opencode", env);
+    // The OpenCode Zen/Go key only stands in for OPENCODE_API_KEY, never for a provider's own key.
+    const ids = keys.includes("OPENCODE_API_KEY") ? [prefix, "opencode", "opencode-go"] : [prefix];
+    const entry = ids.map((id) => auth[id]).find((value) => value?.type === "api" && typeof value.key === "string" && value.key);
+    return entry ? keys.map((key) => ({ key, value: entry.key, source: `derived:${path}` })) : [];
+  }
+  if (provider === "codex") {
+    const path = join(env.CODEX_HOME && isAbsolute(env.CODEX_HOME) ? env.CODEX_HOME : join(home, ".codex"), "auth.json");
+    const auth = readJson(path, context);
+    if (typeof auth?.OPENAI_API_KEY === "string" && auth.OPENAI_API_KEY) return [{ key: "OPENAI_API_KEY", value: auth.OPENAI_API_KEY, source: `derived:${path}` }];
+    if (auth?.tokens) context.notes.push({ provider, message: "Codex is signed in with ChatGPT; Docker workers need an API key (codex login --with-api-key, or OPENAI_API_KEY in the env file)" });
+    return [];
+  }
+  if (provider === "claude") {
+    const userDir = env.CLAUDE_CONFIG_DIR && isAbsolute(env.CLAUDE_CONFIG_DIR) ? env.CLAUDE_CONFIG_DIR : join(home, ".claude");
+    let found = [];
+    for (const path of [join(userDir, "settings.json"), join(root, ".claude", "settings.json"), join(root, ".claude", "settings.local.json")]) {
+      const value = readJson(path, context)?.env?.ANTHROPIC_API_KEY;
+      if (typeof value === "string" && value) found = [{ key: "ANTHROPIC_API_KEY", value, source: `derived:${path}` }];
+    }
+    return found;
+  }
+  return [];
+}
+
+/** True when `command` resolves on PATH (PATHEXT-aware on Windows). */
+export function hasCommand(command, env = process.env) {
+  const exts = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";") : [""];
+  return String(env.PATH ?? "").split(delimiter).filter(Boolean).some((dir) => exts.some((ext) => { try { return statSync(join(dir, command + ext)).isFile(); } catch { return false; } }));
+}
+
+/** Whether git would ignore the env file; outside a work tree there is nothing to commit. */
+const gitignored = (root, envFile) => {
+  const rel = relative(root, envFile);
+  if (rel.startsWith("..") || isAbsolute(rel)) return true;
+  const result = spawnSync("git", ["check-ignore", "-q", "--", rel.split(sep).join("/")], { cwd: root, stdio: "ignore", timeout: 5000 });
+  return result.error ? true : result.status !== 1;
+};
+
+/**
+ * Resolves the daemon environment. `applied` holds only the keys to add to the
+ * process (file + derived); shell keys are left untouched. `problems` with level
+ * `error` must stop the daemon before it starts.
+ */
+export function loadLoopEnv({ root, config, env = process.env, home = homedir(), commandExists = hasCommand } = {}) {
+  root = resolve(root ?? ".");
+  const problems = [], notes = [];
+  const context = { root, env, home, problems, notes };
+  const providers = loopProviders(config);
+  const mode = config?.loop?.mode ?? "off";
+  const sources = {}, applied = {};
+  const merged = { ...env };
+  // Anything the shell exports, even an empty value, is never overridden.
+  const set = (key, value, source) => { if (merged[key] !== undefined) return false; merged[key] = value; applied[key] = value; sources[key] = source; return true; };
+  for (const key of Object.keys(env)) sources[key] = "shell";
+
+  const envFile = resolveEnvFile(root, env);
+  let fileKeys = [];
+  try {
+    const text = readTrustedFile(envFile.path, context, { confine: true });
+    if (text === undefined) {
+      if (envFile.explicit) problems.push({ level: "error", key: "AIDLC_ENV_FILE", message: `env file not found: ${envFile.path}` });
+    } else {
+      const values = parseEnvFile(text, relative(root, envFile.path) || envFile.path);
+      fileKeys = Object.keys(values);
+      for (const [key, value] of Object.entries(values)) if (value !== "") set(key, value, "file");
+      if (!gitignored(root, envFile.path)) problems.push({ level: "warning", key: "", message: `${relative(root, envFile.path)} is not git-ignored; add "loop.env" to .agents/.gitignore so credentials are never committed` });
+    }
+  } catch (error) {
+    problems.push({ level: "error", key: "AIDLC_ENV_FILE", message: error instanceof Error ? error.message : String(error) });
+  }
+
+  if (mode !== "local" && mode !== "fleet") problems.push({ level: "error", key: "", message: 'loop.mode is off: set "loop": { "mode": "local", "agents": { "lead": "<codex|claude|opencode>", "workers": { "worker-a": "<provider>" } } } in .agents/config.json, or run: aidlc-kit init --loop-mode local' });
+  else if (!providers.lead || !providers.workers.length) problems.push({ level: "error", key: "", message: 'loop.agents needs a lead and at least one worker provider (codex, claude, or opencode) in .agents/config.json' });
+
+  set("AIDLC_LOOP_EVENT_LOG", join(root, ".agents", "data", "loop", "ui-events.jsonl"), "derived");
+
+  const keys = new Set(["AIDLC_LOOP_EVENT_LOG"]);
+  if (providers.all.includes("opencode")) {
+    keys.add("AIDLC_OPENCODE_MODEL");
+    if (!merged.AIDLC_OPENCODE_MODEL) { const found = opencodeModel(context); if (found) set("AIDLC_OPENCODE_MODEL", found.value, found.source); }
+    const model = merged.AIDLC_OPENCODE_MODEL;
+    if (model === "" && sources.AIDLC_OPENCODE_MODEL === "shell") problems.push({ level: "error", key: "AIDLC_OPENCODE_MODEL", message: "AIDLC_OPENCODE_MODEL is exported empty in the shell, which overrides the env file and opencode.json: unset it or set provider/model" });
+    else if (!model) problems.push({ level: "error", key: "AIDLC_OPENCODE_MODEL", message: `opencode needs a model: add AIDLC_OPENCODE_MODEL=<provider/model> to ${relative(root, envFile.path)} or set "model" in opencode.json (list models with: opencode models)` });
+    else if (!OPENCODE_MODEL.test(model)) problems.push({ level: "error", key: "AIDLC_OPENCODE_MODEL", message: `AIDLC_OPENCODE_MODEL must look like provider/model[#variant] (from ${sources.AIDLC_OPENCODE_MODEL})` });
+  }
+
+  const workerKeys = new Set();
+  for (const provider of providers.workers) {
+    const needed = workerCredentialKeys(provider, merged);
+    needed.forEach((key) => workerKeys.add(key));
+    if (needed.every((key) => merged[key])) { needed.forEach((key) => keys.add(key)); continue; }
+    for (const credential of providerCredentials(provider, merged, context)) set(credential.key, credential.value, credential.source);
+    for (const key of needed) {
+      keys.add(key);
+      if (!merged[key]) {
+        const note = notes.find((entry) => entry.provider === provider);
+        problems.push({ level: "warning", key, message: note ? note.message : `${provider} workers need ${key} for the build phase: add it to ${relative(root, envFile.path)}` });
+      }
+    }
+  }
+
+  if (mode === "local" && !commandExists("docker", merged)) problems.push({ level: "warning", key: "", message: "docker was not found on PATH; local workers run in Docker during the build phase" });
+  for (const key of ["AIDLC_WORKER_DOCKER_IMAGE", "AIDLC_LOCAL_WORKTREES_ROOT", ...fileKeys]) if (merged[key]) keys.add(key);
+
+  const entries = [...keys].map((key) => {
+    const secret = isSecretKey(key);
+    const present = Boolean(merged[key]);
+    return { key, set: present, source: present ? sources[key] ?? "shell" : null, secret, ...(present && !secret ? { value: merged[key] } : {}) };
+  });
+  // Worker keys detected from another tool's config reach Docker workers only, never the
+  // host lead (a claude/codex lead would otherwise switch from its own login to API-key
+  // billing). Env-file keys are explicit, like shell exports, and reach the lead too.
+  const leadExclude = [...workerKeys].filter((key) => key in applied && String(sources[key]).startsWith("derived:"));
+  if (leadExclude.length) applied.AIDLC_LEAD_ENV_EXCLUDE = leadExclude.join(",");
+  return { root, mode, providers: providers.all, envFile: { path: envFile.path, explicit: envFile.explicit, loaded: fileKeys.length > 0 || existsSync(envFile.path) }, entries, problems, applied, ok: !problems.some((problem) => problem.level === "error") };
+}
+
+/** A report safe to print: the `applied` values are dropped. */
+export const publicReport = ({ applied: _applied, ...report }) => report;
+
+export function formatLoopEnvReport(report) {
+  const lines = [];
+  lines.push(`Loop environment (${report.mode} mode)`);
+  lines.push(`  providers : ${report.providers.length ? report.providers.join(", ") : "none configured"}`);
+  lines.push(`  env file  : ${report.envFile.path}${report.envFile.loaded ? "" : " (not found)"}`);
+  const width = Math.max(4, ...report.entries.map((entry) => entry.key.length));
+  for (const entry of report.entries) {
+    const shown = !entry.set ? "missing" : entry.secret ? "set" : entry.value;
+    lines.push(`  ${entry.set ? "✓" : "✗"} ${entry.key.padEnd(width)}  ${shown}${entry.source ? `  [${entry.source}]` : ""}`);
+  }
+  for (const problem of report.problems) lines.push(`  ${problem.level === "error" ? "ERROR" : "WARN "} ${problem.message}`);
+  if (report.ok) lines.push("  ready: the daemon can start");
+  return lines.join("\n");
+}

package/dist/assets/.agents/aidlc/scripts/lib/loop-fleet-cli.mjs

@@ -9,6 +9,7 @@ import { runFleetSupervisor } from "./loop-fleet-supervisor.mjs";
 import { createFleetRemoteRepository } from "./loop-fleet-remote.mjs";
 import { createLeadGitHandoff, createIsolatedWorkerGitHandoff } from "./loop-git.mjs";
 import { workerDockerInvocation, workerCredentialKeys } from "./loop-worker-docker.mjs";
+import { openWorkerLog } from "./loop-worker-log.mjs";
 import { defaultWorkerImageTag, ensureWorkerImage, validWorkerImageTag } from "./loop-worker-image.mjs";
 
 const required = (env, name) => { const value = env[name]; if (typeof value !== "string" || !value.trim()) throw new Error(`${name} is required`); return value; };
@@ -133,13 +134,23 @@ export async function runFleetCli(argv, { callTool, env = process.env, out = con
     if (workerAgent) await preflight(workerAgent);
     const baseHandoff = createIsolatedWorkerGitHandoff({ root, worktreesRoot: resolve(required(env, "AIDLC_FLEET_WORKTREES_ROOT")), remote });
     const sessions = new Map();
-    const cleanupSession = (workspace) => { const current=sessions.get(workspace.root); if(current) { rmSync(current.home,{recursive:true,force:true}); sessions.delete(workspace.root); } };
+    const dropSession = (key, current) => { current.log?.close(); rmSync(current.home,{recursive:true,force:true}); sessions.delete(key); };
+    const cleanupSession = (workspace) => { const current=sessions.get(workspace.root); if(current) dropSession(workspace.root, current); };
+    // Same container record and raw output tee as the local loop, written under
+    // this worker checkout's .agents/data/tasks/<task>/runtime/workers (the
+    // index entry carries this host's name). Best-effort: reported once, never fatal.
+    const openLog = (job) => {
+      const diagnostic = (error) => emit({ type: "diagnostic", taskId: job.taskId, itemId: job.itemId, message: `Worker log unavailable for assignment ${job.assignmentId}: ${error instanceof Error ? error.message : String(error)}` });
+      try { return openWorkerLog({ root, taskId: job.taskId, assignmentId: job.assignmentId, itemId: job.itemId, workerId, agent: job.agent, mode: "fleet", onError: diagnostic }); }
+      catch (error) { diagnostic(error); return null; }
+    };
     const handoff = {
       ...baseHandoff,
       async prepare(job) {
         const workspace=await baseHandoff.prepare(job);
         const home=mkdtempSync(join(tmpdir(),"aidlc-worker-home-")); chmodSync(home,0o700);
-        sessions.set(workspace.root,{home,agent:job.agent,assignmentId:job.assignmentId,attempt:job.attempt,epoch:job.epoch,workerId,image,sessionId:null});
+        const labels = { "aidlc.task": job.taskId, "aidlc.item": job.itemId, "aidlc.worker": workerId, "aidlc.assignment": job.assignmentId };
+        sessions.set(workspace.root,{home,agent:job.agent,assignmentId:job.assignmentId,attempt:job.attempt,epoch:job.epoch,workerId,image,sessionId:null,labels,log:openLog(job),turns:0});
         return workspace;
       },
       async finish(args) { try { return await baseHandoff.finish(args); } finally { cleanupSession(args.workspace); } },
@@ -151,13 +162,17 @@ export async function runFleetCli(argv, { callTool, env = process.env, out = con
       const credentialEnv = workerCredentialKeys(turn.agent, env);
       const name = `aidlc-worker-${randomUUID()}`;
       let started = false;
+      session.turns += 1;
+      session.log?.turnStart(name, session.turns);
       try {
         const result = await runAgentTurn({...turn, root:"/workspace", env, spawnProcess: (command,args,options) => {
-          const invocation=workerDockerInvocation({workspace:turn.root,image,command,args,credentialEnv,hostEnv:env,uid,gid,sessionHome:session.home});
+          const invocation=workerDockerInvocation({workspace:turn.root,image,command,args,credentialEnv,hostEnv:env,uid,gid,sessionHome:session.home,labels:session.labels});
           const dockerArgs=invocation.args.filter((arg,index) => !(index===1 && arg==="--rm"));
           dockerArgs.splice(1,0,"--name",name);
           started = true;
-          return spawn(invocation.command,dockerArgs,{...options,cwd:turn.root,env:invocation.env});
+          const child = spawn(invocation.command,dockerArgs,{...options,cwd:turn.root,env:invocation.env});
+          if (session.log) { session.log.tee(child); child.once("close", (code) => session.log.turnEnd(code)); }
+          return child;
         }});
         session.sessionId=result.sessionId;
         return result;
@@ -179,7 +194,7 @@ export async function runFleetCli(argv, { callTool, env = process.env, out = con
         "Complete the scoped item and report remaining risks. The supervisor handles the Git commit and push. End the final answer with a Conventional Commits message on its own line as AI-DLC-COMMIT: type(scope): subject (for example AI-DLC-COMMIT: docs(ui): add web UI improvement proposal), followed by AI-DLC-ITEM-COMPLETE on its own line.",
         ...(env.AIDLC_FLEET_CODE_ONLY_RETRY === "1" ? ["This assignment is declared code-only: perform no external side effects beyond the supervisor's Git handoff."] : [])
       ].join("\n"), onEvent: emit }); }
-      finally { for (const [workspace, entry] of sessions) { rmSync(entry.home,{recursive:true,force:true}); sessions.delete(workspace); } }
+      finally { for (const [workspace, entry] of sessions) dropSession(workspace, entry); }
       emit(result);
       if (once || result.status === "stopped") return result;
       await pause(pollMs, signal, cancelSignal);

package/dist/assets/.agents/aidlc/scripts/lib/loop-fleet-remote.mjs

@@ -1,11 +1,20 @@
 import { randomUUID } from "node:crypto";
+import { explainFleetConflict } from "./loop-holder.mjs";
 
 const idempotency = () => randomUUID();
 
 /** Map the coordination service's versioned MCP tools to the headless runner. */
 export function createFleetRemoteRepository({ callTool, url, token, workspace, root, workerId }) {
   if (typeof callTool !== "function" || !url || !token || !workspace || !root) throw new Error("Fleet remote requires MCP callTool, URL, token, workspace, and project root");
-  const call = (name, args) => callTool({ url, token, name, args: { workspace, ...args } });
+  // A FleetConflict keeps its code/current for retry logic; its message gains
+  // a lease/claim explanation and the inspect command (original kept in parentheses).
+  const call = async (name, args) => {
+    try { return await callTool({ url, token, name, args: { workspace, ...args } }); }
+    catch (error) {
+      if (error?.code === "FLEET_CONFLICT" && typeof error.message === "string") error.message = explainFleetConflict(error.message);
+      throw error;
+    }
+  };
   let ownerToken;
   let supervisorToken, supervisorEpoch, supervisorTask;
   const fleet = () => call("fleet_get", {});

package/dist/assets/.agents/aidlc/scripts/lib/loop-fleet-supervisor.mjs

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { setTimeout as sleep } from "node:timers/promises";
+import { explainFleetConflict } from "./loop-holder.mjs";
 import { runFleetCoordinator, validateFleetLimits } from "./loop-fleet.mjs";
 
 const taskDigest = (task) => createHash("sha256").update(JSON.stringify(task)).digest("hex");
@@ -65,7 +66,7 @@ export async function runFleetSupervisor({ repository, taskId, limits: inputLimi
       await onEvent({ type: "gate", taskId, gate: result.gate, snapshotId: result.snapshotId, gateView: result.gateView });
       if (untilStop) return { status: "gate", taskId, gate: result.gate, snapshotId: result.snapshotId, gateView: result.gateView };
     }
-    if (failure) throw new Error(`Supervisor lease renewal failed: ${failure.message}`);
+    if (failure) throw new Error(`Supervisor lease renewal failed: ${explainFleetConflict(failure.message)}`);
     return { status: "stopped", taskId };
   } finally {
     clearInterval(timer); await pending;

package/dist/assets/.agents/aidlc/scripts/lib/loop-fleet.mjs

@@ -5,6 +5,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readyTaskItems, formatGateView, pathsOverlap } from "./store.mjs";
 import { isLoopProvider, LOOP_PROVIDER_LIST } from "./loop-drivers.mjs";
+import { explainFleetConflict, LEASES_COMMAND } from "./loop-holder.mjs";
 
 export const FLEET_LIMITS = Object.freeze({ maxTurns: 12, turnTimeoutMs: 600_000, maxStallTurns: 2, maxWorkers: 4, leaseMs: 300_000, heartbeatMs: 60_000 });
 const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
@@ -111,7 +112,7 @@ async function withHeartbeat(renew, intervalMs, work) {
   try {
     const result = await work(abort.signal);
     await pending;
-    if (failure) throw new Error(`Fleet lease renewal failed: ${failure.message}`);
+    if (failure) throw new Error(`Fleet lease renewal failed: ${explainFleetConflict(failure.message)}`);
     return result;
   } finally { clearInterval(timer); await pending; }
 }
@@ -155,7 +156,7 @@ export async function runFleetCoordinator({ repository, taskId, ownerId = random
       const stopping = () => Boolean(stopSignal?.aborted || cancelSignal?.aborted);
       const stopped = (reason) => ({ status: "stopped", taskId, reason, revision: snapshot.revision });
       for (;;) {
-        if (leaseLost.aborted) throw new Error("Lead lease renewal failed");
+        if (leaseLost.aborted) throw new Error(`Lead lease renewal failed: the lead lease (run_claim, lead epoch ${epoch}) for ${taskId} could not be renewed or the supervisor lease was lost; another lead may have taken over or the coordination service is unreachable. Inspect: ${LEASES_COMMAND} ${taskId}`);
         if (stopping()) return stopped(cancelSignal?.aborted ? "cancel requested" : "stop requested");
         if (Date.now() - startedAt >= limits.maxTurns * limits.turnTimeoutMs) return { status: "paused", taskId, reason: "coordinator wall-time limit reached" };
         snapshot = validateSnapshot(await readTask({ taskId }), taskId);

package/dist/assets/.agents/aidlc/scripts/lib/loop-git.mjs

@@ -79,13 +79,19 @@ function fetchBranch(root, remote, branch) {
 function ancestor(root, base, head) {
   try { git(root, "merge-base", "--is-ancestor", base, head); return true; } catch { return false; } /* intentional: non-git/non-worktree is treated as not clean */
 }
-// Host-local loop operational files (daemon lock/log, UI event sidecar) live in
-// the lead checkout but are never part of a handoff or integration.
+// Host-local loop operational files (daemon lock/log, UI event sidecar) and
+// per-task runtime data (worker container index and logs) live in the lead
+// checkout but are never part of a handoff or integration.
 const LOOP_OPERATIONAL_PREFIX = ".agents/data/loop/";
+const TASK_RUNTIME_PATTERN = /^\.agents\/data\/tasks\/[^/]+\/runtime\//;
+/** True for repository-relative paths the loop writes operationally
+ * (`.agents/data/loop/` and `.agents/data/tasks/<id>/runtime/`); such paths are
+ * ignored by clean checks and working-tree change snapshots. */
+export const isLoopOperationalPath = (path) => typeof path === "string" && (path.startsWith(LOOP_OPERATIONAL_PREFIX) || TASK_RUNTIME_PATTERN.test(path));
 function assertClean(root) {
   // Not via git(): its trim() would eat the leading status column of the first row.
   const status = execFileSync("git", ["status", "--porcelain=v1", "-z", "--no-renames", "--untracked-files=all"], { cwd: root, encoding: "utf8", timeout: 30_000, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
-  const dirty = status.split("\0").filter(Boolean).map((row) => row.slice(3)).filter((path) => !path.startsWith(LOOP_OPERATIONAL_PREFIX));
+  const dirty = status.split("\0").filter(Boolean).map((row) => row.slice(3)).filter((path) => !isLoopOperationalPath(path));
   if (dirty.length) throw new Error("Git worktree must be clean before handoff or integration");
 }
 function normaliseReport(job) {