instar 1.3.1312 → 1.3.1313

package/src/scaffold/templates/jobs/instar/feedback-factory-process.md

@@ -16,29 +16,122 @@ toolAllowlist: "*"
 unrestrictedTools: true
 mcpAccess: none
 ---
-Run one feedback-factory operating-drain tick. This is a near-silent operated cadence — do NOT message the user. The server owns every transition; this job only triggers and sanity-checks one bounded run.
+Run one feedback-factory operating-drain tick. This is a near-silent operated cadence — do NOT message the user. The server owns every transition; this job only triggers one bounded run and records an honest outcome.
 
-AUTH="${INSTAR_AUTH_TOKEN:-$(python3 -c "import json; v=json.load(open('.instar/config.json')).get('authToken',''); print(v if isinstance(v, str) else '')" 2>/dev/null)}"
-AGENT_ID="${INSTAR_AGENT_ID:-$(python3 -c "import json; print(json.load(open('.instar/config.json')).get('projectName',''))" 2>/dev/null)}"
-PORT="${INSTAR_PORT:-4042}"
-NONCE="feedback-drain-$(date +%s)-$$"
+Run the command below ONCE, exactly as written, in a single Bash call with `timeout: 300000`. Do not rewrite it, split it, or re-type it as shell code: the script carries every rule of this job, and an improvised shell loop has broken it before (zsh refuses a variable named `status`, and the run was recorded as a success).
 
-1. Read the operated drain's posture:
-   `curl -s -w '\nHTTP %{http_code}\n' -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" http://localhost:$PORT/feedback-factory/drain/status`
-   Rule on the JSON body's `posture.state`, whatever the HTTP code (a 503 body carries `posture` too). Read `developmentAgent` from `.instar/config.json`.
-   - `live` → go to step 2.
-   - `dark` → exit silently. The drain is switched off on purpose (fleet default, or an operator switch-off).
-   - `unavailable` → FAIL THE RUN with reason `drain posture unavailable: <posture.reason>`.
-   - Anything else — no JSON, no `posture` field, connection refused, 401, 403, any other code → if `developmentAgent` is true, FAIL THE RUN with reason `drain status unreadable: HTTP <code or unreachable>`; otherwise exit silently.
+```bash
+python3 - <<'FEEDBACK_DRAIN_TICK'
+import json, os, sys, time, urllib.error, urllib.request
 
-   To FAIL THE RUN, run exactly this (with the reason filled in), then stop and finish normally — do not retry, do not tick:
-   `[ -n "$INSTAR_JOB_FAILURE_FILE" ] && printf '%s' "<reason>" > "$INSTAR_JOB_FAILURE_FILE"`
-   The scheduler reads that file when this run ends and records the run as failed with the reason. Saying "failed" in your output does NOT record a failure; only the file does.
+def config():
+    try:
+        with open('.instar/config.json') as fh:
+            return json.load(fh)
+    except Exception:
+        return {}
 
-2. Trigger one bounded drain tick:
-   `curl -s -X POST -H "Authorization: Bearer $AUTH" -H "X-Instar-AgentId: $AGENT_ID" -H "X-Instar-Request: 1" -H "X-Instar-Request-Nonce: $NONCE" http://localhost:$PORT/feedback-factory/drain/tick`
-   A 202 response reports `{ runId, accepted, reason? }`. Concurrent triggers return the active run rather than starting a second writer. Poll the status route, bounded to 90 seconds, until `lastRun.runId` matches and `lastRun.state` is no longer `accepted` or `running`; never start a second tick while polling.
+CONFIG = config()
+TOKEN = os.environ.get('INSTAR_AUTH_TOKEN') or (CONFIG.get('authToken') if isinstance(CONFIG.get('authToken'), str) else '')
+AGENT_ID = os.environ.get('INSTAR_AGENT_ID') or str(CONFIG.get('projectName') or '')
+BASE = 'http://localhost:' + str(os.environ.get('INSTAR_PORT') or CONFIG.get('port') or 4042)
+DEVELOPMENT_AGENT = CONFIG.get('developmentAgent') is True
+POLL_SECONDS = float(os.environ.get('FEEDBACK_DRAIN_POLL_SECONDS') or 60)
 
-3. **Tier-1 supervision.** Accept terminal `succeeded` and `no-op`. A `degraded` run must carry a nonempty reason; a `degraded` run without one → FAIL THE RUN (step 1 command) with reason `degraded run without reason: <runId>`. Never retry in the same run; the durable queue and next cadence own retry. In simulation, canonical claimed/completed counts must not advance. In live mode, completed may never exceed the durable claimed/linked history or the configured batch bound. A broken invariant → FAIL THE RUN with reason `invariant broken: <which>`. A poll that ends at 90 seconds with the run still `accepted`/`running` is not a failure; the next cadence observes it.
+def fail(reason):
+    path = os.environ.get('INSTAR_JOB_FAILURE_FILE')
+    if path:
+        with open(path, 'w') as fh:
+            fh.write(reason[:480])
+    print('FEEDBACK_DRAIN_RESULT failed: ' + reason)
+    sys.exit(0)
 
-4. Exit silently. Do NOT relay anything to Telegram and do NOT summarize. The drain's durable run row, metrics, and bounded self-heal/attention path own observability; a declared failure reaches the operator through the scheduler's consecutive-failure alert.
+def done(message):
+    print('FEEDBACK_DRAIN_RESULT ' + message)
+    sys.exit(0)
+
+def call(method, route, extra=None):
+    headers = {'Authorization': 'Bearer ' + TOKEN, 'X-Instar-AgentId': AGENT_ID}
+    headers.update(extra or {})
+    request = urllib.request.Request(BASE + route, method=method, headers=headers, data=b'' if method == 'POST' else None)
+    try:
+        with urllib.request.urlopen(request, timeout=10) as response:
+            code, raw = response.status, response.read()
+    except urllib.error.HTTPError as error:
+        code, raw = error.code, error.read()
+    except Exception as error:
+        return None, 'unreachable (' + type(error).__name__ + ')'
+    try:
+        return code, json.loads(raw.decode('utf8') or 'null')
+    except Exception:
+        return code, None
+
+def drain_status():
+    code, body = call('GET', '/feedback-factory/drain/status')
+    posture = body.get('posture') if isinstance(body, dict) else None
+    state = posture.get('state') if isinstance(posture, dict) else None
+    return code, body, posture, state
+
+def count(value):
+    try:
+        return int(value or 0)
+    except (TypeError, ValueError):
+        return 0
+
+def work_counts(body):
+    work = ((body or {}).get('drain') or {}).get('work') or {}
+    return count(work.get('claimed')) + count(work.get('completed'))
+
+# 1. Posture: the JSON posture decides, whatever the HTTP code.
+code, before, posture, state = drain_status()
+if state == 'dark':
+    done('dark')
+if state == 'unavailable':
+    fail('drain posture unavailable: ' + str(posture.get('reason') or 'unknown'))
+if state != 'live':
+    if DEVELOPMENT_AGENT:
+        fail('drain status unreadable: HTTP ' + (str(code) if isinstance(code, int) else str(before)))
+    done('status unreadable on a fleet agent')
+
+# 2. One bounded tick. A refused tick is a failed run (for example a demoted authority).
+nonce = 'feedback-drain-' + str(int(time.time())) + '-' + str(os.getpid())
+code, tick = call('POST', '/feedback-factory/drain/tick', {'X-Instar-Request': '1', 'X-Instar-Request-Nonce': nonce})
+if code != 202 or not isinstance(tick, dict) or not tick.get('runId'):
+    detail = tick.get('error') if isinstance(tick, dict) else tick
+    fail('drain tick refused: HTTP ' + str(code) + ' ' + str(detail or ''))
+run_id = tick['runId']
+if tick.get('proxied'):
+    done('proxied to the owner machine, run ' + run_id + '; the owner records its outcome')
+
+# 3. Poll this run to a terminal state (60 s). Still running at the limit is not a failure.
+deadline = time.time() + POLL_SECONDS
+last = None
+after = None
+while time.time() < deadline:
+    code, after, _, _ = drain_status()
+    last = (after or {}).get('lastRun') if isinstance(after, dict) else None
+    if isinstance(last, dict) and last.get('runId') == run_id and last.get('state') not in ('accepted', 'running'):
+        break
+    time.sleep(3)
+else:
+    done('run ' + run_id + ' still in flight; the next cadence observes it')
+
+# 4. Tier-1 supervision of the terminal run.
+run_state = last.get('state')
+reason = str(last.get('reason') or '').strip()
+if run_state in ('succeeded', 'no-op'):
+    if isinstance(after, dict) and after.get('consumerLive') is False and work_counts(after) > work_counts(before):
+        fail('invariant broken: claimed/completed work advanced while the consumer is in simulation (run ' + run_id + ')')
+    done(run_state + ' ' + run_id)
+fail('drain run ' + str(run_state) + ': ' + (reason or 'no reason given') + ' (run ' + run_id + ')')
+FEEDBACK_DRAIN_TICK
+```
+
+The script prints one `FEEDBACK_DRAIN_RESULT` line. It records a failed run itself by writing the reason to `$INSTAR_JOB_FAILURE_FILE` (the scheduler reads that file when the run ends); saying "failed" in your output does NOT record a failure. Outcomes it enforces:
+- Posture `dark` → silent exit. `unavailable` → failed run. Unreadable status → failed run on a development agent, silent exit on the fleet.
+- A refused tick (any HTTP code other than 202, e.g. `current registered readiness agent required` after the authority was demoted) → failed run.
+- A tick proxied to the owner machine → success here; its outcome lives in the owner's run history and status.
+- Terminal `succeeded` / `no-op` → success. Terminal `degraded`, `failed` or `abandoned` → failed run carrying the drain's reason.
+- In simulation, claimed/completed work counts must not advance; if they do → failed run.
+
+Never retry in the same run; the durable queue and the next cadence own retry. Then exit silently. Do NOT relay anything to Telegram and do NOT summarize. A failed run reaches the operator through the scheduler's consecutive-failure alert.

package/upgrades/1.3.1313.md

@@ -0,0 +1,65 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The operated feedback drain failed every run with `source record checksum conflicts with
+its projection`. The canonical `feedback.jsonl` is an append-only, last-write-wins log:
+when processing flips a report from unprocessed to processing it re-appends the report's
+full row with the same `sourceRecordId`. The drain read its own re-append as a conflict,
+and one conflict failed the whole run, so 742 clusters never left `collecting`.
+
+- The processing writer now appends each update as a new source record (fresh
+  `sourceRecordId`), as the spec requires. The 1,000 lines the old writer appended under the
+  original ids are accepted as superseded versions only because they change `status` and
+  `clusterId` alone. Any other same-id change, or an id bound to another report, is
+  corruption: that line alone is held in `source_conflicts` (audited, integrity hold set), the
+  cursor moves on, and every run ends `degraded` with `source-record-quarantined` until an
+  operator repairs it.
+- Self-heal: the conflict the earlier build recorded for a legacy update line is cleared
+  (audited) when the cursor re-reads that line.
+- Compaction: the cursor now starts after the checksum-verified copied prefix of a new
+  generation instead of re-reading the whole corpus, and an already-compact generation
+  is no longer copied into a byte-identical new file every interval.
+- A projected batch replayed after a crash mid-pass no longer clusters (and counts) a
+  report the store already processed.
+- The `feedback-factory-process` job body is now one fixed script. The runner model used to
+  improvise a zsh loop (`status=$(...)` fails: `status` is read-only in zsh), and a degraded
+  run was recorded as a success. The script fails the job run (via
+  `$INSTAR_JOB_FAILURE_FILE`) on a refused tick and on a `degraded`, `failed` or
+  `abandoned` run, with the drain's reason. A tick proxied to the owner machine finishes at
+  once (its outcome lives in the owner's run history and status).
+
+Existing stores heal on the next run. The job body reaches existing agents through the
+normal built-in job refresh on update. No operator action.
+
+## What to Tell Your User
+
+The feedback sorter was stuck: it tripped over its own bookkeeping on every run, so no
+feedback reached the task list. It now runs end to end on the real backlog, and if a run
+goes wrong the scheduled job says so instead of reporting success. Nothing for you to do.
+
+## Summary of New Capabilities
+
+- The feedback drain completes full passes on the live store (reports processed, clusters judged, ready work handed to Initiative tasks).
+- One bad source record is quarantined instead of stopping every run.
+- The drain job fails honestly when a run is degraded or refused.
+
+## Evidence
+
+Reproduced on a read-only copy (`sqlite3 .backup`) of the Mac Studio's live store, taken
+2026-10-01 16:02 PDT, driving the real drain code:
+- Before (origin/main): 3 of 3 ticks threw `source record checksum conflicts with its
+  projection` at the first processing re-append (`feedback-source:7720c778-…`); 742 clusters
+  stayed `collecting`, 0 work rows.
+- After: 18 ticks, 0 failed or degraded; 1,004/1,004 reports processed, all 746 clusters
+  evaluated, 45 ready → queued → claimed → completed Initiative tasks (read back), the stale
+  conflict row cleared with an audit entry, 0 lines quarantined, 2 compacted generations
+  (6 before), projection lag 0.
+- Real arbiter (gpt-6-astra via codex-cli): 5 generic clusters → `collecting`, 5 specific
+  multi-report bugs → `ready` (0.86–0.94); both replies replayed in the e2e.
+- Job: the live 11:00 PDT run died on `read-only variable: status` and was recorded as a
+  success for a degraded drain run; the new script records that run as failed
+  (`drain run degraded: readiness-authority-failed`).

package/upgrades/feedback-drain-end-to-end.eli16.md

@@ -0,0 +1,42 @@
+# ELI16 — the feedback sorter tripped over its own notes
+
+## The problem
+
+Fleet agents send bug reports. The feedback sorter ("drain") reads them from a log file,
+groups similar ones, asks a model which groups are ready to become a task, and creates
+those tasks.
+
+The log file is append-only: nothing is ever edited in place. When the sorter files a
+report into a group, it writes a new copy of that report's line at the end of the file,
+marked "processing". The newest copy wins.
+
+The sorter also keeps its own index of every line it has read, with a fingerprint of each.
+When it reached its own "processing" copy, it saw the same report id with a different
+fingerprint and decided the file had been tampered with. It stopped the whole run. Every
+run after that stopped at the same line, so no group ever became a task.
+
+The scheduled job that drives the sorter reported "success" anyway. It runs on a small
+model that wrote its own shell loop, and that loop crashed on a variable name the shell
+reserves (`status`).
+
+## What this change does
+
+- The sorter's own updates now get a new record id each time, as the design always said
+  they should. So a new copy is never mistaken for a changed old one.
+- The 1,000 old copies already in the file changed only the "processing" mark and the group
+  name. Those are accepted as updates. Any other change under an old id is still treated as
+  tampering.
+- Tampering no longer stops everything. Only the bad line is set aside and logged, and the
+  rest of the run continues. Every run is then marked "degraded", so the scheduled job keeps
+  failing and alerting until a person repairs that line.
+- The false alarm already stored on the live machine clears itself on the next run, with
+  an audit entry.
+- Two waste fixes found on the way: after the log is compacted, the sorter no longer
+  re-reads everything from the start, and an unchanged log is no longer copied again.
+- The scheduled job now runs one fixed script. A refused, degraded, or failed run fails
+  the job, with the reason.
+
+## What you need to do
+
+Nothing. The next run heals the stored state, and the job update arrives with the
+normal instar update.

package/upgrades/side-effects/feedback-drain-end-to-end.md

@@ -0,0 +1,245 @@
+# Side-Effects Review — feedback drain: a full pass completes on real data
+
+**Version / slug:** `feedback-drain-end-to-end`
+**Date:** `2026-10-01`
+**Author:** `Echo`
+**Second-pass reviewer:** `independent reviewer subagent (see below)`
+
+## Summary of the change
+
+Seventh first-run blocker on the operated drain (Mac Studio). After authority generation 2
+went active (epoch 22681), both runs (15:58 and 16:00 PDT) failed with `source record
+checksum conflicts with its projection`; `source_conflicts` held one row
+(`feedback-source:7720c778-…`, report `fb-1145e5c3-4a2`). Per the standing "three failed
+rounds → structural review" rule, this change drove the REAL drain code against a copy of
+the live store until a full pass completed, fixing every blocker met on the way:
+
+1. **Root cause (checksum conflict) — the writer.** The spec (§5, source discovery) says a
+   later last-write-wins update is a NEW source record with its own projection sequence, and a
+   duplicate `sourceRecordId` with different bytes is corruption that holds. The processing
+   writer broke the first half: `JsonlFeedbackStore.markProcessed` re-appended each processed
+   report under its ORIGINAL `sourceRecordId`. The first live runs appended 1,000 such lines;
+   the cursor then reached the first one (byte 2,992,509) and the drain, correctly by the
+   spec's second half, called it corruption, and threw for the whole run. Fix: the processing
+   update is appended without the old id, so `FeedbackSourceGenerations.append` mints a fresh
+   one. Updates are now projected as their own records; clustering ignores them (only
+   `unprocessed` rows are clustered).
+2. **Legacy lines and quarantine.** The 1,000 lines already on disk keep their reused ids. A
+   same-id line is accepted as a superseded version only when it differs from the projected
+   record in the LWW fields alone (`status`, `clusterId`) — exactly what the old writer
+   produced (all 1,000 live lines pass; 0 quarantined on the copy). Any other difference
+   (`source-record-content-conflict`) or the id bound to another report
+   (`source-record-identity-conflict`) is corruption: that line alone is held in
+   `source_conflicts` with an audit row and `source_integrity_hold`, the cursor moves on, and
+   EVERY run ends `degraded` / `source-record-quarantined` until an operator repairs the
+   held line (spec §207: a persistent mismatch raises operator attention). One record no
+   longer fails the whole run. **Self-heal:** when the cursor re-reads a legacy LWW line that
+   the earlier build recorded as `source-record-checksum-conflict`, that row is deleted with
+   an audit entry (`cleared-misclassified-conflict`); the hold is lifted only if it is a
+   `source-record-*` hold and no conflict of any kind remains. The live store heals on its
+   next run.
+3. **Compaction re-read (found on the copy).** `acceptSourceHandoff` reset the cursor to
+   byte 0 of the new generation, so every compaction re-read the whole corpus at 500 rows
+   per run. It now takes the handoff's `startOffset` (the end of the copied prefix, already
+   checksum-verified by `readManifest`). Optional parameter; callers without it keep 0.
+4. **Byte-identical generations (found on the copy).** `compact()` on a generation with
+   nothing superseded wrote a new 3 MB copy each interval (5 identical files in the replay).
+   It now returns null when a manifest already exists and the output equals the input; the
+   legacy file still always moves to a generation. The service restarts the compaction
+   interval either way.
+5. **Replay double-count.** A projected batch replayed after a crash mid-pass (process
+   killed between clustering and `acknowledgeProcessedProjection`) re-clustered reports the
+   store already marked processing, inflating `reportCount`; with updates now projected, the
+   same batch could also hold a report and its update ("duplicated id" throw, every run).
+   `withProjectedFeedbackScope` skips a row unless both the row and the store's folded state
+   are `unprocessed`, before the duplicate check.
+6. **Job honesty.** The `feedback-factory-process` body is now one fixed python script the
+   haiku runner executes verbatim. The live run (transcript 8e49dd8d, 11:00 PDT) improvised
+   `status=$(curl …)` in zsh (read-only variable), and the old body also accepted a
+   `degraded` run as success. The script writes `$INSTAR_JOB_FAILURE_FILE` on: posture
+   `unavailable`; unreadable status on a development agent; any tick response other than 202
+   (e.g. 403 after an authority demotion); terminal `degraded` / `failed` / `abandoned`; and
+   simulation work counts that advance. `dark` exits silently. A tick proxied to the owner
+   machine finishes at once (its outcome lives in the owner's run history). Still in flight
+   at 60 s is not a failure. Worst case ~93 s (10 s per HTTP call), inside the
+   `timeout: 300000` the body asks the runner to set.
+
+## Decision-point inventory
+
+- Processing update writer — modify — original sourceRecordId → fresh sourceRecordId (spec).
+- Source projection: same sourceRecordId + same report + only status/clusterId differ — modify — throw (whole run) → superseded version (legacy lines).
+- Source projection: same sourceRecordId + other content or another report — modify — throw (whole run) → quarantine that line; every run degraded until repaired.
+- Compaction handoff cursor start — modify — 0 → manifest `startOffset`.
+- Compaction of an already-compact generation — modify — new identical generation → no-op.
+- Projected clustering scope — modify — includes already-processed rows → skips them (before the duplicate-id check).
+- Job outcome classification — modify — model-improvised → fixed script; `degraded` now fails the job.
+- Reconciliation (`reconcileSourceProjection`) — unchanged: projected byte ranges are still re-hashed and mismatches still recorded.
+
+---
+
+## 1. Over-block
+
+The old code failed whole runs for one line; the live trigger was not even corruption but
+the drain's own writer. Now only a corrupt line is held, and only that line. The job now
+fails on any `degraded` run. Every degraded reason is something an operator should see
+(authority unavailable or failed, spend brake, readiness source missing, cancellation,
+quarantine). The job is priority `low`, so the scheduler alerts after 3 consecutive
+failures: a spend brake or an unrepaired quarantine fails every 30-minute run and alerts
+within ~90 minutes; a single transient degraded run does not alert.
+
+## 2. Under-block
+
+- A legacy same-id line that changes only `status`/`clusterId` is accepted without an alarm.
+  That is the documented LWW update shape; it is never re-projected, so it cannot re-enter
+  clustering. A same-id line with any other change is still held.
+- "Hold the entity family" (spec §6, corrupt source): the held line never enters the
+  projection; later updates of that report under their own ids are projected but are never
+  clustered (not `unprocessed`). The report's first, valid line stays the projected record.
+- Repair of a held line is operator work (no route added); until then every run is degraded
+  and `pruneOperationalHistory` is skipped (existing degraded behaviour), so run/audit
+  history grows while the job alerts.
+- The job script still depends on the runner executing it verbatim. The body says so and
+  the script is one heredoc; a `script`-type job would need a manifest migration for every
+  agent, which this does not justify while the prompt route works.
+- A proxied tick's outcome is not supervised by any job: it is visible only in the owner's
+  run history and `/feedback-factory/drain/status` on the owner.
+
+## 3. Level-of-abstraction fit
+
+The projection rule sits in the store that owns the cursor and the conflict table. The
+compaction fix sits in the generation writer, and the cursor fix in the store's handoff
+acceptance. The job fix is in the shipped template that `installBuiltinJobs` overwrites
+on every update.
+
+## 4. Signal vs authority compliance
+
+Deterministic integrity checks over ids and checksums; no judgment. Quarantine is a
+signal (conflict row, hold, audit, degraded run) and no longer blocks unrelated reports.
+
+## 4b. Judgment-point check
+
+No new heuristic at a competing-signals point. The readiness model's prompt and parsing are
+untouched; the e2e replays two real gpt-6-astra replies through the unchanged parser.
+
+## 5. Interactions
+
+- `reconcileSourceProjection` re-hashes only projected byte ranges, which still hold their
+  original bytes (append-only). Unaffected.
+- `acceptSourceHandoff` keeps the "target generation already projected" refusal.
+- `pruneOperationalHistory` is skipped on degraded runs, as before; quarantine is the only
+  new degraded case, and it persists until repaired.
+- `source_integrity_hold` is also set by the generation-missing path and by reconciliation;
+  this path lifts only a `source-record-*` hold, and only when the conflict table is empty.
+  Nothing reads the hold today.
+- Projection rows grow by one per processing update (the spec's model); compaction's copied
+  prefix is skipped by `startOffset`.
+
+## 6. External surfaces
+
+`/feedback-factory/drain/status`: `sourceChecksumConflicts` drops to 0 on the live store
+after one run. The job's run history now records failures it previously hid.
+
+## 6b. Operator-surface quality
+
+The failure reasons the job records are one line with the drain's own reason and run id.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+Machine-local by design: the source log and drain DB live only on the operated host. The job
+on a non-owner proxies the tick as before and now finishes at once. The proxied run's outcome
+is visible only in the owner's run history and status; no job supervises it.
+
+## 8. Rollback cost
+
+A code revert. A healed store keeps working on the old code until the next processing
+re-append is read, then fails as before. No data is rewritten; the only deletions are the
+misclassified conflict rows, each audited.
+
+## Conclusion
+
+Root cause: the processing writer re-appended updates under the original source id, which
+the spec calls corruption, and one such line failed every run. The writer now mints a new id,
+the 1,000 legacy lines are accepted only because they change status/clusterId alone, real
+corruption holds just its line while runs stay loudly degraded, and the live store heals on
+its next run. Driving
+the real code over a copy of the live store until a full pass completed found and fixed two
+compaction costs and a replay double-count on the way, and the job now reports degraded and
+failed runs honestly.
+
+## Operator repair of a held source line
+
+Only needed if a run reports `source-record-quarantined` (none on the live store today).
+1. Read the held rows: `sqlite3 <stateDir>/state/feedback-factory/store/feedback-drain.db
+   "SELECT * FROM source_conflicts"` and the matching `drain_audit` rows
+   (`kind='source-record'`). Compare the held line in `feedback.jsonl` (search its
+   `sourceRecordId`) with the projected record (`SELECT record_json FROM source_projection
+   WHERE source_record_id=?`).
+2. Decide: the projected record stays authoritative (the default — nothing else to do), or
+   the report needs a fresh correct line, appended through the normal intake.
+3. Clear the hold with the server stopped:
+   `DELETE FROM source_conflicts WHERE source_record_id='<id>';`
+   `INSERT INTO drain_audit(kind,entity_id,from_state,to_state,reason,created_at) VALUES
+   ('source-record','<id>','<reason>','operator-cleared','operator-repair:<decision-ref>',<epoch-ms>);`
+   and, if the table is now empty, `DELETE FROM drain_meta WHERE key='source_integrity_hold';`.
+The next run is no longer degraded by it.
+
+## Spec alignment
+
+`docs/specs/feedback-factory-operating-drain.md` §5 (source discovery, reconciliation) and §6
+(corrupt source):
+- "Later LWW updates are new source records and receive a new projection sequence" — the
+  writer now does this; the defect was the writer reusing the id.
+- "Duplicate `sourceRecordId` with a different checksum is corruption and holds" — kept for
+  every change except the legacy status/clusterId-only update the old writer produced, which
+  is the LWW update the spec describes, written under the wrong id. Those lines are
+  superseded, not deleted; the source file is never rewritten.
+- "Conflicting rows are … never auto-deleted" — the only deletion is of rows the earlier
+  build recorded for those legacy LWW lines, each audited (`cleared-misclassified-conflict`).
+  Real conflicts (content or identity) are never deleted.
+- "A persistent mismatch … raises one operator attention" — every run stays degraded while a
+  held line exists (projection content/identity conflicts and reconciliation checksum
+  conflicts), the job fails, and the scheduler's consecutive-failure alert fires. Before this
+  change a reconciliation conflict never degraded a run.
+- "Source-record uniqueness makes copied live rows idempotent" — unchanged; the compaction
+  cursor additionally skips the verified copied prefix.
+
+## Second-pass review (if required)
+
+**Reviewer:** independent reviewer subagent (general-purpose, read-only)
+**Independent read of the artifact (round 1):** concerns raised, all addressed
+
+Round 1 raised: (a) a real quarantine alerted only once, against spec §207 → every run now
+stays degraded until repair; (b) a proxied tick polled a run it cannot see for 90 s and
+recorded success → finishes at once; (c) worst-case script time (~150 s) exceeded the Bash
+tool's 120 s default → 10 s HTTP timeouts, 60 s poll, body asks for `timeout: 300000`;
+(d) a non-numeric work count crashed the script → safe parse; (e) the hold-clear removed holds
+other paths own → only `source-record-*` holds; (f) the change contradicted spec §5
+("later LWW updates are new source records") → redesigned: the writer mints a fresh id and
+only legacy status/clusterId-only lines are tolerated; (g) wording in §1, §5, §7 → corrected.
+**Round 2:** concur. Notes applied: legacy-update comparison also ignores the re-keyed id
+fields (`feedbackId`/`feedback_id`/`id`); `reconciliation-checksum-conflict` rows now count as
+held (runs degrade until repaired); the operator repair procedure is written above; proxied-run
+wording corrected.
+
+## Evidence pointers
+
+- Live store copy (`sqlite3 .backup`, read-only) at 2026-10-01 16:02 PDT: origin/main fails
+  3/3 ticks with the live error. With this change: 1,004/1,004 reports processed, all 746
+  clusters evaluated, 45 ready → queued → claimed → completed → read-back Initiative tasks
+  (stubbed gpt-6-astra-shaped arbiter through the real parser), stale conflict cleared
+  (audit row), 2 generations after compaction (was 6), projection lag 0.
+- Real arbiter (production `FeedbackReadinessArbiter` + codex-cli provider, gpt-6-astra
+  resolved and accepted): 5 generic clusters → all `collecting` (0.99, 17 s); 5 specific
+  multi-report bugs → all `ready` (0.86–0.94, 18–20 s). Both replies are fixtures.
+- Tests: `tests/unit/feedback-drain-source-versions.test.ts`,
+  `tests/unit/feedback-drain-store.test.ts`, `tests/integration/feedback-factory-drain-service.test.ts`,
+  `tests/integration/feedback-factory-process-job-body.test.ts` (real script against a drain
+  server), `tests/e2e/feedback-drain-live-shapes.test.ts` (AgentServer + HTTP, real shapes).
+  All 14 new tests fail on the pre-fix source.
+
+## Class-Closure Declaration (display-only mirror)
+
+Runtime code defect. Class: a writer that breaks the source-record contract, met by an
+integrity check that fails closed for the whole batch. Siblings in the same path:
+compaction handoff (re-read), compaction no-op (copy), projected replay (double count) —
+all closed here. Reconciliation already scopes to fixed byte ranges and is not a sibling.