@uchibeke/gallivant 0.0.0-stage → 0.2.0

package/lib/task_environment.mjs

@@ -0,0 +1,281 @@
+// Preparation receives a deliberately small environment. Native provider profiles
+// remain available, without granting the operator's HOME or shared XDG roots.
+import { homedir } from "node:os";
+import { join, dirname, basename, resolve } from "node:path";
+import { existsSync, lstatSync, realpathSync, rmSync, statSync, readdirSync, copyFileSync, chmodSync, mkdtempSync, renameSync, readFileSync, writeFileSync } from "node:fs";
+import { adapterFor } from "./harness.mjs";
+import { ensureDir } from "./fs.mjs";
+import { isInside } from "./config.mjs";
+import { runEnv } from "./git.mjs";
+import { taskError } from "./task_store.mjs";
+
+const BASICS = ["PATH", "USER", "LOGNAME", "LANG", "LC_ALL", "LC_CTYPE", "TZ", "TERM", "COLORTERM", "NO_COLOR", "FORCE_COLOR", "SSL_CERT_FILE", "SSL_CERT_DIR", "NODE_EXTRA_CA_CERTS", "HTTPS_PROXY", "HTTP_PROXY", "ALL_PROXY", "NO_PROXY"];
+const AWS_AUTH = ["AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN", "AWS_REGION", "AWS_DEFAULT_REGION", "AWS_PROFILE", "AWS_CONFIG_FILE", "AWS_SHARED_CREDENTIALS_FILE", "AWS_WEB_IDENTITY_TOKEN_FILE", "AWS_ROLE_ARN"];
+const GOOGLE_AUTH = ["GOOGLE_APPLICATION_CREDENTIALS", "GOOGLE_CLOUD_PROJECT", "GOOGLE_CLOUD_LOCATION", "CLOUD_ML_REGION", "ANTHROPIC_VERTEX_PROJECT_ID"];
+const FOUNDRY_AUTH = ["ANTHROPIC_FOUNDRY_RESOURCE", "ANTHROPIC_FOUNDRY_BASE_URL", "ANTHROPIC_FOUNDRY_API_KEY", "ANTHROPIC_FOUNDRY_AUTH_TOKEN"];
+const CLAUDE_DIRECT_AUTH = ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"];
+const CLAUDE_MODES = ["BEDROCK", "VERTEX", "FOUNDRY"];
+const claudeMode = env => {
+  const selected = CLAUDE_MODES.filter(mode => /^(?:1|true|yes|on)$/i.test(env[`CLAUDE_CODE_USE_${mode}`] || ""));
+  if (selected.length > 1 || CLAUDE_MODES.some(mode => !/^(?:1|true|yes|on|0|false|no|off)?$/i.test(env[`CLAUDE_CODE_USE_${mode}`] || ""))) {
+    throw taskError("TASK_PREPARATION_ENV", "select exactly one Claude cloud mode, or disable all cloud modes for direct authentication; retain the configured provider before preparation");
+  }
+  return selected[0] || "DIRECT";
+};
+const GOOSE_AUTH = {
+  openai: ["OPENAI_API_KEY", "OPENAI_HOST"], anthropic: ["ANTHROPIC_API_KEY"], google: ["GOOGLE_API_KEY"],
+  openrouter: ["OPENROUTER_API_KEY"], xai: ["XAI_API_KEY"], deepseek: ["DEEPSEEK_API_KEY"], mistral: ["MISTRAL_API_KEY"],
+  meta: ["META_MODEL_API_KEY"], alibaba: ["DASHSCOPE_API_KEY"], azure_openai: ["AZURE_OPENAI_API_KEY", "AZURE_OPENAI_ENDPOINT"], bedrock: [],
+};
+const pick = (source, keys) => Object.fromEntries(keys.filter(k => typeof source[k] === "string").map(k => [k, source[k]]));
+const AWS_KEYS = new Set(["aws_access_key_id", "aws_secret_access_key", "aws_session_token"]);
+const AWS_SETTINGS = new Set(["region", "output", "retry_mode", "max_attempts", "defaults_mode", "sts_regional_endpoints", "use_fips_endpoint", "use_dualstack_endpoint"]);
+const AWS_CHAINS = new Set(["source_profile", "credential_source", "credential_process", "role_arn", "role_session_name", "external_id", "mfa_serial", "duration_seconds", "web_identity_token_file", "sso_session", "sso_start_url", "sso_region", "sso_account_id", "sso_role_name"]);
+const awsFailure = () => taskError("TASK_PREPARATION_ENV", "selected AWS profile cannot be isolated; provide temporary AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY credentials and AWS_REGION, or a dedicated static profile in AWS_CONFIG_FILE/AWS_SHARED_CREDENTIALS_FILE; credential chains and shared caches are not carried");
+
+// AWS files can contain credentials for many accounts. Render only the selected
+// flat profile, never comments, other profiles, caches or unneeded auth settings.
+function awsProfile(text, section, config, direct) {
+  const values = new Map(); let selected = false, seen = false;
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || /^[#;]/.test(line)) continue;
+    const header = line.match(/^\[([^\]]+)\]\s*(?:[#;].*)?$/);
+    if (header) {
+      selected = header[1].trim() === section;
+      if (selected && seen) throw awsFailure();
+      seen ||= selected; continue;
+    }
+    if (!selected) continue;
+    const setting = line.match(/^(\w+)\s*=\s*(.+)$/);
+    if (!setting || setting[2].includes("\0")) throw awsFailure();
+    const [, key, value] = setting;
+    if (direct && (AWS_KEYS.has(key) || AWS_CHAINS.has(key))) continue;
+    if (!AWS_KEYS.has(key) && !(config && AWS_SETTINGS.has(key))) throw awsFailure();
+    if (values.has(key)) throw awsFailure();
+    values.set(key, value);
+  }
+  return values;
+}
+
+// Read only the native provider selector, leaving models and config bytes intact.
+// Complex YAML needs an explicit environment override rather than a guessed
+// provider that might expose the wrong credentials. Goose gives that override
+// precedence, then the current active_provider key, then its legacy flat key.
+function gooseProvider(text) {
+  const fail = () => taskError("TASK_PREPARATION_ENV", "Goose provider selection cannot be resolved from its config; set GOOSE_PROVIDER explicitly to the configured provider before preparation");
+  const lines = []; let header = false, ended = false;
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    if (line === "---" && !header && !lines.length) { header = true; continue; }
+    if (line === "..." && !ended) { ended = true; continue; }
+    if (ended || line === "---" || /[\t\0]/.test(raw)) throw fail();
+    lines.push(raw);
+  }
+  const indent = Math.min(...lines.map(line => line.length - line.trimStart().length));
+  const providers = new Map();
+  for (const raw of lines) {
+    if (raw.length - raw.trimStart().length !== indent) continue;
+    const setting = raw.trim().match(/^([\w-]+|"[\w-]+"|'[\w-]+') *:(?:\s+(.*)|$)/);
+    if (!setting) throw fail();
+    const key = setting[1].replace(/^["']|["']$/g, "");
+    if (!["active_provider", "GOOSE_PROVIDER"].includes(key)) continue;
+    const value = (setting[2] || "").match(/^([a-zA-Z][\w-]*|"[a-zA-Z][\w-]*"|'[a-zA-Z][\w-]*')\s*(?:#.*)?$/);
+    if (!value || providers.has(key)) throw fail();
+    providers.set(key, value[1].replace(/^["']|["']$/g, ""));
+  }
+  return providers.get("active_provider") ?? providers.get("GOOSE_PROVIDER");
+}
+
+export function preparationEnvironment(harness, cwd, adapterEnv, source = process.env, callerCwd = process.cwd()) {
+  const providerPath = path => resolve(callerCwd, path);
+  const nativeHome = providerPath(source.HOME || homedir());
+  const nativeConfig = providerPath(source.XDG_CONFIG_HOME || join(nativeHome, ".config"));
+  const nativeData = providerPath(source.XDG_DATA_HOME || join(nativeHome, ".local/share"));
+  const nativeState = providerPath(source.XDG_STATE_HOME || join(nativeHome, ".local/state"));
+  const home = ensureDir(join(cwd, "home"));
+  const config = ensureDir(join(home, ".config")), data = ensureDir(join(home, ".local/share")), state = ensureDir(join(home, ".local/state"));
+  const env = { ...pick(source, BASICS), ...pick(source, adapterFor(harness).preparationEnv), ...adapterEnv,
+    HOME: home, USERPROFILE: home, XDG_CONFIG_HOME: config, XDG_DATA_HOME: data, XDG_STATE_HOME: state, XDG_CACHE_HOME: ensureDir(join(home, ".cache")),
+    TMPDIR: ensureDir(join(cwd, "tmp")), TMP: join(cwd, "tmp"), TEMP: join(cwd, "tmp"),
+    ...runEnv(), GIT_TERMINAL_PROMPT: "0", GIT_ALLOW_PROTOCOL: "", GIT_SSH_COMMAND: "false", GH_CONFIG_DIR: "/dev/null", GH_PROMPT_DISABLED: "1" };
+  // All selected files and directories are private snapshots. Native links would
+  // permit writes to operator files or traversal into their parents. Materialize
+  // internal resource links, refuse escaping ones, and publish only complete copies.
+  const snapshot = (root, to) => {
+    const temporary = mkdtempSync(join(dirname(to), ".profile-copy-"));
+    const entry = join(temporary, "entry");
+    const ancestors = new Set();
+    const copy = (from, target) => {
+      let resolved;
+      try { resolved = realpathSync(from); }
+      catch { throw taskError("TASK_PREPARATION_ENV", "provider resource cannot be resolved; check permissions and remove broken or cyclic links before preparation"); }
+      if (!isInside(resolved, root)) throw taskError("TASK_PREPARATION_ENV", "provider resource link leaves its selected directory; move the linked resource inside that directory");
+      const info = statSync(resolved);
+      if (info.isDirectory()) {
+        if (ancestors.has(resolved)) throw taskError("TASK_PREPARATION_ENV", "provider resource contains a directory link cycle; remove the cycle before preparation");
+        ancestors.add(resolved); ensureDir(target);
+        try { for (const name of readdirSync(resolved)) copy(join(resolved, name), join(target, name)); }
+        finally { ancestors.delete(resolved); }
+      } else if (info.isFile()) {
+        copyFileSync(resolved, target); chmodSync(target, info.mode & 0o777);
+      } else throw taskError("TASK_PREPARATION_ENV", "provider resource contains a special file; use only regular files and directories");
+    };
+    try { copy(root, entry); renameSync(entry, to); }
+    finally { rmSync(temporary, { recursive: true, force: true }); }
+  };
+  const selectedResource = from => {
+    let entry;
+    try { entry = lstatSync(from); }
+    catch (error) {
+      if (error.code !== "ENOENT") throw taskError("TASK_PREPARATION_ENV", "provider resource cannot be read; check its permissions before preparation");
+      return null;
+    }
+    // Resolve nested links only after the selected entry has established its own
+    // boundary. An entry alias could otherwise select unrelated native secrets.
+    if (entry.isSymbolicLink()) throw taskError("TASK_PREPARATION_ENV", "selected provider entry is a symbolic link; replace it with a regular file or directory before preparation");
+    const root = realpathSync(from);
+    if (isInside(realpathSync(nativeHome), root)) throw taskError("TASK_PREPARATION_ENV", "provider profile contains the operator home; configure a dedicated provider profile directory");
+    if (isInside(root, realpathSync(home))) throw taskError("TASK_PREPARATION_ENV", "provider profile overlaps the private preparation home; configure a provider profile outside the draft workspace");
+    return root;
+  };
+  const carry = (from, to) => {
+    const root = selectedResource(from);
+    if (!root) { rmSync(to, { recursive: true, force: true }); return; }
+    ensureDir(dirname(to)); rmSync(to, { recursive: true, force: true });
+    snapshot(root, to);
+  };
+  const clearAws = () => {
+    rmSync(join(home, ".aws"), { recursive: true, force: true });
+    for (const key of ["AWS_CONFIG_FILE", "AWS_SHARED_CREDENTIALS_FILE", "AWS_WEB_IDENTITY_TOKEN_FILE"]) rmSync(join(home, ".provider-files", key), { recursive: true, force: true });
+  };
+  const aws = () => {
+    // Remove old material even if validation stops this rebuilt turn.
+    clearAws();
+    Object.assign(env, pick(source, AWS_AUTH));
+    const name = env.AWS_PROFILE || "default";
+    if (!/^[\w.-]+$/.test(name)) throw awsFailure();
+    const staticEnv = Boolean(env.AWS_ACCESS_KEY_ID && env.AWS_SECRET_ACCESS_KEY);
+    const direct = staticEnv || Boolean(env.AWS_ROLE_ARN && env.AWS_WEB_IDENTITY_TOKEN_FILE);
+    if (staticEnv) { delete env.AWS_ROLE_ARN; delete env.AWS_WEB_IDENTITY_TOKEN_FILE; }
+    const nativeAws = join(nativeHome, ".aws");
+    const needsConfig = Boolean(env.AWS_CONFIG_FILE || !direct || !(env.AWS_REGION || env.AWS_DEFAULT_REGION));
+    // Inspect the default directory boundary too; file-level checks alone would
+    // otherwise resolve an alias of the whole native AWS directory.
+    if (needsConfig && !env.AWS_CONFIG_FILE || !direct && !env.AWS_SHARED_CREDENTIALS_FILE) {
+      const root = selectedResource(nativeAws);
+      if (root && !statSync(root).isDirectory()) throw awsFailure();
+    }
+    const read = (key, filename, configFile) => {
+      const from = providerPath(env[key] || join(nativeAws, filename));
+      const root = selectedResource(from);
+      if (!root) { if (env[key]) throw taskError("TASK_PREPARATION_ENV", `selected provider file ${key} must name a readable regular file`); return new Map(); }
+      if (!statSync(root).isFile()) throw taskError("TASK_PREPARATION_ENV", `selected provider file ${key} must name a readable regular file`);
+      return awsProfile(readFileSync(root, "utf8"), configFile && name !== "default" ? `profile ${name}` : name, configFile, direct);
+    };
+    const settings = needsConfig ? read("AWS_CONFIG_FILE", "config", true) : new Map();
+    // SDKs that prioritize AWS_PROFILE must still resolve the same explicit
+    // environment identity, without reading an additional native account.
+    const credentials = staticEnv && env.AWS_PROFILE ? new Map([...AWS_KEYS].flatMap(key => {
+      const value = env[key.toUpperCase()]; return value ? [[key, value]] : [];
+    })) : direct ? new Map() : read("AWS_SHARED_CREDENTIALS_FILE", "credentials", false);
+    const combined = new Map([...settings, ...credentials]);
+    if (!direct && !(combined.get("aws_access_key_id") && combined.get("aws_secret_access_key"))) throw awsFailure();
+    if (credentials.get("aws_access_key_id") && credentials.get("aws_secret_access_key")) {
+      // The credentials file wins over config credentials for this profile.
+      // Do not expose an older identity that the selected SDK will not need.
+      for (const key of credentials.keys()) settings.delete(key);
+    }
+    if (env.AWS_WEB_IDENTITY_TOKEN_FILE) {
+      const root = selectedResource(providerPath(env.AWS_WEB_IDENTITY_TOKEN_FILE));
+      if (!root || !statSync(root).isFile()) throw taskError("TASK_PREPARATION_ENV", "selected provider file AWS_WEB_IDENTITY_TOKEN_FILE must name a readable regular file");
+    }
+    // Only validated selected material is published. Remove pre-fix directory
+    // snapshots and explicit-file copies, including caches and other profiles.
+    const target = ensureDir(join(home, ".aws"));
+    for (const [key, filename, values, section] of [["AWS_CONFIG_FILE", "config", settings, name === "default" ? name : `profile ${name}`], ["AWS_SHARED_CREDENTIALS_FILE", "credentials", credentials, name]]) {
+      env[key] = join(target, filename);
+      writeFileSync(env[key], values.size ? `[${section}]\n${[...values].map(([k, v]) => `${k} = ${v}`).join("\n")}\n` : "", { mode: 0o600 });
+    }
+  };
+  const profile = (from, to, names) => {
+    ensureDir(to);
+    for (const name of names) carry(join(from, name), join(to, name));
+  };
+  const googleAdc = () => carry(join(nativeConfig, "gcloud/application_default_credentials.json"), join(config, "gcloud/application_default_credentials.json"));
+  if (harness === "codex") {
+    env.CODEX_HOME = join(home, ".codex");
+    profile(providerPath(source.CODEX_HOME || join(nativeHome, ".codex")), env.CODEX_HOME, ["auth.json", "config.toml", "managed_config.toml", "requirements.toml", "hooks.json", "rules", "plugins", "skills"]);
+  } else if (harness === "claude") {
+    env.CLAUDE_CONFIG_DIR = join(home, ".claude");
+    const from = providerPath(source.CLAUDE_CONFIG_DIR || join(nativeHome, ".claude"));
+    // Refuse native/private overlap before cleanup could remove selected files.
+    selectedResource(from);
+    // Clear prior identities before resolving a rebuilt turn, including refusals.
+    // Neither shell allowlists nor a private HOME select a provider by themselves.
+    for (const path of [".claude", ".claude.json", ".config/gcloud", ".provider-files/GOOGLE_APPLICATION_CREDENTIALS"]) rmSync(join(home, path), { recursive: true, force: true });
+    clearAws();
+    for (const key of CLAUDE_DIRECT_AUTH) delete env[key];
+    const mode = claudeMode(env);
+    // Native settings can overwrite shell selectors and credentials. Do not
+    // guess precedence or carry an unselected secret through that second input.
+    // Dedicated profiles with exported auth retain model/permission bytes.
+    const settings = selectedResource(join(from, "settings.json"));
+    if (settings) {
+      const fail = () => taskError("TASK_PREPARATION_ENV", "Claude settings authentication cannot be isolated; export the configured mode and credentials and use a dedicated Claude profile without provider/authentication env overrides before preparation");
+      let parsed;
+      try { parsed = JSON.parse(readFileSync(settings, "utf8")); } catch { throw fail(); }
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || parsed.env && (typeof parsed.env !== "object" || Array.isArray(parsed.env))) throw fail();
+      const authKeys = [...CLAUDE_DIRECT_AUTH, ...AWS_AUTH, ...GOOGLE_AUTH, ...FOUNDRY_AUTH, ...CLAUDE_MODES.map(name => `CLAUDE_CODE_USE_${name}`)];
+      if (authKeys.some(key => Object.hasOwn(parsed.env || {}, key))) throw fail();
+    }
+    profile(from, env.CLAUDE_CONFIG_DIR, ["settings.json", "plugins", "rules", "skills", "agents"]);
+    if (mode === "DIRECT") {
+      Object.assign(env, pick(source, CLAUDE_DIRECT_AUTH));
+      carry(join(from, ".credentials.json"), join(env.CLAUDE_CONFIG_DIR, ".credentials.json"));
+      carry(join(nativeHome, ".claude.json"), join(home, ".claude.json"));
+    }
+    if (mode === "BEDROCK") aws();
+    if (mode === "VERTEX") {
+      Object.assign(env, pick(source, GOOGLE_AUTH)); googleAdc();
+    }
+    if (mode === "FOUNDRY") Object.assign(env, pick(source, FOUNDRY_AUTH));
+  } else if (harness === "gemini") {
+    profile(join(nativeHome, ".gemini"), join(home, ".gemini"), ["settings.json", "oauth_creds.json", "google_accounts.json", "policies", "policy_integrity.json", "extensions", "skills", "agents", "commands"]);
+    if (source.GOOGLE_GENAI_USE_VERTEXAI === "true") googleAdc();
+  } else if (harness === "opencode") {
+    profile(providerPath(source.OPENCODE_CONFIG_DIR || join(nativeConfig, "opencode")), join(config, "opencode"), ["opencode.json", "opencode.jsonc", "config.json", "package.json", "node_modules", "agents", "commands", "plugins", "skills", "tools"]);
+    env.OPENCODE_CONFIG_DIR = join(config, "opencode");
+    carry(join(nativeData, "opencode/auth.json"), join(data, "opencode/auth.json"));
+    carry(join(nativeState, "opencode/model.json"), join(state, "opencode/model.json"));
+  } else if (harness === "goose") {
+    // Rebuilding a turn must not retain AWS files from an earlier selection,
+    // including when the new config cannot safely identify its provider.
+    clearAws();
+    // A shared secrets file/keyring may contain every provider's credentials.
+    // Never copy it, including legacy snapshots in a reopened private profile.
+    rmSync(join(config, "goose/secrets.yaml"), { recursive: true, force: true });
+    profile(join(nativeConfig, "goose"), join(config, "goose"), ["config.yaml"]);
+    const file = join(config, "goose/config.yaml");
+    const provider = env.GOOSE_PROVIDER ?? (existsSync(file) ? gooseProvider(readFileSync(file, "utf8")) : undefined);
+    if (!Object.hasOwn(GOOSE_AUTH, provider)) throw taskError("TASK_PREPARATION_ENV", "Goose provider is missing or unsupported for isolated authentication; set GOOSE_PROVIDER to the configured supported provider and export only its credentials before preparation");
+    Object.assign(env, pick(source, GOOSE_AUTH[provider]));
+    env.GOOSE_DISABLE_KEYRING = "1";
+    if (provider !== "bedrock" && !env[GOOSE_AUTH[provider][0]] && existsSync(join(nativeConfig, "goose/secrets.yaml"))) {
+      throw taskError("TASK_PREPARATION_ENV", `Goose shared secret storage is not carried; export ${GOOSE_AUTH[provider][0]} for the selected provider before preparation`);
+    }
+    if (provider === "bedrock") aws();
+  }
+  // Explicit provider file settings must use the same detached bytes as native
+  // profile files; forwarding their native paths would retain writable aliases.
+  for (const key of ["GOOGLE_APPLICATION_CREDENTIALS", "AWS_WEB_IDENTITY_TOKEN_FILE", "OPENCODE_CONFIG"]) {
+    if (!env[key]) continue;
+    const from = providerPath(env[key]);
+    if (!existsSync(from) || !statSync(from).isFile()) throw taskError("TASK_PREPARATION_ENV", `selected provider file ${key} must name a readable regular file`);
+    const to = join(home, ".provider-files", key, basename(from));
+    carry(from, to);
+    env[key] = to;
+  }
+  return env;
+}

package/lib/task_prepare.mjs

@@ -0,0 +1,224 @@
+// Uses the same adapter and durable runner as implementation. There is no model
+// client here. A lost launch acknowledgement is reconciled, never blindly retried.
+import { join } from "node:path";
+import { buildPreparationRun, capabilitiesFor, isPreparationReceipt, adapterFor } from "./harness.mjs";
+import { prepareLocalExecution } from "./execution_preparation.mjs";
+import { taskRoot, taskError } from "./task_store.mjs";
+import { draftPrompt, MAX_TURNS, MAX_PREPARATION_PROMPT_BYTES } from "./task_contract.mjs";
+import { executionRunner } from "./execution.mjs";
+import { redact } from "./execution_io.mjs";
+
+export const PREPARATION_PENDING = Symbol("preparation-pending");
+// Only this pre-submit call site may issue this recovery marker. A transport
+// timeout after submit has uncertain ownership and must reconcile its saved run.
+export const preparationPreflightRetryable = task => task.errorCode === "EXECUTION_DEADLINE"
+  && task.preflightFailure?.attemptCount === task.attempts.length
+  && task.preflightFailure?.code === "EXECUTION_DEADLINE"
+  && task.attempts.every(attempt => attempt.settled && attempt.consumed)
+  && !task.dispatchIntent && !task.implementation;
+export const preparationCancellationPending = task => {
+  const attempt = task.attempts.at(-1);
+  return !!attempt && ((attempt.cancellation && !["confirmed", "terminal"].includes(attempt.cancellation.status)) ||
+    (attempt.execution?.transport === "remote" && attempt.execution.providerState === "cancellation-requested"));
+};
+
+const overDeadline = attempt => {
+  const endedAt = attempt.endedAt ?? (Number.isFinite(attempt.elapsedMs) ? attempt.startedAt + attempt.elapsedMs : null);
+  return Number.isFinite(endedAt) && endedAt > attempt.deadline;
+};
+const exhausted = (task, store, attempt) => {
+  attempt.settled = true;
+  attempt.ok = false;
+  attempt.errorCode = "TASK_ALLOWANCE";
+  attempt.error = "preparation runtime allowance exhausted";
+  store.save(task);
+  throw taskError(attempt.errorCode, attempt.error);
+};
+const failed = attempt => {
+  const reason = attempt.error || "saved preparation failed";
+  return taskError(attempt.errorCode || "TASK_PREPARATION_FAILED", attempt.errorCode ? reason : `preparation failed: ${reason}; inspect ${attempt.log || "the saved run log"}`);
+};
+
+const boundaryFailure = () => taskError("TASK_PREPARATION_BOUNDARY", "saved preparation used an unverified tool boundary; its output cannot authorize readiness or dispatch; use a hand-authored PRD with ready/start until an isolated preparation adapter is supported");
+const safeAttempt = (task, attempt, capabilities, account) => isPreparationReceipt(task.harness, attempt.receipt ?? attempt.boundary, capabilities, account)
+  && (!attempt.receipt?.taskId || attempt.receipt.taskId === `intake/${task.id}`);
+export function assertPreparationBoundary(task, ctx = {}) {
+  const capabilities = ctx.capabilitiesFor?.(task.harness) || capabilitiesFor(task.harness);
+  const account = ctx.config?.harness[task.harness]?.account || "operator";
+  if (task.attempts.some(a => a.ok && !safeAttempt(task, a, capabilities, account))) throw boundaryFailure();
+}
+
+// The builder injection is for offline runner fixtures, just like the service's
+// existing prepare injection. Configuration cannot override the native boundary.
+export async function prepareTurn(ctx, task, store, failures, build = buildPreparationRun) {
+  const runner = executionRunner(ctx, `intake/${task.id}`, task.harness);
+  const capabilities = runner.capabilities || ctx.capabilitiesFor?.(task.harness) || capabilitiesFor(task.harness);
+  const account = runner.account || ctx.config.harness[task.harness]?.account || "operator";
+  const remote = capabilities.transport === "remote";
+  const adapter = remote ? null : adapterFor(task.harness);
+  let attempt = task.attempts.at(-1);
+  const stopping = preparationCancellationPending(task);
+  // A crash after recording output but before rendering its draft must replay
+  // those bytes, not purchase another planning turn.
+  if (attempt?.settled && !attempt.consumed && !stopping) {
+    if (overDeadline(attempt)) exhausted(task, store, attempt);
+    if (!attempt.ok) throw failed(attempt);
+    assertPreparationBoundary(task, ctx);
+    return attempt.message;
+  }
+  if ((!attempt || attempt.settled) && !stopping) {
+    if (task.attempts.length >= MAX_TURNS) throw taskError("TASK_ALLOWANCE", `preparation stopped after ${MAX_TURNS} turns; inspect the unresolved requirements`);
+    const usedMs = task.attempts.reduce((n, a) => n + (a.elapsedMs || 0), 0);
+    const remainingMs = task.allowance.runtimeMs - usedMs;
+    const knownCost = task.attempts.reduce((n, a) => n + Math.max(a.cost ?? 0, a.reservedUsd ?? 0), 0);
+    if (remainingMs <= 0 || knownCost >= task.allowance.budgetUsd) throw taskError("TASK_ALLOWANCE", "preparation allowance exhausted; inspect the saved evidence before granting further work");
+    const cwd = join(taskRoot(ctx.home, task.id), "preparation", `turn-${task.attempts.length + 1}`);
+    const config = { ...ctx.config, max_budget_usd: task.allowance.budgetUsd - knownCost };
+    // Selected documents are already in the prompt. Global implementation read
+    // grants do not belong to preparation, even when the operator configured them.
+    // Older version-1 records did not save the invocation directory. Their
+    // checkout is the durable fallback, never the directory of a later resume.
+    task.callerCwd ??= task.checkout;
+    const prompt = draftPrompt(task, failures);
+    if (Buffer.byteLength(prompt) > MAX_PREPARATION_PROMPT_BYTES) throw taskError("TASK_INPUT", `serialized preparation prompt exceeds ${MAX_PREPARATION_PROMPT_BYTES} bytes; select fewer or smaller context files, or prepare a smaller task; saved requirements were retained`);
+    const environment = remote ? capabilities.preparation?.environment : "isolated-checkout";
+    const reservedUsd = remote ? Math.min(config.max_budget_usd, task.allowance.budgetUsd / MAX_TURNS) : null;
+    const allowance = remote ? { remainingUsd: config.max_budget_usd, reservedUsd } : null;
+    const input = { kind: "intake", environment, prompt, ...(remote ? { allowance } : { config, cwd, sourceEnv: ctx.env, callerCwd: task.callerCwd }) };
+    let prepared;
+    delete task.preflightFailure;
+    try {
+      prepared = runner.prepare ? await runner.prepare(input, { build }) : await prepareLocalExecution(task.harness, capabilities, account, input, build);
+    } catch (error) {
+      if (remote && error.code === "EXECUTION_DEADLINE") {
+        // block() records the transport failure separately. Keep the invalid
+        // draft's feedback for this already-counted repair across every retry.
+        task.preflightFailure = { code: error.code, attemptCount: task.attempts.length, validationFailures: [...failures] };
+        store.save(task);
+      }
+      throw error;
+    }
+    if (!isPreparationReceipt(task.harness, prepared.receipt, capabilities, account)) throw boundaryFailure();
+    attempt = { name: `prepare-${task.attempts.length + 1}`, boundary: prepared.receipt.boundary, receipt: prepared.receipt, reservedUsd, startedAt: Date.now(), deadline: Date.now() + remainingMs, cwd, run: null, settled: false, cost: null, usage: null };
+    task.attempts.push(attempt);
+    task.status = "preparing";
+    store.save(task); // Intent precedes spawn; unknown acceptance never authorizes a second call.
+    const dispatch = { kind: "intake", preparation: prepared.receipt, operationId: attempt.name, name: attempt.name, environment };
+    try {
+      const job = runner.submit ? await runner.submit({ ...dispatch, ...(remote ? { prompt, prepared, allowance } : { spec: prepared.spec }) })
+        : await runner.start(attempt.name, prepared.spec.cmd, prepared.spec.args, { ...prepared.spec.options, execution: dispatch });
+      attempt.run = job.id;
+    } catch (error) {
+      const owned = runner.current();
+      if (!remote || owned?.name !== attempt.name || owned.execution?.acceptance !== "unknown") throw error;
+      attempt.run = owned.id; // Lost acknowledgement remains unresolved, never retried.
+    }
+    store.save(task);
+  }
+  let current = runner.current();
+  if (remote) {
+    await runner.reconcile(); // One bounded, persisted-cadence mutation; inspect/list never poll.
+    current = runner.current();
+  }
+  if (!attempt.run) {
+    if (!current || current.name !== attempt.name) throw taskError("TASK_PREPARATION_UNKNOWN", "preparation launch acceptance is unknown; inspect the intake run directory before retrying; no new model call was made");
+    attempt.run = current.id;
+    store.save(task);
+  }
+  if (!current || current.id !== attempt.run) throw taskError("TASK_PREPARATION_UNKNOWN", "recorded preparation run is missing or has changed; inspect its artifacts; no new model call was made");
+  const unsafe = !safeAttempt(task, attempt, capabilities, account);
+  if (remote) {
+    attempt.execution = current.execution;
+    const completed = ["succeeded", "failed"].includes(current.execution.terminalState) ||
+      (current.execution.collected && ["succeeded", "failed"].includes(current.execution.providerState));
+    if (stopping || unsafe || (!completed && Date.now() >= attempt.deadline)) {
+      attempt.cancellation ??= { reason: current.execution.cancellation?.reason || (unsafe ? "unsafe-preparation" : "preparation-timeout"), requestedAt: Date.now(), status: "intent" };
+      attempt.settled = false; task.status = "preparing"; task.readiness = null;
+      store.save(task);
+      // Once fenced, only the boundary's persisted cadence retries cancellation.
+      // An intent whose fence was not saved may retry the same owned control.
+      if (!runner.state().stopped) {
+        try { await runner.cancel(attempt.cancellation.reason); }
+        catch (error) { attempt.recoveryAction = runner.sanitize ? runner.sanitize(error.message, attempt.run) : redact(error.message); }
+      }
+      current = runner.current();
+      if (!current || current.id !== attempt.run) throw taskError("TASK_PREPARATION_UNKNOWN", "cancellation ownership changed; restore the recorded intake run before reconciliation");
+      attempt.execution = current.execution;
+      attempt.cancellation.status = "pending";
+      if (current.running) {
+        attempt.recoveryAction = current.execution.recoveryAction || "resume owned preparation cancellation; no new turn is authorized";
+        task.failures = [attempt.recoveryAction]; store.save(task); return PREPARATION_PENDING;
+      }
+      attempt.cancellation.status = current.execution.providerState === "cancelled" ? "confirmed" : "terminal";
+      attempt.cancellation.confirmedAt = Date.now(); attempt.recoveryAction = null;
+      attempt.endedAt = current.endedAt ?? Date.now(); attempt.elapsedMs = Math.max(0, attempt.endedAt - attempt.startedAt);
+      attempt.cost = current.execution.costUsd ?? null;
+      store.save(task);
+      if (attempt.cancellation.reason === "unsafe-preparation") { attempt.settled = true; store.save(task); throw boundaryFailure(); }
+      exhausted(task, store, attempt);
+    }
+    if (current.execution.providerState === "retrieving-results" || completed) {
+      try { await runner.collect(); } catch (error) {
+        if (error.code !== "EXECUTION_RESULT" && error.code !== "EXECUTION_DEADLINE") throw error;
+        attempt.recoveryAction = error.message;
+        attempt.execution = runner.current().execution; store.save(task); return PREPARATION_PENDING;
+      }
+      current = runner.current();
+    }
+    attempt.execution = current.execution;
+    store.save(task);
+    if (current.running) return PREPARATION_PENDING; // Authoritative completion/results are still pending.
+    if (current.execution.quarantined || current.execution.providerState === "cancelled") throw taskError("TASK_PREPARATION_FAILED", "preparation cancelled; late output cannot authorize readiness");
+  }
+  if (unsafe && current.running) {
+    runner.kill(attempt.run);
+    await runner.waitForKill?.(attempt.run);
+    current = runner.current();
+    if (!current || current.id !== attempt.run || current.running) throw taskError("TASK_PREPARATION_UNKNOWN", "unsafe preparation could not be stopped; inspect the owned run before any further work");
+  }
+  while (current.running) {
+    if (Date.now() >= attempt.deadline) {
+      runner.kill(attempt.run);
+      await runner.waitForKill?.(attempt.run);
+      attempt.endedAt = Date.now();
+      attempt.elapsedMs = Math.max(0, attempt.endedAt - attempt.startedAt);
+      exhausted(task, store, attempt);
+    }
+    await new Promise(resolve => setTimeout(resolve, 100));
+    current = runner.current();
+    if (!current || current.id !== attempt.run) throw taskError("TASK_PREPARATION_UNKNOWN", "preparation run ownership changed; inspect saved run artifacts");
+  }
+  const lines = remote ? [] : runner.lines(attempt.run);
+  let outcome = remote ? runner.outcome(attempt.run) : adapter.outcome(lines);
+  const job = remote ? current : runner.settle(attempt.run, () => outcome.ok ? 0 : 1);
+  if (!job || job.id !== attempt.run || job.running) throw taskError("TASK_PREPARATION_UNKNOWN", "preparation completion ownership changed; inspect its saved run; no output was accepted");
+  outcome = runner.outcome?.(attempt.run) || outcome; // Reuse the boundary's redacted result.
+  attempt.settled = true;
+  // A detached child may finish while the coordinator is gone. Use the recorded
+  // completion time; if unavailable, settlement time is a conservative bound.
+  attempt.endedAt = Number.isFinite(job.endedAt) ? job.endedAt : Date.now();
+  attempt.completionInferred = job.completionInferred === true || job.inferred === true || !Number.isFinite(job.endedAt);
+  attempt.elapsedMs = Math.max(0, attempt.endedAt - attempt.startedAt);
+  attempt.session = remote ? current.execution.sessionId : runner.sessionFrom ? runner.sessionFrom(attempt.run) : adapter.sessionFrom(lines);
+  attempt.cost = outcome.cost;
+  const usage = remote ? runner.result(attempt.run)?.usage ?? null : lines.flatMap(line => { try { const event = JSON.parse(line); return event.usage ? [event.usage] : []; } catch { return []; } });
+  attempt.usage = runner.sanitize ? runner.sanitize(usage, attempt.run) : redact(usage);
+  attempt.log = join(runner.dirOf(attempt.run), "job.log");
+  attempt.message = outcome.lastMessage;
+  attempt.ok = job.exit === 0 && outcome.ok && !outcome.denials?.length;
+  // Adapter denials are already display strings, including any recorded
+  // guardrail reason. Persist them before blocking so settled replay says the
+  // same thing as the original failure, even when the process exited zero.
+  attempt.error = [outcome.error, ...(outcome.denials || [])].filter(Boolean).join("; ") || (attempt.ok ? null : `exit ${job.exit}`);
+  // Preserve usage/log evidence even when a completed/recovered run ran late.
+  // Such output cannot authorize readiness, implementation or another repair.
+  if (overDeadline(attempt)) exhausted(task, store, attempt);
+  if (unsafe && !outcome.denials?.length) {
+    attempt.ok = false;
+    attempt.errorCode = "TASK_PREPARATION_BOUNDARY";
+    attempt.error = [attempt.error, boundaryFailure().message].filter(Boolean).join("; ");
+  }
+  store.save(task);
+  if (!attempt.ok) throw failed(attempt);
+  return outcome.lastMessage;
+}

package/lib/task_store.mjs

@@ -0,0 +1,38 @@
+import { join } from "node:path";
+import { readdirSync, existsSync } from "node:fs";
+import { ensureDir, readJson, writeJsonAtomic } from "./fs.mjs";
+import { acquireProcessLock } from "./daemon.mjs";
+import { TASK_VERSION } from "./task_contract.mjs";
+
+export const taskError = (code, message) => Object.assign(new Error(message), { code, version: TASK_VERSION });
+export function taskRoot(home, id) {
+  if (!/^task-[a-f0-9]{24}$/.test(id)) throw taskError("TASK_INPUT", "task ID must be task- followed by 24 lowercase hex characters");
+  return join(home, "tasks", id);
+}
+
+export function taskStore(home) {
+  const read = id => {
+    const task = readJson(join(taskRoot(home, id), "intake.json"));
+    if (!task) throw taskError("TASK_NOT_FOUND", `no intake ${id}`);
+    if (task.version !== TASK_VERSION) throw taskError("TASK_VERSION", "unsupported task version; use a compatible package before reopening this intake");
+    return task;
+  };
+  return {
+    read,
+    save: task => writeJsonAtomic(join(taskRoot(home, task.id), "intake.json"), task),
+    list: () => {
+      let names;
+      try { names = readdirSync(join(home, "tasks")); } catch (e) { if (e.code === "ENOENT") return []; throw e; }
+      // A failed input check or crash before first save can leave an empty lock
+      // namespace. It is not an intake and must not break all task discovery.
+      return names.filter(n => /^task-[a-f0-9]{24}$/.test(n) && existsSync(join(home, "tasks", n, "intake.json"))).map(read);
+    },
+    locked: async (id, fn) => {
+      const root = ensureDir(taskRoot(home, id));
+      let lock;
+      try { lock = acquireProcessLock(join(root, "intake.lock"), "task intake"); }
+      catch (e) { throw taskError("TASK_BUSY", e.message); }
+      try { return await fn(); } finally { lock.release(); }
+    },
+  };
+}