Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

docs: the skill's CLI command reference documents no cookies verb at all, and SKILL.md still routes an agent to 'state' to read cookies (PIN-259)

Luigi Agostid4a198e91028
diff --git a/cmd/pinchtab/cmd_cli_docs_test.go b/cmd/pinchtab/cmd_cli_docs_test.go
new file mode 100644
index 00000000..8fb3116c
--- /dev/null
+++ b/cmd/pinchtab/cmd_cli_docs_test.go
@@ -0,0 +1,119 @@
+package main
+
+import (
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+)
+
+func readSkillFile(t *testing.T, parts ...string) string {
+ t.Helper()
+ path := filepath.Join(append([]string{"..", "..", "skills", "pinchtab"}, parts...)...)
+ raw, err := os.ReadFile(path)
+ if err != nil {
+ t.Fatalf("cannot read %s, so this guard would cover nothing: %v", path, err)
+ }
+ return string(raw)
+}
+
+// documentsNamespace reports whether the CLI reference gives a namespace its own
+// section. Headings carry the command's argument form ("### `pinchtab nav <url>`"), so
+// the name is matched with either a closing backtick or a following space — a mention
+// inside another command's prose does not count.
+func documentsNamespace(reference, name string) bool {
+ return strings.Contains(reference, "### `pinchtab "+name+"`") ||
+ strings.Contains(reference, "### `pinchtab "+name+" ")
+}
+
+// The defect this guard is derived from is a CROSS-SURFACE asymmetry, not incompleteness:
+// an agent reading the skill could discover cookie setting over MCP and over raw HTTP,
+// but not the CLI verb built for it — and for reading was sent to `state`, the command
+// whose help no longer claims cookies as its job. The CLI is the token-cheap surface the
+// skill steers agents toward, so a namespace present on the other two surfaces and absent
+// here sends the agent to curl.
+//
+// Deliberately NOT "every namespace must be documented": measured against the tree, the
+// CLI reference is a curated subset (roughly a third of the leaf verbs have no section),
+// so that rule would assert a contract this repo does not have and would red for a dozen
+// commands no card was filed about. Cross-surface parity is the narrower claim that is
+// actually true and actually the defect.
+//
+// knownCrossSurfaceGaps is checked in BOTH directions, so it cannot go quiet: a NEW gap
+// reds, and an entry whose namespace has since been documented reds as stale. Every entry
+// carries what a reader needs to close it.
+func TestNoNamespaceIsDocumentedOnAnotherSurfaceButMissingFromTheCLIReference(t *testing.T) {
+ reference := readSkillFile(t, "references", "commands.md")
+ mcp := readSkillFile(t, "references", "mcp.md")
+ api := readSkillFile(t, "references", "api.md")
+
+ knownCrossSurfaceGaps := map[string]string{
+ "keyboard": "key-sequence verbs; documented on the MCP surface only — same class as the cookies gap, unfixed",
+ "dialog": "JS-dialog handling; documented on the MCP surface only — same class as the cookies gap, unfixed",
+ "state": "SKILL.md carries the state rules and the sensitivity warning inline, so the namespace is reachable there; a commands.md section is still owed",
+ }
+
+ namespaces := 0
+ for _, cmd := range browserRootCommands() {
+ if len(cmd.Commands()) == 0 {
+ continue // a leaf verb is its own name; a namespace hides verbs an agent cannot guess
+ }
+ name := cmd.Name()
+ namespaces++
+ if documentsNamespace(reference, name) {
+ if reason, stale := knownCrossSurfaceGaps[name]; stale {
+ t.Errorf("`pinchtab %s` IS documented in the CLI reference now, but is still recorded as a known gap (%q); drop the entry so the guard keeps meaning what it says", name, reason)
+ }
+ continue
+ }
+ onAnotherSurface := strings.Contains(mcp, "pinchtab_"+name) || strings.Contains(api, "/"+name)
+ if !onAnotherSurface {
+ continue
+ }
+ if reason, ok := knownCrossSurfaceGaps[name]; ok {
+ if reason == "" {
+ t.Errorf("`pinchtab %s` is recorded as a known gap with no reason; every entry is a decision", name)
+ }
+ continue
+ }
+ t.Errorf("`pinchtab %s` is documented on the MCP or HTTP surface but has no `### `+\"`\"+`pinchtab %s`+\"`\"+` section in skills/pinchtab/references/commands.md, so an agent can discover the operation everywhere except on the surface the skill steers it toward. Add the section in the file's house style, or record it in knownCrossSurfaceGaps with the reason",
+ name, name)
+ }
+ if namespaces < 8 {
+ t.Fatalf("only %d namespaces reached this guard; the command list is not being read and it would pass vacuously", namespaces)
+ }
+}
+
+// The routing half of the same defect: the skill sent an agent to `state` to read a
+// cookie, which is precisely the misfiling the cookies namespace removed from the CLI
+// help. Both surfaces must name the command that actually reads one.
+func TestTheSkillRoutesCookieReadsAtTheCookiesCommand(t *testing.T) {
+ for _, parts := range [][]string{{"SKILL.md"}, {"references", "commands.md"}} {
+ name := filepath.Join(parts...)
+ text := readSkillFile(t, parts...)
+ if !strings.Contains(text, "pinchtab cookies get") {
+ t.Errorf("%s never names `pinchtab cookies get`, so an agent reading it cannot find the command that reads a cookie", name)
+ }
+ }
+}
+
+// The browser-wide blast radius of `cookies clear` is pinned on the CLI side, and a doc
+// that omits it teaches an agent to reach for a command that will log the user out of
+// every site. The reference must not contradict the help it mirrors.
+func TestTheCookiesReferenceStatesTheBrowserWideClearEffect(t *testing.T) {
+ reference := readSkillFile(t, "references", "commands.md")
+ // storage is pinned DIRECTLY rather than by the cross-surface rule above, and the
+ // reason is measured: it has no MCP tool and no /storage HTTP route, so nothing on
+ // another surface documents it and the derived rule cannot reach it. Removing its
+ // section leaves that guard green — this assertion is what notices.
+ for _, name := range []string{"cookies", "storage"} {
+ if !documentsNamespace(reference, name) {
+ t.Fatalf("the %s section is gone, so this guard is pinning nothing", name)
+ }
+ }
+ for _, want := range []string{"all origins", "cannot be scoped"} {
+ if !strings.Contains(reference, want) {
+ t.Errorf("the CLI reference never says %q about `cookies clear`; its own --help does, and the doc must not read as narrower than the command is", want)
+ }
+ }
+}
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.md
index 10ae3ed7..8e903405 100644
--- a/skills/pinchtab/SKILL.md
+++ b/skills/pinchtab/SKILL.md
@@ -147,7 +147,8 @@ All subsequent commands use that session's dedicated tab automatically — no `-
State commands are sensitive and only belong in a user-approved diagnostics workflow:
-- `pinchtab state [--tab <id>]` or `GET /state` — full gated browser state for one tab: cookies, current-origin storage, metadata, and tab info. Never print or forward the result.
+- `pinchtab cookies get [--name <name>] [--tab <id>]` — read cookies for the tab's current URL. This is the command for cookies; `cookies set` writes one and `cookies clear` removes every cookie in the browser, all origins. Requires `security.allowCookies`.
+- `pinchtab state [--tab <id>]` or `GET /state` — the whole gated state SNAPSHOT for one tab: cookies, current-origin storage, metadata, and tab info together. Reach for it when you need the snapshot, not to read one cookie. Never print or forward the result.
- `GET /tabs/{id}/state` — lightweight live tab/page runtime state for readiness, dialog blocking, and actionability checks.
### Observation
diff --git a/skills/pinchtab/references/commands.md b/skills/pinchtab/references/commands.md
index 2966abbd..512fc566 100644
--- a/skills/pinchtab/references/commands.md
+++ b/skills/pinchtab/references/commands.md
@@ -250,6 +250,59 @@ pinchtab network <requestId> --body
---
+## State Commands
+
+### `pinchtab cookies`
+Read, set and clear browser cookies for the tab you are driving. Reach for `cookies get` to read a cookie — not `state`, which returns the whole gated state snapshot.
+
+```bash
+pinchtab cookies get # cookies visible to the tab's current URL, with values
+pinchtab cookies get --name session # one cookie
+pinchtab cookies get --url https://example.com # read another origin
+pinchtab cookies set session abc123 # reuse a session without replaying a saved state
+pinchtab cookies set session "" # blank the value without deleting the cookie
+pinchtab cookies clear # every cookie in the browser, all origins
+```
+
+| Flag | Command | Description |
+|------|---------|-------------|
+| `--name <name>` | `get` | Only return the cookie with this name |
+| `--url <url>` | `get`, `set` | Target URL instead of the tab's current page |
+| `--domain <domain>` | `set` | Cookie domain |
+| `--path <path>` | `set` | Cookie path |
+| `--same-site <v>` | `set` | SameSite attribute: `Strict`, `Lax` or `None` |
+| `--secure` | `set` | Mark the cookie Secure |
+| `--http-only` | `set` | Mark the cookie HttpOnly |
+| `--tab <id>` | `get`, `set` | Target a specific tab |
+
+`cookies clear` affects **all origins** and cannot be scoped to one tab or one domain — there is no per-cookie removal verb, and `--tab` is deliberately not offered on it. Nothing in the CLI restores what it removes: re-set what you need with `cookies set`, or reload a saved state with `state load`.
+
+Requires `security.allowCookies: true`.
+
+> **Sensitive data:** Cookie values are credentials. Obtain user approval before reading or forwarding them, and never print them into a transcript that outlives the task.
+
+### `pinchtab storage`
+Read and write `localStorage` and `sessionStorage` for the active tab's origin.
+
+```bash
+pinchtab storage get # both stores
+pinchtab storage get --type local # one store
+pinchtab storage get --key token # a single item
+pinchtab storage set token abc123 # writes to localStorage by default
+pinchtab storage set token abc123 --type session
+pinchtab storage delete --key token # remove one key
+pinchtab storage clear --all # both stores in one call
+```
+
+| Flag | Command | Description |
+|------|---------|-------------|
+| `--type <local\|session>` | `get`, `set`, `delete`, `clear` | Which store. `get` defaults to both; the write verbs default to `local` |
+| `--key <key>` | `get`, `delete` | A single item |
+| `--all` | `clear` | Clear both stores in one call |
+| `--tab <id>` | all | Target a specific tab |
+
+---
+
## Audit Commands
### `pinchtab audit`