@logicseek/hello-cc 0.1.9 → 1.0.0

package/docs/superpowers/plans/2026-08-03-v1-release-verification-plan.md

@@ -0,0 +1,284 @@
+# hello-cc v1 Release and Verification 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:** Convert the completed hardening into a coherent 1.0.0 release with controlled fatal shutdown, complete packaging, accurate documentation, stable tests, and fresh cross-platform evidence.
+
+**Architecture:** A focused fatal-shutdown helper owns process-level failure behavior. Release metadata and documentation declare breaking changes and accepted risks. Verification audits the entire local delta against `origin/master`, not only the last patch.
+
+**Tech Stack:** Node.js 24 ESM, npm packaging, Docker/BuildKit, tmux, SQLite, HTTP/HTTPS/WebSocket regression suite.
+
+---
+
+## File Map
+
+- Create `lib/runtime/fatal-shutdown.mjs` and `test/fatal-shutdown.test.mjs`.
+- Modify `bin/hcc.mjs` fatal handlers and shutdown orchestration.
+- Modify `package.json`, `package-lock.json`, `CHANGELOG.md`.
+- Modify root and `docs/` English/Chinese README, commands, and guide files.
+- Modify `docs/defect-review-2026-07.md` status evidence.
+- Track/modify `.dockerignore`, `Dockerfile`, `lib/shared/clock-grace.mjs`, `lib/web/tls.mjs`.
+- Modify `scripts/regression.mjs` for deterministic TTL evidence and package audits.
+
+### Task 1: Replace unknown-error survival with idempotent fatal shutdown
+
+**Files:**
+- Create: `lib/runtime/fatal-shutdown.mjs`
+- Create: `test/fatal-shutdown.test.mjs`
+- Modify: `bin/hcc.mjs:5190-5335`
+
+- [ ] **Step 1: Write failing fatal-state tests**
+
+Use a real `EventEmitter` as the process signal source and real promises for asynchronous cleanup. Do not mock cleanup behavior; provide complete callbacks that append observable events.
+
+```js
+const events = [];
+const controller = createFatalShutdownController({
+  cleanup: async (reason) => { events.push(`cleanup:${reason}`); },
+  exit: (code) => { events.push(`exit:${code}`); },
+  forceExit: (code) => { events.push(`force:${code}`); },
+  log: (value) => { events.push(`log:${value.code}`); }
+});
+
+await controller.fatal(new Error('first'));
+await controller.fatal(new Error('second'));
+assert.deepEqual(events, ['log:FATAL_RUNTIME_ERROR', 'cleanup:first', 'exit:1', 'force:1']);
+```
+
+Also assert cleanup failure still exits nonzero and its log is redacted.
+
+- [ ] **Step 2: Run to verify RED**
+
+Run: `node --test test/fatal-shutdown.test.mjs`.
+
+Expected: missing-module failure.
+
+- [ ] **Step 3: Implement the controller and wire Web shutdown**
+
+```js
+export function createFatalShutdownController({ cleanup, exit, forceExit, log }) {
+  let state = 'idle';
+  return {
+    async fatal(error) {
+      if (state !== 'idle') {
+        forceExit(1);
+        return;
+      }
+      state = 'stopping';
+      log({ code: 'FATAL_RUNTIME_ERROR', error });
+      try { await cleanup(error?.message || 'fatal runtime error'); }
+      catch (cleanupError) { log({ code: 'FATAL_CLEANUP_ERROR', error: cleanupError }); }
+      state = 'stopped';
+      exit(1);
+    }
+  };
+}
+```
+
+In `cmdWeb`, create one controller after all owned resources exist. `uncaughtException` and `unhandledRejection` call it. Cleanup clears timers/watchers, closes WebSockets/server, detaches or exits sessions by existing semantics, closes DB resources, and clears only runtime pointers matching the current process identity. Remove the log-and-continue handlers.
+
+- [ ] **Step 4: Verify GREEN at unit and child-process boundaries**
+
+Run unit tests. Add a child-process fixture that imports the helper, opens a temporary server/resource, triggers an unhandled rejection, and asserts cleanup marker, closed listener, and exit status 1.
+
+Run: `npm run test:unit`.
+
+Run: `npm run test:regression`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add lib/runtime/fatal-shutdown.mjs test/fatal-shutdown.test.mjs bin/hcc.mjs scripts/regression.mjs
+git commit -m "fix: terminate cleanly after fatal runtime errors"
+```
+
+### Task 2: Publish the breaking 1.0.0 contract in metadata and docs
+
+**Files:**
+- Modify: `package.json:3,24-32`
+- Modify: `package-lock.json`
+- Modify: `CHANGELOG.md`
+- Modify: `README.md`, `README.zh-CN.md`
+- Modify: `docs/README.md`, `docs/README.zh-CN.md`
+- Modify: `docs/commands.md`, `docs/commands.zh-CN.md`
+- Modify: `docs/guide.md`, `docs/guide.zh-CN.md`
+- Modify: `docs/defect-review-2026-07.md`
+- Modify: `lib/ui/help.mjs`
+
+- [ ] **Step 1: Add failing release-document assertions**
+
+Extend `syntaxAndHelp` and release checks to require all of these concepts in
+`README.md`, `README.zh-CN.md`, `docs/commands.md`,
+`docs/commands.zh-CN.md`, `docs/guide.md`, `docs/guide.zh-CN.md`, the changelog,
+and CLI help:
+
+```text
+1.0.0
+schema v7 / no downgrade
+pre-migration backup
+Runtime API v2
+provider peer IDs changed
+gc --history
+process evidence / unknown-only grace
+--tls and --trust-proxy
+plaintext LAN accepted risk
+arbitrary authenticated project root accepted risk
+```
+
+Assert the defect report uses the actual current branch dynamically or avoids naming a branch, and that fixed/partial/deferred counts add up to the listed findings.
+
+- [ ] **Step 2: Run to verify RED**
+
+Run: `npm run test:regression`.
+
+Run: `npm run release:check`.
+
+Expected: FAIL on version and missing release/help documentation.
+
+- [ ] **Step 3: Update release metadata and documentation**
+
+Set `package.json` version to `1.0.0`, then run:
+
+```bash
+npm install --package-lock-only --ignore-scripts --no-audit --no-fund
+```
+
+Add one coherent 1.0.0 changelog section with Breaking, Security, Reliability, GC, and Upgrade headings. Document exact backup naming and recovery inspection, no downgrade, old/new peer ID examples, API v2 negotiation, safe GC flags, supported transport modes, and the two accepted risks.
+
+Update help text without claiming plaintext confidentiality or project isolation. Correct defect statuses from current tests and code evidence.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run: `npm run test:regression`.
+
+Run: `npm run release:check`.
+
+Run: `node ./bin/hcc.mjs --help`.
+
+Expected: all release assertions PASS and version/help output is 1.0.0.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add package.json package-lock.json CHANGELOG.md README.md README.zh-CN.md docs/README.md docs/README.zh-CN.md docs/commands.md docs/commands.zh-CN.md docs/guide.md docs/guide.zh-CN.md docs/defect-review-2026-07.md lib/ui/help.mjs scripts/regression.mjs
+git commit -m "docs: publish hello-cc 1.0.0 contract"
+```
+
+### Task 3: Make packaging complete and TTL regression deterministic
+
+**Files:**
+- Track/modify: `.dockerignore`
+- Track/modify: `Dockerfile`
+- Track: `lib/shared/clock-grace.mjs`
+- Track: `lib/web/tls.mjs`
+- Modify: `scripts/regression.mjs:164-185,2730-2820,7072-7115`
+- Modify: `package.json:10-22`
+
+- [ ] **Step 1: Add failing package-completeness and TTL tests**
+
+Add a package audit that runs `npm pack --dry-run --json`, parses the file list, resolves every relative import reachable from `bin/hcc.mjs`, and asserts every production dependency is tracked and included in the package.
+
+Change hook renewal event payload assertions to require a `renewed_at` timestamp. Seed a fixture where parent `before` is one second greater than child `renewed_at` and assert expiration equals `renewed_at + renewalSec`, not a cross-process before/after window.
+
+- [ ] **Step 2: Run to verify RED**
+
+Run: `npm run test:regression`.
+
+Expected: FAIL because renewal events lack `renewed_at` and current package audit sees untracked production modules.
+
+- [ ] **Step 3: Record operation time and complete packaging**
+
+Include `renewed_at: hookNow` in `lock.renewed_by_hook` payload and assert exact TTL from that value. Keep created time and `ttl_sec` invariants.
+
+Track all imported production modules. Ensure package `files` includes every `lib/` module. Change Docker dependency install to:
+
+```dockerfile
+RUN npm ci --no-audit --no-fund
+```
+
+At test startup print `node --version` and `tmux -V`. Keep `.git`, runtime state, tokens, DBs, WAL files, logs, and local buffers out of the build context; do not exclude production source.
+
+- [ ] **Step 4: Verify GREEN and repeatability**
+
+Run: `npm run test:regression` twice locally.
+
+Run: `npm pack --dry-run --json` and inspect the parsed audit result.
+
+Build and run the container twice at this task boundary. Both runs must reach `FULL_REGRESSION_OK`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add .dockerignore Dockerfile lib/shared/clock-grace.mjs lib/web/tls.mjs scripts/regression.mjs package.json
+git commit -m "test: make v1 package and regression deterministic"
+```
+
+### Task 4: Execute the final ordered verification gates
+
+**Files:**
+- Review: every path in `git diff --name-only origin/master`
+- Modify only when a failed gate identifies a defect, using a new RED-GREEN cycle.
+
+- [ ] **Step 1: Audit final scope and production imports**
+
+Run:
+
+```bash
+git status --short
+git diff --check origin/master
+git diff --stat origin/master
+git diff --name-status origin/master
+npm pack --dry-run --json
+```
+
+Expected: no untracked production dependency; no whitespace errors; package audit lists every reachable module.
+
+- [ ] **Step 2: Run syntax, unit, and focused security checks**
+
+Run:
+
+```bash
+node --check bin/hcc.mjs
+node --check scripts/regression.mjs
+npm run test:unit
+npm run smoke
+npm run release:check
+```
+
+Expected: exit 0 for every command with zero test failures.
+
+- [ ] **Step 3: Re-run original vulnerable paths and bypass controls**
+
+Run focused selectors or fixtures for negative GC, live-buffer manual GC, CLI-only clock gap, concurrent registry writers, PID reuse, API v1/missing version, cross-session tokens, symlink escape, secret log scanning, and fatal shutdown.
+
+Expected: original unsafe behavior no longer reproduces; legitimate live/dead/admin/arbitrary-root/plaintext-LAN controls remain intact.
+
+- [ ] **Step 4: Run complete local regression**
+
+Run: `npm test`.
+
+Expected: unit tests PASS and regression ends with `FULL_REGRESSION_OK`.
+
+- [ ] **Step 5: Build the exact current Node 24/Linux image**
+
+Run:
+
+```bash
+docker build --no-cache -t hello-cc-v1-verify:node24 .
+```
+
+Expected: successful build using `npm ci`, with all current source copied.
+
+- [ ] **Step 6: Run three consecutive container regressions**
+
+Run `docker run --rm hello-cc-v1-verify:node24` three separate times. Do not combine them in a shell loop; preserve each output independently.
+
+Expected for each run: `FULL_REGRESSION_OK`, no TTL clock-window failure, no leaked tmux session, exit 0.
+
+- [ ] **Step 7: Review the complete delta and requirements**
+
+Read all four design specs and map every acceptance criterion to a passing command or test. Review `git diff origin/master` for alternate unsafe branches, duplicated policy logic, accidental user-change loss, secrets, stale documentation, and unrelated churn.
+
+- [ ] **Step 8: Commit only evidence-required final corrections**
+
+If every gate passed without a correction, do not create an empty commit. If a gate required a fix, use a focused commit containing its failing test and minimal production correction.

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.