mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-10 23:19:09 +02:00
docs: sync every doc surface with the v1.63 release
/document-release audit (4-lane, all claims verified against branch code): - README: gstack-egress + gstack-context-bill rows in the standalone-binaries table; Privacy & Telemetry gains the receipted-egress bullet (attempted- egress framing per the shipped threat model). - ARCHITECTURE: /health is liveness-only, POST /extension-token endpoint row + bootstrap mechanics paragraph; new Egress receipt ledger subsection under Security model; eval persistence covers the sharded runner, GSTACK_EVAL_DIR, and the finalized-run baseline rule. - CLAUDE.md: sharded test scripts in Commands; sharded semantics in the detached-evals section; PTY skill seeding in the hermetic section; egress invariant block beside the other server-egress invariants; catalog-budget ceiling beside the 160KB token ceiling; project-tree entries for lib/egress-receipt.ts, lib/context-bill.ts, scripts/test-paid-shards.ts. - CONTRIBUTING: seedSkills + live-tree seeding in the hermetic paragraph; sharded runner in detached runs; catalog-budget in the Tier 1 list. - BROWSER: extension token bootstrap section, tunnel egress receipts section, identity-pin migration note in manual install. - REMOTE_BROWSER_ACCESS: tunnel-start receipt bullet in the security model. - gbrain docs: /sync-gbrain + brain-sync egress-receipt behavior documented; dead consumer-token instructions removed (consumer machinery deleted this release); new fail-closed refusal added to the error catalog. - CHANGELOG: measured-vs-ceiling catalog numbers, contributor notes for the external-service tier move and the PTY single-line AskUserQuestion parser, release date. - TODOS: /health token-distribution TODO resolved by this release, removed; port-wave follow-up sections re-labeled to the shipped version. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Fable 5
parent
562273d793
commit
e7110aac93
@@ -179,6 +179,7 @@ Each agent owns the tabs it creates. Rules:
|
||||
- **Path traversal guarded** on `/welcome` — `GSTACK_SLUG` must match `^[a-z0-9_-]+$` or falls back to the built-in template.
|
||||
- **SSRF guards** on `goto`, `download`, and scrape paths — validates URL target against a localhost/private-range blocklist.
|
||||
- **Tunnel surface denial logging.** Every rejection on the tunnel listener (`path_not_on_tunnel`, `root_token_on_tunnel`, `missing_scoped_token`, `disallowed_command:*`) is appended to `~/.gstack/security/attempts.jsonl` with timestamp, source IP, path, method. Rate-capped at 60 writes/min.
|
||||
- **Egress receipt on tunnel start (v1.63+).** Every tunnel session open writes a hash-chained receipt (sink `browse-tunnel`) to `~/.gstack/security/egress.jsonl` BEFORE ngrok forwards anything. Fail-closed: if the receipt can't be written, the tunnel refuses to start. Audit with `bin/gstack-egress list` / `bin/gstack-egress verify`.
|
||||
- All agent activity is logged with attribution (clientId).
|
||||
|
||||
**Known non-goal (tracked as #1136):** on Windows, the cookie-import-browser path launches Chrome with `--remote-debugging-port=<random>`. With App-Bound Encryption v20, a same-user local process can connect to that port and exfiltrate decrypted v20 cookies — an elevation path relative to reading the SQLite DB directly. Fix direction is `--remote-debugging-pipe` instead of TCP.
|
||||
|
||||
@@ -92,6 +92,29 @@ your local commit still exists — the next skill run will retry the push.
|
||||
|
||||
---
|
||||
|
||||
## `gstack: brain-sync push NOT sent — the egress receipt could not be written`
|
||||
|
||||
**Problem.** The push was refused before anything left your machine. Every
|
||||
brain-sync push writes a tamper-evident receipt to the egress ledger
|
||||
(`~/.gstack/security/egress.jsonl`) before sending, fail-closed. The
|
||||
receipt could not be written, so nothing was sent, no local commit was
|
||||
made, and the queue is preserved — the next run retries the whole drain.
|
||||
`gstack-brain-sync --status` shows `EGRESS_RECEIPT_FAILED` as the failure
|
||||
detail.
|
||||
|
||||
**Cause.** `~/.gstack/security/` is missing or unwritable, the disk is
|
||||
full, or `GSTACK_HOME` points at a read-only location.
|
||||
|
||||
**Fix.**
|
||||
```bash
|
||||
chmod -R u+w ~/.gstack/security
|
||||
```
|
||||
Then run any skill (or `gstack-brain-sync --once`) to retry. Inspect the
|
||||
ledger with `gstack-egress list`; verify its hash chain with
|
||||
`gstack-egress verify`.
|
||||
|
||||
---
|
||||
|
||||
## `gstack-brain-init: ~/.gstack/.git is already a git repo pointing at <url>`
|
||||
|
||||
**Problem.** You tried to init with a remote URL that doesn't match the
|
||||
|
||||
+8
-4
@@ -18,7 +18,7 @@ GBrain.
|
||||
By design, these stay local even when sync is on:
|
||||
|
||||
- Credentials: `.auth.json`, `auth-token.json`, `sidebar-sessions/`,
|
||||
`security/device-salt`, consumer tokens in `config.yaml`
|
||||
`security/device-salt`
|
||||
- Machine-specific state: Chromium profiles, ONNX model weights,
|
||||
caches, eval-cache, CDP-profile, one-time prompt markers
|
||||
(`.welcome-seen`, `.telemetry-prompted`, `.vendoring-warned-*`, etc.)
|
||||
@@ -80,9 +80,7 @@ On machine B:
|
||||
```
|
||||
3. Run `gstack-brain-restore`. That clones the repo, rehydrates your
|
||||
learnings/plans/retros, and re-registers the git merge drivers.
|
||||
4. Re-enter consumer tokens (they're machine-local and NOT synced —
|
||||
`gstack-config set gbrain_token <your-token>`).
|
||||
5. Next skill: your yesterday-on-machine-A learning surfaces. That's the
|
||||
4. Next skill: your yesterday-on-machine-A learning surfaces. That's the
|
||||
magical moment.
|
||||
|
||||
## Status, health, and queue depth
|
||||
@@ -141,6 +139,12 @@ To remediate:
|
||||
There's a defense-in-depth hook at `~/.gstack/.git/hooks/pre-commit` that
|
||||
runs the same scan if you manually `git commit` against the repo.
|
||||
|
||||
Separately (v1.63.0.0+), every push writes a tamper-evident receipt to the
|
||||
egress ledger (`~/.gstack/security/egress.jsonl`) *before* anything is
|
||||
sent, fail-closed: if the receipt can't be written, the push is refused
|
||||
and the queue is preserved. Inspect the ledger with `gstack-egress list`
|
||||
and verify its hash chain with `gstack-egress verify`.
|
||||
|
||||
## Two-machine conflicts
|
||||
|
||||
If you write on machine A and machine B the same day, both will push
|
||||
|
||||
Reference in New Issue
Block a user