callstack / callstack/agent-device
feat: workspace-scoped device pinning (lock a project to one device)
- Lingua principale
- TypeScript
- Stelle
- 4.7k
- Fork
- 303
- Merge medio
- 10h 42m
- PR unite (30g)
- 493
Descrizione
## Motivation
User feedback (local-environment, client project):
> I had tons of issues with agent-device always trying to open iPhone simulator (default) when I really wanted the session to be scoped to a particular iPad only when I was working with real client's project. Solved it by wrapping every agent-device command with my custom bash script. I think simlock might be a good tool to enforce that.
Today the only way to target a specific device is to pass `--platform/--device/--udid/--serial` on every invocation. When an agent (or human) forgets, inventory selection falls back to its booted-device heuristics and picks the default iPhone simulator — on a client project that is not a nuisance but a correctness failure. Users are resorting to wrapper scripts to enforce scoping.
This is adjacent to but distinct from #1320: device claims fence *other* worktrees' daemons off a device; they do nothing to stop *your own* commands from selecting the wrong device. Enforcement of user intent at selection time is the missing piece.
## Proposal
A workspace-scoped device pin that both **defaults** and **enforces**:
- A pin source, in precedence order: env (`AGENT_DEVICE_PIN`-style selector) and/or a per-workspace config the daemon/CLI reads from the project root. The repo currently has no project config file surface, so the env form may be the v1.
- Selector-less commands inherit the pin: `open com.example.app` targets the pinned iPad, never the default iPhone.
- Commands with an explicit selector that CONTRADICTS the pin fail with a structured error naming the pin and its source — consistent with the #1880 principle that selection conflicts fail instead of retargeting. (An explicit selector that refines the pin — same device — passes.)
- `devices`/`doctor` surface the active pin so agents can discover why selection is constrained.
- The error and `--help` text must teach the escape hatch (edit/unset the pin), not invite per-command overrides that defeat the point.
## Non-goals
- Cross-worktree exclusion (that is #1320's device claims).
- Provider/remote lease semantics.
## Acceptance
- With a pin set and no selector flags, every device-targeting command resolves to the pinned device or fails if it is unavailable — it never falls back to another device.
- A conflicting explicit selector fails with a structured error naming the pin, its source, and the pinned device.
- No wrapper scripts required: the pin is honored by `open`, sessionless mutations (`boot`, `install`, ...), and inventory-based selection alike.
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia tracciando la selezione dei dispositivi per le mutazioni aperte e senza sessione, come boot e install, e la selezione basata sull’inventario. Leggi l’attuale guida della CLI e la gestione dei conflitti di selezione, quindi individua come devices e doctor potrebbero esporre un pin attivo. Il lavoro è completato quando i comandi con pin non fanno mai fallback, i selettori in conflitto falliscono con dettagli strutturati e l’escape hatch è documentato.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- typescript
- Ambito
- cli, mobile-dev
- Tipo di issue
- Funzionalità
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Stato di attività
- Attiva
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 48/100