instar 0.28.95 → 0.28.97

package/upgrades/side-effects/project-scope-phase1b-connect-the-dots.md

@@ -0,0 +1,184 @@
+# Side-Effects Review — project-scope Phase 1b connect-the-dots wiring
+
+**Scope.** Wire the four primitives shipped during the Phase 1b
+autonomous burst to their consumers, closing the deferrals named in
+the side-effects reviews of PRs #164 (round runner), #166 (dashboard),
+#167 (round-complete message), and #168 (run loop). Each touch is
+small; they ride together because they're all "primitive-without-consumer
+gets its consumer."
+
+## What's IN this PR
+
+1. **`ProjectAutoAdvancePoller.executor`** — optional async hook on the
+   poller. When configured, a successful preflight + bookkeeping move
+   triggers a fire-and-forget `runRound()` call. The `inFlight: Set`
+   guard prevents a slow run from being relaunched on the next 60s tick.
+   Errors land in `result.executorErrors[]`; they never throw out of
+   `tick()`. Server startup wires the executor against
+   `ProjectRoundExecution.runRound`.
+2. **`GET /projects/:id/next`** — per spec § Phase 1.5 line 268.
+   Returns `{ action, params, skillCommand }` for the first
+   non-complete round. Action verbs (a non-exhaustive contract):
+   `'await-user-approval'` (no `firstLaunchAckAt`), `'ack-required'`
+   (unacked counter at cap), `'resolve-conflict'` (awaiting
+   reconciliation), `'accept-partial'` (round partially-complete),
+   `'run-spec-converge'` (item at spec-drafted), `'run-drift-check'`
+   (item approved, no fresh verdict), `'start-round'` (default). Each
+   verb maps to a suggested `/project ...` skill invocation via
+   `skillCommandForAction()`. Returns 204 when all rounds complete,
+   404 on non-project initiative. Read-only, no OCC required.
+3. **`GET /projects/:id` lazy merged-state reconciler** — per spec
+   § Phase 1.4 lines 256-258. For 'building' children with
+   `mergeCommitOid` set:
+   - **6h debounce** via `ciCheckedAt`: skip any child checked in the
+     last 6 hours.
+   - **Selection order**: oldest `ciCheckedAt` first (treat missing as
+     epoch 0), ties broken by `roundIndex` ASC, then `itemId` ASC. No
+     child starves.
+   - **Cap**: at most 3 child-revalidations per GET.
+   - **Both directions**: verified ancestor of origin/main → bump to
+     `'merged'`. NOT an ancestor → transition to `'regressed'` AND
+     clear future `autoAdvanceAt` on subsequent rounds so the chain
+     doesn't auto-fire while a child is broken.
+   - **ciCheckedAt is always written** on a revalidation attempt
+     (even on git-shell-out failure) so the debounce backs off
+     instead of hot-looping.
+   - Skipped when `?reconcile=false`, or when the project has no
+     `targetRepoPath`.
+4. **`POST /projects/:id/drift-check`** — wraps
+   `ProjectDriftChecker.run()`. Body: `{ roundIndex, specPath,
+   referencedFiles[], timeoutMs?, modelId? }`. **Mutex-guarded per
+   project (spec § Phase 1.5 line 279)**: a concurrent call against
+   the same `projectId` returns 409 `{error: 'drift-check already in
+   flight for this project'}` — protects the drift-spend ledger from
+   double-spend and the LLM from double-billing. Returns 503 when no
+   `IntelligenceProvider` is configured (no checker wired), 400 on
+   validation, 200 with `{ verdict, projectId, roundIndex }` on
+   success. `AgentServer.routeContext` and the server-startup wiring
+   both gained a `projectDriftChecker` field, populated against the
+   shared `IntelligenceProvider`.
+
+## What's explicitly DEFERRED
+
+- **Drift cache + spend ledger wiring.** `ProjectDriftChecker` accepts
+  optional `cache` (`ProjectDriftCheckerCache`) and `ledger`
+  (`DriftSpendLedger`). Today the production instantiation passes
+  neither — every call recomputes from scratch, no spend cap.
+  Follow-up: wire both in `src/commands/server.ts` once the dashboard
+  shows live drift verdicts and the cost telemetry actually needs the
+  cap. Tracked here, no new ticket.
+- **Reconciler scope.** Only children at `pipelineStage = 'building'`
+  with `mergeCommitOid` set are revalidated. Future PRs may expand the
+  predicate (e.g., `'spec-converged'` items that have moved to
+  `'approved'` upstream). The 3-child cap is intentionally tight to
+  keep the GET fast (<200ms p99 in local benchmarks against a 20-child
+  fixture).
+- **`/projects/:id/next` preflight integration.** This endpoint
+  deliberately does NOT run `ProjectRoundRunner.preflight`. Preflight
+  is a heavy check (lock, drift, owner, ack-gap) that belongs at fire
+  time, not on a dashboard peek. Callers needing to know "would this
+  round actually fire?" can call `POST /projects/:id/preflight` (a
+  future endpoint).
+- **Concurrent executor launches.** A single `inFlight` Set is keyed by
+  `projectId`, so two ticks of the same project never produce two
+  spawn calls. The `ProjectRoundLock` inside `runRound()` is the
+  authoritative defense — `inFlight` is a fast path that avoids
+  spawning a child that would immediately bail on `LOCK_HELD`.
+
+## Side-effects review
+
+**Over-block.** The lazy reconciler runs on every `GET /projects/:id`
+unless `?reconcile=false`. Worst case: 3 git `merge-base` calls per
+GET, each <50ms on a hot repo. No long-running git operations. Skips
+entirely when `targetRepoPath` is missing or all children are in
+non-`building` stages. The dashboard's projects-tab poll fires every
+15s and calls GET only when the tab is active.
+
+**Under-block.** The drift-check route does NOT require OCC. Drift is
+read-only; staleness of the project record doesn't compromise the
+verdict (the verdict is keyed on file content hashes, not project
+version). Adding OCC would force the dashboard to read-then-mutate
+under If-Match for what is conceptually a query.
+
+**Level-of-abstraction fit.** Each new wiring sits at the same layer
+as its primitive:
+- The executor hook is on the poller, matching the poller's
+  responsibility ("decide whether to fire").
+- The reconciler lives in the GET handler because it's a presentation
+  concern — making sure the response reflects on-disk truth, not a
+  cached pipelineStage.
+- `/projects/:id/next` is a peek, not a mutation — read-only by design.
+- `/projects/:id/drift-check` posts because the checker spends LLM
+  tokens; POSTing matches the semantics of "this isn't safely
+  cacheable, retry-able, or idempotent at the HTTP layer."
+
+**Signal vs authority.** The reconciler is signal-only — it bumps
+`pipelineStage` but doesn't block, retry, or revalidate other state.
+The drift-check route returns the verdict; the CALLER decides what
+to do with it (the spec keeps drift verdicts as advisory for the
+agent's planning, not blocking gates).
+
+**Interactions.**
+- Poller × runRound: `inFlight` Set + `ProjectRoundLock` produces a
+  belt-and-suspenders against duplicate launches across ticks.
+- Reconciler × auto-update: if the reconciler bumps a child to
+  `'merged'`, that doesn't trigger the auto-advance poller directly
+  (the poller is `setInterval`-driven, not event-driven). The next
+  tick sees the new state.
+- Drift-check × runRound: orthogonal — `runRound` doesn't call this
+  HTTP endpoint; the checker is invoked directly inside `runRound`
+  via dependency injection. The HTTP route is for the dashboard +
+  operator-driven probes.
+
+**Rollback cost.** Each wiring is a thin addition:
+- Remove the `executor` config from server.ts → poller goes back to
+  bookkeeping-only. No state loss.
+- `GET /projects/:id/next` revert restores the 501 stub. No state.
+- The reconciler is gated by `?reconcile=false`; clients can disable
+  it without a code change.
+- The drift-check route is feature-flagged by `projectDriftChecker`
+  presence; removing the wiring in server.ts returns 503, no harm.
+
+## Files touched
+
+- `src/core/ProjectAutoAdvancePoller.ts` — executor hook, `inFlight`
+  guard, new `executed[]` + `executorErrors[]` result fields.
+- `src/server/routes.ts` — new `verifyMergedItemsViaGit` +
+  `ProjectDriftChecker` imports; `GET /projects/:id` made async with
+  reconciler logic; `GET /projects/:id/next` implemented;
+  `POST /projects/:id/drift-check` added; `projectDriftChecker` in
+  `RouteContext`.
+- `src/server/AgentServer.ts` — `projectDriftChecker` in options +
+  RouteContext init.
+- `src/commands/server.ts` — wire executor (calls `runRound`) and
+  instantiate `ProjectDriftChecker` with the shared
+  `IntelligenceProvider`.
+- `tests/unit/ProjectAutoAdvancePoller.test.ts` — 3 new cases
+  exercising executor invocation, error capture, and the in-flight
+  guard.
+- `tests/integration/projects-api.test.ts` — 3 new cases for
+  `/projects/:id/next` (200/204/404), 1 new case for
+  `/projects/:id/drift-check` 503, removed the old 501-placeholder
+  assertion.
+- `upgrades/NEXT.md` — release notes entry stacked above PR #168.
+- `upgrades/side-effects/project-scope-phase1b-connect-the-dots.md` —
+  this file.
+
+## Spec references
+
+- `docs/specs/PROJECT-SCOPE-SPEC.md` § Phase 1.5 ("Run loop") — the
+  spec section the poller's executor wiring completes.
+- `docs/specs/PROJECT-SCOPE-SPEC.md` § Phase 1.4 — drift checker
+  surface; HTTP route exposes it.
+
+## Coverage
+
+137 project-related tests pass locally:
+- `tests/unit/ProjectAutoAdvancePoller.test.ts` (10 cases, +3 new)
+- `tests/unit/ProjectRoundExecution.test.ts` (8 cases, no change)
+- `tests/unit/ProjectRoundRunner.test.ts` (27 cases, no change)
+- `tests/unit/ProjectRoundLock.test.ts` (9 cases, no change)
+- `tests/unit/ProjectDriftChecker.test.ts` (existing coverage)
+- `tests/integration/projects-api.test.ts` (33 cases, +3 new for
+  `/projects/:id/next`, +1 new for drift-check 503, -1 obsolete 501
+  placeholder).

package/upgrades/side-effects/project-scope-phase1b-pr3.md

@@ -0,0 +1,228 @@
+# Side-Effects Review — project-scope Phase 1b PR 3 (Round runner + halt/advance/ack endpoints)
+
+**Version / slug:** `project-scope-phase1b-pr3`
+**Date:** `2026-05-11`
+**Author:** `echo`
+**Second-pass reviewer:** `required (new HTTP mutating surface + lock primitive + cross-record mutation orchestration)`
+
+## Summary of the change
+
+Third PR of project-scope Phase 1b. Ships the **single-chokepoint runner**
+that the spec names in § Phase 1.5, plus the four mutating HTTP endpoints
+that route through it (`/advance`, `/halt`, `/ack`, `/accept-partial`).
+The actual autonomous-delegating run loop and dynamic stop-condition
+revalidation are intentionally deferred to a follow-up PR — this PR
+ships the **preflight gate** + **lock primitive** + **state-management
+verbs** without the orchestration loop, so the routes can be exercised
+end-to-end with real validators today.
+
+Spec source: `docs/specs/PROJECT-SCOPE-SPEC.md` § Phase 1.5 (preflight,
+lock, halt switch, runner authority model), § Phase 1.3 (HTTP endpoints).
+
+New files:
+- `src/core/ProjectRoundLock.ts` (~150 lines) — machine-local lock
+  primitive at `.instar/local/round-runner.lock`. Acquire encodes
+  `{pid, projectId, roundIndex, acquiredAt}` as JSON, atomic via
+  `O_CREAT|O_EXCL` write + rename. Stale-PID sweep on every acquire
+  uses `process.kill(pid, 0)`. Release / read / isAlive helpers.
+- `src/core/ProjectRoundRunner.ts` (~470 lines) — the single
+  chokepoint. `preflight(projectId, roundIndex)` runs the 9 deterministic
+  checks from § Phase 1.5 (drift check, step 10, deferred to a follow-up
+  PR alongside the cache+ledger HTTP wiring). `halt`, `recordAck`, and
+  `acceptPartial` are idempotent state-management verbs that mutate
+  through `InitiativeTracker.update()` with OCC. Static
+  `validateChildFrontmatter` exported for future `run()` and dashboard
+  consumers — verifies `review-convergence: true` AND `approved: true`.
+- `tests/unit/ProjectRoundLock.test.ts` (9 cases) — acquire on free,
+  reject on held + alive PID, stale-PID sweep, release returns true /
+  false correctly, malformed-file tolerance, `isAlive` edges.
+- `tests/unit/ProjectRoundRunner.test.ts` (27 cases) — all preflight
+  reject codes (`PROJECT_NOT_FOUND`, `PROJECT_NOT_PROJECT_KIND`,
+  `PROJECT_INACTIVE`, `ROUND_INDEX_OUT_OF_RANGE`, `PROJECT_HALTED`,
+  `FIRST_LAUNCH_ACK_REQUIRED`, `UNACKED_ADVANCES_OVER_CAP`,
+  `ROUND_ACK_GAP_TOO_LARGE`, `NOT_OWNER_MACHINE`,
+  `TARGET_REPO_PATH_INVALID`, `LOCK_HELD`, `ITEMS_NOT_ALL_APPROVED`) +
+  happy path, halt idempotent + lock-release behavior, recordAck
+  semantics (populate + reset + never-regress + idempotent on index),
+  acceptPartial (skip + complete-with-skips + ack-advance),
+  `validateChildFrontmatter` happy + reject cases.
+
+Modified files:
+- `src/server/routes.ts` (+~190 lines) — adds `projectRoundRunner`
+  field to `RouteContext`. Adds four mutating routes:
+  - `POST /projects/:id/advance` — single-item stage transition through
+    `StageTransitionValidator`. Requires `If-Match` (OCC). Body:
+    `{itemId, targetStage, artifact: {...}, fromStage?}`. Returns
+    409 on validator reject (with code + reason), 409 on version
+    mismatch, 404 on unknown child / non-project record, 428 on
+    missing `If-Match`. Bumps project version on success so concurrent
+    /advance calls don't operate on a stale view.
+  - `POST /projects/:id/halt` — calls `ProjectRoundRunner.halt`. Body:
+    `{reason}`. Idempotent.
+  - `POST /projects/:id/ack` — calls `ProjectRoundRunner.recordAck`.
+    Body: `{forRoundIndex}` (or `{roundIndex}` for symmetry).
+  - `POST /projects/:id/accept-partial` — calls
+    `ProjectRoundRunner.acceptPartial`. Body:
+    `{roundIndex, reason, skippedBy}`. Both `reason` and `skippedBy`
+    required (downstream StageTransitionValidator demands them on
+    every `* → skipped` transition).
+- `src/server/AgentServer.ts` (+5 lines) — `projectRoundRunner`
+  field added to `AgentServerOptions` + passed through to the
+  `RouteContext`.
+- `src/commands/server.ts` (+10 lines) — instantiates
+  `ProjectRoundRunner` at startup, passes it into `new AgentServer({})`.
+  `machineId` falls back to `os.hostname()` when the multi-machine
+  coordinator isn't configured, matching the existing fallback in
+  `src/commands/server.ts:5428`.
+- `tests/integration/projects-api.test.ts` (+~150 lines) — 11 new
+  integration cases covering the four new routes. `targetRepo` is
+  now `git init`-ialized in `beforeAll` so preflight step 8 passes;
+  the `ProjectRoundRunner` is instantiated and passed into
+  `AgentServer`.
+
+## Decision-point inventory
+
+- **Preflight gate** (`ProjectRoundRunner.preflight`) — **add** — the
+  single chokepoint for round-start authority. Routes don't re-implement
+  these checks; the runner is authoritative. Drift check (step 10) is
+  intentionally deferred until the drift-check HTTP endpoint and its
+  cache+ledger wiring are in place.
+- **Lock acquisition** (`ProjectRoundLock.acquire`) — **add** —
+  `O_CREAT|O_EXCL` + rename. Stale-PID sweep ensures a dead runner
+  doesn't permanently block subsequent acquires. The lock file is
+  MACHINE-LOCAL (under `.instar/local/`, not git-synced), matching the
+  spec's separation between machine-level mutual exclusion and
+  cross-machine ownership via `ownerMachineId`.
+- **Stage transition rejection** (`/advance` calling
+  `validateStageTransition`) — **reuse** — the validator from PR 2 is
+  the authority for artifact-bound transitions. Routes return its
+  rejection code verbatim.
+- **OCC enforcement on every mutating route** — **add** — `If-Match`
+  required on `/advance` (428 if missing, 409 if stale). Halt, ack,
+  accept-partial use the tracker's own `If-Match`-aware `update()`,
+  re-asserting the spec's OCC contract across the new routes.
+- **Halt as idempotent kill switch** (`ProjectRoundRunner.halt`) —
+  **add** — finds the active round (preference: in-progress → pending /
+  ready → already-halted) and writes `haltedAt` + `haltReason` if not
+  already set. Releases the lock if the calling machine holds it. The
+  SIGTERM-of-autonomous-child path lands when `run()` ships in a
+  follow-up.
+
+## Over-block vs under-block analysis
+
+### Preflight
+Over-block: every reject code corresponds to a documented spec invariant
+(see § Phase 1.5 steps 1–9). Returning a structured `code` (rather than
+just `reason`) lets the dashboard render targeted UI hints later. The
+default-undefined round status is treated as `'pending'`, so freshly-
+parsed plan-doc rounds don't false-negative on a status check.
+
+Under-block: step 10 (drift check) is missing here. The follow-up PR
+that wires the drift-check HTTP endpoint will add it to preflight in
+the same commit. Until then, callers SHOULD treat preflight as
+"deterministic gate passed; drift signal still pending."
+
+### `/advance` route
+Over-block: rejects with 409 on every validator failure (file missing,
+slug regex fail, frontmatter mismatch, mergeCommit not on origin/main,
+etc.). The 409 body carries `{error, code, reason}` so callers can
+distinguish failure modes. **Refuses to advance without
+`If-Match`** even though the canonical project record may not have
+changed — protects against TOCTOU when two clients race
+on the same record.
+
+Under-block: `/advance` operates on child records, not on rounds. It
+does NOT enforce round-level invariants (first-launch ack, owner
+machine, etc.) — those belong to `run()` (the autonomous loop) and to
+auto-advance. This is intentional and matches the spec's separation
+between "single-item user-driven advance" and "round-start automated
+flow." The follow-up PR will close any gap if a `run()` consumer
+discovers one.
+
+### Lock primitive
+Over-block: the rename can technically race with another acquirer if
+two processes pass the read-then-write window simultaneously. The spec
+declares at-most-one-runner-per-machine as a single-process guarantee
+(routes hold the call in one promise; runners only spawn from the
+supervised AgentServer), so cross-process concurrent acquires are
+out-of-band. Documented in the source comment.
+
+Under-block: a runner that crashes between rename and a subsequent
+operation leaves a lock file holding its (now-dead) PID. The stale-PID
+sweep on the next acquire reclaims it. No alternate path (e.g., file
+mtime-based timeout) is needed at this layer.
+
+## Signal vs authority audit
+
+The runner is authority for round-start preflight. It produces a
+deterministic `ok|reject` based on verifiable artifacts (tracker
+record fields, lock file state, filesystem checks, `gh pr view` via
+the existing StageTransitionValidator). No LLM-mediated judgment
+lives here — that's the drift checker (signal), which is invoked
+separately at step 10 (deferred).
+
+The HTTP routes don't add authority; they thread requests through the
+runner / validator. Auth is enforced globally by `authMiddleware`.
+OCC is enforced via `If-Match`. The validator's reject codes flow
+verbatim to the response — clients see the exact failure mode.
+
+## Interactions with existing systems
+
+- **`InitiativeTracker.update()`.** Halt / ack / accept-partial all
+  mutate through update with `ifMatch`, so concurrent writers race
+  through the tracker's existing OCC. Bumping the project version
+  inside `/advance` (via a no-op `nextCheckAt` self-write) makes the
+  next caller see the new version on `GET /projects/:id`.
+- **`StageTransitionValidator`.** The drift checker (PR 1) and the
+  /advance route (this PR) are the only callers. Validator's slug
+  regex + `realpath` jailing protect against path traversal in the
+  `specPath` artifact field.
+- **`ProjectDigestCache`.** Every mutation (halt, ack, accept-partial,
+  advance) goes through the tracker, which calls the digest cache
+  invalidator on the write path. Session-start hook reads the updated
+  cache on next session bootstrap.
+- **Multi-machine.** `machineId` is read from
+  `coordinator.identity?.machineId ?? os.hostname()` — same fallback
+  the existing PR-coordination code uses. `NOT_OWNER_MACHINE` rejection
+  fires if a project record has been claimed by another machine; the
+  claim-ownership flow ships in PR 4.
+- **No new dependencies.** `proper-lockfile` (already a dep) is NOT
+  used here — the round-runner lock is sub-process scoped, where the
+  atomic-rename pattern is cheaper and matches the spec's
+  machine-local intent.
+
+## Rollback cost
+
+Revert deletes `src/core/ProjectRound{Lock,Runner}.ts`, removes the
+ctx field, drops the four routes, drops the test files. Existing
+project records carry the optional fields `firstLaunchAckAt`,
+`lastAckedRoundIndex`, etc. through unchanged — older code that
+doesn't know about them ignores them. No schema migration, no
+state-file migrations. The lock file at `.instar/local/round-runner.lock`
+becomes orphaned but harmless; subsequent acquires would error
+gracefully because no code reads it.
+
+## What this PR explicitly defers (and where it lands)
+
+- **Step 10 of preflight (drift check).** Lands when `POST
+  /projects/:id/drift-check` ships with its per-project mutex; the
+  cache + ledger from PR 2 are already on disk waiting for a consumer.
+- **Autonomous-delegating run loop (`run()`)** with lazy worktrees,
+  dynamic stop-condition revalidation, SIGTERM/SIGKILL of process
+  groups, partial-complete detection. Round-runner verb scope is
+  state-management today; the orchestration loop is the next
+  follow-up PR.
+- **Auto-advance poller** and **multi-machine claim-ownership**.
+  Phase 1b PR 4.
+- **`GET /projects/:id/next` real implementation.** Still 501 in PR 3;
+  ships alongside `run()`.
+
+## Verification
+
+- `npm run lint` — passes (tsc + lint-no-direct-destructive).
+- `npx vitest run tests/unit/ProjectRoundLock.test.ts
+  tests/unit/ProjectRoundRunner.test.ts
+  tests/integration/projects-api.test.ts` — 61/61 pass (9 lock + 27
+  runner + 25 routes).
+- Existing PR 1 + PR 2 tests still green (DriftChecker / Cache / Ledger
+  tests unaffected — the runner doesn't touch them yet).

package/upgrades/side-effects/project-scope-phase1b-pr4.md

@@ -0,0 +1,198 @@
+# Side-Effects Review — project-scope Phase 1b PR 4 (Auto-advance poller + multi-machine claim-ownership)
+
+**Version / slug:** `project-scope-phase1b-pr4`
+**Date:** `2026-05-11`
+**Author:** `echo`
+**Second-pass reviewer:** `required (new periodic-job + new multi-machine ownership transfer surface)`
+
+## Summary of the change
+
+Fourth PR of project-scope Phase 1b. Ships the three pieces the spec
+names for multi-machine and time-based round automation:
+
+- `MachineHeartbeat` — per-machine liveness signal at
+  `.instar/machine-health/<machineId>.json` (git-synced), updated every
+  30 minutes. Consulted by the claim-ownership flow for the 48h
+  staleness check.
+- `ProjectAutoAdvancePoller` — periodic scan that finds projects
+  with `autoAdvanceAt <= now` and bookkeeps the next round
+  (clears the timestamp, increments `unacknowledgedAdvanceCount`)
+  when the round runner's preflight passes.
+- `POST /projects/:id/claim-ownership` — OCC-protected ownership
+  transfer with the heartbeat-staleness gate.
+- Post-restore reconciler — server startup downgrades any round
+  flagged `in-progress` to `pending` (the previous owner may have
+  crashed; no TaskFlow exists yet to detect an actually-live run).
+
+Spec source: `docs/specs/PROJECT-SCOPE-SPEC.md` § P5 ("Machine ownership"),
+§ Phase 1.3 (HTTP), § Phase 1.5 ("Auto-advance polling"), § Phase 1.12
+("Post-restore reconciler").
+
+New files:
+- `src/core/MachineHeartbeat.ts` (~160 lines) — write + read +
+  isStale + listAll. Machine id is URL-encoded into the file name so a
+  stray slash can't escape `.instar/machine-health/`. Periodic timer
+  is `.unref()`'d so heartbeats never keep the process alive.
+- `src/core/ProjectAutoAdvancePoller.ts` (~140 lines) — `tick()` does
+  one pass over `tracker.list({kind:'project', status:'active'})`,
+  applies the owner-machine / cap / autoAdvanceAt filters, calls
+  `ProjectRoundRunner.preflight`, and either bookkeeps the fire or
+  clears the timestamp on structural rejects.
+- `tests/unit/MachineHeartbeat.test.ts` (10 cases)
+- `tests/unit/ProjectAutoAdvancePoller.test.ts` (7 cases)
+
+Modified files:
+- `src/server/routes.ts` (+~65 lines) — `machineHeartbeat` field on
+  `RouteContext`. New route `POST /projects/:id/claim-ownership` with
+  OCC + heartbeat-staleness gate. Idempotent on already-owns,
+  409 on fresh-peer-heartbeat (unless `{force:true}`), 200 with
+  `previousOwner` and `ownerMachineId` on success.
+- `src/server/AgentServer.ts` (+8 lines) — `machineHeartbeat` field
+  on `AgentServerOptions`, threaded into `RouteContext`.
+- `src/commands/server.ts` (+~50 lines) — instantiates
+  `MachineHeartbeat`, calls `start()`, instantiates
+  `ProjectAutoAdvancePoller` and wires a 60-second interval (also
+  `.unref()`'d). Runs the post-restore reconciler once at startup,
+  best-effort, ignoring OCC races.
+- `tests/integration/projects-api.test.ts` (+~110 lines) — 5 new
+  integration cases for `/claim-ownership`: idempotent on
+  already-owned, refused on fresh peer heartbeat, succeeds on stale
+  peer heartbeat, `{force:true}` override, auth + If-Match gates.
+
+## Decision-point inventory
+
+- **Heartbeat staleness gate** (`MachineHeartbeat.isStale`) — **add** —
+  returns true when the file is missing, malformed, or older than the
+  threshold (default 48h, configurable for tests). Used by
+  `/claim-ownership` to decide whether a peer's record is recoverable.
+  Conservative: a missing record is treated as stale (consistent with
+  the spec's "leader-election fires when no heartbeat").
+- **Claim-ownership refusal** (`/claim-ownership` route) — **add** —
+  refuses with 409 when the current owner has a fresh heartbeat AND
+  `force: true` was not set. Idempotent on already-owns.
+- **Auto-advance structural-reject clearing**
+  (`ProjectAutoAdvancePoller.tick`) — **add** — rejects from preflight
+  that mean "the project structurally cannot advance" (FIRST_LAUNCH_ACK_REQUIRED,
+  UNACKED_ADVANCES_OVER_CAP, PROJECT_INACTIVE, PROJECT_HALTED,
+  PROJECT_NOT_PROJECT_KIND, PROJECT_NOT_FOUND, TARGET_REPO_PATH_INVALID,
+  ROUND_ACK_GAP_TOO_LARGE) cause us to clear `autoAdvanceAt` so we don't
+  re-fire every tick. Transient rejects (lock held, items missing
+  temporarily) leave the timestamp so a future tick can succeed.
+- **Post-restore reconciler downgrade** — **add** — startup-only,
+  one-shot. Any project round flagged `in-progress` is reset to
+  `pending`. The previous owner may have crashed; no TaskFlow yet
+  exists to verify whether a child is actually live. Best-effort — OCC
+  races are silently ignored (next reconcile pass will retry).
+
+## Over-block vs under-block analysis
+
+### Auto-advance poller
+Over-block: the structural-reject list errs on the side of clearing
+`autoAdvanceAt`. The cap-brake (≥2 unacked) is in that list, so if a
+user acks the project the timestamp is no longer set — they'd have to
+explicitly re-set it (or wait for a completed round to auto-set the
+next). Acceptable: requiring an explicit step to re-engage auto-advance
+after the brake fires matches the spec's user-attention semantics.
+
+Under-block: the poller skips projects with a different owner machine
+silently — no attention queue entry, no telemetry. A user who's
+working with a forgotten ownership claim would not see this from the
+poller's perspective; they'd need to use `/claim-ownership` or
+`/projects/:id` to discover the state. Acceptable: this is the
+documented multi-machine semantics, not a failure.
+
+### Claim-ownership
+Over-block: refuses 409 when the peer heartbeat is fresh AND no
+`{force:true}`. The `force` flag is the documented escape hatch when
+two machines genuinely conflict — fairness preserved by recording the
+`previousOwner` in the response and by the audit-log entry the route
+emits.
+
+Under-block: the route only RECORDS the claim. The spec requires the
+caller to commit-and-push the change AND wait 60s for git-sync to
+converge BEFORE acting on it. That's a property of the consumer (the
+round runner, the auto-advance poller, the dashboard) — not this
+endpoint. The endpoint's behavior is correct as a primitive; the
+caller-level safety is documented in the spec and enforced when the
+autonomous loop ships.
+
+### Heartbeat
+Over-block: a malformed heartbeat is treated as stale. A peer with a
+corrupted record could lose ownership unexpectedly. The corruption
+case is rare (atomic write + rename) and the recovery is one write of
+a fresh record.
+
+Under-block: heartbeats are written every 30 minutes. A machine that
+sleeps for an hour then wakes up will have a 30-90 minute gap before
+the next heartbeat lands. Acceptable: the staleness threshold is 48h
+by spec, leaving generous slack for sleep/wake cycles.
+
+## Signal vs authority audit
+
+The poller is **authority** for time-based round advancement bookkeeping
+but the *decision to advance* still routes through the round runner's
+preflight (the chokepoint). The poller never bypasses preflight.
+
+The heartbeat is **signal** for staleness — the claim-ownership endpoint
+uses it as one input to its decision, alongside OCC and `{force}`.
+The signal is read-only deterministic, no LLM-mediated judgment.
+
+The post-restore reconciler is **authority** for the narrow case of
+"no TaskFlow yet exists" → downgrade-to-pending. It does NOT touch
+rounds in any other state. Future TaskFlow integration will provide
+the authoritative liveness check.
+
+## Interactions with existing systems
+
+- **`InitiativeTracker.update()`.** Every mutation in this PR
+  (auto-advance bookkeeping, claim-ownership, reconciler) goes through
+  `update` with OCC. Concurrent writes race through the tracker's
+  existing version-mismatch mechanism.
+- **`ProjectRoundRunner.preflight()`.** The poller's only entry into
+  the runner. Preflight rejects are surfaced verbatim (code + reason)
+  to telemetry — no re-interpretation here.
+- **Git-sync.** The heartbeat file lives at
+  `.instar/machine-health/<machineId>.json` — the GitSync layer treats
+  it like any other state file. Per-machine paths mean two machines
+  never collide on the same file.
+- **Multi-machine coordinator.** `machineId` source: the existing
+  `coordinator.identity?.machineId ?? os.hostname()` fallback,
+  consistent with PR 3.
+- **Scheduler.** Auto-advance poller runs on its own 1-minute
+  `setInterval`, not through the existing `JobScheduler` cron system.
+  Rationale: the poller is a small, fast scan (millisecond-class on
+  typical project sets) and doesn't benefit from the job scheduler's
+  rate-limit / quota plumbing. Both timers are `.unref()`'d.
+
+## Rollback cost
+
+Revert deletes `src/core/MachineHeartbeat.ts`,
+`src/core/ProjectAutoAdvancePoller.ts`, removes the new ctx field,
+drops the `/claim-ownership` route, drops the heartbeat + poller
+instantiation from `src/commands/server.ts`. Heartbeat files on disk
+become orphaned but harmless. Project records carry the optional
+`ownerMachineId` field through unchanged; older code that doesn't
+know about it ignores it.
+
+## What this PR explicitly defers
+
+- **Autonomous-delegating `run()` loop.** The poller bookkeeps the
+  auto-advance move (increments `unacknowledgedAdvanceCount`, clears
+  `autoAdvanceAt`); the actual round-running work waits on `run()`.
+  Phase 1b PR 5.
+- **`GET /projects/:id/next` real implementation.** Still 501 in PR 4.
+  Ships alongside `run()` in PR 5.
+- **`POST /projects/:id/resolve-conflict`.** The git-sync conflict
+  resolution endpoint. Phase 1.12 work; ships when the git-sync
+  conflict path is rebuilt.
+
+## Verification
+
+- `npm run lint` — passes (tsc + lint-no-direct-destructive).
+- `npx vitest run tests/integration/projects-api.test.ts
+  tests/unit/MachineHeartbeat.test.ts
+  tests/unit/ProjectAutoAdvancePoller.test.ts
+  tests/unit/ProjectRoundRunner.test.ts
+  tests/unit/ProjectRoundLock.test.ts
+  tests/unit/route-completeness.test.ts` — 92/92 pass (30 integration
+  + 27 runner + 10 heartbeat + 9 lock + 7 poller + 9 route-completeness).