software-defence-factory 0.10.0 → 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');
@@ -157,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');
@@ -191,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') {
@@ -204,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));
@@ -233,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')});
@@ -251,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)));
@@ -303,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
@@ -316,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
@@ -328,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

package/docs/interfaces.md

@@ -9,9 +9,10 @@ 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 |
@@ -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 start fresh by default; explicit continuation keeps the reviewed tree and recorded source; a new ref replaces the base; 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/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/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 ? {

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),
-// 0.9.1 and 0.10.0. Deliberately independent of VERSION: a release bump is not
+// 0.9.1, 0.10.0 and 0.11.0 (unchanged protected evidence writers). 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', '0.10.0']);
+const SUPPORTED_EXECUTION_RUNTIMES_V1 = new Set(['0.8.0', '0.9.0', '0.9.1', '0.10.0', '0.11.0']);
 
 export function isSupportedExecutionProfile(profile) {
   return profile?.version === 1 && SUPPORTED_EXECUTION_RUNTIMES_V1.has(profile.runtimeVersion);

package/factory/issue-intake.mjs

@@ -1,3 +1,4 @@
+import { canonicalIssue } from './issue-lifecycle.mjs';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { readProjectLinks } from './project-links.mjs';
@@ -23,34 +24,36 @@ function issueLabels(labels = []) {
   return labels.map(label => ({name:label.name, color:/^[a-f0-9]{6}$/i.test(label.color || '') ? label.color.toLowerCase() : null}));
 }
 
-export async function listIssues(repo, page = 1, read = githubRead) {
+export async function listIssues(repo, page = 1, read = githubRead, state = 'open') {
   if (!Number.isSafeInteger(page) || page < 1 || page > 10000) throw new Error('Issue page must be an integer between 1 and 10000.');
+  if (!['open', 'closed', 'all'].includes(state)) throw new Error('Issue state must be open, closed or all.');
   const repository = readProjectLinks(repo)?.repository;
   if (!repository) throw new Error('This project has no configured GitHub origin.');
   const slug = repository.slice('https://github.com/'.length);
-  const result = await read(['api', '--hostname', 'github.com', `repos/${slug}/issues?state=open&sort=created&direction=desc&per_page=50&page=${page}`, '-H', 'Accept: application/vnd.github+json']);
+  const result = await read(['api', '--hostname', 'github.com', `repos/${slug}/issues?state=${state}&sort=created&direction=desc&per_page=50&page=${page}`, '-H', 'Accept: application/vnd.github+json']);
   if (!Array.isArray(result) || result.length > 50) throw new Error('GitHub returned an unexpected issue list.');
   const issues = result.filter(issue => !issue.pull_request).map(issue => {
     validateIssueURL(repository, issue.html_url);
     if (!Number.isSafeInteger(issue.number) || !issue.html_url.endsWith(`/issues/${issue.number}`) || typeof issue.title !== 'string' || !issue.title.trim()) throw new Error('GitHub returned an unexpected issue.');
-    return { number: issue.number, title: issue.title, url: issue.html_url, labels: issueLabels(issue.labels) };
+    return { number: issue.number, title: issue.title, url: issue.html_url, state: issue.state || 'unknown', labels: issueLabels(issue.labels) };
   });
   return { repository, issues, next_page: result.length === 50 && page < 10000 ? page + 1 : null };
 }
 
 export function validateIssueURL(repoURL, value) {
-  if (typeof value !== 'string' || value.length > 2048 || !/^https:\/\/github\.com\/[A-Za-z0-9-]+\/[A-Za-z0-9_.-]+\/issues\/[1-9][0-9]*$/.test(value)) throw new Error('Enter a GitHub issue URL without query parameters.');
-  if (!repoURL || !value.toLowerCase().startsWith(`${repoURL.toLowerCase()}/issues/`)) throw new Error('Issue does not belong to this project’s configured GitHub origin.');
-  return value;
+  const identity = canonicalIssue(value);
+  if (!identity || new URL(value).search) throw new Error('Enter a GitHub issue URL without query parameters.');
+  if (!repoURL || identity.repository !== repoURL.toLowerCase()) throw new Error('Issue does not belong to this project’s configured GitHub origin.');
+  return identity.url;
 }
-export async function readIssue(repo, url, read = url => githubRead(['issue', 'view', url, '--json', 'title,body,url,labels'])) {
+export async function readIssue(repo, url, read = url => githubRead(['issue', 'view', url, '--json', 'title,body,url,labels,state'])) {
   const repoURL = readProjectLinks(repo)?.repository;
-  validateIssueURL(repoURL, url);
+  url = validateIssueURL(repoURL, url);
   const issue = await read(url);
   validateIssueURL(repoURL, issue?.url);
-  if (issue.url.toLowerCase() !== url.toLowerCase() || typeof issue.title !== 'string' || !issue.title.trim() || typeof issue.body !== 'string') throw new Error('GitHub returned an unexpected issue.');
+  if (validateIssueURL(repoURL, issue.url) !== url || typeof issue.title !== 'string' || !issue.title.trim() || typeof issue.body !== 'string') throw new Error('GitHub returned an unexpected issue.');
   const spec = `Issue: ${issue.url}\n${issue.title}\n\n${issue.body}`;
   if (Buffer.byteLength(spec) > 240000) throw new Error('Issue exceeds the 240 KB task limit. Use a bounded task file instead.');
   const labels = issueLabels(issue.labels);
-  return { title: issue.title, url: issue.url, body: issue.body, spec, labels, recommendation: recommendWork({ spec, labels: labels.map(label => label.name) }) };
+  return { title: issue.title, url, number: canonicalIssue(url).number, state: issue.state?.toLowerCase() || 'unknown', body: issue.body, spec, labels, recommendation: recommendWork({ spec, labels: labels.map(label => label.name) }) };
 }

package/factory/issue-lifecycle.mjs

@@ -0,0 +1,59 @@
+// Provider issue truth is read-only here. Only execution associations come from SQLite.
+export const DEFAULT_READINESS_LABELS = Object.freeze({ triage: 'factory:triage', spec: 'factory:spec', ready: 'factory:ready', blocked: 'factory:blocked' });
+export function readinessMapping(value = DEFAULT_READINESS_LABELS) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).some(key => !Object.hasOwn(DEFAULT_READINESS_LABELS, key))
+    || Object.keys(DEFAULT_READINESS_LABELS).some(key => typeof value[key] !== 'string' || !value[key].trim() || value[key].length > 100)
+    || new Set(Object.values(value).map(label => label.toLowerCase())).size !== 4)
+    throw new Error('issueReadinessLabels must map triage, spec, ready and blocked to four distinct label names.');
+  return { ...value };
+}
+export function issueReadiness(labels = [], mapping = DEFAULT_READINESS_LABELS) {
+  const names = labels.map(label => (typeof label === 'string' ? label : label.name).toLowerCase());
+  const matches = Object.entries(mapping).filter(([, label]) => names.includes(label.toLowerCase())).map(([key]) => key);
+  const state = matches.length > 1 ? 'conflicting' : matches[0] || 'unknown';
+  return { state, label: { triage:'Needs triage', spec:'Needs specification', ready:'Ready', blocked:'Blocked', conflicting:'Conflicting readiness labels', unknown:'Readiness unknown' }[state] };
+}
+export function canonicalIssue(value) {
+  if (typeof value !== 'string' || value.length > 2048 || /(?:^|\/)\.\.?(?:\/|$)/.test(value)) return null;
+  try {
+    const url = new URL(value);
+    if (!['https:', 'http:'].includes(url.protocol) || url.hostname !== 'github.com' || url.username || url.password || url.port) return null;
+    const match = url.pathname.match(/^\/([A-Za-z0-9-]+)\/([A-Za-z0-9_.-]+)\/issues\/([1-9][0-9]*)\/?$/i);
+    if (!match || !Number.isSafeInteger(Number(match[3]))) return null;
+    const repository = `https://github.com/${match[1]}/${match[2]}`.toLowerCase(), number = Number(match[3]);
+    return { key:`github:${repository}:${number}`, provider:'github', repository, number, url:`${repository}/issues/${number}` };
+  } catch { return null; }
+}
+export function executionReservesIssue(job) {
+  return !job.deleted_at && (!['succeeded', 'failed', 'cancelled'].includes(job.state)
+    || Boolean(job.delivery && !['published', 'abandoned'].includes(job.delivery.state)));
+}
+export function executionAssociation(jobs, identity) {
+  const attempts = jobs.filter(job => canonicalIssue(job.task?.source_url)?.key === identity.key)
+    .sort((a,b) => String(b.created_at || '').localeCompare(String(a.created_at || '')) || b.id.localeCompare(a.id));
+  const describe = job => ({ id:job.id, state:job.state, workflow:job.workflow?.name || null, phase:job.workflow?.steps?.[job.workflow.current_step] || null, created_at:job.created_at, updated_at:job.updated_at });
+  const active = attempts.filter(executionReservesIssue).map(describe);
+  return { executions:attempts.map(describe), latest_execution:attempts[0] ? describe(attempts[0]) : null, active_execution:active[0] || null, active_executions:active };
+}
+export function associateIssue(issue, jobs, mapping) {
+  const identity = canonicalIssue(issue.url);
+  if (!identity) throw new Error('Provider returned an unsupported issue identity.');
+  const association = executionAssociation(jobs, identity);
+  const readiness = issueReadiness(issue.labels, mapping);
+  const start_block_reason = association.active_execution ? 'An execution is active or unresolved. Open its history to continue or cancel it.'
+    : issue.state !== 'open' ? 'Only an open repository issue can start new work.'
+    : readiness.state === 'blocked' || readiness.state === 'conflicting' ? 'Resolve the readiness labels on the repository before starting work.' : null;
+  return { ...issue, identity, readiness, ...association, start_block_reason };
+}
+export function backlogHistory(jobs, issues) {
+  const loaded = new Set(issues.map(issue => issue.identity.key)), grouped = new Map();
+  for (const job of jobs) {
+    const identity = canonicalIssue(job.task?.source_url);
+    if (identity && loaded.has(identity.key)) continue;
+    const key = identity?.key || `local:${job.id}`;
+    if (!grouped.has(key)) grouped.set(key, { identity, key, title:job.task?.title || job.prompt?.split('\n')[0] || job.id, url:identity?.url || null,
+      source_status:identity ? 'not_loaded' : 'local', ...(identity ? executionAssociation(jobs, identity) : { executions:[{id:job.id,state:job.state,workflow:job.workflow?.name || null,phase:job.workflow?.steps?.[job.workflow.current_step] || null}] }) });
+  }
+  return [...grouped.values()];
+}

package/factory/lib.mjs

@@ -1,3 +1,4 @@
+import { readinessMapping } from './issue-lifecycle.mjs';
 import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
 import { resolve, dirname, join, isAbsolute } from 'node:path';
 import { spawnSync, spawn } from 'node:child_process';
@@ -76,6 +77,7 @@ export function configAt(state) {
     }
   }
   if (typeof config.check !== 'string' || !config.scope || !['project','service','environment','owner'].every(k=>typeof config.scope[k]==='string'&&config.scope[k].trim())) throw new Error('Missing check or installation scope');
+  readinessMapping(config.issueReadinessLabels);
   validateWebVerification(config.webVerification);
   return config;
 }

package/factory/providers/github.mjs

@@ -37,8 +37,8 @@ export function githubIssueProvider(repo, { read = githubRead, write = githubWri
   return {
     id: 'github', label: 'GitHub', repository, supported: true,
     capabilities: { issues: true, templates: true, create: true },
-    list: page => listIssues(repo, page, read),
-    preview: url => readIssue(repo, url, value => read(['issue', 'view', value, '--json', 'title,body,url,labels'])),
+    list: (page, state) => listIssues(repo, page, read, state),
+    preview: url => readIssue(repo, url, value => read(['issue', 'view', value, '--json', 'title,body,url,labels,state'])),
     templates: () => readTemplates(repo, read),
     draft: input => draftFromTemplate(repo, input, read),
     async context() {