ACP terminal attachment
An operator starts a program with a dedicated RPC sideband. A terminal without that sideband cannot be attached. The program keeps its terminal and its external profile: hc supplies neither managed confinement nor human approval.
Living doc, checked against the code 2026-11-14
hc terminal RPC v1 — proposed dependency contract for ACP attachment
Status: private prototype, off in both gateway roles. It is not an installed or published hc capability: the installed hc 0.1.19 has no such methods. Terminal attach/send/keys and opaque document CAS are not substitutes.
Boundary
An operator starts a program with a dedicated RPC sideband. A terminal without that sideband cannot be attached. The program keeps its terminal and its external profile: hc supplies neither managed confinement nor human approval. Vulpine never adopts its PID, replaces its executor, or sends a close or kill on detach.
The original hc HOLDER owns the sideband descriptor and the original program Child/wait. A restarted core is a carrier to that same holder, not a replacement physical writer. All writes, claims, revocations and time checks serialize on the holder’s one owner lock. A core-level observation, label, PID, configuration token or claimed lease alone cannot authorize a physical sideband write.
It is Unix-only, through a platform-owned inherited descriptor. Unsupported platforms and unmodified holders do not advertise it. It is an additive opt-in capability: normal PTY input, screen parsing, automatic input, terminal recovery and existing clients do not change. No raw ACP bytes pass through a PTY or a terminal-screen API.
Negotiation and attribution
The endpoint must advertise terminal_rpc_v1 end to end; an old core, machine relay or holder makes it unavailable.
Discovering a terminal does not acquire a writer. Capture separately:
- authenticated hc machine route and actual core identity;
- original holder incarnation and original program allocation generation;
- terminal address on that machine, independent of its name/labels;
- sideband protocol identifier and readiness on the original descriptor;
- exclusive writer fence and expiry, actual initiating operator interface and wire session.
Provider callbacks stay on the same full-duplex sideband and authenticated hc machine route. No local hook pathname, model-selected endpoint, extra HTTP listener, raw SSH transport or screen scraping supplies callbacks. The original transport capture assigns callback attribution; it is never rebuilt from an address or copied from peer JSON.
Owner operations
The method is terminal.rpc, with a typed operation.kind of info, acquire, write, read or detach. This
document alone is not negotiation.
- Acquire names the exact original allocation and mode: exclusive, or explicit takeover. It returns a private unguessable grant, a monotonically increasing fence, a holder clock epoch and sample, and a fixed expiry. Another live exclusive claimant refuses. There is no implicit renewal or takeover.
- Write names the same capture, grant and fence, and an unrepeated sequence. Bounded nonblocking write admission rechecks those facts, the deadline and revocation under the SAME owner lock. Intent is charged before IO. A full or partial byte count is only observed transport delivery, not provider completion. A lost response keeps dispatch_unknown and cannot replay on reconnect.
- Read is bounded and tied to the same original capture. Stale owners cannot consume or redirect another owner’s progress or permissions. Old callbacks never become a new allocation’s callbacks.
- Detach permanently revokes that grant and drops only our writer and transport. It never invokes a terminal signal, close, kill, recovery shell, SDK abort or approval. Effects admitted before it stay uncertain. A poisoned or partly written stream stays unavailable: a new owner’s bytes are never appended to an old prefix, and no clean protocol boundary is inferred.
Takeover revokes the old grant synchronously. A dirty or ambiguous old stream cannot be made ready by takeover, a new token, a new request ID or a local store reset. A stream reset must be an explicit original-provider protocol action, not a fresh agent or replacement writer.
Clocks, bounds and failure
The RPC 30 s, prompt 300 s, human ≤ 60 s, drain 10 s, TERM grace 2 s and whole-command write/stall 5 s budgets are unchanged. Holder leases never exceed 300 s and expire in their original monotonic epoch. A local retirement intent is not an observed remote fence. Until the original holder acknowledges revocation, or its captured original deadline is known to have expired, remote fencing and cleanup stay unknown. No late response or reconnect may authorize new sends. Permanent physical fencing is linearized at the original holder’s owner lock, not at a local UI acknowledgment.
Cross-host physical-write deadlines need a conservative clock translation from an authenticated holder sample: map by local receipt time as the lower bound, not by send time or a newly granted relative timeout. Repeated writes and partial progress do not renew the original frame deadline.
Only Vulpine’s ConnectionOwner/AttachedGuard queue and physical cursor may submit the frame. The hc transport must not report queued work as physically written or revive queued bytes after revocation. Provider callback bytes and sideband reads stay bounded; there is no uncharged retry or output queue. Vulpine’s total retention is 1024 records / 8 MiB.
EOF, channel or route loss, epoch change, expired lease, foreign allocation, unsupported capability, unknown write outcome and lost original wait all fail closed. On uncertainty, keep the original custody and state. Neither snapshots nor a negative PID lookup proves absence. Detach does not upgrade an externally owned agent to managed ownership.