@felixdotgo/aidlc-kit 0.1.0 → 0.2.0

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

@@ -119,6 +119,19 @@ const approveSnapshot = (current, snapshot, taskId, source, integrationCommit) =
   transitionTask(state, taskId, target);
   return mutationResult(current.state, state, current.index, [taskId]);
 };
+const rejectSnapshot = (current, snapshot, taskId, feedback, snapshotId) => {
+  if (typeof feedback !== "string" || !feedback.trim() || feedback.length > 2000) throw new Error("bounded feedback text is required");
+  if (!snapshot || snapshot.task_id !== taskId || !current.state.tasks?.[taskId] || snapshot.task_digest !== taskDigest(current.state.tasks[taskId])) throw new Error("stale gate snapshot");
+  const task = current.state.tasks?.[taskId];
+  if (!task || task.gate !== snapshot.gate || task.status !== "blocked_on_user" || nextAction(task).classification !== "await_user") throw new Error("gate is no longer ready");
+  const state = structuredClone(current.state);
+  const recordedAt = new Date().toISOString();
+  state.tasks[taskId].evidence.push({ kind: "diagnostic", result: "pass", source: `Fleet reviewer: feedback (${snapshotId})`, detail: `Cancelled gate wait at ${snapshot.gate}: ${feedback}`, recordedAt });
+  delete state.tasks[taskId].legacyG2Wait;
+  state.tasks[taskId].status = "active";
+  state.tasks[taskId].updatedAt = recordedAt;
+  return mutationResult(current.state, state, current.index, [taskId]);
+};
 const verifyFence = (fleet, taskId, epoch, ownerToken, time = Date.now()) => {
   const lead = fleet?.leads?.[taskId];
   if (!lead || !Number.isInteger(epoch) || lead.epoch !== epoch || Date.parse(lead.expiresAt) <= time || (lead.ownerTokenHash && (typeof ownerToken !== "string" || createHash("sha256").update(ownerToken).digest("hex") !== lead.ownerTokenHash))) throw new Error("stale or expired lead epoch");
@@ -306,6 +319,32 @@ export class SqliteStateRepository {
     } catch(error){try{this.db.exec("ROLLBACK");}catch{} throw error;}
   }
 
+  async rejectGate(workspace,expectedRevision,idempotencyKey,taskId,gateSnapshotId,feedback,clientProjectRoot,principal) {
+    if(typeof idempotencyKey!=="string"||!idempotencyKey.trim()||typeof clientProjectRoot!=="string"||!isAbsolute(clientProjectRoot)) throw new Error("invalid rejection precondition");
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      this.#ensure(workspace);
+      sqliteRequest(this.db,workspace,idempotencyKey,principal,"gate_reject",{expectedRevision,taskId,gateSnapshotId,feedback,clientProjectRoot});
+      const cached=this.db.prepare("SELECT response FROM state_idempotency WHERE workspace=? AND idempotency_key=?").get(workspace,idempotencyKey);
+      if(cached){this.db.exec("COMMIT");return parse(cached.response);}
+      const current=snapshot(this.db.prepare("SELECT * FROM state_workspaces WHERE workspace=?").get(workspace));
+      if(current.revision!==expectedRevision) throw new RevisionConflict(current);
+      const gateSnapshot=this.db.prepare("SELECT * FROM state_gate_snapshots WHERE workspace=? AND id=?").get(workspace,gateSnapshotId);
+      const checkpointRow=this.db.prepare("SELECT * FROM state_gate_checkpoints WHERE workspace=? AND task_id=?").get(workspace,taskId);
+      const fleetRow=this.db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='fleet_workspaces'").get() ? this.db.prepare("SELECT fleet FROM fleet_workspaces WHERE workspace=?").get(workspace) : null;
+      const managed=fleetRow && parse(fleetRow.fleet)?.supervisors?.[taskId];
+      if (managed && (!checkpointRow || checkpointRow.status !== "pending" || checkpointRow.snapshot_id !== gateSnapshotId)) throw new Error("supervised rejection requires matching pending checkpoint");
+      if (checkpointRow?.status === "pending" && checkpointRow.snapshot_id !== gateSnapshotId) throw new Error("gate checkpoint does not match snapshot");
+      const next=rejectSnapshot(current,gateSnapshot,taskId,feedback,gateSnapshotId); const revision=current.revision+1; const updatedAt=new Date().toISOString(); next.index={...next.index,sourceRevision:revision,updatedAt};
+      const response={workspace,revision,state:next.state,index:next.index,nextActions:{[taskId]:nextAction(next.state.tasks[taskId],resolve(clientProjectRoot))},updatedAt};
+      this.db.prepare("UPDATE state_workspaces SET revision=?,state=?,task_index=?,updated_at=? WHERE workspace=?").run(revision,encode(next.state),encode(next.index),updatedAt,workspace);
+      this.db.prepare("UPDATE state_gate_checkpoints SET status='rejected' WHERE workspace=? AND task_id=? AND snapshot_id=? AND status='pending'").run(workspace,taskId,gateSnapshotId);
+      this.db.prepare("INSERT INTO state_events (workspace,revision,idempotency_key,command,recorded_at) VALUES (?,?,?,?,?)").run(workspace,revision,idempotencyKey,encode({type:"gate_reject",taskId,snapshotId:gateSnapshotId}),updatedAt);
+      this.db.prepare("INSERT INTO state_idempotency VALUES (?,?,?)").run(workspace,idempotencyKey,encode(response));
+      this.db.exec("COMMIT");return response;
+    } catch(error){try{this.db.exec("ROLLBACK");}catch{} throw error;}
+  }
+
   close() { this.db.close(); }
 }
 
@@ -360,6 +399,33 @@ export class PostgresStateRepository {
   async putGateSnapshot(workspace,expectedRevision,idempotencyKey,taskId,gate,reviewText,leadEpoch,integrationCommit,leadOwnerToken,checkpoint=false,principal) { if(typeof idempotencyKey!=="string"||!idempotencyKey.trim()) throw new Error("idempotencyKey is required"); const c=await this.pool.connect(); try { await this.#init(c); await c.query("BEGIN"); if(leadEpoch!==undefined){const fleetRow=(await c.query("SELECT fleet FROM fleet_workspaces WHERE workspace=$1 FOR UPDATE",[workspace])).rows[0];verifyFence(fleetRow?.fleet,taskId,leadEpoch,leadOwnerToken,Number((await c.query("SELECT extract(epoch from clock_timestamp()) * 1000 AS ms")).rows[0].ms));} await c.query("INSERT INTO state_workspaces VALUES ($1,0,$2,$3,$4) ON CONFLICT DO NOTHING",[workspace,emptyState(),emptyIndex(0),new Date().toISOString()]); const row=(await c.query("SELECT * FROM state_workspaces WHERE workspace=$1 FOR UPDATE",[workspace])).rows[0]; await postgresRequest(c,workspace,idempotencyKey,principal,"gate_snapshot_put",{expectedRevision,taskId,gate,reviewText,leadEpoch,integrationCommit,leadOwnerToken,checkpoint}); const cached=(await c.query("SELECT response FROM state_idempotency WHERE workspace=$1 AND idempotency_key=$2",[workspace,idempotencyKey])).rows[0]; if(cached){await c.query("COMMIT");return cached.response;} const current={workspace,revision:Number(row.revision),state:upgradeStoredState(row.state),index:row.task_index,updatedAt:row.updated_at}; if(current.revision!==expectedRevision) throw new RevisionConflict(current); if(checkpoint){const prior=(await c.query("SELECT status FROM state_gate_checkpoints WHERE workspace=$1 AND task_id=$2 FOR UPDATE",[workspace,taskId])).rows[0];if(prior?.status==="approved") throw new Error("approved checkpoint must be reconciled before replacement");} const boundReviewText=reviewWithCommit(gate,reviewText,integrationCommit); validateGateSnapshot(current,taskId,gate,boundReviewText,integrationCommit); const item={id:snapshotId(workspace,taskId,current.revision,gate,boundReviewText,integrationCommit),workspace,taskId,gate,stateRevision:current.revision,taskDigest:taskDigest(current.state.tasks[taskId]),integrationCommit:integrationCommit??null,reviewText:boundReviewText,createdAt:new Date().toISOString()}; await c.query("INSERT INTO state_gate_snapshots VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9) ON CONFLICT DO NOTHING",[item.id,workspace,taskId,gate,current.revision,item.taskDigest,item.integrationCommit,boundReviewText,item.createdAt]); item.createdAt=(await c.query("SELECT created_at FROM state_gate_snapshots WHERE id=$1",[item.id])).rows[0].created_at; if(checkpoint) await c.query("INSERT INTO state_gate_checkpoints (workspace,task_id,snapshot_id,gate,task_digest,state_revision,integration_commit,status,approval_revision,phase) VALUES ($1,$2,$3,$4,$5,$6,$7,'pending',NULL,$8) ON CONFLICT(workspace,task_id) DO UPDATE SET snapshot_id=excluded.snapshot_id,gate=excluded.gate,task_digest=excluded.task_digest,state_revision=excluded.state_revision,integration_commit=excluded.integration_commit,status='pending',approval_revision=NULL,phase=excluded.phase",[workspace,taskId,item.id,gate,item.taskDigest,current.revision,item.integrationCommit,current.state.tasks[taskId].phase]); await c.query("INSERT INTO state_idempotency VALUES ($1,$2,$3)",[workspace,idempotencyKey,item]); await c.query("COMMIT");return item; } catch(error){try{await c.query("ROLLBACK");}catch{} throw error;} finally{c.release();} }
   async gateCheckpoint(workspace,taskId) { const c=await this.pool.connect(); try { await this.#init(c); const row=(await c.query("SELECT snapshot_id AS \"snapshotId\",gate,phase,task_digest AS \"taskDigest\",state_revision AS \"stateRevision\",integration_commit AS \"integrationCommit\",status,approval_revision AS \"approvalRevision\" FROM state_gate_checkpoints WHERE workspace=$1 AND task_id=$2",[workspace,taskId])).rows[0]; return row ? {...row,stateRevision:Number(row.stateRevision),approvalRevision:row.approvalRevision===null?null:Number(row.approvalRevision)} : null; } finally { c.release(); } }
   async approveGate(workspace,expectedRevision,idempotencyKey,taskId,gateSnapshotId,source,clientProjectRoot,integrationCommit,principal) { if(typeof idempotencyKey!=="string"||!idempotencyKey.trim()||typeof clientProjectRoot!=="string"||!isAbsolute(clientProjectRoot)) throw new Error("invalid approval precondition"); const c=await this.pool.connect(); try { await this.#init(c); await c.query("BEGIN"); const fleetTable=(await c.query("SELECT to_regclass('fleet_workspaces') AS name")).rows[0].name; const fleetRow=fleetTable ? (await c.query("SELECT fleet FROM fleet_workspaces WHERE workspace=$1 FOR UPDATE",[workspace])).rows[0] : null; await c.query("INSERT INTO state_workspaces VALUES ($1,0,$2,$3,$4) ON CONFLICT DO NOTHING",[workspace,emptyState(),emptyIndex(0),new Date().toISOString()]); const row=(await c.query("SELECT * FROM state_workspaces WHERE workspace=$1 FOR UPDATE",[workspace])).rows[0]; await postgresRequest(c,workspace,idempotencyKey,principal,"gate_approve",{expectedRevision,taskId,gateSnapshotId,source,clientProjectRoot,integrationCommit}); const cached=(await c.query("SELECT response FROM state_idempotency WHERE workspace=$1 AND idempotency_key=$2",[workspace,idempotencyKey])).rows[0]; if(cached){await c.query("COMMIT");return cached.response;} const current={workspace,revision:Number(row.revision),state:upgradeStoredState(row.state),index:row.task_index,updatedAt:row.updated_at}; if(current.revision!==expectedRevision) throw new RevisionConflict(current); const gateSnapshot=(await c.query("SELECT * FROM state_gate_snapshots WHERE workspace=$1 AND id=$2",[workspace,gateSnapshotId])).rows[0]; const checkpointRow=(await c.query("SELECT * FROM state_gate_checkpoints WHERE workspace=$1 AND task_id=$2 FOR UPDATE",[workspace,taskId])).rows[0]; if(fleetRow?.fleet?.supervisors?.[taskId] && (!checkpointRow || checkpointRow.status!=="pending" || checkpointRow.snapshot_id!==gateSnapshotId)) throw new Error("supervised approval requires matching pending checkpoint"); if(checkpointRow?.status==="pending" && checkpointRow.snapshot_id!==gateSnapshotId) throw new Error("gate checkpoint does not match snapshot"); const next=approveSnapshot(current,gateSnapshot,taskId,source,integrationCommit); const revision=current.revision+1; const updatedAt=new Date().toISOString(); next.index={...next.index,sourceRevision:revision,updatedAt}; const response={workspace,revision,state:next.state,index:next.index,nextActions:{[taskId]:nextAction(next.state.tasks[taskId],resolve(clientProjectRoot))},updatedAt}; await c.query("UPDATE state_workspaces SET revision=$1,state=$2,task_index=$3,updated_at=$4 WHERE workspace=$5",[revision,next.state,next.index,updatedAt,workspace]); await c.query("UPDATE state_gate_checkpoints SET status='approved',approval_revision=$1 WHERE workspace=$2 AND task_id=$3 AND snapshot_id=$4 AND status='pending'",[revision,workspace,taskId,gateSnapshotId]); await c.query("INSERT INTO state_events (workspace,revision,idempotency_key,command,recorded_at) VALUES ($1,$2,$3,$4,$5)",[workspace,revision,idempotencyKey,{type:"gate_approve",taskId,snapshotId:gateSnapshotId,integrationCommit:integrationCommit??null},updatedAt]); await c.query("INSERT INTO state_idempotency VALUES ($1,$2,$3)",[workspace,idempotencyKey,response]); await c.query("COMMIT");return response; } catch(error){try{await c.query("ROLLBACK");}catch{} throw error;} finally{c.release();} }
+  async rejectGate(workspace,expectedRevision,idempotencyKey,taskId,gateSnapshotId,feedback,clientProjectRoot,principal) {
+    if(typeof idempotencyKey!=="string"||!idempotencyKey.trim()||typeof clientProjectRoot!=="string"||!isAbsolute(clientProjectRoot)) throw new Error("invalid rejection precondition");
+    const c=await this.pool.connect();
+    try {
+      await this.#init(c); await c.query("BEGIN");
+      const fleetTable=(await c.query("SELECT to_regclass('fleet_workspaces') AS name")).rows[0].name;
+      const fleetRow=fleetTable ? (await c.query("SELECT fleet FROM fleet_workspaces WHERE workspace=$1 FOR UPDATE",[workspace])).rows[0] : null;
+      await c.query("INSERT INTO state_workspaces VALUES ($1,0,$2,$3,$4) ON CONFLICT DO NOTHING",[workspace,emptyState(),emptyIndex(0),new Date().toISOString()]);
+      const row=(await c.query("SELECT * FROM state_workspaces WHERE workspace=$1 FOR UPDATE",[workspace])).rows[0];
+      await postgresRequest(c,workspace,idempotencyKey,principal,"gate_reject",{expectedRevision,taskId,gateSnapshotId,feedback,clientProjectRoot});
+      const cached=(await c.query("SELECT response FROM state_idempotency WHERE workspace=$1 AND idempotency_key=$2",[workspace,idempotencyKey])).rows[0];
+      if(cached){await c.query("COMMIT");return cached.response;}
+      const current={workspace,revision:Number(row.revision),state:upgradeStoredState(row.state),index:row.task_index,updatedAt:row.updated_at};
+      if(current.revision!==expectedRevision) throw new RevisionConflict(current);
+      const gateSnapshot=(await c.query("SELECT * FROM state_gate_snapshots WHERE workspace=$1 AND id=$2",[workspace,gateSnapshotId])).rows[0];
+      const checkpointRow=(await c.query("SELECT * FROM state_gate_checkpoints WHERE workspace=$1 AND task_id=$2 FOR UPDATE",[workspace,taskId])).rows[0];
+      if(fleetRow?.fleet?.supervisors?.[taskId] && (!checkpointRow || checkpointRow.status!=="pending" || checkpointRow.snapshot_id!==gateSnapshotId)) throw new Error("supervised rejection requires matching pending checkpoint");
+      if(checkpointRow?.status==="pending" && checkpointRow.snapshot_id!==gateSnapshotId) throw new Error("gate checkpoint does not match snapshot");
+      const next=rejectSnapshot(current,gateSnapshot,taskId,feedback,gateSnapshotId); const revision=current.revision+1; const updatedAt=new Date().toISOString(); next.index={...next.index,sourceRevision:revision,updatedAt};
+      const response={workspace,revision,state:next.state,index:next.index,nextActions:{[taskId]:nextAction(next.state.tasks[taskId],resolve(clientProjectRoot))},updatedAt};
+      await c.query("UPDATE state_workspaces SET revision=$1,state=$2,task_index=$3,updated_at=$4 WHERE workspace=$5",[revision,next.state,next.index,updatedAt,workspace]);
+      await c.query("UPDATE state_gate_checkpoints SET status='rejected' WHERE workspace=$1 AND task_id=$2 AND snapshot_id=$3 AND status='pending'",[workspace,taskId,gateSnapshotId]);
+      await c.query("INSERT INTO state_events (workspace,revision,idempotency_key,command,recorded_at) VALUES ($1,$2,$3,$4,$5)",[workspace,revision,idempotencyKey,{type:"gate_reject",taskId,snapshotId:gateSnapshotId},updatedAt]);
+      await c.query("INSERT INTO state_idempotency (workspace,idempotency_key,response) VALUES ($1,$2,$3)",[workspace,idempotencyKey,response]);
+      await c.query("COMMIT"); return response;
+    } 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/server.mjs

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { timingSafeEqual } from "node:crypto";
+import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/server";
 import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
 import { createMcpExpressApp } from "@modelcontextprotocol/express";
@@ -10,12 +11,14 @@ import { CoordinationConflict, SqliteCoordinationRepository, createCoordinationR
 import { FleetConflict, SqliteFleetRepository, createFleetRepository, featureReady, validateCanonicalFeature } from "./fleet.mjs";
 import { nextAction } from "./lifecycle-core.mjs";
 
+let serviceVersion = "0.0.0-dev";
+try { const parsed = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")); if (parsed?.version) serviceVersion = parsed.version; } catch {}
 const result = (value) => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
 const failure = (error) => ({ isError: true, content: [{ type: "text", text: JSON.stringify(error instanceof RevisionConflict ? { code: "REVISION_CONFLICT", current: error.current } : error instanceof CoordinationConflict ? { code: "COORDINATION_CONFLICT", current: error.current } : error instanceof FleetConflict ? { code: "FLEET_CONFLICT", current: error.current, message: error.message } : { code: "STATE_ERROR", message: error instanceof Error ? error.message : String(error) }) }] });
 const workspace = z.string().min(1).max(128);
 
 export const buildServer = (repository, coordination = new SqliteCoordinationRepository(), fleet = new SqliteFleetRepository(), identity = null) => {
-  const server = new McpServer({ name: "aidlc-coordination", version: "0.1.0" });
+  const server = new McpServer({ name: "aidlc-coordination", version: serviceVersion });
   const requireRole = (...allowed) => { if (identity && !allowed.includes(identity.role)) throw new Error("credential role is not authorized for this operation"); };
   const actorFor = (actor) => identity ? { id: identity.id, role: { lead: "admin", worker: "commenter", reviewer: "reader" }[identity.role] } : actor;
   server.registerTool("state_get", { description: "Pull the current workflow state and derived index for a workspace.", inputSchema: z.object({ workspace }) }, async ({ workspace: id }) => { try { return result(await repository.get(id)); } catch (error) { return failure(error); } });
@@ -55,6 +58,7 @@ export const buildServer = (repository, coordination = new SqliteCoordinationRep
     server.registerTool("gate_snapshot_put", { description: "Publish a review snapshot at the current canonical task revision, binding G2 to an integration commit.", inputSchema: z.object({...precondition,taskId:z.string(),leadEpoch:z.number().int(),leadOwnerToken:z.string().min(32).max(256).optional(),checkpoint:z.boolean().optional(),gate:z.enum(["G0_confirm","G1_review","G2_codereview"]),reviewText:z.string().min(1).max(20000),integrationCommit:z.string().regex(/^[a-f0-9]{40}$/).optional()}) }, async ({workspace:id,expectedRevision,idempotencyKey,taskId,leadEpoch,leadOwnerToken,checkpoint,gate,reviewText,integrationCommit}) => { try { requireRole("lead"); return result(await repository.putGateSnapshot(id,expectedRevision,idempotencyKey,taskId,gate,reviewText,leadEpoch,integrationCommit,leadOwnerToken,checkpoint,identity.id)); } catch(error){return failure(error);} });
     server.registerTool("gate_checkpoint_get", { description: "Read durable supervisor gate checkpoint.", inputSchema: z.object({workspace,taskId:z.string()}) }, async ({workspace:id,taskId}) => { try { requireRole("lead","reviewer"); return result(await repository.gateCheckpoint(id,taskId)); } catch(error){return failure(error);} });
     server.registerTool("gate_approve", { description: "Reviewer-only atomic approval against an unchanged task revision and reviewed integration commit.", inputSchema: z.object({...precondition,taskId:z.string(),snapshotId:z.string(),source:z.string().min(1).max(2000),clientProjectRoot:z.string(),integrationCommit:z.string().regex(/^[a-f0-9]{40}$/).optional()}) }, async ({workspace:id,expectedRevision,idempotencyKey,taskId,snapshotId,source,clientProjectRoot,integrationCommit}) => { try { requireRole("reviewer"); return result(await repository.approveGate(id,expectedRevision,idempotencyKey,taskId,snapshotId,source,clientProjectRoot,integrationCommit,identity.id)); } catch(error){return failure(error);} });
+    server.registerTool("gate_reject", { description: "Reviewer-only feedback against an unchanged task revision; returns the task to active so the loop can revise and re-present the gate.", inputSchema: z.object({...precondition,taskId:z.string(),snapshotId:z.string(),feedback:z.string().min(1).max(2000),clientProjectRoot:z.string()}) }, async ({workspace:id,expectedRevision,idempotencyKey,taskId,snapshotId,feedback,clientProjectRoot}) => { try { requireRole("reviewer"); return result(await repository.rejectGate(id,expectedRevision,idempotencyKey,taskId,snapshotId,feedback,clientProjectRoot,identity.id)); } catch(error){return failure(error);} });
   }
   return server;
 };
@@ -77,9 +81,11 @@ if (fleetEnabled && (fleetCredentials.length < 3 || fleetCredentials.some((entry
 const equalToken = (left,right) => { const a=Buffer.from(left); const b=Buffer.from(right); return a.length===b.length && timingSafeEqual(a,b); };
 const principalFor = (authorization) => fleetCredentials.find((entry) => equalToken(authorization,`Bearer ${entry.token}`));
 const app = createMcpExpressApp({ host });
+app.use((req, res, next) => { const started=Date.now(); res.on("finish", () => { const entry={ts:new Date().toISOString(),method:req.method,path:req.path,status:res.statusCode}; const principal=req.fleetPrincipal?.id; if (principal) entry.principal=principal; entry.ms=Date.now()-started; process.stderr.write(JSON.stringify(entry)+"\n"); }); next(); });
+app.get("/healthz", (req, res) => res.status(200).json({ ok: true }));
 app.use((req, res, next) => {
   if (fleetEnabled) { const principal=principalFor(req.headers.authorization ?? ""); if (!principal) return res.status(401).json({ error: "unauthorized" }); req.fleetPrincipal={id:principal.id,role:principal.role}; return next(); }
-  if (!token || req.headers.authorization === `Bearer ${token}`) return next();
+  if (!token || equalToken(req.headers.authorization ?? "", `Bearer ${token}`)) return next();
   res.status(401).json({ error: "unauthorized" });
 });
 app.post("/mcp", async (req, res) => {
@@ -88,6 +94,6 @@ app.post("/mcp", async (req, res) => {
   await server.connect(transport);
   await transport.handleRequest(req, res, req.body);
 });
-const listener = app.listen(port, host, () => console.error(`aidlc MCP state service listening at http://${host}:${port}/mcp`));
+const listener = app.listen(port, host, () => { const actual = (typeof listener.address === "function" && listener.address()) ? listener.address().port : port; console.error(`aidlc MCP state service listening at http://${host}:${actual}/mcp`); });
 const shutdown = async () => { listener.close(); await repository.close(); await coordination.close(); await fleet?.close(); };
 process.once("SIGINT", shutdown); process.once("SIGTERM", shutdown);

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

@@ -91,6 +91,27 @@ test("review snapshots require a ready wait and approval is atomic against its r
   } finally { repo.close(); }
 });
 
+test("reviewer rejection records feedback, returns the task to active, and marks the checkpoint rejected", async () => {
+  const repo = new SqliteStateRepository(":memory:");
+  try {
+    const first = await repo.apply("w", 0, "create", { type: "upsertTask", taskId: "T1", task }, "/workspace/project");
+    assert.equal(first.nextActions.T1.classification, "await_user");
+    const snapshot = await repo.putGateSnapshot("w", 1, "snapshot", "T1", "G0_confirm", "Review this intent", undefined, undefined, undefined, true);
+    assert.equal((await repo.gateCheckpoint("w", "T1")).status, "pending");
+    await assert.rejects(() => repo.rejectGate("w", 0, "stale", "T1", snapshot.id, "rewrite", "/workspace/project"), /revision conflict/);
+    const rejected = await repo.rejectGate("w", 1, "reject", "T1", snapshot.id, "Please rewrite the problem statement", "/workspace/project");
+    const after = rejected.state.tasks.T1;
+    assert.equal(after.status, "active");
+    assert.equal(after.phase, "clarify");
+    assert.equal(after.gate, "G0_confirm");
+    assert.equal(after.evidence.at(-1).kind, "diagnostic");
+    assert.match(after.evidence.at(-1).detail, /^Cancelled gate wait at G0_confirm: Please rewrite the problem statement$/);
+    assert.equal(rejected.nextActions.T1.classification, "run_phase");
+    assert.equal((await repo.gateCheckpoint("w", "T1")).status, "rejected");
+    await assert.rejects(() => repo.rejectGate("w", 2, "again", "T1", snapshot.id, "more feedback", "/workspace/project"), /stale gate snapshot/);
+  } finally { repo.close(); }
+});
+
 test("G2 snapshot binds the reviewed integration commit through approval", async () => {
   const repo=new SqliteStateRepository(":memory:");
   try {

package/dist/services/aidlc-coordination/test/server-health-auth.test.mjs

@@ -0,0 +1,67 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomBytes } from "node:crypto";
+
+const serviceRoot = join(fileURLToPath(new URL("..", import.meta.url)));
+
+test("health endpoint is public and non-fleet auth is timing-safe", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "aidlc-hz-"));
+  const db = join(dir, "state.db");
+  const token = randomBytes(16).toString("hex");
+  const env = {
+    ...process.env,
+    MCP_STATE_DATABASE: "sqlite",
+    MCP_STATE_SQLITE_PATH: db,
+    MCP_STATE_HOST: "127.0.0.1",
+    MCP_STATE_PORT: "0",
+    MCP_STATE_AUTH_TOKEN: token,
+  };
+  const child = spawn(process.execPath, [join(serviceRoot, "src", "server.mjs")], {
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  let stderr = "";
+  let port;
+  try {
+    port = await new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error("timeout waiting for listening: " + stderr)), 10000);
+      child.stderr.on("data", (chunk) => {
+        stderr += chunk.toString();
+        const match = stderr.match(/listening at http:\/\/[^:]+:(\d+)\/mcp/);
+        if (match) {
+          clearTimeout(timeout);
+          resolve(Number(match[1]));
+        }
+      });
+      child.on("exit", (code) => {
+        clearTimeout(timeout);
+        reject(new Error("server exited " + code + ": " + stderr));
+      });
+    });
+
+    const health = await fetch(`http://127.0.0.1:${port}/healthz`);
+    assert.equal(health.status, 200);
+    assert.deepEqual(await health.json(), { ok: true });
+
+    const noAuth = await fetch(`http://127.0.0.1:${port}/mcp`, { method: "POST" });
+    assert.equal(noAuth.status, 401);
+
+    const wrong = await fetch(`http://127.0.0.1:${port}/mcp`, { method: "POST", headers: { Authorization: "Bearer wrong-token" } });
+    assert.equal(wrong.status, 401);
+
+    const correct = await fetch(`http://127.0.0.1:${port}/mcp`, { method: "POST", headers: { Authorization: `Bearer ${token}` } });
+    assert.notEqual(correct.status, 401);
+
+    assert.match(stderr, /listening at http:/);
+    assert.ok(!stderr.includes(token), "stderr must not contain the token");
+  } finally {
+    child.kill();
+    await new Promise((resolve) => child.on("exit", resolve));
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/dist/src/adapters.d.ts

@@ -1,7 +1,4 @@
 import type { Adapter, AgentId } from "./model.js";
 export declare const adapters: readonly Adapter[];
 export declare const resolvedAdapters: () => readonly Adapter[];
-export declare const resolvedAdaptersForUpgrade: () => readonly Adapter[];
-export declare const installableAdapters: () => readonly Adapter[];
 export declare const findAdapter: (id: AgentId) => Adapter | undefined;
-export declare const findAdapterForUpgrade: (id: AgentId) => Adapter | undefined;

package/dist/src/adapters.js

@@ -1,22 +1,30 @@
+/**
+ * Coding-tool adapters. Each adapter describes the managed prompt blocks, config
+ * files, and skill files installed for one supported coding tool (Claude, Codex,
+ * OpenCode). The `instruction` text is shared verbatim across adapters.
+ */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { legacyManagedMarker, managedEndMarker, managedStartMarker } from "./managed-content.js";
 const hasManagedBlock = (root, path, owner) => {
     const target = join(root, path);
     if (!existsSync(target))
         return false;
     try {
         const content = readFileSync(target, "utf8");
-        return content.includes(`<!-- aidlc-installer:${owner}:start -->`) || content.includes(`<!-- aidlc-installer:${owner} -->`);
+        return content.includes(managedStartMarker(owner)) || content.includes(legacyManagedMarker(owner));
     }
     catch {
         return false;
-    }
+    } /* intentional: an unreadable prompt file is treated as not containing the block */
 };
+/** Builds a managed prompt block for one adapter-owned file. */
 const adapterFile = (owner, path, body) => ({
     path,
     owner,
-    content: `<!-- aidlc-installer:${owner}:start -->\n${body}<!-- aidlc-installer:${owner}:end -->\n`
+    content: `${managedStartMarker(owner)}\n${body}${managedEndMarker(owner)}\n`
 });
+/** Shared AI-DLC instruction text installed into each tool's primary prompt file. */
 const instruction = (agent, adapter) => [
     `# AI-DLC for ${agent}`,
     "",
@@ -100,7 +108,4 @@ export const adapters = [
     }
 ];
 export const resolvedAdapters = () => adapters;
-export const resolvedAdaptersForUpgrade = () => adapters;
-export const installableAdapters = () => adapters;
 export const findAdapter = (id) => adapters.find((adapter) => adapter.id === id);
-export const findAdapterForUpgrade = (id) => adapters.find((adapter) => adapter.id === id);

package/dist/src/cli/argv.d.ts

@@ -0,0 +1,12 @@
+export declare const usage: string;
+export declare const value: (args: string[], name: string) => string | undefined;
+export declare const flags: (args: string[]) => Set<string>;
+export declare const rootArg: (args: string[], fallback?: string) => string;
+export declare const INIT_FLAGS: Set<string>;
+export declare const UPGRADE_FLAGS: Set<string>;
+export declare const UNINSTALL_FLAGS: Set<string>;
+export declare const STATUS_FLAGS: Set<string>;
+export declare const DOCTOR_FLAGS: Set<string>;
+export declare const MCP_FLAGS: Set<string>;
+export declare const UI_FLAGS: Set<string>;
+export declare const assertKnownOptions: (args: string[], allowed: Set<string>) => void;

package/dist/src/cli/argv.js

@@ -0,0 +1,62 @@
+/**
+ * Pure argv layer: usage text, value/flag parsing, and per-command option
+ * allowlists. No prompting, no side effects.
+ */
+import { LOOP_PROVIDERS } from "../model.js";
+export const usage = `Usage:
+  npx @felixdotgo/aidlc-kit init [path] [--agent <name[,name]> | --all] [--loop-mode off|local|fleet] [--loop-lead ${LOOP_PROVIDERS.join("|")}] [--loop-workers <id=provider,...>] [--yes] [--dry-run] [--force]
+  npx @felixdotgo/aidlc-kit upgrade [path] [--loop-mode off|local|fleet] [--loop-lead ${LOOP_PROVIDERS.join("|")}] [--loop-workers <id=provider,...>] [--dry-run]
+  npx @felixdotgo/aidlc-kit uninstall [path] [--yes] [--dry-run]
+  npx @felixdotgo/aidlc-kit status [path] [--json]
+  npx @felixdotgo/aidlc-kit doctor [path] [--strict] [--json]
+  npx @felixdotgo/aidlc-kit profile validate [path]
+  npx @felixdotgo/aidlc-kit loop start|status|intake [--task-id ID] [--title TITLE] [--root PATH] [--mode local|fleet]
+  npx @felixdotgo/aidlc-kit loop worker-image [--provider ${LOOP_PROVIDERS.join("|")}] [--tag TAG] [--root PATH]
+  npx @felixdotgo/aidlc-kit ui [path] [--port 4173] [--host 127.0.0.1] [--open] [--token-file PATH] [--reviewer-token-file PATH]
+  npx @felixdotgo/aidlc-kit mcp setup [path] [--dry-run] [--yes] [--storage sqlite|postgres] [--deployment docker|remote] [--bind localhost|network] [--workspace <id>] [--poll-ms <n>] [--token-env <name>] [--providers <p,...>] [--enable]
+  npx @felixdotgo/aidlc-kit version
+  Global options: --help, --version, -v`;
+export const value = (args, name) => {
+    const index = args.indexOf(name);
+    if (index < 0)
+        return undefined;
+    const next = args[index + 1];
+    if (next === undefined || next.startsWith("--"))
+        throw new Error(`${name} requires a value`);
+    return next;
+};
+export const flags = (args) => new Set(args.filter((item) => item.startsWith("--")));
+const valueFlags = new Set(["--agent", "--storage", "--deployment", "--bind", "--workspace", "--poll-ms", "--token-env", "--providers", "--loop-mode", "--loop-lead", "--loop-workers", "--port", "--host", "--token-file", "--reviewer-token-file"]);
+const COMMAND_KEYWORDS = ["init", "upgrade", "uninstall", "status", "doctor", "validate", "run", "list"];
+const positional = (args) => {
+    const result = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg !== undefined && valueFlags.has(arg)) {
+            index += 1;
+            continue;
+        }
+        if (arg !== undefined && !arg.startsWith("--"))
+            result.push(arg);
+    }
+    return result;
+};
+export const rootArg = (args, fallback = ".") => positional(args).find((item) => !COMMAND_KEYWORDS.includes(item)) ?? fallback;
+export const INIT_FLAGS = new Set(["--agent", "--all", "--loop-mode", "--loop-lead", "--loop-workers", "--yes", "--dry-run", "--force"]);
+export const UPGRADE_FLAGS = new Set(["--loop-mode", "--loop-lead", "--loop-workers", "--dry-run"]);
+export const UNINSTALL_FLAGS = new Set(["--yes", "--dry-run"]);
+export const STATUS_FLAGS = new Set(["--json"]);
+export const DOCTOR_FLAGS = new Set(["--strict", "--json"]);
+export const MCP_FLAGS = new Set(["--dry-run", "--yes", "--storage", "--deployment", "--bind", "--workspace", "--poll-ms", "--token-env", "--providers", "--enable"]);
+export const UI_FLAGS = new Set(["--port", "--host", "--open", "--token-file", "--reviewer-token-file"]);
+export const assertKnownOptions = (args, allowed) => {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === undefined || !arg.startsWith("--"))
+            continue;
+        if (!allowed.has(arg))
+            throw new Error(`Unknown option: ${arg}`);
+        if (valueFlags.has(arg))
+            index += 1;
+    }
+};

package/dist/src/cli/commands.d.ts

@@ -0,0 +1,8 @@
+export declare const runLoopCommand: (args: string[]) => Promise<void>;
+export declare const runUi: (args: string[]) => Promise<void>;
+export declare const runMcpSetup: (args: string[]) => Promise<void>;
+export declare const runMcp: (args: string[]) => Promise<void>;
+export declare const runStatus: (args: string[]) => void;
+export declare const runDoctor: (args: string[]) => void;
+export declare const runProfileValidate: (args: string[]) => void;
+export declare const runProfile: (args: string[]) => void;

package/dist/src/cli/commands.js

@@ -0,0 +1,129 @@
+/**
+ * Command handlers for loop, MCP setup, status, doctor, and profile validate.
+ * Interactive prompting stays in ./prompt.ts and is invoked from here after
+ * argv parsing.
+ */
+import { spawn } from "node:child_process";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { doctor, doctorData, status, statusData } from "../installer.js";
+import { applyMcpSetup, planMcpSetup } from "../mcp-setup.js";
+import { loadProjectConfig, resolveProfiles } from "../profiles.js";
+import { openBrowser, readUiTokenFile, startUiServer } from "../task-ui.js";
+import { assertKnownOptions, DOCTOR_FLAGS, flags, MCP_FLAGS, rootArg, STATUS_FLAGS, UI_FLAGS, value } from "./argv.js";
+import { confirmGeneral, mcpSetupSelections } from "./prompt.js";
+export const runLoopCommand = async (args) => {
+    const action = args[0] ?? "";
+    if (!["start", "status", "resume", "intake", "worker-image"].includes(action))
+        throw new Error("Expected loop start, status, intake, or worker-image");
+    const parsed = new Map();
+    for (let index = 1; index < args.length; index += 2) {
+        const key = args[index];
+        const entry = args[index + 1];
+        if (key === undefined || !["--task-id", "--title", "--root", "--mode", "--provider", "--tag"].includes(key) || !entry || entry.startsWith("--") || parsed.has(key))
+            throw new Error("Invalid or duplicate loop option");
+        parsed.set(key, entry);
+    }
+    const root = resolve(parsed.get("--root") ?? ".");
+    const script = join(root, ".agents", "aidlc", "scripts", "loop-entry.mjs");
+    const child = spawn(process.execPath, [script, action, parsed.get("--task-id") ?? "", root, parsed.get("--mode") ?? "", parsed.get("--provider") ?? "", parsed.get("--tag") ?? "", parsed.get("--title") ?? ""], { stdio: "inherit" });
+    // Stay alive while the child runs so its own staged shutdown (stop after the
+    // current turn → cancel the turn → exit) stays reachable. A terminal Ctrl-C
+    // already reaches the child through the process group, so SIGINT is only
+    // swallowed here (forwarding it would count twice); SIGTERM sent to this
+    // wrapper alone (e.g. `kill <pid>`) is forwarded instead of orphaning the child.
+    const onInterrupt = () => { };
+    const onTerminate = () => { if (child.exitCode === null && child.signalCode === null)
+        child.kill("SIGTERM"); };
+    process.on("SIGINT", onInterrupt);
+    process.on("SIGTERM", onTerminate);
+    try {
+        const { code, signal } = await new Promise((resolveExit, rejectExit) => {
+            child.once("error", rejectExit);
+            child.once("exit", (exitCode, exitSignal) => resolveExit({ code: exitCode, signal: exitSignal }));
+        });
+        if (code !== 0)
+            process.exitCode = code ?? (signal === "SIGINT" ? 130 : 1);
+    }
+    finally {
+        process.off("SIGINT", onInterrupt);
+        process.off("SIGTERM", onTerminate);
+    }
+};
+export const runUi = async (args) => {
+    assertKnownOptions(args, UI_FLAGS);
+    const root = resolve(rootArg(args));
+    const port = Number(value(args, "--port") ?? 4173);
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error("--port must be an integer between 1 and 65535");
+    const host = value(args, "--host") ?? "127.0.0.1";
+    const tokenFile = value(args, "--token-file");
+    const reviewerFile = value(args, "--reviewer-token-file");
+    const token = tokenFile ? readUiTokenFile(root, tokenFile, { create: true }) : undefined;
+    const reviewerToken = reviewerFile ? readUiTokenFile(root, reviewerFile, { create: false }) : undefined;
+    const { server, port: boundPort, token: sessionToken } = await startUiServer({ root, host, port, ...(token ? { token } : {}), ...(reviewerToken ? { reviewerToken } : {}) });
+    const base = `http://${host.includes(":") ? `[${host}]` : host}:${boundPort}`;
+    const loginUrl = `${base}/#token=${encodeURIComponent(sessionToken)}`;
+    console.log(`Loop (AI-DLC UI) listening on ${base} (Ctrl-C to stop)`);
+    console.log(`Open (signs this browser in for loop actions and gate approval): ${loginUrl}`);
+    if (flags(args).has("--open"))
+        openBrowser(loginUrl);
+    await new Promise((resolve) => {
+        const close = () => { server.close(() => resolve()); };
+        process.once("SIGINT", close);
+        process.once("SIGTERM", close);
+    });
+};
+const mcpSetupOptions = async (args) => {
+    const selected = await mcpSetupSelections(args);
+    return { root: rootArg(args), template: join(fileURLToPath(new URL("../../services/aidlc-coordination", import.meta.url))), dryRun: flags(args).has("--dry-run"), deployment: selected.deployment, storage: selected.storage, bind: selected.bind, workspace: selected.workspace, pollMs: selected.pollMs, tokenEnv: selected.tokenEnv, providers: selected.providers, enable: flags(args).has("--enable") };
+};
+export const runMcpSetup = async (args) => {
+    assertKnownOptions(args.slice(1), MCP_FLAGS);
+    const options = await mcpSetupOptions(args.slice(1));
+    const plan = planMcpSetup(options);
+    console.log(`◆ MCP SETUP preview — ${options.dryRun ? "no files will be written" : "review before applying"}`);
+    console.log(JSON.stringify(plan, null, 2));
+    if (options.dryRun)
+        return;
+    if (!await confirmGeneral({ dryRun: options.dryRun, yes: flags(args.slice(1)).has("--yes") }, "Apply MCP setup"))
+        return;
+    applyMcpSetup(options);
+    console.log(`MCP setup written to ${plan.target}. MCP remains ${options.enable ? "enabled" : "disabled"}; start Docker explicitly with docker compose --env-file .env -f ${join(plan.target, "compose.yaml")} up -d.`);
+};
+export const runMcp = async (args) => { if (args[0] !== "setup")
+    throw new Error("Unknown command: mcp"); return runMcpSetup(args); };
+export const runStatus = (args) => {
+    assertKnownOptions(args, STATUS_FLAGS);
+    const root = rootArg(args);
+    if (flags(args).has("--json"))
+        console.log(JSON.stringify(statusData(root)));
+    else
+        console.log(status(root));
+};
+export const runDoctor = (args) => {
+    assertKnownOptions(args, DOCTOR_FLAGS);
+    const root = rootArg(args);
+    const strict = flags(args).has("--strict");
+    if (flags(args).has("--json")) {
+        const data = doctorData(root, strict);
+        console.log(JSON.stringify(data));
+        if (data.level === "error")
+            process.exitCode = 1;
+    }
+    else {
+        const result = doctor(root, strict);
+        console.log(result);
+        if (result.startsWith("ERROR:"))
+            process.exitCode = 1;
+    }
+};
+export const runProfileValidate = (args) => {
+    assertKnownOptions(args.slice(1), new Set());
+    const root = rootArg(args.slice(1));
+    const config = loadProjectConfig(root);
+    const profiles = resolveProfiles(root, config.extends);
+    console.log(`OK: ${profiles.map((item) => item.id).join(" → ")}`);
+};
+export const runProfile = (args) => { if (args[0] !== "validate")
+    throw new Error("Unknown command: profile"); return runProfileValidate(args); };

package/dist/src/cli/options.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Pure argv→options builders: init options, loop flag reads, worker mapping
+ * parsing, and the argv-provided part of MCP setup selections. Prompting for
+ * anything still missing happens in ./prompt.ts.
+ */
+import type { InitOptions } from "../model.js";
+import type { McpSetupOptions } from "../mcp-setup.js";
+export declare const initOptions: (args: string[]) => InitOptions;
+export declare const loopSelection: (args: string[]) => {
+    mode?: string;
+    lead?: string;
+    workers?: string;
+};
+export declare const parseWorkerMapping: (rawWorkers: string) => Record<string, string>;
+/** Argv-provided MCP selections: connection choices stay optional until prompted; the rest always carry defaults. */
+export type McpArgSelections = {
+    deployment?: McpSetupOptions["deployment"];
+    storage?: McpSetupOptions["storage"];
+    bind?: McpSetupOptions["bind"];
+    workspace?: string;
+    pollMs: number;
+    tokenEnv: string;
+    providers: string[];
+};
+export declare const mcpArgSelections: (args: string[]) => McpArgSelections;

package/dist/src/cli/options.js

@@ -0,0 +1,32 @@
+import { flags, rootArg, value } from "./argv.js";
+export const initOptions = (args) => ({
+    root: rootArg(args),
+    agents: (value(args, "--agent") ?? "").split(",").filter(Boolean),
+    all: flags(args).has("--all"),
+    dryRun: flags(args).has("--dry-run"),
+    yes: flags(args).has("--yes"),
+    force: flags(args).has("--force")
+});
+export const loopSelection = (args) => ({ mode: value(args, "--loop-mode"), lead: value(args, "--loop-lead"), workers: value(args, "--loop-workers") });
+export const parseWorkerMapping = (rawWorkers) => {
+    const workers = Object.create(null);
+    for (const entry of rawWorkers.split(",")) {
+        const parts = entry.split("=");
+        if (parts.length !== 2 || !parts[0] || !parts[1] || Object.hasOwn(workers, parts[0]))
+            throw new Error("Invalid or duplicate loop worker mapping");
+        workers[parts[0]] = parts[1];
+    }
+    return workers;
+};
+export const mcpArgSelections = (args) => {
+    const selected = {
+        deployment: value(args, "--deployment"),
+        storage: value(args, "--storage"),
+        bind: value(args, "--bind"),
+        workspace: value(args, "--workspace"),
+        pollMs: Number(value(args, "--poll-ms") ?? 30_000),
+        tokenEnv: value(args, "--token-env") ?? "AIDLC_MCP_TOKEN",
+        providers: (value(args, "--providers") ?? "").split(",").filter(Boolean)
+    };
+    return selected;
+};

package/dist/src/cli/prompt.d.ts

@@ -0,0 +1,9 @@
+import type { LoopConfig } from "../model.js";
+import type { McpSetupOptions } from "../mcp-setup.js";
+export declare const interactive: () => boolean;
+export declare const chooseLoop: (args: string[], upgrade: boolean) => Promise<LoopConfig | undefined>;
+export declare const mcpSetupSelections: (args: string[]) => Promise<Partial<Omit<McpSetupOptions, "root" | "template" | "dryRun" | "enable">>>;
+export declare const confirmGeneral: (options: {
+    dryRun: boolean;
+    yes: boolean;
+}, operation: string) => Promise<boolean>;