software-defence-factory 0.15.5 → 0.16.0

package/bin/software-defence-factory.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { followActivity } from '../factory/activity-follow.mjs';
 import { harnessPreset, parseRoleDefinition, ROLE_CAPABILITIES } from '../factory/role-definition.mjs';
 import { inspectDefinition, previewDefinition, previewRollback } from '../factory/definition-store.mjs';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, chmodSync, openSync, closeSync, rmSync, renameSync, realpathSync } from 'node:fs';
@@ -29,6 +30,7 @@ const args = process.argv.slice(2), command = args.shift() || 'help';
 const positional = [], flags = {};
 for (let i=0;i<args.length;i++) {
   if (args[i].startsWith('--')) {
+    if (args[i] === '--follow') { flags.follow = true; continue; }
     if (!args[i+1] || args[i+1].startsWith('--')) throw new Error(`Value required for ${args[i]}`);
     flags[args[i].slice(2)] = args[++i];
   } else positional.push(args[i]);
@@ -231,6 +233,18 @@ try {
     const snapshot=await api(state,'/api/v1/status');
     console.log(JSON.stringify(command==='automations'?snapshot.automation_control:snapshot[command],null,2));
   }
+  else if(command==='activity') {
+    const [job, attempt] = positional;
+    if (!/^job_[a-f0-9]+$/.test(job || '') || !/^run_[a-f0-9]+$/.test(attempt || '')) throw new Error('activity requires JOB_ID RUN_ID; inspect status for exact identities');
+    const controller = new AbortController(), interrupt = () => controller.abort();
+    process.once('SIGINT', interrupt); process.once('SIGTERM', interrupt);
+    try {
+      await followActivity({ job, attempt, after: flags.after, limit: flags.limit || '50', follow: flags.follow === true,
+        interval: Number(flags['poll-ms'] || 2000), signal: controller.signal,
+        request: (path, signal) => api(state, path, undefined, undefined, { timeoutMs: 5000, signal }),
+        output: page => console.log(JSON.stringify(page)), unavailable: page => console.error(JSON.stringify(page)) });
+    } finally { process.removeListener('SIGINT', interrupt); process.removeListener('SIGTERM', interrupt); }
+  }
   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') {
     const config=configAt(state),dockerVersion=run('docker',['info','--format','{{.ServerVersion}}']),imageStatus=inspectImageInstallation(state,config);
@@ -383,6 +397,8 @@ Compatibility executable: software-defence-factory (same runtime and state)
   run --file task.md | --issue URL         Submit software (default), or --workflow defence
        [--source-ref REF]                 Pin a configured-repository ref before admission
   incident --file incident.json            Submit a private, read-only incident draft
+  activity JOB_ID RUN_ID [--after CURSOR] [--limit 1..128]
+    [--follow] [--poll-ms 1000..30000]      Bounded JSON activity; exact-attempt reconnect
   approve JOB_ID | cancel JOB_ID           Review gate / stop this attempt
   publish JOB_ID                          Publish/reconcile the accepted candidate as one draft PR
   abandon-delivery JOB_ID --branch-sha SHA Resolve an inspected pre-write collision; keep the remote branch

package/docs/interfaces.md

@@ -10,6 +10,7 @@ shell endpoint or a second scheduler.
 | Capability | CLI | Shared API | Dashboard | Remaining work |
 | --- | --- | --- | --- | --- |
 | Project/queue/attempt state | `status`, `inbox --source factory` JSON | `GET /api/v1/status` | Project, tasks, details/history | Stable versioned agent result/error contract |
+| Bounded phase activity | `activity JOB RUN`, tail/follow and cursor reconnect | Authenticated `GET /jobs/:job/runs/:run/activity` | Current detail and History; refresh/stale state | First slice; native/installed/browser qualification and health coverage remain open (#32) |
 | 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 | Primary list/Board with shared status/search/workflow/model/label filters, compact Repository tools/loaded scope, item count with secondary issue/execution totals and progressive linked detail; 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 |
@@ -177,3 +178,79 @@ observations of delivered-commit checks, not proof of required-check completion,
 branch protection, mergeability, deployment or model quality. Protected Verify,
 independent Review and explicit acceptance remain unchanged. #37 remains open
 for the other parity gaps above; no role/profile or workflow redesign is included.
+
+## Bounded execution activity (0.16.0, #32 first slice)
+
+`factory activity JOB_ID RUN_ID [--after CURSOR] [--limit 1..128] [--follow]
+[--poll-ms 1000..30000] --state PATH` reads the same authenticated
+`GET /api/v1/jobs/:job/runs/:run/activity?after=CURSOR&limit=N` contract as the
+issue detail. Discover identities with `status`. Without `after`, the default is
+the last 50 events; with it, return up to the limit after that cursor in ascending
+order. CLI output is one JSON page per line. Follow polls sequentially (default
+2 seconds, 5-second request timeout), preserves the cursor on transport/server
+failure, reports unavailability on stderr, reconnects to that exact attempt and
+stops after a terminal attempt's retained pages are drained. SIGINT/SIGTERM abort
+both a request and the polling delay. Invalid requests/identity/cursors are errors,
+not indefinite reconnects. Retry/revision creates another run: select it explicitly.
+
+Result activity selects the running attempt, otherwise the latest attempt with a
+recorded start, including failed, cancelled or interrupted execution. An unstarted
+Handoff approval or queued retry does not hide the previous execution. The card
+labels its phase and state; Observation details retains the full attempt identity.
+Initial work without a started attempt says so without inventing observations.
+History activity remains bound to each historical attempt.
+
+The version-1 response identifies job, attempt and phase. `next_cursor` is the
+last delivered event; `latest_cursor`, `oldest_cursor`, `has_more`, `truncated`
+and `dropped` make paging, tail omission and ring rollover explicit. Cursors are
+nonnegative safe integers scoped to the exact job/run URL; never carry one to a
+different attempt. Ahead-of-history cursors return 409; malformed cursor/limit
+returns 400; an unknown job or foreign run returns 404. Reads require the existing
+operator token or dashboard session, with unchanged Host/Origin protections.
+`status` is available, unavailable (including pre-feature history) or error
+(invalid/inaccessible storage). No raw logs are consulted or backfilled.
+
+`attempt_state`/`terminal` come from the queue; `completion_observed` only records
+an executor end event. Interrupted/cancelled attempts may lack the end and final
+unflushed observations. `phase_started_at` is the queue start, `last_received_at`
+is the latest stdout chunk received by the existing executor, and `saved_at` is
+the record checkpoint time. The most recent event carries its own receive-time
+`at`. `process_observation`/`process_observed_at` retain the last Docker **client**
+start/exit even after ring rollover; neither attests current process/container
+health. `container_health` is explicitly unknown. API `refreshed_at` and the UI's
+last successful read are reader facts, never worker heartbeats. Silence has no
+failure threshold. A failed UI refresh retains a stale-labelled view; refresh
+starts a new tail read. History reads remain tied to their original attempts.
+
+The stdout owner records phase start/end and client start/exit. Codex
+`item.completed` maps agent messages and command/file/search/MCP tool categories;
+Pi maps assistant `message_end` and `tool_execution_end`. Tool completion does not
+mean successful work. Reasoning, deltas, final aggregate message replay and nested
+events do not become activity. Unknown/custom/deterministic harnesses report
+unsupported event categories and retain only executor observations plus stdout
+receive times. Mapped tool categories are read, edit, command, search and other.
+Only fixed enums, timestamps, identities and bounded counters are returned.
+
+All input text is excluded: prompts, messages, reasoning, commands, arguments,
+results, paths, raw errors, arbitrary names and provider/credential data are never
+copied to activity. This is an allowlist, not heuristic string redaction. Native
+JSONL lines are capped at 64 KiB with strict UTF-8; malformed, oversized or trailing
+incomplete lines increment `rejected`, then parsing resumes at the next newline.
+Activity does not change canonical completion usage parsers or cost provenance.
+
+The host executor owns `jobs/JOB/RUN/activity.json`, outside worker mounts. A
+128-event ring and one fixed temporary file bound storage; at most one async
+atomic checkpoint is in flight, throttled to once per second during execution,
+with a final flush. Input buffers are fixed-size; readers cannot create queues,
+trigger writes or backpressure stdout. Readback caps bytes at 64 KiB and revalidates
+identity, schema, ordering, categories, timestamps and private regular-file paths.
+No activity is included in the main status payload. Checkpoint write failures do
+not abort the worker; `write_errors` reports them if storage recovers. If storage
+never recovers, missing/stale checkpoints cannot reveal the lost interval. A killed
+executor may lose the final uncheckpointed interval. Existing private logs and
+reports retain their separate bounded artifact rules; previews are labelled
+snapshots with explicit refresh. Observations grant no acceptance/action authority.
+
+This first slice leaves #32 open for independent installed/native Z13 and visual
+browser qualification, richer genuinely observed health, and broader provider
+coverage. See the actual evidence and limits in [proof](proof.md).

package/docs/npm.md

@@ -116,8 +116,8 @@ installation or retained attempt needs them.
 
 ## Protected evidence compatibility
 
-Factory 0.15.2 recognizes version-1 execution profiles emitted by native
-**0.8.0, 0.9.0, 0.9.1, 0.10.0, 0.11.0, 0.11.1, 0.11.2, 0.12.0, 0.13.0, 0.13.1, 0.14.0, 0.15.0, 0.15.1 and 0.15.2**. This is an exact allowlist in
+Factory 0.16.0 recognizes version-1 execution profiles emitted by native
+**0.8.0, 0.9.0, 0.9.1, 0.10.0, 0.11.0, 0.11.1, 0.11.2, 0.12.0, 0.13.0, 0.13.1, 0.14.0, 0.15.0, 0.15.1, 0.15.2, 0.15.3, 0.15.4, 0.15.5, 0.15.6 and 0.16.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
@@ -185,7 +185,8 @@ Verify evidence and cannot authorize acceptance or publication.
 Version 0.14.0 preserves the v1 writer only for unchanged inherited installations:
 policy bytes, candidate/check/review/acceptance bindings, mounts and credential
 rules stay compatible. Adopted role overrides use **v2 from 0.14.0, 0.15.0, 0.15.1 and 0.15.2**, recording
-role/provider/effort and an exact selection digest. The executor verifies the
+role/provider/effort and an exact selection digest. Later audited v2 writers are
+**0.15.3, 0.15.4, 0.15.5, 0.15.6 and 0.16.0**. The executor verifies the
 frozen common configuration before phase selection; continuation and both delivery
 validation paths require matching protected v2 evidence and private frozen config.
 V1 cannot attest an override. Mixed roles share one policy across deterministic
@@ -220,9 +221,29 @@ that the release is not yet downloadable, retain the prior runtime and retry the
 update later. This does not establish whether a particular delay came from a
 local cache or registry propagation.
 
-For a release, update both manifests with `npm version patch --no-git-tag-version`,
-review the change, and push through the project's normal review flow. A code
-push without a version bump is tested but does not overwrite a published package.
+Before shipping any version, including a documentation-only patch:
+
+1. Audit the diff from the previous release across profile/evidence writers,
+   schemas, isolation, frozen selection and policy hashes, checks, candidate
+   reconstruction, review and acceptance. Add only the exact audited writer to
+   the applicable v1/v2/v3 lists in `factory/execution-profile.mjs`. Never derive
+   compatibility from package `VERSION` or a semver range; an incompatible writer
+   blocks release until its evidence contract is resolved.
+2. Align `package.json`, the lockfile root and `packages[""]` versions (for
+   example with `npm version patch --no-git-tag-version`). Run
+   `npm ci --ignore-scripts`, `npm run build:dashboard` and `npm run check` on the
+   final candidate, then inspect the packed artifact. Exercise the native current
+   writer, retained evidence, continuation and protected-evidence rejection
+   checks. Keep unknown-writer fixtures clearly unaudited (for example `99.0.0`),
+   and preserve historical bytes and every current-policy guard.
+3. Obtain independent review of that exact candidate and qualify the installed
+   CLI/API with retained evidence. Deliver through the protected PR/main CI flow,
+   verify the public npm artifact against the reviewed package, then adopt only
+   while idle and reconciled with private configuration, history and rollback
+   data preserved. Source tests alone do not establish these delivery gates.
+
+A code push without a version bump is tested but does not overwrite a published
+package.
 
 The current trusted-publisher identity is npm package `software-defence-factory`,
 GitHub owner `arcitai`, repository `software-and-defence-factory`,
@@ -254,7 +275,7 @@ The 0.15.0 compatibility audit preserves unchanged v1/v2 policy construction,
 protected checks, candidate reconstruction, read-only review and acceptance guards.
 Historical 0.14.0 v2 validation compares its actual writer version rather than
 relabeling it as the installed version. Local registry selection is a new execution
-contract: every phase of a local/hybrid attempt requires **v3 from 0.15.0, 0.15.1 or 0.15.2** and its
+contract: every phase of a local/hybrid attempt requires **v3 from 0.15.0, 0.15.1, 0.15.2, 0.15.3, 0.15.4, 0.15.5, 0.15.6 or 0.16.0** and its
 exact protected frozen configuration. v1/v2 cannot attest local binding fields,
 providers or a common policy containing a selected local role. A selected endpoint,
 model, limit or compatibility change invalidates the current policy; explicit
@@ -292,3 +313,29 @@ remain unchanged from 0.15.4. Profile tests exercise all phases and inherited,
 cloud, hybrid and local definitions, reject changed selections and future writers,
 and verify immutable readback. This does not upgrade or qualify historical local
 attempts; installed image adoption and actual inference remain separate gates.
+
+The 0.15.6 audit adds only that exact writer to the explicit v1/v2/v3 lists for
+the packaged setup-guide correction. Compared with 0.15.5, profile/evidence
+writers and schemas, isolation, frozen selection/policy hashes, checks,
+reconstruction, review and acceptance are unchanged. The runtime emits its new
+version even for a documentation-only release, so changing package metadata
+alone is insufficient. Retained evidence keeps its original version and bytes;
+unknown writers/schemas and altered selections remain blocked. This audit does
+not qualify local model productivity or upgrade failed attempts.
+
+
+The 0.16.0 audit extends only the exact v1/v2/v3 writer allowlists. Compared
+with admitted main 16a47cd (0.15.6), activity is a new host-owned, read-only
+observation contract. Execution profile/evidence writers and schemas, effective
+policy construction, role/local selection digests, candidate reconstruction,
+checks/review/acceptance and delivery target guards are unchanged. Activity is
+never an input to any protected-evidence reader. Regression coverage exercises
+current emission and retained 0.15.6 inherited/cloud/hybrid/local profiles, all
+phases, changed policy/selection/image/schema rejection and unchanged retained
+bytes. Controlled delivery fixtures exercise exact known v1 writers through
+capability derivation and publication validation, including 0.16.0; future
+0.16.1/unknown writers remain rejected. This does not qualify an old failed
+attempt or a live installation. No image, mounted kit/skill or Pi launcher code
+changed, so this capability does not require a new worker image. Qualification
+must use the operator's actually selected image; no image adoption is performed
+by this source change.

package/docs/setup.md

@@ -393,43 +393,67 @@ local requests still use `issue start --file` or `--draft` without `--brief-file
 
 ## Optional keyless local or hybrid inference
 
-Use the [local binding recipe](definition.md#opt-in-local-bindings-0150-69) to adopt
-an explicit private endpoint/model map and portable Pi role references. Keep the
-working default and a stopped private-state backup; preview, apply while idle and
-use revision-guarded rollback. A local Implement role can be paired with an existing
-cloud Review role. No downloads, service restarts, port changes or jobs occur during
-configuration. Authenticated endpoints, sampling overrides and custom thinking
-maps are unsupported. Local bindings may request OpenAI-style `reasoningEffort`:
-`default` (or omitted), `none`, `low`, `medium` or `high`. Default omits the request;
-it does not disable server thinking. Qualify the endpoint's actual semantics before
-using a request as a thinking-budget control. Unsupported requests fail without
-fallback when the endpoint rejects them; transport success alone cannot prove a
-server honored the request. Existing omitted choices remain unchanged.
-
-Qualify the actual installed image and endpoint from an isolated job before using
-it for application work. Record server/harness versions, exact model ID and digest,
-quantization, GPU/backend and actual offload, available and peak memory, endpoint
-reachability, tool-call/result compatibility and report/check/review outcomes.
-Keep host inference access separate from controller/forge credentials. Unknown
-values stay unknown; registry discovery only proves client capability.
-
-Reconcile the client's configured context with the server's actual allocation and
-per-request/model overrides. Do not infer a 65k allocation from a remembered agent
-setting or a server default. A bounded 64k/128k allocation experiment, where
-supported, must record KV-cache and Flash Attention settings, memory and allocation
-success separately from long-context task quality. This worker supplies no such
-measurements or driver/kernel advice. Do not recommend larger windows from the
-schema's upper limit.
-
-The operator still owns #69's matched two-fixture comparison: pinned bases,
-comparable prompts/contexts/trials, a measured existing local baseline and one
-selected alternative, decisive independent checks and separate Review contexts.
-Retain failures, repairs and human time. Record wall time, observable prefill/decode,
-input/cached/output tokens, memory/offload and all reviewer usage. Factory currently
-leaves Pi usage unknown; controlled protocol fixtures are not token or quality
-benchmarks. Include cloud Review in hybrid totals. No provider token billing for
-local inference does not mean zero electricity, hardware or operator cost. Only
-then qualify a suitable real Factory issue; no customer jobs are part of this slice.
+Local profiles are opt-in. Follow the [local binding contract](definition.md#opt-in-local-bindings-0150-69)
+for supported fields and commands; configuration is not qualification and starts
+no jobs, downloads or inference services.
+
+1. **Keep the working configuration.** Export portable roles with
+   `factory definition export --state PATH > factory-roles.json`. Export omits
+   private bindings: also retain the selected immutable image ID and a complete
+   stopped private-state backup using [recovery](recovery.md).
+2. **Qualify the inference path.** From a disposable container using the selected
+   job image and network, verify the exact endpoint/model, tool calls/results and
+   report compatibility. Record server/harness versions, model digest and
+   quantization, GPU/backend and actual offload, available/peak memory and actual
+   context allocation, including request/model overrides. Host loopback is not
+   container loopback. Keep inference access separate from forge/controller
+   credentials; missing models/providers must fail without silent cloud fallback.
+3. **Preview and explicitly apply roles.** Use the linked binding recipe to select
+   local Pi Implement and an independently chosen local or cloud Review. Preview
+   with `factory definition diff`, then use `factory definition apply` with the
+   same `--state`, `--file`, `--bindings-file` and the preview's `--expected-revision`.
+   Apply requires the
+   running controller to be idle and reconciled. Agents/Definition uses the same
+   diff/apply contract. Inspect the effective selections; each attempt freezes
+   them with its resource, timeout and skill policy. CLI upgrades and worker-image
+   selection are separate; use the [image procedure below](#local-context-budget-and-worker-image-0152-100)
+   if the selected image needs changing.
+4. **Qualify bounded representative work before a real repository issue.** Use
+   pinned fixture bases, observable decisive tests independent of Implement, and
+   separate Review contexts. For a comparison, use two small software fixtures,
+   comparable prompts/contexts/trials, a measured local baseline and one selected
+   local/hybrid alternative. Build returns to Factory's checks, independent Review
+   and operator handoff; it does not launch another review pipeline. Set explicit
+   deadlines/resource budgets and exercise tool use, context recovery and reports.
+5. **Inspect history and usage.** Use `factory status --state PATH` and the
+   dashboard's attempt history/Analytics. Retain raw failures, diagnostics,
+   unfinished work and repairs under [recovery](recovery.md). Record wall time,
+   observable prefill/decode throughput, memory/offload, token observations,
+   tool/report failures, checks/review outcomes and human time, including cloud
+   Review usage in hybrid totals. Unknown measurements stay unknown; see
+   [qualification evidence and limits](proof.md) before generalizing a result.
+6. **Roll back explicitly when needed.** With the running controller idle,
+   `factory definition rollback --state PATH` previews the previous roles/bindings;
+   add `--expected-revision` from that preview to apply it. Image rollback is a
+   separate stopped-installation operation described below. Preserve attempts and
+   backups; rollback does not rewrite failed history or retry work.
+
+Fresh Pi completed-message observations have **partial** coverage: input includes
+cache reads/writes, with cached input, cache-write input and output shown separately;
+cache subsets are not added again. Absent or old usage remains unknown, with no Pi
+historical backfill. Summary and unreported error/retry usage remains unreported,
+even when the attempt succeeds. See [Pi usage semantics](usage.md#pi-stdout-measurements-0154).
+These observations establish neither total cost nor speed or quality. Local
+inference avoids provider token billing, not electricity, hardware or operator cost.
+
+Set context/output limits against actual allocation with headroom as described
+below. Before recommending larger windows, test a bounded 64k/128k allocation
+where supported, recording KV-cache/Flash Attention settings and memory separately from
+long-context task quality. An advertised window or successful short prompt is
+insufficient. Authenticated local endpoints, sampling overrides and custom thinking
+maps are unsupported; supported reasoning-effort requests still need endpoint
+qualification and do not prove a server honored them. No model/provider is chosen
+automatically. Broader local/hybrid qualification remains open in #69.
 
 
 ## Local Pi project resources (0.15.3, #103)
@@ -455,13 +479,12 @@ extensions/packages and automatically discovered repository skills are not a
 supported configuration path. Explicit task-driven file reads are still possible
 within the sandbox and grant no additional authority.
 
-Before accepting this repair, the lead must qualify the exact installed 0.15.3
-package/image through CLI/API, representative native local Build and separate
-read-only Review, and one actual local-model run. `npm run qualify:pi` uses actual
-Pi with **synthetic HTTP inference**, not model judgment. See [trust-store
-proof and limits](proof.md#pi-project-trust-startup-0153-103). Retain the failed
-#51 attempt unchanged and unaccepted; retry only through a newly authorized
-attempt after qualification. Do not modify private installations from a job.
+Qualify native local Build and separate read-only Review with the exact selected
+image and model. `npm run qualify:pi` exercises actual Pi with **synthetic HTTP
+inference**, not model judgment. See [trust-store proof and limits](proof.md#pi-project-trust-startup-0153-103)
+and the later qualification records in [proof](proof.md). Preserve failed attempts
+and use [recovery](recovery.md) before retrying; jobs must not modify private
+installations.
 
 ## Local context budget and worker image (0.15.2, #100)
 
@@ -509,9 +532,8 @@ guessed or silently rewritten. Do not add project Pi settings to bypass
 the admitted binding or rely on custom tuning that has not been qualified.
 See [pinned compaction behavior](https://github.com/earendil-works/pi/blob/v0.87.1/packages/coding-agent/docs/compaction.md).
 
-Starting with the **0.15.5 candidate (#105)**, the local adapter also checks
-history pressure at Pi's completed-tool-turn boundary. This conservative byte
-signal counts the system/task/tool envelope once, call arguments, non-tool text
+The local adapter also checks history pressure at Pi's completed-tool-turn
+boundary. This conservative byte signal counts the system/task/tool envelope once, call arguments, non-tool text
 and capped tool excerpts, separately from provider-reported usage. At 65% of the
 input budget it considers Pi's supported summary generator and append-only
 compaction entry. The newest complete tool group is retained; up to three older
@@ -541,7 +563,7 @@ output on pinned Pi). `factory_context_recovery` JSONL events record only
 pressure, envelope/floor sizes, group counts and recovery progress, without
 prompts/content. Pi token accounting stays partial; this summary path is not
 added to ordinary assistant usage totals. See
-[source measurements, rejected real trial and pending qualification](proof.md#short-local-pi-history-recovery-0155-candidate-105).
+[context-recovery measurements, retained failures and qualification limits](proof.md#short-local-pi-history-recovery-0155-candidate-105).
 
 Before adoption, stop and reconcile all work, retain the old immutable image ID
 and a stopped private-state backup. Build/qualify the exact candidate image, then
@@ -556,7 +578,7 @@ readable and cloud profiles keep their existing wrapper. Roll back with the reta
 path and restore the previously working role definition through revision-guarded
 rollback. Do not change frozen attempts or relabel old failed results.
 
-Lead's bounded actual-inference fixture must include enough tool results to trigger
+A bounded actual-inference fixture must include enough tool results to trigger
 summarization, resumed useful tool work, the required report, checks and independent
 Review. Record the exact image/model digest, harness/server versions, allocated
 window, output/reasoning request, tool growth, compaction ordering, elapsed time,
@@ -564,6 +586,6 @@ quality outcome and peak memory; unknown measurements remain null. Set an explic
 job deadline/resource budget and preserve any unfinished checkout and diagnostic
 artifacts. A short successful prompt is insufficient. A larger actually allocated
 window is a later measured comparison only if this evidence warrants it; do not
-switch model or cloud provider automatically. The failed #83 local attempt is not
-local delivery. An operator-selected fresh cloud retry and unfinished-checkpoint
-recovery remain governed by [recovery](recovery.md) and #42.
+switch model or cloud provider automatically. An operator-selected fresh cloud
+retry and unfinished-checkpoint recovery remain governed by [recovery](recovery.md); neither converts failed local work into local
+delivery.

package/factory/activity-follow.mjs

@@ -0,0 +1,23 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { activityQuery } from './activity.mjs';
+
+// One request at a time; reconnect always retains the exact attempt and cursor.
+export async function followActivity({ request, job, attempt, after = null, limit = '50', follow = false,
+  interval = 2000, signal, output, unavailable }) {
+  let { cursor } = activityQuery(after, limit);
+  if (!Number.isSafeInteger(interval) || interval < 1000 || interval > 30000) throw new Error('Activity poll interval must be 1000–30000 ms');
+  do {
+    if (signal?.aborted) return;
+    try {
+      const page = await request(`/api/v1/jobs/${job}/runs/${attempt}/activity?limit=${limit}${cursor === null ? '' : `&after=${cursor}`}`, signal);
+      if (signal?.aborted) return;
+      output(page); cursor = page.next_cursor;
+      if (!follow || (page.terminal && !page.has_more)) return;
+    } catch (error) {
+      if (signal?.aborted) return;
+      if (!follow || /Controller 4\d\d:/.test(error.message)) throw error;
+      unavailable({ status: 'unavailable', job, attempt, next_cursor: cursor, refreshed_at: null });
+    }
+    try { await delay(interval, undefined, { signal }); } catch { if (signal?.aborted) return; }
+  } while (follow);
+}

package/factory/activity.mjs

@@ -0,0 +1,174 @@
+// Private execution observations, never evidence, usage or action authority.
+import { open, rename, rm } from 'node:fs/promises';
+import { constants, fstatSync, lstatSync, openSync, readSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const ACTIVITY_CAP = 128;
+export const ACTIVITY_BYTES = 64 * 1024;
+export const ACTIVITY_LINE_BYTES = 64 * 1024;
+export const ACTIVITY_KINDS = Object.freeze(['phase_started', 'process_started', 'message_completed',
+  'tool_completed', 'process_exited', 'phase_completed', 'phase_error']);
+export const TOOL_CATEGORIES = Object.freeze(['read', 'edit', 'command', 'search', 'other']);
+const phases = ['build', 'verify', 'review', 'handoff', 'defence'];
+const timestamp = value => typeof value === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value) && Number.isFinite(Date.parse(value));
+const integer = value => Number.isSafeInteger(value) && value >= 0;
+const keys = (value, allowed) => value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).every(key => allowed.includes(key));
+const increment = value => Math.min(Number.MAX_SAFE_INTEGER, value + 1);
+const codexTools = { command_execution: 'command', file_change: 'edit', web_search: 'search', mcp_tool_call: 'other' };
+const piTools = { read: 'read', write: 'edit', edit: 'edit', bash: 'command', grep: 'search', find: 'search', ls: 'read' };
+
+// Independent from usage parsing: strict UTF-8 JSONL, no tail fragments, no raw
+// input retained after each line, and a fixed buffer even for newline-free output.
+export class ActivityParser {
+  constructor(harness, emit, received = () => {}, lost = () => {}) {
+    this.harness = harness; this.emit = emit; this.received = received; this.lost = lost;
+    this.buffer = Buffer.alloc(ACTIVITY_LINE_BYTES); this.length = 0; this.overflow = false;
+    this.decoder = new TextDecoder('utf-8', { fatal: true });
+  }
+  write(chunk) {
+    if (!chunk.length) return;
+    this.received();
+    if (!['codex', 'pi'].includes(this.harness)) return;
+    for (const byte of chunk) {
+      if (byte === 10) { this.complete(); continue; }
+      if (this.length < this.buffer.length) this.buffer[this.length++] = byte;
+      else this.overflow = true;
+    }
+  }
+  complete() {
+    try {
+      if (this.overflow) throw new Error();
+      if (!this.length) return;
+      const event = JSON.parse(this.decoder.decode(this.buffer.subarray(0, this.length)));
+      if (!event || typeof event !== 'object' || Array.isArray(event)) throw new Error();
+      if (this.harness === 'codex' && event.type === 'item.completed') {
+        const type = event.item?.type;
+        if (type === 'agent_message') this.emit('message_completed');
+        else if (Object.hasOwn(codexTools, type)) this.emit('tool_completed', codexTools[type]);
+      }
+      if (this.harness === 'pi') {
+        if (event.type === 'message_end' && event.message?.role === 'assistant') this.emit('message_completed');
+        if (event.type === 'tool_execution_end' && typeof event.toolName === 'string')
+          this.emit('tool_completed', Object.hasOwn(piTools, event.toolName) ? piTools[event.toolName] : 'other');
+      }
+    } catch { this.lost(); }
+    finally { this.buffer.fill(0, 0, this.length); this.length = 0; this.overflow = false; }
+  }
+  finish() {
+    if (this.length || this.overflow) this.lost();
+    this.buffer.fill(0); this.length = 0; this.overflow = false;
+  }
+}
+
+export class ActivityWriter {
+  constructor(directory, { job, attempt, phase, harness }, { interval = 1000 } = {}) {
+    this.path = join(directory, 'activity.json'); this.interval = interval;
+    this.record = { version: 1, job, attempt, phase, support: ['codex', 'pi'].includes(harness) ? harness : 'unsupported',
+      cursor: 0, dropped: 0, rejected: 0, write_errors: 0, last_received_at: null, process_observation: null, process_observed_at: null, saved_at: null, events: [] };
+    this.dirty = false; this.pending = null; this.timer = null; this.closed = false;
+    this.parser = new ActivityParser(harness, (kind, tool) => this.emit(kind, tool),
+      () => { this.record.last_received_at = new Date().toISOString(); this.schedule(); },
+      () => { this.record.rejected = increment(this.record.rejected); this.schedule(); });
+    this.emit('phase_started');
+  }
+  emit(kind, tool) {
+    if (!ACTIVITY_KINDS.includes(kind) || (tool !== undefined && !TOOL_CATEGORIES.includes(tool))) throw new Error('Invalid activity category');
+    if (this.record.cursor === Number.MAX_SAFE_INTEGER) { this.record.rejected = increment(this.record.rejected); this.schedule(); return; }
+    if (['process_started', 'process_exited'].includes(kind)) {
+      this.record.process_observation = kind; this.record.process_observed_at = new Date().toISOString();
+    }
+    this.record.events.push({ cursor: ++this.record.cursor, at: new Date().toISOString(), kind, ...(tool ? { tool } : {}) });
+    if (this.record.events.length > ACTIVITY_CAP) { this.record.events.shift(); this.record.dropped++; }
+    this.schedule();
+  }
+  schedule() {
+    this.dirty = true;
+    if (!this.closed && !this.timer) this.timer = setTimeout(() => { this.timer = null; void this.flush(); }, this.interval);
+  }
+  async flush() {
+    if (this.pending) { await this.pending; return; }
+    if (!this.dirty) return;
+    this.dirty = false;
+    const snapshot = JSON.stringify({ ...this.record, saved_at: new Date().toISOString() });
+    // At most one write in flight; clients never trigger writes. A fixed temp
+    // name and atomic replacement bound disk usage to two capped records.
+    this.pending = (async () => {
+      let handle;
+      try {
+        handle = await open(`${this.path}.tmp`, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, 0o600);
+        await handle.chmod(0o600); await handle.writeFile(snapshot); await handle.sync(); await handle.close(); handle = null;
+        await rename(`${this.path}.tmp`, this.path);
+      } catch {
+        this.record.write_errors = increment(this.record.write_errors); this.dirty = true;
+        await handle?.close().catch(() => {}); await rm(`${this.path}.tmp`, { force: true }).catch(() => {});
+      }
+    })();
+    await this.pending; this.pending = null;
+    if (this.dirty && !this.closed) this.schedule();
+  }
+  async finish(success) {
+    if (this.closed) return;
+    this.closed = true; clearTimeout(this.timer); this.timer = null;
+    this.parser.finish(); this.emit(success ? 'phase_completed' : 'phase_error');
+    await this.pending; await this.flush();
+  }
+}
+
+export function activityQuery(after, limit = '50') {
+  if (after !== null && after !== undefined && !/^(0|[1-9]\d{0,15})$/.test(String(after))) throw Object.assign(new Error('Invalid activity cursor'), { status: 400 });
+  const cursor = after == null ? null : Number(after), count = Number(limit);
+  if ((cursor !== null && !integer(cursor)) || !/^[1-9]\d{0,2}$/.test(String(limit)) || !integer(count) || count > ACTIVITY_CAP)
+    throw Object.assign(new Error('Invalid activity cursor or limit'), { status: 400 });
+  return { cursor, limit: count };
+}
+
+export function readActivity(state, job, attempt, query = activityQuery(null)) {
+  if (!/^job_[a-f0-9]+$/.test(job.id) || !/^run_[a-f0-9]+$/.test(attempt.id) || !phases.includes(attempt.command))
+    throw Object.assign(new Error('Activity identity unavailable'), { status: 400 });
+  const terminal = ['succeeded', 'failed', 'cancelled', 'interrupted'].includes(attempt.state);
+  const result = { version: 1, job: job.id, attempt: attempt.id, phase: attempt.command,
+    attempt_state: attempt.state, terminal, container_health: 'unknown', refreshed_at: new Date().toISOString(),
+    status: 'unavailable', support: 'unknown', events: [], next_cursor: query.cursor ?? 0,
+    latest_cursor: null, oldest_cursor: null, truncated: false, has_more: false,
+    last_received_at: null, process_observation: null, process_observed_at: null, phase_started_at: timestamp(attempt.started_at) ? attempt.started_at : null,
+    saved_at: null, dropped: 0, rejected: 0, write_errors: 0, completion_observed: false };
+  let record, fd;
+  try {
+    const folder = join(state, 'jobs', job.id, attempt.id);
+    for (const dir of [join(state, 'jobs'), join(state, 'jobs', job.id), folder]) {
+      const stat = lstatSync(dir);
+      if (!stat.isDirectory() || stat.isSymbolicLink() || (stat.mode & 0o077)) throw new Error();
+    }
+    fd = openSync(join(folder, 'activity.json'), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || (stat.mode & 0o077) || stat.size > ACTIVITY_BYTES) throw new Error();
+    const buffer = Buffer.alloc(ACTIVITY_BYTES + 1), size = readSync(fd, buffer, 0, buffer.length, 0);
+    if (size > ACTIVITY_BYTES) throw new Error();
+    record = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, size)));
+    if (!keys(record, ['version','job','attempt','phase','support','cursor','dropped','rejected','write_errors','last_received_at','process_observation','process_observed_at','saved_at','events'])
+      || record.version !== 1 || record.job !== job.id || record.attempt !== attempt.id || record.phase !== attempt.command
+      || !['codex','pi','unsupported'].includes(record.support) || !integer(record.cursor) || !integer(record.dropped)
+      || !integer(record.rejected) || !integer(record.write_errors) || !timestamp(record.saved_at)
+      || (record.last_received_at !== null && !timestamp(record.last_received_at))
+      || (record.process_observation === null ? record.process_observed_at !== null
+        : !['process_started','process_exited'].includes(record.process_observation) || !timestamp(record.process_observed_at))
+      || !Array.isArray(record.events) || !record.events.length || record.events.length > ACTIVITY_CAP
+      || record.cursor !== record.dropped + record.events.length) throw new Error();
+    for (const [index, event] of record.events.entries()) {
+      if (!keys(event, ['cursor','at','kind','tool']) || event.cursor !== record.dropped + index + 1
+        || !timestamp(event.at) || !ACTIVITY_KINDS.includes(event.kind)
+        || (event.kind === 'tool_completed' ? !TOOL_CATEGORIES.includes(event.tool) : event.tool !== undefined)) throw new Error();
+    }
+  } catch (error) { result.status = error.code === 'ENOENT' ? 'unavailable' : 'error'; return result; }
+  finally { if (fd !== undefined) closeSync(fd); }
+  if (query.cursor !== null && query.cursor > record.cursor) throw Object.assign(new Error('Activity cursor is ahead of retained history; reconnect with the same attempt and no cursor'), { status: 409 });
+  const start = query.cursor ?? Math.max(record.dropped, record.cursor - query.limit);
+  const events = record.events.filter(event => event.cursor > start).slice(0, query.limit);
+  return { ...result, status: 'available', support: record.support, events,
+    next_cursor: events.at(-1)?.cursor ?? start, latest_cursor: record.cursor, oldest_cursor: record.dropped + 1,
+    truncated: start < record.dropped || (query.cursor === null && start > 0),
+    has_more: (events.at(-1)?.cursor ?? start) < record.cursor,
+    last_received_at: record.last_received_at, process_observation: record.process_observation, process_observed_at: record.process_observed_at, saved_at: record.saved_at,
+    dropped: record.dropped, rejected: record.rejected, write_errors: record.write_errors,
+    completion_observed: ['phase_completed', 'phase_error'].includes(record.events.at(-1)?.kind) };
+}