@logicseek/hello-cc 0.1.9 → 1.0.0

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.

package/docs/superpowers/specs/2026-08-03-v1-release-verification-design.md

@@ -0,0 +1,117 @@
+# hello-cc v1 Release and Verification Design
+
+Status: approved in conversation on 2026-08-03.
+
+## Purpose
+
+Define code ownership boundaries, fatal error behavior, packaging, documentation,
+and evidence required before the remaining hardening work can be called complete.
+
+## Module Boundaries
+
+New focused modules own these policies:
+
+- process identity inspection and comparison;
+- clock observation and liveness resolution;
+- project registry locking;
+- buffer GC planning and arbitration;
+- Runtime API version negotiation;
+- secret redaction.
+
+`bin/hcc.mjs` remains the command and runtime orchestrator. It calls these
+modules but does not duplicate their decision logic. Existing repository
+patterns are retained; unrelated restructuring is out of scope.
+
+Every imported production module must be tracked and included by the package
+`files` contract. Docker test files are tracked but remain outside the npm
+package.
+
+## Fatal Error Behavior
+
+Expected poller, watcher, sibling-project, and transient runtime failures are
+caught at their ownership boundary, logged with redaction, and isolated.
+
+An uncaught exception or unhandled rejection initiates one idempotent fatal
+shutdown. Shutdown stops timers and watchers, closes sessions and sockets using
+the documented detach/exit semantics, clears only runtime pointers owned by the
+current process identity, closes the server and database resources, then exits
+nonzero. The runtime must not continue after an unknown exception.
+
+A second fatal signal during shutdown forces termination without attempting a
+second cleanup pass.
+
+## Release Contract
+
+The package version becomes `1.0.0`. Changelog, README files, bilingual command
+documentation, help output, and the defect review describe:
+
+- schema v7 and no downgrade support;
+- the pre-migration backup;
+- provider peer ID changes;
+- Runtime API v2 and session token delivery changes;
+- safe GC defaults and `--history`;
+- process-evidence-first liveness and unknown-only grace;
+- optional TLS and trusted proxy usage;
+- accepted plaintext LAN and arbitrary-root risks.
+
+The defect report uses evidence-backed status counts and the actual branch. It
+must not label accepted risks or partial controls as completely fixed.
+
+The Dockerfile uses `npm ci`, records Node and tmux versions in test output, and
+builds from the complete current source tree. `.dockerignore` excludes host
+runtime state and secrets without excluding production source.
+
+## Test Architecture
+
+Pure policies use Node's built-in test runner in focused test files. Real CLI,
+SQLite, tmux, HTTP, HTTPS, and WebSocket boundaries remain integration tests.
+Tests do not add production-only backdoors or test-only public APIs.
+
+Each behavior change follows red-green-refactor:
+
+1. add the smallest regression that demonstrates the missing invariant;
+2. run it and record the expected failure;
+3. implement the minimum production change;
+4. rerun the focused test and relevant neighboring tests;
+5. refactor only while green.
+
+Required regressions cover:
+
+- v5/v6 backup and migration failure atomicity;
+- PID reuse and platform process inspection;
+- live, dead, and unknown tmux/external peers;
+- CLI-only sleep-sized gaps and concurrent grace writers;
+- manual/automatic GC, negative retention, history opt-in, and runtime failure;
+- concurrent registry writers and same-root DB changes;
+- API v2, cookie lifecycle, action-token scope, CSP, and redaction;
+- realpath and symlink containment;
+- fatal shutdown cleanup;
+- package content and tracked-file completeness.
+
+TTL renewal tests use the renewal operation's recorded timestamp rather than
+assuming wall-clock readings in separate processes are monotonic. This retains
+strict TTL inflation checks without the observed one-second container flake.
+
+## Verification Gates
+
+Completion requires fresh evidence, in this order:
+
+1. final diff and tracked production import audit;
+2. syntax/import/package-content checks;
+3. focused unit and security regression tests;
+4. original vulnerable-path reproductions and alternate bypass inputs;
+5. preserved legitimate behavior tests;
+6. complete local regression;
+7. a freshly built Node 24/Linux image;
+8. three consecutive complete container regressions;
+9. final `origin/master..worktree` review and documentation consistency check.
+
+A failed gate blocks a completion claim. Accepted risks are reported separately
+and are not represented as test gaps or fixed findings.
+
+## Definition of Done
+
+The work is complete only when every approved non-accepted-risk requirement in
+the four v1 design specifications has a passing test or a documented reason the
+check is inapplicable, all required verification gates pass, and the final
+working tree contains no untracked production dependency.

package/docs/superpowers/specs/2026-08-03-web-api-hardening-design.md

@@ -0,0 +1,104 @@
+# Web and Runtime API v2 Hardening Design
+
+Status: approved in conversation on 2026-08-03.
+
+## Purpose
+
+Define the v1 Web authentication, Runtime API v2, browser policy, path safety,
+and log-redaction contract while preserving two explicitly accepted risks.
+
+## Accepted Risks
+
+- The default Web listener remains `0.0.0.0` over HTTP for LAN access.
+- An authenticated administrator may select any existing server project root.
+
+These choices permit passive LAN observation of HTTP traffic and broad access
+to server project directories by anyone holding the administrator credential.
+Documentation must state these risks and must not mark transport confidentiality
+or project scoping as fully remediated.
+
+## Authentication Roles
+
+The stable runtime token is the administrator credential. An HttpOnly browser
+cookie issued after successful token login represents the same administrator
+role. Both may create, stop, attach, and inject managed sessions.
+
+A session action token is narrower. It authorizes terminal WebSocket input for
+one managed session and is delivered only in that session's terminal snapshot.
+It is never returned by the session list. Session action token comparisons use
+the shared constant-time token helper.
+
+Cookie sessions have a server-side expiry, a bounded count, explicit logout,
+and tracked WebSocket membership. Expiry, eviction, or logout closes associated
+WebSockets immediately. Cookie-authenticated mutations require a same-origin
+request.
+
+Non-loopback listeners require a non-empty administrator token. Tokenless mode
+is accepted only from a loopback socket.
+
+## Runtime API v2
+
+Runtime metadata advertises API version 2. CLI and browser HTTP requests send
+`X-HCC-API-Version: 2`. Browser WebSocket handshakes send `api_version=2` in the
+query because the WebSocket browser API cannot set an arbitrary request header.
+Protected API requests with a missing or unsupported version receive HTTP 426
+with `API_VERSION_UNSUPPORTED` and the supported version.
+
+Public login and static bootstrap routes remain reachable without the API
+version header. The v1 release notes identify removal of `action_token` from
+`GET /api/sessions` as a breaking API change.
+
+## Browser Policy
+
+HTML responses use a per-response nonce. The Content Security Policy permits
+scripts only from self and the response nonce, denies objects and framing,
+restricts base URIs, and permits only the same-origin HTTP/WebSocket connections
+needed by the console. Styles allow the current xterm and inline-style contract;
+script policy must not require `unsafe-inline`.
+
+Responses retain no-store, no-referrer, and nosniff headers. Secure requests may
+add transport-only headers without applying HSTS to accepted plaintext mode.
+
+## Path Safety
+
+Arbitrary existing roots remain supported, but lexical containment is not
+enough. The selected root is canonicalized with `realpath`. The `.hello-cc`
+directory is created with owner-only permissions when absent and canonicalized
+when present. A symlinked `.hello-cc` or DB parent that resolves outside the
+canonical state directory is rejected.
+
+The selected database must resolve to `mesh.db` or another path below the real
+`.hello-cc` directory. Pseudo-files, non-regular database targets, and symlink
+escapes are rejected before SQLite opens the target.
+
+## TLS and Proxy Modes
+
+Direct `--tls` mode validates certificate dates, SAN coverage, key pairing, file
+permissions, and generation publication before listening. CLI requests trust
+only the runtime's stored self-signed certificate.
+
+`--trust-proxy --proxy-origin https://host[:port]` accepts forwarded host/proto
+only from a loopback peer and only when both exactly match the pinned public
+origin. Either option without the other is rejected. Forwarded headers from any
+non-loopback peer are ignored. Cookie `Secure` state and origin checks consume
+the same trusted-proxy decision.
+
+## Secret Redaction
+
+All startup and error logging passes through one redactor. It removes or replaces
+values for `--token`, Authorization, cookies, session action tokens, runtime
+tokens, and URL `token` query parameters. The redactor handles both structured
+objects and command-line strings. Runtime pointer files remain owner-readable
+only because local CLI operation requires the administrator token.
+
+## Acceptance Criteria
+
+- Old or missing API versions receive 426 on protected API routes.
+- Admin token and admin cookie retain documented management behavior.
+- Session action tokens are absent from lists and required for WS input.
+- Logout and expiry close existing cookie-authenticated WebSockets.
+- CSP blocks an injected inline script without the nonce.
+- Logs contain no supplied administrator, cookie, or session token value.
+- Symlink DB escape is rejected while a normal arbitrary project root works.
+- Direct TLS, loopback trusted proxy, and accepted plaintext LAN modes pass
+  independent integration tests.