feat(agent): attach to the canonical PTY by ID

[schickling-assistant]

Problem

Callers that create an Agent currently have to rediscover its PTY runtime ID and reproduce readiness logic before they can open the session. That duplicates internal runtime-ID and PTY-root rules and can attach the terminal to the wrong registry.

Goal

Add one transparent exact-ID handoff: st2 agent attach --id <AGENT-ID> [--host H] [--wait SECONDS].

Decisions

• Accept only an immutable Agent ID. Never fall back to the mutable address namespace.
• Resolve the authored canonical agent PTY task and reuse the runner's shared runtime-ID derivation.
• Wait up to 30 seconds by default for positive live-session evidence; expose --wait only for advanced direct use.
• Probe and hand pty the same effective PTY registry, including an intentional ambient PTY_ROOT override.
• Replace the st2 process with pty attach --force; PTY owns terminal input, signals, detach behavior, restart behavior, and exit status.
• Add no receipt, mission, parent, delivery, or replay protocol.

Verification

• nix develop --offline -c cargo test --offline --test agent_attach — 11 passed.
• nix develop --offline -c cargo test --offline --workspace --no-run — passed.
• nix build .#checks.x86_64-linux.wasm-resolver-feature --no-link --print-build-logs — passed.
• Independent review reproduced and drove fixes for divergent PTY registries and overflowing --wait deadlines; bounded re-review returned go.

Full nix flake check built 21 of 22 checks and failed only the existing load-sensitive tests/resync.rs::an_address_change_keeps_the_subscription_and_its_delivery_target. The attach diff does not touch its call graph. The test's unacknowledged ResyncSupervisor::refresh can seed an already-written carrier as its silent baseline under parallel load. The focused test and its exact Nix check passed immediately in isolation. The durable test defect is recorded in Agent Feedback; this PR does not hide it with a longer timeout or unrelated resync change.

Complexity

The command is intentionally a narrow resolve → wait → exec path. The only shared refactor promotes the existing runtime-ID helper so attach, reconciliation, evaluation, and inventory cannot drift.

Concerns

The default wait is a bounded readiness window, not a lifecycle controller. A timeout changes no state and directs the operator to inspect st2 tasks --json or run st2 up.

References

• Depends on Implement immutable agent IDs and mutable addresses coherently #464
• Refs Define immutable agent IDs and mutable addresses #453

Posted on behalf of @schickling

field	value
agent_identity	dev3.direct.omp.2ahzpbs3
session	dev3.2ahzpbs3
agent_persona	generalist
agent_supervisor	unavailable
agent_tool	OMP
agent_tool_version	18.1.2
agent_runtime	OMP 18.1.2
tooling_profile	dotfiles@7534055

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-05T16:25:36.106754Z	019f154	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 019f1547d2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Hold the catalog snapshot through the attach handoff

The shared catalog lock is scoped only around discovery and is released before the readiness wait and pty exec. If a publish or catalog apply changes/removes the selected task during that window—especially while the command waits up to 30 seconds—the old runtime ID can be reassigned and adopted by another agent, causing this exact-ID command to attach to the wrong live terminal. Retain the snapshot fence through the handoff or reacquire it and revalidate the selected task and effective PTY root immediately before exec.

Useful? React with 👍 / 👎.

[schickling-assistant]

Closing in favour of the address-first landing: st2#468 → #467, per dotfiles decisions Q23–Q25 (seat dev3.direct.omp.v6c4mkm2) and the two audits (StackMinimal, StackAnatomy): the #453 problem statement is solved by a mutable address alone; the immutable-id half is staged behind named triggers in decision 0015 Amendment 1 (cross-host seat move, live/archive identity collision, a UUIDv7 creation call site). Branch kept; agent attach --id can be re-cut as attach --address on top of #467.

Posted on behalf of @schickling

field	value
agent_identity	dev3.direct.omp.aetn947t
session	dev3.aetn947t
agent_persona	generalist
agent_supervisor	unavailable
agent_tool	OMP
agent_tool_version	18.1.2
agent_runtime	OMP 18.1.2
tooling_profile	dotfiles@7534055