Personal-data agent: ship it as an App (app-store demo) + the app→orchestrator consent gate

[NotASithLord]

@jonybur — a direction call on where the local-first personal-data agent lands (your spec: docs/specs/LOCAL-FIRST-PERSONAL-DATA-AGENT.md). Short version: build it as an App, not just a chat skill-recipe. That's deliberate, and it has a dependency. Details below.

Why an App

The chat-recipe version (harvest → js_notebook query → answer) is fine for the solo case, but it's a prompt, not a place. As an App it becomes something you open and come back to — a dashboard over your own data you can re-query without re-prompting the model.

The bigger reason is distribution: a personal-data App is something we can preload over the network into the app store as a flagship demo. A visitor installs it and it fills itself in from their own accounts, entirely on-device. That's the "try it and get it" moment we want to seed the store with.

And it makes the privacy pitch stronger, not weaker: an opaque-origin App with no network egress physically can't exfiltrate, so handing it your freshly-harvested data is safe by construction. "Nothing leaves your machine" stops being a promise and becomes a property of the container.

The seam: the harvest can't live in the App

An App is an opaque-origin iframe with no access to your real tabs or logged-in sessions — by design, that's why it's safe to run untrusted code. So it can't do the harvest itself; that's the do/get/check runner, which is extension-privileged. The harvest stays agent-side. Which means a preloaded App needs a way to ask the agent to do the privileged part for it.

The mechanism (app → orchestrator, user-gated)

1. The App calls an internal peerd.* capability the resident has — something like peerd.requestOrchestration(intent). The App can only trigger it.
2. peerd renders a permission prompt in its own trusted UI — not inside the iframe. The App must never be able to draw this. It shows the user exactly what's being requested.
3. User approves → it's passed as a message to the orchestrator, which does the work (delegates the harvest to residents).
4. Results come back to the app-resident, which finishes building the on-device store / dashboard.

One-shot to start — every harvest re-asks. Keep it simple. We can add a scoped, revocable per-app grant later (DECISIONS #21 territory) if the re-ask friction gets annoying, but for "read my bank tab," that friction is arguably the feature.

Controls that have to be in v1

This is reading your authenticated accounts, so the gate has to be real:

• Un-spoofable consent. The prompt is peerd chrome outside the App's iframe — the browser-permission model (the App can ask, only peerd can grant). If the App can render its own "approve" button, we've lost.
• Show the capability scope, not just the prompt text. What the user is really approving is an untrusted App injecting an instruction into their trusted agent. The prose can read benign while the tools it invokes aren't. So the consent screen should say what the delegated turn can reach ("will read logged-in tabs + write on-device storage; will NOT send anything off-device"), derived from the allowed toolset — not the words. For the preloaded-demo case especially, I'd lean toward structured intents (the App picks harvest:orders from a constrained vocabulary) over freeform prompts — far easier to render an honest consent screen for.
• Restricted posture for the delegated turn. Run it under the runner's untrusted fence, a tight gate set, no privilege escalation, and it can't itself re-delegate.
• Provenance in the prompt. Bundles are already signed and content-addressed, so the consent screen can show "signed by peerd" vs "unsigned / anonymous." An anonymous App asking to read your bank tab should feel different from a first-party one.

Dependency: this rides on the DESIGN-17 resident refactor (#61)

This isn't a separate system — it's the inbound clamp that #61's spec explicitly deferred. The sender gate there already blocks inbound/untrusted requests by default (inbound = synthetic && !trusted); this consent flow is the user-mediated way an inbound App request gets promoted to trusted. So it lands after #61, and the requestOrchestration capability should be designed as part of that surface, not bolted on. Flagging it as a hard dependency.

Net

Personal-data agent → an App. Harvest stays agent-side. The App bootstraps itself via a one-shot, user-approved orchestration request. Ships on top of #61. This is the path that gets us a real preloadable app-store demo instead of a prompt people have to know to type.

React on any of it — especially the structured-intents-vs-freeform call and whether one-shot holds up once you start building the demo.

[NotASithLord]

Status check: the hard dependency this issue names — #61 (the DESIGN-17 resident/actor refactor) — merged and closed on 2026-06-29. The inbound = synthetic && !trusted sender-gate clamp it shipped is exactly the seam this issue's peerd.requestOrchestration(intent) flow needs to promote an inbound App request to trusted via user consent.

So the blocker is cleared — this is now unblocked and ready for a design pass on the two open calls flagged in the issue: structured intents vs. freeform requestOrchestration text, and whether one-shot consent (no scoped/revocable grant) holds up once the demo App is actually built. No code changes proposed here; flagging readiness only.

---

Generated by Claude Code

[NotASithLord]

Readiness check: the hard dependency this issue names — #61 (the DESIGN-17 resident/actor refactor) — merged on 2026-06-29. So the blocker is cleared and this is actionable now, not just well-scoped.

One more thing worth folding in before implementation starts: PR #141 (just reviewed) shipped a directly relevant precedent for the consent mechanism this issue asks for. It introduces a global daemon actor whose dangerous actions (dweb_install/dweb_share, both mutate_external) force-confirm unconditionally, routed through the same confirm() coordinator that's fail-closed by construction (broken channel or timeout → auto-deny, never auto-approve). That's effectively the same shape as the peerd.requestOrchestration(intent) gate this issue proposes — an untrusted/external-triggered request whose only path to a side effect runs through a trusted-UI confirm that can't silently degrade into an approval. Worth reusing that pattern (and the trust-lineage / sender-gate machinery from the heap-split work) rather than designing the app→orchestrator consent screen from scratch.

No blockers otherwise — the structured-intents-vs-freeform call and the one-shot-vs-scoped-grant question are still open design calls for whoever picks this up, as the issue already flags.

---

Generated by Claude Code

[NotASithLord]

Status check on the dependency: #61 (the actor-model / DESIGN-17 resident refactor) merged on 2026-06-29. The sender-gate primitive this issue's consent flow rides on (inbound = synthetic && !trusted) is live in subagent/delegation-lineage.js, and the bound-actor substrate (web/webvm/notebook/app, now including the dweb actor) is shipped per CLAUDE.md.

So the hard dependency this issue flagged is cleared — it's unblocked and ready for a design pass on the peerd.requestOrchestration(intent) capability + the un-spoofable, chrome-owned consent UI. The two open calls from the issue body still need an owner decision before implementation starts:

1. Structured intents (constrained vocabulary, e.g. harvest:orders) vs. freeform prompt text for what the App can request.
2. Whether one-shot-only consent (re-ask every harvest) holds up once the demo App is actually built, or needs a scoped/revocable grant sooner than planned.

Flagging as ready, pending those two calls — not blocked on other in-flight work.

---

Generated by Claude Code

[NotASithLord]

Triage pass: this is a direction/design proposal, not yet actionable as an implementation task — it's explicitly awaiting @jonybur's call (App vs. chat-skill-recipe, structured-intents vs. freeform, whether one-shot consent holds up) and it has a hard, stated dependency on #61 (the DESIGN-17 resident refactor) landing first for the inbound consent clamp. Flagging as blocked, not stale — no action needed until the owner responds and #61 merges.

---

Generated by Claude Code

[NotASithLord]

Clarifying the dependency status since the last two comments on this thread disagree: #61 (the DESIGN-17 resident/actor refactor) is merged (merged 2026-06-29, merged_at confirmed via the PR record). The most recent comment's claim that this is still "blocked" on #61 is stale — that hard dependency is cleared.

What's actually left before this is actionable is the two owner-decision points already named upthread: (1) structured intents (harvest:orders-style fixed vocabulary) vs. freeform prompt for peerd.requestOrchestration, and (2) one-shot-per-harvest vs. a scoped/revocable per-app grant. Once @jonybur calls those, the design/implementation work itself is unblocked and well-scoped per the spec above.

---

Generated by Claude Code

[NotASithLord]

Status update: the stated hard dependency, #61 (the web-actor/orchestrator-delegates-to-actors architecture), has landed — it's merged and shipped per CLAUDE.md's feature inventory. So this issue is now unblocked on that front.

What's still open before this is implementation-ready: the owner calls flagged in the issue body itself — (a) structured intents (harvest:orders from a constrained vocabulary) vs. freeform requestOrchestration(intent) text, and (b) whether one-shot consent holds up once the demo App is actually built, or needs the scoped/revocable per-app grant sooner. Recommend resolving those two before scoping an implementation PR, since the consent-gate shape is the security-load-bearing part of this design.

---

Generated by Claude Code