software-defence-factory 0.9.1 → 0.11.0

package/README.md

@@ -37,7 +37,7 @@ The runtime supplies policy and six focused skills to its isolated jobs. `init`
 
 Each result belongs to a specific candidate commit and policy. A failed check blocks delivery. Changing the candidate or check policy invalidates earlier evidence. Approval records a handoff; publishing, merging and deployment follow the application's separate authority.
 
-The project dashboard has an **Inbox**, measured **Analytics**, **Agents**, **Skills**, **Automations**, **Definition** and **Infrastructure**. New issue offers the repository’s issue templates, a blank local form or a selectable GitHub issue. Create an issue on the supported repository provider, then choose Start work separately; local brief execution remains available. CLI `issue` exposes the same intake. Definition lives with settings above the theme control. The CLI reads the same definition and controller state. Agent roles use a selected harness such as Codex or Pi; a worker executes their isolated jobs on a host. See [concepts](docs/concepts.md) and [supported interfaces](docs/interfaces.md). Optional automations belong to the selected harness, which calls Factory CLI/API. Factory runs no cron scheduler. See [provider boundaries](docs/integrations.md).
+The project dashboard has an **Inbox**, measured **Analytics**, **Agents**, **Skills**, **Automations**, **Definition** and **Infrastructure**. Inbox lists repository issues with readiness and linked execution attempts. New issue offers repository templates or a blank creation form. Create an issue on the supported repository provider, then choose Start work separately; local brief execution remains available. CLI `issue` exposes the same intake. Definition lives with settings above the theme control. The CLI reads the same definition and controller state. Agent roles use a selected harness such as Codex or Pi; a worker executes their isolated jobs on a host. See [concepts](docs/concepts.md) and [supported interfaces](docs/interfaces.md). Optional automations belong to the selected harness, which calls Factory CLI/API. Factory runs no cron scheduler. See [provider boundaries](docs/integrations.md).
 
 The optional **defence** workflow accepts scoped incident evidence and produces a private, read-only draft. It does not monitor production or claim verified recovery. See [defence integration](docs/defence-integration.md).
 

package/bin/software-defence-factory.mjs

@@ -6,7 +6,7 @@ import { spawn } from 'node:child_process';
 import { createServer } from 'node:net';
 import { ROOT, PINS, DEFAULT_STATE, configAt, save, json, run, stream, digest, api, sleep, stopContainers, PUBLICATION_API_TIMEOUT_MS } from '../factory/lib.mjs';
 import { assertInstalledJobImage, installCustomJobImage, installStandardJobImage, inspectImageInstallation } from '../factory/image-install.mjs';
-import { listIssues, readIssue } from '../factory/issue-intake.mjs';
+import { readIssue } from '../factory/issue-intake.mjs';
 import { recommendWork } from '../factory/intake.mjs';
 import { factoryDefinition, foundationSkill } from '../factory/definition.mjs';
 import { harnessOf } from '../factory/lib.mjs';
@@ -55,6 +55,16 @@ function init(repo, harness='codex', check='', port=7331, sourceRef='HEAD', deli
   console.log(`Configured ${state}\nApp files were not changed. Only committed code is cloned into jobs.`);
 }
 
+async function listInbox(defaultSource) {
+  const source=flags.source || defaultSource;
+  if(!['factory','inbox','remote','github'].includes(source))throw new Error('Choose --source factory, inbox or remote');
+  if(source==='factory') {
+    if(flags.page !== undefined || flags['issue-state'] !== undefined)throw new Error('Repository paging/state filters require --source inbox or remote.');
+    return (await api(state,'/api/v1/status')).jobs;
+  }
+  return api(state,`/api/v1/issues?page=${encodeURIComponent(flags.page || 1)}&state=${encodeURIComponent(flags['issue-state'] || 'open')}`);
+}
+
 async function install() {
   const config=configAt(state);
   if (!['darwin','linux'].includes(process.platform)||!['arm64','x64'].includes(process.arch)) throw new Error('Use macOS/Linux arm64/amd64, or WSL2');
@@ -101,10 +111,10 @@ async function stop() {
   }
   stopContainers(state);console.log('Controller and its labelled containers stopped.');
 }
-async function submit(workflow,spec,sourceRef=flags['source-ref']) {
+async function submit(workflow,spec,sourceRef=flags['source-ref'],sourceURL) {
   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,...(sourceRef===undefined?{}:{source_ref:sourceRef})});
+  return api(state,'/api/v1/jobs',{workflow,repository:'app',spec,title,...(sourceURL?{source_url:sourceURL}:{}),...(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');
@@ -113,15 +123,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}`);
 }
 
@@ -150,6 +167,7 @@ async function abandonDeliveryJob(jobId) {
 }
 
 try {
+  if(flags['brief-file'] !== undefined && (command !== 'issue' || positional[0] !== 'start' || !(flags.url || flags.github) || flags.file || flags.draft))throw new Error('Use --brief-file only with issue start --url (or --github); local --file/--draft already supplies the scope.');
   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');
@@ -184,9 +202,10 @@ try {
     const value=command==='agents'?definition.agents:command==='skills'?{agents:definition.skills,operators:definition.operator_skills}:definition;
     console.log(JSON.stringify(value,null,2));
   }
-  else if(['infrastructure','automations','inbox'].includes(command)) {
+  else if(command==='inbox')console.log(JSON.stringify(await listInbox('inbox'),null,2));
+  else if(['infrastructure','automations'].includes(command)) {
     const snapshot=await api(state,'/api/v1/status');
-    console.log(JSON.stringify(command==='inbox'?snapshot.jobs:command==='automations'?snapshot.automation_control:snapshot[command],null,2));
+    console.log(JSON.stringify(command==='automations'?snapshot.automation_control:snapshot[command],null,2));
   }
   else if(command==='status') { const snapshot=await api(state,'/api/v1/status');delete snapshot.csrf_token;console.log(JSON.stringify(snapshot,null,2)); }
   else if(command==='doctor') {
@@ -197,8 +216,7 @@ try {
   } else if(command==='issue') {
     const action=positional[0], sourceURL=flags.url || flags.github;
     if(action==='list') {
-      if(flags.source && !['factory','remote','github'].includes(flags.source))throw new Error('Choose --source factory or remote');
-      console.log(JSON.stringify(['github','remote'].includes(flags.source) ? await api(state,`/api/v1/issues?page=${encodeURIComponent(flags.page || 1)}`) : (await api(state,'/api/v1/status')).jobs,null,2));
+      console.log(JSON.stringify(await listInbox('factory'),null,2));
     } else if(action==='templates') console.log(JSON.stringify(await api(state,'/api/v1/issue-templates'),null,2));
     else if(action==='connection') console.log(JSON.stringify(await api(state,'/api/v1/issue-connection'),null,2));
     else if(action==='submissions') console.log(JSON.stringify(await api(state,'/api/v1/issue-submissions'),null,2));
@@ -226,17 +244,21 @@ try {
     } else if(action==='start') {
       if(!['software','defence'].includes(flags.workflow))throw new Error('Review the issue and choose --workflow software or defence');
       if([flags.file,sourceURL,flags.draft].filter(Boolean).length!==1)throw new Error('Choose --file brief.md, --draft draft.json or --url ISSUE_URL');
-      let input;
-      if(sourceURL) { const issue=await api(state,'/api/v1/issues/preview',{url:sourceURL});input={title:issue.title,spec:issue.spec,source_url:issue.url}; }
+      let input, brief;
+      if(flags['brief-file'] !== undefined) {
+        brief=readFileSync(resolve(flags['brief-file']),'utf8');
+        if(brief.length>16000)throw new Error('Operator brief must be at most 16000 characters.');
+      }
+      if(sourceURL) { const issue=await api(state,'/api/v1/issues/preview',{url:sourceURL});input={title:issue.title,url:issue.url,expected_spec:issue.spec,...(brief===undefined?{}:{brief})}; }
       else if(flags.draft) { const draft=json(resolve(flags.draft));input={title:draft.title,spec:draft.spec}; }
       else input={title:flags.title,spec:readFileSync(resolve(flags.file),'utf8')};
       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(!sourceURL && (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 || '',...(flags['source-ref']===undefined?{}:{source_ref:flags['source-ref']})}),null,2));
+      console.log(JSON.stringify(await api(state,sourceURL ? '/api/v1/issues/start' : '/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));
+    console.log(JSON.stringify(await listInbox('inbox'),null,2));
   } else if(command==='recommend') {
     if(Boolean(flags.issue) === Boolean(flags.file))throw new Error('Choose --file task.md or --issue URL');
     const recommendation=flags.issue ? (await readIssue(configAt(state).repo,flags.issue)).recommendation : recommendWork({spec:readFileSync(resolve(flags.file),'utf8')});
@@ -244,13 +266,13 @@ try {
   } else if(command==='run') {
     const workflow=flags.workflow || 'software';
     if(!['software','defence'].includes(workflow))throw new Error('Choose --workflow software or defence');
-    let spec;
+    let spec,sourceURL;
     if(flags.issue) {
-      spec=(await readIssue(configAt(state).repo,flags.issue)).spec;
+      const issue=await readIssue(configAt(state).repo,flags.issue);spec=issue.spec;sourceURL=issue.url;
     } else if(flags.file)spec=readFileSync(resolve(flags.file),'utf8');
     else throw new Error('Use --file task.md or --issue https://github.com/owner/repo/issues/123');
     if(workflow==='software'&&!configAt(state).check?.trim())throw new Error('Configure an app check before submitting software work');
-    console.log(JSON.stringify(await submit(workflow,spec)));
+    console.log(JSON.stringify(await submit(workflow,spec,flags['source-ref'],sourceURL)));
   } else if(command==='incident') {
     if(!flags.file)throw new Error('Use --file incident.json; see factory/examples/incident.json');
     console.log(JSON.stringify(await admitIncident(state,json(resolve(flags.file)),submit)));
@@ -296,7 +318,9 @@ try {
   web probe --state PATH                    Execute the pinned local Chromium readiness probe
   foundation                              Read the operator setup skill; no installation required
   definition | agents | skills            Inspect roles, instructions and installation settings
-  inbox | infrastructure | automations    Inspect live tasks, host/worker and automation state
+  inbox [--page N] [--issue-state open|closed|all] [--source inbox|factory]
+                                          Repository backlog (default); factory: execution-only array
+  infrastructure | automations            Inspect host/worker and automation state
   workflows                               Compatibility alias for definition
   --agent                                 Legacy alias for init --harness
   serve                                   Foreground supervisor
@@ -309,7 +333,8 @@ try {
   service resume                          Release a reconciled maintenance reservation
   tunnel install|start|stop|status|logs|uninstall --host SSH_ALIAS --port PORT
                                           Persistent loopback SSH tunnel (macOS/Linux)
-  issue list [--source remote] [--page N]  List local executions or open repository issues
+  issue list [--source inbox|remote|factory] [--page N] [--issue-state open|closed|all]
+                                          List linked repository issues or local executions (default)
   issue templates                         Read this repository's issue forms and contact links
   issue preview --url URL              Preview one repository issue without starting work
   issue recommend --file brief.md | --url URL
@@ -321,8 +346,9 @@ try {
   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 [--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
+               [--brief-file operator.md]  Only with --url; at most 16000 characters
+                                          Explicitly start execution; no GitHub write
+  issues [--page N]                       Browse linked project issues; supports --issue-state
   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
@@ -331,7 +357,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

@@ -9,14 +9,15 @@ shell endpoint or a second scheduler.
 
 | Capability | CLI | Shared API | Dashboard | Remaining work |
 | --- | --- | --- | --- | --- |
-| Project/queue/attempt state | `status`, `inbox` JSON | `GET /api/v1/status` | Project, tasks, details/history | Stable versioned agent result/error contract |
-| Start local work | `issue start --file --title`, `--draft` or `--url`, explicit `--workflow`, optional `--model` | `POST /api/v1/jobs` | Local execution only → review → Create & start locally | Persistent unstarted drafts and typed incident intake remain separate |
-| Browse/import repository issues | `issue list --source remote [--page N]`, `issue preview --url URL` via controller provider | Authenticated `GET /api/v1/issues`, `POST /api/v1/issues/preview` using shared readers | Paged open-issue list, search loaded results, preview and explicit start for either type | Issue → execution links retained; no implicit polling |
+| Project/queue/attempt state | `status`, `inbox --source factory` JSON | `GET /api/v1/status` | Project, tasks, details/history | Stable versioned agent result/error contract |
+| Start local work | `issue start --file --title` or `--draft`, explicit `--workflow`, optional `--model` | `POST /api/v1/jobs` | Local execution only → review → Create & start locally | Persistent unstarted drafts and typed incident intake remain separate |
+| Browse repository Inbox | `inbox [--page N] [--issue-state open/closed/all]` (also `issue list --source inbox`), `issue preview --url URL` via controller provider | Authenticated `GET /api/v1/issues`, `POST /api/v1/issues/preview` using shared readers | Inbox with provider/state/readiness, loaded-page counts, linked attempts, local/off-page history; explicit Start work for either type | Issue → execution links retained; no implicit polling |
+| Start repository work | `issue start --url URL --workflow software/defence [--brief-file operator.md]` | `POST /api/v1/issues/start` | Issue context → explicit Start work with operator brief | Rechecks current content and active admission |
 | Create repository issue / recovery | `issue connection`, `create --key`, `submissions`, `recover --key` | Authenticated connection, `POST /issues`, receipts and recovery | Display destination/actor, create without execution, recover uncertain result | GitHub adapter first; assignees/projects and other providers unimplemented |
 | 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 +33,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 | Issue Start work, local request 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) |
 
@@ -57,3 +58,51 @@ the Skills page reads that same file. Full safe setup controls remain #37.
 The roadmap is split into Defence #50, quality measurement #51, GitHub intake
 #52, editable definitions #53 and scoped MCP #54. Existing REST endpoints are
 local single-operator interfaces, not a public multi-user API.
+
+
+## Issue lifecycle API in 0.11.0
+
+`GET /api/v1/issues?page=1&state=open` retains repository/issues/next_page and adds
+provider, page, state, loaded_count, total (null when unknown), and history.
+Each issue adds canonical identity, provider state, readiness, executions,
+latest_execution, active_execution(s), and start_block_reason. History groups
+local jobs and canonical sources outside the page; not_loaded does not claim
+that an issue is missing or closed. `status.issue_history` refreshes these local
+associations without polling the provider. No issue content database was added.
+
+`POST /api/v1/issues/preview` retains content/labels/recommendation and adds the
+same identity/readiness/history contract. `POST /api/v1/issues/start` accepts
+url, expected_spec (the preview's spec), workflow, optional brief, source_ref
+and model. It re-reads current provider context, rejects changed scope, closed
+sources, blocked/conflicting readiness and active/unresolved work, then uses
+existing source admission. HTTP 409 describes stale or duplicate admission.
+`POST /api/v1/jobs` remains compatible for local/direct callers; its queue-level
+canonical reservation also rejects concurrent duplicate active work and retries.
+Terminal succeeded/failed/cancelled executions release the reservation unless
+provider delivery is unresolved. Other/unknown states retain it conservatively.
+
+`inbox` now defaults to the same repository page object as the dashboard (open,
+page 1), an intentional 0.11.0 JSON change from its former jobs array. Use
+`inbox --source factory` for the explicit legacy execution-only array.
+`issue list` still defaults to the original local jobs array (`--source factory`).
+`--source inbox`, `remote` and compatibility `github` return the shared enriched
+page. `issues` now uses this same authenticated controller endpoint and enriched
+JSON, rather than bypassing the controller; scripts need a running controller.
+Use `--issue-state` for provider state; `--state` continues to mean installation
+path. Repository paging/state options are rejected in execution-only mode rather
+than ignored. Unsupported providers return their capability state and local/history
+records; provider/auth failures exit nonzero, never an empty-success backlog.
+`issue start --url URL --brief-file operator.md` reads a UTF-8 operator brief of at
+most 16000 characters (the API's string-length limit), forwarded unchanged to the
+shared preview/start contract. The API appends nonblank, trimmed text under
+`Operator brief:` in the admitted spec, while preserving provider identity and
+rechecking current content. `--brief-file` is optional, only valid with remote
+`issue start --url` (or its `--github` alias); it cannot accompany local `--file`
+or `--draft`, creation, browsing or other commands. Missing/unreadable files and
+oversize text fail without admission. Local file/draft execution is unchanged. `run` retains
+its compatible direct-job path and the controller's duplicate identity guard.
+
+Definition exposes `configuration.issueReadinessLabels`. The optional private
+config field has exactly triage/spec/ready/blocked keys with four distinct label
+names; defaults are factory:triage/spec/ready/blocked. Configuration is validated,
+not inferred from issue content. No browsing path changes labels or comments.

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/quickstart.md

@@ -149,7 +149,7 @@ create a second PR or overwrite a changed branch. The CLI gives this bounded
 multi-request action ten minutes; branch resolution uses the same bound and
 other API calls keep their five-second deadline. If a client deadline expires,
 inspect status and repeat `publish` to reconcile or recheck the reported branch
-identity before `abandon-delivery`. Delete issue stays disabled while delivery
+identity before `abandon-delivery`. Remove local execution history stays disabled while delivery
 is unresolved, and the controller enforces the same guard on its API.
 Publication does not merge, integrate, release or deploy. See [delivery
 recovery](recovery.md#trusted-pr-delivery).
@@ -211,8 +211,7 @@ use the [Defence integration](defence-integration.md) recipe; the generic
 Defence form is not that typed intake path.
 
 The header names the configured project. View repo opens a validated GitHub
-origin. New issue opens Factory’s local chooser: repository templates, a blank
-form or existing GitHub issues. Create issue saves to the supported repository provider without execution. Start work queues local work. See [intake and CLI examples](workflows.md). The task detail provides previous/next within the filtered list, copy
+origin. Inbox lists repository issues directly with open/closed/all filters and paging. New issue opens repository templates or a blank creation form. Create issue saves to the supported repository provider without execution. Open an issue from Inbox and choose Start work to admit execution explicitly. The controller rejects duplicate active work; linked attempts remain accessible. See [intake and CLI examples](workflows.md). The task detail provides previous/next within the filtered list, copy
 link and close (Escape). Closing preserves the list's filters and position.
 
 If the interface looks unexpectedly small, check the browser zoom. The design

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/docs/setup.md

@@ -227,7 +227,7 @@ controller action; other CLI API requests retain their five-second deadline.
 If the client deadline expires, inspect status and repeat `publish JOB_ID` so
 the controller can reconcile its saved intent. Restart the installed controller
 and repeat `publish JOB_ID`; verify the same branch and PR head are read back
-and no second PR appears. Delete issue is disabled while the delivery is
+and no second PR appears. Remove local execution history is disabled while the delivery is
 unresolved, and the controller rejects the same removal through its API. Leave
 pending/unknown checks labelled as such. After inspection, close the proof PR
 without merging its fixture change. Do not publish a worker candidate from
@@ -326,3 +326,36 @@ installed file. Keep host identities, credentials, raw logs and customer details
 out of public issues and package contents. A ready worker is only the foundation:
 follow [the method](../kit/README.md#first-real-task) for the first explicitly
 accepted application task and revision-bound checks/review/handoff.
+
+
+## Repository Inbox and explicit execution
+
+The controller's configured repository selects its issue adapter. On GitHub,
+use the controller host's existing read access; browser login does not supply
+credentials. Open Inbox, verify the provider/repository, refresh and page through
+Open/Closed/All states. Provider failures remain visible; local execution and
+retained history remain available on unsupported hosts. Creating through New
+issue and browsing must leave the execution queue unchanged. Open the issue and
+choose Start work only after reviewing its scope and work type.
+
+Readiness is separate from execution state. To use different repository labels,
+set `issueReadinessLabels` in private `factory.json` while stopped and restart:
+`{"triage":"factory:triage","spec":"factory:spec","ready":"factory:ready","blocked":"factory:blocked"}`.
+All four values must be distinct label names. Definition displays the effective
+mapping. This only interprets read metadata; it installs no labels or automations.
+Keep private security reports on their configured private route.
+
+Before adopting 0.11.0, qualify the exact installed package and real provider
+lifecycle, including creation without execution, explicit start, duplicate
+rejection and linked subsequent attempts. Inspect affected flows at desktop,
+390px and 320px in both themes, including failures. Component/provider-fixture
+tests do not qualify those native interactions. Existing source retention,
+continuation, review and trusted delivery acceptance remain required.
+
+CLI `inbox --state PATH` opens the same repository page (open issues, page 1).
+Use `--page N` and `--issue-state closed|all` for additional issues/history;
+`inbox --source factory` explicitly selects the legacy execution-only array.
+To add operator scope at admission, use `issue start --url URL --workflow software
+--brief-file operator.md --state PATH` with an optional UTF-8 brief of at most
+16000 characters. This keeps the remote identity and current-content check;
+local requests still use `issue start --file` or `--draft` without `--brief-file`.

package/docs/workflows.md

@@ -24,12 +24,27 @@ kept outside those execution mounts.
 
 ## Start work
 
-Open **New issue** in Inbox, choose a repository template (or **Blank issue**),
-complete the title and fields, then **Continue**. Or choose
-**From GitHub issues** and select an open issue from the configured repository.
-The list excludes pull requests, loads 50 GitHub records per page and offers
-**Load more**; search filters the loaded issues by title, number or label. GitHub
-reads use the controller's existing access, with retry on failure.
+Inbox lists repository issues directly. Choose Open, Closed or All states and use
+Previous/Next page or Refresh issues. Search covers the loaded page and visible
+history, not the whole repository. GitHub returns up to 50 records per page;
+pull requests are excluded, so even a page with zero issues can have a next page.
+Counts name the loaded page and total remains unknown. Authentication/provider
+failures are visible, with any retained page explicitly stale.
+
+Open an issue for its context, readiness, and linked execution attempts. Start
+work is deliberate; browsing never starts an agent. Active or unresolved work
+blocks another admission for the same canonical identity, including concurrent
+requests and retries. Completion/cancellation permits a subsequent explicit
+attempt. Failed work stays in history; blocked/interrupted work must first be
+reconciled or cancelled, and unresolved provider delivery continues to block.
+Closed issues and blocked/conflicting readiness labels cannot start new work.
+No readiness labels means unknown, not ready or running. Readiness is planning
+metadata; Needs triage never means an agent is Triaging.
+
+**New issue** only composes/publishes: choose a repository template (or **Blank
+issue**), complete the title and fields, then Continue and Create issue. Done
+returns to Inbox, where the new issue appears without a job. Refresh also finds
+issues created directly on the forge. Existing issue selection is in Inbox.
 
 Review the instructions and suggested work type before explicitly starting work. The shared,
 deterministic suggestion prioritizes `track:software` and `track:security` (also
@@ -57,8 +72,8 @@ shown as literal text, never executed or rendered as raw HTML.
 On a supported repository, **Create issue on GitHub** writes the title, description
 and template labels to that repository using the displayed host identity. It
 returns the real issue number/link and **does not start execution**. Select
-**Start work** separately, or choose the issue later from the repository list.
-Choose **Local execution only** to submit a brief without publishing it. A local
+**Done**, then open the issue in Inbox and choose **Start work**.
+Choose **Local execution request** in Inbox to submit a brief without publishing it. On unsupported hosts, New issue also offers this explicitly local route. A local
 brief is an execution request; an unfinished form is not a persistent backlog.
 Use the private security contact route for sensitive reports, never a public issue.
 
@@ -73,17 +88,24 @@ CLI equivalents (the selected controller must be running):
 
 ```sh
 software-defence-factory issue connection --state PATH
-software-defence-factory issue list --source remote --state PATH --page 1
+software-defence-factory inbox --state PATH --page 1 --issue-state open
+# Explicit legacy execution-only JSON array:
+software-defence-factory inbox --state PATH --source factory
 software-defence-factory issue templates --state PATH
 software-defence-factory issue draft --state PATH --template bug-report.yml --sha TEMPLATE_SHA --file answers.json > draft.json
 software-defence-factory issue create --state PATH --draft draft.json --key release-board-fix-01
 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 --url URL --workflow software --brief-file operator.md
 software-defence-factory issue start --state PATH --file brief.md --title "Investigate supplied evidence" --workflow defence --source-ref main
 ```
 
+`--brief-file` is optional, UTF-8, at most 16000 characters and valid only with
+a remote issue start. Use `--file` or `--draft` alone for local scope. Inbox
+defaults to a repository page with linked history; `--issue-state closed` or
+`all` and `--page` browse further without starting work.
+
 `answers.json` contains `{"title":"Fix the board","answers":{"problem":"..."}}`;
 keys match `fields[].id` in `issue templates`. Multi-select/checkbox answers are
 arrays of exact option labels. `issue create` now publishes only; migrate 0.5.1
@@ -116,3 +138,12 @@ while the installation is stopped, then restart. Workflow order and packaged
 skills change through reviewed Factory releases. This release does not support
 per-role profiles or arbitrary editable workflow graphs. Versioned editable
 definitions are tracked in [#53](https://github.com/arcitai/software-and-defence-factory/issues/53).
+
+
+Inbox groups URL case, HTTP/HTTPS, trailing-slash, query and fragment aliases by GitHub
+repository and issue number. Credential-bearing URLs, queries, foreign hosts and
+non-issue paths are not admitted by the provider preview. Local-only records and
+executions whose source is missing, closed or outside the loaded page remain in
+Local and other execution history. Removing local execution history preserves
+private evidence and never deletes a provider issue; unresolved delivery guards
+still apply. The separate Execution history tab keeps the execution list/board.

package/factory/definition.mjs

@@ -1,3 +1,4 @@
+import { readinessMapping } from './issue-lifecycle.mjs';
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ROOT, digest, harnessOf } from './lib.mjs';
@@ -39,7 +40,7 @@ export function factoryDefinition(config) {
     commands: Object.entries(phaseInfo).map(([name, info]) => ({ name, ...info, prompt: info.description,
       executor: info.owner === 'agent' ? harnessOf(config) : 'factory', timeout: `${config.timeoutSeconds}s` })),
     skills,
-    configuration: { harness, agent: harness, // agent is a v1 compatibility alias
+    configuration: { issueReadinessLabels: readinessMapping(config.issueReadinessLabels), harness, agent: harness, // agent is a v1 compatibility alias
       model: config.model || null, check: config.check, timeoutSeconds: config.timeoutSeconds,
       memoryMiB: config.memoryMiB, cpus: config.cpus || 2,
       web_verification: config.webVerification?.enabled ? {