software-defence-factory 0.3.0

package/factory/incident.mjs

@@ -0,0 +1,64 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { configAt, digest, json, save, sleep } from './lib.mjs';
+
+const secret = /(?:sk-(?:proj-)?[a-zA-Z0-9_-]{16,}|gh[pousr]_[a-zA-Z0-9]{16,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|(?:authorization|password|api[_-]?key|secret)\s*[=:]\s*["']?(?!\[REDACTED\])[a-zA-Z0-9_+\/.=-]{8,})/i;
+export function validateIncident(input,scope,now=Date.now()) {
+  if(!scope||!['project','service','environment','owner'].every(k=>typeof scope[k]==='string'&&scope[k].trim()))throw new Error('A complete trusted installation scope is required');
+  if(input.contract_version!==1||input.sanitized!==true)throw new Error('Expected contract_version:1 and operator-sanitized:true evidence');
+  for(const k of ['project','service','environment'])if(input[k]!==scope[k])throw new Error(`Incident ${k} differs from the trusted installation scope`);
+  for(const k of ['source','event_id','summary'])if(typeof input[k]!=='string'||!input[k].trim()||input[k].length>1000)throw new Error(`Invalid incident ${k}`);
+  if(!Array.isArray(input.evidence)||input.evidence.length>20)throw new Error('Expected up to 20 bounded evidence entries');
+  const clean={contract_version:1,project:scope.project,service:scope.service,environment:scope.environment,owner:scope.owner,source:input.source,event_id:input.event_id,summary:input.summary,evidence:[],gaps:[]};
+  for(const e of input.evidence) {
+    if(!['logs','metrics','revision'].includes(e.kind)||typeof e.text!=='string'||e.text.length>16000||!Number.isFinite(Date.parse(e.observed_at)))throw new Error('Invalid evidence kind, text or observed_at');
+    const stale=now-Date.parse(e.observed_at)>3600000||Date.parse(e.observed_at)>now+60000;
+    clean.evidence.push({kind:e.kind,text:e.text,observed_at:e.observed_at,stale,hash:digest(e.text)});
+    if(stale)clean.gaps.push(`${e.kind}: outside the one-hour freshness window`);
+  }
+  for(const kind of ['logs','metrics','revision'])if(!clean.evidence.some(e=>e.kind===kind&&e.text.trim()))clean.gaps.push(`Missing ${kind}`);
+  const serialized=JSON.stringify(clean);
+  if(Buffer.byteLength(serialized)>64000)throw new Error('Evidence exceeds 64 KB');
+  if(secret.test(serialized))throw new Error('Possible credential detected; remove it before submitting evidence');
+  return clean;
+}
+export async function admitIncident(state,input,submit) {
+  const clean=validateIncident(input,configAt(state).scope);
+  // Stable input hash excludes time-dependent coverage judgments.
+  const hash=digest(JSON.stringify({...clean,gaps:[],evidence:clean.evidence.map(({stale,...e})=>e)}));
+  const key=digest(JSON.stringify([clean.project,clean.environment,clean.service,clean.source,clean.event_id]));
+  const directory=join(state,'incidents');mkdirSync(directory,{recursive:true,mode:0o700});
+  const path=join(directory,`${key}.json`);
+  if(existsSync(path)) {
+    const prior=json(path);
+    if(prior.inputHash!==hash)throw new Error('Same incident identity with conflicting evidence; review it before creating a new episode');
+    if(!prior.job)throw new Error('Admission outcome unknown; reconcile the existing case in the dashboard before retrying');
+    return {id:prior.job,case_id:prior.case_id,deduplicated:true};
+  }
+  const entry={case_id:`case_${key.slice(0,16)}`,inputHash:hash,received_at:new Date().toISOString(),case_state:'open',input:clean};
+  writeFileSync(path,JSON.stringify(entry,null,2),{mode:0o600,flag:'wx'});
+  // Keeping a pending record on a network failure prevents a duplicate writer.
+  const job=await submit('defence',`ARCITAI_INCIDENT_REF:${key}`);
+  save(path,{...entry,job:job.id});return {...job,case_id:entry.case_id,deduplicated:false};
+}
+export async function incidentFor(state,prompt,job) {
+  const match=prompt.trim().match(/^ARCITAI_INCIDENT_REF:([a-f0-9]{64})$/);
+  if(!match)throw new Error('Submit incident evidence through the CLI incident command');
+  const path=join(state,'incidents',`${match[1]}.json`);
+  let entry=json(path);
+  // Submission may return just after the worker claims its first step. Never let
+  // the executor claim a pending admission itself: only the submitting controller binds it.
+  for(let i=0;!entry.job&&i<30;i++){await sleep(100);entry=json(path);}
+  if(!entry.job||entry.job!==job)throw new Error('Incident admission is not bound to this job; reconcile it instead of duplicating the case');
+  // Recheck the trusted scope and freshness at execution time.
+  const input=validateIncident({...entry.input,sanitized:true},configAt(state).scope);
+  return {path,entry,input};
+}
+export function validateReport(report,incident) {
+  const list=k=>Array.isArray(report[k])&&report[k].length<=50&&report[k].every(v=>typeof v==='string'&&v.length<=4000);
+  if(!['needs_review','insufficient_evidence'].includes(report.status)||typeof report.summary!=='string'||!report.summary.trim()||report.summary.length>8000||report.production_action_taken!==false||!['hypotheses','recommended_actions','unknowns'].every(list))throw new Error('Invalid incident draft');
+  const incomplete=report.status==='insufficient_evidence'||incident.input.gaps.length>0;
+  // Model output cannot introduce authoritative recovery or verification fields.
+  return {case_id:incident.entry.case_id,case_state:'open',draft:true,verification:'not_performed',status:incomplete?'insufficient_evidence':'needs_review',investigation:incomplete?'inconclusive':'triaged',
+    summary:report.summary,hypotheses:report.hypotheses,recommended_actions:report.recommended_actions,unknowns:report.unknowns,evidence_gaps:incident.input.gaps,production_action_taken:false};
+}

package/factory/lib.mjs

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { resolve, dirname, join, isAbsolute } from 'node:path';
+import { spawnSync, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+
+import { ROOT, DEFAULT_STATE } from './paths.mjs';
+export { ROOT, DEFAULT_STATE };
+export const PINS = JSON.parse(readFileSync(join(ROOT, 'factory/pins.json')));
+export const json = path => JSON.parse(readFileSync(path, 'utf8'));
+export function save(path, value) {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 }); renameSync(temp, path);
+}
+export function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024, ...options });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error(`${command} failed (${result.status}): ${result.stderr || result.stdout || ''}`);
+  return result.stdout?.trim() ?? '';
+}
+export function stream(command, args, options = {}) {
+  return new Promise((ok, fail) => {
+    const child = spawn(command, args, { stdio: 'inherit', ...options });
+    child.on('error', fail); child.on('exit', code => code === 0 ? ok() : fail(new Error(`${command} exited ${code}`)));
+  });
+}
+export const digest = value => createHash('sha256').update(value).digest('hex');
+export const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+export function configAt(state) {
+  const config = json(join(state, 'factory.json'));
+  if (config.version !== 1 || !['mock','codex','pi','custom'].includes(config.agent)) throw new Error('Unsupported configuration');
+  if (!Array.isArray(config.command) || !config.command.length || !config.command.every(v => typeof v === 'string' && v && !v.includes('\0'))) throw new Error('command must be an argument array');
+  if (!Number.isInteger(config.port) || config.port < 1024 || config.port > 65535) throw new Error('Invalid port');
+  if (!Number.isInteger(config.timeoutSeconds) || config.timeoutSeconds < 1 || config.timeoutSeconds > 7200) throw new Error('timeoutSeconds must be 1–7200');
+  if (!Number.isInteger(config.memoryMiB) || config.memoryMiB < 256) throw new Error('Invalid memory limit');
+  if (!['none','bridge'].includes(config.network)) throw new Error('network must be none or bridge; host networking is not supported');
+  if (typeof config.image !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_./:@-]*$/.test(config.image)) throw new Error('Invalid container image');
+  if (typeof config.repo !== 'string' || !isAbsolute(config.repo) || [config.repo,state,ROOT].some(p=>/[,\n\r]/.test(p))) throw new Error('Expected absolute paths without commas or line breaks');
+  if (typeof config.check !== 'string' || !config.scope || !['project','service','environment','owner'].every(k=>typeof config.scope[k]==='string'&&config.scope[k].trim())) throw new Error('Missing check or installation scope');
+  if (!existsSync(config.repo)) throw new Error('Configured repository is missing');
+  return config;
+}
+export async function api(state, path, body, method) {
+  const config = configAt(state);
+  const response = await fetch(`http://127.0.0.1:${config.port}${path}`, {
+    method: method || (body === undefined ? 'GET' : 'POST'),
+    headers: { Authorization: `Bearer ${readFileSync(join(state, 'worker.token'), 'utf8').trim()}`, 'Content-Type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(5000),
+  });
+  const text = await response.text();
+  if (!response.ok) throw new Error(`Controller ${response.status}: ${text}`);
+  return text ? JSON.parse(text) : null;
+}
+export function instanceLabel(state) { return digest(resolve(state)).slice(0, 16); }
+export function containers(state) {
+  const ids = run('docker', ['ps', '-aq', '--filter', `label=sdf.factory=${instanceLabel(state)}`]).split('\n').filter(Boolean);
+  return ids.flatMap(id=>{
+    const result=spawnSync('docker',['inspect',id],{encoding:'utf8'});
+    if(result.error)throw result.error;
+    // Normal completion can remove a container between list and inspect.
+    if(result.status!==0) {
+      if(/no such (object|container)/i.test(result.stderr))return [];
+      throw new Error(`Cannot inspect job container: ${result.stderr}`);
+    }
+    return JSON.parse(result.stdout);
+  });
+}
+export function stopContainers(state, jobId) {
+  for (const item of containers(state)) {
+    if (jobId && item.Config.Labels['sdf.job'] !== jobId) continue;
+    if (item.State.Running) {
+      try {run('docker', ['stop', '--time', '2', item.Id]);}
+      catch(error) {if(containers(state).some(c=>c.Id===item.Id&&c.State.Running))throw error;}
+    }
+    try { run('docker', ['rm', item.Id]); } catch (error) {
+      if (containers(state).some(c => c.Id === item.Id)) throw error;
+    }
+  }
+}

package/factory/paths.mjs

@@ -0,0 +1,13 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+export const SOURCE_CHECKOUT = existsSync(join(ROOT, '.git'));
+export const STATE_HOME = join(process.env.XDG_STATE_HOME || join(homedir(), '.local/state'), 'software-defence-factory');
+export const DATA_HOME = join(process.env.XDG_DATA_HOME || join(homedir(), '.local/share'), 'software-defence-factory');
+// Keep existing source-checkout installations compatible. npm installations never
+// put private state in node_modules, an npm cache, or the caller's application.
+export const DEFAULT_STATE = SOURCE_CHECKOUT ? join(ROOT, '.factory/platform') : join(STATE_HOME, 'platform');
+export const DEFAULT_DEMO_STATE = SOURCE_CHECKOUT ? join(ROOT, '.factory/demo-platform') : join(STATE_HOME, 'demo-platform');

package/factory/pins.json

@@ -0,0 +1,3 @@
+{
+  "jobImage": "software-defence-factory-job:0.3.0"
+}

package/factory/processes.mjs

@@ -0,0 +1,60 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, openSync, closeSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { ROOT, configAt, run, json, stopContainers, sleep } from './lib.mjs';
+
+const alive = pid => { try { process.kill(pid, 0); return true; } catch (error) { if (error.code === 'ESRCH') return false; throw error; } };
+export function executors(state) {
+  const children = new Map();
+  async function stop(jobId) {
+    const running = children.get(jobId);
+    if (running) {
+      try { process.kill(-running.child.pid, 'SIGTERM'); } catch (error) { if (error.code !== 'ESRCH') throw error; }
+      await Promise.race([running.done, sleep(2000)]);
+      if (alive(-running.child.pid)) {
+        try { process.kill(-running.child.pid, 'SIGKILL'); } catch (error) { if (error.code !== 'ESRCH') throw error; }
+        await running.done;
+      }
+    }
+    stopContainers(state, jobId);
+    if (running && !alive(-running.child.pid)) rmSync(join(state, 'jobs', jobId, 'active.json'), { force: true });
+  }
+  async function reconcile(jobId, phase) {
+    if (children.has(jobId)) throw new Error('Previous executor is still finishing');
+    stopContainers(state, jobId);
+    const folder = join(state, 'jobs', jobId), lock = join(folder, 'active.json');
+    if (existsSync(lock)) {
+      const previous = json(lock);
+      if (!Number.isSafeInteger(previous.pid) || alive(previous.pid)) throw new Error('Previous executor is still present or unknown');
+      if (!Number.isSafeInteger(previous.pgid) || run('ps', ['-axo', 'pgid=']).split('\n').map(Number).includes(previous.pgid))
+        throw new Error('Previous process group is still present or unknown');
+      rmSync(lock);
+    }
+    if (['build', 'defence'].includes(phase) && existsSync(join(folder, 'checkout')))
+      renameSync(join(folder, 'checkout'), join(folder, `previous-checkout-${Date.now()}`));
+  }
+  async function execute(job, attempt) {
+    const config = configAt(state), output = join(state, 'jobs', job.id, 'artifacts', attempt.id);
+    mkdirSync(output, { recursive: true, mode: 0o700 });
+    const resultPath = join(output, 'result.json'), fd = openSync(join(output, 'executor.log'), 'a', 0o600);
+    const child = spawn(process.execPath, [join(ROOT, 'factory/executor.mjs'), state, attempt.command], {
+      detached: true, stdio: ['pipe', fd, fd], env: { ...process.env, SDF_JOB_ID: job.id, SDF_RUN_ID: attempt.id, SDF_MODEL: job.model || '', SDF_OUTPUT_DIR: output, SDF_STEP_RESULT_PATH: resultPath },
+    }); closeSync(fd);
+    let finish;
+    const done = new Promise(resolve => { finish = resolve; });
+    children.set(job.id, { child, done });
+    child.on('error', error => finish({ error }));
+    child.on('close', code => finish({ code }));
+    child.stdin.on('error', error => { if (error.code !== 'EPIPE') finish({ error }); }); child.stdin.end(job.prompt);
+    const deadline = setTimeout(() => { stop(job.id).catch(error => console.error(error.message)); }, (config.timeoutSeconds + 30) * 1000);
+    let exit;
+    try { exit = await done; }
+    finally { clearTimeout(deadline); children.delete(job.id); }
+    if (exit.error) throw exit.error;
+    if (!existsSync(resultPath)) throw new Error(`Executor exited ${exit.code} without a result`);
+    const outcome = JSON.parse(readFileSync(resultPath, 'utf8'));
+    if (exit.code !== 0 || outcome.outcome !== 'complete') return { outcome: 'blocked', summary: outcome.summary || `Executor exited ${exit.code}` };
+    return outcome;
+  }
+  return { execute, stop, reconcile };
+}

package/factory/queue.mjs

@@ -0,0 +1,132 @@
+import { DatabaseSync } from 'node:sqlite';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+
+const workflows = { software: ['build', 'verify', 'review', 'handoff'], defence: ['defence'] };
+const id = prefix => prefix + '_' + randomBytes(12).toString('hex');
+const now = () => new Date().toISOString();
+export class QueueError extends Error { constructor(message, status = 409) { super(message); this.status = status; } }
+
+// One controller owns this database and one executor at a time. Each transition
+// is committed before execution starts; a restart never assumes a result.
+export class JobQueue {
+  constructor(state, { execute, stop, reconcile }) {
+    this.db = new DatabaseSync(join(state, 'jobs.sqlite'));
+    this.db.exec('PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000; CREATE TABLE IF NOT EXISTS jobs(id TEXT PRIMARY KEY, data TEXT NOT NULL);');
+    this.execute = execute; this.stop = stop; this.reconcile = reconcile;
+    this.active = null; this.closing = false; this.pumping = false; this.actions = new Set();
+    for (const job of this.all()) if (['running', 'cancelling'].includes(job.state)) {
+      job.state = 'interrupted';
+      Object.assign(job.runs.at(-1), { state: 'interrupted', completed_at: now(), error: 'Controller stopped before completion was confirmed.' });
+      this.save(job);
+    }
+  }
+  all() { return this.db.prepare('SELECT data FROM jobs ORDER BY rowid').all().map(row => JSON.parse(row.data)).filter(job => !job.deleted_at); }
+  get(jobId) {
+    const row = this.db.prepare('SELECT data FROM jobs WHERE id=?').get(jobId);
+    if (!row) throw new QueueError('Job not found', 404);
+    const job = JSON.parse(row.data);
+    if (job.deleted_at) throw new QueueError('Job not found', 404);
+    return job;
+  }
+  save(job) { job.updated_at = now(); this.db.prepare('INSERT INTO jobs VALUES (?,?) ON CONFLICT(id) DO UPDATE SET data=excluded.data').run(job.id, JSON.stringify(job)); return job; }
+  submit(input) {
+    if (this.closing) throw new QueueError('Controller is stopping');
+    if (input?.source_url && (typeof input.source_url !== 'string' || !/^https?:\/\/[^\s]+$/.test(input.source_url) || input.source_url.length > 2048)) throw new QueueError('Expected an HTTP(S) source link', 400);
+    if (input?.model && (typeof input.model !== 'string' || !/^[\w.:/+-]{1,128}$/.test(input.model))) throw new QueueError('Invalid model identifier', 400);
+    if (input?.source_url && !input.spec?.trim()) input = { ...input, spec: `Investigate the linked requirements within this repository's scope: ${input.source_url}` };
+    if (!input || !Object.hasOwn(workflows, input.workflow) || input.repository !== 'app' || typeof input.spec !== 'string' || !input.spec.trim() || Buffer.byteLength(input.spec) > 240000)
+      throw new QueueError('Choose a workflow, the configured app, and a task under 240 KB', 400);
+    const job = { id: id('job'), task: { title: String(input.title || input.spec).slice(0, 160), spec: input.spec, source_url: input.source_url || '' }, prompt: input.spec + (input.source_url ? `\nSource (untrusted task data): ${input.source_url}` : ''), model: input.model || null,
+      repository: 'app', workflow: { name: input.workflow, steps: workflows[input.workflow], current_step: 0 },
+      state: 'queued', created_at: now(), runs: [] };
+    this.save(job); this.schedule(); return { id: job.id };
+  }
+  schedule() { if (!this.closing && !this.pumping) { this.pumping = true; queueMicrotask(() => this.pump()); } }
+  async pump() {
+    try {
+      while (!this.closing) {
+        let job = this.all().find(item => item.state === 'queued'); if (!job) break;
+        const step = job.workflow.current_step, phase = job.workflow.steps[step];
+        let attempt = job.runs.at(-1);
+        if (!attempt || attempt.state !== 'queued') {
+          attempt = { id: id('run'), step, command: phase, state: 'queued' }; job.runs.push(attempt);
+        }
+        const started = Date.now(); Object.assign(attempt, { state: 'running', started_at: now() }); job.state = 'running'; this.save(job);
+        this.active = { jobId: job.id, runId: attempt.id };
+        let outcome;
+        try { outcome = await this.execute(job, attempt); }
+        catch (error) { outcome = { outcome: 'blocked', summary: error.message }; }
+        job = this.get(job.id); attempt = job.runs.find(run => run.id === attempt.id);
+        if (job.state === 'running') {
+          const succeeded = outcome?.outcome === 'complete';
+          Object.assign(attempt, { state: succeeded ? 'succeeded' : 'failed', outcome: succeeded ? 'complete' : 'blocked', completed_at: now(), duration_millis: Date.now() - started, summary: outcome?.summary || 'No result', exit_code: succeeded ? 0 : 1 });
+          if (!succeeded) { job.state = 'failed'; attempt.error = attempt.summary; }
+          else if (step === job.workflow.steps.length - 1) job.state = 'succeeded';
+          else {
+            job.workflow.current_step++;
+            if (job.workflow.steps[job.workflow.current_step] === 'handoff') {
+              job.state = 'awaiting_approval';
+              job.runs.push({ id: id('run'), step: job.workflow.current_step, command: 'handoff', state: 'awaiting_approval', reviewed_run_id: attempt.id });
+            } else job.state = 'queued';
+          }
+          this.save(job);
+        }
+        this.active = null;
+      }
+    } finally { this.pumping = false; }
+  }
+  async exclusive(jobId, perform) {
+    if (this.closing || this.actions.has(jobId)) throw new QueueError('Job is already changing; reload before acting');
+    this.actions.add(jobId);
+    try { return await perform(); } finally { this.actions.delete(jobId); }
+  }
+  action(jobId, action, input) { return this.exclusive(jobId, () => this.applyAction(jobId, action, input)); }
+  async applyAction(jobId, action, input) {
+    if (this.closing) throw new QueueError('Controller is stopping');
+    const job = this.get(jobId), attempt = job.runs.at(-1);
+    if (input?.run_id !== attempt?.id) throw new QueueError('Job changed; reload before acting');
+    if (action === 'approve') {
+      if (job.state !== 'awaiting_approval') throw new QueueError('Job is not awaiting approval');
+      job.state = 'queued'; attempt.state = 'queued'; this.save(job); this.schedule();
+    } else if (action === 'request_changes') {
+      if (job.state !== 'awaiting_approval' || job.workflow.name !== 'software') throw new QueueError('Only a reviewed software task can be revised');
+      if (typeof input.feedback !== 'string' || !input.feedback.trim() || input.feedback.length > 4000) throw new QueueError('Provide revision feedback under 4000 characters', 400);
+      await this.reconcile(jobId, 'build');
+      Object.assign(attempt, { state: 'succeeded', outcome: 'changes_requested', summary: input.feedback, completed_at: now(), duration_millis: 0 });
+      job.prompt += `\n\nRequested revision: ${input.feedback}`;
+      job.workflow.current_step = 0; job.state = 'queued'; this.save(job); this.schedule();
+    } else if (action === 'cancel') {
+      if (!['queued', 'running', 'awaiting_approval', 'blocked', 'interrupted'].includes(job.state)) throw new QueueError('Job is already stopped');
+      job.state = 'cancelling'; this.save(job);
+      try { await this.stop(jobId); }
+      catch (error) { job.state = 'interrupted'; this.save(job); throw error; }
+      job.state = 'cancelled';
+      if (attempt) Object.assign(attempt, { state: 'cancelled', completed_at: now() });
+      this.save(job);
+    } else if (action === 'retry') {
+      if (!['failed', 'interrupted', 'cancelled'].includes(job.state)) throw new QueueError('Only a stopped attempt can be retried');
+      await this.reconcile(jobId, attempt?.command);
+      job.state = 'queued'; this.save(job); this.schedule();
+    } else throw new QueueError('Unknown action', 404);
+    return { id: jobId, state: job.state };
+  }
+  remove(jobId) { return this.exclusive(jobId, () => this.removeStopped(jobId)); }
+  async removeStopped(jobId) {
+    const job = this.get(jobId);
+    if (!['succeeded', 'failed', 'cancelled'].includes(job.state) || this.active?.jobId === jobId) throw new QueueError('Stop the task before removing it');
+    await this.reconcile(jobId);
+    job.deleted_at = now(); this.save(job);
+    return { id: jobId, deleted: true };
+  }
+  async close() {
+    this.closing = true;
+    if (this.active) {
+      const job = this.get(this.active.jobId);
+      job.state = 'interrupted'; Object.assign(job.runs.at(-1), { state: 'interrupted', completed_at: now() }); this.save(job);
+      await this.stop(job.id);
+    }
+    while (this.pumping || this.actions.size) await new Promise(resolve => setTimeout(resolve, 20));
+    this.db.close();
+  }
+}

package/factory/server.mjs

@@ -0,0 +1,101 @@
+import http from 'node:http';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, lstatSync, realpathSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { hostname } from 'node:os';
+import { JobQueue, QueueError } from './queue.mjs';
+import { executors } from './processes.mjs';
+import { configAt, ROOT } from './lib.mjs';
+
+function equal(a, b) { return typeof a === 'string' && Buffer.byteLength(a) === Buffer.byteLength(b) && timingSafeEqual(Buffer.from(a), Buffer.from(b)); }
+async function body(request) {
+  let text = '';
+  for await (const part of request) { text += part; if (Buffer.byteLength(text) > 256000) throw new QueueError('Request too large', 413); }
+  try { const value = JSON.parse(text); if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(); return value; }
+  catch { throw new QueueError('Expected a JSON object', 400); }
+}
+function artifacts(state, jobId) {
+  const root = join(state, 'jobs', jobId, 'artifacts'); if (!existsSync(root)) return [];
+  return readdirSync(root).filter(name => /^run_[a-f0-9]+$/.test(name)).flatMap(runId =>
+    readdirSync(join(root, runId)).filter(name => /^[\w.-]+\.(?:md|json|patch|log)$/.test(name)).flatMap(name => {
+      const stat = lstatSync(join(root, runId, name));
+      return stat.isFile() && !stat.isSymbolicLink() ? [{ id: `${jobId}~${runId}~${name}`, run_id: runId, path: name, storagePath: `${runId}/${name}`, size: stat.size, bytes: stat.size, content_type: 'text/plain' }] : [];
+    }));
+}
+export function createController(state, adapter = executors(state)) {
+  const config = configAt(state), csrf = randomBytes(32).toString('hex');
+  const token = readFileSync(join(state, 'worker.token'), 'utf8').trim();
+  const queue = new JobQueue(state, adapter);
+  const server = http.createServer(async (request, response) => {
+    const send = (status, value, type = 'application/json; charset=utf-8') => { response.writeHead(status, { 'Content-Type': type }); response.end(type.startsWith('application/json') ? JSON.stringify(value) : value); };
+    response.setHeader('Cache-Control', 'no-store'); response.setHeader('X-Content-Type-Options', 'nosniff'); response.setHeader('Referrer-Policy', 'no-referrer');
+    response.setHeader('Content-Security-Policy', "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'");
+    try {
+      const port = server.address().port, hosts = [`localhost:${port}`, `127.0.0.1:${port}`];
+      if (!hosts.includes(request.headers.host)) throw new QueueError('Host is not allowed', 403);
+      if (request.headers.origin && !hosts.map(host => `http://${host}`).includes(request.headers.origin)) throw new QueueError('Origin is not allowed', 403);
+      if (request.headers['sec-fetch-site'] === 'cross-site') throw new QueueError('Cross-site access is not allowed', 403);
+      const url = new URL(request.url, `http://${request.headers.host}`);
+      const authenticated = equal(request.headers.authorization, `Bearer ${token}`) || equal(request.headers['x-factory-session'], csrf);
+      if (request.method === 'GET' && url.pathname === '/api/v1/status') {
+        const jobs = queue.all().map(job => ({ ...job, runs: job.runs.map(attempt => ({ ...attempt,
+          outcome: attempt.outcome || (attempt.state === 'succeeded' ? 'complete' : undefined),
+          executor: ['verify','handoff'].includes(attempt.command) ? 'deterministic' : config.agent,
+          worker_name: hostname(), model: job.model || config.model })) }));
+        return send(200, { version: 1, workflows: ['software', 'defence'], commands: [], triggers: [], jobs, csrf_token: csrf,
+          workers: [{ name: hostname(), instance_id: 'local-executor', repositories: ['app'], connected: !queue.closing, last_seen_at: new Date().toISOString() }],
+          repositories: ['app'], repo: config.repo, agent: config.agent });
+      }
+      if (request.method === 'GET' && url.pathname === '/api/v1/definitions') {
+        const descriptions = {
+          build: 'Implement the accepted task in an isolated checkout, using the bundled policy and skills. Produce a candidate commit and implementation evidence.',
+          verify: `Run the configured application check on the candidate commit: ${config.check}`,
+          review: 'Independently review the candidate diff and checks. Record pass, changes or blocked with concrete findings.',
+          handoff: 'After operator approval, verify the candidate and policy still match the checks and review. Record acceptance without pushing, merging or deploying.',
+          defence: 'Read-only triage of an admitted, scoped incident. Produce a private draft, preserve unknowns and make no production change or recovery claim.',
+        };
+        return send(200, { workflows: { software: ['build','verify','review','handoff'].map(name => ({ name, approval: name === 'handoff' })), defence: [{ name: 'defence' }] },
+          commands: Object.entries(descriptions).map(([name,prompt]) => ({ name, prompt, executor: ['verify','handoff'].includes(name) ? 'deterministic' : config.agent, timeout: `${config.timeoutSeconds}s` })) });
+      }
+      const content = url.pathname.match(/^\/api\/v1\/artifacts\/(job_[a-f0-9]+)~(run_[a-f0-9]+)~([\w.-]+)\/content$/);
+      const artifactList = url.pathname.match(/^\/api\/v1\/jobs\/(job_[a-f0-9]+)\/artifacts$/);
+      if (request.method === 'GET' && (artifactList || content)) {
+        if (!authenticated) throw new QueueError('Session required', 403);
+        const jobId = (artifactList || content)[1]; queue.get(jobId);
+        const entries = artifacts(state, jobId), file = content ? `${content[2]}/${content[3]}` : url.searchParams.get('file');
+        if (!file) return send(200, entries);
+        if (!entries.some(item => item.storagePath === file && item.bytes <= 1024 * 1024)) throw new QueueError('Artifact not available', 404);
+        const root = realpathSync(join(state, 'jobs', jobId, 'artifacts')), path = realpathSync(resolve(root, file));
+        if (!path.startsWith(root + sep)) throw new QueueError('Artifact path rejected', 403);
+        return send(200, readFileSync(path), 'text/plain; charset=utf-8');
+      }
+      if (request.method === 'POST') {
+        if (!authenticated) throw new QueueError('Session required', 403);
+        if (!(request.headers['content-type'] || '').startsWith('application/json')) throw new QueueError('Use application/json', 415);
+        const input = await body(request);
+        if (url.pathname === '/api/v1/jobs') {
+          if (input.model && input.model !== config.model && !['codex','pi'].includes(config.agent)) throw new QueueError('Model overrides require a codex or pi executor', 400);
+          return send(201, queue.submit(input));
+        }
+        const action = url.pathname.match(/^\/api\/v1\/jobs\/(job_[a-f0-9]+)\/(approve|cancel|retry|request_changes)$/);
+        if (action) return send(200, await queue.action(action[1], action[2], input));
+      }
+      const removal = url.pathname.match(/^\/api\/v1\/jobs\/(job_[a-f0-9]+)$/);
+      if (request.method === 'DELETE' && removal) {
+        if (!authenticated) throw new QueueError('Session required', 403);
+        return send(200, await queue.remove(removal[1]));
+      }
+      const asset = url.pathname.match(/^\/assets\/([\w.-]+\.(js|css|woff2))$/);
+      if (request.method === 'GET' && (url.pathname === '/' || asset)) {
+        const name = asset ? `assets/${asset[1]}` : 'index.html';
+        const types = { js: 'text/javascript', css: 'text/css', woff2: 'font/woff2' };
+        const path = join(ROOT, 'factory/ui', name);
+        if (!existsSync(path)) throw new QueueError('Asset not found', 404);
+        return send(200, readFileSync(path), asset ? types[asset[2]] : 'text/html; charset=utf-8');
+      }
+      throw new QueueError('Not found', 404);
+    } catch (error) { if (!error.status) console.error(error); send(error.status || 500, { error: error.status ? error.message : 'Controller error; see private logs' }); }
+  });
+  server.requestTimeout = 20000; server.headersTimeout = 15000; server.on('listening', () => queue.schedule());
+  return { server, queue, async close() { await queue.close(); await new Promise(resolve => server.close(resolve)); } };
+}

package/factory/supervisor.mjs

@@ -0,0 +1,20 @@
+import { writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { configAt, stopContainers } from './lib.mjs';
+import { createController } from './server.mjs';
+const state = process.argv[2], config = configAt(state), lock = join(state, 'supervisor.json');
+writeFileSync(lock, JSON.stringify({ pid: process.pid }), { flag: 'wx', mode: 0o600 });
+let controller, stopping = false;
+async function shutdown(code = 0) {
+  if (stopping) return; stopping = true;
+  try { if (controller) await controller.close(); stopContainers(state); }
+  catch (error) { console.error(`Stop unconfirmed: ${error.message}`); process.exit(1); }
+  rmSync(lock, { force: true }); process.exit(code);
+}
+process.on('SIGTERM', () => shutdown()); process.on('SIGINT', () => shutdown());
+try {
+  stopContainers(state);
+  controller = createController(state);
+  controller.server.on('error', error => { console.error(error.message); shutdown(1); });
+  controller.server.listen(config.port, '127.0.0.1', () => console.log(`Factory controller ready on 127.0.0.1:${config.port}`));
+} catch (error) { console.error(error.message); await shutdown(1); }