control

Imported from hraness/ghostget (src/control/AGENTS.md). Install upstream with npx skills add hraness/ghostget --skill control. Copyright stays with the author.

Contents

• protocol.ts – browser-safe administrative and agent contracts.
• helper.ts, service.ts – process custody, transport and control composition.
• retire-tray.ts – moves the retired menu bar's login item aside (never deletes) and answers ghostget menubar with the replacements.
• tui*.ts – keyboard-driven control views, input decoding, and terminal lifetime.
• registry.ts, registry-words.ts – the shared-grammar control verbs (status, approvals, permissions, control, …) with --json parity.
• admin-socket.ts – the owner's capability-bound administrative socket used by those verbs.
• status-view.ts, outputs.ts – the one-screen status model and saved-output listing shared by the TUI and CLI.
• helper-client.ts, control-response.ts – bounded private control transport and strict response parsing shared by the CLI verbs and TUI.
• approval-*.ts – exact human request and one-use approval lifetimes.
• web-*.ts, activity.ts – bounded public retrieval and SQLite metadata.
• interface*.ts – OpenAPI parsing, inert drafts and conditional activation.
• connections.ts – subject-bound account setup.
• Colocated tests exercise boundary, lifetime and property laws.

Guidelines

protocol.ts is the browser-safe shared contract. helper.ts owns private administrative stdio and a separate owner-only agent socket. Agent requests cannot grant approvals, alter policy, connect accounts, or resolve secrets. Keep both protocols bounded and reject drift before dispatch. The owner's admin.sock carries the administrative union for the control verbs and requires the owner's private capability file. It is not a boundary against the same user, so every verb that grants, loosens, connects, disconnects, activates or installs passes the shared T1+T2 human gate; only inputs that strictly tighten run without it. The control verbs and TUI share one helper owner per state home. Keep account selection and exact revision/digest review visible before actions. Terminal input, including pasted text, must never bypass that review. Restore terminal state before waiting for helper cancellation and custody settlement.

service.ts composes current account, manifest and implementation identities. Display optimizations must not cache authorization across a changed account, policy, interface or executable closure. User OpenAPI documents remain inert until exact conditional activation and never create arbitrary HTTP executors.

web-policy.ts, web-gateway.ts and activity.ts form one admission boundary: durable metadata before dispatch, public pinned DNS, no redirects or ambient credentials, policy rechecks, and durable terminal evidence before disclosure. Request bodies, query values, secrets, response bodies and raw transport errors must not enter activity storage. A cancellation or interrupted record does not authorize a retry. Legacy provider dispatch journals remain separate.

Connection and helper shutdown must settle owned work before custody is released.