@logicseek/hello-cc 1.0.0 → 1.0.1

package/docs/layout-split-stack-audit.md

@@ -1,298 +0,0 @@
-# Layout Split Stack Audit
-
-Date: 2026-06-14
-
-Audit branch: `audit/layout-split-stack-20260614`
-
-Reviewed range: `origin/master..HEAD`
-
-- Base: `4969100` (`origin/master`, published as `@logicseek/hello-cc@0.1.5`)
-- Audited head: `4283234`
-- Commit count: 40
-
-This document audits the local architecture split stack before any push or npm
-publish. It is intentionally on a dedicated audit branch/worktree so the active
-`master` implementation stack is not rewritten during review.
-
-## Review Standard
-
-Each commit is classified against `docs/architecture.md`:
-
-- `keep`: the commit directly moves code toward a documented product boundary.
-- `keep-with-cleanup`: the direction is right, but package surface, shim policy,
-  or module placement still needs a cleanup decision before release.
-- `squash/rebuild`: the code is useful, but the commit exists mostly as an
-  intermediate flat extraction and should be folded into a product-boundary
-  commit if a clean release branch is rebuilt.
-- `decision-needed`: the final location or public surface is not settled.
-- `docs-only`: documentation or process record.
-
-The important distinction is code shape versus history shape. A commit can be
-useful for reaching the current code state while still being a poor standalone
-release-history commit.
-
-## Team Review Split
-
-Parent task: `#232`
-
-- `#234 lead-audit`: maintain this matrix and merge review feedback.
-- `#236 review-core-db`: core, coordination, db, peers, session semantics.
-- `#235 review-runtime-web`: runtime, web, terminal, integrations, release,
-  shared helper placement.
-- `#237 review-package-surface`: top-level `lib/*.mjs` compatibility shims,
-  npm package surface, and release-note risk.
-
-## Summary
-
-The current `HEAD` is not a random bad refactor. The final code shape has mostly
-been corrected toward the target architecture:
-
-- coordination logic under `lib/core/coordination`
-- peer/session semantics under `lib/core/peers` and `lib/core/sessions`
-- schema and stores under `lib/db`
-- runtime state/client/project helpers under `lib/runtime`
-- tmux under `lib/terminal`
-- Web runtime helpers under `lib/web`
-- provider/hooks/shims under `lib/integrations`
-- small utilities under `lib/shared`
-- text rendering/help under `lib/ui`
-- release helpers under `lib/release`
-
-The problem is the history shape. The first 25 local commits were mostly
-"extract a helper from `bin/hcc.mjs` into a top-level `lib/*.mjs` file". That
-was useful as a safety step, but it does not match the architecture design by
-itself. Later commits then moved many of those flat files into real product
-boundaries.
-
-Therefore:
-
-1. If the project keeps the current `master` history, do not keep making broad
-   split commits. Finish only package-surface cleanup, run full validation, bump
-   the version, and publish/sync with a clear changelog.
-2. If the project wants clean history for this major refactor, create a rebuild
-   branch from `origin/master` and replay the final shape as fewer architectural
-   commits. Do not rewrite the active `master` while peers use it.
-
-## Phase Classification
-
-### Phase 1: Early Flat Extractions
-
-These commits reduced `bin/hcc.mjs`, but mostly created top-level helper modules
-before the design document existed. They should be treated as
-`squash/rebuild` if a clean branch is made.
-
-| Commit | Area | Classification | Reason |
-| --- | --- | --- | --- |
-| `1bb1967` | providers + tmux | `squash/rebuild` | Mixed two product boundaries in one top-level extraction; should become integrations/provider and terminal/tmux commits. |
-| `e155d5a` | locks | `squash/rebuild` | Useful code, but final home is `lib/core/coordination/locks.mjs`, not top-level `lib/locks.mjs`. |
-| `9ab464d` | team planning | `squash/rebuild` | Same pattern; final home is `lib/core/coordination/teams.mjs`. |
-| `807fa96` | peer identity | `squash/rebuild` | Useful extraction, but identity is split between integration discovery and core peer semantics later. |
-| `494d38f` | peer format | `squash/rebuild` | Good low-level helper, but should land with peer-boundary cleanup rather than a standalone flat helper commit. |
-| `e2b745d` | project registry | `squash/rebuild` | Final boundary is runtime/project registry. |
-| `e4c4497` | project context | `squash/rebuild` | Final boundary is runtime/project context. |
-| `dec3e2e` | handoff | `decision-needed` | `lib/handoff.mjs` remains top-level; decide core coordination semantics versus CLI command helper. |
-| `61b02a2` | timeline | `squash/rebuild` | Final boundary is core coordination timeline. |
-| `62ede11` | runtime state | `squash/rebuild` | Final boundary is `lib/runtime/state.mjs`. |
-| `7d885f1` | task liveness | `squash/rebuild` | Final boundary is core peer liveness. |
-| `3f0cc7e` | session launch | `decision-needed` | Current compatibility file bridges core session launch and terminal/tmux helpers; keep an eye on dependency direction. |
-| `b07e9b5` | automation | `squash/rebuild` | Final boundary is core coordination automation. |
-| `428bbf3` | state render | `squash/rebuild` | Final boundary is UI state rendering. |
-| `8a6120f` | tmux pane | `squash/rebuild` | Should be folded into terminal/tmux movement. |
-| `3ec062b` | help text | `squash/rebuild` | Final boundary is UI help. |
-| `7e8068c` | uninstall help | `squash/rebuild` | Should be folded into UI help extraction. |
-| `9ed79b6` | message store | `squash/rebuild` | Final boundary is core coordination messages. |
-| `07ddcc9` | runtime client | `squash/rebuild` | Final boundary is `lib/runtime/client.mjs`. |
-| `c06e55d` | web runtime server helpers | `squash/rebuild` | Useful step, but final boundary is `lib/web/runtime.mjs`; route/session/server split still pending. |
-| `fe36930` | task store | `squash/rebuild` | Final boundary is core coordination tasks. |
-| `3bd0782` | task CLI parsing | `keep-with-cleanup` | This is a CLI-specific helper and can remain near CLI until `lib/cli/*` exists. |
-| `61538fc` | peer bindings | `squash/rebuild` | Final split crosses core peer bindings and db peer store. |
-| `787857f` | CLI runtime | `keep-with-cleanup` | Still not the final `lib/cli/context.mjs` layout, but it is a valid CLI/runtime entrypoint reduction. |
-| `00ac7ba` | coordination state | `squash/rebuild` | Useful factory boundary, but should be evaluated with core coordination dependencies. |
-
-### Phase 2: Architecture Documentation And First Boundary Correction
-
-| Commit | Area | Classification | Reason |
-| --- | --- | --- | --- |
-| `94d63c0` | architecture docs | `docs-only` | Correctly establishes the target layout. |
-| `76d5181` | web peer actions | `squash/rebuild` | Good product boundary direction, but final import path is corrected later under `lib/web/peer-actions.mjs`. |
-| `265284a` | broad architecture alignment | `keep-with-cleanup` | Correct direction, but too broad for ideal history; should become several product-boundary commits on a rebuild branch. Also review whether SQL/transaction-heavy task code belongs in `lib/core/coordination/tasks.mjs` or should split pure task policy from a db store. |
-
-### Phase 3: Product-Boundary Cleanup Commits
-
-These commits are much closer to the target design. They are the model for the
-rebuild branch if one is created.
-
-| Commit | Area | Classification | Reason |
-| --- | --- | --- | --- |
-| `294eb2e` | peer layout boundaries | `keep` | Moves peer semantics toward `core/peers`, `db/stores`, and integrations boundaries. |
-| `a3eabd8` | tmux adapter | `keep` | Clear terminal adapter boundary. |
-| `fb9c35a` | shared JSON file helpers | `keep-with-cleanup` | Shared utility is appropriate; keep `lib/json-file.mjs` compat because it was already published in `0.1.5`. |
-| `77c098d` | provider commands | `keep` | Correct integrations boundary. |
-| `6bbe4a0` | project context | `keep` | Correct runtime boundary. |
-| `be7c882` | session launch helpers | `decision-needed` | Direction is mostly correct, but compat surface exports both core session and terminal/tmux helpers. Review dependency direction before release. |
-| `ffc42a7` | setup hook installers | `keep` | Correct integrations/hooks boundary. |
-| `1bd110f` | setup shims | `keep` | Correct integrations/shims boundary. |
-| `c191c72` | shim script generator | `keep` | Correct integrations/shims/script boundary. |
-| `11fd4f6` | CLI errors | `keep` | Correct small shared utility boundary with compatibility re-export. |
-
-### Phase 4: Review And Policy Docs
-
-| Commit | Area | Classification | Reason |
-| --- | --- | --- | --- |
-| `19c0856` | split review | `docs-only` | Captures the historical concern and branch strategy. |
-| `4283234` | package surface policy | `docs-only` | Captures npm `0.1.5` fact, version-bump requirement, and A/B/C shim policy. |
-
-## Initial Recommendations
-
-### Use A New Branch
-
-Yes. This is a major refactor stack and should not be pushed or published
-directly just because `master` is currently green. Use this audit branch for
-review. If the team chooses clean history, create a separate rebuild branch from
-`origin/master`, not from current `master`.
-
-Suggested rebuild branch:
-
-```bash
-git worktree add ../hello-cc-layout-rebuild -b rebuild/layout-split-20260614 origin/master
-```
-
-Suggested rebuilt commit order:
-
-1. Architecture docs.
-2. Core coordination modules: locks, teams, messages, tasks, timeline,
-   automation, liveness-related coordination state.
-3. Core peer/session modules and db peer store.
-4. Runtime modules: paths, state, client, project registry, project context.
-5. Terminal adapter: tmux.
-6. Web modules: runtime, HTTP, peer actions, UI template.
-7. Integrations: providers, hooks, shims, shim script, peer identity.
-8. Shared/release/ui helpers.
-9. Compatibility shim policy and package-surface release notes.
-
-### Do Not Revert The Final Shape Blindly
-
-The final code shape is mostly aligned with the architecture document. The
-problem is the noisy path taken to get there. A rebuild should preserve the
-validated final behavior while changing the history granularity.
-
-### Core/DB Review Findings
-
-The core/db review from `#236` and the parallel read-only subagent agree on the
-main shape:
-
-- Keep the final direction of `lib/core/coordination/*`, `lib/core/peers/*`,
-  `lib/core/sessions/launch.mjs`, `lib/db/schema.mjs`,
-  `lib/db/stores/peers.mjs`, and `lib/shared/errors.mjs`.
-- Rebuild the early top-level coordination/peer/session helper commits into
-  product-boundary commits if clean history is chosen.
-- Do not treat `lib/handoff.mjs`, `lib/session-launch.mjs`, or
-  `lib/coordination-state.mjs` as settled final architecture.
-
-Concrete cleanup items from that review:
-
-- `lib/core/coordination/tasks.mjs` is currently SQL/transaction-heavy. Split
-  pure task lifecycle/takeover/team policy from DB store operations, or move the
-  store-style SQL operations under `lib/db/stores/tasks.mjs`.
-- `lib/core/coordination/automation.mjs` and
-  `lib/core/coordination/timeline.mjs` depend on top-level `lib/format.mjs` for
-  `shellQuoteArg` / `compactText`. Move dependency-light text helpers to
-  `lib/shared/text.mjs` or keep rendering concerns in the UI/CLI layer.
-- `lib/handoff.mjs` mixes CLI input normalization with runtime Git changed-file
-  discovery. Split handoff product semantics from CLI/runtime file inspection.
-- `lib/session-launch.mjs` re-exports both core session helpers and
-  terminal/tmux helpers. That is acceptable only as a compatibility entrypoint;
-  do not let it become the conceptual module boundary.
-- `lib/coordination-state.mjs` is useful as an interim assembler, but it mixes
-  DB queries, timeline, automation, hook context, status summary, and message
-  ack batching. Later split it into core state services plus CLI/Web adapters.
-
-### Runtime/Web/Integrations Review Findings
-
-The runtime/web/terminal/integrations review from `#235` and the parallel
-read-only subagent agree on the main shape:
-
-- Keep the final direction of `lib/terminal/tmux.mjs`.
-- Keep the final direction of `lib/integrations/providers.mjs`,
-  `lib/integrations/hooks.mjs`, `lib/integrations/shims.mjs`, and
-  `lib/integrations/shims/script.mjs`.
-- Keep the final direction of `lib/release/*`, `lib/shared/errors.mjs`, and
-  `lib/shared/json-file.mjs`.
-- Keep the runtime and Web movement as directionally correct:
-  `lib/runtime/{paths,state,client,projects,project-context}.mjs` and
-  `lib/web/{http,runtime,ui-template,peer-actions}.mjs`.
-
-Concrete cleanup items from that review:
-
-- `lib/runtime/client.mjs` and `lib/runtime/state.mjs` import `runtimeApiUrl`
-  from `lib/web/runtime.mjs`. That creates a runtime -> web reverse dependency.
-  Move the URL helper into `lib/runtime`, `lib/shared`, or inject it from the
-  caller before claiming strict dependency direction.
-- `lib/web/runtime.mjs` and `lib/web/peer-actions.mjs` import CLI parsing
-  helpers from `lib/cli-args.mjs`. Move shared option parsing such as
-  `intOpt`/`required` to a dependency-light shared helper, or inject parsing at
-  the route boundary.
-- `lib/web/peer-actions.mjs` imports `normalizeStateResources` from
-  `lib/ui/state-render.mjs`. Move non-render normalization out of the UI layer,
-  or keep the dependency at a CLI/Web adapter edge.
-- `cmdWeb()` in `bin/hcc.mjs` still owns server lifecycle, session manager,
-  WebSocket terminal transport, tmux/PTY orchestration, external-buffer
-  adoption, and shutdown cleanup. Future work should split this by subsystem;
-  do not continue random helper extraction from it.
-
-No immediate runtime blocker was found. `#235` also reran `npm test` and got
-`FULL_REGRESSION_OK`.
-
-### Decide Shim Policy Before Release
-
-Because `@logicseek/hello-cc@0.1.5` is already published from `4969100`, the
-next package version must be new. Before that publish:
-
-- Group A: already-published or CLI-facing top-level `lib/*.mjs` paths stay.
-- Group B: migration compatibility paths stay one release if needed and are
-  documented as compatibility-only deep-import paths.
-- Group C: unpublished top-level shims with no internal use or compatibility
-  value should be removed before release.
-
-Initial package-surface inventory:
-
-| Group | Paths | Current decision |
-| --- | --- | --- |
-| A: published in `0.1.5` | `lib/cli-args.mjs`, `lib/db-schema.mjs`, `lib/discover.mjs`, `lib/errors.mjs`, `lib/format.mjs`, `lib/guidance.mjs`, `lib/json-file.mjs`, `lib/package-meta.mjs`, `lib/release-notes.mjs`, `lib/runtime-paths.mjs`, `lib/setup.mjs`, `lib/shell-path.mjs`, `lib/shim-script.mjs`, `lib/web-http.mjs`, `lib/web-runtime.mjs`, `lib/web-ui-template.mjs` | Keep for the next release, even if some are now compatibility re-exports. Removing them would be a package-surface break. |
-| A: current internal top-level runtime refs | `lib/cli-runtime.mjs`, `lib/coordination-state.mjs`, `lib/handoff.mjs`, `lib/project-context.mjs`, `lib/task-cli.mjs`, `lib/tmux.mjs` | Keep until a focused cleanup moves current internal imports to the target directories. Do not delete these as pure compatibility shims today. |
-| B/C candidates: new re-export-only paths with no current runtime ref | `lib/automation.mjs`, `lib/help.mjs`, `lib/locks.mjs`, `lib/messages.mjs`, `lib/peer-bindings.mjs`, `lib/peer-format.mjs`, `lib/peer-identity.mjs`, `lib/project-registry.mjs`, `lib/provider-commands.mjs`, `lib/runtime-client.mjs`, `lib/runtime-state.mjs`, `lib/session-launch.mjs`, `lib/state-render.mjs`, `lib/task-liveness.mjs`, `lib/task-store.mjs`, `lib/team-planning.mjs`, `lib/timeline.mjs`, `lib/web-peer-actions.mjs` | Treat as C only if the project decides they have no migration compatibility value. Otherwise keep for one release as B and document them as compatibility-only deep imports. |
-| C: remove before publish | None confirmed yet | Do not delete by guess. A candidate becomes C only after checking it was not in `0.1.5`, is not imported internally, and has no release compatibility value. |
-
-### Watch Items
-
-- `lib/handoff.mjs`: decide core coordination versus CLI command helper.
-- `lib/session-launch.mjs`: review mixed core session and terminal/tmux
-  compatibility exports.
-- `lib/core/coordination/tasks.mjs`: split pure task policy from DB store style
-  SQL/transactions.
-- `lib/core/coordination/{automation,timeline}.mjs`: remove dependency on
-  top-level `lib/format.mjs`.
-- `lib/coordination-state.mjs`: keep as interim assembler, but split before
-  claiming final architecture.
-- `lib/runtime/{client,state}.mjs`: remove reverse dependency on
-  `lib/web/runtime.mjs`.
-- `lib/web/{runtime,peer-actions}.mjs`: remove direct dependency on CLI parsing
-  helpers.
-- `lib/web/peer-actions.mjs`: remove direct dependency on UI state-render
-  helpers for non-render normalization.
-- `scripts/regression.mjs`: current test coverage is valuable, but its size
-  should be split after the architecture stack is stable.
-- `bin/hcc.mjs`: still contains large command and Web orchestration areas; do
-  not continue extracting from it until this audit decides branch strategy.
-
-## Current Status
-
-Peer feedback from `#235`, `#236`, and `#237` has been merged into this audit.
-The audit conclusion is:
-
-- The final code shape is mostly reasonable.
-- The early commit history is not clean architecture history.
-- Use a new rebuild branch from `origin/master` if clean history matters.
-- Keep the current `master` stack only if the project accepts noisy local
-  history and completes the release cleanup items above before publish.
-- Do not resume release task `#233` until this audit decision is accepted.

package/docs/superpowers/plans/2026-08-03-runtime-safety-plan.md

@@ -1,294 +0,0 @@
-# Runtime Safety, Clock, GC, and Registry Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make clock, takeover, garbage collection, and project-registry decisions safe under sleep, PID reuse, runtime failure, and concurrent writers.
-
-**Architecture:** A clock-safety module owns persistent observation and grace. A buffer-GC planner is shared by CLI and runtime, while an authenticated runtime endpoint serializes deletion with active sessions. Registry updates use an owner-identified lock directory.
-
-**Tech Stack:** Node.js 24 ESM, `node:test`, `node:sqlite`, filesystem atomics, HTTP runtime API, tmux integration.
-
----
-
-## File Map
-
-- Create `lib/core/coordination/clock-safety.mjs` and `test/clock-safety.test.mjs`.
-- Modify `lib/shared/clock-grace.mjs` to make grace extension atomic and observable.
-- Create `lib/runtime/buffer-gc.mjs` and `test/buffer-gc.test.mjs`.
-- Create `lib/shared/file-lock.mjs` and `test/file-lock.test.mjs`.
-- Modify `bin/hcc.mjs` for clock observation, runtime GC endpoint, safe CLI GC, and history flags.
-- Modify `lib/runtime/projects.mjs` for lock-protected registry merging.
-- Modify `lib/runtime/client.mjs` for the internal buffer-GC request.
-- Modify `lib/coordination-state.mjs`, task/lock paths, and `scripts/regression.mjs` for integration behavior.
-
-### Task 1: Make grace extension atomic and classify observation decisions
-
-**Files:**
-- Create: `lib/core/coordination/clock-safety.mjs`
-- Create: `test/clock-safety.test.mjs`
-- Modify: `lib/shared/clock-grace.mjs:1-46`
-
-- [ ] **Step 1: Write failing pure-decision tests**
-
-```js
-import test from 'node:test';
-import assert from 'node:assert/strict';
-import { decideClockSafety } from '../lib/core/coordination/clock-safety.mjs';
-
-test('live evidence crosses expiry without grace and requests renewal', () => {
-  assert.deepEqual(decideClockSafety({ previous: 100, current: 1000, operation: 'ownership', candidates: [{ boundary: 500, evidence: 'live' }] }), {
-    enterGrace: false,
-    renewOwners: true,
-    reason: 'verified-live'
-  });
-});
-
-test('unknown evidence crossing expiry enters grace', () => {
-  assert.equal(decideClockSafety({ previous: 100, current: 1000, operation: 'ownership', candidates: [{ boundary: 500, evidence: 'unknown' }] }).enterGrace, true);
-});
-
-test('GC crossing an age cutoff enters grace without owner candidates', () => {
-  assert.equal(decideClockSafety({ previous: 100, current: 1000, operation: 'gc', gcCutoffs: [500] }).enterGrace, true);
-});
-
-test('verified dead evidence does not delay ownership', () => {
-  assert.equal(decideClockSafety({ previous: 100, current: 1000, operation: 'ownership', candidates: [{ boundary: 500, evidence: 'dead' }] }).enterGrace, false);
-});
-```
-
-- [ ] **Step 2: Run to verify RED**
-
-Run: `node --test test/clock-safety.test.mjs`
-
-Expected: FAIL because the decision module is missing.
-
-- [ ] **Step 3: Implement the pure decision and atomic SQL extension**
-
-`decideClockSafety` must return deterministic `{ enterGrace, renewOwners, reason }` from the supplied observation. Backward movement beyond five seconds always enters grace for unknown and GC age decisions. Long forward gaps enter grace only when they cross the relevant boundary.
-
-Replace grace overwrite SQL with:
-
-```sql
-INSERT INTO meta(key, value) VALUES ('clock_grace_until', ?)
-ON CONFLICT(key) DO UPDATE SET value = CAST(
-  MAX(CAST(meta.value AS INTEGER), CAST(excluded.value AS INTEGER)) AS TEXT
-)
-```
-
-`writeClockGraceUntil` returns the persisted deadline and throws on write failure; it must not swallow exceptions.
-
-- [ ] **Step 4: Verify GREEN**
-
-Run: `node --test test/clock-safety.test.mjs`.
-
-Add a real in-memory SQLite test with two shorter/longer writes and assert the final value is the maximum. Run again and require PASS.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add lib/core/coordination/clock-safety.mjs lib/shared/clock-grace.mjs test/clock-safety.test.mjs
-git commit -m "fix: make clock grace monotonic"
-```
-
-### Task 2: Observe clock safety before destructive ownership decisions
-
-**Files:**
-- Modify: `bin/hcc.mjs:413-471,728-751,1053-1120,1752-1810,2926-3005,5709-5725,6426-6538`
-- Modify: `lib/core/coordination/clock-safety.mjs`
-- Modify: `lib/coordination-state.mjs:37-105,191-220`
-- Modify: `lib/core/coordination/tasks.mjs:73-90`
-- Modify: `scripts/regression.mjs:2616-2820`
-
-- [ ] **Step 1: Add the CLI-only failing integration fixture**
-
-Create an isolated project with no local or global runtime pointer. Register a peer using the regression process PID and stored fingerprint, acquire a lock, move only wall-clock DB timestamps one day into the past, remove `clock_grace_until`, and attempt acquisition from another peer.
-
-Write the final expected assertion from the start:
-
-```js
-if (attempt.status === 0 || !attempt.stderr.includes('LOCK_HELD')) {
-  fail(`live owner was not protected after a CLI-only clock gap:\n${attempt.stderr}`);
-}
-```
-
-From the same initial test, require an unchanged owner, renewed `expires_at`, and
-no blanket grace for the verified live owner. Add unknown-evidence and
-verified-dead variants before running RED.
-
-- [ ] **Step 2: Run to verify RED**
-
-Run: `npm run test:regression`.
-
-Expected: live-owner fixture demonstrates takeover/replacement under the current code.
-
-- [ ] **Step 3: Add the observation transaction**
-
-Export `observeClockSafety(db, { operation, candidates, gcCutoffs, nowSec })`. In one immediate transaction, read `clock_last_observed_at`, call `decideClockSafety`, extend grace to `nowSec + 120` only when `enterGrace` is true, and write the new watermark. Persist the maximum of the existing and proposed deadline. Return the decision and persisted grace. Verified-live evidence renews immediately without grace, verified-dead evidence proceeds without grace, and only unknown evidence receives the 120-second delay.
-
-Call it before lock acquire, task takeover, heartbeat/hook recovery, reaper, and GC. Do not call it from pure status/list/doctor paths. When it reports verified live owners, renew retained locks from `ttl_sec`. When grace persistence throws, abort the destructive command with `CLOCK_SAFETY_UNAVAILABLE`.
-
-The Web poller passes its wall/monotonic jump signal into the same observer and no longer maintains a separate grace algorithm.
-
-- [ ] **Step 4: Verify GREEN and nearby behavior**
-
-Run: `node --test test/clock-safety.test.mjs`.
-
-Run: `npm run test:regression`.
-
-Expected: live evidence renews immediately, dead evidence expires, unknown evidence enters grace, status/doctor remain read-only.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add bin/hcc.mjs lib/core/coordination/clock-safety.mjs lib/coordination-state.mjs lib/core/coordination/tasks.mjs scripts/regression.mjs
-git commit -m "fix: protect CLI-only ownership after clock gaps"
-```
-
-### Task 3: Extract a buffer-GC planner and runtime arbitration endpoint
-
-**Files:**
-- Create: `lib/runtime/buffer-gc.mjs`
-- Create: `test/buffer-gc.test.mjs`
-- Modify: `bin/hcc.mjs:3005-3063,6426-6538,4675-5050`
-- Modify: `lib/runtime/client.mjs:7-35`
-- Modify: `scripts/regression.mjs:1841-1880,2866-3300,7019-7070`
-
-- [ ] **Step 1: Write failing planner tests with real files**
-
-In a temporary `bufs` directory create old protected, old dead, old unknown, and new files. Call:
-
-```js
-const result = pruneBufferFiles({
-  directories: [bufsDir],
-  cutoffMs,
-  protectedPaths: new Set([protectedFile]),
-  unknownPaths: new Set([unknownFile]),
-  dryRun: false
-});
-```
-
-Assert protected/unknown/new remain, dead old is deleted, and counts are `{ deleted: 1, protected: 1, deferred: 1 }`.
-
-- [ ] **Step 2: Run to verify RED**
-
-Run: `node --test test/buffer-gc.test.mjs`.
-
-Expected: missing-module failure.
-
-- [ ] **Step 3: Implement the planner and endpoint**
-
-Implement `pruneBufferFiles` with absolute resolved paths, `lstat` regular-file/FIFO checks, one supplied cutoff, and identical dry-run/apply planning. It must not follow symlinks.
-
-Add authenticated `POST /api/runtime/gc-buffers`. The handler snapshots actual `outFile`, `inFile`, `resizeFile`, `pipeFile`, and external meta paths from every running session, groups them by actual directory, and calls the synchronous planner before returning counts.
-
-Manual CLI GC fixes `cutoffMs` before the request. If a runtime pointer exists and the endpoint returns unreachable/404/426, mark eligible buffers deferred and do not fall back to blind local deletion. With no runtime pointer, build live/unknown protection from external metadata fingerprints and verified tmux panes.
-
-- [ ] **Step 4: Verify RED-GREEN at the real boundary**
-
-Run planner tests. Then add runtime integration cases for active external files, active tmux FIFO, sibling-project actual directories, unreachable runtime, legacy metadata, and orphan old files.
-
-Run: `npm run test:regression`.
-
-Expected: active/unknown files remain, only proven old orphans are removed, and runtime failure reports deferred counts.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add lib/runtime/buffer-gc.mjs test/buffer-gc.test.mjs lib/runtime/client.mjs bin/hcc.mjs scripts/regression.mjs
-git commit -m "fix: arbitrate buffer cleanup through runtime"
-```
-
-### Task 4: Make GC retention explicit and clock-safe
-
-**Files:**
-- Modify: `bin/hcc.mjs:6420-6557`
-- Modify: `lib/ui/help.mjs:40-50,285-305`
-- Modify: `scripts/regression.mjs:3689-3776,7019-7070`
-
-- [ ] **Step 1: Add failing CLI cases**
-
-Add fixtures proving:
-
-```text
-hcc gc --older-than -1 --yes -> BAD_ARGS, no row/file changes
-hcc gc --older-than 0 --yes -> technical cleanup only
-hcc gc --older-than 0 --history -> dry-run only
-hcc gc --older-than 0 --history --yes -> eligible history removed
-clock grace + any form -> every age-based category deferred
-```
-
-Keep an open-task handoff and assert it survives even with `--history --yes`.
-
-- [ ] **Step 2: Run to verify RED**
-
-Run: `npm run test:regression`.
-
-Expected: negative retention mutates/plans broadly, and ordinary `--yes` currently removes history.
-
-- [ ] **Step 3: Implement the command contract**
-
-Reject `olderThanDays < 0` before `connect()`. Parse a `history` boolean. Split the planner into technical and history SQL. During grace, produce deferred counts for all age-based categories and execute no age-based delete. Always preserve handoffs linked to tasks outside `done`/`abandoned`.
-
-Keep WAL checkpoint only after an applied safe plan. Update text and JSON output with `deleted`, `protected`, and `deferred` category counts.
-
-- [ ] **Step 4: Verify GREEN**
-
-Run: `npm run test:regression`.
-
-Run: `node ./bin/hcc.mjs gc --help`.
-
-Expected: every CLI contract case passes and help documents `--history`.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add bin/hcc.mjs lib/ui/help.mjs scripts/regression.mjs
-git commit -m "fix: make GC retention explicit and safe"
-```
-
-### Task 5: Serialize project-registry writers
-
-**Files:**
-- Create: `lib/shared/file-lock.mjs`
-- Create: `test/file-lock.test.mjs`
-- Modify: `lib/runtime/projects.mjs:1-86`
-- Modify: `scripts/regression.mjs:1813-1840,4500-4700`
-
-- [ ] **Step 1: Write failing real-filesystem tests**
-
-Spawn two Node child processes that wait on a barrier file, then concurrently call `registerProject` for different roots under one isolated `HOME`. Assert both records remain. Add a same-root/different-DB update inside 60 seconds and assert the DB changes immediately.
-
-Add a stale-lock fixture with a dead owner fingerprint and an unknown-owner fixture. Dead lock must be reclaimed; unknown lock must time out without deletion.
-
-- [ ] **Step 2: Run to verify RED**
-
-Run: `node --test test/file-lock.test.mjs`.
-
-Expected: missing-module failure, then the concurrent registry assertion fails before integration.
-
-- [ ] **Step 3: Implement atomic lock-directory ownership**
-
-Implement:
-
-```js
-export function withFileLock(target, fn, { timeoutMs = 5000, retryMs = 25 } = {})
-```
-
-Acquire `${target}.lock` with `mkdirSync`. Write owner metadata atomically with the current process fingerprint. On `EEXIST`, inspect the owner: reclaim only `dead`, retry `live`, and time out `unknown`. Always remove only the lock whose owner token still matches the current holder.
-
-Wrap the entire registry re-read, merge, throttle decision, and atomic write. Compare both canonical root and resolved DB before throttling.
-
-- [ ] **Step 4: Verify GREEN**
-
-Run: `node --test test/file-lock.test.mjs`.
-
-Run: `npm run test:regression`.
-
-Expected: concurrent writers retain both records; changed DB updates immediately; unknown locks are not stolen.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add lib/shared/file-lock.mjs test/file-lock.test.mjs lib/runtime/projects.mjs scripts/regression.mjs
-git commit -m "fix: serialize project registry updates"
-```