software-defence-factory 0.6.0 → 0.7.0

package/bin/software-defence-factory.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,18 +34,18 @@ 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') {
   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,
     scope:{project:'pilot',service:'app',environment:'test',owner:'operator'}});
   configAt(state);
   writeFileSync(join(state,'worker.token'),randomBytes(32).toString('hex')+'\n',{mode:0o600});
@@ -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,12 @@ 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}`);
 }
 
 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');init(flags.repo,flags.harness || flags.agent,flags.check,flags.port,flags['source-ref'] || 'HEAD'); }
   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 +200,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));
@@ -225,9 +227,7 @@ try {
     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 +243,7 @@ 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]
   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 +272,17 @@ 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
   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

package/docs/interfaces.md

@@ -32,7 +32,7 @@ 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 |
+| 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 |
 
 The current generic task form can name the Defence workflow; that is not a

package/docs/quickstart.md

@@ -23,12 +23,14 @@ 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. The CLI and dashboard show the requested ref and resolved SHA. Task text and reference links do not select a repository or ref.
+
+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.
 
@@ -38,14 +40,14 @@ A local model endpoint must be reachable from inside the job container. Host loo
 
 ```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.
 

package/docs/recovery.md

@@ -4,9 +4,10 @@ Use `status --state PATH` and the private supervisor.log to identify the active
 
 - A normal `stop` signals the controller, waits for the executor process group, removes its labelled containers and retains the database and artifacts.
 - An unconfirmed running attempt becomes `interrupted` on controller restart. It is never silently considered successful.
-- `retry JOB_ID` reconciles the previous process group and containers. A live or unknown writer blocks retry. For a new build/defence attempt, the prior checkout is retained as previous-checkout-*.
+- 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 requested revision retains previous evidence and starts a new build from the source repository with the accumulated feedback. It does not reuse earlier approval.
+- 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.
 
 Do not remove active.json merely to unblock a job. Establish that its PID, process group and labelled containers are stopped. PID reuse or missing process identity requires operator investigation. Preserve logs and work before cleanup.
@@ -34,11 +35,14 @@ software-defence-factory revise JOB_ID --file /private/revision.md --state /priv
 
 Feedback must be nonempty and at most 4,000 characters. It is accumulated in the
 bounded job prompt. The controller checks the latest attempt and reconciles its
-processes before starting a new build from the configured source with that
+processes before starting a new build from the retained source commit with that
 feedback. The old checkout moves to `previous-checkout-*`; the old failed review
 and reports remain intact. Verification, review and operator approval are all
 required again. A stale or duplicate request cannot approve or restart a newer
-attempt. **Retry** only repeats the stopped phase and is suitable for a repaired
+attempt. To deliberately change the base, pass `--source-ref REF`; the controller
+resolves and retains it from the same configured repository before changing the
+job record. If the request cannot reconcile, its unlinked source copy is removed.
+**Retry** only repeats the stopped phase and is suitable for a repaired
 execution environment; retrying review cannot change the candidate.
 
 A crashed review without a validated verdict cannot request implementation
@@ -91,6 +95,22 @@ facts in a separate private incident note with evidence paths and unknowns; leav
 the original queue/evidence unchanged. Without that evidence, model/image facts
 cannot be reconstructed reliably.
 
+### Legacy source records
+
+Jobs admitted before source retention keep their historical candidate and review
+evidence without an invented admission-time SHA. A complete existing candidate
+can still pass the normal current candidate, policy, review and approval guards;
+the handoff labels its source **Not recorded (legacy/unknown)**. An unpinned
+queued job is blocked on controller restart, and an unpinned job cannot retry or
+request implementation changes. Submit a replacement job to capture the
+configured or explicit source ref before execution. Do not reconstruct proof
+from the current checkout, issue text or a later ref value.
+
+If a retained store is missing or corrupt, retry and revision stop with an
+explicit source error. Restore the private state backup containing that job's
+retained Git objects, or submit a replacement from a source ref that still
+resolves. The controller never substitutes the mutable configured checkout.
+
 ### Interrupted image selection or controller startup
 
 `installation.lock` serializes image changes with controller startup, including

package/docs/workflows.md

@@ -39,6 +39,12 @@ Conflicting labels request a choice. This is a simple editable suggestion, not a
 model assessment or permission to act. A security code fix can remain Software.
 Both sources support either type; Defence still produces a private draft.
 
+The **Source ref** option applies to the configured local Git repository. Leave
+it blank to use the configured default ref, or enter a branch, tag, `HEAD` or
+full commit SHA. The controller resolves it and retains the commit before
+admitting the job; the task and any linked issue cannot select another
+repository. Status and task details show the requested ref and resolved SHA.
+
 Repository templates are read from `.github/ISSUE_TEMPLATE` on the default
 branch through GitHub's API. Markdown templates and YAML markdown, input,
 textarea, dropdown (including multiple choices) and checkboxes are supported.
@@ -75,7 +81,7 @@ software-defence-factory issue submissions --state PATH
 software-defence-factory issue recover --state PATH --key release-board-fix-01
 # Explicit execution, independent of creation:
 software-defence-factory issue start --state PATH --url URL --workflow software
-software-defence-factory issue start --state PATH --file brief.md --title "Investigate supplied evidence" --workflow defence
+software-defence-factory issue start --state PATH --file brief.md --title "Investigate supplied evidence" --workflow defence --source-ref main
 ```
 
 `answers.json` contains `{"title":"Fix the board","answers":{"problem":"..."}}`;
@@ -84,6 +90,10 @@ arrays of exact option labels. `issue create` now publishes only; migrate 0.5.1
 execution scripts to `issue start`. Legacy `run` remains compatible. Typed private
 incident admission remains `incident --file`, distinct from a generic Defence brief.
 `--source github` remains an alias for repository listing; `--github URL` remains a compatibility alias for `--url URL`.
+`run` and `issue start` accept the same `--source-ref`; `init --source-ref` sets
+the configured default. A revision keeps the admitted SHA unless an explicit
+new ref is supplied. Every revision gets a fresh implementation, check and
+review sequence while earlier source records and evidence remain available.
 
 Provider selection and unknown-host behavior are documented in [integrations](integrations.md).
 View repo uses the browser's own login. Factory's provider uses the controller

package/factory/demo-fixture.mjs

@@ -0,0 +1,11 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runCandidateGit } from './git-environment.mjs';
+
+export function initializeDemoRepository(repo) {
+  mkdirSync(repo, { recursive: true, mode: 0o700 });
+  runCandidateGit(repo, 'init', '-b', 'main');
+  writeFileSync(join(repo, 'value.txt'), 'broken\n');
+  runCandidateGit(repo, 'add', 'value.txt');
+  runCandidateGit(repo, '-c', 'user.name=Factory demo', '-c', 'user.email=demo@localhost', 'commit', '-m', 'Synthetic fixture');
+}

package/factory/executor.mjs

@@ -6,6 +6,8 @@ import { ROOT, run, save, json, digest, instanceLabel, stopContainers } from './
 import { incidentFor, validateReport } from './incident.mjs';
 import { BoundedLog } from './bounded-log.mjs';
 import { CodexUsageParser, emptyUsage, usageFields } from './usage.mjs';
+import { assertRetainedSource, publicSourceAdmission, restoreRetainedCheckout } from './source-admission.mjs';
+import { runCandidateGit } from './git-environment.mjs';
 
 const [state, phase] = process.argv.slice(2);
 if(process.getuid()===0)throw new Error('Agent jobs require a non-root controller account');
@@ -15,6 +17,9 @@ if (!['build','verify','review','handoff','defence'].includes(phase)) throw new
 const folder = join(state, 'jobs', job), workspace = join(folder, 'checkout');
 const config = json(join(folder, attempt, 'execution-config.json'));
 const execution = json(join(folder, 'artifacts', attempt, 'execution.json'));
+let sourceAdmission;
+try { sourceAdmission = JSON.parse(process.env.SDF_SOURCE_ADMISSION || 'null'); }
+catch { throw new Error('Protected source admission metadata is malformed'); }
 const policyHash = digest(JSON.stringify(config));
 if (execution.policyHash !== policyHash || execution.phase !== phase) throw new Error('Admitted execution profile does not match this attempt');
 const output = process.env.SDF_OUTPUT_DIR, result = process.env.SDF_STEP_RESULT_PATH;
@@ -29,12 +34,13 @@ for await (const part of process.stdin) {
   prompt += part;
   if (Buffer.byteLength(prompt) > 256000) throw new Error('Task brief too large');
 }
-const gitEnv = { ...process.env, GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null' };
-const git = (...args) => run('git', ['-c','core.hooksPath=/dev/null','-c','core.fsmonitor=false','-C',workspace,...args], { env: gitEnv });
+const git = (...args) => runCandidateGit(workspace, ...args);
 const metadata = () => json(join(folder, 'candidate.json'));
 function candidate() {
   const meta = metadata();
   if (git('rev-parse','HEAD') !== meta.head || git('status','--porcelain')) throw new Error('Candidate changed; create a new task and rerun verification');
+  if (sourceAdmission?.status === 'retained' && (meta.base !== sourceAdmission.resolved_sha || meta.source_admission?.resolved_sha !== sourceAdmission.resolved_sha))
+    throw new Error('Candidate does not use this job’s retained source revision; previous evidence is invalid for the current base');
   return meta;
 }
 function safeRead(path) {
@@ -108,9 +114,12 @@ try {
   if(incident)prompt=JSON.stringify(incident.input);
   if (phase === 'build' || phase === 'defence') {
     if (existsSync(workspace)) throw new Error('Workspace already exists; preserve evidence and create a new task for a fresh build');
-    run('git',['-c','core.hooksPath=/dev/null','-c','core.fsmonitor=false','clone','--no-hardlinks','--',config.repo,workspace], { env: gitEnv });
-    git('remote','remove','origin');
-    save(join(folder,'candidate.json'), { base: git('rev-parse','HEAD'), head: git('rev-parse','HEAD'), synthetic: harnessOf(config) === 'mock' });
+    if (sourceAdmission?.status !== 'retained') throw new Error('Legacy job has no admission-time source revision and cannot build from the current checkout. Submit a replacement job to pin its source.');
+    const retained = assertRetainedSource(state, job, sourceAdmission);
+    restoreRetainedCheckout(state, job, sourceAdmission, workspace);
+    const head = git('rev-parse','HEAD');
+    if (head !== retained.sha) throw new Error('Build checkout differs from its admission-time source revision');
+    save(join(folder,'candidate.json'), { base: sourceAdmission.resolved_sha, head, source_admission: publicSourceAdmission(sourceAdmission), synthetic: harnessOf(config) === 'mock' });
   }
   if (phase === 'build') {
     const reports = await container('build', brief('Implement the requested bounded change. Save /output/agent-report.md with actual changes and remaining uncertainty.'), config.command, true, true);
@@ -118,7 +127,7 @@ try {
     if (git('diff','--cached','--stat')) git('-c','user.name=Arcitai Factory','-c','user.email=factory@localhost','commit','--no-verify','-m','Factory candidate');
     // Checks must cover the committed tree, not ignored build products supplied by the agent.
     git('clean','-fdx');
-    const meta = { ...metadata(), head: git('rev-parse','HEAD') };
+    const meta = { ...metadata(), head: git('rev-parse','HEAD'), source_admission: publicSourceAdmission(sourceAdmission) };
     save(join(folder,'candidate.json'),meta);
     save(join(output,'candidate.json'),meta);
     writeFileSync(join(output,'change.patch'), git('diff','--binary',meta.base,meta.head) + '\n');
@@ -146,8 +155,9 @@ try {
   } else if (phase === 'handoff') {
     const meta = candidate(), review = json(join(folder,'review.json')), checks = json(join(folder,'checks.json'));
     if (review.verdict !== 'pass' || review.head !== meta.head || !checks.passed || checks.head !== meta.head || checks.policyHash!==policyHash || review.policyHash!==policyHash) throw new Error('Review/checks do not cover candidate and current policy');
-    writeFileSync(join(output,'handoff.md'), `Ready for manual handoff at ${meta.head}.\nNo PR, merge or deployment performed.\nSee docs/quickstart.md for applying the reviewed change.patch to your own branch.\n`);
-    save(join(folder,'accepted.json'), { head: meta.head, acceptedAt: new Date().toISOString() });
+    const sourceSha = meta.source_admission?.resolved_sha || 'Not recorded (legacy/unknown)';
+    writeFileSync(join(output,'handoff.md'), `Ready for manual handoff at ${meta.head}, based on source ${sourceSha}.\nNo PR, merge or deployment performed.\nSee docs/quickstart.md for applying the reviewed change.patch to your own branch.\n`);
+    save(join(folder,'accepted.json'), { head: meta.head, source_admission: meta.source_admission || publicSourceAdmission(null), acceptedAt: new Date().toISOString() });
   } else if (phase === 'defence') {
     const reports = await container('defence', brief('Read-only incident triage. Use supplied evidence only; distinguish observations, hypotheses and unknowns. No live production access is configured. A 500 error is not inherently a security incident. Missing or stale telemetry remains unknown. Write /output/incident-report.json with status needs_review or insufficient_evidence, summary, hypotheses array, recommended_actions array, unknowns array and production_action_taken:false. Write /output/agent-report.md. Never claim root cause or recovery without supporting evidence.'), config.command,false,true);
     const report = JSON.parse(safeRead(join(reports,'incident-report.json')));

package/factory/git-environment.mjs

@@ -0,0 +1,26 @@
+import { run } from './lib.mjs';
+
+// Git reads repository and configuration overrides from its environment before
+// considering -C. Host operations must therefore start from a bounded context
+// rather than inherit the controller's arbitrary GIT_* variables.
+export function hostGitEnvironment(inherited = process.env) {
+  const env = { ...inherited };
+  for (const key of Object.keys(env)) if (/^GIT_/i.test(key)) delete env[key];
+  env.GIT_CONFIG_NOSYSTEM = '1';
+  env.GIT_CONFIG_GLOBAL = '/dev/null';
+  env.GIT_TERMINAL_PROMPT = '0';
+  return env;
+}
+
+export function runHostGit(args, options = {}) {
+  return run('git', args, { ...options, env: hostGitEnvironment() });
+}
+
+export function runCandidateGit(workspace, ...args) {
+  return runHostGit([
+    '-c', 'core.hooksPath=/dev/null',
+    '-c', 'core.fsmonitor=false',
+    '-C', workspace,
+    ...args,
+  ]);
+}

package/factory/issue-provider.mjs

@@ -1,7 +1,7 @@
-import { execFileSync } from 'node:child_process';
 import { githubIssueProvider } from './providers/github.mjs';
 import { readProjectLinks } from './project-links.mjs';
 import { QueueError } from './queue.mjs';
+import { runHostGit } from './git-environment.mjs';
 
 // Selection is local and capability-based. Unknown hosts never receive a GitHub
 // token or a guessed API request. Git checkout/execution does not need an adapter.
@@ -9,7 +9,9 @@ export function issueProvider(repo) {
   if (readProjectLinks(repo)) return githubIssueProvider(repo);
   let host = null;
   try {
-    const remote = execFileSync('git', ['-c', 'core.fsmonitor=false', '-C', repo, 'config', '--local', '--get', 'remote.origin.url'], { encoding:'utf8', timeout:2000, maxBuffer:4096, stdio:['ignore','pipe','ignore'], env:{...process.env,GIT_CONFIG_NOSYSTEM:'1',GIT_CONFIG_GLOBAL:'/dev/null'} }).trim();
+    const remote = runHostGit(['-c', 'core.fsmonitor=false', '-C', repo, 'config', '--local', '--get', 'remote.origin.url'], {
+      timeout: 2000, maxBuffer: 4096, stdio: ['ignore', 'pipe', 'ignore'],
+    });
     if (/^(https?|ssh):\/\//.test(remote)) host = new URL(remote).hostname;
     else host = remote.match(/^(?:[^@\s]+@)?([a-zA-Z0-9.-]+):[^/]/)?.[1] || null;
     if (!/^[a-zA-Z0-9.-]+$/.test(host || '')) host = null;

package/factory/lib.mjs

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
 import { resolve, dirname, join, isAbsolute } from 'node:path';
 import { spawnSync, spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
@@ -46,8 +46,8 @@ export function configAt(state) {
   if (!['none','bridge'].includes(config.network)) throw new Error('network must be none or bridge; host networking is not supported');
   if (typeof config.image !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_./:@-]*$/.test(config.image)) throw new Error('Invalid container image');
   if (typeof config.repo !== 'string' || !isAbsolute(config.repo) || [config.repo,state,ROOT].some(p=>/[,\n\r]/.test(p))) throw new Error('Expected absolute paths without commas or line breaks');
+  if (config.sourceRef !== undefined && (typeof config.sourceRef !== 'string' || !config.sourceRef || Buffer.byteLength(config.sourceRef) > 256 || /[\u0000-\u001f\u007f]/.test(config.sourceRef))) throw new Error('sourceRef must be a Git ref under 256 bytes');
   if (typeof config.check !== 'string' || !config.scope || !['project','service','environment','owner'].every(k=>typeof config.scope[k]==='string'&&config.scope[k].trim())) throw new Error('Missing check or installation scope');
-  if (!existsSync(config.repo)) throw new Error('Configured repository is missing');
   return config;
 }
 export async function api(state, path, body, method) {

package/factory/processes.mjs

@@ -125,7 +125,8 @@ export function executors(state) {
     mkdirSync(output, { recursive: true, mode: 0o700 });
     const resultPath = join(output, 'result.json'), fd = openSync(join(output, 'executor.log'), 'a', 0o600);
     const child = spawn(process.execPath, [join(ROOT, 'factory/executor.mjs'), state, attempt.command], {
-      detached: true, stdio: ['pipe', fd, fd], env: { ...process.env, SDF_JOB_ID: job.id, SDF_RUN_ID: attempt.id, SDF_OUTPUT_DIR: output, SDF_STEP_RESULT_PATH: resultPath },
+      detached: true, stdio: ['pipe', fd, fd], env: { ...process.env, SDF_JOB_ID: job.id, SDF_RUN_ID: attempt.id, SDF_OUTPUT_DIR: output, SDF_STEP_RESULT_PATH: resultPath,
+        SDF_SOURCE_ADMISSION: JSON.stringify(job.source_admission || null) },
     }); closeSync(fd);
     let finish;
     const done = new Promise(resolve => { finish = resolve; });

package/factory/project-links.mjs

@@ -1,4 +1,4 @@
-import { execFileSync } from 'node:child_process';
+import { runHostGit } from './git-environment.mjs';
 
 // Only a canonical public web URL is exposed. Git transports may contain
 // credentials; never return the original remote or derive an owner from a path.
@@ -11,9 +11,8 @@ export function githubProjectLinks(remote) {
 }
 export function readProjectLinks(repo) {
   try {
-    const remote = execFileSync('git', ['-c', 'core.fsmonitor=false', '-C', repo, 'config', '--local', '--get', 'remote.origin.url'], {
-      encoding: 'utf8', timeout: 2000, maxBuffer: 4096, stdio: ['ignore', 'pipe', 'ignore'],
-      env: { ...process.env, GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null' },
+    const remote = runHostGit(['-c', 'core.fsmonitor=false', '-C', repo, 'config', '--local', '--get', 'remote.origin.url'], {
+      timeout: 2000, maxBuffer: 4096, stdio: ['ignore', 'pipe', 'ignore'],
     });
     return githubProjectLinks(remote);
   } catch { return undefined; }

package/factory/queue.mjs

@@ -12,16 +12,22 @@ export class QueueError extends Error { constructor(message, status = 409) { sup
 // One controller owns this database and one executor at a time. Each transition
 // is committed before execution starts; a restart never assumes a result.
 export class JobQueue {
-  constructor(state, { execute, stop, reconcile, prepare, reviewVerdict = () => undefined }) {
+  constructor(state, { execute, stop, reconcile, prepare, reviewVerdict = () => undefined, sourceAdmission }) {
     this.db = new DatabaseSync(join(state, 'jobs.sqlite'));
     this.db.exec('PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000; CREATE TABLE IF NOT EXISTS jobs(id TEXT PRIMARY KEY, data TEXT NOT NULL);');
-    this.execute = execute; this.stop = stop; this.reconcile = reconcile; this.prepare = prepare; this.reviewVerdict = reviewVerdict;
+    this.execute = execute; this.stop = stop; this.reconcile = reconcile; this.prepare = prepare; this.reviewVerdict = reviewVerdict; this.sourceAdmission = sourceAdmission;
     this.maintenanceFile = join(state, 'maintenance.json');
     this.active = null; this.closing = false; this.pumping = false; this.actions = new Set(); this.maintenance = existsSync(this.maintenanceFile);
-    for (const job of this.all()) if (['running', 'cancelling'].includes(job.state)) {
-      job.state = 'interrupted';
-      Object.assign(job.runs.at(-1), { state: 'interrupted', completed_at: now(), error: 'Controller stopped before completion was confirmed.' });
-      this.save(job);
+    for (const job of this.all()) {
+      if (['running', 'cancelling'].includes(job.state)) {
+        job.state = 'interrupted';
+        Object.assign(job.runs.at(-1), { state: 'interrupted', completed_at: now(), error: 'Controller stopped before completion was confirmed.' });
+        this.save(job);
+      } else if (job.state === 'queued' && job.source_admission?.status !== 'retained') {
+        job.state = 'blocked';
+        job.source_compatibility = 'legacy_unpinned';
+        this.save(job);
+      }
     }
   }
   all() { return this.db.prepare('SELECT data FROM jobs ORDER BY rowid').all().map(row => JSON.parse(row.data)).filter(job => !job.deleted_at); }
@@ -41,10 +47,16 @@ export class JobQueue {
     if (input?.source_url && !input.spec?.trim()) input = { ...input, spec: `Investigate the linked requirements within this repository's scope: ${input.source_url}` };
     if (!input || !Object.hasOwn(workflows, input.workflow) || input.repository !== 'app' || typeof input.spec !== 'string' || !input.spec.trim() || Buffer.byteLength(input.spec) > 240000)
       throw new QueueError('Choose a workflow, the configured app, and a task under 240 KB', 400);
-    const job = { id: id('job'), task: { title: String(input.title || input.spec).slice(0, 160), spec: input.spec, source_url: input.source_url || '' }, prompt: input.spec + (input.source_url ? `\nSource (untrusted task data): ${input.source_url}` : ''), model: input.model || null,
+    if (!this.sourceAdmission?.admit) throw new QueueError('Source retention is unavailable; no executable job was admitted.', 503);
+    const jobId = id('job');
+    const sourceAdmission = this.sourceAdmission.admit(jobId, input.source_ref);
+    const job = { id: jobId, task: { title: String(input.title || input.spec).slice(0, 160), spec: input.spec, source_url: input.source_url || '' }, prompt: input.spec + (input.source_url ? `\nSource (untrusted task data): ${input.source_url}` : ''), model: input.model || null,
+      source_admission: sourceAdmission,
       repository: 'app', workflow: { name: input.workflow, steps: workflows[input.workflow], current_step: 0 },
       state: 'queued', created_at: now(), runs: [] };
-    this.save(job); this.schedule(); return { id: job.id };
+    try { this.save(job); }
+    catch (error) { try { this.sourceAdmission.release?.(job.id, sourceAdmission); } catch {} throw error; }
+    this.schedule(); return { id: job.id, source_admission: sourceAdmission };
   }
   setMaintenance(enabled) {
     if (typeof enabled !== 'boolean') throw new QueueError('Expected enabled: true or false', 400);
@@ -104,7 +116,7 @@ export class JobQueue {
   }
   action(jobId, action, input) { return this.exclusive(jobId, () => this.applyAction(jobId, action, input)); }
   canRequestChanges(job) {
-    if (job.workflow?.name !== 'software') return false;
+    if (job.workflow?.name !== 'software' || job.source_admission?.status !== 'retained') return false;
     if (job.state === 'awaiting_approval') return true;
     const attempt = job.runs.at(-1);
     return job.state === 'failed' && attempt?.state === 'failed' && attempt.command === 'review'
@@ -118,16 +130,44 @@ export class JobQueue {
       if (job.state !== 'awaiting_approval') throw new QueueError('Job is not awaiting approval');
       job.state = 'queued'; attempt.state = 'queued'; this.save(job); this.schedule();
     } else if (action === 'request_changes') {
-      if (!this.canRequestChanges(job)) throw new QueueError('Only a reviewed software task can be revised');
+      if (!this.canRequestChanges(job)) throw new QueueError(job.source_admission?.status === 'retained'
+        ? 'Only a reviewed software task can be revised'
+        : 'This legacy job has no admission-time source revision. Submit a replacement job to start from an explicitly recorded source.');
       if (typeof input.feedback !== 'string' || !input.feedback.trim() || input.feedback.length > 4000) throw new QueueError('Provide revision feedback under 4000 characters', 400);
       const revisedPrompt = job.prompt + `\n\nRequested revision: ${input.feedback}`;
       if (Buffer.byteLength(revisedPrompt) > 240000) throw new QueueError('Accumulated revision instructions exceed 240 KB; create a bounded continuation task', 400);
-      await this.reconcile(jobId, 'build');
+      const explicitSource = input.source_ref !== undefined;
+      if (typeof this.sourceAdmission?.validate !== 'function') throw new QueueError('Retained source validation is unavailable; this job was not revised.', 503);
+      const admittedSource = explicitSource
+        ? this.sourceAdmission.admit(job.id, input.source_ref, job.source_admission.repository_identity)
+        : job.source_admission;
+      if (!explicitSource) this.sourceAdmission.validate(job.id, job.source_admission);
+      const changedBase = admittedSource.resolved_sha !== job.source_admission.resolved_sha;
+      let repairRetainedSource = false;
+      if (explicitSource && !changedBase) {
+        try { this.sourceAdmission.validate(job.id, job.source_admission); }
+        catch { repairRetainedSource = true; }
+      }
+      const replaceSourceRecord = changedBase || repairRetainedSource;
+      const nextSource = replaceSourceRecord ? admittedSource : job.source_admission;
+      try { await this.reconcile(jobId, 'build'); }
+      catch (error) {
+        if (explicitSource) this.sourceAdmission.release?.(job.id, admittedSource);
+        throw error;
+      }
+      if (explicitSource && !replaceSourceRecord) this.sourceAdmission.release?.(job.id, admittedSource);
       // A failed review stays failed. Revision feedback must not rewrite its result.
-      attempt.revision = { feedback: input.feedback, requested_at: now() };
+      attempt.revision = { feedback: input.feedback, requested_at: now(), ...(explicitSource ? { requested_source_ref: admittedSource.requested_ref, resolved_source_sha: admittedSource.resolved_sha } : {}), ...(changedBase ? { previous_source_sha: job.source_admission.resolved_sha, new_source_sha: nextSource.resolved_sha } : {}) };
       if (job.state === 'awaiting_approval') Object.assign(attempt, { state: 'succeeded', outcome: 'changes_requested', summary: input.feedback, completed_at: now(), duration_millis: 0 });
+      if (replaceSourceRecord) {
+        job.source_history = [...(job.source_history || []), job.source_admission];
+        job.source_admission = nextSource;
+      }
       job.prompt = revisedPrompt;
-      job.workflow.current_step = 0; job.state = 'queued'; this.save(job); this.schedule();
+      job.workflow.current_step = 0; job.state = 'queued';
+      try { this.save(job); }
+      catch (error) { if (replaceSourceRecord) this.sourceAdmission.release?.(job.id, admittedSource); throw error; }
+      this.schedule();
     } else if (action === 'cancel') {
       if (!['queued', 'running', 'awaiting_approval', 'blocked', 'interrupted'].includes(job.state)) throw new QueueError('Job is already stopped');
       job.state = 'cancelling'; this.save(job);
@@ -138,7 +178,10 @@ export class JobQueue {
       if (attempt) Object.assign(attempt, { state: 'cancelled', completed_at: now() });
       this.save(job);
     } else if (action === 'retry') {
+      if (job.source_admission?.status !== 'retained') throw new QueueError('This legacy job has no admission-time source revision and cannot be retried. Submit a replacement job to capture a source revision explicitly.');
       if (!['failed', 'interrupted', 'cancelled'].includes(job.state)) throw new QueueError('Only a stopped attempt can be retried');
+      if (typeof this.sourceAdmission?.validate !== 'function') throw new QueueError('Retained source validation is unavailable; this job was not retried.', 503);
+      this.sourceAdmission.validate(job.id, job.source_admission);
       await this.reconcile(jobId, attempt?.command);
       job.state = 'queued'; this.save(job); this.schedule();
     } else throw new QueueError('Unknown action', 404);

package/factory/server.mjs

@@ -14,6 +14,7 @@ import { configAt, ROOT } from './lib.mjs';
 import { VERSION } from './updates.mjs';
 import { readProjectLinks } from './project-links.mjs';
 import { attemptPresentation } from './execution-profile.mjs';
+import { SourceAdmissionStore, publicSourceAdmission } from './source-admission.mjs';
 
 function equal(a, b) { return typeof a === 'string' && Buffer.byteLength(a) === Buffer.byteLength(b) && timingSafeEqual(Buffer.from(a), Buffer.from(b)); }
 async function body(request) {
@@ -33,7 +34,8 @@ function artifacts(state, jobId) {
 export function createController(state, adapter = executors(state), integrations = {}) {
   const config = configAt(state), csrf = randomBytes(32).toString('hex');
   const token = readFileSync(join(state, 'worker.token'), 'utf8').trim();
-  const queue = new JobQueue(state, adapter);
+  const sourceAdmission = new SourceAdmissionStore(state, config.repo, config.sourceRef || 'HEAD');
+  const queue = new JobQueue(state, { ...adapter, sourceAdmission });
   const provider = integrations.issueProvider || issueProvider(config.repo);
   const submissions = new IssueSubmissions(queue, provider);
   const projectLinks = readProjectLinks(config.repo);
@@ -50,13 +52,14 @@ export function createController(state, adapter = executors(state), integrations
       const url = new URL(request.url, `http://${request.headers.host}`);
       const authenticated = equal(request.headers.authorization, `Bearer ${token}`) || equal(request.headers['x-factory-session'], csrf);
       if (request.method === 'GET' && url.pathname === '/api/v1/status') {
-        const jobs = queue.all().map(job => ({ ...job, can_request_changes: queue.canRequestChanges(job), runs: job.runs.map(attempt => attemptPresentation({ ...attempt,
+        const jobs = queue.all().map(job => ({ ...job, source_admission: publicSourceAdmission(job.source_admission),
+          source_history: (job.source_history || []).map(publicSourceAdmission), can_request_changes: queue.canRequestChanges(job), runs: job.runs.map(attempt => attemptPresentation({ ...attempt,
           outcome: attempt.outcome || (attempt.state === 'succeeded' ? 'complete' : undefined) }, adapter.usage?.(job, attempt))) }));
         return send(200, { version: 1, runtime_version: VERSION, maintenance: queue.maintenance, workflows: Object.keys(definitions.workflows), commands: [], triggers: [], jobs, csrf_token: csrf,
           infrastructure: { host, controller: { connected: !queue.closing }, workers: [{ id: 'local-executor', name: 'Local worker', host: host.hostname, connected: !queue.closing }] },
           automations: [], automation_control: definitions.automations, issue_provider: providerInfo(provider),
           workers: [{ name: 'Local worker', machine: host, instance_id: 'local-executor', repositories: ['app'], connected: !queue.closing, last_seen_at: new Date().toISOString() }], // v1 compatibility view
-          repositories: ['app'], repo: config.repo, project_links: projectLinks, harness: harnessOf(config), agent: harnessOf(config) });
+          repositories: ['app'], repo: config.repo, project_links: projectLinks, source_ref_default: config.sourceRef || 'HEAD', harness: harnessOf(config), agent: harnessOf(config) });
       }
       if (request.method === 'GET' && url.pathname === '/api/v1/definitions') {
         return send(200, definitions);
@@ -112,7 +115,8 @@ export function createController(state, adapter = executors(state), integrations
         }
         if (url.pathname === '/api/v1/jobs') {
           if (input.model && input.model !== config.model && !['codex','pi'].includes(harnessOf(config))) throw new QueueError('Model overrides require a codex or pi executor', 400);
-          return send(201, queue.submit(input));
+          const created = queue.submit(input);
+          return send(201, { id: created.id, source_admission: publicSourceAdmission(created.source_admission) });
         }
         const action = url.pathname.match(/^\/api\/v1\/jobs\/(job_[a-f0-9]+)\/(approve|cancel|retry|request_changes)$/);
         if (action) return send(200, await queue.action(action[1], action[2], input));