@logicseek/hello-cc 0.1.8 → 1.0.0

package/docs/superpowers/plans/2026-08-03-web-api-hardening-plan.md

@@ -0,0 +1,303 @@
+# Web and Runtime API v2 Hardening 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:** Ship an explicit Runtime API v2 with bounded browser sessions, session-scoped terminal input, CSP, secret redaction, and symlink-safe project databases.
+
+**Architecture:** Central helpers own API negotiation, redaction, token comparison, and canonical path validation. The HTTP and WebSocket entry points enforce these helpers before routing while preserving the accepted plaintext-LAN and arbitrary-root behaviors.
+
+**Tech Stack:** Node.js 24 HTTP/HTTPS, `ws`, browser WebSocket/fetch, `node:test`, real filesystem integration tests.
+
+---
+
+## File Map
+
+- Create `lib/web/api-version.mjs` and `test/web-api-version.test.mjs`.
+- Create `lib/shared/redact.mjs` and `test/redact.test.mjs`.
+- Create `lib/runtime/project-path.mjs` and `test/project-path.test.mjs`.
+- Modify `lib/web/http.mjs`, `lib/web/runtime.mjs`, `lib/runtime/client.mjs`.
+- Modify `bin/hcc.mjs` HTTP/WS routing, cookie lifecycle, logging, and TLS use.
+- Modify `lib/web/ui-template.mjs` for API headers, WS version query, and CSP nonce.
+- Modify `lib/web/tls.mjs` only where focused tests show a contract gap.
+- Modify `scripts/regression.mjs` for real HTTP/HTTPS/WS tests.
+
+### Task 1: Add Runtime API v2 negotiation
+
+**Files:**
+- Create: `lib/web/api-version.mjs`
+- Create: `test/web-api-version.test.mjs`
+- Modify: `lib/runtime/client.mjs:7-35`
+- Modify: `lib/web/runtime.mjs:11-185`
+- Modify: `bin/hcc.mjs:4675-5190`
+- Modify: `lib/web/ui-template.mjs:1-2100`
+
+- [ ] **Step 1: Write failing negotiation tests**
+
+```js
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { API_VERSION, readHttpApiVersion, readWebSocketApiVersion } from '../lib/web/api-version.mjs';
+
+test('reads API v2 from the HTTP header', () => {
+  assert.equal(API_VERSION, 2);
+  assert.deepEqual(readHttpApiVersion({ headers: { 'x-hcc-api-version': '2' } }), { ok: true, version: 2 });
+});
+
+test('rejects missing and old protected API versions', () => {
+  assert.deepEqual(readHttpApiVersion({ headers: {} }), { ok: false, version: null });
+  assert.deepEqual(readHttpApiVersion({ headers: { 'x-hcc-api-version': '1' } }), { ok: false, version: 1 });
+});
+
+test('reads browser WebSocket version from query', () => {
+  assert.deepEqual(readWebSocketApiVersion(new URL('http://localhost/ws?api_version=2')), { ok: true, version: 2 });
+});
+```
+
+- [ ] **Step 2: Run to verify RED**
+
+Run: `node --test test/web-api-version.test.mjs`.
+
+Expected: missing-module failure.
+
+- [ ] **Step 3: Implement and enforce v2**
+
+```js
+export const API_VERSION = 2;
+
+function result(value) {
+  const version = Number.parseInt(String(value ?? ''), 10);
+  return { ok: version === API_VERSION, version: Number.isFinite(version) ? version : null };
+}
+
+export function readHttpApiVersion(req) {
+  return result(req?.headers?.['x-hcc-api-version']);
+}
+
+export function readWebSocketApiVersion(url) {
+  return result(url?.searchParams?.get('api_version'));
+}
+```
+
+Before every protected `/api/*` route, return status 426 and:
+
+```json
+{"ok":false,"error":{"code":"API_VERSION_UNSUPPORTED","message":"Runtime API version 2 is required","supported_version":2}}
+```
+
+Expose `api_version: 2` from runtime metadata. Add `X-HCC-API-Version: 2` in `runtimeRequest` and every browser fetch wrapper. Add `api_version=2` to terminal WebSocket URLs and reject old/missing WS versions before authentication/session lookup.
+
+- [ ] **Step 4: Verify GREEN and real compatibility rejection**
+
+Run unit tests. Add regression requests with missing/1/2 headers plus WS query 1/2. Public `/`, `/login`, and static assets must remain exempt.
+
+Run: `npm run test:regression`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/web/api-version.mjs test/web-api-version.test.mjs lib/runtime/client.mjs lib/web/runtime.mjs lib/web/ui-template.mjs bin/hcc.mjs scripts/regression.mjs
+git commit -m "feat: require Runtime API v2"
+```
+
+### Task 2: Enforce administrator and session-action token semantics
+
+**Files:**
+- Modify: `lib/web/http.mjs:62-122`
+- Modify: `bin/hcc.mjs:2382-2465,2475-2580,4675-4955,5100-5185`
+- Modify: `lib/web/ui-template.mjs:1570-1760,2050-2110`
+- Modify: `scripts/regression.mjs:1193-1355,1974-2115,2866-3300`
+
+- [ ] **Step 1: Add failing privilege-boundary tests**
+
+Through real HTTP and WebSocket connections assert:
+
+```text
+admin bearer -> create/stop/inject allowed
+admin cookie + same Origin -> create/stop/inject allowed
+admin cookie + foreign Origin -> mutation denied
+session action token absent from GET /api/sessions
+wrong/missing session action token -> WS input denied
+correct token for another session -> WS input denied
+logout/expiry/eviction -> existing cookie WS closed and future input denied
+```
+
+Also assert tokenless non-loopback startup fails while tokenless loopback still works.
+Because constant-time behavior is not safely distinguishable with a timing test,
+add a static security assertion that extracts `resolveWebActionSession` from
+`bin/hcc.mjs`, requires `tokenMatches(provided, expected)`, and rejects direct
+`provided !== expected` comparison. This is the repeatable validation artifact
+for the timing boundary; the integration cases remain the behavior proof.
+
+- [ ] **Step 2: Run to verify RED**
+
+Run: `npm run test:regression`.
+
+Expected: FAIL on the static constant-time assertion while the current code uses
+direct inequality. Any additional integration failure is fixed through the same
+boundary, but is not required to establish RED.
+
+- [ ] **Step 3: Apply one shared token comparator and explicit roles**
+
+Use `tokenMatches(provided, expected)` for administrator and session action tokens. Keep `webAuthMode` results `token` and `cookie`, document both as administrator roles, and keep same-origin enforcement on every cookie mutation. Track each cookie-authenticated WS in its server session record and validate the record before inbound and outbound frames.
+
+Do not put action tokens in serialized session lists. Deliver them only in the corresponding terminal snapshot frame. Preserve CLI injection through administrator bearer authentication without requiring the session token.
+
+- [ ] **Step 4: Verify GREEN and alternate bypasses**
+
+Run the regression suite, then repeat token tests with same-length wrong tokens, URL-encoded peer IDs, revoked cookies, and a token from a sibling project session.
+
+Expected: legitimate admin and matching-session behavior remains; all bypasses fail.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/web/http.mjs bin/hcc.mjs lib/web/ui-template.mjs scripts/regression.mjs
+git commit -m "fix: enforce Web administrator and session tokens"
+```
+
+### Task 3: Add structured secret redaction and CSP
+
+**Files:**
+- Create: `lib/shared/redact.mjs`
+- Create: `test/redact.test.mjs`
+- Modify: `lib/web/http.mjs:33-59`
+- Modify: `lib/web/ui-template.mjs:1-2150`
+- Modify: `bin/hcc.mjs:2180-2250,2368-2470,5290-5300`
+- Modify: `scripts/regression.mjs:1841-2115,3894-4300`
+
+- [ ] **Step 1: Write failing redaction tests**
+
+```js
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { redactSecrets } from '../lib/shared/redact.mjs';
+
+test('redacts CLI, URL, headers, cookies, and structured tokens', () => {
+  const secret = 's3cr3t-value';
+  const value = {
+    command: `hcc web --token ${secret}`,
+    url: `http://host/?token=${secret}&root=/tmp/x`,
+    headers: { authorization: `Bearer ${secret}`, cookie: `hcc_sid=${secret}` },
+    action_token: secret
+  };
+  const redacted = JSON.stringify(redactSecrets(value));
+  assert.equal(redacted.includes(secret), false);
+  assert.equal(redacted.includes('[REDACTED]'), true);
+});
+```
+
+Add an HTML test that extracts the CSP nonce, verifies the script tag uses it, and asserts a second un-nonced inline script would violate the generated `script-src` policy.
+
+- [ ] **Step 2: Run to verify RED**
+
+Run: `node --test test/redact.test.mjs`.
+
+Expected: missing-module failure.
+
+- [ ] **Step 3: Implement redaction and nonce responses**
+
+`redactSecrets(value)` recursively clones arrays/objects, replaces secret-key values, redacts bearer/cookie fragments, replaces `--token` arguments, and deletes URL `token` parameter values. It must handle cycles with a `WeakSet` and replace them with `[Circular]`.
+
+Pass all startup/error logging through this helper before stringification. Never log raw request headers or URLs.
+
+Generate a random nonce per HTML response and call `webIndexHtml({ nonce })` or `webLoginPage({ nonce })`. Add the nonce to every inline script. Emit CSP:
+
+```text
+default-src 'self'; script-src 'self' 'nonce-<value>'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' ws: wss:; object-src 'none'; base-uri 'none'; frame-ancestors 'none'
+```
+
+- [ ] **Step 4: Verify GREEN and leak controls**
+
+Run unit tests. Start Web with unique test secrets, exercise login/WS/errors, stop it, and scan all generated logs/runtime output. Assert no supplied secret appears. Verify browser HTML contains a matching nonce and no un-nonced script.
+
+Run: `npm run test:regression`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/shared/redact.mjs test/redact.test.mjs lib/web/http.mjs lib/web/ui-template.mjs bin/hcc.mjs scripts/regression.mjs
+git commit -m "fix: redact Web secrets and enforce CSP"
+```
+
+### Task 4: Canonicalize arbitrary project roots without symlink escape
+
+**Files:**
+- Create: `lib/runtime/project-path.mjs`
+- Create: `test/project-path.test.mjs`
+- Modify: `bin/hcc.mjs:2479-2525`
+- Modify: `scripts/regression.mjs:2866-3300,6300-6700`
+
+- [ ] **Step 1: Write failing real-filesystem tests**
+
+Create temporary roots for: normal project, missing `.hello-cc`, `.hello-cc` symlink to an outside directory, nested DB symlink escape, `/proc` pseudo-file target on Linux, and a normal custom DB below `.hello-cc`.
+
+Use the intended API:
+
+```js
+const safe = resolveProjectDatabase({ root, db: path.join(root, '.hello-cc', 'mesh.db'), createStateDir: true });
+assert.equal(safe.db.startsWith(safe.stateDir + path.sep), true);
+assert.throws(() => resolveProjectDatabase({ root: escapedRoot, db: escapedDb, createStateDir: true }), /PROJECT_PATH_FORBIDDEN/);
+```
+
+- [ ] **Step 2: Run to verify RED**
+
+Run: `node --test test/project-path.test.mjs`.
+
+Expected: missing-module failure.
+
+- [ ] **Step 3: Implement canonical containment**
+
+Resolve an existing root with `realpathSync`. Create `.hello-cc` with mode `0700` only when requested and absent. Reject it when `lstat` reports a symlink or when its real path is outside root. Resolve the DB parent, reject symlink components escaping the state directory, and require an existing DB target to be a regular file.
+
+Replace `assertDbUnderRoot`/lexical-only checks with `resolveProjectDatabase`. Continue allowing every existing canonical root after administrator authentication.
+
+- [ ] **Step 4: Verify GREEN and HTTP boundary**
+
+Run unit tests, then issue real authenticated Web requests for normal arbitrary roots and each escape fixture. Require normal requests to work and every escape to return `PROJECT_PATH_FORBIDDEN` without creating/opening the outside DB.
+
+Run: `npm run test:regression`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/runtime/project-path.mjs test/project-path.test.mjs bin/hcc.mjs scripts/regression.mjs
+git commit -m "fix: prevent project database symlink escape"
+```
+
+### Task 5: Finish TLS and trusted-proxy mode coverage
+
+**Files:**
+- Track/modify: `lib/web/tls.mjs`
+- Modify: `lib/web/runtime.mjs:80-190`
+- Modify: `lib/runtime/state.mjs:91-123`
+- Modify: `lib/web/http.mjs:76-112`
+- Modify: `scripts/regression.mjs:6440-6600`
+
+- [ ] **Step 1: Add failing mode-matrix tests**
+
+Cover direct self-signed TLS, expired certificate rejection, SAN mismatch regeneration, key mismatch regeneration, loopback trusted proxy, forwarded headers from non-loopback, and accepted plaintext LAN. Assert `Secure` cookie only for direct TLS or trusted loopback proxy reporting HTTPS.
+
+- [ ] **Step 2: Run to verify RED**
+
+Run: `npm run test:regression`.
+
+Expected: any uncovered certificate generation race or proxy-origin discrepancy fails with the specific mode fixture.
+
+- [ ] **Step 3: Make only evidence-required production changes**
+
+Keep generation directories, `.creating`/`.published`, atomic `current.json`, SAN/date/key validation, and CA-scoped runtime requests. Ensure proxy host/proto is consumed only when `--trust-proxy` is enabled and socket remote address is loopback. Do not make TLS mandatory or change the accepted default listener.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run: `npm run test:unit`.
+
+Run: `npm run test:regression`.
+
+Expected: all three supported modes pass and every spoofed forwarded-header control fails closed.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/web/tls.mjs lib/web/runtime.mjs lib/runtime/state.mjs lib/web/http.mjs scripts/regression.mjs
+git commit -m "test: close Web transport mode coverage"
+```

package/docs/superpowers/plans/2026-08-04-runtime-buffer-gc-two-phase.md

@@ -0,0 +1,71 @@
+# Runtime Buffer GC Two-Phase 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 manual GC use one server-derived timing snapshot, one unified clock decision, a one-shot runtime file apply, and only then an exact database apply.
+
+**Architecture:** The runtime prepares an immutable canonical file plan from a canonical retention period and stores it behind a short-lived root/DB-bound token. The CLI uses the runtime-derived cutoff to capture an exact database plan and merges both plans' would-delete boundaries into one clock observation. Runtime file batches each recheck clock grace under `BEGIN IMMEDIATE`; database rows are finalized only after the runtime reports that every prepared file candidate was processed.
+
+**Tech Stack:** Node.js ESM, `node:sqlite`, synchronous filesystem APIs, built-in test runner, HTTP runtime API.
+
+---
+
+### Task 1: Read-only clock prediction
+
+**Files:**
+- Modify: `lib/core/coordination/clock-safety.mjs`
+- Test: `test/clock-safety.test.mjs`
+
+- [ ] Write a failing test that seeds a watermark, pending gap, and grace row, calls `previewClockSafety`, verifies the same grace decision expected from apply, and compares the complete `meta` table before/after.
+- [ ] Run `node --test test/clock-safety.test.mjs` and verify the missing export fails.
+- [ ] Extract the shared pending-gap decision calculation and implement `previewClockSafety(db, options)` without a transaction or write.
+- [ ] Re-run the focused test and verify preview and observer decisions match while preview leaves `meta` byte-for-byte unchanged.
+
+### Task 2: One-shot runtime plan tokens and bounded apply barriers
+
+**Files:**
+- Create: `lib/runtime/buffer-gc-protocol.mjs`
+- Modify: `lib/runtime/buffer-gc.mjs`
+- Create: `test/buffer-gc-protocol.test.mjs`
+
+- [ ] Write failing tests for token entropy shape, root/DB binding, replay, expiry, mismatch cleanup, and dry-run plans leaving no token.
+- [ ] Write a failing real SQLite/filesystem test with more than 64 frozen candidates; extend grace from a second connection after the first committed batch and assert exactly the first batch is deleted and the remainder deferred.
+- [ ] Implement `createBufferGcPlanStore` with a 15-second TTL and destructive take semantics.
+- [ ] Implement `applyClockSafeBufferPlan` using batches of 64; each batch opens `BEGIN IMMEDIATE`, runs `observeClockSafetyInTransaction`, checks current grace, and performs only that batch's bounded identity rechecks/unlinks before commit.
+- [ ] Re-run the focused protocol tests.
+
+### Task 3: Authenticated prepare/apply API
+
+**Files:**
+- Modify: `bin/hcc.mjs`
+- Modify: `scripts/regression.mjs`
+
+- [ ] Add failing authenticated endpoint regressions: legacy or forged `cutoffMs`/`observedAt` bodies return `BAD_REQUEST`; prepare accepts only canonical safe `retentionSec`; apply rejects replay, wrong root/DB, and expired tokens.
+- [ ] Replace the single-call endpoint with `phase: prepare|apply`. Prepare derives `observedAt` and `cutoffMs` from server time, freezes the full actual-directory plan, and returns counts/cutoffs plus a token only for apply. Apply destructively takes the token and runs the bounded barrier.
+- [ ] Add periodic opportunistic expiry cleanup and verify dry-run preparation stores no token.
+- [ ] Run the endpoint regression through the multi-project runtime workflow.
+
+### Task 4: Manual CLI unified decision and apply ordering
+
+**Files:**
+- Modify: `bin/hcc.mjs`
+- Modify: `lib/core/coordination/gc-plan.mjs`
+- Modify: `scripts/regression.mjs`
+- Test: `test/gc-plan.test.mjs`
+
+- [ ] Add a failing regression with an exact DB history/lock/peer plan plus an actual-directory buffer candidate crossing one pending gap; assert dry-run predicts all would-delete categories deferred without changing `meta`, and apply deletes neither resource.
+- [ ] Add a failing regression where grace is extended after prepare and before apply; assert runtime deletes zero and database finalization never starts.
+- [ ] Add async snapshot cleanup support so the history temp table is always dropped across runtime awaits while preserving primary/cleanup errors.
+- [ ] Split manual GC into prepare, unified preview/observe, runtime/local file apply, and exact DB finalization. Treat runtime unavailability, token failure, incomplete batched apply, subject drift, or clock failure as a barrier that prevents all database deletion.
+- [ ] Ensure result counters report only committed deletes, retain verified-live buffer counts as protected, and report all unprocessed would-delete rows/files as deferred.
+- [ ] Run `node --test test/gc-plan.test.mjs` and the focused manual/runtime regression.
+
+### Task 5: Full verification and amended commit
+
+**Files:**
+- Verify all Task 4 files only.
+
+- [ ] Run `npm run test:unit` and require zero failures.
+- [ ] Run `npm run test:regression` and require `FULL_REGRESSION_OK`.
+- [ ] Rebuild the Node 24 image and run its full regression.
+- [ ] Run `git diff --cached --check`, selectively stage Task 4 files, and amend `f075976` without staging unrelated worktree changes.

package/docs/superpowers/specs/2026-08-03-runtime-safety-design.md

@@ -0,0 +1,117 @@
+# Runtime Safety, Clock, GC, and Registry Design
+
+Status: approved in conversation on 2026-08-03.
+
+## Purpose
+
+Close destructive-operation and ownership races without forcing every project
+to wait after normal idle time. Verified process evidence is authoritative;
+clock grace is reserved for unknown evidence.
+
+## Clock Observation
+
+The meta table stores a last-observed wall-clock watermark and the active grace
+deadline. Observation runs before ownership-changing or destructive operations,
+including lock acquisition, takeover, hook/heartbeat recovery, reaping, and GC.
+Pure read-only commands do not update the watermark, preserving read-only DB
+behavior.
+
+A clock observation transaction:
+
+1. reads the previous watermark and current grace deadline;
+2. evaluates backward movement and long forward gaps;
+3. for ownership operations, checks whether the gap crossed a peer or lock
+   expiry boundary whose owner is currently `unknown`;
+4. for GC, checks whether suspicious backward/forward movement or a long gap
+   crossed the requested age cutoff for any deletion category, independent of
+   owner evidence;
+5. atomically extends grace to `max(existing, now + 120 seconds)` when needed;
+6. writes the new watermark only after the safety decision succeeds.
+
+A verified live owner is renewed immediately from persisted `ttl_sec`. A
+verified dead owner may expire immediately. Only unknown evidence is delayed by
+grace. Failure to persist a required grace blocks the current destructive or
+ownership-changing operation and returns an observable error.
+
+The Web runtime also compares wall-clock movement with its monotonic probe and
+uses the same database transaction. Concurrent probes can extend but never
+shorten grace.
+
+## Grace Semantics
+
+While grace is active, every age-based deletion is deferred:
+
+- expired or apparently expired locks;
+- stale peers and peer bindings;
+- events, completed tasks, messages, and handoffs;
+- buffer files selected only by mtime.
+
+Explicit `exited` peers and artifacts proven dead by identity may still be
+cleaned. Results expose separate `deleted`, `protected`, and `deferred` counts.
+
+## Buffer GC Arbitration
+
+The buffer pruning policy is a shared helper that receives a fixed cutoff,
+dry-run flag, project context, and protected absolute paths. It never recomputes
+the cutoff during a run.
+
+When a healthy compatible runtime exists, manual GC calls an authenticated
+internal API. The runtime computes protection from the actual files referenced
+by its session map and performs synchronous pruning in its event loop. Session
+creation and replacement cannot interleave with that synchronous decision. New
+files created after the fixed cutoff are not eligible.
+
+If a runtime pointer exists but the runtime is unreachable or API-incompatible,
+buffer deletion fails closed and reports deferred files. Safe database cleanup
+may continue.
+
+Without a runtime, local GC protects:
+
+- external file groups whose wrapper or child identity is live or unknown;
+- tmux pipes belonging to verified live or unknown managed panes;
+- any legacy artifact whose ownership cannot be proved dead.
+
+Only old artifacts with definitive dead or orphan evidence are deleted.
+
+## GC Command Contract
+
+`--older-than` must be zero or greater. Invalid values fail before opening a
+write connection or deleting any file.
+
+`hcc gc` remains dry-run by default. `--yes` removes technical state only.
+Business history removal requires both `--history` and `--yes`. Open-task
+handoffs, live-owner records, and unknown session artifacts are never removed
+only because of age. Dry-run and apply execute the same planner.
+
+A WAL checkpoint runs only after successful applied database cleanup. A busy
+checkpoint is reported without converting successful safe cleanup into failure.
+
+## Project Registry Lock
+
+Registry read-modify-write is guarded by an atomic lock directory adjacent to
+`projects.json`. Lock owner metadata includes process identity and creation
+time. Acquisition uses bounded retry. A lock is reclaimed only when its owner is
+definitively dead; unknown ownership times out with an error rather than being
+stolen.
+
+After acquiring the lock, the writer re-reads the registry, merges by canonical
+real root, and writes with the existing atomic temp-and-rename helper. A changed
+DB path updates immediately. The 60-second throttle applies only when root and
+DB are both unchanged.
+
+Authenticated Web users may continue registering arbitrary existing server
+directories. This is an explicitly accepted product risk, not an isolation
+guarantee.
+
+## Acceptance Criteria
+
+- CLI-only wake with a live process renews ownership without a blanket delay.
+- CLI-only wake with unknown evidence enters grace before takeover or GC.
+- A GC after a suspicious clock gap defers age-based history deletion even when
+  no peer or lock candidate exists.
+- Grace never shrinks under concurrent writers.
+- Manual GC preserves live external and tmux artifacts with old mtimes.
+- Unreachable runtime state defers buffer deletion.
+- Negative retention is rejected without mutation.
+- Grace defers every wall-clock-based history deletion.
+- Concurrent registry writers retain both projects and update changed DB paths.

package/docs/superpowers/specs/2026-08-03-v1-data-identity-design.md

@@ -0,0 +1,120 @@
+# hello-cc v1 Data and Identity Design
+
+Status: approved in conversation on 2026-08-03.
+
+## Purpose
+
+Define the breaking v1 data contract, schema migration, process identity model,
+and provider peer identity semantics. This specification intentionally does not
+provide downgrade compatibility or map pre-v1 provider peer IDs to v1 IDs.
+
+## Product Decisions
+
+- Release the result as package version `1.0.0`.
+- Use database schema version 7.
+- A schema v7 database is not supported by pre-v1 binaries.
+- Provider peer IDs use the v1 full-value hash algorithm for every provider ID,
+  including UUIDs and user-defined session names.
+- Pre-v1 peer IDs, tasks, locks, messages, and bindings are not merged into the
+  new v1 identity automatically.
+- Migration must create a consistent database backup before the first v7 write.
+
+## Migration Contract
+
+Before migrating a v5 or v6 database, hello-cc must create a SQLite-consistent
+snapshot next to the source database. The backup name includes the source
+schema version and a collision-resistant timestamp suffix. It must never
+overwrite an existing file.
+
+The backup is produced through the open SQLite connection with `VACUUM INTO`,
+not by copying `mesh.db` while WAL frames may still be pending. Migration stops
+without changing the source database if backup creation or backup integrity
+validation fails. A successful backup is opened read-only and must pass
+`PRAGMA quick_check` before schema migration begins.
+
+Registered sibling projects follow the same contract independently. A failed
+sibling backup or migration is reported and isolated; it must not partially
+migrate that sibling or fail the active project's command.
+
+## Schema v7
+
+Schema v7 adds process identity fields to `peers`:
+
+- `pid_start_token TEXT`: opaque platform-derived process start identity.
+- `pid_command_hash TEXT`: hash of the normalized executable/command identity.
+
+Both fields are nullable. Missing or unreadable identity evidence means
+`unknown`; it never means live or dead.
+
+Existing v6 `locks.ttl_sec` remains required. Invalid or absent historical TTL
+values are repaired to the documented default, capped at one hour when derived
+from historical timestamps.
+
+The schema migration history records v7 exactly once. `doctor` reports the
+current schema, supported schema, backup location when known, and the explicit
+no-downgrade contract.
+
+## Process Identity
+
+A shared process identity helper returns one of:
+
+- a verified identity `{ pid, startToken, commandHash }`;
+- `null` when the process does not exist;
+- `unknown` when the process cannot be inspected safely.
+
+Linux identity combines boot ID, `/proc/<pid>/stat` start ticks, and normalized
+executable identity. macOS identity combines boot time, `ps` process start time,
+PID, and normalized command identity. Inspection failures, permission errors,
+or malformed output return `unknown`.
+
+A stored identity is live only when the current identity matches every stored
+component. A missing PID is dead only when the OS definitively reports that the
+PID does not exist. A reused PID with a different start token or command hash is
+dead for the stored peer.
+
+External session metadata stores separate wrapper and child identities. New
+metadata is written atomically. Legacy metadata without fingerprints is treated
+as unknown unless both referenced PIDs are definitively absent.
+
+tmux identity requires all of the following:
+
+- the managed session name matches the hello-cc naming contract;
+- the pane still exists;
+- `HCC_ROOT` resolves to the expected project root;
+- the pane process identity matches the stored identity when one is available.
+
+## Liveness Precedence
+
+All ownership, lock, reaper, and GC decisions consume one shared resolver with
+the result `live`, `dead`, or `unknown`.
+
+1. Explicit administrative `exited` status is dead.
+2. Verified tmux or process identity is live.
+3. `detached` is not dead by itself; a detached tmux session may still be live.
+4. Definitive process absence plus definitive tmux absence is dead.
+5. Conflicting, missing, legacy, or unreadable evidence is unknown.
+
+Wall-clock age never overrides verified live or dead evidence.
+
+## Provider Peer IDs
+
+JavaScript and generated shims derive the same first eight lowercase SHA-1 hex
+characters from the complete provider ID. Hash output is accepted only when it
+is exactly 40 lowercase hexadecimal characters. When no supported hash command
+can produce a valid digest, a shim starts the real provider without hello-cc
+coordination rather than creating an ambiguous ID.
+
+The v1 release notes must show examples of old and new IDs and explain that old
+coordination history remains queryable in the backup but is not attached to the
+new peer automatically.
+
+## Acceptance Criteria
+
+- A v5 and a development v6 fixture each produce a validated backup and migrate
+  once to v7.
+- A forced backup failure leaves the source schema and data unchanged.
+- A pre-v1 binary rejects v7 with the documented error.
+- PID reuse is classified as dead for the stored identity.
+- A live tmux pane remains live across sleep-sized wall-clock gaps.
+- A detached but live tmux session is not made takeover-ready.
+- JavaScript and every generated shim produce identical v1 peer IDs.