@felixdotgo/aidlc-kit 0.0.1 → 0.1.1

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

@@ -0,0 +1,131 @@
+import { randomUUID } from "node:crypto";
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { assertLoopPath } from "./loop-lease.mjs";
+import { validateRoot } from "./loop-runtime.mjs";
+import { acquireStateLock, loadTask, nextAction } from "./store.mjs";
+import { recoverLeadArtifact } from "./loop-lead-artifacts.mjs";
+
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const checkAuthority = (authority) => { if (authority !== "local") throw new Error("local supervisor adapter requires local authority"); };
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (error) { return error?.code !== "ESRCH"; } };
+const wait = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+function readLease(path, taskId) {
+  try {
+    const lease = JSON.parse(readFileSync(path, "utf8"));
+    if (lease?.taskId !== taskId || !Number.isSafeInteger(lease.pid) || lease.pid < 1 || typeof lease.token !== "string" || !lease.token) throw new Error("invalid fields");
+    return lease;
+  } catch (error) { if (error?.code === "ENOENT") return null; throw new Error(`Corrupt supervisor lease for ${taskId}: ${error.message}`); }
+}
+
+function writeExclusive(path, value) {
+  const fd = openSync(path, "wx", 0o600);
+  try { writeFileSync(fd, `${JSON.stringify(value)}\n`); fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+/** Local durable checkpoint + separate PID-fenced supervisor lock.
+ * The lock uses a distinct task key from the runner's lease so humans can approve.
+ * This adapter intentionally does not implement runTurn or perform approvals.
+ */
+export function createLocalSupervisorAdapter({ root: rootInput, taskId }) {
+  const root = validateRoot(rootInput);
+  const checkpointPath = assertLoopPath(root, taskId, ".supervisor.json");
+  const leasePath = assertLoopPath(root, taskId, ".supervisor.lease");
+  const guardPath = assertLoopPath(root, taskId, ".supervisor.guard");
+  let token;
+  const withGuard = (action) => {
+    assertLoopPath(root, taskId, ".supervisor.guard");
+    mkdirSync(dirname(guardPath), { recursive: true });
+    const guard = { taskId, pid: process.pid, token: randomUUID() }, deadline = Date.now() + 5000;
+    for (;;) {
+      try { writeExclusive(guardPath, guard); break; }
+      catch (error) {
+        if (error?.code !== "EEXIST") throw error;
+        const existing = readLease(guardPath, taskId);
+        if (!existing) continue;
+        if (!alive(existing.pid)) { if (readLease(guardPath, taskId)?.token === existing.token) { try { unlinkSync(guardPath); } catch (e) { if (e?.code !== "ENOENT") throw e; } } continue; }
+        if (Date.now() >= deadline) throw new Error(`Timed out waiting for supervisor guard: ${taskId}`);
+        wait(10);
+      }
+    }
+    try { return action(); } finally { if (readLease(guardPath, taskId)?.token === guard.token) unlinkSync(guardPath); }
+  };
+  const checkScope = (input) => { checkAuthority(input?.authority); if (input?.taskId !== taskId) throw new Error("supervisor task mismatch"); };
+  const assertOwned = async () => {
+    assertLoopPath(root, taskId, ".supervisor.lease");
+    const current = readLease(leasePath, taskId);
+    if (!token || !current || current.token !== token || current.pid !== process.pid) throw new Error("local supervisor ownership lost");
+  };
+  const readCheckpoint = () => {
+    assertLoopPath(root, taskId, ".supervisor.json");
+    try {
+      const value = JSON.parse(readFileSync(checkpointPath, "utf8"));
+      if (!value || value.version !== 1 || value.taskId !== taskId || value.authority !== "local") throw new Error("wrong task or authority");
+      return value;
+    } catch (error) {
+      if (error?.code === "ENOENT") return null;
+      throw new Error(`Corrupt supervisor checkpoint for ${taskId}: ${error.message}`);
+    }
+  };
+  const syncDir = () => { const dir = openSync(dirname(checkpointPath), "r"); try { fsyncSync(dir); } finally { closeSync(dir); } };
+  return {
+    async acquireSupervisor(input) {
+      checkScope(input);
+      if (token) throw new Error("local supervisor adapter is already acquired");
+      if (input.signal?.aborted) throw new Error("supervisor already aborted");
+      const newToken = randomUUID();
+      withGuard(() => {
+        assertLoopPath(root, taskId, ".supervisor.lease");
+        const existing = readLease(leasePath, taskId);
+        if (existing && alive(existing.pid)) throw new Error(`Task ${taskId} already has a live supervisor (pid ${existing.pid})`);
+        if (existing && readLease(leasePath, taskId)?.token === existing.token) unlinkSync(leasePath);
+        writeExclusive(leasePath, { taskId, pid: process.pid, token: newToken });
+      });
+      token = newToken;
+      return { assertOwned, release: async () => { if (token !== newToken) return; withGuard(() => { if (readLease(leasePath, taskId)?.token === newToken) unlinkSync(leasePath); }); token = undefined; } };
+    },
+    async readTask(input) {
+      checkScope({ ...input, authority: "local" });
+      const release = acquireStateLock(root);
+      try {
+        if (token) await assertOwned();
+        const task = loadTask(root, taskId);
+        if (!task || task.id !== taskId) throw new Error("invalid local canonical task snapshot");
+        if (token) {
+          await recoverLeadArtifact({ root, taskId, task, assertOwned });
+          await assertOwned();
+        } else {
+          const journal = join(root, ".agents", "data", "tasks", taskId, ".lead-artifact-journal.json");
+          try { lstatSync(journal); throw new Error("Pending lead artifact journal requires supervised recovery"); }
+          catch (error) { if (error?.code !== "ENOENT") throw error; }
+        }
+        return { task, nextAction: nextAction(task, root) };
+      } finally { release(); }
+    },
+    async loadCheckpoint(input) { checkScope(input); await assertOwned(); return readCheckpoint(); },
+    async saveCheckpoint(input) {
+      checkScope(input); await assertOwned();
+      if (!input.checkpoint || input.checkpoint.taskId !== taskId || input.checkpoint.authority !== "local") throw new Error("invalid local checkpoint");
+      if (!same(readCheckpoint(), input.previous ?? null)) throw new Error("supervisor checkpoint conflict");
+      mkdirSync(dirname(checkpointPath), { recursive: true });
+      const temporary = `${checkpointPath}.tmp-${process.pid}-${randomUUID()}`;
+      let fd;
+      try {
+        fd = openSync(temporary, "wx", 0o600); writeFileSync(fd, `${JSON.stringify(input.checkpoint)}\n`); fsyncSync(fd); closeSync(fd); fd = undefined;
+        await assertOwned();
+        if (!same(readCheckpoint(), input.previous ?? null)) throw new Error("supervisor checkpoint conflict");
+        renameSync(temporary, checkpointPath); syncDir();
+      } finally {
+        if (fd !== undefined) closeSync(fd);
+        if (existsSync(temporary)) unlinkSync(temporary);
+      }
+    },
+    async clearCheckpoint(input) {
+      checkScope(input); await assertOwned();
+      const current = readCheckpoint();
+      if (!same(current, input.checkpoint)) throw new Error("supervisor checkpoint conflict");
+      if (current) { unlinkSync(checkpointPath); syncDir(); }
+    }
+  };
+}

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

@@ -0,0 +1,55 @@
+import { createHash } from "node:crypto";
+import { requireLocalAuthority } from "./authority.mjs";
+import { runAgentTurn, isLoopProvider, LOOP_PROVIDER_LIST } from "./loop-drivers.mjs";
+import { readLoopRecord, runLoop, validateRoot } from "./loop-runtime.mjs";
+import { runSupervisor } from "./loop-supervisor.mjs";
+import { createLocalSupervisorAdapter } from "./loop-supervisor-local.mjs";
+
+const digest = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+
+/**
+ * Bind the canonical local store, distinct supervisor lease and the existing
+ * leased runner. The caller owns process supervision and human gate approval.
+ * Abort stops polling or the next turn; the current runLoop call is bounded by
+ * its existing timeouts and is not cancelled by this wrapper.
+ */
+export function createLocalLoopSupervisor({ root: rootInput, taskId, agent, limits, driver = runAgentTurn, preflight = true, pollMs, signal, onEvent = () => {}, runner = runLoop } = {}) {
+  requireLocalAuthority();
+  const root = validateRoot(rootInput);
+  if (!isLoopProvider(agent)) throw new Error(`local lead agent must be ${LOOP_PROVIDER_LIST}`);
+  if (typeof driver !== "function" || typeof runner !== "function" || typeof onEvent !== "function") throw new Error("invalid local supervisor callbacks");
+  const adapter = createLocalSupervisorAdapter({ root, taskId });
+  const getRecord = () => readLoopRecord(root, taskId);
+  const execute = async (mode) => {
+    requireLocalAuthority();
+    const record = getRecord();
+    if (mode === "run" && record) throw new Error("Local loop record already exists; use resume");
+    if (mode === "resume" && !record) throw new Error("Local loop record missing; use start");
+    if (record && record.agent !== agent) throw new Error("Resume must use the recorded lead agent");
+    let nextMode = mode;
+    return runSupervisor({ taskId, authority: "local", ...adapter, pollMs, signal, onEvent,
+      runTurn: async ({ precondition }) => {
+        if (signal?.aborted) return { status: "stopped", taskId };
+        requireLocalAuthority();
+        let expected = precondition;
+        if (!expected) {
+          const snapshot = await adapter.readTask({ taskId });
+          if (snapshot.task.status !== "active" || snapshot.nextAction.classification !== "run_phase") return { status: "blocked", taskId, reason: "Canonical state changed before runner acquired lease" };
+          expected = { taskId, phase: snapshot.task.phase, taskHash: digest(snapshot.task), evidenceHash: digest(snapshot.task.evidence), evidenceCount: snapshot.task.evidence.length };
+        }
+        const result = await runner({ root, taskId, agent, mode: nextMode, limits, driver, preflight, precondition: expected, onEvent });
+        nextMode = "resume";
+        return result;
+      }
+    });
+  };
+  return {
+    start: () => execute("run"),
+    resume: () => execute("resume"),
+    async status() {
+      requireLocalAuthority();
+      const snapshot = await adapter.readTask({ taskId });
+      return { taskId, authority: "local", record: getRecord(), nextAction: snapshot.nextAction };
+    }
+  };
+}

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

@@ -0,0 +1,101 @@
+import { createHash } from "node:crypto";
+import { setTimeout as sleep } from "node:timers/promises";
+
+const TARGET = { G0_confirm: "plan", G1_review: "build", G2_codereview: "wrap" };
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const required = (value, name) => { if (typeof value !== "function") throw new Error(`${name} is required`); return value; };
+const validId = (value, name) => { if (typeof value !== "string" || !ID.test(value)) throw new Error(`invalid ${name}`); };
+
+function validateSnapshot(snapshot, taskId) {
+  if (!snapshot || snapshot.task?.id !== taskId || !Array.isArray(snapshot.task.evidence) || !snapshot.nextAction || !["run_phase", "await_user", "blocked", "terminal", "complete"].includes(snapshot.nextAction.classification)) throw new Error("invalid canonical task snapshot");
+  return snapshot;
+}
+
+/** Checkpoints contain a digest, not the task evidence or user-provided approval text. */
+export function makeGateCheckpoint({ taskId, authority, snapshot, result }) {
+  validId(taskId, "task ID");
+  if (!["local", "fleet"].includes(authority)) throw new Error("invalid authority");
+  validateSnapshot(snapshot, taskId);
+  const gate = result?.gate ?? result?.nextAction?.gate;
+  if (!TARGET[gate] || snapshot.task.gate !== gate || snapshot.task.status !== "blocked_on_user" || snapshot.nextAction.classification !== "await_user" || (result.taskId && result.taskId !== taskId)) throw new Error("gate changed before supervisor checkpoint; inspect state manually");
+  if (authority === "fleet" && (!result.snapshotId || !Number.isSafeInteger(snapshot.revision))) throw new Error("fleet gate requires snapshot ID and revision");
+  return { version: 1, taskId, authority, gate, phase: snapshot.task.phase, taskHash: hash(snapshot.task), evidenceCount: snapshot.task.evidence.length, evidenceHash: hash(snapshot.task.evidence), ...(authority === "fleet" ? { snapshotId: result.snapshotId, revision: snapshot.revision } : {}) };
+}
+
+/** Return wait/resume/blocked only from fresh canonical state, never grant approval. */
+export async function checkGateCheckpoint({ checkpoint, snapshot, verifyFleetApproval, verifyLocalApproval }) {
+  if (!checkpoint || checkpoint.version !== 1 || !TARGET[checkpoint.gate] || !["local", "fleet"].includes(checkpoint.authority) || !Number.isSafeInteger(checkpoint.evidenceCount) || checkpoint.evidenceCount < 0 || typeof checkpoint.evidenceHash !== "string" || typeof checkpoint.taskHash !== "string") throw new Error("invalid gate checkpoint");
+  validId(checkpoint.taskId, "checkpoint task ID");
+  validateSnapshot(snapshot, checkpoint.taskId);
+  const { task, nextAction } = snapshot;
+  if (task.evidence.length < checkpoint.evidenceCount || hash(task.evidence.slice(0, checkpoint.evidenceCount)) !== checkpoint.evidenceHash) return { status: "blocked", reason: "gate evidence changed since checkpoint" };
+  if (task.status === "paused" || task.handoff || ["blocked", "terminal", "complete"].includes(nextAction.classification)) return { status: "blocked", reason: "task is paused, blocked, or terminal" };
+  if (task.phase === checkpoint.phase && task.gate === checkpoint.gate && task.status === "blocked_on_user" && nextAction.classification === "await_user") {
+    if (checkpoint.authority === "fleet" && hash(task) !== checkpoint.taskHash) return { status: "blocked", reason: "fleet review snapshot is stale" };
+    return { status: "wait" };
+  }
+  const appended = task.evidence.slice(checkpoint.evidenceCount);
+  const approvals = appended.filter((entry) => entry.kind === "approval" && entry.gate === checkpoint.gate && entry.result === "pass" && typeof entry.source === "string" && entry.source.trim());
+  if (task.phase !== TARGET[checkpoint.gate] || task.status !== "active" || nextAction.classification !== "run_phase" || approvals.length !== 1) return { status: "blocked", reason: "gate changed without its matching approval" };
+  if (checkpoint.authority === "local" && verifyLocalApproval && !await verifyLocalApproval({ checkpoint, snapshot })) return { status: "blocked", reason: "local approval lacks the matching host receipt" };
+  if (checkpoint.authority === "fleet") {
+    if (!checkpoint.snapshotId || !Number.isSafeInteger(checkpoint.revision) || !Number.isSafeInteger(snapshot.revision) || snapshot.revision <= checkpoint.revision) return { status: "blocked", reason: "fleet gate revision is stale" };
+    if (!await required(verifyFleetApproval, "verifyFleetApproval")({ checkpoint, snapshot })) return { status: "blocked", reason: "fleet approval does not match review snapshot" };
+  }
+  return { status: "resume", precondition: { taskId: checkpoint.taskId, gate: checkpoint.gate, phase: task.phase, taskHash: hash(task), evidenceCount: task.evidence.length, evidenceHash: hash(task.evidence), ...(checkpoint.authority === "fleet" ? { revision: snapshot.revision, snapshotId: checkpoint.snapshotId } : {}) } };
+}
+
+/**
+ * Supervises short runner invocations. runTurn MUST acquire its existing exclusive
+ * loop lease/lead epoch, reread canonical state, and enforce the supplied precondition
+ * before doing any work; if no precondition is supplied it MUST still verify
+ * run_phase under the lease. It MUST release the lease before returning a gate. Fleet
+ * runTurn additionally reconciles uncertain jobs and Git before dispatch. The
+ * checkpoint adapter MUST persist atomically, be scoped to task+authority, and be
+ * concurrency safe. acquireSupervisor MUST provide an independently fenced,
+ * renewable exclusive supervisor lease that does not block human gate approval.
+ * No callback is allowed to approve a human gate.
+ */
+export async function runSupervisor({ taskId, authority, acquireSupervisor, readTask, runTurn, loadCheckpoint, saveCheckpoint, clearCheckpoint, verifyFleetApproval, verifyLocalApproval, pollMs = 5000, signal, onEvent = () => {} }) {
+  validId(taskId, "task ID");
+  if (!["local", "fleet"].includes(authority)) throw new Error("invalid authority");
+  for (const [name, value] of Object.entries({ acquireSupervisor, readTask, runTurn, loadCheckpoint, saveCheckpoint, clearCheckpoint, onEvent })) required(value, name);
+  if (!Number.isSafeInteger(pollMs) || pollMs < 1 || pollMs > 300000) throw new Error("invalid poll interval");
+  const ownership = await acquireSupervisor({ taskId, authority, signal });
+  if (!ownership || typeof ownership.assertOwned !== "function" || typeof ownership.release !== "function") throw new Error("supervisor ownership must provide assertOwned and release");
+  try {
+  let checkpoint = await loadCheckpoint({ taskId, authority });
+  if (checkpoint && (checkpoint.taskId !== taskId || checkpoint.authority !== authority)) throw new Error("checkpoint authority or task mismatch");
+  while (!signal?.aborted) {
+    const snapshot = validateSnapshot(await readTask({ taskId }), taskId);
+    let precondition;
+    if (checkpoint) {
+      const verdict = await checkGateCheckpoint({ checkpoint, snapshot, verifyFleetApproval, verifyLocalApproval });
+      if (verdict.status === "blocked") return { status: "blocked", taskId, reason: verdict.reason };
+      if (verdict.status === "wait") {
+        try { await sleep(pollMs, undefined, { signal }); } catch (error) { if (error?.name !== "AbortError") throw error; }
+        continue;
+      }
+      precondition = verdict.precondition;
+    } else if (snapshot.nextAction.classification !== "run_phase") {
+      return { status: snapshot.nextAction.classification === "await_user" ? "blocked" : snapshot.nextAction.classification, taskId, reason: snapshot.nextAction.classification === "await_user" ? "gate checkpoint missing; inspect the gate before resuming" : snapshot.nextAction.reason };
+    }
+    // Leave the durable gate checkpoint intact until the next stop is saved. A
+    // crash during a turn then cannot cause an unverified automatic restart.
+    await ownership.assertOwned();
+    const result = await runTurn({ taskId, authority, precondition, signal });
+    if (result?.status !== "gate") {
+      if (checkpoint && ["complete", "terminal"].includes(result?.status)) await clearCheckpoint({ taskId, authority, checkpoint });
+      return result;
+    }
+    const fresh = validateSnapshot(await readTask({ taskId }), taskId);
+    const next = makeGateCheckpoint({ taskId, authority, snapshot: fresh, result });
+    await ownership.assertOwned();
+    await saveCheckpoint({ taskId, authority, checkpoint: next, previous: checkpoint });
+    checkpoint = next;
+    await onEvent({ type: "gate", taskId, gate: next.gate, ...(next.snapshotId ? { snapshotId: next.snapshotId } : {}), gateView: result.gateView });
+  }
+  return { status: "stopped", taskId };
+  } finally { await ownership.release(); }
+}

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

@@ -0,0 +1,32 @@
+import { lstatSync, realpathSync } from 'node:fs';
+import { sep } from 'node:path';
+import { isLoopProvider } from './loop-drivers.mjs';
+
+/** Container workers receive credentials as environment keys only. OpenCode
+ * authenticates from a file-based data store, so it fails closed here. */
+export const OPENCODE_CONTAINER_ERROR = 'OpenCode workers require file-based credentials and are not available in isolated containers yet';
+
+/** Build a Docker invocation. This function never accepts a shell command or credentials in arguments. */
+export function workerDockerInvocation({ workspace, image, command, args, credentialEnv, hostEnv, uid, gid, containerName, sessionHome }) {
+  const root = realpathSync(workspace);
+  if (/[\x00-\x1f,]/.test(root)) throw new Error('Invalid Docker workspace path');
+  if (typeof image !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._/:@-]{0,255}$/.test(image)) throw new Error('Explicit Docker image is required');
+  if (command === 'opencode') throw new Error(OPENCODE_CONTAINER_ERROR);
+  if (!isLoopProvider(command) || !Array.isArray(args) || args.some((arg) => typeof arg !== 'string')) throw new Error('Invalid worker provider command');
+  if (!Number.isSafeInteger(uid) || uid < 1 || !Number.isSafeInteger(gid) || gid < 1) throw new Error('Non-root worker uid and gid are required');
+  if (!hostEnv || typeof hostEnv !== 'object' || !Array.isArray(credentialEnv) || !credentialEnv.length || credentialEnv.some((key) => !/^[A-Z][A-Z0-9_]*$/.test(key) || typeof hostEnv[key] !== 'string' || !hostEnv[key])) throw new Error('Explicit worker provider credentials are required');
+  const allowed = command === 'codex' ? ['OPENAI_API_KEY'] : ['ANTHROPIC_API_KEY'];
+  if (credentialEnv.some((key) => !allowed.includes(key)) || new Set(credentialEnv).size !== credentialEnv.length) throw new Error('Unsupported worker credential environment');
+  if (containerName !== undefined && (typeof containerName !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}$/.test(containerName))) throw new Error('Invalid container name');
+  let homeMount;
+  if (sessionHome !== undefined) {
+    const info = lstatSync(sessionHome);
+    if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== uid || (info.mode & 0o077)) throw new Error('Private worker session HOME is required');
+    const home = realpathSync(sessionHome);
+    if (/[\x00-\x1f,]/.test(home) || home === root || home.startsWith(`${root}${sep}`) || root.startsWith(`${home}${sep}`)) throw new Error('Worker session HOME must be separate from workspace');
+    homeMount = `type=bind,src=${home},dst=/home/worker`;
+  }
+  const env = { PATH: hostEnv.PATH ?? '/usr/bin:/bin' };
+  for (const key of credentialEnv) env[key] = hostEnv[key];
+  return { command: 'docker', args: ['run', '--rm', '--interactive', ...(containerName ? ['--name', containerName] : []), '--read-only', '--user', `${uid}:${gid}`, '--cap-drop', 'ALL', '--security-opt', 'no-new-privileges', '--pids-limit', '256', '--memory', '2g', '--cpus', '2', '--tmpfs', '/tmp:rw,nosuid,nodev,size=256m', ...(homeMount ? ['--mount', homeMount] : ['--tmpfs', `/home/worker:rw,nosuid,nodev,size=128m,uid=${uid},gid=${gid}`]), '--env', 'HOME=/home/worker', '--workdir', '/workspace', '--mount', `type=bind,src=${root},dst=/workspace`, ...credentialEnv.flatMap((key) => ['--env', key]), '--entrypoint', command, image, ...args], env };
+}

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

@@ -0,0 +1,66 @@
+import { createHash } from 'node:crypto';
+import { copyFileSync, lstatSync, mkdirSync, readdirSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, join, sep } from 'node:path';
+
+const excluded = (path) => path.split('/').includes('.git') || path === '.agents/data' || path.startsWith('.agents/data/');
+const scopePath = (path) => typeof path === 'string' && path && !isAbsolute(path) && !path.includes('\\') && !path.split('/').some((part) => !part || part === '.' || part === '..' || part === '.git' || part === '.agents');
+const within = (path, scopes) => scopes.some((scope) => path === scope || path.startsWith(`${scope}/`));
+const digest = (path) => createHash('sha256').update(readFile(path)).digest('hex');
+import { readFileSync as readFile } from 'node:fs';
+
+// Reject links and special files rather than allowing a worker to make a host
+// copy operation follow an external path or alias a file outside its scope.
+function inventory(root, skipExcluded) {
+  const files = new Map();
+  function visit(dir, prefix = '') {
+    for (const name of readdirSync(dir)) {
+      const path = prefix ? `${prefix}/${name}` : name;
+      if (excluded(path)) {
+        if (skipExcluded) continue;
+        throw new Error(`Worker created a protected path: ${path}`);
+      }
+      const full = join(dir, name), info = lstatSync(full);
+      if (info.isSymbolicLink() || (!info.isDirectory() && !info.isFile()) || (info.isFile() && info.nlink !== 1)) throw new Error(`Unsafe worker file: ${path}`);
+      if (info.isDirectory()) visit(full, path);
+      else files.set(path, { digest: digest(full), executable: Boolean(info.mode & 0o111) });
+    }
+  }
+  visit(root);
+  return files;
+}
+
+/** Create a source-only snapshot. The caller supplies a new empty directory. */
+export function createWorkerSnapshot(source, destination, trackedPaths) {
+  const src = realpathSync(source), dst = realpathSync(destination);
+  if (src === dst || dst.startsWith(`${src}${sep}`) || src.startsWith(`${dst}${sep}`)) throw new Error('Worker snapshot must be separate from source');
+  if (readdirSync(dst).length) throw new Error('Worker snapshot destination must be empty');
+  if (!Array.isArray(trackedPaths) || !trackedPaths.length || trackedPaths.some((path) => typeof path !== 'string' || !path || isAbsolute(path) || path.includes('\\') || path.split('/').some((part) => !part || part === '.' || part === '..') || excluded(path))) throw new Error('An explicit safe tracked-file manifest is required');
+  const sourceFiles = inventory(src, true), baseline = new Map();
+  for (const path of new Set(trackedPaths)) {
+    const entry = sourceFiles.get(path);
+    if (!entry) throw new Error(`Tracked worker source is missing or unsafe: ${path}`);
+    baseline.set(path, entry);
+  }
+  for (const [path] of baseline) {
+    const target = join(dst, path);
+    mkdirSync(dirname(target), { recursive: true });
+    copyFileSync(join(src, path), target);
+  }
+  return baseline;
+}
+
+/** Validate the complete stopped-worker snapshot before host integration. */
+export function inspectWorkerSnapshot(destination, baseline, scopes) {
+  const normalizedScopes = (Array.isArray(scopes) ? scopes : []).map((scope) => (typeof scope === "string" ? scope.replace(/\/+$/, "") : scope)).filter((scope) => scope);
+  if (!(baseline instanceof Map) || !normalizedScopes.length || !normalizedScopes.every(scopePath)) throw new Error('Invalid snapshot baseline or scopes');
+  const root = realpathSync(destination), current = inventory(root, false);
+  const changed = [];
+  for (const path of new Set([...baseline.keys(), ...current.keys()])) {
+    const before = baseline.get(path), after = current.get(path);
+    if (!before || !after || before.digest !== after.digest || before.executable !== after.executable) {
+      if (!scopePath(path) || !within(path, normalizedScopes)) throw new Error(`Worker changed a path outside its scope: ${path}`);
+      changed.push(path);
+    }
+  }
+  return changed.sort();
+}

package/dist/assets/.agents/aidlc/scripts/lib/remote-state-client.mjs

@@ -0,0 +1,112 @@
+import { randomUUID } from "node:crypto";
+
+const parseMessage = (body, contentType, id) => {
+  if (contentType.includes("text/event-stream")) {
+    for (const block of body.split(/\r?\n\r?\n/)) {
+      const data = block.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trim()).join("\n");
+      if (!data || data === "[DONE]") continue;
+      try { const message = JSON.parse(data); if (message.id === id) return message; } catch { /* keep reading */ }
+    }
+    return undefined;
+  }
+  const message = JSON.parse(body);
+  return Array.isArray(message) ? message.find((entry) => entry.id === id) : message;
+};
+
+export const remoteConfig = (env = process.env) => {
+  const url = env.AIDLC_FLEET_URL;
+  const workspace = env.AIDLC_FLEET_WORKSPACE;
+  const token = env.AIDLC_FLEET_TOKEN;
+  const projectRoot = env.AIDLC_FLEET_PROJECT_ROOT;
+  const leadEpoch = Number(env.AIDLC_FLEET_LEAD_EPOCH);
+  if (!url || !/^https?:\/\//.test(url) || !workspace || !token || !projectRoot?.startsWith("/") || !Number.isSafeInteger(leadEpoch) || leadEpoch < 1) {
+    throw new Error("Remote state requires AIDLC_FLEET_URL, WORKSPACE, TOKEN, absolute PROJECT_ROOT, and positive LEAD_EPOCH");
+  }
+  return { url, workspace, token, projectRoot, leadEpoch, leadOwnerToken: env.AIDLC_FLEET_LEAD_OWNER_TOKEN, integrationBranch: env.AIDLC_FLEET_INTEGRATION_BRANCH, gitRemote: env.AIDLC_FLEET_GIT_REMOTE ?? "origin" };
+};
+
+export const featureConfig = (env = process.env) => {
+  const url = env.AIDLC_FLEET_URL;
+  const workspace = env.AIDLC_FLEET_WORKSPACE;
+  const token = env.AIDLC_FLEET_TOKEN;
+  const projectRoot = env.AIDLC_FLEET_PROJECT_ROOT;
+  if (!url || !/^https?:\/\//.test(url) || !workspace || !token || !projectRoot?.startsWith("/")) {
+    throw new Error("Remote feature commands require AIDLC_FLEET_URL, WORKSPACE, TOKEN, and absolute PROJECT_ROOT");
+  }
+  return { url, workspace, token, projectRoot };
+};
+
+export const reviewerConfig = (env = process.env) => {
+  const url = env.AIDLC_FLEET_URL;
+  const workspace = env.AIDLC_FLEET_WORKSPACE;
+  const token = env.AIDLC_FLEET_REVIEWER_TOKEN;
+  const projectRoot = env.AIDLC_FLEET_PROJECT_ROOT;
+  if (!url || !/^https?:\/\//.test(url) || !workspace || !token || !projectRoot?.startsWith("/")) {
+    throw new Error("Remote review requires AIDLC_FLEET_URL, WORKSPACE, REVIEWER_TOKEN, and absolute PROJECT_ROOT");
+  }
+  return { url, workspace, token, projectRoot, integrationBranch: env.AIDLC_FLEET_INTEGRATION_BRANCH, gitRemote: env.AIDLC_FLEET_GIT_REMOTE ?? "origin" };
+};
+
+export const callRemoteTool = async (config, name, args = {}, fetchImpl = fetch) => {
+  const id = randomUUID();
+  let response;
+  try {
+    response = await fetchImpl(config.url, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${config.token}`, Accept: "application/json, text/event-stream", "Content-Type": "application/json", "MCP-Protocol-Version": "2025-06-18" },
+      body: JSON.stringify({ jsonrpc: "2.0", id, method: "tools/call", params: { name, arguments: args } }),
+      signal: AbortSignal.timeout(20000)
+    });
+  } catch (error) { throw new Error(`Remote coordination unavailable: ${error.message}`); }
+  const body = await response.text();
+  if (!response.ok) throw new Error(`Remote coordination HTTP ${response.status}: ${body.slice(0, 300)}`);
+  let message;
+  try { message = parseMessage(body, response.headers.get("content-type") ?? "", id); }
+  catch { throw new Error("Remote coordination returned invalid JSON"); }
+  if (!message || message.id !== id) throw new Error("Remote coordination returned no matching result");
+  if (message.error) throw new Error(`Remote coordination RPC ${message.error.code}: ${message.error.message}`);
+  const tool = message.result;
+  if (!Array.isArray(tool?.content) || tool.content[0]?.type !== "text") throw new Error("Remote coordination returned no JSON text");
+  let value;
+  try { value = JSON.parse(tool.content[0].text); } catch { throw new Error("Remote coordination returned invalid tool JSON"); }
+  if (tool.isError) {
+    const error = new Error(value.message ?? value.code ?? "Remote coordination rejected operation");
+    error.code = value.code; error.current = value.current;
+    throw error;
+  }
+  return value;
+};
+
+export const createRemoteStateClient = (config, call = callRemoteTool) => ({
+  get: () => call(config, "state_get", { workspace: config.workspace }),
+  task: (taskId) => call(config, "task_get", { workspace: config.workspace, taskId, clientProjectRoot: config.projectRoot }),
+  apply: (expectedRevision, taskId, task) => call(config, "state_apply", {
+    workspace: config.workspace, expectedRevision, idempotencyKey: randomUUID(), clientProjectRoot: config.projectRoot,
+    leadEpoch: config.leadEpoch, ...(config.leadOwnerToken ? { leadOwnerToken: config.leadOwnerToken } : {}), command: { type: "upsertTask", taskId, task }
+  }),
+  snapshot: (expectedRevision, taskId, gate, reviewText, integrationCommit) => call(config, "gate_snapshot_put", {
+    workspace: config.workspace, expectedRevision, idempotencyKey: randomUUID(), taskId,
+    leadEpoch: config.leadEpoch, ...(config.leadOwnerToken ? { leadOwnerToken: config.leadOwnerToken } : {}), gate, reviewText, ...(integrationCommit ? { integrationCommit } : {})
+  }),
+  featureGet: (featureId) => call(config, "feature_get", { workspace: config.workspace, featureId }),
+  featureReady: (featureId) => call(config, "feature_ready", { workspace: config.workspace, featureId }),
+  featureApply: (expectedRevision, feature) => call(config, "feature_apply", {
+    workspace: config.workspace, expectedRevision, idempotencyKey: randomUUID(), feature
+  }),
+  fleetGet: () => call(config, "fleet_get", { workspace: config.workspace }),
+  runClaim: (expectedRevision, taskId, leaseMs) => call(config, "run_claim", {
+    workspace: config.workspace, expectedRevision, idempotencyKey: randomUUID(), taskId, leaseMs
+  }),
+  runRelease: (expectedRevision, taskId, epoch) => call(config, "run_release", {
+    workspace: config.workspace, expectedRevision, idempotencyKey: randomUUID(), taskId, epoch
+  })
+});
+
+export const createRemoteReviewerClient = (config, call = callRemoteTool) => ({
+  get: () => call(config, "state_get", { workspace: config.workspace }),
+  inbox: () => call(config, "gate_inbox_get", { workspace: config.workspace }),
+  approve: (expectedRevision, taskId, snapshotId, source, integrationCommit) => call(config, "gate_approve", {
+    workspace: config.workspace, expectedRevision, idempotencyKey: randomUUID(), taskId, snapshotId,
+    source, clientProjectRoot: config.projectRoot, ...(integrationCommit ? { integrationCommit } : {})
+  })
+});