Software factory overview
The software factory (phase P3) turns a task description into a reviewed pull request. A client submits a job against an allowlisted repository at a pinned commit; a durable Temporal workflow runs a plan, code, test and review loop in per-job sandboxes; a human approves the result; the worker pushes a deterministic commit to a fork and opens a pull request. The goal of the design is that an untrusted model can propose a change but cannot publish one: every byte that leaves the sandbox is parsed, filtered and re-derived on the host, and a human gate binds to a digest of those bytes.
Status. The source documents state that the factory is built and tested locally only (a Linux VM, a scripted fake model, a fake git remote). Nothing in the deploy runbook has run on the VPS or against real GitHub; the GitHub Apps, the fork layout, runsc, TLS for the control link and real-key runs are all marked UNVERIFIED with a named owner (Job lifecycle, docs/deploy-factory.md).
End-to-end flow
Where the code lives
| Concern | Location |
|---|---|
| Contracts (statuses, limits, digests, policy schema) | packages/agent-types/src/factory.ts |
| Intake, read, approval and cancel routes | apps/api/src/factory.ts |
| Workflow | packages/agent-workflows/src/workflows/factory.ts, contract in factory-shared.ts |
| Activities | apps/worker/src/factory/activities.ts |
| Patch parser, filter, secret scan, hardened git | apps/worker/src/factory/patch.ts, secrets.ts, apply.ts, outfile.ts |
| GitHub (two Apps, fork, PR) | apps/worker/src/factory/git-host.ts, github-app.ts, local-git.ts |
| Sandbox runtime, test container | apps/worker/src/sandbox/* |
| Sandbox runner (inside the container) | apps/sandbox-runner/src/runner.ts |
| Factory worker entry and config | apps/worker/src/factory-main.ts, apps/worker/src/factory/config.ts |
| Tables | packages/db/src/schema.ts, store in packages/db/src/factory.ts |
Design principles
- Postgres decides. Job and step state, attempt counters, fences, approvals and artifacts live in Postgres. Temporal payloads carry ids, digests and small enums only. The approval signal wakes the workflow; the decision is read from Postgres.
- The sandbox is untrusted. It holds only a per-job token. The host takes exactly one regular file out of it, and the completion of a step is a host fact, not the runtime's claim.
- The host never runs repository code. No package manager, hooks or filters on the worker; the host only parses text, applies it with hardened git and archives it.
- Approvals bind to bytes. A digest over job, repo, base commit and artifact digest;
openPrre-derives everything from the approved bytes before it pushes. - Least credential per component. The factory worker holds the GitHub App keys and the gateway worker control token but never an Anthropic key; the API holds no GitHub credential; the gateway holds the Anthropic key; the sandboxes hold a single short-lived token.
- Fail closed. Any error in a security check ends the step or the job (kill switch read error, scrub error, unparseable manifest, preflight failure).
Components and trust
Job at a glance
| Item | Value |
|---|---|
| Workflow type, id, queue | factoryJobWorkflow, factory-<jobId>, agentforge-factory |
| Roles and caps (default, USD per step) | planner 0.10, coder 0.25, reviewer 0.10 |
| Per-job budget | request budgetUsd up to 2, ceiling FACTORY_MAX_JOB_USD default 0.5 |
| Iterations | 1 to 5, default 3 |
| Step timeout | FACTORY_STEP_TIMEOUT_MS default 600 s, max 840 s |
| Approval TTL | 72 hours default, up to 7 days |
| Active jobs per client | 2 by default |
| Gates | factory.pr always, factory.plan optional |
| Statuses | queued, planning, awaiting_plan_approval, coding, validating, testing, reviewing, awaiting_pr_approval, opening_pr, pr_opened, failed, cancelled |
Per-repo policy
Operator-owned knobs live in a strict JSON file per repository, <FACTORY_POLICY_DIR>/<repo name>.json, parsed as FactoryRepoPolicy. An unknown key is a startup error. A repository with no file gets the defaults (the factory.pr gate only). They are not part of the gateway's policy.
| Key | Default | Meaning |
|---|---|---|
id | required (default when no file) | policy id, ^[a-z0-9-]{1,64}$ |
tests.command | ['pnpm', 'test'] | fixed argv for the test container |
tests.required | true | a non-passing test blocks acceptance |
tests.timeoutMs | 300000 (max 840000) | test run bound |
patch.allowBinary | false | allow binary hunks (their decoded bytes are scanned) |
patch.allowNonAscii | false | declared; not wired in the patch parser (see Patch policy) |
patch.protected | [] | extra protected path globs, added to the defaults |
patch.githubAllow | [] | .github/** globs explicitly allowed (workflows stay forbidden) |
approvals.fourEyes | false | declared; not enforced anywhere (see Gates and approvals) |
gates | ['factory.pr'] | gates to add; factory.pr is always present |
quality | absent | CodeCrucible policy; absent means CodeCrucible is off for the repo |
Section map
- Job lifecycle: states, the workflow, activities, budget, cancellation, tables and limits, worker configuration.
- Gates and approvals: digests, the approval transaction, expiry races, roles, the four-eyes gap.
- Patch policy: the validation pipeline, protected paths, reason codes, secret scan, publishing a pull request.
- Sandbox roles: the planner, coder, reviewer and test containers, the Docker contract, workspace in and out.
Related: REST API for the routes, Runtimes and CLI for the runtime port the sandbox runtime implements, Sandbox and Threat model for security analysis, Deploy runbooks for deployment.
Sources
packages/agent-types/src/factory.ts(FACTORY_LIMITS,FactoryStatus,FactoryRepoPolicy,effectiveGates)packages/agent-workflows/src/workflows/factory.ts,packages/agent-workflows/src/workflows/factory-shared.tsapps/api/src/factory.ts,apps/api/src/config.ts(FACTORY_*)apps/worker/src/factory/config.ts(loadPolicies,loadFactoryConfig),apps/worker/src/factory-main.tsdocs/deploy-factory.md.omc/plans/p3-software-factory.md(sections 0, 4, 5, 6)