software-defence-factory 0.7.0 → 0.8.0

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';
@@ -34,7 +34,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 +45,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 +124,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); }
@@ -222,6 +253,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);
@@ -244,6 +277,8 @@ try {
   demo                                    Install and run a synthetic sample (no model key)
   qualify --state PATH                    Exercise recovery and isolation with a stopped demo job
   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
   foundation                              Read the operator setup skill; no installation required
@@ -280,6 +315,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 +328,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,7 @@ 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 |
 
 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,9 +18,14 @@ 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.
 
@@ -67,6 +73,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 +150,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.

package/docs/setup.md

@@ -155,11 +155,79 @@ model servers, public listeners, Docker socket mounts or whole account folders.
 Cloud inference likewise needs a real provider/model connectivity check without
 printing credentials. A model-list/health response is connectivity evidence;
 qualifying model output requires a separately accepted bounded task.
+Store only supported inference settings in `model.env`; jobs reject unrelated
+names such as deployment credentials. Codex receives its OpenAI setting group,
+and Pi receives only its operator-selected provider group. Use
+`--inference-provider` with `init` when Pi's provider is not encoded in the
+operator-configured model name or when multiple provider groups are stored.
+An installation already using Codex account auth may set the validated
+`FACTORY_CODEX_AUTH_JSON` single-line JSON value in private `model.env`; only
+Codex agent phases receive it. Pi and checks do not. See the [quickstart
+inference guidance](quickstart.md#connect-an-application) for constraints.
 
 Checkpoint: record the exact source revision, image ID, check command, resource
 limits, inference connectivity and CI result. Keep product controllers stopped
 until their tasks are explicitly ready to run.
 
+### Optional trusted PR delivery
+
+Patch-only handoff is the default. When the operator intends to enable GitHub
+delivery for this installation, configure the exact canonical repository and
+target while initializing it, for example:
+
+```sh
+software-defence-factory init --repo /absolute/path/to/app --harness pi \
+  --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
+```
+
+The admitted source ref and PR target are independent. Only `main` and `dev`
+are supported target choices in this release. The destination must match the
+canonical origin retained at admission. A changed/renamed origin, moved target
+base or changed Factory policy blocks delivery until fresh applicable evidence
+exists. Configure this before admitting work. Unknown providers remain
+patch-only.
+
+Before enabling trusted PR delivery, confirm the repository workflows fit the
+bounded qualification in [recovery](recovery.md#trusted-pr-delivery). Factory
+compares the immutable admitted base and accepted candidate trees, refuses any
+candidate change to a GitHub Actions workflow, and requires jobs that can run
+for generated-branch pushes, PR events or selected-ref manual dispatches to use
+explicit `contents: read` or `none`, a known GitHub-hosted runner, and no
+secrets, protected environments, OIDC or deploy permissions. Unsupported
+workflow syntax keeps the patch-only path available. Organization hooks and
+other external CI automation remain operator-owned and are not audited by this
+check.
+
+The operator's authenticated `gh` identity stays on the controller. Keep GitHub
+credentials out of `model.env`, project files and worker containers. Do not add
+deploy credentials or a Docker socket for PR delivery. Use only the existing
+authorized repository and the repository access already approved for the
+operator; do not create a new fixture repository or request broader access.
+
+The release lead owns the live provider/browser qualification after installing
+the published candidate separately. Use a separate private state against the
+already authorized Factory repository and `main`; ordinary issue admission,
+checks, independent review and approval must produce the disposable candidate.
+Give its issue a title beginning **[Factory PR handoff proof]**, then use the
+normal **Publish accepted candidate as draft PR** action. Record the job,
+candidate SHA/tree, generated unique branch, exact draft PR, base/head/tree and
+triggered check states. The CLI allows up to ten minutes for this multi-request
+controller action; other CLI API requests retain their five-second deadline.
+If the client deadline expires, inspect status and repeat `publish JOB_ID` so
+the controller can reconcile its saved intent. Restart the installed controller
+and repeat `publish JOB_ID`; verify the same branch and PR head are read back
+and no second PR appears. Delete issue is disabled while the delivery is
+unresolved, and the controller rejects the same removal through its API. Leave
+pending/unknown checks labelled as such. After inspection, close the proof PR
+without merging its fixture change. Do not publish a worker candidate from
+inside its sandbox.
+
+Mocks exercise controller and receipt behavior only. They are not live GitHub
+publication or browser proof; record each separately in [qualification](proof.md).
+
 ## 5. Enable only the intended background services
 
 A newly initialized state has no jobs. Before adopting older state, establish
@@ -242,6 +310,8 @@ Copy this private completion record into the installation's handoff:
 | History and intentionally stopped products preserved | Pending | |
 | Backups, logs, stop/update/rollback owner and guide | Pending | |
 | First bounded application task | Not started | Separate task authority and proof |
+| Optional trusted PR provider and target explicitly configured, or patch-only retained | Pending | |
+| Release lead live disposable Factory draft PR/readback/restart/close proof | Not started | Separate from mocked provider tests |
 
 Use Pass, Fail or Not applicable with a reason; never infer success from an
 installed file. Keep host identities, credentials, raw logs and customer details

package/factory/delivery-provider.mjs

@@ -0,0 +1,20 @@
+import { githubDeliveryProvider } from './providers/github-delivery.mjs';
+
+// Provider selection is a trusted installation setting. Unknown providers do
+// not get guessed URLs, credentials or a write path; they remain patch-only.
+export function deliveryProvider(config, integrations = {}) {
+  const provider = config.delivery?.provider;
+  if (provider !== 'github') return { id: provider || null, supported: false };
+  return integrations.deliveryProvider || githubDeliveryProvider();
+}
+
+export function deliveryProviderInfo(config, provider) {
+  const enabled = provider?.supported === true && config.delivery?.provider === provider.id;
+  return {
+    enabled,
+    mode: enabled ? 'trusted_pr' : 'patch_only',
+    provider: config.delivery?.provider || null,
+    repository: enabled ? config.delivery.repository : null,
+    target: enabled ? config.delivery.target : null,
+  };
+}