@felixdotgo/aidlc-kit 0.0.1 → 0.1.0

package/dist/services/aidlc-coordination/compose.yaml

@@ -12,13 +12,34 @@ services:
 
   postgres:
     image: postgres:16-alpine
-    profiles: [postgres]
+    profiles: [postgres, fleet]
     environment:
       POSTGRES_DB: aidlc
       POSTGRES_USER: aidlc
-      POSTGRES_PASSWORD: change-me
+      POSTGRES_PASSWORD: ${MCP_POSTGRES_PASSWORD:?set MCP_POSTGRES_PASSWORD in .env}
     volumes:
       - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U aidlc -d aidlc"]
+      interval: 5s
+      timeout: 3s
+      retries: 20
+
+  fleet-coordination:
+    profiles: [fleet]
+    build: .
+    ports:
+      - "${MCP_FLEET_BIND_ADDRESS:-127.0.0.1}:${MCP_FLEET_PORT:-8788}:8787"
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      MCP_STATE_DATABASE: postgres
+      MCP_STATE_POSTGRES_URL: postgres://aidlc:${MCP_POSTGRES_PASSWORD:?set MCP_POSTGRES_PASSWORD in .env}@postgres:5432/aidlc
+      MCP_FLEET_ENABLED: "1"
+      MCP_FLEET_LEAD_TOKEN: ${MCP_FLEET_LEAD_TOKEN:?set MCP_FLEET_LEAD_TOKEN in .env}
+      MCP_FLEET_REVIEWER_TOKEN: ${MCP_FLEET_REVIEWER_TOKEN:?set MCP_FLEET_REVIEWER_TOKEN in .env}
+      MCP_FLEET_WORKER_TOKENS: ${MCP_FLEET_WORKER_TOKENS:?set MCP_FLEET_WORKER_TOKENS JSON in .env}
 
 volumes:
   aidlc-coordination-data:

package/dist/services/aidlc-coordination/package-lock.json

@@ -4,6 +4,7 @@
   "requires": true,
   "packages": {
     "": {
+      "bin": { "aidlc-fleet": "src/fleet-run.mjs" },
       "dependencies": {
         "@modelcontextprotocol/express": "^2.0.0",
         "@modelcontextprotocol/node": "^2.0.0",

package/dist/services/aidlc-coordination/package.json

@@ -2,11 +2,12 @@
   "name": "@felixdotgo/aidlc-coordination",
   "private": true,
   "type": "module",
+  "bin": { "aidlc-fleet": "src/fleet-run.mjs" },
   "engines": { "node": ">=20" },
   "scripts": {
     "start": "node src/server.mjs",
     "test": "node --test test/*.test.mjs",
-    "lint": "node --check src/repository.mjs && node --check src/coordination.mjs && node --check src/server.mjs"
+    "lint": "node --check src/repository.mjs && node --check src/coordination.mjs && node --check src/fleet.mjs && node --check src/fleet-client.mjs && node --check src/fleet-run.mjs && node --check src/server.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/express": "^2.0.0",

package/dist/services/aidlc-coordination/src/coordination.mjs

@@ -61,7 +61,7 @@ export class PostgresCoordinationRepository {
   async get(workspace, filters = {}) { const c = await this.pool.connect(); try { await this.#init(c); await c.query("INSERT INTO coordination_workspaces VALUES ($1,0,$2,$3) ON CONFLICT DO NOTHING", [workspace,{tasks:{},comments:{}},now()]); const row=(await c.query("SELECT * FROM coordination_workspaces WHERE workspace=$1",[workspace])).rows[0]; return { workspace, revision:Number(row.revision), board:{tasks:Object.values(row.board.tasks).filter((t)=>!filters.assignee||t.assignees.includes(filters.assignee)).slice(0,Math.min(filters.limit??50,100))}, updatedAt:row.updated_at }; } finally { c.release(); } }
   async eventsSince(workspace,cursor=0,filters={}) { const c=await this.pool.connect(); try { await this.#init(c); return (await c.query("SELECT * FROM coordination_events WHERE workspace=$1 AND id>$2 ORDER BY id LIMIT 100",[workspace,cursor])).rows.filter((e)=>!filters.actor||e.actor===filters.actor||e.type==="mention").map((e)=>({cursor:Number(e.id),taskId:e.task_id,type:e.type,revision:Number(e.revision),actor:e.actor,timestamp:e.recorded_at,digest:e.digest})); } finally { c.release(); } }
   async thread(workspace,taskId,cursor=0,limit=50) { const state=await this.get(workspace); const c=await this.pool.connect(); try { const row=(await c.query("SELECT board FROM coordination_workspaces WHERE workspace=$1",[workspace])).rows[0]; if(!row.board.tasks[taskId]) throw new Error("task not found"); return {revision:state.revision,task:row.board.tasks[taskId],comments:(row.board.comments[taskId]??[]).filter((x)=>x.id>cursor).slice(0,Math.min(limit,100))}; } finally { c.release(); } }
-  async apply(workspace,expectedRevision,idempotencyKey,actor,role,command) { if(!Number.isInteger(expectedRevision)||!text(idempotencyKey,256)||!text(actor,128)||!roles.has(role)) throw new Error("invalid coordination mutation precondition"); const c=await this.pool.connect(); try { await this.#init(c); await c.query("BEGIN"); await c.query("INSERT INTO coordination_workspaces VALUES ($1,0,$2,$3) ON CONFLICT DO NOTHING",[workspace,{tasks:{},comments:{}},now()]); const cached=(await c.query("SELECT response FROM coordination_idempotency WHERE workspace=$1 AND idempotency_key=$2",[workspace,idempotencyKey])).rows[0]; if(cached){await c.query("COMMIT");return cached.response;} const row=(await c.query("SELECT * FROM coordination_workspaces WHERE workspace=$1 FOR UPDATE",[workspace])).rows[0]; const current={workspace,revision:Number(row.revision),board:row.board}; if(current.revision!==expectedRevision) throw new CoordinationConflict(current); const bridge=new SqliteCoordinationRepository(":memory:"); try { await bridge.apply(workspace,0,"seed","system","admin",{type:"upsert_task",task:{id:"seed",title:"seed",status:"backlog"}}); const seed=await bridge.get(workspace); bridge.db.prepare("UPDATE coordination_workspaces SET revision=?,board=? WHERE workspace=?").run(current.revision,encode(current.board),workspace); const response=await bridge.apply(workspace,expectedRevision,idempotencyKey,actor,role,command); const next=(await bridge.get(workspace)).board; const event=(await bridge.eventsSince(workspace,0)).at(-1); await c.query("UPDATE coordination_workspaces SET revision=$1,board=$2,updated_at=$3 WHERE workspace=$4",[response.revision,next,response.updatedAt,workspace]); await c.query("INSERT INTO coordination_events (workspace,task_id,type,revision,actor,digest,recorded_at) VALUES ($1,$2,$3,$4,$5,$6,$7)",[workspace,event.taskId,event.type,response.revision,actor,event.digest,response.updatedAt]); await c.query("INSERT INTO coordination_idempotency VALUES ($1,$2,$3)",[workspace,idempotencyKey,response]); await c.query("COMMIT"); return response; } finally { bridge.close(); } } catch(error){try{await c.query("ROLLBACK");}catch{} throw error;} finally{c.release();} }
+  async apply(workspace,expectedRevision,idempotencyKey,actor,role,command) { if(!Number.isInteger(expectedRevision)||!text(idempotencyKey,256)||!text(actor,128)||!roles.has(role)) throw new Error("invalid coordination mutation precondition"); const c=await this.pool.connect(); try { await this.#init(c); await c.query("BEGIN"); await c.query("INSERT INTO coordination_workspaces VALUES ($1,0,$2,$3) ON CONFLICT DO NOTHING",[workspace,{tasks:{},comments:{}},now()]); const cached=(await c.query("SELECT response FROM coordination_idempotency WHERE workspace=$1 AND idempotency_key=$2",[workspace,idempotencyKey])).rows[0]; if(cached){await c.query("COMMIT");return cached.response;} const row=(await c.query("SELECT * FROM coordination_workspaces WHERE workspace=$1 FOR UPDATE",[workspace])).rows[0]; const current={workspace,revision:Number(row.revision),board:row.board}; if(current.revision!==expectedRevision) throw new CoordinationConflict(current); const bridge=new SqliteCoordinationRepository(":memory:"); try { await bridge.get(workspace); bridge.db.prepare("UPDATE coordination_workspaces SET revision=?,board=? WHERE workspace=?").run(current.revision,encode(current.board),workspace); const response=await bridge.apply(workspace,expectedRevision,idempotencyKey,actor,role,command); const next=parse(bridge.db.prepare("SELECT board FROM coordination_workspaces WHERE workspace=?").get(workspace).board); const event=(await bridge.eventsSince(workspace,0)).at(-1); await c.query("UPDATE coordination_workspaces SET revision=$1,board=$2,updated_at=$3 WHERE workspace=$4",[response.revision,next,response.updatedAt,workspace]); await c.query("INSERT INTO coordination_events (workspace,task_id,type,revision,actor,digest,recorded_at) VALUES ($1,$2,$3,$4,$5,$6,$7)",[workspace,event.taskId,event.type,response.revision,actor,event.digest,response.updatedAt]); await c.query("INSERT INTO coordination_idempotency VALUES ($1,$2,$3)",[workspace,idempotencyKey,response]); await c.query("COMMIT"); return response; } finally { bridge.close(); } } catch(error){try{await c.query("ROLLBACK");}catch{} throw error;} finally{c.release();} }
   async close(){await this.pool.end();}
 }
 

package/dist/services/aidlc-coordination/src/fleet-client.mjs

@@ -0,0 +1,36 @@
+import { randomUUID } from "node:crypto";
+
+const responseMessage = (body, contentType, id) => {
+  if (contentType.includes("text/event-stream")) {
+    const events = body.split(/\r?\n\r?\n/).flatMap((block) => {
+      const data = block.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice(5).trim()).join("\n");
+      if (!data || data === "[DONE]") return [];
+      try { return [JSON.parse(data)]; } catch { return []; }
+    });
+    return events.find((event) => event.id === id && (event.result || event.error));
+  }
+  const parsed = JSON.parse(body);
+  return Array.isArray(parsed) ? parsed.find((item) => item.id === id) : parsed;
+};
+
+export const callTool = async ({ url, token, name, args = {}, timeoutMs = 20000, fetchImpl = fetch }) => {
+  if (typeof url !== "string" || !/^https?:\/\//.test(url) || typeof token !== "string" || !token || typeof name !== "string" || !name) throw new Error("MCP URL, token, and tool name are required");
+  const id = randomUUID();
+  const response = await fetchImpl(url, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${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(timeoutMs)
+  });
+  const body = await response.text();
+  if (!response.ok) throw new Error(`MCP HTTP ${response.status}: ${body.slice(0, 500)}`);
+  const message = responseMessage(body, response.headers.get("content-type") ?? "", id);
+  if (!message) throw new Error("MCP response did not contain a matching result");
+  if (message.error) throw new Error(`MCP ${message.error.code}: ${message.error.message}`);
+  const tool = message.result;
+  if (!Array.isArray(tool?.content) || tool.content[0]?.type !== "text") throw new Error("MCP tool returned no JSON text");
+  let value;
+  try { value = JSON.parse(tool.content[0].text); } catch { throw new Error("MCP tool returned invalid JSON text"); }
+  if (tool.isError) { const error = new Error(value.message ?? value.code ?? "MCP tool failed"); error.code = value.code; error.current = value.current; throw error; }
+  return value;
+};

package/dist/services/aidlc-coordination/src/fleet-run.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { callTool } from "./fleet-client.mjs";
+
+const source = new URL("../../../assets/aidlc/scripts/lib/loop-fleet-cli.mjs", import.meta.url);
+const packaged = new URL("../../../assets/.agents/aidlc/scripts/lib/loop-fleet-cli.mjs", import.meta.url);
+const installed = new URL("../../aidlc/scripts/lib/loop-fleet-cli.mjs", import.meta.url);
+const entry = [installed, source, packaged].find((candidate) => existsSync(fileURLToPath(candidate)));
+
+try {
+  if (!entry) throw new Error("Fleet runner assets are missing from this installation");
+  const { runFleetCli } = await import(entry.href);
+  await runFleetCli(process.argv.slice(2), { callTool });
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/dist/services/aidlc-coordination/src/fleet.mjs

@@ -0,0 +1,233 @@
+import Database from "better-sqlite3";
+import pg from "pg";
+import { createHash } from "node:crypto";
+import { nextAction } from "./lifecycle-core.mjs";
+
+const now = () => Date.now();
+const iso = (time) => new Date(time).toISOString();
+const id = (value) => typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value);
+const branchName = (value) => typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._/-]{0,127}$/.test(value) && !value.includes("..") && !value.endsWith("/");
+const copy = (value) => structuredClone(value);
+const initial = () => ({ schemaVersion: 1, features: {}, leads: {}, supervisors: {}, jobs: {} });
+const validLease = (value) => Number.isInteger(value) && value >= 60000 && value <= 3600000;
+
+export class FleetConflict extends Error {
+  constructor(message, current) { super(message); this.name = "FleetConflict"; this.current = current; }
+}
+
+export const validateFeature = (feature) => {
+  if (!feature || !id(feature.id) || !Array.isArray(feature.tasks) || !feature.tasks.length || feature.tasks.length > 100 || !branchName(feature.integrationBranch)) throw new Error("invalid feature manifest");
+  const tasks = new Map();
+  for (const task of feature.tasks) {
+    if (!id(task?.id) || tasks.has(task.id) || !Array.isArray(task.dependsOn) || task.dependsOn.some((dependency) => !id(dependency))) throw new Error("invalid or duplicate feature task");
+    tasks.set(task.id, task);
+  }
+  const visiting = new Set(), visited = new Set();
+  const visit = (taskId) => {
+    if (!tasks.has(taskId)) throw new Error(`unknown feature dependency: ${taskId}`);
+    if (visiting.has(taskId)) throw new Error("feature dependency cycle");
+    if (visited.has(taskId)) return;
+    visiting.add(taskId);
+    for (const dependency of tasks.get(taskId).dependsOn) visit(dependency);
+    visiting.delete(taskId); visited.add(taskId);
+  };
+  for (const taskId of tasks.keys()) visit(taskId);
+  return { schemaVersion: 1, id: feature.id, integrationBranch: feature.integrationBranch, tasks: feature.tasks.map((task) => ({ id: task.id, dependsOn: [...new Set(task.dependsOn)] })) };
+};
+
+export const featureReady = (feature, completedIds = []) => {
+  const completed = new Set(completedIds);
+  return feature.tasks.map((task) => ({ taskId: task.id, ready: !completed.has(task.id) && task.dependsOn.every((dependency) => completed.has(dependency)), blockers: task.dependsOn.filter((dependency) => !completed.has(dependency)) }));
+};
+
+export const validateCanonicalFeature = (feature, state) => {
+  const manifest=validateFeature(feature);
+  for(const member of manifest.tasks) {
+    const task=state.tasks?.[member.id];
+    if(!task) throw new Error(`feature task does not exist in canonical state: ${member.id}`);
+    if(task.featureId && task.featureId!==manifest.id) throw new Error(`task belongs to another feature: ${member.id}`);
+  }
+  return manifest;
+};
+
+const tokenHash = (token) => createHash("sha256").update(token).digest("hex");
+const requireSupervisor = (state, taskId, actor, epoch, time, ownerToken) => {
+  const supervisor = state.supervisors?.[taskId];
+  if (!supervisor || supervisor.actor !== actor || supervisor.epoch !== epoch || Date.parse(supervisor.expiresAt) <= time || typeof ownerToken !== "string" || tokenHash(ownerToken) !== supervisor.ownerTokenHash) throw new FleetConflict("stale or expired supervisor claim");
+  return supervisor;
+};
+const verifyBoundSupervisor = (state, lead, time) => {
+  if (state.supervisors?.[lead.taskId]) {
+    const supervisor = state.supervisors[lead.taskId];
+    if (!lead.supervisorEpoch || supervisor.epoch !== lead.supervisorEpoch || supervisor.actor !== lead.actor || supervisor.ownerTokenHash !== lead.supervisorOwnerTokenHash || Date.parse(supervisor.expiresAt) <= time) throw new FleetConflict("stale or expired bound supervisor claim");
+  }
+};
+const requireLead = (state, taskId, actor, epoch, time, ownerToken) => {
+  const lead = state.leads[taskId];
+  if (!lead || lead.actor !== actor || lead.epoch !== epoch || Date.parse(lead.expiresAt) <= time || (lead.ownerTokenHash && (typeof ownerToken !== "string" || tokenHash(ownerToken) !== lead.ownerTokenHash))) throw new FleetConflict("stale or expired lead claim");
+  verifyBoundSupervisor(state, lead, time);
+  return lead;
+};
+const requireJob = (state, jobId, actor, epoch, time) => {
+  const job = state.jobs[jobId];
+  if (!job || job.workerId !== actor || job.epoch !== epoch || job.state !== "leased" || Date.parse(job.expiresAt) <= time) throw new FleetConflict("stale or expired job claim");
+  const lead = state.leads[job.taskId];
+  if (state.supervisors?.[job.taskId] && (!lead || lead.epoch !== job.leadEpoch || Date.parse(lead.expiresAt) <= time)) throw new FleetConflict("job lead lease is stale");
+  if (lead) verifyBoundSupervisor(state, lead, time);
+  return job;
+};
+const validChangedPaths = (job, paths) => Array.isArray(paths) && paths.length <= 100 && paths.every((path) => typeof path === "string" && Boolean(path) && !path.startsWith("/") && !path.split("/").includes("..") && job.ownedPaths.some((scope) => path === scope || path.startsWith(`${scope.replace(/\/$/, "")}/`)));
+
+export const applyFleetCommand = (before, command, actor, role, time = now()) => {
+  const state = copy(before);
+  const c = command ?? {};
+  if (c.type === "feature_apply") {
+    if (role !== "lead") throw new Error("lead credential required");
+    const feature = validateFeature(c.feature);
+    for (const existing of Object.values(state.features)) for (const member of existing.tasks) if (existing.id !== feature.id && feature.tasks.some((task) => task.id === member.id)) throw new Error(`task already belongs to feature ${existing.id}`);
+    const old = state.features[feature.id];
+    if (old && c.feature.revision !== old.revision) throw new FleetConflict("feature revision conflict");
+    state.features[feature.id] = { ...feature, revision: (old?.revision ?? 0) + 1, updatedAt: iso(time) };
+  } else if (c.type === "supervisor_claim") {
+    if (role !== "lead" || !id(c.taskId) || !validLease(c.leaseMs) || typeof c.ownerToken !== "string" || c.ownerToken.length < 32 || c.ownerToken.length > 256) throw new Error("invalid supervisor claim");
+    state.supervisors ??= {};
+    const old = state.supervisors[c.taskId], lead = state.leads[c.taskId];
+    if ((old && Date.parse(old.expiresAt) > time) || (lead && Date.parse(lead.expiresAt) > time)) throw new FleetConflict("supervisor or prior lead claim is held");
+    state.supervisors[c.taskId] = { taskId: c.taskId, actor, epoch: (old?.epoch ?? 0) + 1, expiresAt: iso(time + c.leaseMs), ownerTokenHash: tokenHash(c.ownerToken) };
+  } else if (c.type === "supervisor_heartbeat" || c.type === "supervisor_release") {
+    if (role !== "lead" || !id(c.taskId) || !Number.isInteger(c.epoch)) throw new Error("invalid supervisor mutation");
+    const supervisor = requireSupervisor(state, c.taskId, actor, c.epoch, time, c.ownerToken);
+    if (c.type === "supervisor_heartbeat") { if (!validLease(c.leaseMs)) throw new Error("invalid lease duration"); supervisor.expiresAt = iso(time + c.leaseMs); }
+    else supervisor.expiresAt = iso(time);
+  } else if (c.type === "run_claim") {
+    if (role !== "lead" || !id(c.taskId) || !validLease(c.leaseMs)) throw new Error("invalid lead claim");
+    if (c.ownerToken !== undefined && (typeof c.ownerToken !== "string" || c.ownerToken.length < 32 || c.ownerToken.length > 256)) throw new Error("invalid owner token");
+    const supervisor = state.supervisors?.[c.taskId];
+    if (supervisor) {
+      requireSupervisor(state, c.taskId, actor, c.supervisorEpoch, time, c.supervisorOwnerToken);
+      if (typeof c.ownerToken !== "string" || c.ownerToken.length < 32) throw new Error("supervised run requires a secret owner token");
+    }
+    const old = state.leads[c.taskId];
+    if (old && Date.parse(old.expiresAt) > time) throw new FleetConflict("lead claim is held");
+    state.leads[c.taskId] = { taskId: c.taskId, actor, epoch: (old?.epoch ?? 0) + 1, expiresAt: iso(time + c.leaseMs), ...(c.ownerToken ? { ownerTokenHash: tokenHash(c.ownerToken) } : {}), ...(supervisor ? { supervisorEpoch: supervisor.epoch, supervisorOwnerTokenHash: supervisor.ownerTokenHash, ...(c.checkpointSnapshotId ? { checkpointSnapshotId: c.checkpointSnapshotId } : {}) } : {}) };
+    for (const job of Object.values(state.jobs)) if (job.taskId === c.taskId && job.state !== "integrated" && job.leadEpoch < state.leads[c.taskId].epoch) { job.state = "uncertain"; job.uncertainAt = iso(time); job.expiresAt = null; }
+  } else if (c.type === "run_heartbeat" || c.type === "run_release") {
+    if (role !== "lead" || !id(c.taskId) || !Number.isInteger(c.epoch)) throw new Error("invalid lead mutation");
+    const lead = requireLead(state, c.taskId, actor, c.epoch, time, c.ownerToken);
+    if (c.type === "run_heartbeat") { if (!validLease(c.leaseMs)) throw new Error("invalid lease duration"); lead.expiresAt = iso(time + c.leaseMs); }
+    else lead.expiresAt = iso(time);
+  } else if (c.type === "job_schedule") {
+    if (role !== "lead" || !id(c.jobId) || !id(c.taskId) || !id(c.itemId) || !id(c.workerId) || !["codex", "claude", "opencode"].includes(c.agent) || !Number.isInteger(c.attempt) || c.attempt < 1 || !Array.isArray(c.ownedPaths) || c.ownedPaths.length > 100 || c.ownedPaths.some((path) => typeof path !== "string" || !path || path.startsWith("/") || path.split("/").includes("..")) || !/^[a-f0-9]{40}$/.test(c.baseCommit) || !branchName(c.branch)) throw new Error("invalid job schedule");
+    requireLead(state, c.taskId, actor, c.leadEpoch, time, c.ownerToken);
+    if (state.jobs[c.jobId]) throw new FleetConflict("job ID already exists");
+    const priorJobs=Object.values(state.jobs).filter((job)=>job.taskId===c.taskId&&job.itemId===c.itemId);
+    if(priorJobs.some((job)=>job.state==="integrated")) throw new FleetConflict("item already integrated");
+    if(priorJobs.some((job)=>!["integrated","uncertain"].includes(job.state))) throw new FleetConflict("item already has an active job");
+    if(priorJobs.length && c.attempt<=Math.max(...priorJobs.map((job)=>job.attempt))) throw new FleetConflict("job attempt must increase after reconciliation");
+    state.jobs[c.jobId] = { schemaVersion: 1, id: c.jobId, taskId: c.taskId, itemId: c.itemId, workerId: c.workerId, agent: c.agent, attempt: c.attempt, leadEpoch: c.leadEpoch, epoch: 0, ownedPaths: c.ownedPaths, baseCommit: c.baseCommit, branch: c.branch, state: "ready", expiresAt: null, uncertainAt: null, sessionId: null, checkpoint: null, report: null };
+  } else if (c.type === "job_claim") {
+    if (role !== "worker" || !id(c.jobId) || !validLease(c.leaseMs)) throw new Error("invalid job claim");
+    const job = state.jobs[c.jobId];
+    if (!job || job.workerId !== actor) throw new Error("job is not assigned to worker");
+    { const lead = state.leads[job.taskId]; if (!lead || lead.epoch !== job.leadEpoch || Date.parse(lead.expiresAt) <= time) throw new FleetConflict("stale or expired lead claim"); verifyBoundSupervisor(state, lead, time); }
+    if (job.state === "leased") throw new FleetConflict(Date.parse(job.expiresAt) > time ? "job lease is held" : "expired job lease requires lead reconciliation");
+    if (job.state !== "ready") throw new FleetConflict("job requires lead reconciliation");
+    job.epoch += 1; job.state = "leased"; job.expiresAt = iso(time + c.leaseMs); job.sessionId = null; job.checkpoint = null;
+  } else if (c.type === "job_heartbeat" || c.type === "job_checkpoint" || c.type === "job_report" || c.type === "job_abandon") {
+    if (role !== "worker" || !id(c.jobId) || !Number.isInteger(c.epoch)) throw new Error("invalid job mutation");
+    const job = requireJob(state, c.jobId, actor, c.epoch, time);
+    { const lead = state.leads[job.taskId]; if (!lead || lead.epoch !== job.leadEpoch || Date.parse(lead.expiresAt) <= time) throw new FleetConflict("stale or expired lead claim"); }
+    if (c.type === "job_heartbeat") { if (!validLease(c.leaseMs)) throw new Error("invalid lease duration"); job.expiresAt = iso(time + c.leaseMs); }
+    else if (c.type === "job_checkpoint") { if (typeof c.sessionId !== "string" || !c.sessionId || c.sessionId.length > 256 || typeof c.checkpoint !== "string" || c.checkpoint.length > 4000) throw new Error("invalid job checkpoint"); if (job.sessionId && job.sessionId !== c.sessionId) throw new FleetConflict("job session cannot change within a leased attempt"); job.sessionId = c.sessionId; job.checkpoint = c.checkpoint; }
+    else if (c.type === "job_abandon") { if (typeof c.reason !== "string" || !c.reason.trim() || c.reason.length > 2000) throw new Error("invalid abandonment reason"); job.state = "uncertain"; job.uncertainAt = iso(time); job.report = { reason: c.reason, reportedAt: iso(time) }; job.expiresAt = iso(time); }
+    else { if (!/^[a-f0-9]{40}$/.test(c.commitSha) || !validChangedPaths(job,c.changedPaths)) throw new Error("invalid or out-of-scope job report"); job.report = { commitSha: c.commitSha, changedPaths: c.changedPaths, summary: typeof c.summary === "string" ? c.summary.slice(0, 2000) : "", reportedAt: iso(time) }; job.state = "reported"; job.expiresAt = iso(time); }
+  } else if (c.type === "job_recover") {
+    if(role!=="lead" || !id(c.jobId)) throw new Error("invalid job recovery");
+    const job=state.jobs[c.jobId]; if(!job) throw new Error("unknown job");
+    requireLead(state,job.taskId,actor,c.leadEpoch,time,c.ownerToken);
+    if(!["uncertain","ready"].includes(job.state)) throw new FleetConflict("job is not awaiting recovery");
+    if(!/^[a-f0-9]{40}$/.test(c.commitSha) || !validChangedPaths(job,c.changedPaths)) throw new Error("invalid or out-of-scope recovered commit");
+    job.leadEpoch=c.leadEpoch; job.report={commitSha:c.commitSha,changedPaths:c.changedPaths,summary:typeof c.summary==="string"?c.summary.slice(0,2000):"",recoveredAt:iso(time)};
+    job.state="reported"; job.expiresAt=null; job.uncertainAt=null;
+  } else if (c.type === "job_reconcile") {
+    if (role !== "lead" || !id(c.jobId) || !["ready", "uncertain", "integrated"].includes(c.state)) throw new Error("invalid job reconciliation");
+    const job = state.jobs[c.jobId]; if (!job) throw new Error("unknown job"); requireLead(state, job.taskId, actor, c.leadEpoch, time, c.ownerToken); if(c.state==="integrated" && (job.state!=="reported" || !job.report?.commitSha || job.leadEpoch!==c.leadEpoch)) throw new Error("only a current-epoch reported commit may be integrated"); if(c.state==="ready") { if(job.state!=="uncertain") throw new Error("only an uncertain job may be retried"); job.leadEpoch=c.leadEpoch; job.sessionId=null; job.checkpoint=null; job.report=null; job.uncertainAt=null; } if(c.state==="uncertain") job.uncertainAt=iso(time); if(c.state==="integrated") job.uncertainAt=null; job.state = c.state; job.expiresAt = null;
+  } else throw new Error("unsupported fleet command");
+  return state;
+};
+
+const validateMutation = (workspace, revision, key, actor, role) => {
+  if (!id(workspace) || !Number.isInteger(revision) || revision < 0 || !id(key) || !id(actor) || !["lead", "worker"].includes(role)) throw new Error("invalid fleet mutation precondition");
+};
+const publicFleet = (input) => {
+  const fleet = copy(input);
+  for (const entry of Object.values(fleet.leads ?? {})) { delete entry.ownerTokenHash; delete entry.supervisorOwnerTokenHash; }
+  for (const entry of Object.values(fleet.supervisors ?? {})) delete entry.ownerTokenHash;
+  return fleet;
+};
+const payloadDigest = (role, actor, command) => createHash("sha256").update(JSON.stringify([role, actor, command])).digest("hex");
+const verifyReplayFence = (state, command, actor, role, time = now()) => {
+  const type = command.type;
+  if (type.startsWith("supervisor_")) return requireSupervisor(state, command.taskId, actor, type === "supervisor_claim" ? state.supervisors?.[command.taskId]?.epoch : command.epoch, time, command.ownerToken);
+  if (type === "run_claim") return requireLead(state, command.taskId, actor, state.leads?.[command.taskId]?.epoch, time, command.ownerToken);
+  if (type === "run_heartbeat" || type === "run_release") return requireLead(state, command.taskId, actor, command.epoch, time, command.ownerToken);
+  if (["job_schedule", "job_reconcile", "job_recover"].includes(type)) return requireLead(state, command.taskId ?? state.jobs?.[command.jobId]?.taskId, actor, command.leadEpoch, time, command.ownerToken);
+  if (["job_claim", "job_heartbeat", "job_checkpoint", "job_report", "job_abandon"].includes(type)) return requireJob(state, command.jobId, actor, type === "job_claim" ? state.jobs?.[command.jobId]?.epoch : command.epoch, time);
+};
+const verifyResume = (command, row, checkpoint, review) => {
+  if (!row || !Number.isSafeInteger(command.expectedStateRevision) || command.expectedStateRevision !== Number(row.revision)) throw new FleetConflict("canonical revision changed before run claim");
+  const state = typeof row.state === "string" ? JSON.parse(row.state) : row.state;
+  const task = state?.tasks?.[command.taskId];
+  if (!task || typeof command.expectedTaskDigest !== "string" || createHash("sha256").update(JSON.stringify(task)).digest("hex") !== command.expectedTaskDigest || task.status !== "active" || task.handoff || nextAction(task).classification !== "run_phase") throw new FleetConflict("canonical task changed or is not runnable");
+  if (checkpoint?.status === "pending") throw new FleetConflict("human approval is still pending");
+  if (checkpoint?.status === "approved") {
+    const target = { G0_confirm: "plan", G1_review: "build", G2_codereview: "wrap" }[checkpoint.gate];
+    const originalPhase = { G0_confirm: "clarify", G1_review: "plan", G2_codereview: "build" }[checkpoint.gate];
+    if (checkpoint.phase !== originalPhase || command.checkpointSnapshotId !== checkpoint.snapshot_id || command.checkpointApprovalRevision !== Number(checkpoint.approval_revision) || Number(row.revision) !== Number(checkpoint.approval_revision) || !review || review.task_id !== command.taskId || review.gate !== checkpoint.gate || review.task_digest !== checkpoint.task_digest || Number(review.state_revision) !== Number(checkpoint.state_revision) || review.integration_commit !== checkpoint.integration_commit || task.phase !== target || !task.evidence?.some((e) => e.kind === "approval" && e.gate === checkpoint.gate && e.result === "pass" && typeof e.source === "string" && e.source.trim())) throw new FleetConflict("approved gate checkpoint is stale or mismatched");
+  } else if (command.checkpointSnapshotId !== undefined || command.checkpointApprovalRevision !== undefined) throw new FleetConflict("unexpected checkpoint precondition");
+};
+const gitIntent = (input) => {
+  const {workspace,taskId,epoch,ownerToken,operationId,ref,oldOid,newOid} = input ?? {};
+  if (!id(workspace) || !id(taskId) || !Number.isInteger(epoch) || typeof ownerToken !== "string" || !id(operationId) || typeof ref !== "string" || !/^refs\/heads\/[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$/.test(ref) || ref.includes("..") || ref.endsWith("/") || !/^[a-f0-9]{40}$/.test(oldOid ?? "") || !/^[a-f0-9]{40}$/.test(newOid ?? "") || oldOid === newOid) throw new Error("invalid Git operation intent");
+  return {workspace,taskId,epoch,ownerToken,operationId,ref,oldOid,newOid};
+};
+const gitFence = (fleet, taskId, epoch, ownerToken, marginMs = 1000, time = now()) => {
+  const lead=fleet?.leads?.[taskId]; if (!fleet?.supervisors?.[taskId] || !lead) throw new FleetConflict("Git gateway requires supervisor-bound run");
+  requireLead(fleet,taskId,lead.actor,epoch,time+marginMs,ownerToken);
+};
+const gitRow = (row) => row && ({ workspace:row.workspace, operationId:row.operation_id, taskId:row.task_id, epoch:Number(row.epoch), ref:row.ref, oldOid:row.old_oid, newOid:row.new_oid, status:row.status });
+const view = (row) => ({ workspace: row.workspace, revision: Number(row.revision), fleet: typeof row.fleet === "string" ? JSON.parse(row.fleet) : row.fleet, updatedAt: row.updated_at });
+
+export class SqliteFleetRepository {
+  constructor(filename = process.env.MCP_STATE_SQLITE_PATH ?? "./data/mcp-state.db") { this.db = new Database(filename); this.db.pragma("journal_mode = WAL"); this.db.pragma("busy_timeout = 5000"); this.db.exec("CREATE TABLE IF NOT EXISTS fleet_workspaces (workspace TEXT PRIMARY KEY, revision INTEGER NOT NULL, fleet TEXT NOT NULL, updated_at TEXT NOT NULL); CREATE TABLE IF NOT EXISTS fleet_idempotency (workspace TEXT NOT NULL, idempotency_key TEXT NOT NULL, response TEXT NOT NULL, PRIMARY KEY(workspace,idempotency_key)); CREATE TABLE IF NOT EXISTS fleet_git_operations (workspace TEXT NOT NULL, operation_id TEXT NOT NULL, task_id TEXT NOT NULL, epoch INTEGER NOT NULL, ref TEXT NOT NULL, old_oid TEXT NOT NULL, new_oid TEXT NOT NULL, status TEXT NOT NULL, PRIMARY KEY(workspace,operation_id))"); }
+  #ensure(workspace) { this.db.prepare("INSERT OR IGNORE INTO fleet_workspaces VALUES (?,0,?,?)").run(workspace, JSON.stringify(initial()), iso(now())); }
+  async get(workspace) { if (!id(workspace)) throw new Error("invalid workspace"); this.#ensure(workspace); const current=view(this.db.prepare("SELECT * FROM fleet_workspaces WHERE workspace=?").get(workspace)); return {...current,fleet:publicFleet(current.fleet)}; }
+  async apply(workspace, expectedRevision, idempotencyKey, actor, role, command) { validateMutation(workspace, expectedRevision, idempotencyKey, actor, role); const scopedKey=`${role}:${actor}:${idempotencyKey}`; this.db.exec("BEGIN IMMEDIATE"); try { this.#ensure(workspace); const current=view(this.db.prepare("SELECT * FROM fleet_workspaces WHERE workspace=?").get(workspace)); const cached=this.db.prepare("SELECT response FROM fleet_idempotency WHERE workspace=? AND idempotency_key=?").get(workspace,scopedKey); if(cached){const entry=JSON.parse(cached.response); if(entry.payloadDigest!==payloadDigest(role,actor,command)) throw new FleetConflict("idempotency payload mismatch"); verifyReplayFence(current.fleet,command,actor,role); this.db.exec("COMMIT");return entry.response;} if(current.revision!==expectedRevision) throw new FleetConflict("fleet revision conflict",{...current,fleet:publicFleet(current.fleet)}); if(command.type==="run_claim" && current.fleet.supervisors?.[command.taskId]) { if(this.db.prepare("SELECT 1 FROM fleet_git_operations WHERE workspace=? AND task_id=? AND status='pending' LIMIT 1").get(workspace,command.taskId)) throw new FleetConflict("pending Git operation requires reconciliation"); const row=this.db.prepare("SELECT revision,state FROM state_workspaces WHERE workspace=?").get(workspace); const checkpoint=this.db.prepare("SELECT * FROM state_gate_checkpoints WHERE workspace=? AND task_id=?").get(workspace,command.taskId); const review=checkpoint ? this.db.prepare("SELECT * FROM state_gate_snapshots WHERE workspace=? AND id=?").get(workspace,checkpoint.snapshot_id) : null; verifyResume(command,row,checkpoint,review); } if(command.type==="job_schedule" && this.db.prepare("SELECT 1 FROM fleet_git_operations WHERE workspace=? AND task_id=? AND status='pending' LIMIT 1").get(workspace,command.taskId)) throw new FleetConflict("pending Git operation requires reconciliation"); const fleet=applyFleetCommand(current.fleet,command,actor,role); if(command.type==="job_schedule"){const checkpointId=fleet.leads?.[command.taskId]?.checkpointSnapshotId;if(checkpointId){const changed=this.db.prepare("UPDATE state_gate_checkpoints SET status='consumed' WHERE workspace=? AND task_id=? AND snapshot_id=? AND status='approved'").run(workspace,command.taskId,checkpointId);if(!changed.changes){const cp=this.db.prepare("SELECT snapshot_id,status FROM state_gate_checkpoints WHERE workspace=? AND task_id=?").get(workspace,command.taskId);if(!cp || cp.snapshot_id!==checkpointId || cp.status!=="consumed") throw new Error("checkpoint changed before fenced dispatch");}}} const response={workspace,revision:expectedRevision+1,fleet:publicFleet(fleet),updatedAt:iso(now())}; this.db.prepare("UPDATE fleet_workspaces SET revision=?,fleet=?,updated_at=? WHERE workspace=?").run(response.revision,JSON.stringify(fleet),response.updatedAt,workspace); this.db.prepare("INSERT INTO fleet_idempotency VALUES (?,?,?)").run(workspace,scopedKey,JSON.stringify({payloadDigest:payloadDigest(role,actor,command),response})); this.db.exec("COMMIT"); return response; } catch(error){try{this.db.exec("ROLLBACK");}catch{} throw error;} }
+  async prepareGitOperation(input) {
+    const intent=gitIntent(input); this.db.exec("BEGIN IMMEDIATE");
+    try { const row=this.db.prepare("SELECT * FROM fleet_workspaces WHERE workspace=?").get(intent.workspace); gitFence(row && view(row).fleet,intent.taskId,intent.epoch,intent.ownerToken); const old=gitRow(this.db.prepare("SELECT * FROM fleet_git_operations WHERE workspace=? AND operation_id=?").get(intent.workspace,intent.operationId)); if(old){if(old.taskId!==intent.taskId || old.epoch!==intent.epoch || old.ref!==intent.ref || old.oldOid!==intent.oldOid || old.newOid!==intent.newOid) throw new FleetConflict("Git operation intent mismatch"); this.db.exec("COMMIT");return {status:old.status};} this.db.prepare("INSERT INTO fleet_git_operations VALUES (?,?,?,?,?,?,?,?)").run(intent.workspace,intent.operationId,intent.taskId,intent.epoch,intent.ref,intent.oldOid,intent.newOid,"pending");this.db.exec("COMMIT");return {status:"pending"}; } catch(error){try{this.db.exec("ROLLBACK");}catch{}throw error;}
+  }
+  async getGitOperation({workspace,operationId}) { if(!id(workspace)||!id(operationId)) throw new Error("invalid Git operation lookup"); return gitRow(this.db.prepare("SELECT * FROM fleet_git_operations WHERE workspace=? AND operation_id=?").get(workspace,operationId)) ?? null; }
+  async withGitFence({workspace,taskId,epoch,ownerToken,operationId},callback) {
+    if(!id(workspace)||!id(taskId)||!Number.isInteger(epoch)||typeof ownerToken!=="string"||!id(operationId)||typeof callback!=="function") throw new Error("invalid Git fence request");
+    this.db.exec("BEGIN IMMEDIATE");try { const row=this.db.prepare("SELECT * FROM fleet_workspaces WHERE workspace=?").get(workspace), fleet=row && view(row).fleet; const record=gitRow(this.db.prepare("SELECT * FROM fleet_git_operations WHERE workspace=? AND operation_id=?").get(workspace,operationId)); const assertValid=()=>gitFence(fleet,taskId,epoch,ownerToken);assertValid();if(!record || record.taskId!==taskId || record.epoch!==epoch || record.status!=="pending") throw new FleetConflict("Git operation is absent, stale or already completed");let complete=false;const result=await callback({record,assertValid,complete:async()=>{assertValid();complete=true;}});assertValid();if(!complete) throw new Error("Git callback did not complete operation");this.db.prepare("UPDATE fleet_git_operations SET status='complete' WHERE workspace=? AND operation_id=? AND status='pending'").run(workspace,operationId);this.db.exec("COMMIT");return result;}catch(error){try{this.db.exec("ROLLBACK");}catch{}throw error;}
+  }
+  close() { this.db.close(); }
+}
+
+export class PostgresFleetRepository {
+  constructor(connectionString = process.env.MCP_STATE_POSTGRES_URL) { if (!connectionString) throw new Error("MCP_STATE_POSTGRES_URL is required"); this.pool = new pg.Pool({ connectionString }); }
+  async #init(c) { await c.query("CREATE TABLE IF NOT EXISTS fleet_workspaces (workspace TEXT PRIMARY KEY, revision BIGINT NOT NULL, fleet JSONB NOT NULL, updated_at TEXT NOT NULL)"); await c.query("CREATE TABLE IF NOT EXISTS fleet_idempotency (workspace TEXT NOT NULL, idempotency_key TEXT NOT NULL, response JSONB NOT NULL, PRIMARY KEY(workspace,idempotency_key))"); await c.query("CREATE TABLE IF NOT EXISTS fleet_git_operations (workspace TEXT NOT NULL, operation_id TEXT NOT NULL, task_id TEXT NOT NULL, epoch BIGINT NOT NULL, ref TEXT NOT NULL, old_oid TEXT NOT NULL, new_oid TEXT NOT NULL, status TEXT NOT NULL, PRIMARY KEY(workspace,operation_id))"); }
+  async get(workspace) { if (!id(workspace)) throw new Error("invalid workspace"); const c=await this.pool.connect(); try { await this.#init(c); await c.query("INSERT INTO fleet_workspaces VALUES ($1,0,$2,$3) ON CONFLICT DO NOTHING",[workspace,initial(),iso(now())]); const current=view((await c.query("SELECT * FROM fleet_workspaces WHERE workspace=$1",[workspace])).rows[0]); return {...current,fleet:publicFleet(current.fleet)}; } finally { c.release(); } }
+  async apply(workspace,expectedRevision,idempotencyKey,actor,role,command) { validateMutation(workspace,expectedRevision,idempotencyKey,actor,role); const scopedKey=`${role}:${actor}:${idempotencyKey}`; const c=await this.pool.connect(); try { await this.#init(c); await c.query("BEGIN"); await c.query("INSERT INTO fleet_workspaces VALUES ($1,0,$2,$3) ON CONFLICT DO NOTHING",[workspace,initial(),iso(now())]); const row=(await c.query("SELECT * FROM fleet_workspaces WHERE workspace=$1 FOR UPDATE",[workspace])).rows[0]; const current=view(row); const dbTime=Number((await c.query("SELECT extract(epoch from clock_timestamp()) * 1000 AS ms")).rows[0].ms); const cached=(await c.query("SELECT response FROM fleet_idempotency WHERE workspace=$1 AND idempotency_key=$2",[workspace,scopedKey])).rows[0]; if(cached){const entry=cached.response; if(entry.payloadDigest!==payloadDigest(role,actor,command)) throw new FleetConflict("idempotency payload mismatch"); verifyReplayFence(current.fleet,command,actor,role,dbTime); await c.query("COMMIT");return entry.response;} if(current.revision!==expectedRevision) throw new FleetConflict("fleet revision conflict",{...current,fleet:publicFleet(current.fleet)}); if(command.type==="run_claim" && current.fleet.supervisors?.[command.taskId]) { if((await c.query("SELECT 1 FROM fleet_git_operations WHERE workspace=$1 AND task_id=$2 AND status='pending' LIMIT 1",[workspace,command.taskId])).rowCount) throw new FleetConflict("pending Git operation requires reconciliation"); const stateRow=(await c.query("SELECT revision,state FROM state_workspaces WHERE workspace=$1 FOR UPDATE",[workspace])).rows[0]; const checkpoint=(await c.query("SELECT * FROM state_gate_checkpoints WHERE workspace=$1 AND task_id=$2 FOR UPDATE",[workspace,command.taskId])).rows[0]; const review=checkpoint ? (await c.query("SELECT * FROM state_gate_snapshots WHERE workspace=$1 AND id=$2",[workspace,checkpoint.snapshot_id])).rows[0] : null; verifyResume(command,stateRow,checkpoint,review); } if(command.type==="job_schedule" && (await c.query("SELECT 1 FROM fleet_git_operations WHERE workspace=$1 AND task_id=$2 AND status='pending' LIMIT 1",[workspace,command.taskId])).rowCount) throw new FleetConflict("pending Git operation requires reconciliation"); const fleet=applyFleetCommand(current.fleet,command,actor,role,dbTime); if(command.type==="job_schedule"){const checkpointId=fleet.leads?.[command.taskId]?.checkpointSnapshotId;if(checkpointId){await c.query("SELECT revision FROM state_workspaces WHERE workspace=$1 FOR UPDATE",[workspace]);const changed=await c.query("UPDATE state_gate_checkpoints SET status='consumed' WHERE workspace=$1 AND task_id=$2 AND snapshot_id=$3 AND status='approved'",[workspace,command.taskId,checkpointId]);if(!changed.rowCount){const cp=(await c.query("SELECT snapshot_id,status FROM state_gate_checkpoints WHERE workspace=$1 AND task_id=$2",[workspace,command.taskId])).rows[0];if(!cp || cp.snapshot_id!==checkpointId || cp.status!=="consumed") throw new Error("checkpoint changed before fenced dispatch");}}} const response={workspace,revision:expectedRevision+1,fleet:publicFleet(fleet),updatedAt:iso(now())}; await c.query("UPDATE fleet_workspaces SET revision=$1,fleet=$2,updated_at=$3 WHERE workspace=$4",[response.revision,fleet,response.updatedAt,workspace]); await c.query("INSERT INTO fleet_idempotency VALUES ($1,$2,$3)",[workspace,scopedKey,{payloadDigest:payloadDigest(role,actor,command),response}]); await c.query("COMMIT");return response; } catch(error){try{await c.query("ROLLBACK");}catch{} throw error;} finally{c.release();} }
+  async prepareGitOperation(input) {
+    const intent=gitIntent(input), c=await this.pool.connect();try{await this.#init(c);await c.query("BEGIN");const row=(await c.query("SELECT * FROM fleet_workspaces WHERE workspace=$1 FOR UPDATE",[intent.workspace])).rows[0];gitFence(row && view(row).fleet,intent.taskId,intent.epoch,intent.ownerToken,1000,Number((await c.query("SELECT extract(epoch from clock_timestamp()) * 1000 AS ms")).rows[0].ms));const old=gitRow((await c.query("SELECT * FROM fleet_git_operations WHERE workspace=$1 AND operation_id=$2 FOR UPDATE",[intent.workspace,intent.operationId])).rows[0]);if(old){if(old.taskId!==intent.taskId||old.epoch!==intent.epoch||old.ref!==intent.ref||old.oldOid!==intent.oldOid||old.newOid!==intent.newOid)throw new FleetConflict("Git operation intent mismatch");await c.query("COMMIT");return {status:old.status};}await c.query("INSERT INTO fleet_git_operations VALUES ($1,$2,$3,$4,$5,$6,$7,'pending')",[intent.workspace,intent.operationId,intent.taskId,intent.epoch,intent.ref,intent.oldOid,intent.newOid]);await c.query("COMMIT");return {status:"pending"};}catch(error){try{await c.query("ROLLBACK");}catch{}throw error;}finally{c.release();}
+  }
+  async getGitOperation({workspace,operationId}) {if(!id(workspace)||!id(operationId))throw new Error("invalid Git operation lookup");const c=await this.pool.connect();try{await this.#init(c);return gitRow((await c.query("SELECT * FROM fleet_git_operations WHERE workspace=$1 AND operation_id=$2",[workspace,operationId])).rows[0])??null;}finally{c.release();}}
+  async withGitFence({workspace,taskId,epoch,ownerToken,operationId},callback) {
+    if(!id(workspace)||!id(taskId)||!Number.isInteger(epoch)||typeof ownerToken!=="string"||!id(operationId)||typeof callback!=="function")throw new Error("invalid Git fence request");const c=await this.pool.connect();try{await this.#init(c);await c.query("BEGIN");const row=(await c.query("SELECT * FROM fleet_workspaces WHERE workspace=$1 FOR UPDATE",[workspace])).rows[0],fleet=row&&view(row).fleet;const record=gitRow((await c.query("SELECT * FROM fleet_git_operations WHERE workspace=$1 AND operation_id=$2 FOR UPDATE",[workspace,operationId])).rows[0]);const assertValid=async()=>gitFence(fleet,taskId,epoch,ownerToken,1000,Number((await c.query("SELECT extract(epoch from clock_timestamp()) * 1000 AS ms")).rows[0].ms));await assertValid();if(!record||record.taskId!==taskId||record.epoch!==epoch||record.status!=="pending")throw new FleetConflict("Git operation is absent, stale or already completed");let complete=false;const result=await callback({record,assertValid,complete:async()=>{await assertValid();complete=true;}});await assertValid();if(!complete)throw new Error("Git callback did not complete operation");await c.query("UPDATE fleet_git_operations SET status='complete' WHERE workspace=$1 AND operation_id=$2 AND status='pending'",[workspace,operationId]);await c.query("COMMIT");return result;}catch(error){try{await c.query("ROLLBACK");}catch{}throw error;}finally{c.release();}
+  }
+  async close(){await this.pool.end();}
+}
+
+export const createFleetRepository = () => process.env.MCP_STATE_DATABASE === "postgres" ? new PostgresFleetRepository() : new SqliteFleetRepository();

package/dist/services/aidlc-coordination/src/git-gateway.mjs

@@ -0,0 +1,50 @@
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+
+const id = (value) => typeof value === "string" && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value);
+const sha = (value) => typeof value === "string" && /^[a-f0-9]{40}$/.test(value);
+const git = (root, ...args) => execFileSync("git", args, { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 30000 }).trim();
+
+/**
+ * Gateway core. The deployment must deny every other writer to protected refs.
+ * Authority persists an intent before entering the same lease lock used by claims;
+ * a callback may update the ref only while that lock is held. A crash after Git's
+ * CAS but before authority commit leaves a pending intent and requires reconciliation.
+ */
+export function createGitGateway({ repo, protectedRefs, authority }) {
+  const root = realpathSync(repo);
+  if (git(root, "rev-parse", "--is-bare-repository") !== "true") throw new Error("Git gateway requires a bare repository");
+  if (!Array.isArray(protectedRefs) || !protectedRefs.length || new Set(protectedRefs).size !== protectedRefs.length) throw new Error("Explicit protected refs are required");
+  const permitted = new Set(protectedRefs);
+  for (const ref of protectedRefs) {
+    if (typeof ref !== "string" || !ref.startsWith("refs/heads/") || ref.includes("\0")) throw new Error("Invalid protected ref");
+    git(root, "check-ref-format", ref);
+  }
+  if (typeof authority?.prepareGitOperation !== "function" || typeof authority?.withGitFence !== "function") throw new Error("Fenced authority with durable operations is required");
+  return {
+    async update({ workspace, taskId, epoch, ownerToken, operationId, ref, oldCommit, newCommit }) {
+      if (!id(workspace) || !id(taskId) || !id(operationId) || !Number.isSafeInteger(epoch) || epoch < 1 || typeof ownerToken !== "string" || ownerToken.length < 32 || ownerToken.length > 256 || !permitted.has(ref) || !sha(oldCommit) || !sha(newCommit) || oldCommit === newCommit) throw new Error("Invalid protected Git update");
+      // resolve a commit object before creating the durable intent; no refs are changed.
+      if (git(root, "cat-file", "-t", newCommit) !== "commit") throw new Error("Git update requires a commit object");
+      try { git(root, "merge-base", "--is-ancestor", oldCommit, newCommit); }
+      catch { throw new Error("Protected Git updates must fast-forward"); }
+      const operation = { workspace, taskId, operationId, ref, oldOid:oldCommit, newOid:newCommit, epoch };
+      const prepared = await authority.prepareGitOperation({ ...operation, ownerToken });
+      if (prepared?.status === "complete") return { status: "complete", operationId, ref, newCommit };
+      if (prepared?.status !== "pending") throw new Error("Durable Git operation intent unavailable");
+      return authority.withGitFence({ workspace, taskId, epoch, ownerToken, operationId }, async (transaction) => {
+        if (typeof transaction?.assertValid !== "function" || typeof transaction?.complete !== "function" || transaction.record?.ref !== ref || transaction.record?.oldOid !== oldCommit || transaction.record?.newOid !== newCommit) throw new Error("Atomic fenced operation intent mismatch");
+        const current = git(root, "rev-parse", "--verify", ref);
+        if (current !== oldCommit) throw new Error(current === newCommit ? "Git update outcome uncertain; reconcile pending intent" : "Protected Git ref conflict");
+        // Recheck expiry while the same lease lock is held immediately before CAS.
+        await transaction.assertValid();
+        // oldCommit is passed to Git itself: competing ref updates fail atomically.
+        try { git(root, "update-ref", ref, newCommit, oldCommit); }
+        catch { throw new Error("Protected Git ref compare-and-swap failed; reconcile intent"); }
+        try { await transaction.complete(); }
+        catch { throw new Error("Git ref updated but authority commit uncertain; reconcile pending intent"); }
+        return { status: "complete", operationId, ref, newCommit };
+      });
+    }
+  };
+}

package/dist/services/aidlc-coordination/src/lifecycle-core.mjs

@@ -61,7 +61,9 @@ const validateTask = (id, task) => {
   if (!task.title || !["feature", "bug", "refactor", "infra"].includes(task.type) || !statuses.includes(task.status) || (task.phase === "done") !== (task.status === "done")) throw new Error(`Invalid task fields: ${id}`);
   if (!["vi", "en"].includes(task.language) || !["low", "normal", "high", "regulated"].includes(task.risk) || !Array.isArray(task.areas) || !task.areas.length || task.areas.some((area) => !text(area))) throw new Error(`Invalid task language, risk, or areas: ${id}`);
   if (task.decisions.some((item) => !item.id || !item.label || !["unresolved", "approved", "changed", "dropped"].includes(item.status) || (item.status === "changed" && !item.resolution))) throw new Error(`Invalid decisions: ${id}`);
+  if (task.featureId !== undefined && !idPattern.test(task.featureId)) throw new Error(`Invalid feature id: ${id}`);
   if (task.tasks.some((item) => !item.id || !item.label || !["todo", "in_progress", "done", "deferred"].includes(item.status))) throw new Error(`Invalid execution tasks: ${id}`);
+  readyTaskItems(task);
   if (task.evidence.some((item) => !["approval", "spec", "test", "lint", "review", "diagnostic"].includes(item.kind) || !["pass", "fail", "skip"].includes(item.result) || !item.source || !iso(item.recordedAt) || (item.area !== undefined && !text(item.area)) || (item.gate !== undefined && !gates.includes(item.gate)) || (item.kind === "approval" && (!item.gate || item.gate === "none")))) throw new Error(`Invalid evidence: ${id}`);
   const lessonIds = new Set();
   for (const lesson of task.lessons ?? []) { validateLesson(id, lesson); if (lessonIds.has(lesson.id)) throw new Error(`Duplicate lesson id: ${id}/${lesson.id}`); lessonIds.add(lesson.id); }
@@ -276,6 +278,35 @@ export const transitionTask = (state, id, target) => {
   task.phase = target; task.gate = phaseGate(target); task.status = target === "done" ? "done" : "active"; delete task.legacyG2Wait; task.updatedAt = new Date().toISOString(); return task;
 };
 
+export const readyTaskItems = (task) => {
+  const byId = new Map(task.tasks.map((item) => [item.id, item]));
+  if (byId.size !== task.tasks.length) throw new Error(`Duplicate execution item: ${task.id}`);
+  const visiting = new Set(); const visited = new Set();
+  const visit = (id) => {
+    if (visiting.has(id)) throw new Error(`Cyclic execution dependency: ${task.id}/${id}`);
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const dep of byId.get(id)?.dependsOn ?? []) {
+      if (dep === id || !byId.has(dep)) throw new Error(`Unknown execution dependency: ${task.id}/${id}/${dep}`);
+      visit(dep);
+    }
+    visiting.delete(id); visited.add(id);
+  };
+  for (const item of task.tasks) {
+    if (item.dependsOn !== undefined && (!Array.isArray(item.dependsOn) || new Set(item.dependsOn).size !== item.dependsOn.length || item.dependsOn.some((dep) => typeof dep !== "string" || !dep))) throw new Error(`Invalid execution dependencies: ${task.id}/${item.id}`);
+    if (item.ownedPaths !== undefined && (!Array.isArray(item.ownedPaths) || new Set(item.ownedPaths).size !== item.ownedPaths.length || item.ownedPaths.some((path) => typeof path !== "string" || !path || isAbsolute(path) || path === ".." || path.startsWith("../") || path.includes("\\") || path.split("/").includes("..")))) throw new Error(`Invalid owned paths: ${task.id}/${item.id}`);
+    visit(item.id);
+  }
+  const ready = []; const blocked = [];
+  for (const item of task.tasks) {
+    const waitingOn = (item.dependsOn ?? []).filter((dep) => byId.get(dep)?.status !== "done");
+    if (item.status === "done" && waitingOn.length) throw new Error(`Completed item has incomplete prerequisites: ${task.id}/${item.id}`);
+    if (item.status !== "todo" && item.status !== "in_progress") continue;
+    if (waitingOn.length) blocked.push({ id: item.id, waitingOn }); else ready.push(item.id);
+  }
+  return { ready, blocked };
+};
+
 export const nextAction = (task, root) => {
   const rootSuffix = root === undefined ? "" : ` --root ${JSON.stringify(resolve(root))}`;
   const script = (name) => root === undefined ? `node .agents/aidlc/scripts/${name}` : `node ${JSON.stringify(join(resolve(root), ".agents/aidlc/scripts", name))}`;
@@ -288,16 +319,20 @@ export const nextAction = (task, root) => {
   if (task.status === "blocked_on_user" && task.gate === "G1_review" && task.decisions.some((decision) => decision.status === "unresolved")) return { classification: "run_phase", phase: task.phase, gate: task.gate, command: `${contextCommand} ${task.id} --phase plan${rootSuffix}`, reason: "Invalid premature G1 wait; resolve every decision before presenting G1" };
   if (task.status === "blocked_on_user" && task.gate === "G2_codereview" && (task.tasks.some((item) => !["done", "deferred"].includes(item.status)) || !hasVerification(task) || !hasReview(task))) {
     const open = task.tasks.filter((item) => item.status === "in_progress" || item.status === "todo");
-    const item = open.find((entry) => entry.status === "in_progress") ?? open[0];
+    const ready = new Set(readyTaskItems(task).ready);
+    const item = open.find((entry) => entry.status === "in_progress" && ready.has(entry.id)) ?? open.find((entry) => ready.has(entry.id));
     if (item) return { classification: "run_phase", phase: task.phase, gate: task.gate, itemId: item.id, remainingItems: open.length, command: `${contextCommand} ${task.id} --phase build --item ${item.id}${rootSuffix}`, reason: `Invalid premature G2 wait; continue build item ${item.id}` };
+    if (open.length) return { classification: "blocked", phase: task.phase, gate: task.gate, reason: `No dependency-ready build item: ${readyTaskItems(task).blocked.map((entry) => `${entry.id} waits for ${entry.waitingOn.join(",")}`).join("; ")}` };
     return { classification: "run_phase", phase: task.phase, gate: task.gate, remainingItems: 0, command: `${contextCommand} ${task.id} --phase build${rootSuffix}`, reason: "Invalid premature G2 wait; continue verification and adversarial review before presenting G2" };
   }
   if (task.status === "blocked_on_user" && task.gate === "none") return { classification: "run_phase", phase: task.phase, gate: task.gate, command: `${stateCommand} task status ${task.id} --status active${rootSuffix}`, reason: "Recover invalid wait at a gateless wrap phase before continuing wrap" };
   if (task.status === "blocked_on_user") return { classification: "await_user", phase: task.phase, gate: task.gate, command: `${stateCommand} gate approve ${task.id} --gate ${task.gate} --source <explicit-user-approval>${rootSuffix}`, reason: `Explicit human approval is required at ${task.gate}` };
   if (task.phase === "build") {
     const open = task.tasks.filter((item) => item.status === "in_progress" || item.status === "todo");
-    const item = open.find((entry) => entry.status === "in_progress") ?? open[0];
+    const ready = new Set(readyTaskItems(task).ready);
+    const item = open.find((entry) => entry.status === "in_progress" && ready.has(entry.id)) ?? open.find((entry) => ready.has(entry.id));
     if (item) return { classification: "run_phase", phase: task.phase, gate: task.gate, itemId: item.id, remainingItems: open.length, command: `${contextCommand} ${task.id} --phase build --item ${item.id}${rootSuffix}`, reason: `Continue build item ${item.id}; ${open.length} actionable item(s) remain before verification, review, and G2` };
+    if (open.length) return { classification: "blocked", phase: task.phase, gate: task.gate, reason: `No dependency-ready build item: ${readyTaskItems(task).blocked.map((entry) => `${entry.id} waits for ${entry.waitingOn.join(",")}`).join("; ")}` };
     return { classification: "run_phase", phase: task.phase, gate: task.gate, remainingItems: 0, command: `${contextCommand} ${task.id} --phase build${rootSuffix}`, reason: "All build items are terminal; continue verification, adversarial review, and G2 preparation" };
   }
   return { classification: "run_phase", phase: task.phase, gate: task.gate, command: `${contextCommand} ${task.id} --phase ${task.phase}${rootSuffix}`, reason: `Continue ${task.phase} until the next human gate, real blocker, or completion` };
@@ -322,7 +357,7 @@ export const searchLessons = (root, state, query, areas = [], limit = 5) => { co
 
 export const listTaskSummaries = (state, options = {}) => { const active = Object.values(state.tasks).map((task) => ({ id: task.id, title: task.title, phase: task.phase, gate: task.gate, status: task.status, risk: task.risk, areas: task.areas, updatedAt: task.updatedAt, source: "active" })); const archived = options.includeArchive ? Object.values(state.archive ?? {}).map((task) => ({ id: task.id, title: task.title, phase: task.phase, gate: task.gate, status: task.status, risk: task.risk, areas: task.areas, updatedAt: task.updatedAt, source: "archive" })) : []; const queryTokens = tokens(options.query ?? ""); const statusSet = new Set(options.statuses ?? []); const filtered = [...active, ...archived].filter((item) => (!statusSet.size || statusSet.has(item.status)) && (!queryTokens.length || queryTokens.every((token) => tokens(`${item.id} ${item.title} ${item.areas.join(" ")}`).includes(token)))).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.id.localeCompare(b.id)); const cursor = Math.max(0, options.cursor ?? 0); const limit = Math.max(1, Math.min(options.limit ?? 20, 100)); const items = filtered.slice(cursor, cursor + limit); return { items, nextCursor: cursor + items.length < filtered.length ? String(cursor + items.length) : null, total: filtered.length }; };
 
-export const renderWorkplan = (task) => { const decisions = task.decisions.length ? task.decisions.map((item) => `- [${item.status === "approved" ? "x" : " "}] ${item.id} — ${item.label}${item.resolution ? ` — ${item.resolution}` : ""}`).join("\n") : "- None"; const tasks = task.tasks.length ? task.tasks.map((item) => `- [${item.status === "done" ? "x" : item.status === "in_progress" ? "~" : " "}] ${item.id} — ${item.label}`).join("\n") : "- None"; const lifecycle = [`- Status: \`${task.status}\``, task.handoff ? `- Handoff: \`${task.handoff.kind}\` — ${task.handoff.reason}` : "", task.closure ? `- Closure: ${task.closure.reason}` : "", task.predecessorTaskId ? `- Predecessor: \`${task.predecessorTaskId}\`` : "", task.successorTaskId ? `- Successor: \`${task.successorTaskId}\`` : "", task.lessonDisposition ? `- Lessons: \`${task.lessonDisposition.status}\`` : ""].filter(Boolean).join("\n"); return `# Workplan — ${task.title} (\`${task.id}\`)\n\n> Generated from canonical JSON state.\n\n## Lifecycle\n${lifecycle}\n\n## 🧩 Decisions (Gate G1 — approve before build)\n${decisions}\n\n## 🧩 Tasks (Gate G2 — build execution)\n${tasks}\n`; };
+export const renderWorkplan = (task) => { const decisions = task.decisions.length ? task.decisions.map((item) => `- [${item.status === "approved" ? "x" : " "}] ${item.id} — ${item.label}${item.resolution ? ` — ${item.resolution}` : ""}`).join("\n") : "- None"; const tasks = task.tasks.length ? task.tasks.map((item) => `- [${item.status === "done" ? "x" : item.status === "in_progress" ? "~" : " "}] ${item.id} — ${item.label}`).join("\n") : "- None"; const lifecycle = [`- Status: \`${task.status}\``, task.handoff ? `- Handoff: \`${task.handoff.kind}\` — ${task.handoff.reason}` : "", task.closure ? `- Closure: ${task.closure.reason}` : "", task.predecessorTaskId ? `- Predecessor: \`${task.predecessorTaskId}\`` : "", task.successorTaskId ? `- Successor: \`${task.successorTaskId}\`` : "", task.lessonDisposition ? `- Lessons: \`${task.lessonDisposition.status}\`` : ""].filter(Boolean).join("\n"); return `# Workplan — ${task.title} (\`${task.id}\`)\n\n> Generated from canonical JSON state.\n\n## Lifecycle\n${lifecycle}\n\n## 🧩 Decisions (Approve plan — before implementation)\n${decisions}\n\n## 🧩 Tasks (Review implementation — work items)\n${tasks}\n`; };
 export const renderViews = (root, state = loadState(root), selected = Object.values(state.tasks)) => { for (const task of selected) { if (!task.artifacts.workplan) continue; assertNoSymlinkPath(root, task.artifacts.workplan); writeAtomic(join(resolve(root), task.artifacts.workplan), renderWorkplan(task)); } };
 
 const safeArtifactTarget = (root, path) => { assertNoSymlinkPath(root, path); return join(resolve(root), path); };
@@ -335,7 +370,7 @@ export const formatDiagnostics = (diagnostics) => diagnostics.map((item) => `${i
 
 const oneLine = (value) => value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").replace(/ACTION\s+REQUIRED/gi, "ACTION-REQUIRED").trim();
 const markdownText = (value) => oneLine(value).replace(/([\\`*_{}\[\]()<>#+.!|>~])/g, "\\$1");
-const gateMeta = { G0_confirm: { icon: "🟢", title: "GATE G0 · CONFIRM INTENT", action: "Reply `ok` to approve intent, or state changes." }, G1_review: { icon: "🔵", title: "GATE G1 · REVIEW PLAN", action: "Reply `approve` to start build, or state decision changes." }, G2_codereview: { icon: "🟣", title: "GATE G2 · REVIEW CODE", action: "Approve to wrap, or point out what to fix." } };
+const gateMeta = { G0_confirm: { icon: "🟢", title: "Review step · Confirm requirements", action: "Reply `ok` to confirm requirements, or state changes." }, G1_review: { icon: "🔵", title: "Review step · Approve plan", action: "Reply `approve` to approve the plan and start implementation, or state decision changes." }, G2_codereview: { icon: "🟣", title: "Review step · Review implementation", action: "Approve the implementation to complete the task, or point out what to fix." } };
 export const gateView = (task, diagnostics) => { if (task.gate === "none") throw new Error(`Task has no human gate: ${task.id}`); const errors = diagnostics.filter((item) => item.level === "ERROR"); if (errors.length) throw new Error(errors.map((item) => item.message).join("; ")); const meta = gateMeta[task.gate]; const counts = (items) => items.reduce((result, item) => ({ ...result, [item.status]: (result[item.status] ?? 0) + 1 }), {}); return { schemaVersion: 1, gate: task.gate, icon: meta.icon, title: meta.title, action: meta.action, task: { id: task.id, title: oneLine(task.title), status: task.status, risk: task.risk, areas: task.areas }, artifacts: Object.entries(task.artifacts).flatMap(([name, path]) => path ? [{ name: oneLine(name), path: oneLine(path) }] : []), decisions: counts(task.decisions), execution: counts(task.tasks), evidence: task.evidence.filter((item) => ["test", "lint", "review"].includes(item.kind)).slice(-5).map((item) => ({ kind: item.kind, result: item.result, source: oneLine(item.source) })), diagnostics: diagnostics.filter((item) => item.level !== "INFO").map((item) => ({ level: item.level, code: item.code, message: oneLine(item.message) })) }; };
 const markdownLinkTarget = (value) => encodeURI(value).replace(/[()#?]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
 export const formatGateView = (task, diagnostics, format = "markdown") => { const view = gateView(task, diagnostics); if (format === "json") return `${JSON.stringify(view, null, 2)}\n`; const artifacts = view.artifacts.length ? view.artifacts.map((item) => format === "markdown" ? `- **${markdownText(item.name)}:** [${markdownText(item.path)}](${markdownLinkTarget(item.path)})` : `- ${item.name}: ${item.path}`).join("\n") : "- none"; const decisions = Object.entries(view.decisions).map(([status, count]) => `${count} ${status}`).join(" · ") || "none"; const execution = Object.entries(view.execution).map(([status, count]) => `${count} ${status}`).join(" · ") || "none"; const evidence = view.evidence.length ? view.evidence.map((item) => `- ${item.kind}: ${item.result} — ${format === "markdown" ? markdownText(item.source) : item.source}`).join("\n") : "- none yet"; const warnings = view.diagnostics.length ? `\n\n${view.diagnostics.map((item) => `- ${item.level} ${item.code}: ${format === "markdown" ? markdownText(item.message) : item.message}`).join("\n")}` : ""; if (format === "plain") return [`[IMPORTANT] ${view.icon} ${view.title}`, `Task: ${view.task.id} — ${view.task.title}`, `Status: ${view.task.status} · Risk: ${view.task.risk} · Areas: ${view.task.areas.join(", ")}`, "", "Review artifacts", artifacts, "", `Decisions: ${decisions}`, `Execution: ${execution}`, "Evidence", evidence, warnings, "", `ACTION REQUIRED -> ${oneLine(view.action)}`].join("\n").replace(/\n{3,}/g, "\n\n") + "\n"; return ["> [!IMPORTANT]", `> ${view.icon} **${view.title}**`, `> **Task:** \`${view.task.id}\` — ${markdownText(view.task.title)}`, `> **Status:** \`${view.task.status}\` · **Risk:** \`${view.task.risk}\` · **Areas:** ${view.task.areas.map((area) => `\`${markdownText(area)}\``).join(", ")}`, "", "### Review artifacts", artifacts, "", `**Decisions:** ${decisions}  `, `**Execution:** ${execution}`, "", "### Verification evidence", evidence, warnings, "", `> **ACTION REQUIRED →** ${view.action}`].join("\n").replace(/\n{3,}/g, "\n\n") + "\n"; };