---
title: "ACP terminal attachment"
description: "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."
type: "living"
source: "docs/contracts/hc-terminal-rpc.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **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.

