@hasna/loops 0.4.1 → 0.4.2

package/dist/runner/index.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "@hasna/loops",
-  version: "0.4.1",
+  version: "0.4.2",
   description: "Persistent local loop and workflow runner for deterministic commands and headless AI coding agents",
   type: "module",
   main: "dist/index.js",
@@ -43,6 +43,22 @@ var package_default = {
     "./storage": {
       types: "./dist/lib/store.d.ts",
       import: "./dist/lib/store.js"
+    },
+    "./storage/contract": {
+      types: "./dist/lib/storage/contract.d.ts",
+      import: "./dist/lib/storage/contract.js"
+    },
+    "./storage/sqlite": {
+      types: "./dist/lib/storage/sqlite.d.ts",
+      import: "./dist/lib/storage/sqlite.js"
+    },
+    "./storage/postgres": {
+      types: "./dist/lib/storage/postgres.d.ts",
+      import: "./dist/lib/storage/postgres.js"
+    },
+    "./storage/postgres-schema": {
+      types: "./dist/lib/storage/postgres-schema.d.ts",
+      import: "./dist/lib/storage/postgres-schema.js"
     }
   },
   files: [
@@ -53,7 +69,7 @@ var package_default = {
     "LICENSE"
   ],
   scripts: {
-    build: "rm -rf dist && bun build src/cli/index.ts src/daemon/index.ts src/api/index.ts src/runner/index.ts src/mcp/index.ts src/index.ts src/sdk/index.ts src/lib/store.ts src/lib/mode.ts --root src --outdir dist --target bun --packages external && chmod +x dist/cli/index.js dist/daemon/index.js dist/api/index.js dist/runner/index.js dist/mcp/index.js && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
+    build: "rm -rf dist && bun build src/cli/index.ts src/daemon/index.ts src/api/index.ts src/runner/index.ts src/mcp/index.ts src/index.ts src/sdk/index.ts src/lib/store.ts src/lib/mode.ts src/lib/storage/index.ts src/lib/storage/contract.ts src/lib/storage/sqlite.ts src/lib/storage/postgres.ts src/lib/storage/postgres-schema.ts --root src --outdir dist --target bun --packages external && chmod +x dist/cli/index.js dist/daemon/index.js dist/api/index.js dist/runner/index.js dist/mcp/index.js && tsc -p tsconfig.build.json --emitDeclarationOnly --outDir dist",
     "build:bin": "bun build src/cli/index.ts --compile --outfile dist/loops",
     typecheck: "tsc --noEmit",
     test: "bun test",
@@ -254,18 +270,1730 @@ function deploymentStatusLine(status) {
 
 // src/runner/index.ts
 import { Command } from "commander";
+
+// src/lib/executor.ts
+import { spawn as spawn2, spawnSync as spawnSync2 } from "child_process";
+import { randomBytes as randomBytes2 } from "crypto";
+import { once } from "events";
+import { lstatSync, mkdirSync, realpathSync } from "fs";
+import { dirname, resolve } from "path";
+
+// src/lib/accounts.ts
+import { spawnSync } from "child_process";
+import { existsSync } from "fs";
+
+// src/lib/agent-adapter.ts
+import { spawn } from "child_process";
+
+// src/lib/redact.ts
+var SCRUBBED = "[SCRUBBED]";
+var TOKEN_PATTERNS = [
+  /\bsk-ant-[A-Za-z0-9_-]{8,}/g,
+  /\bsk-proj-[A-Za-z0-9_-]{8,}/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /\bghp_[A-Za-z0-9]{16,}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{16,}\b/g,
+  /\bxox[a-z]-[A-Za-z0-9-]{8,}/g,
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{4,}\.[A-Za-z0-9_-]{10,}\b/g
+];
+var AUTHORIZATION_PATTERN = /(\bAuthorization(?:\\?["'])?\s*[:=]\s*(?:\\?["'])?(?:Bearer|Basic)\s+)[A-Za-z0-9._~+/=-]{16,}/gi;
+var PEM_PATTERN = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY-----|$)/g;
+var ASSIGNMENT_PATTERN = /([A-Za-z0-9_.-]{0,64}(?:key|token|secret|passwd|password|passphrase|credentials?)(?:\\?["'])?\s*[:=]\s*)(\\"([^"\\\r\n]{12,})\\"|"((?:[^"\\\r\n]|\\[^\r\n]){12,})"|'([^'\\\r\n]{12,})'|([A-Za-z0-9+/_.=-]{16,}))/gi;
+var BENIGN_KEY_NAME_PATTERN = /(?:^|[._-])(?:idempotency|dedupe|route)[_-]?key$/i;
+var ASSIGNMENT_HINTS = ["key", "token", "secret", "pass", "credential"];
+function mayContainAssignment(text) {
+  const lowered = text.toLowerCase();
+  return ASSIGNMENT_HINTS.some((hint) => lowered.includes(hint));
+}
+function shannonEntropy(value) {
+  const counts = new Map;
+  for (const char of value)
+    counts.set(char, (counts.get(char) ?? 0) + 1);
+  let entropy = 0;
+  for (const count of counts.values()) {
+    const probability = count / value.length;
+    entropy -= probability * Math.log2(probability);
+  }
+  return entropy;
+}
+function isLikelySecretValue(value) {
+  if (value.length < 12)
+    return false;
+  if (value.includes(SCRUBBED))
+    return false;
+  if (value.startsWith("/") || value.startsWith("~") || value.startsWith("./"))
+    return false;
+  return shannonEntropy(value) >= 3.2;
+}
+function scrubSecrets(text) {
+  if (!text)
+    return text;
+  let scrubbed = text;
+  for (const pattern of TOKEN_PATTERNS)
+    scrubbed = scrubbed.replace(pattern, SCRUBBED);
+  scrubbed = scrubbed.replace(AUTHORIZATION_PATTERN, `$1${SCRUBBED}`);
+  scrubbed = scrubbed.replace(PEM_PATTERN, SCRUBBED);
+  if (!mayContainAssignment(scrubbed))
+    return scrubbed;
+  scrubbed = scrubbed.replace(ASSIGNMENT_PATTERN, (match, prefix, quotedValue, escapedQuoted, doubleQuoted, singleQuoted, bare) => {
+    const value = escapedQuoted ?? doubleQuoted ?? singleQuoted ?? bare ?? "";
+    const keyName = /^[A-Za-z0-9_.-]*/.exec(prefix)?.[0] ?? "";
+    if (BENIGN_KEY_NAME_PATTERN.test(keyName))
+      return match;
+    if (!isLikelySecretValue(value))
+      return match;
+    const quote = quotedValue.startsWith("\\\"") ? "\\\"" : quotedValue.startsWith('"') ? '"' : quotedValue.startsWith("'") ? "'" : "";
+    return `${prefix}${quote}${SCRUBBED}${quote}`;
+  });
+  return scrubbed;
+}
+function scrubSecretsDeep(value) {
+  if (typeof value === "string")
+    return scrubSecrets(value);
+  if (Array.isArray(value))
+    return value.map((entry) => scrubSecretsDeep(entry));
+  if (value !== null && typeof value === "object") {
+    const toJSON = value.toJSON;
+    if (typeof toJSON === "function")
+      return scrubSecretsDeep(toJSON.call(value));
+    const scrubbed = {};
+    for (const [key, entry] of Object.entries(value))
+      scrubbed[key] = scrubSecretsDeep(entry);
+    return scrubbed;
+  }
+  return value;
+}
+
+// src/lib/agent-adapter.ts
+var UNSAFE_CODEWITH_DURABLE_EXTRA_ARGS = new Set([
+  "e",
+  "exec",
+  "agent",
+  "start",
+  "--ephemeral",
+  "--ignore-rules",
+  "--skip-git-repo-check",
+  "--json",
+  "--output-last-message",
+  "-o",
+  "--output-schema",
+  "--dangerously-bypass-approvals-and-sandbox"
+]);
+var CODEX_LIKE_SANDBOXES = ["read-only", "workspace-write", "danger-full-access"];
+var CURSOR_SANDBOXES = ["enabled", "disabled"];
+var PERMISSION_MODES = ["default", "plan", "auto", "bypass"];
+function assertOptionalNonEmptyString(value, label) {
+  if (value === undefined)
+    return;
+  if (typeof value !== "string" || value.trim() === "")
+    throw new Error(`${label} must be a non-empty string`);
+}
+function validateAgentOptions(target, label, capabilities) {
+  const provider = target.provider;
+  if (typeof target.prompt !== "string" || target.prompt.trim() === "") {
+    throw new Error(`${label}.prompt must be a non-empty string`);
+  }
+  assertOptionalNonEmptyString(target.model, `${label}.model`);
+  assertOptionalNonEmptyString(target.variant, `${label}.variant`);
+  assertOptionalNonEmptyString(target.agent, `${label}.agent`);
+  assertOptionalNonEmptyString(target.authProfile, `${label}.authProfile`);
+  assertOptionalNonEmptyString(target.configIsolation, `${label}.configIsolation`);
+  if (target.configIsolation !== undefined && target.configIsolation !== "safe" && target.configIsolation !== "none") {
+    throw new Error(`${label}.configIsolation must be safe or none`);
+  }
+  if (target.authProfile !== undefined && provider !== "codewith") {
+    throw new Error(`${label}.authProfile is currently supported only for provider codewith`);
+  }
+  if (provider === "opencode" && (typeof target.model !== "string" || target.model.trim() === "")) {
+    throw new Error(`${label}.model is required for provider opencode; pass a provider/model id such as openrouter/google/gemini-2.5-flash`);
+  }
+  if (provider === "cursor" && target.variant !== undefined) {
+    throw new Error(`${label}.variant is not supported for provider cursor`);
+  }
+  if (provider === "codex" && target.agent !== undefined) {
+    throw new Error(`${label}.agent is not supported for provider codex`);
+  }
+  if (provider === "codewith" && target.agent !== undefined) {
+    throw new Error(`${label}.agent is not supported for provider codewith durable background-agent execution`);
+  }
+  if (provider === "codewith") {
+    const unsafe = target.extraArgs?.find((arg) => UNSAFE_CODEWITH_DURABLE_EXTRA_ARGS.has(arg));
+    if (unsafe) {
+      throw new Error(`${label}.extraArgs cannot include ${unsafe}; codewith agent steps use durable agent start, not exec/ephemeral flags`);
+    }
+  }
+  if (target.addDirs?.length && !["codewith", "codex"].includes(provider)) {
+    throw new Error(`${label}.addDirs is currently supported only for provider codewith or codex`);
+  }
+  if (target.permissionMode !== undefined) {
+    if (!PERMISSION_MODES.includes(target.permissionMode)) {
+      throw new Error(`${label}.permissionMode must be one of ${PERMISSION_MODES.join(", ")}`);
+    }
+    if (target.permissionMode === "plan" && !["claude", "cursor"].includes(provider)) {
+      throw new Error(`${label}.permissionMode plan is currently supported only for provider claude or cursor`);
+    }
+    if (target.permissionMode === "auto" && provider !== "claude") {
+      throw new Error(`${label}.permissionMode auto is currently supported only for provider claude`);
+    }
+  }
+  if (target.sandbox !== undefined) {
+    if (!capabilities.sandbox.length) {
+      throw new Error(`${label}.sandbox is currently supported only for provider codewith, codex, or cursor`);
+    }
+    if (!capabilities.sandbox.includes(target.sandbox)) {
+      throw new Error(`${label}.sandbox must be one of ${capabilities.sandbox.join(", ")}`);
+    }
+  }
+}
+function codewithLikeSandbox(target) {
+  return target.sandbox ?? (target.permissionMode === "bypass" ? "danger-full-access" : "workspace-write");
+}
+function configStringValue(value) {
+  return JSON.stringify(value);
+}
+function buildAgentInvocation(target) {
+  const isolation = target.configIsolation ?? "safe";
+  const permissionMode = target.permissionMode ?? "default";
+  const args = [];
+  switch (target.provider) {
+    case "claude": {
+      if (isolation === "safe")
+        args.push("--safe-mode", "--setting-sources", "local", "--no-session-persistence");
+      if (permissionMode !== "default") {
+        const mode = permissionMode === "bypass" ? "bypassPermissions" : permissionMode;
+        args.push("--permission-mode", mode);
+      }
+      args.push("-p", "--output-format", "json");
+      if (target.model)
+        args.push("--model", target.model);
+      if (target.variant)
+        args.push("--effort", target.variant);
+      if (target.agent)
+        args.push("--agent", target.agent);
+      args.push(...target.extraArgs ?? []);
+      return { command: "claude", args, stdin: target.prompt };
+    }
+    case "cursor": {
+      args.push("-c", [
+        "set -eu",
+        "if command -v agent >/dev/null 2>&1; then",
+        '  exec agent "$@"',
+        "else",
+        "  echo 'Executable not found in PATH: agent' >&2",
+        "  exit 127",
+        "fi"
+      ].join(`
+`), "openloops-cursor", "-p");
+      if (permissionMode === "plan")
+        args.push("--mode", "plan");
+      if (permissionMode === "bypass")
+        args.push("--force");
+      const cursorSandbox = target.sandbox ?? (isolation === "safe" ? "enabled" : undefined);
+      if (cursorSandbox)
+        args.push("--sandbox", cursorSandbox);
+      if (target.model)
+        args.push("--model", target.model);
+      if (target.agent)
+        args.push("--agent", target.agent);
+      args.push(...target.extraArgs ?? []);
+      return { command: "sh", args, stdin: target.prompt, preflightAnyOf: ["agent"] };
+    }
+    case "codewith": {
+      args.push(...target.authProfile ? ["--auth-profile", target.authProfile] : []);
+      if (target.variant)
+        args.push("-c", `model_reasoning_effort=${configStringValue(target.variant)}`);
+      args.push("--ask-for-approval", "never", "--sandbox", codewithLikeSandbox(target));
+      if (target.cwd)
+        args.push("--cd", target.cwd);
+      for (const dir of target.addDirs ?? [])
+        args.push("--add-dir", dir);
+      if (target.model)
+        args.push("--model", target.model);
+      args.push(...target.extraArgs ?? []);
+      args.push("agent", "start");
+      if (target.cwd)
+        args.push("--cwd", target.cwd);
+      args.push(target.prompt);
+      return { command: "codewith", args };
+    }
+    case "codex": {
+      if (target.variant)
+        args.push("-c", `model_reasoning_effort=${configStringValue(target.variant)}`);
+      args.push("--ask-for-approval", "never", "exec", "--json", "--ephemeral", "--sandbox", codewithLikeSandbox(target), "--skip-git-repo-check");
+      if (isolation === "safe")
+        args.push("--ignore-rules");
+      if (target.cwd)
+        args.push("--cd", target.cwd);
+      for (const dir of target.addDirs ?? [])
+        args.push("--add-dir", dir);
+      if (target.model)
+        args.push("--model", target.model);
+      args.push(...target.extraArgs ?? []);
+      return { command: "codex", args, stdin: target.prompt };
+    }
+    case "aicopilot":
+    case "opencode": {
+      args.push("run", "--format", "json");
+      if (isolation === "safe")
+        args.push("--pure");
+      if (permissionMode === "bypass")
+        args.push("--dangerously-skip-permissions");
+      if (target.cwd)
+        args.push("--dir", target.cwd);
+      if (target.model)
+        args.push("--model", target.model);
+      if (target.variant)
+        args.push("--variant", target.variant);
+      if (target.agent)
+        args.push("--agent", target.agent);
+      args.push(...target.extraArgs ?? []);
+      return { command: target.provider, args, stdin: target.prompt };
+    }
+  }
+}
+function adapterFor(provider, capabilities) {
+  return {
+    provider,
+    capabilities,
+    validate(target, label = provider) {
+      validateAgentOptions(target, label, capabilities);
+    },
+    buildInvocation(target) {
+      validateAgentOptions(target, provider, capabilities);
+      return buildAgentInvocation(target);
+    }
+  };
+}
+var PROVIDER_ADAPTERS = {
+  claude: adapterFor("claude", { sandbox: [], durable: false, remote: true, promptChannel: "stdin" }),
+  cursor: adapterFor("cursor", { sandbox: CURSOR_SANDBOXES, durable: false, remote: true, promptChannel: "stdin" }),
+  codewith: adapterFor("codewith", { sandbox: CODEX_LIKE_SANDBOXES, durable: true, remote: false, promptChannel: "argv" }),
+  codex: adapterFor("codex", { sandbox: CODEX_LIKE_SANDBOXES, durable: false, remote: true, promptChannel: "stdin" }),
+  aicopilot: adapterFor("aicopilot", { sandbox: [], durable: false, remote: true, promptChannel: "stdin" }),
+  opencode: adapterFor("opencode", { sandbox: [], durable: false, remote: true, promptChannel: "stdin" })
+};
+var AGENT_PROVIDERS = Object.keys(PROVIDER_ADAPTERS);
+function providerAdapter(provider) {
+  const adapter = PROVIDER_ADAPTERS[provider];
+  if (!adapter)
+    throw new Error(`unsupported agent provider: ${String(provider)}`);
+  return adapter;
+}
+var DEFAULT_CAPTURE_MAX_OUTPUT_BYTES = 256 * 1024;
+function killProcessGroup(pgid) {
+  try {
+    process.kill(-pgid, "SIGTERM");
+  } catch {
+    try {
+      process.kill(pgid, "SIGTERM");
+    } catch {}
+  }
+  setTimeout(() => {
+    try {
+      process.kill(-pgid, "SIGKILL");
+    } catch {
+      try {
+        process.kill(pgid, "SIGKILL");
+      } catch {}
+    }
+  }, 2000).unref();
+}
+
+class BoundedOutputBuffer {
+  maxBytes;
+  text = "";
+  truncatedBytes = 0;
+  constructor(maxBytes) {
+    this.maxBytes = maxBytes;
+  }
+  append(chunk) {
+    if (!chunk)
+      return;
+    this.text += chunk;
+    if (Buffer.byteLength(this.text, "utf8") <= this.maxBytes)
+      return;
+    this.text = scrubSecrets(this.text);
+    const encoded = Buffer.from(this.text, "utf8");
+    if (encoded.length <= this.maxBytes)
+      return;
+    let start = encoded.length - this.maxBytes;
+    while (start < encoded.length && (encoded[start] & 192) === 128)
+      start++;
+    this.truncatedBytes += start;
+    this.text = encoded.subarray(start).toString("utf8");
+  }
+  value() {
+    if (this.truncatedBytes === 0)
+      return this.text;
+    return `[truncated ${this.truncatedBytes} bytes]
+${this.text}`;
+  }
+}
+async function spawnCapture(command, args, opts) {
+  const maxOutputBytes = opts.maxOutputBytes ?? DEFAULT_CAPTURE_MAX_OUTPUT_BYTES;
+  const stdout = new BoundedOutputBuffer(maxOutputBytes);
+  const stderr = new BoundedOutputBuffer(maxOutputBytes);
+  let timedOut = false;
+  let error;
+  const child = spawn(command, args, {
+    cwd: opts.cwd,
+    env: opts.env,
+    detached: true,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  const timer = setTimeout(() => {
+    timedOut = true;
+    if (child.pid)
+      killProcessGroup(child.pid);
+  }, opts.timeoutMs);
+  timer.unref();
+  child.stdout?.setEncoding("utf8");
+  child.stderr?.setEncoding("utf8");
+  child.stdout?.on("data", (chunk) => stdout.append(chunk));
+  child.stderr?.on("data", (chunk) => stderr.append(chunk));
+  const [status, signal] = await new Promise((resolve) => {
+    child.once("error", (err) => {
+      error = err.message;
+      resolve([null, null]);
+    });
+    child.once("close", (code, sig) => resolve([code, sig]));
+  });
+  clearTimeout(timer);
+  if (timedOut && !error)
+    error = `timed out after ${opts.timeoutMs}ms`;
+  return { status, signal, stdout: stdout.value(), stderr: stderr.value(), error, timedOut };
+}
+
+// src/lib/accounts.ts
+var EXPORT_RE = /^export\s+([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;
+var ACCOUNTS_ENV_TIMEOUT_MS = 30000;
+function accountToolForProvider(provider) {
+  switch (provider) {
+    case "claude":
+      return "claude";
+    case "cursor":
+      return "cursor";
+    case "codewith":
+      return "codewith";
+    case "aicopilot":
+      return "aicopilot";
+    case "opencode":
+      return "opencode";
+    case "codex":
+      return "codex";
+  }
+}
+function parseExportValue(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw.replace(/^['"]|['"]$/g, "");
+  }
+}
+function parseAccountExportLines(output) {
+  const env = {};
+  for (const line of output.split(/\r?\n/)) {
+    const match = EXPORT_RE.exec(line.trim());
+    if (!match)
+      continue;
+    env[match[1]] = parseExportValue(match[2]);
+  }
+  return env;
+}
+function primaryAccountDir(output) {
+  for (const line of output.split(/\r?\n/)) {
+    const match = EXPORT_RE.exec(line.trim());
+    if (!match)
+      continue;
+    return parseExportValue(match[2]);
+  }
+  return;
+}
+function accountDirEnvVar(tool) {
+  switch (tool) {
+    case "claude":
+      return "CLAUDE_CONFIG_DIR";
+    case "codex":
+    case "codex-app":
+      return "CODEX_HOME";
+    case "cursor":
+      return "CURSOR_CONFIG_DIR";
+    case "opencode":
+      return "OPENCODE_CONFIG_DIR";
+    case "codewith":
+      return "CODEWITH_HOME";
+    case "aicopilot":
+      return "AICOPILOT_CONFIG_DIR";
+    default:
+      return;
+  }
+}
+function requiredAccountTool(account, toolHint) {
+  const tool = account.tool ?? toolHint;
+  if (!tool)
+    throw new Error("account.tool is required when no provider tool can be inferred");
+  return tool;
+}
+function accountEnvFromResult(account, tool, result) {
+  if (result.error) {
+    throw new Error(`failed to run accounts env for ${account.profile}/${tool}: ${result.error}`);
+  }
+  if ((result.status ?? 1) !== 0) {
+    const stderr = result.stderr.trim();
+    throw new Error(`accounts env failed for ${account.profile}/${tool}${stderr ? `: ${stderr}` : ""}`);
+  }
+  const accountEnv = parseAccountExportLines(result.stdout);
+  const profileDir = (accountDirEnvVar(tool) ? accountEnv[accountDirEnvVar(tool)] : undefined) ?? primaryAccountDir(result.stdout);
+  if (!profileDir)
+    throw new Error(`accounts env returned no profile directory for ${account.profile}/${tool}`);
+  if (!existsSync(profileDir))
+    throw new Error(`account profile directory does not exist for ${account.profile}/${tool}: ${profileDir}`);
+  return {
+    ...accountEnv,
+    LOOPS_ACCOUNT_PROFILE: account.profile,
+    LOOPS_ACCOUNT_TOOL: tool
+  };
+}
+async function resolveAccountEnv(account, toolHint, env) {
+  if (!account)
+    return {};
+  const tool = requiredAccountTool(account, toolHint);
+  const result = await spawnCapture("accounts", ["env", account.profile, "--tool", tool], {
+    env,
+    timeoutMs: ACCOUNTS_ENV_TIMEOUT_MS
+  });
+  return accountEnvFromResult(account, tool, result);
+}
+function resolveAccountEnvSync(account, toolHint, env) {
+  if (!account)
+    return {};
+  const tool = requiredAccountTool(account, toolHint);
+  const result = spawnSync("accounts", ["env", account.profile, "--tool", tool], {
+    encoding: "utf8",
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: ACCOUNTS_ENV_TIMEOUT_MS
+  });
+  return accountEnvFromResult(account, tool, {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    error: result.error?.message
+  });
+}
+
+// src/lib/env.ts
+import { accessSync, constants } from "fs";
+import { homedir } from "os";
+import { delimiter, join } from "path";
+function compactPathParts(parts) {
+  const seen = new Set;
+  const result = [];
+  for (const part of parts) {
+    const value = part?.trim();
+    if (!value || seen.has(value))
+      continue;
+    seen.add(value);
+    result.push(value);
+  }
+  return result;
+}
+function commonExecutableDirs(env = process.env) {
+  const home = env.HOME || homedir();
+  return compactPathParts([
+    join(home, ".local", "bin"),
+    join(home, ".bun", "bin"),
+    join(home, ".cargo", "bin"),
+    join(home, ".npm-global", "bin"),
+    join(home, "bin"),
+    env.BUN_INSTALL ? join(env.BUN_INSTALL, "bin") : undefined,
+    env.PNPM_HOME,
+    env.NPM_CONFIG_PREFIX ? join(env.NPM_CONFIG_PREFIX, "bin") : undefined,
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    "/usr/bin",
+    "/bin",
+    "/usr/sbin",
+    "/sbin"
+  ]);
+}
+function normalizeExecutionPath(env = process.env) {
+  return compactPathParts([...(env.PATH ?? "").split(delimiter), ...commonExecutableDirs(env)]).join(delimiter);
+}
+function isExecutable(path) {
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function executableExists(command, env = process.env) {
+  if (command.includes("/"))
+    return isExecutable(command);
+  for (const dir of (env.PATH ?? "").split(delimiter)) {
+    if (dir && isExecutable(join(dir, command)))
+      return true;
+  }
+  return false;
+}
+function commandNotFoundMessage(command, env = process.env) {
+  return `Executable not found in PATH: ${command}. Effective PATH=${env.PATH || "(empty)"}`;
+}
+
+// src/lib/ids.ts
+import { randomBytes } from "crypto";
+var TIME_HEX_LENGTH = 12;
+function genId() {
+  const time = Date.now().toString(16).padStart(TIME_HEX_LENGTH, "0");
+  return `${time}${randomBytes(10).toString("hex")}`;
+}
+function nowIso() {
+  return new Date().toISOString();
+}
+
+// src/lib/machines.ts
+import { createRequire } from "module";
+var consumerModule;
+function machinesConsumer() {
+  if (!consumerModule) {
+    try {
+      const resolved = Bun.resolveSync("@hasna/machines/consumer", import.meta.dir);
+      consumerModule = createRequire(import.meta.url)(resolved);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(`@hasna/machines is not available; install the optional dependency to use machine-assigned loops: ${detail}`);
+    }
+  }
+  return consumerModule;
+}
+function compact(value) {
+  const text = value?.trim();
+  return text ? text : undefined;
+}
+function entryToSummary(entry, topology) {
+  return {
+    id: entry.machine_id,
+    hostname: compact(entry.hostname),
+    platform: compact(entry.platform),
+    user: compact(entry.user),
+    workspacePath: compact(entry.workspace_path),
+    route: entry.ssh.route,
+    local: entry.machine_id === topology.local_machine_id || entry.ssh.route === "local",
+    heartbeatStatus: entry.heartbeat_status,
+    tailscaleOnline: entry.tailscale.online,
+    tags: entry.tags
+  };
+}
+function machineFromRoute(route, topology) {
+  if (!route.ok || !route.machine_id) {
+    throw new Error(`OpenMachines route not found for machine: ${route.requested_machine_id}`);
+  }
+  const entry = topology.machines.find((machine) => machine.machine_id === route.machine_id);
+  return {
+    id: route.machine_id,
+    requestedId: route.requested_machine_id !== route.machine_id ? route.requested_machine_id : undefined,
+    route: route.route,
+    local: route.local,
+    confidence: route.confidence,
+    workspacePath: compact(entry?.workspace_path),
+    resolvedAt: route.generated_at,
+    packageVersion: route.package.version,
+    warnings: route.warnings.length ? route.warnings : undefined
+  };
+}
+function listOpenMachines() {
+  const topology = machinesConsumer().discoverMachineTopology();
+  return topology.machines.map((entry) => entryToSummary(entry, topology));
+}
+function resolveLoopMachine(machineId) {
+  const consumer = machinesConsumer();
+  const topology = consumer.discoverMachineTopology();
+  const route = consumer.resolveMachineRoute(machineId, { topology });
+  return machineFromRoute(route, topology);
+}
+function resolveMachineCommand(machineId, command) {
+  return machinesConsumer().resolveMachineCommand(machineId, command);
+}
+function refreshLoopMachine(machine) {
+  return resolveLoopMachine(machine.id);
+}
+
+// src/lib/executor.ts
+var DEFAULT_TIMEOUT_MS = 30 * 60000;
+var DEFAULT_MAX_OUTPUT_BYTES = 256 * 1024;
+var DEFAULT_AGENT_IDLE_TIMEOUT_MS = 30 * 60000;
+var BUFFERED_OUTPUT_PROVIDERS = new Set(["claude", "codewith", "opencode", "aicopilot"]);
+var DEFAULT_BUFFERED_AGENT_IDLE_TIMEOUT_MS = 4 * 60 * 60000;
+var WORKTREE_GIT_TIMEOUT_MS = 5 * 60000;
+var AUTH_ENV_KEYS = [
+  "CLAUDE_CONFIG_DIR",
+  "CODEWITH_HOME",
+  "CODEX_HOME",
+  "CURSOR_CONFIG_DIR",
+  "CURSOR_API_KEY",
+  "OPENCODE_CONFIG_DIR",
+  "AICOPILOT_CONFIG_DIR",
+  "ANTHROPIC_API_KEY",
+  "OPENAI_API_KEY",
+  "OPENROUTER_API_KEY",
+  "GITHUB_TOKEN",
+  "GH_TOKEN",
+  "XDG_CONFIG_HOME",
+  "XDG_DATA_HOME",
+  "XDG_STATE_HOME",
+  "XDG_CACHE_HOME"
+];
+var TRANSPORT_ENV_KEYS = new Set([
+  "BUN_INSTALL",
+  "HOME",
+  "LANG",
+  "LANGUAGE",
+  "LOGNAME",
+  "PATH",
+  "SHELL",
+  "SSH_AGENT_PID",
+  "SSH_AUTH_SOCK",
+  "TERM",
+  "TMP",
+  "TMPDIR",
+  "TEMP",
+  "USER",
+  "XDG_RUNTIME_DIR"
+]);
+function boundedText(text, maxBytes) {
+  const buffer = new BoundedOutputBuffer(maxBytes);
+  buffer.append(text);
+  return buffer.value();
+}
+function buildResult(status, startedAt, fields = {}) {
+  const finishedAt = fields.finishedAt ?? nowIso();
+  return {
+    status,
+    exitCode: fields.exitCode,
+    stdout: fields.stdout ?? "",
+    stderr: fields.stderr ?? "",
+    error: fields.error,
+    pid: fields.pid,
+    startedAt,
+    finishedAt,
+    durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime()
+  };
+}
+function failureResult(startedAt, error, fields = {}) {
+  return buildResult("failed", startedAt, { ...fields, error });
+}
+function timeoutResult(startedAt, error, fields = {}) {
+  return buildResult("timed_out", startedAt, { ...fields, error });
+}
+function successResult(startedAt, fields = {}) {
+  return buildResult("succeeded", startedAt, fields);
+}
+function notifySpawn(pid, opts) {
+  if (!pid)
+    return;
+  opts.onSpawn?.(pid);
+  opts.onSpawnProcess?.({ pid, pgid: pid, processStartedAt: nowIso() });
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function metadataEnv(metadata) {
+  const env = {};
+  if (metadata.loopId)
+    env.LOOPS_LOOP_ID = metadata.loopId;
+  if (metadata.loopName)
+    env.LOOPS_LOOP_NAME = metadata.loopName;
+  if (metadata.runId)
+    env.LOOPS_RUN_ID = metadata.runId;
+  if (metadata.scheduledFor)
+    env.LOOPS_SCHEDULED_FOR = metadata.scheduledFor;
+  if (metadata.workflowId)
+    env.LOOPS_WORKFLOW_ID = metadata.workflowId;
+  if (metadata.workflowName)
+    env.LOOPS_WORKFLOW_NAME = metadata.workflowName;
+  if (metadata.workflowRunId)
+    env.LOOPS_WORKFLOW_RUN_ID = metadata.workflowRunId;
+  if (metadata.workflowStepId)
+    env.LOOPS_WORKFLOW_STEP_ID = metadata.workflowStepId;
+  if (metadata.goalId)
+    env.LOOPS_GOAL_ID = metadata.goalId;
+  if (metadata.goalObjective)
+    env.LOOPS_GOAL_OBJECTIVE = metadata.goalObjective;
+  if (metadata.goalNodeKey)
+    env.LOOPS_GOAL_NODE_KEY = metadata.goalNodeKey;
+  return env;
+}
+function codewithAgentIdempotencyKey(metadata) {
+  const parts = [
+    "openloops",
+    metadata.workflowRunId ? `workflow-run:${metadata.workflowRunId}` : undefined,
+    metadata.workflowStepId ? `step:${metadata.workflowStepId}` : undefined,
+    metadata.runId ? `loop-run:${metadata.runId}` : undefined,
+    metadata.loopId ? `loop:${metadata.loopId}` : undefined,
+    metadata.scheduledFor ? `scheduled:${metadata.scheduledFor}` : undefined,
+    metadata.goalId ? `goal:${metadata.goalId}` : undefined,
+    metadata.goalNodeKey ? `node:${metadata.goalNodeKey}` : undefined
+  ].filter(Boolean);
+  if (parts.length > 1)
+    return parts.join(":");
+  return `openloops:adhoc:${randomBytes2(16).toString("hex")}`;
+}
+function allowlistEnv(allowlist) {
+  const env = {};
+  if (allowlist?.tools?.length)
+    env.LOOPS_AGENT_ALLOWED_TOOLS = allowlist.tools.join(",");
+  if (allowlist?.commands?.length)
+    env.LOOPS_AGENT_ALLOWED_COMMANDS = allowlist.commands.join(",");
+  if (allowlist?.tools?.length || allowlist?.commands?.length)
+    env.LOOPS_AGENT_ALLOWLIST_ENFORCEMENT = "metadata_only";
+  return env;
+}
+function defaultAgentIdleTimeoutMs(target, opts) {
+  if (target.timeoutMs !== undefined || target.idleTimeoutMs !== undefined)
+    return;
+  const raw = opts.env?.LOOPS_AGENT_IDLE_TIMEOUT_MS ?? process.env.LOOPS_AGENT_IDLE_TIMEOUT_MS;
+  if (raw !== undefined && raw !== "") {
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "0" || normalized === "none" || normalized === "off")
+      return;
+    const parsed = Number(normalized);
+    if (Number.isFinite(parsed) && parsed > 0)
+      return parsed;
+  }
+  return BUFFERED_OUTPUT_PROVIDERS.has(target.provider) ? DEFAULT_BUFFERED_AGENT_IDLE_TIMEOUT_MS : DEFAULT_AGENT_IDLE_TIMEOUT_MS;
+}
+function commandSpec(target, opts) {
+  if (target.type === "command") {
+    const commandTarget = target;
+    return {
+      command: commandTarget.command,
+      args: commandTarget.args ?? [],
+      cwd: commandTarget.cwd,
+      shell: commandTarget.shell,
+      env: commandTarget.env,
+      timeoutMs: commandTarget.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : commandTarget.timeoutMs,
+      idleTimeoutMs: commandTarget.idleTimeoutMs,
+      account: commandTarget.account,
+      accountTool: commandTarget.account?.tool
+    };
+  }
+  const agentTarget = target;
+  const adapter = providerAdapter(agentTarget.provider);
+  const invocation = adapter.buildInvocation(agentTarget);
+  return {
+    command: invocation.command,
+    args: invocation.args,
+    cwd: agentTarget.cwd,
+    timeoutMs: agentTarget.timeoutMs ?? null,
+    idleTimeoutMs: agentTarget.idleTimeoutMs ?? defaultAgentIdleTimeoutMs(agentTarget, opts),
+    account: agentTarget.account,
+    accountTool: agentTarget.account?.tool ?? accountToolForProvider(agentTarget.provider),
+    nativeAuthProfile: agentTarget.authProfile ? { provider: agentTarget.provider, profile: agentTarget.authProfile } : undefined,
+    preflightAnyOf: invocation.preflightAnyOf,
+    stdin: invocation.stdin,
+    allowlist: agentTarget.allowlist,
+    worktree: agentTarget.worktree,
+    codewithDurableAgent: adapter.capabilities.durable ? { target: agentTarget } : undefined
+  };
+}
+function composeExecutionEnv(spec, metadata, opts, accountEnv) {
+  const env = { ...opts.env ?? process.env };
+  if (accountEnv) {
+    for (const key of AUTH_ENV_KEYS)
+      delete env[key];
+    Object.assign(env, accountEnv);
+  }
+  Object.assign(env, spec.env ?? {});
+  Object.assign(env, allowlistEnv(spec.allowlist));
+  env.PATH = normalizeExecutionPath(env);
+  Object.assign(env, metadataEnv(metadata));
+  return env;
+}
+async function executionEnv(spec, metadata, opts) {
+  const accountEnv = spec.account ? await resolveAccountEnv(spec.account, spec.accountTool, { ...opts.env ?? process.env }) : undefined;
+  return composeExecutionEnv(spec, metadata, opts, accountEnv);
+}
+function executionEnvSync(spec, metadata, opts) {
+  const accountEnv = spec.account ? resolveAccountEnvSync(spec.account, spec.accountTool, { ...opts.env ?? process.env }) : undefined;
+  return composeExecutionEnv(spec, metadata, opts, accountEnv);
+}
+function resolvedMachine(opts) {
+  if (!opts.machine)
+    return;
+  return (opts.machineResolver ?? refreshLoopMachine)(opts.machine);
+}
+function commandForShell(spec) {
+  if (!spec.args.length)
+    return spec.command;
+  return [spec.command, ...spec.args.map(shellQuote)].join(" ");
+}
+function hereDoc(value) {
+  let delimiter2 = `__OPENLOOPS_STDIN_${randomBytes2(8).toString("hex").toUpperCase()}__`;
+  while (value.split(/\r?\n/).includes(delimiter2)) {
+    delimiter2 = `__OPENLOOPS_STDIN_${randomBytes2(8).toString("hex").toUpperCase()}__`;
+  }
+  return [`cat > "$__OPENLOOPS_STDIN" <<'${delimiter2}'`, value, delimiter2];
+}
+function remoteBootstrapLines(spec, metadata, opts = {}) {
+  const lines = [
+    "set -e",
+    'export PATH="$HOME/.local/bin:$HOME/.bun/bin:$HOME/.cargo/bin:$HOME/.npm-global/bin:$HOME/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin${PATH:+:$PATH}"'
+  ];
+  const worktree = spec.worktree;
+  const worktreeManaged = worktree?.enabled && (worktree.mode === "auto" || worktree.mode === "required");
+  if (opts.worktree && worktree && worktreeManaged) {
+    lines.push(...remoteWorktreePrepareLines(worktree));
+    lines.push(...remoteWorktreeEnterLines(worktree, spec.cwd));
+  } else if (worktree && worktreeManaged) {
+    lines.push(`cd ${shellQuote(worktree.originalCwd)}`);
+  } else if (spec.cwd) {
+    lines.push(`cd ${shellQuote(spec.cwd)}`);
+  }
+  if (spec.account) {
+    if (!spec.accountTool)
+      throw new Error("account.tool is required when no provider tool can be inferred");
+    lines.push("if ! command -v accounts >/dev/null 2>&1; then echo 'accounts CLI is not available on remote machine' >&2; exit 127; fi", `unset ${AUTH_ENV_KEYS.join(" ")}`, `eval "$(accounts env ${shellQuote(spec.account.profile)} --tool ${shellQuote(spec.accountTool)})"`, `export LOOPS_ACCOUNT_PROFILE=${shellQuote(spec.account.profile)}`, `export LOOPS_ACCOUNT_TOOL=${shellQuote(spec.accountTool)}`);
+  }
+  for (const [key, value] of Object.entries({ ...metadataEnv(metadata), ...spec.env ?? {} })) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+      continue;
+    lines.push(`export ${key}=${shellQuote(value)}`);
+  }
+  for (const [key, value] of Object.entries(allowlistEnv(spec.allowlist))) {
+    lines.push(`export ${key}=${shellQuote(value)}`);
+  }
+  return lines;
+}
+function remoteWorktreePrepareLines(worktree) {
+  const { repoRoot, path, branch } = worktree;
+  if (!repoRoot || !path || !branch) {
+    return [
+      "__openloops_prepare_worktree() {",
+      `  echo ${shellQuote("worktree preparation requires repoRoot, path, and branch metadata")} >&2`,
+      "  return 1",
+      "}"
+    ];
+  }
+  return [
+    "__openloops_prepare_worktree() {",
+    `  local repo=${shellQuote(repoRoot)} path=${shellQuote(path)} branch=${shellQuote(branch)}`,
+    "  local top expected_common actual_common current",
+    '  if [ -L "$path" ]; then echo "refusing symlinked worktree path $path" >&2; return 1; fi',
+    '  if [ -e "$path" ]; then',
+    '    top="$(git -C "$path" rev-parse --show-toplevel 2>/dev/null)" || { echo "refusing to reuse non-worktree path: $path" >&2; return 1; }',
+    '    if [ "$(cd "$top" 2>/dev/null && pwd -P)" != "$(cd "$path" 2>/dev/null && pwd -P)" ]; then echo "existing worktree top-level mismatch for $path: $top" >&2; return 1; fi',
+    '    expected_common="$(cd "$repo" 2>/dev/null && cd "$(git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null && pwd -P)"',
+    '    actual_common="$(cd "$path" 2>/dev/null && cd "$(git rev-parse --git-common-dir 2>/dev/null)" 2>/dev/null && pwd -P)"',
+    '    if [ -z "$expected_common" ] || [ "$expected_common" != "$actual_common" ]; then echo "existing worktree $path belongs to a different git common dir" >&2; return 1; fi',
+    '    current="$(git -C "$path" branch --show-current 2>/dev/null)"',
+    '    if [ "$current" != "$branch" ]; then echo "existing worktree $path is on branch ${current:-unknown}, expected $branch" >&2; return 1; fi',
+    "    return 0",
+    "  fi",
+    '  git -C "$repo" rev-parse --is-inside-work-tree >/dev/null 2>&1 || { echo "worktree repoRoot is not a git repository: $repo" >&2; return 1; }',
+    '  mkdir -p "$(dirname "$path")" || return 1',
+    "  # Preparation chatter goes to stderr so run stdout stays the agent's.",
+    '  if git -C "$repo" show-ref --verify --quiet "refs/heads/$branch"; then',
+    '    git -C "$repo" worktree add "$path" "$branch" 1>&2 || return 1',
+    "  else",
+    '    git -C "$repo" worktree add -b "$branch" "$path" HEAD 1>&2 || return 1',
+    "  fi",
+    "}"
+  ];
+}
+function remoteWorktreeEnterLines(worktree, cwd) {
+  const workdir = cwd ?? worktree.cwd;
+  if (worktree.mode === "required") {
+    return [
+      "if ! __openloops_prepare_worktree; then",
+      `  echo ${shellQuote("worktree preparation failed (mode=required)")} >&2`,
+      "  exit 1",
+      "fi",
+      "__OPENLOOPS_WORKTREE_OK=1",
+      `cd ${shellQuote(workdir)}`
+    ];
+  }
+  return [
+    "if __openloops_prepare_worktree; then",
+    "  __OPENLOOPS_WORKTREE_OK=1",
+    `  cd ${shellQuote(workdir)}`,
+    "else",
+    `  echo ${shellQuote(`worktree preparation failed (mode=${worktree.mode}); falling back to ${worktree.originalCwd}`)} >&2`,
+    "  __OPENLOOPS_WORKTREE_OK=0",
+    `  cd ${shellQuote(worktree.originalCwd)}`,
+    "fi"
+  ];
+}
+function remoteScript(spec, metadata, fallbackSpec) {
+  const lines = remoteBootstrapLines(spec, metadata, { worktree: true });
+  let stdinRedirect = "";
+  if (spec.stdin !== undefined) {
+    lines.push('__OPENLOOPS_STDIN="$(mktemp -t openloops-stdin.XXXXXX)"', `trap 'rm -f "$__OPENLOOPS_STDIN"' EXIT`);
+    lines.push(...hereDoc(spec.stdin));
+    stdinRedirect = ' < "$__OPENLOOPS_STDIN"';
+  }
+  const invocationFor = (invocationSpec) => invocationSpec.shell ? `sh -c ${shellQuote(commandForShell(invocationSpec))}${stdinRedirect}` : `${[invocationSpec.command, ...invocationSpec.args].map(shellQuote).join(" ")}${stdinRedirect}`;
+  if (spec.worktree?.enabled && spec.worktree.mode === "auto" && fallbackSpec) {
+    lines.push('if [ "${__OPENLOOPS_WORKTREE_OK:-0}" = 1 ]; then', `  ${invocationFor(spec)}`, "else", `  ${invocationFor(fallbackSpec)}`, "fi");
+  } else {
+    lines.push(invocationFor(spec));
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+function remotePreflightScript(spec, metadata) {
+  const lines = [
+    ...remoteBootstrapLines(spec, metadata),
+    "command -v bash >/dev/null 2>&1",
+    `command -v ${shellQuote(spec.shell ? "sh" : spec.command)} >/dev/null 2>&1`
+  ];
+  if (spec.preflightAnyOf?.length) {
+    lines.push(`if ! ${spec.preflightAnyOf.map((command) => `command -v ${shellQuote(command)} >/dev/null 2>&1`).join(" && ! ")}; then`, `  echo 'none of required executables found: ${spec.preflightAnyOf.join(", ")}' >&2`, "  exit 127", "fi");
+  }
+  if (spec.nativeAuthProfile?.provider === "codewith") {
+    lines.push(`__OPENLOOPS_CODEWITH_PROFILES="$(${shellQuote(spec.command)} profile list)" || {`, `  printf '%s\\n' ${shellQuote("codewith auth profile preflight failed")} >&2`, "  exit 1", "}", `if ! printf '%s\\n' "$__OPENLOOPS_CODEWITH_PROFILES" | awk 'NR > 1 { print $1 }' | grep -Fx ${shellQuote(spec.nativeAuthProfile.profile)} >/dev/null; then`, `  printf '%s\\n' ${shellQuote(`codewith auth profile not found: ${spec.nativeAuthProfile.profile}`)} >&2`, "  exit 1", "fi");
+  }
+  return lines.join(`
+`);
+}
+function transportEnv(opts) {
+  const source = opts.env ?? process.env;
+  const env = {};
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined)
+      continue;
+    if (TRANSPORT_ENV_KEYS.has(key) || key.startsWith("LC_"))
+      env[key] = value;
+  }
+  env.PATH = normalizeExecutionPath(env);
+  return env;
+}
+function assertCodewithProfileListed(profile, result) {
+  if (result.error) {
+    throw new Error(`codewith auth profile preflight failed: ${result.error}`);
+  }
+  if ((result.status ?? 1) !== 0) {
+    const detail = (result.stderr || result.stdout || `exit ${result.status ?? "unknown"}`).trim();
+    throw new Error(`codewith auth profile preflight failed${detail ? `: ${detail}` : ""}`);
+  }
+  const profiles = new Set((result.stdout || "").split(/\r?\n/).slice(1).map((line) => line.trim().split(/\s+/)[0]).filter(Boolean));
+  if (!profiles.has(profile)) {
+    throw new Error(`codewith auth profile not found: ${profile}`);
+  }
+}
+function preflightNativeAuthProfileSync(spec, env) {
+  if (spec.nativeAuthProfile?.provider !== "codewith")
+    return;
+  const result = spawnSync2(spec.command, ["profile", "list"], {
+    encoding: "utf8",
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 15000
+  });
+  assertCodewithProfileListed(spec.nativeAuthProfile.profile, {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    error: result.error?.message
+  });
+}
+async function preflightNativeAuthProfile(spec, env) {
+  if (spec.nativeAuthProfile?.provider !== "codewith")
+    return;
+  const result = await spawnCapture(spec.command, ["profile", "list"], { env, timeoutMs: 15000 });
+  assertCodewithProfileListed(spec.nativeAuthProfile.profile, result);
+}
+function codewithAgentStartArgs(target, idempotencyKey) {
+  const args = providerAdapter(target.provider).buildInvocation(target).args;
+  const startIndex = args.findIndex((arg, index) => arg === "start" && args[index - 1] === "agent");
+  if (startIndex === -1)
+    throw new Error("internal error: codewith durable agent args missing agent start");
+  args.splice(startIndex + 1, 0, "--idempotency-key", idempotencyKey);
+  return args;
+}
+function codewithAgentControlArgs(target, command, agentId) {
+  return [
+    ...target.authProfile ? ["--auth-profile", target.authProfile] : [],
+    "agent",
+    command,
+    ...command === "logs" ? ["--limit", "20"] : [],
+    agentId
+  ];
+}
+function parseJsonOutput(stdout, label) {
+  try {
+    const value = JSON.parse(stdout || "{}");
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      throw new Error("not an object");
+    return value;
+  } catch (error) {
+    throw new Error(`${label} did not return JSON${error instanceof Error ? `: ${error.message}` : ""}`);
+  }
+}
+function recordField(value, key) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return;
+  const field = value[key];
+  return field && typeof field === "object" && !Array.isArray(field) ? field : undefined;
+}
+function stringField(value, key) {
+  const field = value?.[key];
+  return typeof field === "string" ? field : undefined;
+}
+function numberField(value, key) {
+  const field = value?.[key];
+  return typeof field === "number" && Number.isFinite(field) ? field : undefined;
+}
+function codewithAgentStatus(readJson) {
+  return stringField(recordField(readJson, "agent"), "status") ?? stringField(recordField(readJson, "statusSnapshot"), "status");
+}
+function codewithAgentEvidence(startJson, readJson, logsJson) {
+  const agent = recordField(readJson, "agent") ?? recordField(startJson, "agent");
+  const statusSnapshot = recordField(readJson, "statusSnapshot");
+  const events = Array.isArray(logsJson?.data) ? logsJson.data.filter((event) => Boolean(event) && typeof event === "object" && !Array.isArray(event)).map((event) => ({
+    seq: numberField(event, "seq"),
+    eventType: stringField(event, "eventType"),
+    createdAt: numberField(event, "createdAt")
+  })) : undefined;
+  return JSON.stringify({
+    codewithAgent: {
+      agentId: stringField(agent, "agentId"),
+      status: stringField(agent, "status"),
+      desiredState: stringField(agent, "desiredState"),
+      statusReason: stringField(agent, "statusReason"),
+      threadId: stringField(agent, "threadId"),
+      rolloutPath: stringField(agent, "rolloutPath"),
+      pid: numberField(agent, "pid"),
+      exitCode: numberField(agent, "exitCode"),
+      created: typeof startJson.created === "boolean" ? startJson.created : undefined
+    },
+    statusSnapshot: statusSnapshot ? {
+      seq: numberField(statusSnapshot, "seq"),
+      status: stringField(statusSnapshot, "status"),
+      summary: stringField(statusSnapshot, "summary"),
+      pendingInteractionCount: numberField(statusSnapshot, "pendingInteractionCount"),
+      lastEventSeq: numberField(statusSnapshot, "lastEventSeq")
+    } : undefined,
+    events
+  }, null, 2);
+}
+function sleep(ms) {
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
+}
+async function executeCodewithDurableAgent(spec, metadata, opts, env, startedAt) {
+  const target = spec.codewithDurableAgent?.target;
+  if (!target)
+    throw new Error("internal error: missing codewith durable target");
+  const maxOutputBytes = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const idempotencyKey = codewithAgentIdempotencyKey(metadata);
+  const start = await spawnCapture(spec.command, codewithAgentStartArgs(target, idempotencyKey), {
+    cwd: spec.cwd,
+    env,
+    timeoutMs: 30000,
+    maxOutputBytes
+  });
+  const stderr = new BoundedOutputBuffer(maxOutputBytes);
+  stderr.append(start.stderr);
+  if (start.error || (start.status ?? 1) !== 0) {
+    return failureResult(startedAt, start.error ?? `codewith agent start exited with code ${start.status ?? "unknown"}`, {
+      exitCode: start.status ?? undefined,
+      stdout: start.stdout,
+      stderr: stderr.value()
+    });
+  }
+  let startJson;
+  try {
+    startJson = parseJsonOutput(start.stdout || "{}", "codewith agent start");
+  } catch (error) {
+    return failureResult(startedAt, error instanceof Error ? error.message : String(error), { stdout: start.stdout, stderr: stderr.value() });
+  }
+  const agentId = stringField(recordField(startJson, "agent"), "agentId");
+  if (!agentId) {
+    return failureResult(startedAt, "codewith agent start did not return agent.agentId", { stdout: start.stdout, stderr: stderr.value() });
+  }
+  const stopAgent = async () => {
+    await spawnCapture(spec.command, codewithAgentControlArgs(target, "stop", agentId), {
+      cwd: spec.cwd,
+      env,
+      timeoutMs: 15000,
+      maxOutputBytes
+    });
+  };
+  const pollMs = Math.max(100, Number(opts.env?.LOOPS_CODEWITH_AGENT_POLL_MS ?? process.env.LOOPS_CODEWITH_AGENT_POLL_MS ?? 2000) || 2000);
+  let lastReadJson = startJson;
+  let lastLogsJson;
+  let lastFingerprint;
+  let lastProgressAt = Date.now();
+  const evidence = () => boundedText(codewithAgentEvidence(startJson, lastReadJson, lastLogsJson), maxOutputBytes);
+  while (true) {
+    if (opts.signal?.aborted) {
+      await stopAgent();
+      return failureResult(startedAt, "cancelled", { stdout: evidence(), stderr: stderr.value() });
+    }
+    const read = await spawnCapture(spec.command, codewithAgentControlArgs(target, "read", agentId), {
+      cwd: spec.cwd,
+      env,
+      timeoutMs: 30000,
+      maxOutputBytes
+    });
+    stderr.append(read.stderr);
+    if (read.error || (read.status ?? 1) !== 0) {
+      return failureResult(startedAt, read.error ?? `codewith agent read exited with code ${read.status ?? "unknown"}`, {
+        exitCode: read.status ?? undefined,
+        stdout: evidence(),
+        stderr: stderr.value()
+      });
+    }
+    try {
+      lastReadJson = parseJsonOutput(read.stdout || "{}", "codewith agent read");
+    } catch (error) {
+      return failureResult(startedAt, error instanceof Error ? error.message : String(error), {
+        stdout: boundedText(read.stdout, maxOutputBytes),
+        stderr: stderr.value()
+      });
+    }
+    const status = codewithAgentStatus(lastReadJson);
+    const fingerprint = JSON.stringify({ status, snapshot: recordField(lastReadJson, "statusSnapshot") ?? null });
+    if (fingerprint !== lastFingerprint) {
+      lastFingerprint = fingerprint;
+      lastProgressAt = Date.now();
+    }
+    if (status === "completed" || status === "failed" || status === "cancelled") {
+      const logs = await spawnCapture(spec.command, codewithAgentControlArgs(target, "logs", agentId), {
+        cwd: spec.cwd,
+        env,
+        timeoutMs: 30000,
+        maxOutputBytes
+      });
+      if (!logs.error && (logs.status ?? 1) === 0) {
+        try {
+          lastLogsJson = parseJsonOutput(logs.stdout || "{}", "codewith agent logs");
+        } catch {
+          lastLogsJson = undefined;
+        }
+      } else {
+        stderr.append(logs.stderr || logs.error || "");
+      }
+      if (status === "completed") {
+        return successResult(startedAt, { exitCode: 0, stdout: evidence(), stderr: stderr.value() });
+      }
+      return failureResult(startedAt, stringField(recordField(lastReadJson, "agent"), "statusReason") ?? `codewith agent ${status}`, { exitCode: 1, stdout: evidence(), stderr: stderr.value() });
+    }
+    if (typeof spec.timeoutMs === "number" && new Date(nowIso()).getTime() - new Date(startedAt).getTime() >= spec.timeoutMs) {
+      await stopAgent();
+      return timeoutResult(startedAt, `timed out after ${spec.timeoutMs}ms`, { stdout: evidence(), stderr: stderr.value() });
+    }
+    if (typeof spec.idleTimeoutMs === "number" && Date.now() - lastProgressAt >= spec.idleTimeoutMs) {
+      await stopAgent();
+      return timeoutResult(startedAt, `idle timed out after ${spec.idleTimeoutMs}ms without agent progress`, {
+        stdout: evidence(),
+        stderr: stderr.value()
+      });
+    }
+    await sleep(pollMs);
+  }
+}
+function resolvedDirEquals(left, right) {
+  try {
+    return realpathSync(left) === realpathSync(right);
+  } catch {
+    return false;
+  }
+}
+async function ensureLocalWorktree(worktree, env) {
+  const { repoRoot, path, branch } = worktree;
+  if (!repoRoot || !path || !branch) {
+    return { error: "worktree preparation requires repoRoot, path, and branch metadata" };
+  }
+  const git = (args) => spawnCapture("git", args, { env, timeoutMs: WORKTREE_GIT_TIMEOUT_MS });
+  let stats;
+  try {
+    stats = lstatSync(path);
+  } catch {
+    stats = undefined;
+  }
+  if (stats?.isSymbolicLink())
+    return { error: `refusing symlinked worktree path ${path}` };
+  const commonDir = async (base) => {
+    const result = await git(["-C", base, "rev-parse", "--git-common-dir"]);
+    if (result.error || (result.status ?? 1) !== 0)
+      return;
+    const raw = result.stdout.trim();
+    if (!raw)
+      return;
+    try {
+      return realpathSync(resolve(base, raw));
+    } catch {
+      return resolve(base, raw);
+    }
+  };
+  if (stats) {
+    const top = await git(["-C", path, "rev-parse", "--show-toplevel"]);
+    if (top.error || (top.status ?? 1) !== 0) {
+      return { error: `refusing to reuse non-worktree path: ${path}` };
+    }
+    if (!resolvedDirEquals(top.stdout.trim(), path)) {
+      return { error: `existing worktree top-level mismatch for ${path}: ${top.stdout.trim()}` };
+    }
+    const expectedCommon = await commonDir(repoRoot);
+    const actualCommon = await commonDir(path);
+    if (!expectedCommon || expectedCommon !== actualCommon) {
+      return { error: `existing worktree ${path} belongs to a different git common dir` };
+    }
+    const current = await git(["-C", path, "branch", "--show-current"]);
+    const actualBranch = current.stdout.trim();
+    if (current.error || (current.status ?? 1) !== 0 || actualBranch !== branch) {
+      return { error: `existing worktree ${path} is on branch ${actualBranch || "unknown"}, expected ${branch}` };
+    }
+    return { cwd: worktree.cwd };
+  }
+  const inside = await git(["-C", repoRoot, "rev-parse", "--is-inside-work-tree"]);
+  if (inside.error || (inside.status ?? 1) !== 0) {
+    return { error: `worktree repoRoot is not a git repository: ${repoRoot}` };
+  }
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+  } catch (error) {
+    return { error: `could not create worktree parent directory: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  const hasBranch = await git(["-C", repoRoot, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+  const add = hasBranch.status === 0 ? await git(["-C", repoRoot, "worktree", "add", path, branch]) : await git(["-C", repoRoot, "worktree", "add", "-b", branch, path, "HEAD"]);
+  if (add.error || (add.status ?? 1) !== 0) {
+    const detail = (add.stderr || add.stdout || add.error || "").toString().trim();
+    return { error: `git worktree add failed for ${path}${detail ? `: ${detail}` : ""}` };
+  }
+  return { cwd: worktree.cwd };
+}
+async function enterWorktree(spec, opts, env, startedAt) {
+  const worktree = spec.worktree;
+  if (!worktree?.enabled || worktree.mode === "off" || worktree.mode === "main")
+    return;
+  const prepared = await ensureLocalWorktree(worktree, env);
+  if (prepared.error) {
+    if (worktree.mode === "required") {
+      return { failure: failureResult(startedAt, `worktree preparation failed (mode=required): ${prepared.error}`) };
+    }
+    opts.log?.(`worktree preparation failed (mode=${worktree.mode}); falling back to ${worktree.originalCwd}: ${prepared.error}`);
+    spec.cwd = worktree.originalCwd;
+    return { fallbackCwd: worktree.originalCwd };
+  }
+  spec.cwd = prepared.cwd ?? spec.cwd;
+  opts.log?.(`entered worktree ${worktree.path ?? spec.cwd}${worktree.branch ? ` branch ${worktree.branch}` : ""}`);
+  return;
+}
+function worktreeFallbackSpec(target, opts, fallbackCwd) {
+  if (target.type !== "agent")
+    return;
+  const agentTarget = target;
+  const fallbackTarget = {
+    ...agentTarget,
+    cwd: fallbackCwd,
+    worktree: agentTarget.worktree ? { ...agentTarget.worktree, enabled: false, cwd: fallbackCwd, reason: "auto worktree preparation failed" } : undefined
+  };
+  return commandSpec(fallbackTarget, opts);
+}
+function preflightRemoteSpec(spec, machine, metadata, opts) {
+  const plan = (opts.machineCommandResolver ?? resolveMachineCommand)(machine.id, "bash -s");
+  const result = spawnSync2(plan.command, plan.args, {
+    encoding: "utf8",
+    env: transportEnv(opts),
+    input: remotePreflightScript(spec, metadata),
+    stdio: ["pipe", "pipe", "pipe"],
+    timeout: 15000
+  });
+  if (result.error)
+    throw new Error(`remote preflight failed on ${machine.id}: ${result.error.message}`);
+  if ((result.status ?? 1) !== 0) {
+    const detail = (result.stderr || result.stdout || `exit ${result.status ?? "unknown"}`).trim();
+    throw new Error(`remote preflight failed on ${machine.id}${detail ? `: ${detail}` : ""}`);
+  }
+}
+async function executeRemoteSpec(spec, machine, metadata, opts, fallbackSpec) {
+  const maxOutputBytes = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const startedAt = nowIso();
+  const stdout = new BoundedOutputBuffer(maxOutputBytes);
+  const stderr = new BoundedOutputBuffer(maxOutputBytes);
+  let timedOut = false;
+  let idleTimedOut = false;
+  let exitCode;
+  let error;
+  let plan;
+  let script;
+  try {
+    plan = (opts.machineCommandResolver ?? resolveMachineCommand)(machine.id, "bash -s");
+    script = remoteScript(spec, metadata, fallbackSpec);
+  } catch (err) {
+    return failureResult(startedAt, err instanceof Error ? err.message : String(err));
+  }
+  const child = spawn2(plan.command, plan.args, {
+    env: transportEnv(opts),
+    detached: true,
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  notifySpawn(child.pid, opts);
+  child.stdin?.on("error", (err) => {
+    if (err.code !== "EPIPE")
+      error = err.message;
+  });
+  child.stdin?.end(script);
+  const abortHandler = () => {
+    error = "cancelled";
+    if (child.pid)
+      killProcessGroup(child.pid);
+  };
+  if (opts.signal?.aborted)
+    abortHandler();
+  opts.signal?.addEventListener("abort", abortHandler, { once: true });
+  const timer = typeof spec.timeoutMs === "number" ? setTimeout(() => {
+    timedOut = true;
+    if (child.pid)
+      killProcessGroup(child.pid);
+  }, spec.timeoutMs) : undefined;
+  timer?.unref();
+  let idleTimer;
+  const resetIdleTimer = () => {
+    if (!spec.idleTimeoutMs)
+      return;
+    if (idleTimer)
+      clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      idleTimedOut = true;
+      if (child.pid)
+        killProcessGroup(child.pid);
+    }, spec.idleTimeoutMs);
+    idleTimer.unref();
+  };
+  resetIdleTimer();
+  child.stdout?.setEncoding("utf8");
+  child.stderr?.setEncoding("utf8");
+  child.stdout?.on("data", (chunk) => {
+    stdout.append(chunk);
+    resetIdleTimer();
+  });
+  child.stderr?.on("data", (chunk) => {
+    stderr.append(chunk);
+    resetIdleTimer();
+  });
+  try {
+    const [code, signal] = await once(child, "exit");
+    if (typeof code === "number")
+      exitCode = code;
+    if (signal)
+      error = `terminated by ${signal}`;
+  } catch (err) {
+    error = err instanceof Error ? err.message : String(err);
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+    if (idleTimer)
+      clearTimeout(idleTimer);
+    opts.signal?.removeEventListener("abort", abortHandler);
+  }
+  const fields = { exitCode, stdout: stdout.value(), stderr: stderr.value(), pid: child.pid };
+  if (timedOut || idleTimedOut) {
+    return timeoutResult(startedAt, idleTimedOut ? `idle timed out after ${spec.idleTimeoutMs}ms without stdout/stderr` : `timed out after ${spec.timeoutMs}ms`, fields);
+  }
+  if (error || exitCode !== 0) {
+    return failureResult(startedAt, error ?? `remote process on ${machine.id} exited with code ${exitCode ?? "unknown"}`, fields);
+  }
+  return successResult(startedAt, fields);
+}
+function preflightTarget(target, metadata = {}, opts = {}) {
+  const spec = commandSpec(target, opts);
+  const machine = resolvedMachine(opts);
+  if (machine && !machine.local) {
+    preflightRemoteSpec(spec, machine, metadata, opts);
+    return {
+      command: spec.command,
+      accountProfile: spec.account?.profile,
+      accountTool: spec.accountTool
+    };
+  }
+  const env = executionEnvSync(spec, metadata, opts);
+  if (!spec.shell && !executableExists(spec.command, env)) {
+    throw new Error(commandNotFoundMessage(spec.command, env));
+  }
+  if (spec.preflightAnyOf?.length && !spec.preflightAnyOf.some((command) => executableExists(command, env))) {
+    throw new Error(`none of required executables found: ${spec.preflightAnyOf.join(", ")}`);
+  }
+  preflightNativeAuthProfileSync(spec, env);
+  return {
+    command: spec.command,
+    accountProfile: spec.account?.profile,
+    accountTool: spec.accountTool
+  };
+}
+async function executeTarget(target, metadata = {}, opts = {}) {
+  let spec = commandSpec(target, opts);
+  const machine = resolvedMachine(opts);
+  if (machine && !machine.local && spec.codewithDurableAgent) {
+    return failureResult(nowIso(), "remote Codewith durable background-agent steps require remote status polling support; run this Codewith step locally or add remote durable readback before dispatch");
+  }
+  if (machine && !machine.local) {
+    const remoteFallbackSpec = spec.worktree?.enabled && spec.worktree.mode === "auto" ? worktreeFallbackSpec(target, opts, spec.worktree.originalCwd) : undefined;
+    return executeRemoteSpec(spec, machine, metadata, opts, remoteFallbackSpec);
+  }
+  const maxOutputBytes = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+  const startedAt = nowIso();
+  const stdout = new BoundedOutputBuffer(maxOutputBytes);
+  const stderr = new BoundedOutputBuffer(maxOutputBytes);
+  let timedOut = false;
+  let idleTimedOut = false;
+  let exitCode;
+  let error;
+  const env = await executionEnv(spec, metadata, opts);
+  if (!spec.shell && !executableExists(spec.command, env)) {
+    return failureResult(startedAt, commandNotFoundMessage(spec.command, env));
+  }
+  if (spec.preflightAnyOf?.length && !spec.preflightAnyOf.some((command) => executableExists(command, env))) {
+    return failureResult(startedAt, `none of required executables found: ${spec.preflightAnyOf.join(", ")}`);
+  }
+  try {
+    await preflightNativeAuthProfile(spec, env);
+  } catch (err) {
+    return failureResult(startedAt, err instanceof Error ? err.message : String(err));
+  }
+  const worktreeEntry = await enterWorktree(spec, opts, env, startedAt);
+  if (worktreeEntry?.failure)
+    return worktreeEntry.failure;
+  if (worktreeEntry?.fallbackCwd) {
+    spec = worktreeFallbackSpec(target, opts, worktreeEntry.fallbackCwd) ?? spec;
+  }
+  if (spec.codewithDurableAgent) {
+    return executeCodewithDurableAgent(spec, metadata, opts, env, startedAt);
+  }
+  const child = spawn2(spec.command, spec.args, {
+    cwd: spec.cwd,
+    env,
+    shell: spec.shell ?? false,
+    detached: true,
+    stdio: spec.stdin === undefined ? ["ignore", "pipe", "pipe"] : ["pipe", "pipe", "pipe"]
+  });
+  notifySpawn(child.pid, opts);
+  if (spec.stdin !== undefined && child.stdin) {
+    child.stdin.on("error", (err) => {
+      if (err.code !== "EPIPE")
+        error = err.message;
+    });
+    child.stdin.end(spec.stdin);
+  }
+  const abortHandler = () => {
+    error = "cancelled";
+    if (child.pid)
+      killProcessGroup(child.pid);
+  };
+  if (opts.signal?.aborted)
+    abortHandler();
+  opts.signal?.addEventListener("abort", abortHandler, { once: true });
+  const timer = typeof spec.timeoutMs === "number" ? setTimeout(() => {
+    timedOut = true;
+    if (child.pid)
+      killProcessGroup(child.pid);
+  }, spec.timeoutMs) : undefined;
+  timer?.unref();
+  let idleTimer;
+  const resetIdleTimer = () => {
+    if (!spec.idleTimeoutMs)
+      return;
+    if (idleTimer)
+      clearTimeout(idleTimer);
+    idleTimer = setTimeout(() => {
+      idleTimedOut = true;
+      if (child.pid)
+        killProcessGroup(child.pid);
+    }, spec.idleTimeoutMs);
+    idleTimer.unref();
+  };
+  resetIdleTimer();
+  child.stdout?.setEncoding("utf8");
+  child.stderr?.setEncoding("utf8");
+  child.stdout?.on("data", (chunk) => {
+    stdout.append(chunk);
+    resetIdleTimer();
+  });
+  child.stderr?.on("data", (chunk) => {
+    stderr.append(chunk);
+    resetIdleTimer();
+  });
+  try {
+    const [code, signal] = await once(child, "exit");
+    if (typeof code === "number")
+      exitCode = code;
+    if (signal)
+      error = `terminated by ${signal}`;
+  } catch (err) {
+    error = err instanceof Error ? err.message : String(err);
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+    if (idleTimer)
+      clearTimeout(idleTimer);
+    opts.signal?.removeEventListener("abort", abortHandler);
+  }
+  const fields = { exitCode, stdout: stdout.value(), stderr: stderr.value(), pid: child.pid };
+  if (timedOut || idleTimedOut) {
+    return timeoutResult(startedAt, idleTimedOut ? `idle timed out after ${spec.idleTimeoutMs}ms without stdout/stderr` : `timed out after ${spec.timeoutMs}ms`, fields);
+  }
+  if (error || exitCode !== 0) {
+    return failureResult(startedAt, error ?? `process exited with code ${exitCode ?? "unknown"}`, fields);
+  }
+  return successResult(startedAt, fields);
+}
+async function executeLoop(loop, run, opts = {}) {
+  if (loop.target.type === "workflow") {
+    throw new Error("workflow loop targets must be executed with executeLoopTarget");
+  }
+  if (loop.target.preflight?.beforeRun) {
+    const startedAt = nowIso();
+    try {
+      preflightTarget(loop.target, {
+        loopId: loop.id,
+        loopName: loop.name,
+        runId: run.id,
+        scheduledFor: run.scheduledFor
+      }, { ...opts, machine: opts.machine ?? loop.machine });
+    } catch (error) {
+      return failureResult(startedAt, `runtime preflight failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return executeTarget(loop.target, {
+    loopId: loop.id,
+    loopName: loop.name,
+    runId: run.id,
+    scheduledFor: run.scheduledFor
+  }, { ...opts, machine: opts.machine ?? loop.machine });
+}
+
+// src/runner/index.ts
 var program = new Command;
+var DEFAULT_RUNNER_ID = `runner:${process.pid}`;
+var MIN_RUNNER_LEASE_MS = 1000;
 program.name("loops-runner").description("OpenLoops control-plane runner foundation").version(packageVersion()).option("-j, --json", "print JSON");
+function configuredApiUrl(env = process.env) {
+  return env.LOOPS_API_URL?.trim() || env.HASNA_LOOPS_API_URL?.trim() || env.LOOPS_CLOUD_API_URL?.trim() || env.HASNA_LOOPS_CLOUD_API_URL?.trim();
+}
+function configuredApiToken(env = process.env) {
+  return env.LOOPS_API_TOKEN?.trim() || env.HASNA_LOOPS_API_TOKEN?.trim() || env.LOOPS_CLOUD_TOKEN?.trim() || env.HASNA_LOOPS_CLOUD_TOKEN?.trim();
+}
+function isLocalApiUrl(value) {
+  try {
+    const url = new URL(value);
+    return ["127.0.0.1", "localhost", "::1"].includes(url.hostname);
+  } catch {
+    return false;
+  }
+}
 function runnerStatus(machineId = process.env.LOOPS_RUNNER_MACHINE_ID || process.env.HASNA_MACHINE_ID) {
   const deployment = buildDeploymentStatus();
+  const local = deployment.deploymentMode === "local";
+  const apiUrl = configuredApiUrl();
+  const token = configuredApiToken();
+  const apiReady = Boolean(apiUrl && (isLocalApiUrl(apiUrl) || token));
   return {
-    ok: deployment.deploymentMode === "local" || deployment.controlPlane.configured,
+    ok: local || apiReady,
     service: "loops-runner",
     machineId,
     deployment,
-    state: deployment.deploymentMode === "local" ? "local_daemon_authoritative" : deployment.controlPlane.configured ? "ready_for_control_plane" : "missing_control_plane_configuration"
+    state: local ? "local_daemon_authoritative" : apiReady ? "control_plane_ready" : apiUrl ? "missing_control_plane_token" : "missing_control_plane_api_url"
   };
 }
+function resolveRunnerConfig(opts) {
+  const env = opts.env ?? process.env;
+  const apiUrl = opts.apiUrl ?? configuredApiUrl(env);
+  if (!apiUrl)
+    throw new Error("loops-runner requires LOOPS_API_URL or HASNA_LOOPS_API_URL");
+  const token = opts.apiToken ?? configuredApiToken(env);
+  if (!isLocalApiUrl(apiUrl) && !token)
+    throw new Error("non-local loops-runner requires LOOPS_API_TOKEN or HASNA_LOOPS_API_TOKEN");
+  return {
+    apiUrl,
+    token,
+    runnerId: opts.runnerId ?? env.LOOPS_RUNNER_ID ?? env.LOOPS_RUNNER_MACHINE_ID ?? env.HASNA_MACHINE_ID ?? DEFAULT_RUNNER_ID,
+    machineId: opts.machineId ?? env.LOOPS_RUNNER_MACHINE_ID ?? env.HASNA_MACHINE_ID
+  };
+}
+function endpoint(base, path) {
+  return new URL(path.replace(/^\//, ""), base.endsWith("/") ? base : `${base}/`).toString();
+}
+async function postJson(fetchImpl, config, path, body) {
+  const response = await fetchImpl(endpoint(config.apiUrl, path), {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      ...config.token ? { authorization: `Bearer ${config.token}` } : {}
+    },
+    body: JSON.stringify(body)
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok)
+    throw new Error(typeof payload.error === "string" ? payload.error : `loops-api request failed: ${response.status}`);
+  return payload;
+}
+async function runRunnerOnce(opts = {}) {
+  const config = resolveRunnerConfig(opts);
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const runnerBody = {
+    runnerId: config.runnerId,
+    machineId: config.machineId,
+    now: (opts.now ?? new Date).toISOString(),
+    maxClaims: 1
+  };
+  await postJson(fetchImpl, config, "/v1/runners/register", runnerBody);
+  const claimed = await postJson(fetchImpl, config, "/v1/runners/claim", runnerBody);
+  const claims = Array.isArray(claimed.claims) ? claimed.claims : [];
+  const completed = [];
+  for (const claim of claims) {
+    const result = await executeClaimWithHeartbeat(fetchImpl, config, claim, opts);
+    const finalized = await postJson(fetchImpl, config, `/v1/runs/${claim.run.id}/finalize`, {
+      claimToken: claim.claimToken,
+      status: result.status,
+      finishedAt: result.finishedAt,
+      durationMs: result.durationMs,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      error: result.error,
+      exitCode: result.exitCode,
+      pid: result.pid
+    });
+    const run = finalized.run ?? claim.run;
+    completed.push(run);
+  }
+  return { ok: completed.every((run) => run.status === "succeeded"), claimed: claims.length, completed };
+}
+async function executeClaimWithHeartbeat(fetchImpl, config, claim, opts) {
+  const execute = opts.execute ?? executeLoop;
+  const leaseMs = runnerLeaseMs(claim.loop.leaseMs);
+  const heartbeatIntervalMs = runnerHeartbeatIntervalMs(leaseMs, opts.heartbeatIntervalMs);
+  const heartbeat = async () => {
+    await postJson(fetchImpl, config, `/v1/runs/${claim.run.id}/heartbeat`, {
+      claimToken: claim.claimToken,
+      leaseMs
+    });
+  };
+  await heartbeat();
+  let lastHeartbeatError;
+  const timer = setInterval(() => {
+    heartbeat().catch((error) => {
+      lastHeartbeatError = error;
+    });
+  }, heartbeatIntervalMs);
+  try {
+    const result = await execute(claim.loop, claim.run);
+    return result;
+  } finally {
+    clearInterval(timer);
+  }
+}
+function runnerLeaseMs(leaseMs) {
+  return Math.max(MIN_RUNNER_LEASE_MS, leaseMs);
+}
+function runnerHeartbeatIntervalMs(leaseMs, configured) {
+  const boundedLeaseMs = Number.isFinite(leaseMs) && leaseMs > 0 ? leaseMs : 30000;
+  const safeDefault = Math.max(1, Math.floor(boundedLeaseMs / 2));
+  const requested = configured === undefined ? safeDefault : Math.max(1, Math.floor(configured));
+  return Math.min(30000, safeDefault, requested);
+}
 function wantsJson(opts) {
   return Boolean(program.opts().json || opts?.json);
 }
@@ -283,6 +2011,19 @@ async function main(argv = process.argv) {
 }
 program.action(() => printStatus());
 program.command("status").option("-j, --json", "print JSON").action((opts) => printStatus(opts));
+program.command("run-once").description("claim and execute one control-plane run").option("--api-url <url>", "control-plane API URL").option("--runner-id <id>", "runner id").option("--machine-id <id>", "machine id").option("-j, --json", "print JSON").action(async (opts) => {
+  const result = await runRunnerOnce({
+    apiUrl: opts.apiUrl,
+    runnerId: opts.runnerId,
+    machineId: opts.machineId
+  });
+  if (wantsJson(opts))
+    console.log(JSON.stringify(result, null, 2));
+  else
+    console.log(`claimed=${result.claimed} completed=${result.completed.length}`);
+  if (!result.ok)
+    process.exitCode = 1;
+});
 if (import.meta.main) {
   main().catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));
@@ -291,5 +2032,6 @@ if (import.meta.main) {
 }
 export {
   runnerStatus,
+  runRunnerOnce,
   main
 };