software-defence-factory 0.6.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';
@@ -14,6 +14,8 @@ import { admitIncident } from '../factory/incident.mjs';
 import { DEFAULT_DEMO_STATE } from '../factory/paths.mjs';
 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';
 
 try {
   const handled = await bootstrap(process.argv.slice(2));
@@ -32,22 +34,22 @@ 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) {
+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');
-  if (run('git',['-C',repo,'rev-parse','--show-toplevel']) !== repo) throw new Error('--repo must be the Git root');
-  run('git',['-C',repo,'rev-parse','HEAD']);
+  if (runCandidateGit(repo,'rev-parse','--show-toplevel') !== repo) throw new Error('--repo must be the Git root');
+  runCandidateGit(repo,'rev-parse','HEAD');
   const presets={codex:['codex','exec','--json','--ephemeral','--sandbox','danger-full-access','-'],pi:['pi','--mode','json','--print','--no-session','--no-extensions','--skill','/factory-skills'],mock:['node','/opt/factory/mock.mjs']};
   const argv=harness==='custom'?JSON.parse(flags['command-json'] || 'null'):presets[harness];
   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,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.`);
 }
@@ -98,10 +100,10 @@ async function stop() {
   }
   stopContainers(state);console.log('Controller and its labelled containers stopped.');
 }
-async function submit(workflow,spec) {
+async function submit(workflow,spec,sourceRef=flags['source-ref']) {
   if(Buffer.byteLength(spec)>240000)throw new Error('Task exceeds 240 KB');
   const title=workflow==='defence'?'Private incident triage':spec.split('\n').find(s=>s.trim())?.replace(/^#+\s*/, '').slice(0,100)||'Software task';
-  return api(state,'/api/v1/jobs',{workflow,repository:'app',spec,title});
+  return api(state,'/api/v1/jobs',{workflow,repository:'app',spec,title,...(sourceRef===undefined?{}:{source_ref:sourceRef})});
 }
 async function jobAction(action) {
   const id=positional[0];if(!/^job_[a-z0-9]+$/.test(id || ''))throw new Error('A job ID is required');
@@ -118,12 +120,43 @@ async function jobAction(action) {
   }
   // The controller validates the current run and owns reconciliation atomically.
   // A CLI-side stop after a stale snapshot could terminate a newer attempt.
-  await api(state,`/api/v1/jobs/${id}/${action}`,{run_id:current?.id,...(feedback===undefined?{}:{feedback})});
+  await api(state,`/api/v1/jobs/${id}/${action}`,{run_id:current?.id,...(feedback===undefined?{}:{feedback}),...(flags['source-ref']===undefined?{}:{source_ref:flags['source-ref']})});
   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); }
+  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); }
@@ -198,7 +231,7 @@ try {
       input.title=flags.title || input.title;
       if(typeof input.title!=='string'||!input.title.trim()||input.title.length>160)throw new Error('Provide a title of 1–160 characters (use --title for a blank issue)');
       if(flags.workflow==='software'&&!configAt(state).check?.trim())throw new Error('Configure an app check before submitting software work');
-      console.log(JSON.stringify(await api(state,'/api/v1/jobs',{...input,workflow:flags.workflow,repository:'app',model:flags.model || ''}),null,2));
+      console.log(JSON.stringify(await api(state,'/api/v1/jobs',{...input,workflow:flags.workflow,repository:'app',model:flags.model || '',...(flags['source-ref']===undefined?{}:{source_ref:flags['source-ref']})}),null,2));
     } else throw new Error('Use issue list|connection|templates|preview|recommend|draft|create|start|submissions|recover; see help');
   } else if(command==='issues') {
     console.log(JSON.stringify(await listIssues(configAt(state).repo,Number(flags.page || 1)),null,2));
@@ -220,14 +253,14 @@ 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);
     const repo=join(state,'sample-app');
     if(!existsSync(join(state,'factory.json'))) {
-      mkdirSync(repo,{recursive:true,mode:0o700});run('git',['init','-b','main',repo]);
-      writeFileSync(join(repo,'value.txt'),'broken\n');run('git',['-C',repo,'add','value.txt']);
-      run('git',['-C',repo,'-c','user.name=Factory demo','-c','user.email=demo@localhost','commit','-m','Synthetic fixture']);
+      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');
     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.')));
@@ -243,7 +276,9 @@ 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
-  init --repo PATH --harness codex|pi|custom --check "npm ci && npm test"
+  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
@@ -272,15 +307,19 @@ try {
   issue connection | submissions          Inspect provider identity or durable creation receipts
   issue recover --key REQUEST_ID           Reconcile an uncertain creation without another write
   issue start --draft draft.json | --url URL | --file brief.md --title TITLE
-               --workflow software|defence [--model MODEL]
+               --workflow software|defence [--source-ref REF] [--model MODEL]
                                           Create a local issue and start work; no GitHub write
   issues [--page N]                       Browse open project issues, with next_page for more
   recommend --file task.md | --issue URL  Suggest a work type without starting work
   run --file task.md | --issue URL         Submit software (default), or --workflow defence
+       [--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         New build/check/review after a stopped review
+  revise JOB_ID --file feedback.md [--source-ref REF]
+                                          New build/check/review; source stays pinned unless a new ref is explicit
   version                                 Show the active CLI version
   update | update --check                 Update the npm CLI / inspect the latest release
   update --auto on|off                    Control automatic daily CLI updates
@@ -289,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

@@ -32,8 +32,8 @@ shell endpoint or a second scheduler.
 | SSH tunnels | `tunnel` | No tunnel endpoint | None | Client-host ownership; distinguish operator machine from worker |
 | 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 | Controlled-checkout workaround | Not implemented | Not implemented | #28, same recorded source in both interfaces |
-| Trusted PR handoff | Operator applies accepted patch | Not implemented | Not implemented | #29; credentials remain outside jobs |
+| 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 | `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

@@ -23,32 +23,146 @@ The qualification intentionally creates failed, cancelled and interrupted tasks.
 Commit an intentional, reviewed starting point in the application first. Jobs clone committed code only; uncommitted work stays in the source checkout.
 
 ```sh
-software-defence-factory init --repo /absolute/path/to/app --harness codex --check "npm ci && npm test" --state /private/state/my-app --port 7331
+software-defence-factory init --repo /absolute/path/to/app --harness codex --check "npm ci && npm test" --source-ref main --state /private/state/my-app --port 7331
 software-defence-factory install --state /private/state/my-app
 software-defence-factory doctor --state /private/state/my-app
 ```
 
-Verification commands receive `FACTORY_BASE_REVISION`, the resolved 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.
+`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.
 
-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.
+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.
 
-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.
+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.
 
-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
-software-defence-factory run --file task.md --state /private/state/my-app
+software-defence-factory run --file task.md --source-ref main --state /private/state/my-app
 ```
 
 A task should describe the accepted outcome, allowed scope and observable checks. The CLI also accepts `--issue https://github.com/owner/repo/issues/123` for an issue belonging to the configured origin; it uses the operator's existing gh access outside the job. The dashboard supports the same task workflow. Source text and links do not grant additional authority.
 
 ## Review and handoff
 
-Inspect the task's Result, Files and History tabs. Build evidence includes candidate.json, change.patch and the implementation report. Checks and review identify their exact commit and policy hash. Approval revalidates both before writing accepted.json. Request changes creates a new implementation sequence while preserving earlier attempts.
+Inspect the task's Result, Files and History tabs. Task details show the requested source ref, resolved admission SHA and previous source commits when a new base was selected. Build evidence includes candidate.json, change.patch and the implementation report; handoff records its source SHA. Checks and review identify their exact candidate commit and policy hash. Approval revalidates both before writing accepted.json. Request changes preserves the recorded source by default and starts fresh checks/review; an explicit new source ref is retained as a deliberate base change.
 
 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
@@ -107,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.