software-defence-factory 0.9.1 → 0.10.0

package/bin/software-defence-factory.mjs

@@ -113,15 +113,22 @@ async function jobAction(action) {
   const current=job.runs.at(-1);
   if(action==='approve'&&job.state!=='awaiting_approval')throw new Error('Job is not awaiting approval');
   if(action==='retry'&&!['interrupted','failed','blocked','cancelled'].includes(job.state))throw new Error('Only a stopped attempt can be retried');
-  let feedback;
+  let feedback, revision = {};
   if(action==='request_changes') {
     if(!flags.file)throw new Error('revise requires --file feedback.md');
+    if (flags.from !== undefined && !['admitted-source', 'reviewed-candidate'].includes(flags.from)) throw new Error('revise --from must be admitted-source or reviewed-candidate');
+    if (flags.from !== undefined && flags['source-ref'] !== undefined) throw new Error('Choose --from or --source-ref, not both');
+    if (flags.from === 'reviewed-candidate') {
+      const checkpoint = job.continuation_status;
+      if (!checkpoint?.available) throw new Error(checkpoint?.reason || 'No current reviewed checkpoint is available; inspect status');
+      revision = { revision_mode: 'continue_candidate', candidate_head: checkpoint.head, candidate_tree: checkpoint.tree };
+    } else revision = { revision_mode: flags['source-ref'] === undefined ? 'fresh_source' : 'replace_source' };
     feedback=readFileSync(resolve(flags.file),'utf8');
     if(!feedback.trim()||feedback.length>4000)throw new Error('Provide revision feedback under 4000 characters');
   }
   // 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}),...(flags['source-ref']===undefined?{}:{source_ref:flags['source-ref']})});
+  await api(state,`/api/v1/jobs/${id}/${action}`,{run_id:current?.id,...revision,...(feedback===undefined?{}:{feedback}),...(flags['source-ref']===undefined?{}:{source_ref:flags['source-ref']})});
   console.log(`${action}: ${id}`);
 }
 
@@ -331,7 +338,7 @@ try {
   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]
+  revise JOB_ID --file feedback.md [--from admitted-source|reviewed-candidate | --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

package/docs/interfaces.md

@@ -16,7 +16,7 @@ shell endpoint or a second scheduler.
 | Repository issue templates | `issue templates`, `issue draft --template --sha --file` | Authenticated template list and draft compilation | Chooser, fields/defaults/validation, review | Supports Markdown and YAML markdown/input/textarea/dropdown/checkboxes; unsupported templates link to GitHub |
 | Suggest task type | `issue recommend --file` or `--url` | Authenticated `POST /api/v1/intake/recommend`; issue preview includes suggestion | Editable recommendation after source selection | Deterministic label/brief rules; no model judgment or execution authority |
 | Cancel/retry/approve | Commands | Job action endpoints with current run ID | Task controls | JSON action results and consistent needs-attention outcomes |
-| Request changes | `revise --file` | `request_changes` action | Feedback form | JSON action result; retain shared stale-action guards |
+| Request changes | `revise --file`, optional `--from admitted-source\|reviewed-candidate` or `--source-ref REF` | `request_changes` with `revision_mode`; continuation binds current run/head/tree from shared status | Explicit starting point, baseline and reviewed checkpoint; inline errors | JSON action result; unfinished Build checkpoints remain #42 |
 | Remove a stopped task | No command | `DELETE /api/v1/jobs/:id` | Remove action | Add CLI; keep existing recoverability/history semantics |
 | Evidence list/read/download | No command | Authenticated artifact routes | Files/preview/download | Add CLI with matching access and size/path rules |
 | Roles, workflows and packaged skills | `definition`, `agents`, `skills` JSON (also while stopped) | `GET /api/v1/definitions` | Agents, Skills and Definition | Shared read-only catalog; future editing must preserve common policy/gates |
@@ -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 | `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 |
+| 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 start fresh by default; explicit continuation keeps the reviewed tree and recorded source; a new ref replaces the base; 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 |
 | Optional trusted web verification | `web probe` performs a real local Chromium interaction; `doctor` reports readiness | Verify stores a shared story summary and protected JSON artifact in the run | Task history shows passed/failed/unavailable/inconclusive plus tool, candidate, policy and story hashes | Disabled by default. Required operator stories and Playwright/Chromium image ID are frozen in attempt policy. Linux Chromium proof cannot qualify native/mobile OS behavior; see [the browser contract](web-verification.md) |
 

package/docs/npm.md

@@ -73,8 +73,8 @@ installation or retained attempt needs them.
 
 ## Protected evidence compatibility
 
-0.9.1 recognizes version-1 execution profiles emitted by native **0.8.0,
-0.9.0 and 0.9.1**. This is an exact allowlist in
+0.10.0 recognizes version-1 execution profiles emitted by native **0.8.0,
+0.9.0, 0.9.1 and 0.10.0**. This is an exact allowlist in
 `factory/execution-profile.mjs`, independent of the installed package version;
 it is not a semver range or an automatic promise for later releases. Unknown
 runtime strings, unknown profile formats and incomplete legacy acceptance
@@ -101,12 +101,25 @@ neither a reason to discard evidence nor proof of compatibility. Retain
 unsupported records unchanged and obtain fresh applicable evidence through the
 normal workflow; never repair them by editing private records or hashes.
 
-After native Verify/Review, the lead must qualify the installed patch read-only
-against actual retained production evidence. This source change and its
-controlled fixtures do not supply that proof. An already delivered PR keeps
-read-only receipt reconciliation. New publication still requires the current
-remote target to equal the original accepted base; checkpoint continuation and
-target mismatch remain the separate #42 limit.
+The 0.10.0 writer retains the same profile format and original-base, aggregate
+single-parent candidate/check/review/approval guarantees. Continuation adds
+separate provenance; it is not acceptance evidence. The audited 0.8.0, 0.9.0 and
+0.9.1 writers remain supported only when their old records meet all current
+checks. For continuation specifically, the current completed review, successful
+Build/Verify, protected per-attempt artifacts, current policy and clean candidate
+objects must also be present and agree. An old runtime string alone never makes
+a checkpoint usable. Browser-disabled 0.8.0 records cannot satisfy a newly
+enabled browser policy. Missing or unsupported records stay unchanged and
+unavailable; no schema migration, profile relabeling or policy repair occurs.
+
+#71 shipped 0.9.0 through PR #81 and #84 shipped 0.9.1 through PR #85; both
+passed installed qualification, as reported by the lead. For this 0.10.0 slice,
+native Verify/Review remain required. The lead owns installed continuation,
+disposable protected PR/CI and desktop/narrow light/dark browser qualification
+on Z13. Controlled source fixtures do not supply that proof. New publication
+still requires the current remote target to equal the original accepted base;
+reviewed-candidate continuation preserves that baseline, while target refresh
+remains #72.
 
 ## Release flow
 

package/docs/recovery.md

@@ -8,7 +8,7 @@ Use `status --state PATH` and the private supervisor.log to identify the active
 - `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 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.
+- A requested revision starts fresh from the recorded source by default, retains previous evidence and starts a new build with accumulated feedback. It never silently reuses candidate code. 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. See the explicit continuation choice below.
 - 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.
@@ -331,3 +331,69 @@ 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.
+
+## Continue a reviewed candidate (first #42 slice)
+
+Use one explicit starting point for a current software review with a returned
+`changes`/`blocked` verdict, or a passed review awaiting approval:
+
+```sh
+# Existing default: restore admitted source, discarding candidate code from the next Build.
+software-defence-factory revise JOB_ID --file feedback.md --state PATH
+# Keep this job’s current immutable reviewed tree; keep its source/delivery baseline.
+software-defence-factory revise JOB_ID --file feedback.md --from reviewed-candidate --state PATH
+# Existing source replacement: resolve and retain a deliberately different baseline.
+software-defence-factory revise JOB_ID --file feedback.md --source-ref REF --state PATH
+```
+
+`--from admitted-source` names the default explicitly. `--from` and
+`--source-ref` cannot be combined. In the dashboard, Request changes exposes
+these same three starting points, the original source SHA, selected checkpoint
+head/tree and review attempt. Opening the form defaults to fresh source; a
+background refresh does not silently replace a checkpoint already selected.
+Errors stay next to the revision action and preserve feedback.
+
+The shared `request_changes` action accepts `run_id`, `feedback`, and
+`revision_mode`: `fresh_source`, `continue_candidate` or `replace_source`.
+Continuation additionally requires `candidate_head` and `candidate_tree` from
+this job’s `continuation_status` in `GET /api/v1/status`. They are stale-action
+guards, not selectors for arbitrary refs, host paths or other jobs. Replacement
+requires `source_ref`. Omitting mode preserves the existing default and
+`source_ref` behavior. Status includes `revision_mode`, public `continuation`
+provenance, and `continuation_status.available` or an actionable refusal reason.
+Availability describes protected evidence; the action also probes live workers
+and validates the Git objects before changing the checkout.
+
+Continuation confirms the executor/process group and job containers are idle;
+it refuses active or unknown work instead of stopping it implicitly. Under the
+existing queue action lock it validates the current review cycle, exact
+protected profiles and artifacts, original retained source, effective policy
+and any required browser evidence. It copies the clean reviewed Git objects
+into a private, job-bound checkpoint store with a pinned ref and manifest,
+checks head/tree/single parent and object integrity, and only then archives the
+writable checkout through ordinary reconciliation. Missing, dirty, tampered,
+foreign or incompatible candidates are refused without deleting prior work.
+
+The next Build validates the retained checkpoint and current policy again,
+restores the retained source as HEAD, and stages the checkpoint tree on that
+base. The ordinary Build commit is a single-parent aggregate: Review sees the
+entire original-base-to-new-candidate diff, including earlier changes. The
+original source admission is unchanged; continuation provenance has separate
+names and records on the revision, job, candidate and acceptance. Prior failed
+reviews stay failed, with their usage and artifacts retained. A stopped Build
+can retry the same selected immutable checkpoint after validation; it cannot
+reuse unfinished Build output. A restart never grants acceptance or triggers
+an automatic retry.
+
+Every revision requires new full Verify, independent Review and operator
+approval. Browser and profile gates still apply. Delivery requires the original
+accepted base to equal the configured, unchanged remote target. Continuation
+does not refresh that target (#72), rewrite history, merge or publish anything.
+Changed execution policy requires an explicit fresh start or source replacement,
+not reuse of an incompatible checkpoint. Restore missing private retention from
+backup before retrying; never edit checkpoint manifests or acceptance records.
+
+Unfinished/uncommitted Build checkpoints, exit-cause classification, live pending
+feedback and harness deadline hints remain deferred within #42. Opt-in desktop/VM
+observation and browser recordings belong to later #82. This slice does not close
+#42 or qualify those capabilities.

package/factory/delivery.mjs

@@ -1,8 +1,8 @@
+import { readPrivateJson, assertPrivateDirectory, trustedExecutionProfile } from './execution-evidence.mjs';
 import { createHash, randomBytes } from 'node:crypto';
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { isDeepStrictEqual } from 'node:util';
 import { configAt, digest } from './lib.mjs';
 import { effectiveExecutionConfig, isSupportedExecutionProfile } from './execution-profile.mjs';
 import { publicSourceAdmission } from './source-admission.mjs';
@@ -15,7 +15,6 @@ const MAX_PATCH_BYTES = 8 * 1024 * 1024;
 const MAX_CHANGED_FILES = 500;
 const MAX_TREE_BYTES = 8 * 1024 * 1024;
 const SHA1 = /^[a-f0-9]{40}$/;
-const PRIVATE_JSON_BYTES = 1024 * 1024;
 const utf8 = new TextDecoder('utf-8', { fatal: true });
 const KNOWN_DELIVERY_STATES = new Set(['intent', 'publishing', 'uncertain', 'blocked', 'conflict', 'published', 'abandoned']);
 const RESUMABLE_DELIVERY_STATES = new Set(['intent', 'publishing', 'uncertain', 'blocked']);
@@ -55,23 +54,12 @@ function commitObjectSha({ tree, parents, message, author, committer }) {
   const raw = Buffer.from(`tree ${tree}\nparent ${parents[0]}\nauthor ${author.name} <${author.email}> ${date.epoch} +0000\ncommitter ${committer.name} <${committer.email}> ${date.epoch} +0000\n\n${message}`, 'utf8');
   return createHash('sha1').update(`commit ${raw.length}\0`).update(raw).digest('hex');
 }
-function readPrivateJson(path) {
-  const stat = lstatSync(path);
-  if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0 || stat.size > PRIVATE_JSON_BYTES)
-    throw new Error('Protected delivery evidence is missing or unsafe.');
-  return JSON.parse(readFileSync(path, 'utf8'));
-}
 function readPrivateFile(path, limit) {
   const stat = lstatSync(path);
   if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0 || stat.size > limit)
     throw new Error('Protected candidate patch is missing, unsafe or too large.');
   return readFileSync(path);
 }
-function assertPrivateDirectory(path) {
-  const stat = lstatSync(path);
-  if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0)
-    throw new Error('Protected delivery directory is missing or unsafe.');
-}
 function runGitCommand(args) {
   const env = {
     PATH: process.env.PATH || '/usr/bin:/bin', HOME: '/nonexistent',
@@ -207,25 +195,6 @@ function remotePullReceipt(pull, repository, target, branch) {
   };
 }
 
-function trustedExecutionProfile(state, job, run, phase, expectedPolicy) {
-  if (!run || !/^run_[a-z0-9]+$/.test(run.id || '')) return false;
-  try {
-    const folder = join(state, 'jobs', job.id);
-    for (const path of [join(state, 'jobs'), folder, join(folder, 'artifacts'), join(folder, 'artifacts', run.id)])
-      assertPrivateDirectory(path);
-    const profile = readPrivateJson(join(folder, 'artifacts', run.id, 'execution.json'));
-    const agentPhase = phase === 'build' || phase === 'review';
-    const executorMatches = agentPhase
-      ? ['codex', 'pi'].includes(profile.executor)
-        && ['explicit', 'provider_default'].includes(profile.modelSelection)
-        && (profile.modelSelection === 'explicit' ? typeof profile.requestedModel === 'string' : profile.requestedModel === null)
-      : profile.executor === 'deterministic' && profile.modelSelection === 'not_applicable' && profile.requestedModel === null;
-    return isSupportedExecutionProfile(profile) && profile.phase === phase && executorMatches
-      && profile.policyHash === expectedPolicy
-      && isDeepStrictEqual(run.execution, profile);
-  } catch { return false; }
-}
-
 function trustedPhaseEvidence(state, job, expectedPolicy, runs, candidate, checks, review) {
   const executionsMatch = trustedExecutionProfile(state, job, runs.build, 'build', expectedPolicy)
     && trustedExecutionProfile(state, job, runs.verify, 'verify', expectedPolicy)

package/factory/execution-evidence.mjs

@@ -1,4 +1,9 @@
-import { assertCurrentWebEvidence } from './web-verification.mjs';
+import { lstatSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { configAt, digest } from './lib.mjs';
+import { effectiveExecutionConfig, isSupportedExecutionProfile } from './execution-profile.mjs';
+import { assertCurrentWebArtifacts, assertCurrentWebEvidence } from './web-verification.mjs';
 
 export function assertCurrentHandoffEvidence(meta, checks, review, policyHash, config = {}, job) {
   if (review.verdict !== 'pass' || review.head !== meta.head || review.tree !== meta.tree
@@ -9,3 +14,93 @@ export function assertCurrentHandoffEvidence(meta, checks, review, policyHash, c
   if (config.webVerification?.enabled) assertCurrentWebEvidence(config.webVerification, checks.web_verification,
     { job, attempt: checks.run_id, meta, policyHash });
 }
+
+export function readPrivateJson(path) {
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0 || stat.size > 1024 * 1024)
+    throw new Error('Protected execution evidence is missing or unsafe.');
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+export function assertPrivateDirectory(path) {
+  const stat = lstatSync(path);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077) !== 0)
+    throw new Error('Protected execution directory is missing or unsafe.');
+}
+
+export function trustedExecutionProfile(state, job, run, phase, expectedPolicy) {
+  if (!run || !/^run_[a-z0-9]+$/.test(run.id || '')) return false;
+  try {
+    const folder = join(state, 'jobs', job.id);
+    for (const path of [join(state, 'jobs'), folder, join(folder, 'artifacts'), join(folder, 'artifacts', run.id)])
+      assertPrivateDirectory(path);
+    const profile = readPrivateJson(join(folder, 'artifacts', run.id, 'execution.json'));
+    const agentPhase = phase === 'build' || phase === 'review';
+    const executorMatches = agentPhase
+      ? ['codex', 'pi'].includes(profile.executor)
+        && ['explicit', 'provider_default'].includes(profile.modelSelection)
+        && (profile.modelSelection === 'explicit' ? typeof profile.requestedModel === 'string' : profile.requestedModel === null)
+      : profile.executor === 'deterministic' && profile.modelSelection === 'not_applicable' && profile.requestedModel === null;
+    return isSupportedExecutionProfile(profile) && profile.phase === phase && executorMatches
+      && profile.policyHash === expectedPolicy
+      && isDeepStrictEqual(run.execution, profile);
+  } catch { return false; }
+}
+
+export function currentExecutionPolicy(state, job) {
+  const config = effectiveExecutionConfig(configAt(state), job.model, join(state, 'model.env'));
+  return { config, policyHash: digest(JSON.stringify(config)) };
+}
+
+// Only the current, completed review cycle may supply a continuation. Old writers
+// can supply it only with the same protected profiles, full checks and bindings.
+export function currentReviewedCandidate(state, job) {
+  const latest = job.runs.at(-1);
+  const reviewRun = job.state === 'awaiting_approval' && latest?.command === 'handoff'
+    ? job.runs.find(run => run.id === latest.reviewed_run_id) : latest;
+  if (job.workflow?.name !== 'software' || !['failed', 'awaiting_approval'].includes(job.state)
+    || reviewRun?.command !== 'review' || !['failed', 'succeeded'].includes(reviewRun.state))
+    throw new Error('Only this job’s current completed review can supply a checkpoint.');
+  const folder = join(state, 'jobs', job.id);
+  const meta = readPrivateJson(join(folder, 'candidate.json'));
+  const checks = readPrivateJson(join(folder, 'checks.json'));
+  const review = readPrivateJson(join(folder, 'review.json'));
+  const { config, policyHash } = currentExecutionPolicy(state, job);
+  const source = job.source_admission;
+  const buildRun = job.runs.find(run => run.id === meta.build_run_id);
+  const checkRun = job.runs.find(run => run.id === checks.run_id);
+  const cycle = job.runs.slice(0, job.runs.indexOf(reviewRun));
+  if (cycle.findLast(run => run.command === 'build')?.id !== buildRun?.id
+    || cycle.findLast(run => run.command === 'verify')?.id !== checkRun?.id
+    || job.runs.indexOf(buildRun) >= job.runs.indexOf(checkRun))
+    throw new Error('Checkpoint is not from the current reviewed Build/Verify cycle.');
+  for (const [run, phase] of [[buildRun, 'build'], [checkRun, 'verify'], [reviewRun, 'review']]) {
+    if (!trustedExecutionProfile(state, job, run, phase, policyHash)
+      || (phase !== 'review' && (run?.state !== 'succeeded' || run.outcome !== 'complete')))
+      throw new Error('Checkpoint execution provenance or current policy is incompatible; start fresh from admitted source.');
+  }
+  if (source?.status !== 'retained' || meta.base !== source.resolved_sha
+    || meta.source_admission?.resolved_sha !== source.resolved_sha
+    || meta.source_admission?.repository_identity !== source.repository_identity
+    || meta.build_policy_hash !== policyHash || meta.synthetic !== false || checks.synthetic !== false || review.synthetic !== false
+    || !checks.passed || checks.command !== config.check || checks.policyHash !== policyHash
+    || checks.head !== meta.head || checks.tree !== meta.tree
+    || review.run_id !== reviewRun.id || review.head !== meta.head || review.tree !== meta.tree
+    || review.policyHash !== policyHash || !['pass', 'changes', 'blocked'].includes(review.verdict)
+    || (reviewRun.review_verdict !== undefined && reviewRun.review_verdict !== review.verdict)
+    || (job.state === 'failed' && (reviewRun.state !== 'failed' || !['changes', 'blocked'].includes(review.verdict)))
+    || (job.state === 'awaiting_approval' && (reviewRun.state !== 'succeeded' || review.verdict !== 'pass')))
+    throw new Error('Checkpoint source, checks or review is stale or incompatible; reload or start fresh from admitted source.');
+  for (const [run, name, evidence] of [[buildRun, 'candidate', meta], [checkRun, 'checks', checks], [reviewRun, 'review', review]]) {
+    if (!isDeepStrictEqual(readPrivateJson(join(folder, 'artifacts', run.id, `${name}.json`)), evidence))
+      throw new Error('Checkpoint differs from its protected attempt evidence; preserve it for investigation.');
+  }
+  if (config.webVerification?.enabled) {
+    assertCurrentWebEvidence(config.webVerification, checks.web_verification,
+      { job: job.id, attempt: checkRun.id, meta, policyHash });
+    assertCurrentWebArtifacts(config.webVerification, checks.web_verification, join(folder, 'artifacts', checkRun.id));
+  }
+  return { head: meta.head, tree: meta.tree, original_base: meta.base,
+    build_run_id: buildRun.id, checks_run_id: checkRun.id, review_run_id: reviewRun.id,
+    policy_hash: policyHash, repository_identity: source.repository_identity };
+}

package/factory/execution-profile.mjs

@@ -7,11 +7,11 @@ import { effectiveInferenceProvider } from './model-environment.mjs';
 import { expectedWebStories, webPolicyHash } from './web-verification.mjs';
 
 // Audited v1 protected evidence writers: 0.8.0 (380f749), 0.9.0 (cdaadef),
-// and this patch. Deliberately independent of VERSION: a release bump is not
+// 0.9.1 and 0.10.0. Deliberately independent of VERSION: a release bump is not
 // evidence compatibility. Re-audit this list for every trust-relevant writer,
 // isolation or validation change; remove versions whose guarantees no longer
 // satisfy current policy. See docs/npm.md. This predicate alone grants no trust.
-const SUPPORTED_EXECUTION_RUNTIMES_V1 = new Set(['0.8.0', '0.9.0', '0.9.1']);
+const SUPPORTED_EXECUTION_RUNTIMES_V1 = new Set(['0.8.0', '0.9.0', '0.9.1', '0.10.0']);
 
 export function isSupportedExecutionProfile(profile) {
   return profile?.version === 1 && SUPPORTED_EXECUTION_RUNTIMES_V1.has(profile.runtimeVersion);

package/factory/executor.mjs

@@ -6,7 +6,7 @@ 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 { assertRetainedSource, publicSourceAdmission, publicContinuation, restoreBuildCheckout } from './source-admission.mjs';
 import { runCandidateGit } from './git-environment.mjs';
 import { selectedInferenceSecrets, writeSelectedModelEnvironment } from './model-environment.mjs';
 import { redactInferenceText, redactRetainedPhaseOutputs } from './inference-redaction.mjs';
@@ -25,8 +25,8 @@ 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'); }
+let sourceAdmission, continuation;
+try { sourceAdmission = JSON.parse(process.env.SDF_SOURCE_ADMISSION || 'null'); continuation = JSON.parse(process.env.SDF_CONTINUATION || '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');
@@ -50,7 +50,7 @@ function candidate() {
   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');
   if (git('rev-parse','HEAD^{tree}') !== meta.tree) throw new Error('Candidate tree changed; previous evidence is invalid');
-  if (meta.head !== meta.base && git('rev-parse', `${meta.head}^`) !== meta.base)
+  if (meta.head !== meta.base && git('rev-list', '--parents', '-n', '1', meta.head) !== `${meta.head} ${meta.base}`)
     throw new Error('Candidate parent differs from its admitted base; previous evidence is invalid');
   return meta;
 }
@@ -272,14 +272,16 @@ try {
     if (existsSync(workspace)) throw new Error('Workspace already exists; preserve evidence and create a new task for a fresh build');
     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);
+    restoreBuildCheckout(state, job, sourceAdmission, workspace, continuation, policyHash);
     const head = git('rev-parse','HEAD');
     if (head !== retained.sha) throw new Error('Build checkout differs from its admission-time source revision');
     const baseTree = git('rev-parse', `${head}^{tree}`);
-    save(join(folder,'candidate.json'), { base: sourceAdmission.resolved_sha, head, tree: baseTree, source_admission: publicSourceAdmission(sourceAdmission), synthetic: harnessOf(config) === 'mock' });
+    save(join(folder,'candidate.json'), { base: sourceAdmission.resolved_sha, head, tree: baseTree, continuation: publicContinuation(continuation), 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, { writable: true });
+    const continuationNote = continuation
+      ? ` The checkout deliberately contains reviewed checkpoint ${continuation.head} (tree ${continuation.tree}, review ${continuation.review_run_id}) staged on original source ${continuation.original_base}. Retain those changes while addressing the requested revision; independent Review will cover the whole combined diff.` : '';
+    const reports = await container('build', brief('Implement the requested bounded change. Save /output/agent-report.md with actual changes and remaining uncertainty.' + continuationNote), config.command, { writable: true });
     git('add','-A');
     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.
@@ -357,7 +359,7 @@ try {
     writeFileSync(join(output,'handoff.md'), `Accepted candidate ${meta.head} (tree ${meta.tree}), based on source ${sourceSha}.\nPatch handoff remains available. Optional PR delivery is a separate explicit operator action when configured.\nNo integration, merge, release or deployment performed.\nSee docs/quickstart.md for applying the reviewed change.patch to your own branch.\n`);
     save(join(folder,'accepted.json'), { base: meta.base, head: meta.head, tree: meta.tree, patch_sha256: patchHash,
       build_run_id: meta.build_run_id, checks_run_id: checks.run_id, review_run_id: review.run_id,
-      handoff_run_id: attempt, policyHash, source_admission: meta.source_admission || publicSourceAdmission(null), acceptedAt: new Date().toISOString() });
+      handoff_run_id: attempt, policyHash, continuation: meta.continuation || null, 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);
     const report = JSON.parse(safeRead(join(reports,'incident-report.json')));

package/factory/processes.mjs

@@ -2,7 +2,8 @@ import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, openSync, closeSync, readFileSync, renameSync, rmSync, lstatSync } from 'node:fs';
 import { join } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
-import { ROOT, configAt, run, json, save, stopContainers, sleep } from './lib.mjs';
+import { ROOT, configAt, run, json, save, stopContainers, containers, sleep } from './lib.mjs';
+import { assertRetainedCheckpoint } from './source-admission.mjs';
 import { effectiveExecutionConfig, executionProfile } from './execution-profile.mjs';
 import { parseCodexJsonl, emptyUsage, usageFields } from './usage.mjs';
 import { removeScratch } from './scratch.mjs';
@@ -98,6 +99,7 @@ export function executors(state, recovery = {}) {
   const recoveryStopContainers = recovery.stopContainers || stopContainers;
   const recoveryRun = recovery.run || run;
   const recoveryAlive = recovery.alive || alive;
+  const recoveryContainers = recovery.containers || containers;
   const usageCache = new Map();
   let usageReadWindow = -1, usageReads = 0;
   function presentedUsage(job, attempt) {
@@ -123,7 +125,10 @@ export function executors(state, recovery = {}) {
     // Resolve tags before admission so the recorded image is the one actually run.
     config.image = run('docker', ['image', 'inspect', '--format', '{{.Id}}', config.image]);
     if (!/^sha256:[a-f0-9]{64}$/.test(config.image)) throw new Error('Expected an immutable Docker image ID');
-    const profile = executionProfile(config, attempt.command), folder = join(state, 'jobs', job.id);
+    const profile = executionProfile(config, attempt.command);
+    if (attempt.command === 'build' && job.continuation)
+      assertRetainedCheckpoint(state, job.id, job.source_admission, job.continuation, profile.policyHash);
+    const folder = join(state, 'jobs', job.id);
     save(join(folder, attempt.id, 'execution-config.json'), config);
     save(join(folder, 'artifacts', attempt.id, 'execution.json'), profile);
     return profile;
@@ -141,17 +146,21 @@ export function executors(state, recovery = {}) {
     recoveryStopContainers(state, jobId);
     if (running && !processAlive(-running.child.pid)) clearStoppedFence(state, jobId, running.child.pid);
   }
-  async function reconcile(jobId, phase) {
+  async function reconcile(jobId, phase, { requireIdle = false, beforeArchive } = {}) {
     if (children.has(jobId)) throw new Error('Previous executor is still finishing');
-    recoveryStopContainers(state, jobId);
+    if (requireIdle && recoveryContainers(state).some(item => item.Config?.Labels?.['sdf.job'] === jobId && item.State?.Running !== false))
+      throw new Error('Previous job container is still active; stop it explicitly before continuing.');
+    if (!requireIdle) recoveryStopContainers(state, jobId);
     const folder = join(state, 'jobs', jobId), lock = join(folder, 'active.json');
     if (existsSync(lock)) {
       const previous = json(lock);
       if (!Number.isSafeInteger(previous.pid) || recoveryAlive(previous.pid)) throw new Error('Previous executor is still present or unknown');
       if (!Number.isSafeInteger(previous.pgid) || recoveryRun('ps', ['-axo', 'pgid=']).split('\n').map(Number).includes(previous.pgid))
         throw new Error('Previous process group is still present or unknown');
+      if (requireIdle) recoveryStopContainers(state, jobId);
       clearStoppedFence(state, jobId);
-    }
+    } else if (requireIdle) recoveryStopContainers(state, jobId);
+    beforeArchive?.();
     if (['build', 'defence'].includes(phase) && existsSync(join(folder, 'checkout')))
       renameSync(join(folder, 'checkout'), join(folder, `previous-checkout-${Date.now()}`));
   }
@@ -161,7 +170,7 @@ export function executors(state, recovery = {}) {
     const resultPath = join(output, 'result.json'), fd = openSync(join(output, 'executor.log'), 'a', 0o600);
     const child = spawnChild(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,
-        SDF_SOURCE_ADMISSION: JSON.stringify(job.source_admission || null) },
+        SDF_SOURCE_ADMISSION: JSON.stringify(job.source_admission || null), SDF_CONTINUATION: JSON.stringify(job.continuation || null) },
     }); closeSync(fd);
     let finish;
     const done = new Promise(resolve => { finish = resolve; });

package/factory/queue.mjs

@@ -1,3 +1,5 @@
+import { currentReviewedCandidate, currentExecutionPolicy } from './execution-evidence.mjs';
+import { publicContinuation } from './source-admission.mjs';
 import { DatabaseSync } from 'node:sqlite';
 import { randomBytes } from 'node:crypto';
 import { join } from 'node:path';
@@ -13,6 +15,7 @@ export class QueueError extends Error { constructor(message, status = 409) { sup
 // is committed before execution starts; a restart never assumes a result.
 export class JobQueue {
   constructor(state, { execute, stop, reconcile, prepare, reviewVerdict = () => undefined, sourceAdmission }) {
+    this.state = state;
     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.sourceAdmission = sourceAdmission;
@@ -124,6 +127,12 @@ export class JobQueue {
     return job.state === 'failed' && attempt?.state === 'failed' && attempt.command === 'review'
       && ['changes', 'blocked'].includes(attempt.review_verdict ?? this.reviewVerdict(job, attempt));
   }
+  continuationStatus(job) {
+    const originalBase = job.source_admission?.resolved_sha || null;
+    if (!this.canRequestChanges(job)) return { available: false, original_base: originalBase, reason: 'A current completed software review is required.' };
+    try { return { available: true, ...currentReviewedCandidate(this.state, job) }; }
+    catch (error) { return { available: false, original_base: originalBase, reason: error.code ? 'Protected reviewed checkpoint evidence is missing or unreadable; restore it or start fresh explicitly.' : error.message }; }
+  }
   async applyAction(jobId, action, input) {
     if (this.closing) throw new QueueError('Controller is stopping');
     let job = this.get(jobId), attempt = job.runs.at(-1);
@@ -138,7 +147,21 @@ export class JobQueue {
       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);
+      if (this.active?.jobId === jobId) throw new QueueError('Previous executor is still finishing; reload before acting');
       const explicitSource = input.source_ref !== undefined;
+      const mode = input.revision_mode ?? (explicitSource ? 'replace_source' : 'fresh_source');
+      if (!['fresh_source', 'replace_source', 'continue_candidate'].includes(mode)
+        || (explicitSource !== (mode === 'replace_source')))
+        throw new QueueError('Choose fresh_source, continue_candidate, or replace_source with source_ref; choices cannot be combined.', 400);
+      let continuation = null;
+      if (mode === 'continue_candidate') {
+        const selected = this.continuationStatus(job);
+        if (!selected.available) throw new QueueError(selected.reason);
+        if (input.candidate_head !== selected.head || input.candidate_tree !== selected.tree)
+          throw new QueueError('Reviewed candidate changed; reload and select the current checkpoint before continuing.');
+        if (typeof this.sourceAdmission?.retainCheckpoint !== 'function')
+          throw new QueueError('Reviewed checkpoint retention is unavailable.', 503);
+      }
       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)
@@ -152,19 +175,34 @@ export class JobQueue {
       }
       const replaceSourceRecord = changedBase || repairRetainedSource;
       const nextSource = replaceSourceRecord ? admittedSource : job.source_admission;
-      try { await this.reconcile(jobId, 'build'); }
+      try {
+        await this.reconcile(jobId, 'build', mode === 'continue_candidate' ? {
+          requireIdle: true,
+          beforeArchive: () => {
+            const selected = currentReviewedCandidate(this.state, job);
+            if (input.candidate_head !== selected.head || input.candidate_tree !== selected.tree)
+              throw new QueueError('Reviewed candidate changed; reload before continuing.');
+            continuation = this.sourceAdmission.retainCheckpoint(job, selected);
+          },
+        } : undefined);
+        if (mode === 'continue_candidate' && !continuation)
+          throw new QueueError('Executor reconciliation did not retain the selected checkpoint; revision was not queued.', 503);
+      }
       catch (error) {
         if (explicitSource) this.sourceAdmission.release?.(job.id, admittedSource);
+        if (mode === 'continue_candidate') throw new QueueError(error.code ? 'Cannot continue: protected checkpoint storage is unreadable; prior work is preserved.' : error.message, error.status || 409);
         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(), ...(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 } : {}) };
+      attempt.revision = { feedback: input.feedback, requested_at: now(), mode, original_base: nextSource.resolved_sha, continuation: publicContinuation(continuation), ...(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.continuation = continuation;
+      job.revision_mode = mode;
       job.prompt = revisedPrompt;
       job.workflow.current_step = 0; job.state = 'queued';
       try { this.save(job); }
@@ -184,6 +222,8 @@ export class JobQueue {
       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);
+      if (attempt?.command === 'build' && job.continuation)
+        this.sourceAdmission.validateCheckpoint(job.id, job.source_admission, job.continuation, currentExecutionPolicy(this.state, job).policyHash);
       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,7 +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';
+import { SourceAdmissionStore, publicSourceAdmission, publicContinuation } from './source-admission.mjs';
 import { deliveryProvider, deliveryProviderInfo } from './delivery-provider.mjs';
 import { DeliveryService } from './delivery.mjs';
 import { MAX_WEB_SCREENSHOT_BYTES } from './web-verification.mjs';
@@ -81,6 +81,7 @@ export function createController(state, adapter = executors(state), integrations
       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, source_admission: publicSourceAdmission(job.source_admission),
+          continuation: publicContinuation(job.continuation), continuation_status: queue.continuationStatus(job),
           source_history: (job.source_history || []).map(publicSourceAdmission), can_request_changes: queue.canRequestChanges(job),
           can_remove: queue.canRemove(job), removal_block_reason: queue.removalBlockReason(job),
           delivery_removal_blocked: Boolean(job.delivery && !['published', 'abandoned'].includes(job.delivery.state)),