@logicseek/hello-cc 0.1.8 → 1.0.0

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"
+```

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.