software-defence-factory 0.7.0 → 0.9.0

package/THIRD_PARTY_NOTICES.md

@@ -152,6 +152,7 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+
 ## @radix-ui/react-compose-refs 1.1.5
 
 MIT License
@@ -574,3 +575,12 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+## Optional browser verification image
+
+The operator-built Playwright runner image installs `playwright` and
+`playwright-core` 1.63.0 from the exact lockfile in `factory/web/` under the
+Apache License 2.0. The original license files are retained in the built image
+under `/opt/factory-web/node_modules/playwright/LICENSE` and
+`/opt/factory-web/node_modules/playwright-core/LICENSE`. Factory does not bundle
+the built browser image in its npm package.

package/bin/software-defence-factory.mjs

@@ -4,7 +4,7 @@ import { resolve, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { createServer } from 'node:net';
-import { ROOT, PINS, DEFAULT_STATE, configAt, save, json, run, stream, digest, api, sleep, stopContainers } from '../factory/lib.mjs';
+import { ROOT, PINS, DEFAULT_STATE, configAt, save, json, run, stream, digest, api, sleep, stopContainers, PUBLICATION_API_TIMEOUT_MS } from '../factory/lib.mjs';
 import { assertInstalledJobImage, installCustomJobImage, installStandardJobImage, inspectImageInstallation } from '../factory/image-install.mjs';
 import { listIssues, readIssue } from '../factory/issue-intake.mjs';
 import { recommendWork } from '../factory/intake.mjs';
@@ -16,6 +16,7 @@ import { bootstrap, registerInstallation, VERSION } from '../factory/updates.mjs
 import { hasService, manageService, serviceDefinition, withServiceOperation, isManagedLaunch } from '../factory/services.mjs';
 import { runCandidateGit } from '../factory/git-environment.mjs';
 import { initializeDemoRepository } from '../factory/demo-fixture.mjs';
+import { probeWebBrowser } from '../factory/web-readiness.mjs';
 
 try {
   const handled = await bootstrap(process.argv.slice(2));
@@ -34,7 +35,7 @@ let state = resolve(flags.state || DEFAULT_STATE);
 if(existsSync(state))state=realpathSync(state);
 const alive = pid => { try { process.kill(pid,0); return true; } catch(error) { if(error.code === 'ESRCH')return false; throw error; } };
 
-function init(repo, harness='codex', check='', port=7331, sourceRef='HEAD') {
+function init(repo, harness='codex', check='', port=7331, sourceRef='HEAD', delivery, inferenceProvider) {
   repo=realpathSync(resolve(repo));
   if (existsSync(join(state,'factory.json'))) throw new Error('Already configured; edit the private factory.json explicitly or choose another --state');
   if ([repo,state,ROOT].some(p=>/[,\n\r]/.test(p))) throw new Error('Paths cannot contain commas or line breaks');
@@ -45,11 +46,11 @@ function init(repo, harness='codex', check='', port=7331, sourceRef='HEAD') {
   if (!argv) throw new Error('Select codex, pi, mock or custom with --command-json');
   if (flags.model && ['codex','pi'].includes(harness)) argv.splice(harness==='codex'?argv.length-1:argv.length,0,'--model',flags.model);
   mkdirSync(state,{recursive:true,mode:0o700});state=realpathSync(state);chmodSync(state,0o700);
-  save(join(state,'factory.json'),{version:1,repo,sourceRef,harness,command:argv,check,port:Number(port),image:PINS.jobImage,network:harness==='mock'?'none':'bridge',timeoutSeconds:1800,memoryMiB:2048,model:flags.model || null,
+  save(join(state,'factory.json'),{version:1,repo,sourceRef,harness,command:argv,check,port:Number(port),image:PINS.jobImage,network:harness==='mock'?'none':'bridge',timeoutSeconds:1800,memoryMiB:2048,model:flags.model || null,...(inferenceProvider?{inferenceProvider}:{}),...(delivery?{delivery}:{}),
     scope:{project:'pilot',service:'app',environment:'test',owner:'operator'}});
   configAt(state);
   writeFileSync(join(state,'worker.token'),randomBytes(32).toString('hex')+'\n',{mode:0o600});
-  writeFileSync(join(state,'model.env'),'# Only inference credentials belong here. Never add GitHub, deploy or cloud credentials.\n',{mode:0o600});
+  writeFileSync(join(state,'model.env'),'# Supported inference settings only. Never add host, forge, deploy, Docker or cloud identity credentials.\n',{mode:0o600});
   registerInstallation(state);
   console.log(`Configured ${state}\nApp files were not changed. Only committed code is cloned into jobs.`);
 }
@@ -124,8 +125,39 @@ async function jobAction(action) {
   console.log(`${action}: ${id}`);
 }
 
+async function publishJob(jobId) {
+  if (!/^job_[a-f0-9]{24}$/.test(jobId || '')) throw new Error('publish requires a Factory JOB_ID');
+  const snapshot=await api(state,'/api/v1/status'),job=snapshot.jobs.find(item=>item.id===jobId);
+  if(!job)throw new Error('Job not found');
+  const current=job.runs.at(-1);
+  const receipt=await api(state,`/api/v1/jobs/${jobId}/publish`,{run_id:current?.id},undefined,{timeoutMs:PUBLICATION_API_TIMEOUT_MS});
+  console.log(JSON.stringify(receipt,null,2));
+}
+
+async function abandonDeliveryJob(jobId) {
+  if (!/^job_[a-f0-9]{24}$/.test(jobId || '')) throw new Error('abandon-delivery requires a Factory JOB_ID');
+  const branchSha = flags['branch-sha'];
+  if (!/^[a-f0-9]{40}$/.test(branchSha || '')) throw new Error('abandon-delivery requires --branch-sha with the inspected remote SHA');
+  const snapshot=await api(state,'/api/v1/status'),job=snapshot.jobs.find(item=>item.id===jobId);
+  if(!job)throw new Error('Job not found');
+  const delivery=job.delivery_status;
+  if(!delivery?.can_abandon)throw new Error('This job has no resolvable pre-write branch collision; inspect status and reconcile unresolved provider effects.');
+  if(branchSha!==delivery.remote_collision?.sha)throw new Error('The supplied branch SHA differs from current status; inspect the current remote branch before resolving.');
+  const result=await api(state,`/api/v1/jobs/${jobId}/abandon-delivery`,{
+    run_id:job.runs.at(-1)?.id,delivery_identity:delivery.identity,branch_sha:branchSha,
+  },undefined,{timeoutMs:PUBLICATION_API_TIMEOUT_MS});
+  console.log(JSON.stringify(result,null,2));
+}
+
 try {
-  if(command==='init') { if(!flags.repo)throw new Error('init requires --repo /path/to/existing/git/repo');if(flags.harness && flags.agent && flags.harness !== flags.agent)throw new Error('--harness conflicts with legacy --agent');init(flags.repo,flags.harness || flags.agent,flags.check,flags.port,flags['source-ref'] || 'HEAD'); }
+  if(command==='init') {
+    if(!flags.repo)throw new Error('init requires --repo /path/to/existing/git/repo');
+    if(flags.harness && flags.agent && flags.harness !== flags.agent)throw new Error('--harness conflicts with legacy --agent');
+    const deliveryFlags=[flags['delivery-provider'],flags['delivery-repository'],flags['delivery-target']];
+    if(deliveryFlags.some(Boolean)&&deliveryFlags.some(value=>!value))throw new Error('Trusted PR delivery requires --delivery-provider github --delivery-repository URL --delivery-target main|dev');
+    const delivery=deliveryFlags.every(Boolean)?{provider:flags['delivery-provider'],repository:flags['delivery-repository'],target:flags['delivery-target']}:undefined;
+    init(flags.repo,flags.harness || flags.agent,flags.check,flags.port,flags['source-ref'] || 'HEAD',delivery,flags['inference-provider']);
+  }
   else if(command==='install')await withServiceOperation('install',install);
   else if(command==='up') { if(hasService(state))await manageService('controller','start',state);else await withServiceOperation('up',up); }
   else if(command==='stop') { if(hasService(state))await manageService('controller','stop',state);else await withServiceOperation('stop',stop); }
@@ -159,8 +191,9 @@ try {
   else if(command==='status') { const snapshot=await api(state,'/api/v1/status');delete snapshot.csrf_token;console.log(JSON.stringify(snapshot,null,2)); }
   else if(command==='doctor') {
     const config=configAt(state),dockerVersion=run('docker',['info','--format','{{.ServerVersion}}']),imageStatus=inspectImageInstallation(state,config);
-    console.log(JSON.stringify({node:process.version,docker:dockerVersion,engineInstalled:imageStatus.installed,image:imageStatus.image,repo:config.repo,harness:harnessOf(config),agent:harnessOf(config),checksConfigured:!!config.check?.trim(),inference:'Not called or verified',qualification:{model:'not assessed',toolchain:'not assessed'},dashboard:`http://127.0.0.1:${config.port}`},null,2));
-    if(!imageStatus.installed)process.exitCode=1;
+    const webVerification=config.webVerification?.enabled?probeWebBrowser(config,state):null;
+    console.log(JSON.stringify({node:process.version,docker:dockerVersion,engineInstalled:imageStatus.installed,image:imageStatus.image,repo:config.repo,harness:harnessOf(config),agent:harnessOf(config),checksConfigured:!!config.check?.trim(),inference:'Not called or verified',qualification:{model:'not assessed',toolchain:'not assessed'},dashboard:`http://127.0.0.1:${config.port}`,...(webVerification?{web_verification:webVerification}:{})},null,2));
+    if(!imageStatus.installed||webVerification&&!webVerification.ready)process.exitCode=1;
   } else if(command==='issue') {
     const action=positional[0], sourceURL=flags.url || flags.github;
     if(action==='list') {
@@ -222,6 +255,8 @@ try {
     if(!flags.file)throw new Error('Use --file incident.json; see factory/examples/incident.json');
     console.log(JSON.stringify(await admitIncident(state,json(resolve(flags.file)),submit)));
   } else if(['approve','cancel','retry'].includes(command))await jobAction(command);
+  else if(command==='publish')await publishJob(positional[0]);
+  else if(command==='abandon-delivery')await abandonDeliveryJob(positional[0]);
   else if(command==='revise')await jobAction('request_changes');
   else if(command==='demo') {
     state=resolve(flags.state || DEFAULT_DEMO_STATE);
@@ -230,11 +265,20 @@ try {
       initializeDemoRepository(repo);
       init(repo,'mock',"test \"$(cat value.txt)\" = fixed",Number(flags.port || 7332));
     } else if(harnessOf(configAt(state))!=='mock')throw new Error('Demo requires a mock configuration');
+    save(join(state,'synthetic-demo.json'),{version:1,createdAt:new Date().toISOString(),purpose:'Disposable Factory runtime qualification only'});
     await withServiceOperation('demo startup',async()=>{await install();await up();});console.log(JSON.stringify(await submit('software','Synthetic installation qualification: fix value.txt. No inference is used.')));
     console.log('Review the synthetic change in the dashboard and approve its handoff.');
   } else if(['version','--version','-v'].includes(command))console.log(VERSION);
   else if(command==='qualify') {
     await stream(process.execPath,[join(ROOT,'scripts/probe-platform.mjs'),state]);
+  } else if(command==='qualify-web') {
+    if(!flags.image)throw new Error('qualify-web requires --image sha256:<local browser image ID>');
+    await stream(process.execPath,[join(ROOT,'scripts/probe-web.mjs'),state,flags.image]);
+  } else if(command==='web') {
+    if(positional[0]!=='probe'||positional.length!==1)throw new Error('Use web probe to execute the configured browser readiness check');
+    const readiness=probeWebBrowser(configAt(state),state);
+    console.log(JSON.stringify(readiness,null,2));
+    if(readiness.enabled&&!readiness.ready)process.exitCode=1;
   } else if(command==='kit') {
     if(!flags.output)throw new Error('kit requires --output NEW_DIRECTORY');
     await stream(process.execPath,[join(ROOT,'scripts/export-kit.mjs'),resolve(flags.output)]);
@@ -243,9 +287,13 @@ try {
   kit --output NEW_DIRECTORY               Export the portable method without a runtime
   demo                                    Install and run a synthetic sample (no model key)
   qualify --state PATH                    Exercise recovery and isolation with a stopped demo job
+  qualify-web --state PATH --image ID     Exercise Playwright Verify with a synthetic delayed-action fixture
   init --repo PATH --harness codex|pi|custom --check "npm ci && npm test" [--source-ref REF]
+       [--inference-provider PROVIDER]
+       [--delivery-provider github --delivery-repository https://github.com/OWNER/REPO --delivery-target main|dev]
   install [--image LOCAL_REF]             Build the standard image, or select an existing local image
   doctor | up | status | stop              Inspect / operate your private installation
+  web probe --state PATH                    Execute the pinned local Chromium readiness probe
   foundation                              Read the operator setup skill; no installation required
   definition | agents | skills            Inspect roles, instructions and installation settings
   inbox | infrastructure | automations    Inspect live tasks, host/worker and automation state
@@ -280,6 +328,8 @@ try {
        [--source-ref REF]                 Pin a configured-repository ref before admission
   incident --file incident.json            Submit a private, read-only incident draft
   approve JOB_ID | cancel JOB_ID           Review gate / stop this attempt
+  publish JOB_ID                          Publish/reconcile the accepted candidate as one draft PR
+  abandon-delivery JOB_ID --branch-sha SHA Resolve an inspected pre-write collision; keep the remote branch
   retry JOB_ID                            Prove stop; retain old checkout and retry
   revise JOB_ID --file feedback.md [--source-ref REF]
                                           New build/check/review; source stays pinned unless a new ref is explicit
@@ -291,7 +341,7 @@ Runtime commands accept --state PATH. Default: ${DEFAULT_STATE}
 Demo default: ${DEFAULT_DEMO_STATE}
 The npm CLI keeps state outside the package; updates wait for stopped installations.
 Dashboard binds only to loopback; use SSH for remote access.
-Setup plan: ${join(ROOT, 'docs/setup.md')}
+  Setup plan: ${join(ROOT, 'docs/setup.md')}
 See docs/quickstart.md for task execution, evidence and recovery.`);
   else throw new Error(`Unknown command: ${command}`);
 } catch(error) {console.error(`Factory: ${error.message}`);process.exitCode=1;}

package/docs/interfaces.md

@@ -33,7 +33,8 @@ shell endpoint or a second scheduler.
 | Method export | `kit --output` | No export endpoint | None | Equivalent download/export preserving staging-only adoption |
 | Synthetic qualification | `demo`, `qualify` | No qualification endpoint | Synthetic disclosure only | Explicit separate state; never target an application accidentally |
 | Immutable source admission | `init --source-ref`, `run --source-ref`, `issue start --source-ref`; status and build evidence carry the resolved SHA | `POST /api/v1/jobs` resolves/retains before acknowledgement; shared source metadata in status | New issue and revision forms accept a ref; task detail shows requested ref, resolved SHA and prior source commits | Build/retry use retained objects; revisions keep the recorded source unless a new ref is explicit; legacy source remains unknown |
-| Trusted PR handoff | Operator applies accepted patch | Not implemented | Not implemented | #29; credentials remain outside jobs |
+| Trusted PR handoff | `publish JOB_ID` publishes/reconciles; `abandon-delivery JOB_ID --branch-sha SHA` records a checked local resolution for a pre-write branch collision | Authenticated `POST /api/v1/jobs/:id/publish` and `/abandon-delivery`; shared receipt, conflict identity and removal policy | Publish/reconcile and explicit “Abandon local delivery; keep remote branch” actions share controller state; errors/results and inspected branch identity are visible | New writes require matching protected Codex/Pi build/review provenance, deterministic verify/handoff provenance, non-synthetic bound artifacts and a qualified GitHub Actions tree. Shared delivery status exposes `workflow_qualification` and the same reason blocks CLI/API/dashboard capability and publication/retry. Candidate workflow changes, unsupported triggers/syntax, or active generated-push, selected-ref-dispatch and PR jobs with write/secrets/environment/OIDC/deploy access, self-hosted runners or ambiguous privileged guards refuse trusted writes. Supported ASCII guard comparisons follow GitHub's case-insensitive string semantics; unknown PR refs, non-ASCII mismatches, and glob/escaped branch filters cannot prove a privileged job inactive. The shared summary's `action_mode` distinguishes new/resumable publication from read-only reconciliation and drives idle and pending task button wording. Branch-only collisions and unknown/abandoned states offer neither; known PR receipts and pending PR-creation checkpoints retain read-only reconciliation. Abandonment checks the current run, saved intent, exact branch head and absence of an associated PR; it writes no provider data, preserves the remote branch/evidence, disables republishing and permits local removal. Uncertain effects and incompatible evidence stay blocked. Destination remains private operator config; patch-only remains default |
+| Optional trusted web verification | `web probe` performs a real local Chromium interaction; `doctor` reports readiness | Verify stores a shared story summary and protected JSON artifact in the run | Task history shows passed/failed/unavailable/inconclusive plus tool, candidate, policy and story hashes | Disabled by default. Required operator stories and Playwright/Chromium image ID are frozen in attempt policy. Linux Chromium proof cannot qualify native/mobile OS behavior; see [the browser contract](web-verification.md) |
 
 The current generic task form can name the Defence workflow; that is not a
 substitute for the CLI's validated incident admission. Treat the typed intake

package/docs/quickstart.md

@@ -28,15 +28,47 @@ software-defence-factory install --state /private/state/my-app
 software-defence-factory doctor --state /private/state/my-app
 ```
 
-`init --source-ref` selects the configured default ref (`HEAD` when omitted). Each job resolves that ref, or an explicit `--source-ref` on `run`/`issue start`, in the configured repository and durably retains its commit before acknowledging admission. The CLI and dashboard show the requested ref and resolved SHA. Task text and reference links do not select a repository or ref.
+`init --source-ref` selects the configured default ref (`HEAD` when omitted). Each job resolves that ref, or an explicit `--source-ref` on `run`/`issue start`, in the configured repository and durably retains its commit before acknowledging admission. It records the canonical GitHub origin identity when available; the CLI and dashboard show the requested ref and resolved SHA. Task text and reference links do not select a repository, source ref or PR target.
 
 Verification commands receive `FACTORY_BASE_REVISION`, the resolved admission commit recorded as the candidate base. Diff-based checks should compare against this revision; the isolated checkout has no origin remote. The value comes from protected controller metadata, not the task text.
 
 Replace the check with the application's actual verification command. `init` does not edit the app, copy global skills or start work. It creates factory.json, worker.token and model.env with private permissions. Each installation has one repository and a distinct state path/port. `--harness pi` selects Pi; `--harness custom --command-json '["executable","argument"]'` selects an available command in the job image. The bundled image provides Node, Git, Codex and Pi. Other toolchains require an intentionally built compatible image; do not claim Rust/mobile/browser capabilities from this image alone.
 
-Configure inference credentials in the private model.env file. Do not copy the operator's entire account environment or authentication folders. Codex uses its supported API credential environment; Pi uses the selected provider's configuration. Use `--model` with init for a specific model. Task-level model overrides are supported only for Codex/Pi and do not prove that the provider serves that model.
-
-A local model endpoint must be reachable from inside the job container. Host loopback addresses do not automatically refer to the host from Docker. Configure and qualify the chosen adapter/network path before dispatch; this package does not automatically expose Ollama or import its models.
+Configure supported inference settings in the private `model.env` file. It
+rejects unrelated names such as `DEPLOY_TOKEN`; do not copy the operator's
+account environment or authentication folders. Codex receives only its OpenAI
+settings. Pi receives only the selected provider's settings. Set
+`--inference-provider PROVIDER` during `init`, or pin an operator-selected
+`provider/model` with `--model`; if multiple provider credential groups are in
+`model.env`, an explicit provider is required. Task-level model overrides never
+select a credential group. See the `inferenceProvider` entry in private
+`factory.json` when editing trusted installation configuration directly.
+
+Installations using the existing Codex account-auth command may also put its
+single-line JSON object in `FACTORY_CODEX_AUTH_JSON` in private `model.env`.
+Factory validates that value as JSON and gives it only to the selected Codex
+build/review/defence worker through a temporary private env file; the configured
+operator command that consumes this setting must materialize its temporary
+native `auth.json` before invoking Codex; the bundled stock `codex exec` does
+not do this by itself. Pi never receives this setting, including with the OpenAI provider, and
+deterministic checks and output artifacts do not receive it. Keep `model.env`
+private with mode `0600`; do not copy account folders or place the value in a
+task, source file or report. This setting does not replace provider API-key or
+local OpenAI-compatible endpoint configuration.
+
+Factory's Pi provider identifiers are `anthropic`, `azure-openai-responses`,
+`cerebras`, `cloudflare-ai-gateway`, `cloudflare-workers-ai`, `deepseek`,
+`google`, `groq`, `huggingface`, `kimi-coding`, `minimax`, `minimax-cn`,
+`mistral`, `openai`, `opencode`, `opencode-go`, `openrouter`,
+`vercel-ai-gateway`, `xiaomi`, `xiaomi-token-plan-ams`,
+`xiaomi-token-plan-cn`, `xiaomi-token-plan-sgp`, `xai` and `zai`. Factory
+forwards provider API-key and endpoint settings from this map; it does not
+forward OAuth files or ambient cloud identity credentials.
+
+`OPENAI_BASE_URL` remains available for an OpenAI-compatible local endpoint
+selected for Codex; the endpoint must be reachable from inside the job
+container. Host loopback addresses do not automatically refer to the host from
+Docker. The package does not automatically expose Ollama or import models.
 
 ```sh
 software-defence-factory up --state /private/state/my-app
@@ -51,6 +83,86 @@ Inspect the task's Result, Files and History tabs. Task details show the request
 
 The source application is not changed and no branch, PR, merge or deployment is published automatically. A reviewed change.patch can be checked and applied with `git apply --check` and `git apply` on an appropriate branch at its recorded base revision; then follow the application's normal integrated checks and delivery policy.
 
+### Optional trusted PR delivery
+
+Patch-only remains the default. To enable the first delivery provider, select a
+canonical GitHub origin and an explicit target while initializing the private
+installation:
+
+```sh
+software-defence-factory init --repo /absolute/path/to/app --harness codex \
+  --check "npm ci && npm test" --source-ref main \
+  --delivery-provider github \
+  --delivery-repository https://github.com/OWNER/REPO \
+  --delivery-target main --state /private/state/my-app
+```
+
+Use `dev` only when it is the intended target. The source ref (`main` above)
+and PR target are separate settings. The configured GitHub repository must
+match the canonical origin captured at admission; a later repository rename or
+remote change blocks delivery. Configure this before admitting work because a
+configuration change invalidates earlier check/review/approval policy evidence.
+Unknown providers and installations without `delivery` configuration keep the
+patch-only flow.
+
+After the ordinary check, independent review and operator approval complete,
+use **Publish accepted candidate as draft PR** in task details or run:
+
+```sh
+software-defence-factory publish JOB_ID --state /private/state/my-app
+```
+
+Trusted publication requires protected per-run execution records for native
+Codex/Pi build and review plus deterministic verification and handoff, bound to
+non-synthetic candidate, check and review artifacts. Mock qualification remains
+local exploration and cannot be published; missing or inconsistent provenance
+keeps the action unavailable in status, CLI, API and dashboard. A saved intent
+is checked again before new provider writes. Known PR receipts and PR-creation
+checkpoints still allow read-only reconciliation.
+
+New writes also require the shared GitHub Actions qualification described in
+[setup](setup.md#optional-trusted-pr-delivery) and [recovery](recovery.md#trusted-pr-delivery).
+Unsupported or candidate-changed workflows keep publication unavailable in
+status, CLI, API and dashboard; the accepted patch remains available for normal
+manual delivery.
+
+For `push`, the qualifier evaluates branch filters when either `branches` or
+`branches-ignore` is declared, even alongside tag filters; tag-only filters do
+not activate a generated branch push. Docker phase logs redact literal selected
+inference credential values before retention. Mounted worker reports are
+redacted after the container stops and before promotion; if shutdown is
+uncertain, recovery handles them after confirming the stop. This is a bounded
+output filter, not general protection against encoded or transformed values.
+
+The controller uses its existing `gh` identity. GitHub credentials are never
+copied to `model.env` or mounted into jobs. The intent, generated branch, PR
+identity, actual base/head/tree and triggered PR check results appear in the
+same job. Unknown and pending checks remain visible and are not reported as
+success. GitHub's raw `success`, `skipped` and `neutral` conclusions are
+non-blocking in the Factory check summary; skipped and neutral remain visibly
+distinct from an executed passing check. Unknown conclusions and incomplete
+pagination keep the aggregate unknown. This summary does not determine branch
+protection requirements or grant merge authorization. See [GitHub's required
+status check guidance](https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks).
+Repeating `publish` refreshes/reconciles the same branch and PR; it does not
+create a second PR or overwrite a changed branch. The CLI gives this bounded
+multi-request action ten minutes; branch resolution uses the same bound and
+other API calls keep their five-second deadline. If a client deadline expires,
+inspect status and repeat `publish` to reconcile or recheck the reported branch
+identity before `abandon-delivery`. Delete issue stays disabled while delivery
+is unresolved, and the controller enforces the same guard on its API.
+Publication does not merge, integrate, release or deploy. See [delivery
+recovery](recovery.md#trusted-pr-delivery).
+
+If status reports a reserved branch collision at the untouched `intent` stage,
+inspect that branch in GitHub first. The task detail action **Abandon local
+delivery; keep remote branch** or `abandon-delivery JOB_ID --branch-sha SHA`
+records only a local resolution after the controller confirms the same branch
+head and no associated PR. It preserves the remote branch and accepted evidence,
+permits local issue removal, and permanently disables publication for that
+delivery record. Changed identities, PRs and uncertain provider effects remain
+blocked; see [recovery](recovery.md#trusted-pr-delivery).
+
 ## Remote access and operation
 
 ```sh
@@ -109,8 +221,11 @@ is tested at 100%; changing browser zoom is separate from a project theme.
 ## Environment
 
 Factory does not load a repository `.env` file. Configure the private
-`factory.json` through `init`; put inference credentials only in its private
-`model.env`. A repository `.env.example` is unnecessary for this CLI. Optional
+`factory.json` through `init`; put supported inference settings only in its
+private `model.env`. A provider allowlist selects the configured Codex/Pi
+settings before a worker starts; unrelated host, forge, deployment, cloud
+identity and application variables are rejected. A repository `.env.example`
+is unnecessary for this CLI. Optional
 process settings are `SDF_AUTO_UPDATE=0` (skip automatic CLI update checks),
 `XDG_STATE_HOME`, `XDG_DATA_HOME` and `XDG_CONFIG_HOME` (user-owned state, release
 and service locations). They must be exported in the process environment.

package/docs/recovery.md

@@ -6,7 +6,8 @@ Use `status --state PATH` and the private supervisor.log to identify the active
 - An unconfirmed running attempt becomes `interrupted` on controller restart. It is never silently considered successful.
 - Admission resolves the configured source ref or an explicit `--source-ref` in the configured repository, records its identity/ref/SHA in private job metadata and retains its Git objects under that job. Build and retry restore from this retained revision; moving or deleting the source ref does not select a new commit.
 - `retry JOB_ID` verifies retained objects and reconciles the previous process group and containers. A missing/corrupt retained source, live writer or unknown process blocks retry. For a new build/defence attempt, the prior checkout is retained as previous-checkout-*.
-- A failed verification can retry the same unchanged candidate after the check environment is repaired. A changed candidate needs a fresh verification/review sequence.
+- A forced host/controller stop can leave the selected inference env file in the private attempt directory. Normal executor cleanup removes it only after a Docker listing confirms the named container is absent. Retry/reconciliation removes a leftover copy only after the prior process group is confirmed stopped and a Docker listing confirms the labelled containers are absent; a `docker rm` or `docker stop` exit alone does not prove shutdown. If identity, a Docker probe or shutdown is uncertain, the recovery fence and file remain; do not clean it manually while a worker may still be active. After shutdown is confirmed, recovery also redacts the fixed phase reports and log using the selected environment values before removing the env file.
+- Retry repeats the stopped phase. A failed verification may retry the same candidate when its policy is unchanged and the check can now pass. If the check or execution policy changed after build, retrying verify/review cannot reuse the earlier build for handoff; handoff remains blocked. Preserve that failed attempt, then use an eligible requested revision or submit a replacement task to build under the current policy. Do not edit SQLite or acceptance evidence to bypass the guard.
 - A requested revision keeps the recorded source by default, retains previous evidence and starts a new build with accumulated feedback. Supplying a deliberate new `--source-ref` resolves and retains that base before the action; prior source metadata stays in history, and the new build gets fresh checks and review.
 - Removing a stopped task from the dashboard hides its queue record. Private artifacts and its deleted_at record remain on disk; this is not secure erasure.
 
@@ -17,12 +18,32 @@ For backup, stop the installation and copy the complete private state directory,
 Earlier experimental engines use a different journal. Start a new state directory for the native 0.3 runtime; preserve old journals separately. There is no automatic import of their jobs or approval state.
 
 Verification cleanup makes owned scratch directories traversable before removing
-them and never follows their symlinks. It runs only after container stop is
-confirmed. If a filesystem error still prevents cleanup, the attempt fails and
-retains the original check exit and private log path alongside the cleanup error.
+them and never follows their symlinks. The executor and recovery paths remove
+`check-workspace` only after Docker confirms the named container is absent; a
+client exit, failed remove or failed/unknown probe does not establish shutdown.
+While shutdown is uncertain, the scratch directory and active recovery fence
+remain. Ordinary reconciliation removes scratch after the process and labelled
+containers are confirmed stopped. If a filesystem error still prevents cleanup,
+the attempt fails and retains the original check exit and private log path
+alongside the cleanup error.
 Inspect that retained attempt before manual removal; never substitute the source
 candidate path for the scratch path.
 
+When trusted web verification is enabled, Verify keeps the copied check output
+as disposable preview scratch and creates separate preview and browser
+containers. The preview uses `network none`; the browser shares only that exact
+preview's isolated network namespace for loopback. Their mounts and PID
+namespaces remain separate, and only the browser mounts its private result and
+screenshot directory. The `web-policy.json`, preview scratch, browser output
+and active fence remain until both exact labelled containers are confirmed
+removed. Normal stop/retry recovery reconciles all Factory-labelled containers
+before removing those files. An unknown stop, deadline or cancellation keeps
+the state and fence for recovery. A missing browser, unsupported Linux
+capability, interrupted story or malformed evidence blocks acceptance; never
+retry around a retained writer or reuse earlier story evidence for a changed
+candidate or policy. Browser traces and screenshots are private evidence and
+are presented through the shared interfaces. See [the web contract](web-verification.md).
+
 ## Review feedback or phase retry
 
 Use **Request changes** on a failed software review only when its validated
@@ -67,6 +88,24 @@ agent reports, passing checks or review. Nonzero exits and missing/malformed
 reports still fail closed. Process termination during a host crash can leave
 incomplete logs and an interrupted attempt; apply process reconciliation above.
 
+Before retention, Docker stdout/stderr logs have exact selected inference
+credential values replaced. Mounted reports (`agent-report.md`, `review.json`,
+`incident-report.json`) are sanitized after the phase container is confirmed
+absent; if shutdown is uncertain, they remain in the private attempt directory
+and ordinary recovery sanitizes them after confirming the stop. Filtering
+includes selected API-key, token, secret, password and credential settings plus
+credential fields inside selected Codex auth JSON. Reports are opened without
+following symlinks and with nonblocking access before descriptor type checks, so
+special files such as FIFOs are refused promptly. An unsafe or oversized report
+cannot be promoted. If filtering cannot complete, recovery retains the selected
+inference file and active fence; a repeated recovery remains blocked until the
+fixed owned report can be safely filtered. Once process and container shutdown
+are confirmed, repair or replace that report and retry ordinary recovery so it
+can sanitize the output before removing the selected file and fence. This
+bounded filter does not detect encoded or transformed values and does not
+rewrite candidate files or patches; it is not a general data loss prevention
+control.
+
 ## Recorded execution profiles
 
 Before each attempt executes, the controller freezes its effective configuration
@@ -126,3 +165,159 @@ Use `issue submissions` and `issue recover --key REQUEST_ID` against the same
 controller state. Recovery reads the original provider using the original
 identity; it does not publish again. Do not use a new request key to retry an
 uncertain write. See [provider ownership and recovery limits](integrations.md).
+
+## Trusted PR delivery
+
+Delivery is available only for an accepted software job with current source,
+candidate, check, independent review and approval records. Trusted publication
+also requires matching private per-run execution records: native Codex/Pi for
+build and review, deterministic verification and handoff, and explicitly
+non-synthetic bound candidate/check/review artifacts. Missing, unknown,
+synthetic or inconsistent evidence is not publication proof. Status, CLI, API
+and dashboard use the same guard. The private operator configuration pins the
+GitHub repository and target; task text and worker reports cannot provide
+either. The controller stores the intent and remote branch/PR identifiers in
+the job row before it writes. Status and task details show the receipt
+separately from integration or deployment.
+
+Inspect the same installation before recovery:
+
+```sh
+software-defence-factory status --state /private/state/project
+software-defence-factory publish JOB_ID --state /private/state/project
+```
+
+After a lost response or controller restart, repeat `publish`. The controller
+reads the exact configured target, generated branch and PR before attempting a
+missing stage. A matching branch/PR is reused; a different remote head, target,
+repository or collision is preserved and blocks recovery. It never force-pushes,
+rebases, creates a second PR to avoid an uncertain response, or merges. Restore
+the original trusted repository/target configuration if it changed; do not
+redirect a saved intent.
+
+Before any new content, branch or PR write, a saved intent is rechecked against
+the protected run profiles and linked artifacts. A mock/synthetic record cannot
+authorize a new write on retry. A known receipt or PR-creation checkpoint can
+still use read-only provider reconciliation; if that cannot establish the
+existing effect, the uncertain record remains blocked from further writes.
+
+Before advertising or attempting a new write, status and the shared publisher
+qualify the exact accepted Git trees again. Factory reads the immutable admitted
+base commit and reconstructs the accepted candidate tree from the protected,
+digest-bound patch. Added, changed, deleted or symlinked
+`.github/workflows/*.yml` and `*.yaml` definitions block trusted publication.
+Every base workflow must parse with the bundled YAML parser and use the
+supported literal `push`, `pull_request`, `pull_request_target` or
+`workflow_dispatch` trigger subset; dispatch inputs and other events such as
+`workflow_run` or `workflow_call` are unsupported. A manual dispatch is
+evaluated with the generated branch as its selected ref, as GitHub permits
+dispatching a workflow against a selected branch ([manual workflow runs](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/manually-run-a-workflow)).
+Any declared PR activity type is treated as potentially active for that
+candidate PR. Branch filters are interpreted only when their patterns contain
+ASCII letters, digits, `.`, `_`, `-` or `/`; exact literals are checked against
+the generated branch and configured target. Other patterns are treated as
+possible matches. This includes `*`, `**`, `?`, `+`, `[]`, `!` and escaped
+characters from GitHub's [filter syntax](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#filter-pattern-cheat-sheet).
+Path filters are also treated as possible matches.
+
+Conditions support only `&&`-joined `==`/`!=` comparisons against quoted
+strings using `github.ref`, `github.event_name`, `github.head_ref`,
+`github.base_ref` or `vars.NAME`; `||`, functions and other contexts are
+refused. Supported ASCII string comparisons follow GitHub's case-insensitive
+[expression semantics](https://docs.github.com/en/actions/reference/workflows-and-actions/expressions).
+Non-ASCII mismatches stay unknown rather than guessing Unicode case folding.
+For `pull_request`, `github.ref` stays unknown because the future merge ref
+cannot be established from a guessed PR number. Unknown comparisons cannot
+prove a privileged job inactive. Dynamic permissions, malformed YAML and
+ambiguous guards block publication with a reason while leaving patch delivery
+available.
+
+Each job that could run for the generated branch push, a branch-selected
+manual dispatch or a PR event must have explicit effective permissions limited
+to `contents: read` or `none`, a known GitHub-hosted runner, and no secret
+context, protected environment, reusable workflow call, OIDC permission or
+deployment permission. A privileged release job can qualify only when a simple
+literal conjunction proves it cannot run for each matching event. The current
+`ci.yml` main-only release guard is supported. Before any content, branch or PR
+write, the existing provider readback still confirms that the configured
+target commit and tree are the exact accepted base. Active jobs must use one of
+the supported literal runner labels (`ubuntu-latest`,
+`ubuntu-22.04`, `ubuntu-24.04`, `ubuntu-26.04`, `windows-latest`,
+`windows-2022`, `windows-2025`, `macos-latest`, `macos-14`, `macos-15` or
+`macos-26`). External action steps must be local or pinned to an immutable
+commit SHA or container digest.
+
+This bounded check does not establish that all CI is safe. It does not inspect
+repository/organization rules, webhooks, external CI or other organization
+automation, nor does it audit the behavior of referenced third-party actions.
+Unsupported cases refuse trusted publication and leave normal local checks,
+review, approval and manual patch delivery available.
+
+After publication is confirmed, readback follows the saved PR identity and
+records its current open draft/ready, closed or merged state and checks. This
+read-only refresh does not require the source branch to remain after closure or
+the PR base commit to equal today's target commit. It still checks the saved
+repository, target and branch names, PR head, and accepted delivery commit's
+tree and parent. A changed identity or candidate stays a visible conflict; a
+provider outage retains the last known publication receipt. First publication
+continues to require the accepted current base and an open draft PR.
+
+The dashboard offers reconciliation for saved `intent`, `publishing`,
+`uncertain` and safely retryable `blocked` checkpoints. Legacy accepted jobs
+without candidate-bound check, review and approval evidence are labelled
+unverified and cannot be published. Deleting an issue with any unconfirmed
+delivery record is blocked in the dashboard and controller API; inspect or
+reconcile the saved remote effect before removing the job. A confirmed
+`published` receipt is no longer unresolved.
+
+The shared capability advertises new publication only with ready evidence and
+no saved delivery or a known resumable write state. A branch-only `conflict`
+has no publish action; inspect it and use explicit local abandonment only
+after the exact branch head and absence of an associated PR are confirmed.
+Conflicts with a saved PR receipt and pending PR-creation checkpoints retain a
+read-only reconciliation action. Unknown and abandoned delivery states cannot
+advertise or start publication.
+
+The shared delivery status marks each available PR action as `publish` or
+`reconcile`; task details use that mode for idle and pending button wording.
+While a request is pending, publication shows “Publishing…” and read-only
+recovery shows “Reconciling…”. A conflicted record with a saved PR receipt
+therefore stays visibly a readback action.
+
+A collision found while the record is still at `intent` is known to precede
+provider writes. Inspect the exact branch in GitHub, then use the task action
+**Abandon local delivery; keep remote branch**, or confirm its current head with
+the CLI:
+
+```sh
+software-defence-factory status --state /private/state/project
+software-defence-factory abandon-delivery JOB_ID --branch-sha INSPECTED_SHA --state /private/state/project
+```
+
+The controller checks the latest run, saved delivery identity, current branch
+head and exact repository/target, then confirms that no PR is attached. It
+records the inspected identity and local resolution in the job row. It does not
+write, update or delete the remote branch or create/accept a PR. The `abandoned`
+state disables later publication and permits local issue removal while retaining
+the delivery record, run history and evidence. A stale or changed branch, any
+associated/unknown PR, changed destination, later delivery stage or uncertain
+provider effect remains blocked; reconcile or inspect it before taking another
+action.
+
+CLI publication and branch-resolution requests have a ten-minute deadline
+because they can require multiple provider requests. Other CLI API requests
+keep their five-second deadline. If the client reaches its deadline, inspect
+`status` after the controller action finishes. Repeat `publish` to reconcile a
+publication; repeat `abandon-delivery` only after inspecting the currently
+reported branch identity.
+
+The receipt reads the exact PR head's check runs and commit statuses. Raw
+conclusions are retained. `success`, `skipped` and `neutral` do not make the
+aggregate fail, while skipped/neutral are distinct from an executed passing
+check. `pending`, `unknown`, failed and unavailable remain distinct; unknown
+conclusions and incomplete pagination stay unknown. This aggregate does not
+establish required-check completeness or merge authorization. A target/base,
+candidate or policy change requires fresh applicable checks, review and
+approval; do not edit SQLite or acceptance evidence to bypass the guard. A stale
+target after branch creation leaves that unique branch for inspection and does
+not open a PR. A PR does not imply integration or deployment.