@logicseek/hello-cc 1.0.0 → 1.0.1

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

@@ -1,303 +0,0 @@
-# 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

@@ -1,71 +0,0 @@
-# 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

@@ -1,117 +0,0 @@
-# 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

@@ -1,120 +0,0 @@
-# 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.