factory-ai 1.4.0 → 1.5.0

package/src/telemetry.js

@@ -0,0 +1,173 @@
+import { randomBytes } from "node:crypto";
+
+export const TELEMETRY_SCHEMA_VERSION = "factory.telemetry.v1";
+
+const operationNames = Object.freeze({
+  model: "gen_ai.chat",
+  tool: "gen_ai.execute_tool",
+  queue: "factory.queue",
+  checkpoint: "factory.checkpoint",
+  scanner: "factory.scanner",
+  watchdog: "factory.watchdog",
+  release: "factory.release",
+});
+
+const aliases = Object.freeze({
+  objectiveId: "factory.objective.id",
+  taskId: "factory.task.id",
+  role: "factory.agent.role",
+  modelRoute: "gen_ai.request.model",
+  attempt: "factory.attempt",
+  toolCallId: "gen_ai.tool.call.id",
+  messageId: "messaging.message.id",
+  inputTokens: "gen_ai.usage.input_tokens",
+  outputTokens: "gen_ai.usage.output_tokens",
+  cacheReadInputTokens: "gen_ai.usage.cache_read.input_tokens",
+  durationMs: "factory.duration_ms",
+  retryCount: "factory.retry.count",
+  cacheHit: "factory.cache.hit",
+  statusClass: "factory.status.class",
+  errorCode: "error.type",
+});
+
+const identifier = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/;
+const modelRoute = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}\/[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
+const providerName = /^[a-z][a-z0-9._-]{0,63}$/;
+const errorCode = /^[a-z][a-z0-9_.-]{0,63}$/;
+const statusClasses = new Set(["ok", "error", "cancelled", "timeout", "retry"]);
+const genAiOperations = Object.freeze({ model: "chat", tool: "execute_tool" });
+
+function nonNegativeInteger(value) {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+
+function nonNegativeNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+const validators = Object.freeze({
+  "factory.objective.id": (value) => typeof value === "string" && identifier.test(value),
+  "factory.task.id": (value) => typeof value === "string" && identifier.test(value),
+  "factory.agent.role": (value) => typeof value === "string" && identifier.test(value),
+  "gen_ai.request.model": (value) => typeof value === "string" && modelRoute.test(value) && !value.includes("://"),
+  "factory.attempt": nonNegativeInteger,
+  "gen_ai.tool.call.id": (value) => typeof value === "string" && identifier.test(value),
+  "messaging.message.id": (value) => typeof value === "string" && identifier.test(value),
+  "gen_ai.provider.name": (value) => typeof value === "string" && providerName.test(value),
+  "gen_ai.operation.name": (value) => value === "chat" || value === "execute_tool",
+  "gen_ai.usage.input_tokens": nonNegativeInteger,
+  "gen_ai.usage.output_tokens": nonNegativeInteger,
+  "gen_ai.usage.cache_read.input_tokens": nonNegativeInteger,
+  "factory.duration_ms": nonNegativeNumber,
+  "factory.retry.count": nonNegativeInteger,
+  "factory.cache.hit": (value) => typeof value === "boolean",
+  "factory.status.class": (value) => statusClasses.has(value),
+  "error.type": (value) => typeof value === "string" && errorCode.test(value),
+});
+
+export function safeAttributes(input = {}) {
+  const result = {};
+  if (!input || typeof input !== "object" || Array.isArray(input)) return result;
+  for (const [inputName, value] of Object.entries(input)) {
+    const name = aliases[inputName] ?? inputName;
+    if (validators[name]?.(value)) result[name] = value;
+  }
+  return result;
+}
+
+function operationName(kind) {
+  const name = operationNames[kind];
+  if (!name) throw new Error(`Unknown telemetry operation: ${kind}`);
+  return name;
+}
+
+function validHexId(value, length) {
+  return typeof value === "string" && new RegExp(`^[a-f0-9]{${length}}$`).test(value);
+}
+
+export function createTelemetry(options = {}) {
+  const {
+    exporter,
+    fallback,
+    now = Date.now,
+    createTraceId = () => randomBytes(16).toString("hex"),
+    createSpanId = () => randomBytes(8).toString("hex"),
+  } = options;
+
+  function ids(context) {
+    const traceId = validHexId(context?.traceId, 32) ? context.traceId : createTraceId();
+    const spanId = createSpanId();
+    if (!validHexId(traceId, 32) || !validHexId(spanId, 16)) throw new Error("Telemetry ID generators must return lowercase hexadecimal IDs");
+    return {
+      traceId,
+      spanId,
+      ...(validHexId(context?.parentSpanId, 16) ? { parentSpanId: context.parentSpanId } : {}),
+    };
+  }
+
+  async function deliver(record) {
+    if (typeof exporter === "function") {
+      try {
+        await exporter(record);
+        return record;
+      } catch {}
+    }
+    if (typeof fallback === "function") {
+      try { await fallback(record); } catch {}
+    }
+    return record;
+  }
+
+  function baseRecord(recordType, kind, context) {
+    const timestamp = new Date(now()).toISOString();
+    return {
+      schemaVersion: TELEMETRY_SCHEMA_VERSION,
+      recordType,
+      name: operationName(kind),
+      timestamp,
+      ...ids(context),
+    };
+  }
+
+  function startSpan(kind, context = {}, attributes = {}) {
+    const startedAt = now();
+    const base = baseRecord("span", kind, context);
+    const initialAttributes = safeAttributes({
+      ...context,
+      ...attributes,
+      ...(genAiOperations[kind] ? { "gen_ai.operation.name": genAiOperations[kind] } : {}),
+    });
+    let completion;
+    return {
+      traceId: base.traceId,
+      spanId: base.spanId,
+      end(endAttributes = {}) {
+        if (!completion) {
+          const measured = endAttributes.durationMs === undefined
+            ? { durationMs: Math.max(0, now() - startedAt), ...endAttributes }
+            : endAttributes;
+          const record = {
+            ...base,
+            attributes: { ...initialAttributes, ...safeAttributes(measured) },
+          };
+          completion = deliver(record);
+        }
+        return completion;
+      },
+    };
+  }
+
+  function emitEvent(kind, context = {}, attributes = {}) {
+    const record = {
+      ...baseRecord("event", kind, context),
+      attributes: safeAttributes({
+        ...context,
+        ...attributes,
+        ...(genAiOperations[kind] ? { "gen_ai.operation.name": genAiOperations[kind] } : {}),
+      }),
+    };
+    return deliver(record);
+  }
+
+  return Object.freeze({ startSpan, emitEvent });
+}

package/src/tui.js

@@ -13,7 +13,7 @@ const colors = { bg: "#0d0f12", panel: "#15191f", border: "#303743", text: "#d9e
 blessed.box({ parent: screen, top: 0, left: 0, width: "100%", height: 3, tags: true, style: { bg: colors.panel, fg: colors.text }, content: `  {bold}{#78dba9-fg}${factoryName.toUpperCase()}{/}  {/bold}  ${factoryPurpose}` });
 const menu = blessed.list({ parent: screen, top: 3, left: 0, width: 23, bottom: 2, border: { type: "line" }, label: " Navigate ", keys: true, mouse: true, vi: true, items: ["Overview", "Objectives", "Agents", "Secrets", "Capabilities", "Logs", "Settings"], style: { bg: colors.panel, fg: colors.text, border: { fg: colors.border }, selected: { bg: colors.accent, fg: "#07130d", bold: true }, item: { fg: colors.text } } });
 const main = blessed.box({ parent: screen, top: 3, left: 23, right: 0, bottom: 2, border: { type: "line" }, label: " Overview ", tags: true, scrollable: true, alwaysScroll: true, keys: true, mouse: true, vi: true, scrollbar: { ch: "▐", style: { fg: colors.accent } }, padding: { left: 2, right: 2 }, style: { bg: colors.bg, fg: colors.text, border: { fg: colors.border } } });
-const footer = blessed.box({ parent: screen, bottom: 0, left: 0, width: "100%", height: 2, tags: true, style: { bg: colors.panel, fg: colors.muted }, content: "  {bold}n{/} new objective   {bold}r{/} refresh   {bold}a{/} add secret   {bold}p/u{/} pause/resume   {bold}q{/} quit" });
+const footer = blessed.box({ parent: screen, bottom: 0, left: 0, width: "100%", height: 2, tags: true, style: { bg: colors.panel, fg: colors.muted }, content: "  {bold}n{/} new   {bold}r{/} refresh   {bold}a{/} secret   {bold}y/x{/} approve/deny   {bold}p/u{/} pause/resume   {bold}q{/} quit" });
 
 let dashboard;
 let capabilities;
@@ -22,6 +22,11 @@ let logs;
 let section = "Overview";
 let refreshing = false;
 
+function safe(value) {
+  const text = String(value ?? "").replaceAll(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "");
+  return blessed.escape ? blessed.escape(text) : text.replaceAll("{", "\\{").replaceAll("}", "\\}");
+}
+
 function status(message, color = colors.muted) {
   footer.setContent(`  {${color}-fg}${message}{/}   {bold}n{/} new   {bold}r{/} refresh   {bold}q{/} quit`);
   screen.render();
@@ -39,20 +44,20 @@ function renderOverview() {
   const inputTokens = modelUsage.reduce((sum, item) => sum + item.inputTokens, 0);
   const cachedTokens = modelUsage.reduce((sum, item) => sum + item.cachedInputTokens, 0);
   const outputTokens = modelUsage.reduce((sum, item) => sum + item.outputTokens, 0);
-  const recent = (dashboard?.objectives ?? []).slice(-8).reverse().map((objective) => `  ${badge(objective.status.padEnd(9))}  {bold}${objective.objective}{/}\n             ${objective.repository ?? ""}`).join("\n\n");
+  const recent = (dashboard?.objectives ?? []).slice(-8).reverse().map((objective) => `  ${badge(objective.status.padEnd(9))}  {bold}${safe(objective.objective)}{/}\n             ${safe(objective.repository ?? "")}`).join("\n\n");
   main.setContent(`{bold}System{/}\n\n  Queue       {#78dba9-fg}${dashboard?.queue?.active ?? 0}{/}\n  Dead letter ${dashboard?.queue?.deadLetter ?? 0}\n  Azure MTD   {#efc46b-fg}${cost}{/}\n  Objectives  ${counts}\n  Tokens      ${inputTokens} in · ${cachedTokens} cached · ${outputTokens} out\n\n{bold}Recent objectives{/}\n\n${recent || "  No objectives yet."}`);
 }
 
 function renderObjectives() {
   main.setContent((dashboard?.objectives ?? []).slice().reverse().map((objective) => {
-    const tasks = objective.tasks.map((task) => `    ${badge(task.state.padEnd(9))} ${task.role.padEnd(9)} {#7f8b99-fg}${task.model}{/}\n               ${task.title}`).join("\n");
-    return `${badge(objective.status)} {bold}${objective.objective}{/}\n  ${objective.id}\n${tasks}${objective.pullRequest ? `\n  PR ${objective.pullRequest}` : ""}${objective.blocker ? `\n  {#ef7d7d-fg}${objective.blocker}{/}` : ""}`;
+    const tasks = objective.tasks.map((task) => `    ${badge((task.stale ? "stale" : task.state).padEnd(9))} ${task.role.padEnd(9)} {#7f8b99-fg}${safe(task.model)}{/}\n               ${safe(task.title)}${task.activity ? ` · ${safe(task.activity.type)}${task.activity.tool ? ` ${safe(task.activity.tool)}` : ""}` : ""}`).join("\n");
+    return `${badge(objective.status)} {bold}${safe(objective.objective)}{/}\n  ${safe(objective.id)}\n${tasks}${objective.pullRequest ? `\n  PR ${safe(objective.pullRequest)}` : ""}${objective.blocker ? `\n  {#ef7d7d-fg}${safe(objective.blocker)}{/}` : ""}`;
   }).join("\n\n────────────────────────────────────────────────────────\n\n") || "No objectives." );
 }
 
 function renderAgents() {
   const agents = (dashboard?.objectives ?? []).flatMap((objective) => objective.tasks.map((task) => ({ objective: objective.objective, ...task }))).filter((task) => !["succeeded"].includes(task.state));
-  main.setContent(agents.map((task) => `${badge(task.state.padEnd(9))} {bold}${task.role}{/}  ${task.model}\n  ${task.title}\n  {#7f8b99-fg}${task.objective}{/}`).join("\n\n") || "No active agents.");
+  main.setContent(agents.map((task) => `${badge((task.stale ? "stale" : task.state).padEnd(9))} {bold}${safe(task.role)}{/}  ${safe(task.model)}\n  ${safe(task.title)}\n  ${task.activity ? `${safe(task.activity.phase ?? task.activity.type)}${task.activity.tool ? ` · ${safe(task.activity.tool)}` : ""} · ${Math.round(task.activityAgeSeconds ?? 0)}s ago${task.retries ? ` · ${task.retries} retries` : ""}` : "No activity event yet"}${task.lastError ? `\n  {#ef7d7d-fg}${safe(task.lastError)}{/}` : ""}\n  {#7f8b99-fg}${safe(task.objective)}{/}`).join("\n\n") || "No active agents.");
 }
 
 function renderSecrets() {
@@ -77,7 +82,7 @@ function render() {
   else if (section === "Agents") renderAgents();
   else if (section === "Secrets") renderSecrets();
   else if (section === "Capabilities") renderCapabilities();
-  else if (section === "Logs") main.setContent(logs ?? "Loading logs...");
+  else if (section === "Logs") main.setContent(safe(logs ?? "Loading logs..."));
   else renderSettings();
   main.setScrollPerc(0);
   screen.render();
@@ -90,7 +95,7 @@ async function refresh() {
   try {
     dashboard = await operator.dashboard();
     if (section === "Capabilities" && !capabilities) capabilities = await operator.capabilities();
-    if (section === "Secrets") secrets = await operator.listSecrets();
+    if (section === "Secrets") secrets = dashboard?.secrets ?? await operator.listSecrets();
     if (section === "Logs") logs = await operator.logs();
     render();
     status(`Updated ${new Date().toLocaleTimeString()}`);
@@ -123,7 +128,19 @@ async function addSecret() {
   const value = await ask("Secret value", { secret: true });
   if (!value) return;
   status("Storing secret...");
-  try { await operator.setSecret(name, value); secrets = await operator.listSecrets(); renderSecrets(); status(`Stored ${name}`, colors.accent); } catch (error) { status(error.message, colors.danger); }
+  try {
+    await operator.setSecret(name, value);
+    secrets = [...(secrets ?? []).filter((item) => item.name !== name), { name, updated: new Date().toISOString() }].sort((left, right) => left.name.localeCompare(right.name));
+    renderSecrets();
+    status(`Stored ${name}`, colors.accent);
+  } catch (error) { status(error.message, colors.danger); }
+}
+
+async function decideApproval(decision) {
+  const objectiveId = await ask("Objective ID"); if (!objectiveId) return;
+  const approvalId = await ask("Approval ID"); if (!approvalId) return;
+  const reason = await ask(`${decision === "approved" ? "Approval" : "Denial"} reason`); if (!reason) return;
+  try { await operator.approval({ objectiveId, approvalId, decision, reason }); status(`Approval ${decision}`, decision === "approved" ? colors.accent : colors.danger); await refresh(); } catch (error) { status(error.message, colors.danger); }
 }
 
 menu.on("select", async (_, index) => { section = menu.getItem(index).getText(); render(); await refresh(); menu.focus(); });
@@ -131,6 +148,8 @@ screen.key(["q", "C-c"], () => process.exit(0));
 screen.key("r", refresh);
 screen.key("n", submitObjective);
 screen.key("a", addSecret);
+screen.key("y", () => decideApproval("approved"));
+screen.key("x", () => decideApproval("denied"));
 screen.key("p", async () => { status("Pausing workers..."); try { await operator.control("pause"); status("Workers paused", colors.warn); } catch (error) { status(error.message, colors.danger); } });
 screen.key("u", async () => { status("Resuming workers..."); try { await operator.control("resume"); status("Workers active", colors.accent); } catch (error) { status(error.message, colors.danger); } });
 screen.key("tab", () => menu.focus());

package/src/validation.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { ROLES } from "./routing.js";
+import { approvalPolicies } from "./approval-policy.js";
 
 const identifier = z.string().min(1).max(64).regex(/^[A-Za-z0-9][A-Za-z0-9_-]*$/);
 const repository = z.string().url().max(2048).refine((value) => {
@@ -48,11 +49,11 @@ const taskResultSchema = z.object({
   }).optional(),
 }).strict();
 
-export const workMessageSchema = z.object({
-  type: z.literal("task"),
-  objectiveId: identifier,
-  task: taskSchema,
-}).strict();
+const scannerEvidenceSchema = z.array(z.object({
+  scanner: z.string().min(1).max(100),
+  status: z.enum(["passed", "findings", "error"]),
+  output: z.string().max(6000),
+}).strict()).max(20);
 
 const resultMessageSchema = taskResultSchema.extend({
   type: z.literal("result"),
@@ -61,6 +62,33 @@ const resultMessageSchema = taskResultSchema.extend({
   status: z.literal("succeeded"),
   commit: z.string().regex(/^[0-9a-f]{40,64}$/),
   branch: z.string().min(1).max(255).regex(/^[A-Za-z0-9][A-Za-z0-9._/-]*$/),
+  scannerEvidence: scannerEvidenceSchema.optional(),
+}).strict();
+
+const approvalRequestMessageSchema = z.object({
+  type: z.literal("approval_request"),
+  objectiveId: identifier,
+  approvalId: identifier,
+  policy: z.enum(approvalPolicies),
+  reason: z.string().trim().min(1).max(1000),
+  actor: z.string().trim().min(1).max(200),
+  requestedAt: z.string().datetime(),
+  expiresAt: z.string().datetime(),
+  checkpoint: z.string().min(1).max(500).optional(),
+}).strict().refine((value) => Date.parse(value.expiresAt) > Date.parse(value.requestedAt), {
+  message: "Approval expiration must follow its request time",
+  path: ["expiresAt"],
+});
+
+const approvalDecisionMessageSchema = z.object({
+  type: z.literal("approval_decision"),
+  objectiveId: identifier,
+  approvalId: identifier,
+  decision: z.enum(["approved", "denied", "expired"]),
+  actor: z.string().trim().min(1).max(200),
+  reason: z.string().trim().min(1).max(1000),
+  decidedAt: z.string().datetime(),
+  messageId: identifier,
 }).strict();
 
 export function parseObjective(value) {
@@ -71,10 +99,6 @@ export function parsePlan(value) {
   return planSchema.parse(value);
 }
 
-export function parseWorkMessage(value) {
-  return workMessageSchema.parse(value);
-}
-
 export function parseTaskResult(value) {
   return taskResultSchema.parse(value);
 }
@@ -82,3 +106,11 @@ export function parseTaskResult(value) {
 export function parseResultMessage(value) {
   return resultMessageSchema.parse(value);
 }
+
+export function parseApprovalRequestMessage(value) {
+  return approvalRequestMessageSchema.parse(value);
+}
+
+export function parseApprovalDecisionMessage(value) {
+  return approvalDecisionMessageSchema.parse(value);
+}

package/src/watchdog.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { pathToFileURL } from "node:url";
+import { ServiceBusClient } from "@azure/service-bus";
+import { DefaultAzureCredential } from "@azure/identity";
+import { loadConfig } from "./config.js";
+import { loadLocalState } from "./dashboard.js";
+import { sendMessage } from "./bus.js";
+import { run } from "./process.js";
+import { ActivityStore } from "./activity.js";
+import { objectiveIsTerminal } from "./objective-status.js";
+
+const TERMINAL = new Set(["complete", "failed", "blocked", "cancelled", "denied", "expired"]);
+
+export function findStaleAgents(states, now = new Date(), staleSeconds = 900) {
+  const stale = [];
+  for (const state of states) {
+    if (TERMINAL.has(state.status)) continue;
+    const tasks = state.tasks?.length ? state.tasks : state.status === "planning" ? [{ id: "planner0", role: "planner" }] : [];
+    for (const task of tasks) {
+      if (state.results?.[task.id]?.status !== "queued" && task.id !== "planner0") continue;
+      const occurredAt = state.activity?.[task.id]?.occurredAt ?? state.results?.[task.id]?.queuedAt ?? (task.id === "planner0" ? state.createdAt : undefined);
+      if (!occurredAt || now.getTime() - new Date(occurredAt).getTime() <= staleSeconds * 1000) continue;
+      stale.push({ objectiveId: state.objective.id, taskId: task.id, role: task.role, occurredAt });
+    }
+  }
+  return stale;
+}
+
+async function main() {
+  const config = loadConfig();
+  const { states } = await loadLocalState(config.stateDir);
+  const stale = findStaleAgents(states, new Date(), Number(process.env.FACTORY_WATCHDOG_STALE_SECONDS ?? 900));
+  if (stale.length === 0) return;
+  const client = new ServiceBusClient(config.serviceBusFqdn, new DefaultAzureCredential());
+  const sender = client.createSender(config.controlQueue);
+  const activityStore = new ActivityStore(config.stateDir);
+  try {
+    for (const item of stale) {
+      await activityStore.withTaskLock(item.objectiveId, item.taskId, async () => {
+        const latest = await activityStore.latestTask(item.objectiveId, item.taskId);
+        if (await objectiveIsTerminal(config.stateDir, item.objectiveId)) return;
+        if (latest?.occurredAt && latest.occurredAt !== item.occurredAt) return;
+        await sendMessage(sender, {
+          type: "failure_result",
+          objectiveId: item.objectiveId,
+          taskId: item.taskId,
+          error: `Watchdog stopped ${item.role} after no heartbeat since ${item.occurredAt}`,
+        }, `watchdog:${item.objectiveId}:${item.taskId}:${item.occurredAt}`, item.objectiveId);
+        const container = `factory-ai-${item.objectiveId}-${item.taskId}`.toLowerCase().replaceAll(/[^a-z0-9_.-]/g, "-").slice(0, 63);
+        await run("docker", ["rm", "--force", container], { allowExitCodes: [0, 1], timeoutMs: 30_000 });
+      });
+    }
+  } finally {
+    await sender.close();
+    await client.close();
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) main().catch((error) => {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+});

package/src/worker.js

@@ -10,19 +10,43 @@ import { sendMessage } from "./bus.js";
 import { ContainerAgentRunner } from "./container-runner.js";
 import { ScannerSuite } from "./scanner-suite.js";
 import { LocalRetriever } from "./retriever.js";
+import { ActivityStore } from "./activity.js";
+import { objectiveIsTerminal } from "./objective-status.js";
+import { evaluateApprovalPolicy } from "./approval-policy.js";
 
 process.title = "factory-ai-worker";
 const config = loadConfig();
 Object.assign(process.env, await loadRuntimeSecrets(config));
 await run("gh", ["auth", "setup-git"], { timeoutMs: 60_000 });
 const bus = createBus(config, config.agentQueue, config.controlQueue);
-const sendControl = (message) => sendMessage(bus.sender, message, `${message.objectiveId}:${message.type}:${message.taskId ?? "plan"}:v1`, message.objectiveId);
+const sendControl = (message) => sendMessage(bus.sender, message, `${message.objectiveId}:${message.type}:${message.approvalId ?? message.taskId ?? "plan"}:v1`, message.objectiveId);
+const scannerSuite = new ScannerSuite();
+async function requestApproval(input, context) {
+  if (context.message.approvalGranted) return { skipped: true };
+  const now = new Date();
+  const approvalId = `approval-${context.message.task.id}`.slice(0, 64);
+  await sendControl({ type: "approval_request", objectiveId: context.message.objectiveId, approvalId, policy: input.policy, reason: input.reason, actor: "factory-policy", requestedAt: now.toISOString(), expiresAt: input.expiresAt ?? new Date(now.getTime() + 86_400_000).toISOString(), checkpoint: context.message.task.id });
+  return { approvalId };
+}
 const executor = new AgentExecutor({
   workspaces: new WorkspaceManager(config.workspaceDir, config.timeoutMs),
-  agentRunner: new ContainerAgentRunner({ image: config.workerImage, memoryDir: config.memoryDir, timeoutMs: config.timeoutMs }),
-  scannerSuite: new ScannerSuite(),
+  agentRunner: new ContainerAgentRunner({ image: config.workerImage, memoryDir: config.memoryDir, timeoutMs: config.timeoutMs, activityStore: new ActivityStore(config.stateDir) }),
+  scannerSuite,
   retriever: new LocalRetriever({ stateDir: config.stateDir }),
+  repoMapMaxCharacters: config.repoMapMaxCharacters,
   sendControl,
+  hooks: config.hooks,
+  hookHandlers: {
+    scanner: (input, context) => scannerSuite.scan(context.directory, { names: input.scanners }),
+    policy_check: async (input, context) => {
+      const evaluated = evaluateApprovalPolicy(Object.fromEntries(input.policies.map((policy) => [policy, new RegExp(policy.replaceAll("_", ".*"), "i").test(`${context.message.task.title} ${context.message.task.instructions}`)])));
+      if (!evaluated.required) return evaluated;
+      return { ...evaluated, ...await requestApproval({ policy: evaluated.policies[0], reason: `Policy requires approval: ${evaluated.policies.join(", ")}` }, context) };
+    },
+    notification: async (input, context) => log("info", "hook_notification", { objectiveId: context.message.objectiveId, taskId: context.message.task.id, message: input.message }),
+    snapshot: async (input) => ({ label: input.label ?? "checkpoint" }),
+    approval_request: requestApproval,
+  },
 });
 
 let shuttingDown = false;
@@ -30,6 +54,11 @@ const subscription = bus.receiver.subscribe({
   processMessage: async (message) => {
     const body = message.body;
     try {
+      if (await objectiveIsTerminal(config.stateDir, body?.objectiveId)) {
+        log("info", "terminal_objective_message_discarded", { objectiveId: body.objectiveId, taskId: body.task?.id });
+        await bus.receiver.completeMessage(message);
+        return;
+      }
       await executor.process(body);
       await bus.receiver.completeMessage(message);
     } catch (error) {

package/src/workspace-tools.js

@@ -5,6 +5,7 @@ import { run } from "./process.js";
 
 const ALLOWED_COMMANDS = new Set(["git", "ls", "node", "npm", "npx", "pwd", "rg"]);
 const DENIED_GIT_OPERATIONS = new Set(["credential", "push", "remote"]);
+const READ_ONLY_GIT_OPERATIONS = new Set(["diff", "grep", "log", "ls-files", "rev-parse", "show", "status"]);
 
 function lexicalPath(root, requested) {
   const target = path.resolve(root, requested);
@@ -43,10 +44,11 @@ async function walk(directory, root, output, limit) {
   }
 }
 
-export function createWorkspaceTools(rootInput, { execute = run } = {}) {
+export function createWorkspaceTools(rootInput, { execute = run, mutable = true, allowTests = false } = {}) {
   const root = realpathSync(path.resolve(rootInput));
-  return {
+  const tools = {
     read_file: {
+      parallelSafe: true,
       description: "Read a bounded UTF-8 line range inside the assigned workspace. Use offsetLine/limitLines instead of rereading large files.",
       parameters: {
         type: "object",
@@ -69,6 +71,7 @@ export function createWorkspaceTools(rootInput, { execute = run } = {}) {
       },
     },
     write_file: {
+      parallelSafe: false,
       description: "Atomically replace a UTF-8 file inside the assigned workspace.",
       parameters: {
         type: "object",
@@ -86,6 +89,7 @@ export function createWorkspaceTools(rootInput, { execute = run } = {}) {
       },
     },
     list_files: {
+      parallelSafe: true,
       description: "List files recursively inside the assigned workspace.",
       parameters: {
         type: "object",
@@ -101,6 +105,7 @@ export function createWorkspaceTools(rootInput, { execute = run } = {}) {
       },
     },
     run_command: {
+      parallelSafe: false,
       description: "Run an allowlisted noninteractive development command in the assigned workspace.",
       parameters: {
         type: "object",
@@ -113,7 +118,10 @@ export function createWorkspaceTools(rootInput, { execute = run } = {}) {
       },
       execute: async ({ command, args }) => {
         if (!ALLOWED_COMMANDS.has(command)) throw new Error(`Command not allowed: ${command}`);
-        if (command === "git" && DENIED_GIT_OPERATIONS.has(args[0])) throw new Error(`Git operation not allowed: ${args[0]}`);
+        const testCommand = allowTests && ((command === "npm" && ["test", "run"].includes(args[0])) || (command === "node" && args[0] === "--test") || (command === "npx" && args[0] === "--no-install"));
+        if (!mutable && !testCommand && !["git", "ls", "pwd", "rg"].includes(command)) throw new Error(`Command not allowed for read-only role: ${command}`);
+        if (command === "git" && (args.some((item) => DENIED_GIT_OPERATIONS.has(item)) || args.some((item) => ["-c", "--config-env", "--exec-path"].includes(item)))) throw new Error("Git operation not allowed");
+        if (!mutable && command === "git" && (args[0]?.startsWith("-") || !READ_ONLY_GIT_OPERATIONS.has(args[0]))) throw new Error(`Git operation not allowed for read-only role: ${args[0]}`);
         if (command === "npx" && args[0] !== "--no-install") throw new Error("npx requires --no-install");
         const result = await execute(command, args, {
           cwd: root,
@@ -127,4 +135,6 @@ export function createWorkspaceTools(rootInput, { execute = run } = {}) {
       },
     },
   };
+  if (!mutable) delete tools.write_file;
+  return tools;
 }

package/src/workspace.js

@@ -45,10 +45,18 @@ export class WorkspaceManager {
 
   async prepareTask(objective, task, dependencyCommits = []) {
     const directory = this.taskDirectory(objective.id, task.id);
-    if (await exists(directory)) return directory;
+    const branch = `factory-ai/${objective.id}/${task.id}`;
+    if (await exists(directory)) {
+      const current = (await run("git", ["-C", directory, "branch", "--show-current"])).stdout.trim();
+      if (current !== branch) throw new Error(`Existing task workspace is on unexpected branch: ${current}`);
+      for (const commit of dependencyCommits) {
+        const ancestor = await run("git", ["-C", directory, "merge-base", "--is-ancestor", commit, "HEAD"], { allowExitCodes: [0, 1] });
+        if (ancestor.code !== 0) throw new Error(`Existing task workspace is missing dependency commit: ${commit}`);
+      }
+      return directory;
+    }
     await mkdir(path.dirname(directory), { recursive: true, mode: 0o750 });
     const base = dependencyCommits[0] ?? `origin/${objective.baseBranch}`;
-    const branch = `factory-ai/${objective.id}/${task.id}`;
     await run("git", ["clone", objective.repository, directory], { timeoutMs: this.timeoutMs });
     await run("git", ["-C", directory, "config", "user.name", "Factory AI"]);
     await run("git", ["-C", directory, "config", "user.email", "factory-ai@localhost"]);
@@ -60,6 +68,13 @@ export class WorkspaceManager {
     return directory;
   }
 
+  async recoveryContext(directory) {
+    const status = (await run("git", ["-C", directory, "status", "--short"], { maxOutputBytes: 50_000 })).stdout.trim();
+    if (!status) return "";
+    const summary = (await run("git", ["-C", directory, "diff", "--stat"], { maxOutputBytes: 50_000 })).stdout.trim();
+    return `RECOVERED DURABLE WORKTREE CHECKPOINT\nA previous attempt changed these files. Inspect and continue rather than repeating completed work.\n${status}${summary ? `\n\n${summary}` : ""}`;
+  }
+
   async checkpoint(directory, objective, task) {
     await run("git", ["-C", directory, "add", "-A"]);
     const diff = await run("git", ["-C", directory, "diff", "--cached", "--quiet"], { allowExitCodes: [0, 1] });
@@ -75,4 +90,9 @@ export class WorkspaceManager {
     return { commit, branch };
   }
 
+  async reference(directory, objective, task) {
+    const { stdout } = await run("git", ["-C", directory, "rev-parse", "HEAD"]);
+    return { commit: stdout.trim(), branch: `factory-ai/${objective.id}/${task.id}` };
+  }
+
 }

package/templates/AGENTS.md

@@ -0,0 +1,15 @@
+# Project Agent Instructions
+
+## Working Agreement
+
+- Make the smallest correct change that satisfies the objective.
+- Read existing code and tests before editing. Preserve established architecture and style.
+- Never read, print, persist, or commit credentials or local environment files.
+- Keep changes inside this repository. Do not push, deploy, or mutate external systems.
+- Add or update focused tests for behavior changes.
+- Run the project's documented format, typecheck, lint, test, and build gates before claiming completion.
+- Report commands run, results, remaining risks, and any assumptions.
+
+## Project Commands
+
+Record project-specific commands and constraints in `.agent-factory/commands.md` and `.agent-factory/project.md`.