8000 "Known limitations" is out of date after this run (#37) by simon-inkie · Pull Request #64 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content

"Known limitations" is out of date after this run (#37) - #64

Merged
simon-inkie merged 10 commits into
mainfrom
37-known-limitations-audit
Oct 16, 2026
Merged

simon-inkie merged 10 commits into
mainfrom
37-known-limitations-audit

Conversation

@simon-inkie
@simon-inkie simon-inkie commented Oct 12, 2026 •
Copy link
Copy Markdown
Owner

Requested by Simon · project thread

What was wrong

INSTALL.md "Known limitations" said nobody had run Deck on Windows, everything was measured only as root, and the Deck-to-agent delivery direction was unproven. The 2026-09-27 WSL run (non-root, Ubuntu 24.04) changed those, and a later merged PR changed a fourth entry. Entries also did not say who measured what, or when. It also said every optional subsystem needs a key, which is not true of web push.

What changed

Only the Known limitations section of INSTALL.md (the README has no copy). Each entry now says what was measured, by whom (rig or by hand) and when. Corrected: the root entry, the Windows entry, the delivery entry, and the paragraph on Deck's terminal send. Added three entries: first boot needs a person, starting Deck on boot is unchecked, and web push is switched on by a browser subscription (no operator key). The egress sentence now says Deck itself needs no egress beyond the optional integrations, and that the agents' model CLIs still need their provider. SPEC at .specs/37-known-limitations-audit/SPEC.md, with the review feedback recorded.

Audit

8000
Limitation Still true? Evidence
No authentication Yes No login or session routes in packages/deck/app/routes; note added
Quoted header splits a message Yes Ran the inbox parser on a quoted header in a code fence: split into two senders; a plain ## heading does not split
Readers disagree Yes, unchanged packages/base/conformance/corpus.json: five deviations, all on deck. No edit needed (entry already says to read the file)
CLI send misses the file Deck reads Yes Ran it: inbox reply quill as me wrote me/inbox/quill.md; quill's inbox unread said "no unread"
Nothing proves a READY pane receives text Partly. Reworded Issue #37 reports delivery seen by hand on WSL 2, 2026-09-27 (~10 s reply); still no automated test, rig/README.md:116 says the stub-agent stage is not built
Deck's own terminal send has no idle check or read-back No. Corrected tmux.server.ts sendKeysToWindow and tmux-submit.ts: composer gate (unsafe-composer) and re-capture after Enter; added in #43; tests in packages/deck/test/tmux-send-verification.test.ts
e2e suite not a guarantee, not in CI Yes No e2e step in .github/workflows/ci.yml
boot-agents.sh session fixed to agents Yes packages/base/bin/boot-agents.sh:57
Typography needs the internet Yes. Egress sentence qualified Google Fonts still linked in packages/deck/app/root.tsx:42-51; #32 (merged) fixed loading, not the dependency. Other egress: Gemini, Deepgram, web push once subscribed, and the agents' model CLIs
Optional subsystems unverified (Deepgram, Gemini) Reworded, dated 2026-10-12 Voice no-key path in packages/deck/server/voice-proxy.mjs:185-188; Gemini code exists. Not exercised by the rig; not re-run here
NEW: web push needs no operator key Added, read from code 2026-10-15 getVapidKeys in packages/deck/app/lib/push.server.ts generates and stores vapid-keys.json on the first /api/push-subscribe request; packages/deck/server/push-watcher.mjs sends to each stored subscription endpoint only once a browser has subscribed. Not run
Only measured as root Partly. Reworded Rig still root: rig/container-image-note.md section 3. By-hand non-root run on WSL, 2026-09-27, from the issue
macOS and Windows unverified Partly. Reworded WSL 2 by hand 2026-09-27 (issue); native Windows unsupported because tier 3 needs tmux; macOS still unrun; the Windows section's sh-manual blocks are not run by the rig
MC_USER defaults to alex Yes mcUser in packages/deck/app/lib/instance.server.ts:32-34; note added
NEW: fresh agents need a person at first boot Added packages/base/bin/boot-agents.sh:642 BOOT_READY_SECS (default 45), exit 3 pending; tier 3 text from #46 and #55
NEW: Deck on boot unchecked Added Already said in Keep it running; now on the list

How verified

The two behavioural claims were reproduced here (CLI send target, quoted header). The rest is code reading, cited above. Also run: pnpm typecheck, pnpm test (2227 passed), pnpm check:boundaries, pnpm check:leaks, pnpm check:licence, pnpm check:lib-version, pnpm -C packages/deck check:dashes, node rig/self-test.mjs.

What could not be verified

  • The 2026-09-27 WSL run and the ~10 s delivery are taken from the issue text. I could not re-observe them, and there is no Windows machine here.
  • Voice, Gemini and web push were not run (no keys, no subscribed browser).
  • Docker install rig not run (no Docker here). check:leaks:messages and check:leaks:history are red on older commits on main.

Not changed, noted for follow-up

Fixes #37

🤖 Generated with Claude Code

https://claude.ai/code/session_01ByrScobyMJ5eQ8EQZzEcWB

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie simon-inkie self-assigned this Oct 12, 2026
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Review findings for head 3423dee

Two independent reviews of this PR. Please address the Critical and Major items and reply to each Minor with a fix or a one-line reason to defer, then push. Keep the spec in sync with what changes.

Review A

Verdict: MERGE AFTER FIXES. No Critical or Major findings in the three #37 commits. Two Minor corrections remain in the audited text.

  • Minor - INSTALL.md:1061: false egress assurance. “Nothing else about the application depends on egress” conflicts with the optional subsystems immediately below. Image descriptions call Google's API (file-description.server.ts:475), voice connects to Deepgram, and web push sends to subscription endpoints (push-watcher.mjs:136). An operator allowing only Google Fonts through a firewall would find these configured features failing. Qualify the assurance as applying to core functionality with optional integrations disabled. This sentence predates "Known limitations" is out of date after this run #37, but the audit retains it and adds a “Checked” note.

  • Minor - INSTALL.md:1090: incomplete account of unexecuted instructions. The audited paragraph says the Ubuntu path executes on every rig run except sh-manual blocks in Keep it running. The Windows section also contains Ubuntu-side sh-manual instructions that the rig does not execute, including user creation and CLI checks. A Windows installer could interpret those instructions as continuously tested. Include the Windows blocks in the exception, matching the disclosure at lines 57-64.

The remaining #37 changes agree with the inspected implementation: CLI replies write into the sender's tree; valid quoted headers split messages; the launcher fixes the session name to agents; fresh launches wait for readiness; and unconfirmed terminal submissions receive a distinct response. The automated delivery coverage gap is explicitly acknowledged.

I found no private company names, commercial plans or credentials in the #37 additions or their three commit messages. Those commits contain only documentation changes, so they introduce no executable path traversal, symlink, race or data-loss behaviour.

Review limits: local main is stale, so git diff main...HEAD spans 86 files and numerous earlier PRs. I isolated #37 against its parent, e51a322; this is not an approval of all intervening implementation changes. No browser, tests, real installation, Docker rig or reboot was run. No network, database or credential files were accessed. Historical WSL results, CI results and the SPEC's required PR evidence table could not be independently verified offline.

Review B

Verdict: MERGE

Summary

PR 64 updates INSTALL.md and .specs/37-known-limitations-audit/SPEC.md to reflect an audit of known operational limitations and delivery test coverage in Deck.

Findings

Critical

None.

Major

None.

Minor

None.

Verification of Claims

  • Tmux session name: Verified that boot-agents.sh:57 sets SESSION="agents".
  • Google Fonts egress dependency: Verified that packages/deck/app/root.tsx:42 imports Google Fonts stylesheets (fonts.googleapis.com).
  • Default user: Verified that mcUser in packages/deck/app/lib/instance.server.ts defaults to "alex" when MC_USER is unset.
  • Delivery suite scope: Accurately states that pnpm delivery tests keystroke handling against supplied buffer text with mock panes, rather than dispatching real keystrokes to live agents.
  • E2E tests in CI: Accurately notes that .github/workflows/ci.yml lacks Playwright e2e test execution.
  • First-boot limitation: Correctly documents that boot-agents.sh waits up to BOOT_READY_SECS (45s) for human interaction on interactive first-boot prompts (trust, model selection, resume).

Safety & Leaks

  • Information leakage: Checked for private paths, internal URLs, company credentials, and customer data. No leaks identified.
  • Formatting: Documentation-only changes; no broken code blocks or invalid shell instructions.

What Was Not Checked

  • Following the manual WSL 2 installation instructions on a physical Windows machine.

Related Brain Files

  • [[../../brain/projects/oss-pr-reviews-2026-10-14/pr-64-comment]] (1.00) — pr-64-comment
  • [[../../brain/projects/oss-pr-reviews-2026-10-14/pr-64-aggy]] (0.93) — PR 64 Review: Known Limitations Audit ("Known limitations" is out of date after this run #37)
  • [[../../brain/projects/oss-pr-reviews-2026-10-14/pr-64-sol]] (0.90) — pr-64-sol
  • [[../../brain/projects/deck-install-fixes-2026-09-27/ISSUES-DRAFT]] (0.78) — Inkie Deck: issues from the Windows/WSL install test (2026-09-27)
  • [[../../brain/projects/2026-10-11-deck-cloud-agent-prompts-batch-b]] (0.78) — 6. Known limitations is out of date (issue 37)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Both Minor items are fixed and pushed, and main is merged in (no conflicts).

  • Egress claim (INSTALL.md ~1061): now says that with the optional subsystems off, nothing else in the core application depends on egress, and that with them on, image descriptions call Google's API, voice connects to Deepgram and web push sends to subscribers' push services.
  • Unexecuted blocks (INSTALL.md ~1090): the macOS and Windows entry now lists the Windows section's sh-manual blocks (user creation, the CLI path check, the /etc/wsl.conf edits) alongside the Keep it running ones as not run by any rig.

The SPEC records both under Review feedback. I also updated the BOOT_READY_SECS citation to boot-agents.sh:642, which moved when #61 merged. The new WSL claude entry from #60 sits above the entries I audited and is consistent with them.


Generated by Claude Code

@simon-inkie
Copy link
Copy Markdown
Owner Author

Automated review (CodeRabbit CLI, run against this branch) found two minor documentation issues:

  • .specs/37-known-limitations-audit/SPEC.md:10-12 (also 40-42): the spec says three limitations were added, but INSTALL.md adds four (root-owned rig directories, platform coverage, first-boot readiness, boot startup). Update the count, the list and the decisions log.
  • INSTALL.md:951-953: the introduction says every entry states what was measured, by whom and when, but the optional-subsystems entry (line 1064) and the boot-startup entry (line 1104) carry no date. Add dates or narrow the claim.

…#37)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Both findings are fixed and pushed.

  • SPEC count: two entries were added (first boot needs a person, boot start unchecked), not three or four. The root and platform entries were rewritten in place, and native Windows went into the reworded Windows entry. The TL;DR and decisions log now say so.
  • Undated entries: the optional-subsystems and boot-start entries now carry 2026-10-12 and say that nothing was run, so the introduction's claim holds.

The SPEC records the feedback under Review feedback.


Generated by Claude Code

Web push makes its own VAPID keys and sends only once a browser has
subscribed, so it does not belong with the key-gated subsystems. Give it
its own Known limitations entry and correct the egress sentence.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Review of head 64bf9ed

Verdict: MERGE AFTER TWO SMALL FIXES. No Critical or Major findings. The new web push entry is accurate against the code. One SPEC count is now stale, and one egress sentence can be misread.

Findings

  • [Minor] .specs/37-known-limitations-audit/SPEC.md:10-12 and :41-44 - stale count. The TL;DR says the audit "adds two real limitations" and the Decisions log says "Added two entries". 64bf9ed adds a third, separate entry ("Web push needs no operator key; a subscription switches it on"). The PR description's audit table is also stale: it still has "Optional subsystems unverified: Left as is" and no web push row. Fix: say three entries were added and list web push, then update the PR table to match.
  • [Minor] INSTALL.md:1095-1096 - the egress assurance can be read as "runs offline". "nothing else in the core application depends on egress" is true of Deck's server code. But the agents that this stack launches (boot-agents.sh, using claude or codex) need their model provider. An operator planning an air-gapped or allowlisted host could take this sentence as a guarantee. Fix: narrow it, for example "nothing else in Deck itself depends on egress (the agents' model CLIs need their provider, as tier 3 says)".

Verified against the code at 64bf9ed

  • VAPID keys. getVapidKeys (push.server.ts:95) reads DATA_ROOT/vapid-keys.json. If the file is missing or invalid, it calls webpush.generateVAPIDKeys() and writes the result through the confined atomic write. No operator key is involved.
    • The only caller is the loader of api.push-subscribe.tsx, so a plain GET creates the keys, as the entry says.
    • A POST does not call it, so "the first request" is strictly "the first GET". This is harmless, because PushToggle.enable() always sends the GET before the POST.
    • Nothing calls it on page load: the GET is sent only from PushToggle.enable(), after notification permission is granted.
  • Subscriptions. The POST intent=subscribe action calls addSubscription, which stores the subscription in push-subscriptions.json, deduplicated by endpoint. Correct.
  • Watcher. Only scripts/start-production.mjs:130-140 spawns push-watcher.mjs. scripts/dev.mjs (pnpm dev) and pnpm start (react-router-serve) do not, so "the production launcher's push-watcher.mjs" is correct.
    • It polls INBOX_ROOT/*/inbox/$MC_USER.md every 4 s. deliver() returns with no network call when there is no keypair or no subscriptions, so "polls the inbox files and sends nothing" is correct.
    • It sends with webpush.sendNotification to each stored sub.endpoint (the browser vendor's push service), only for new blocks whose sender is not the user (push-watch-core.mjs:60; (unknown) senders are skipped too). On a 404 or 410 it drops that subscription.
  • Optional subsystems entry. Now limited to Deepgram (voice-proxy.mjs:185, sends no_key and closes) and Gemini (file-description.server.ts:442-457, skipped when GOOGLE_GENERATIVE_AI_API_KEY is unset). Both truly need keys.
  • Other outbound requests. I searched packages/ for fetch(, URLs, WebSocket, webpush, http(s).request, curl, telemetry and update checks.
    • All fetch calls in the app are same-origin /api/*.
    • Server-side egress is limited to Deepgram (wss://api.deepgram.com), Gemini through @ai-sdk/google, and web push.
    • The only browser-side egress is Google Fonts (root.tsx).
    • There are no telemetry or update checks.
    • packages/base/bin/stuck-pane-sweep.sh can call generativelanguage.googleapis.com, but it is opt-in, key-gated and not part of Deck's launcher, so it is fine to leave out of this sentence.
  • Scope and hygiene.
    • The diff against main touches only INSTALL.md and the "Known limitations" is out of date after this run #37 SPEC (docs only, no code).
    • There are no U+2013 or U+2014 characters in either file, and no private hosts, paths or names in the new text.
    • No commit on the branch carries a Claude-Session trailer; 64bf9ed has Co-Authored-By and Signed-off-by only.

CI on 64bf9ed

guards: success · licence: success · test (22.x): success · test (24.x): success

Not verified


Generated by Claude Code

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
Copy link
Copy Markdown
Owner Author

Both findings are fixed and pushed.

  • Stale count: the SPEC now says three entries were added (first boot, boot start, web push). The PR description's table now has the web push row and the narrowed optional-subsystems row.
  • Egress sentence: it now says nothing else in Deck itself depends on egress, that the agents' model CLIs still need their provider as tier 3 says, and then lists the optional subsystems that do call out.

Generated by Claude Code

…ads (#37)

Signed-off-by: Claude <noreply@anthropic.com>
@simon-inkie
simon-inkie merged commit 84aae73 into main Oct 16, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

"Known limitations" is out of date after this run

2 participants

0