@logicseek/hello-cc 0.1.9 → 1.0.0

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

@@ -0,0 +1,294 @@
+# 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"
+```

package/docs/superpowers/plans/2026-08-03-v1-data-identity-plan.md

@@ -0,0 +1,400 @@
+# hello-cc v1 Data and Identity 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:** Introduce schema v7, safe pre-migration backups, process fingerprints, and the breaking v1 provider identity contract.
+
+**Architecture:** Put process inspection and migration backup logic in focused modules. Persist opaque process fingerprints on peers and external/tmux session metadata, then route all liveness consumers through one three-state resolver.
+
+**Tech Stack:** Node.js 24 ESM, `node:test`, `node:sqlite`, macOS `ps`, Linux `/proc`, tmux.
+
+---
+
+## File Map
+
+- Create `test/process-identity.test.mjs`: real-process and parser behavior.
+- Create `test/schema-v7.test.mjs`: real SQLite backup and migration behavior.
+- Create `lib/process/identity.mjs`: inspect and compare process fingerprints.
+- Create `lib/db/migration-backup.mjs`: consistent `VACUUM INTO` backup.
+- Create `lib/core/peers/evidence.mjs`: `live`/`dead`/`unknown` resolver.
+- Modify `package.json`: unit-test scripts and v1 version.
+- Modify `lib/db/schema.mjs`: schema v7 process columns and backup hook.
+- Modify `bin/hcc.mjs`: migration hook, peer identity persistence, liveness wiring.
+- Modify `lib/core/peers/liveness.mjs`: consume evidence rather than age alone.
+- Modify `lib/core/coordination/tasks.mjs`: use evidence for takeover.
+- Modify `lib/core/peers/session.mjs`: finalize the breaking v1 ID algorithm.
+- Modify `lib/integrations/shims/script.mjs`: keep shim hashing byte-identical.
+- Modify `scripts/regression.mjs`: real CLI migration and session evidence coverage.
+
+### Task 1: Add the focused unit-test entry point
+
+**Files:**
+- Modify: `package.json:24-32`
+- Create: `test/process-identity.test.mjs`
+
+- [ ] **Step 1: Write the failing test**
+
+Create the test with the intended module API:
+
+```js
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  compareProcessIdentity,
+  inspectProcessIdentity,
+  parseLinuxStatStartTicks,
+  parsePsStartIdentity
+} from '../lib/process/identity.mjs';
+
+test('reads a stable identity for the current process', () => {
+  const first = inspectProcessIdentity(process.pid);
+  const second = inspectProcessIdentity(process.pid);
+  assert.equal(first.state, 'live');
+  assert.deepEqual(second.identity, first.identity);
+  assert.equal(compareProcessIdentity(first.identity, second.identity), 'live');
+});
+
+test('parses Linux stat when command contains spaces and parentheses', () => {
+  const fields = Array.from({ length: 30 }, (_, i) => String(i + 1));
+  fields[19] = '987654';
+  assert.equal(parseLinuxStatStartTicks(`42 (worker (one)) ${fields.join(' ')}`), '987654');
+});
+
+test('parses macOS ps start and command identity', () => {
+  assert.deepEqual(parsePsStartIdentity('Mon Aug  3 06:10:11 2026\t/usr/bin/node app.mjs\n'), {
+    startToken: 'Mon Aug  3 06:10:11 2026',
+    command: '/usr/bin/node app.mjs'
+  });
+});
+
+test('rejects a reused PID fingerprint', () => {
+  const stored = { pid: 42, startToken: 'boot-a:100', commandHash: 'aaa' };
+  const current = { pid: 42, startToken: 'boot-a:200', commandHash: 'aaa' };
+  assert.equal(compareProcessIdentity(stored, current), 'dead');
+  assert.equal(compareProcessIdentity(null, current), 'unknown');
+});
+```
+
+- [ ] **Step 2: Run the test to verify RED**
+
+Run: `node --test test/process-identity.test.mjs`
+
+Expected: FAIL with `ERR_MODULE_NOT_FOUND` for `lib/process/identity.mjs`.
+
+- [ ] **Step 3: Add the unit-test scripts**
+
+Set the scripts to:
+
+```json
+"pretest": "npm run test:unit",
+"test": "npm run test:regression",
+"test:unit": "node --test test/*.test.mjs",
+"test:regression": "node ./scripts/regression.mjs"
+```
+
+Do not change the production version in this task.
+
+- [ ] **Step 4: Verify the intended failure through npm**
+
+Run: `npm run test:unit`
+
+Expected: the same missing-module failure, proving the new test entry point runs.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add package.json test/process-identity.test.mjs
+git commit -m "test: add v1 focused test entry point"
+```
+
+### Task 2: Implement cross-platform process fingerprints
+
+**Files:**
+- Create: `lib/process/identity.mjs`
+- Test: `test/process-identity.test.mjs`
+
+- [ ] **Step 1: Complete the failing boundary tests before implementation**
+
+Append tests that inspect PID `2147483647` as dead, treat a partial stored
+fingerprint as unknown, reject a changed command hash, and parse malformed Linux
+and macOS fixture rows as unknown/null.
+
+- [ ] **Step 2: Run the complete test to verify RED**
+
+Run: `node --test test/process-identity.test.mjs`
+
+Expected: the module is still missing and every final identity expectation is
+already present before production code exists.
+
+- [ ] **Step 3: Implement the minimal identity module**
+
+```js
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+
+function commandHash(command) {
+  return createHash('sha256').update(String(command || '').trim()).digest('hex');
+}
+
+export function parseLinuxStatStartTicks(text) {
+  const close = String(text).lastIndexOf(')');
+  if (close < 0) return null;
+  const rest = String(text).slice(close + 2).trim().split(/\s+/);
+  return rest[19] || null;
+}
+
+export function parsePsStartIdentity(text) {
+  const line = String(text).trimEnd();
+  const tab = line.indexOf('\t');
+  if (tab < 0) return null;
+  const startToken = line.slice(0, tab).trim();
+  const command = line.slice(tab + 1).trim();
+  return startToken && command ? { startToken, command } : null;
+}
+
+function linuxIdentity(pid) {
+  const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+  const startTicks = parseLinuxStatStartTicks(stat);
+  const bootId = fs.readFileSync('/proc/sys/kernel/random/boot_id', 'utf8').trim();
+  const command = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0').filter(Boolean).join(' ');
+  if (!startTicks || !bootId) throw new Error('incomplete Linux identity');
+  return { pid, startToken: `${bootId}:${startTicks}`, commandHash: commandHash(command) };
+}
+
+function psIdentity(pid) {
+  const boot = spawnSync('sysctl', ['-n', 'kern.boottime'], { encoding: 'utf8' });
+  const started = spawnSync('ps', ['-p', String(pid), '-o', 'lstart='], { encoding: 'utf8' });
+  const command = spawnSync('ps', ['-p', String(pid), '-o', 'command='], { encoding: 'utf8' });
+  if (started.status !== 0 || command.status !== 0 || boot.status !== 0) return null;
+  const parsed = parsePsStartIdentity(`${started.stdout.trim()}\t${command.stdout.trim()}\n`);
+  if (!parsed) throw new Error('incomplete ps identity');
+  return {
+    pid,
+    startToken: `${String(boot.stdout || '').trim()}:${parsed.startToken}`,
+    commandHash: commandHash(parsed.command)
+  };
+}
+
+export function inspectProcessIdentity(value) {
+  const pid = Number(value);
+  if (!Number.isInteger(pid) || pid <= 0) return { state: 'unknown', identity: null };
+  try {
+    process.kill(pid, 0);
+  } catch (err) {
+    if (err?.code === 'ESRCH') return { state: 'dead', identity: null };
+    if (err?.code !== 'EPERM') return { state: 'unknown', identity: null };
+  }
+  try {
+    const identity = process.platform === 'linux' ? linuxIdentity(pid) : psIdentity(pid);
+    return identity ? { state: 'live', identity } : { state: 'dead', identity: null };
+  } catch {
+    return { state: 'unknown', identity: null };
+  }
+}
+
+function isCompleteIdentity(value) {
+  return Number.isInteger(Number(value?.pid)) && Number(value.pid) > 0 &&
+    typeof value?.startToken === 'string' && value.startToken.length > 0 &&
+    typeof value?.commandHash === 'string' && /^[a-f0-9]{64}$/.test(value.commandHash);
+}
+
+export function compareProcessIdentity(stored, current) {
+  if (!isCompleteIdentity(stored) || !isCompleteIdentity(current)) return 'unknown';
+  return Number(stored.pid) === Number(current.pid) &&
+    stored.startToken === current.startToken &&
+    stored.commandHash === current.commandHash ? 'live' : 'dead';
+}
+```
+
+- [ ] **Step 4: Run focused tests to verify GREEN**
+
+Run: `node --test test/process-identity.test.mjs`
+
+Expected: all boundary tests PASS on macOS and Linux. If the macOS parser fixture exposes a spacing mismatch, fix the parser, not the assertions.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/process/identity.mjs test/process-identity.test.mjs
+git commit -m "feat: add process identity fingerprints"
+```
+
+### Task 3: Add schema v7 and consistent migration backups
+
+**Files:**
+- Create: `lib/db/migration-backup.mjs`
+- Create: `test/schema-v7.test.mjs`
+- Modify: `lib/db/schema.mjs:3,76-88,169-179,318-355`
+- Modify: `bin/hcc.mjs:413-466`
+
+- [ ] **Step 1: Write real SQLite failing tests**
+
+Create temporary v5 and v6 databases using `DatabaseSync`. Assert that `ensureMigrationBackup(db, dbPath, 5, 7)` returns a new path, the backup passes `quick_check`, contains the original row, and a second call returns a different non-overwriting path. Add a failure case with an unwritable destination and assert the source `schema_version` remains unchanged.
+
+Use this call shape:
+
+```js
+const backup = ensureMigrationBackup(db, dbPath, 5, 7, { timestamp: () => '20260803T120000000Z' });
+assert.match(backup, /mesh\.db\.pre-v5-to-v7\.20260803T120000000Z\.[a-f0-9]{8}\.bak$/);
+```
+
+- [ ] **Step 2: Run to verify RED**
+
+Run: `node --test test/schema-v7.test.mjs`
+
+Expected: FAIL because `lib/db/migration-backup.mjs` does not exist.
+
+- [ ] **Step 3: Implement backup and migration hook**
+
+Implement `ensureMigrationBackup` with a SQL-string quoting helper, `VACUUM INTO`, an exclusive new filename, read-only `quick_check`, and cleanup of an invalid backup. Export `initSchema(db, { beforeMigration, ... })`; call `beforeMigration({ fromVersion, toVersion })` before the migration transaction when `fromVersion < 7`.
+
+Set:
+
+```js
+export const DB_SCHEMA_VERSION = 7;
+```
+
+Add to `peers` and migration 7:
+
+```sql
+pid_start_token TEXT,
+pid_command_hash TEXT
+```
+
+In every production connection path, pass:
+
+```js
+beforeMigration: ({ fromVersion, toVersion }) =>
+  ensureMigrationBackup(db, dbPath, fromVersion, toVersion)
+```
+
+The sibling-project migration catch remains isolated and logs the backup failure.
+
+- [ ] **Step 4: Verify GREEN and migration integration**
+
+Run: `node --test test/schema-v7.test.mjs`
+
+Then add v7 expectations to `createLegacySchemaDb`, `assertLegacySchemaMigration`, `assertRegisteredProjectDbMigration`, and the future-schema rejection workflow in `scripts/regression.mjs`.
+
+Run: `npm run test:regression`
+
+Expected: `FULL_REGRESSION_OK` with v5 and v6 fixtures backed up before v7.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/db/migration-backup.mjs lib/db/schema.mjs bin/hcc.mjs test/schema-v7.test.mjs scripts/regression.mjs
+git commit -m "feat: back up databases before schema v7"
+```
+
+### Task 4: Persist identities and unify liveness evidence
+
+**Files:**
+- Create: `lib/core/peers/evidence.mjs`
+- Create: `test/peer-evidence.test.mjs`
+- Modify: `bin/hcc.mjs:524-575,2610-2720,4369-4515,5620-5735`
+- Modify: `lib/core/peers/liveness.mjs:1-65`
+- Modify: `lib/core/coordination/tasks.mjs:65-90`
+- Modify: `scripts/regression.mjs:2616-2820,6834-6918`
+
+- [ ] **Step 1: Write failing evidence tests**
+
+Use complete peer/session fixtures and assert:
+
+```js
+assert.equal(resolvePeerEvidence({ peer: { status: 'exited' } }).state, 'dead');
+assert.equal(resolvePeerEvidence({ peer: detachedPeer, process: matchingProcess, tmuxManaged: false }).state, 'live');
+assert.equal(resolvePeerEvidence({ peer: detachedPeer, tmux: matchingPane, tmuxManaged: true }).state, 'live');
+assert.equal(resolvePeerEvidence({ peer: workingPeer, process: reusedPid, tmuxManaged: false }).state, 'dead');
+assert.equal(resolvePeerEvidence({ peer: legacyPeer, process: { state: 'live', identity: null }, tmuxManaged: false }).state, 'unknown');
+```
+
+Run: `node --test test/peer-evidence.test.mjs`
+
+Expected: FAIL because the resolver module is missing.
+
+- [ ] **Step 2: Implement the resolver**
+
+```js
+export function resolvePeerEvidence({ peer, process: processEvidence, tmux = null, tmuxManaged = false } = {}) {
+  if (peer?.status === 'exited') return { state: 'dead', reason: 'explicit-exit' };
+  if (tmux?.state === 'live') return { state: 'live', reason: 'tmux-identity' };
+  if (processEvidence?.state === 'live' && processEvidence.identityMatched) {
+    return { state: 'live', reason: 'process-identity' };
+  }
+  const processDead = processEvidence?.state === 'dead' ||
+    (processEvidence?.state === 'live' && processEvidence.identityMatched === false);
+  if (tmux?.state === 'unknown' || processEvidence?.state === 'unknown') {
+    return { state: 'unknown', reason: 'incomplete-evidence' };
+  }
+  if (tmuxManaged && tmux?.state === 'dead' && processDead) {
+    return { state: 'dead', reason: 'process-and-tmux-dead' };
+  }
+  if (!tmuxManaged && processDead) return { state: 'dead', reason: 'process-dead' };
+  return { state: 'unknown', reason: 'insufficient-evidence' };
+}
+```
+
+- [ ] **Step 3: Persist and consume fingerprints**
+
+When registering/upserting a peer, inspect its PID and persist `pid_start_token` and `pid_command_hash` only for verified identity. Store full wrapper/child identity objects in external `.meta`. Store pane identity when adopting or starting tmux.
+
+Replace age-only decisions in task annotations, takeover, reaper, lock recovery, and GC peer selection with the shared evidence result. `detached` must no longer be included in a hard-coded dead-status set.
+
+- [ ] **Step 4: Verify real behavior**
+
+Run: `node --test test/peer-evidence.test.mjs`
+
+Add integration fixtures for a detached live tmux pane, live non-tmux child, reused PID fingerprint, and legacy unknown metadata. Run: `npm run test:regression`.
+
+Expected: live evidence blocks takeover; reused/dead evidence permits it; legacy evidence is unknown.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/core/peers/evidence.mjs test/peer-evidence.test.mjs lib/core/peers/liveness.mjs lib/core/coordination/tasks.mjs bin/hcc.mjs scripts/regression.mjs
+git commit -m "fix: resolve ownership from process evidence"
+```
+
+### Task 5: Prove and freeze the v1 provider identity break
+
+**Files:**
+- Modify: `lib/core/peers/session.mjs:1-12`
+- Modify: `lib/integrations/shims/script.mjs:60-149,335-415`
+- Modify: `scripts/regression.mjs:1385-1584,5660-5745`
+
+- [ ] **Step 1: Add failing upgrade-contract assertions**
+
+Assert exact new IDs for a UUID and two same-prefix names, assert they differ from the remote v0.1.9 prefix algorithm, and assert every generated shim returns the JavaScript ID. Add an invalid hash-command fixture and assert transparent provider passthrough.
+
+- [ ] **Step 2: Run the identity contract**
+
+Run: `npm run test:regression`
+
+Expected: if the current worktree already satisfies every final identity
+assertion, record this item as `no_change` and do not modify production code. If
+any assertion fails, the failure becomes the RED proof for Step 3.
+
+- [ ] **Step 3: Correct only a demonstrated algorithm mismatch**
+
+When Step 2 is RED, keep `providerSessionPeerId(kind, providerId)` as full-input
+SHA-1 first-eight hex and make the failing shim path byte-identical. Keep strict
+40-hex validation and passthrough on failure. When Step 2 is already green, skip
+this production step.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run: `npm run test:unit`.
+
+Run: `npm run test:regression`.
+
+Expected: all identity fixtures PASS and no old-name scan regression.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add scripts/regression.mjs
+# Add the two production files only when Step 2 proved a mismatch.
+git commit -m "feat: finalize v1 provider identities"
+```