feat(catalog): declare the authoritative PTY registry - #66
Merged
schickling-assistant merged 1 commit intoJul 29, 2026
Merged
Conversation
A catalog's session registry was only expressible as ambient environment:
`effective_pty_root` took an exported `PTY_ROOT`, else `<catalog>/pty`. A host
that wants one shared registry across catalogs therefore has to export the root
into every process that will ever read the catalog, and a reader that misses it
resolves a different registry — `doctor` then reports a live agent's task as
dead, which is the wrong diagnosis from the one command whose job is diagnosis.
`<catalog>/catalog.kdl` lets the folder say it itself:
catalog {
pty-root "/run/agents/pty"
}
Resolution becomes exported `PTY_ROOT` → declaration → `<catalog>/pty`. Ambient
still wins so an eval run keeps its short decoupled partition, and a catalog
that declares nothing is byte-for-byte unchanged.
`st2 env`/`pty`/`shell` follow the declaration but not the ambient value: they
describe the catalog to bus-aware tools rather than echo the caller's registry.
The file is not a spec — `catalog` is not an `agent` node and `parse_spec`
rejects it as a top-level node — so a declaring catalog is still dispatched as a
catalog, pinned by a test. A mistyped field would resolve silently back to
`<catalog>/pty` and reproduce the exact symptom this fixes, so the field set is
closed and `st2 validate` fails it; the runtime path stays on the native root
rather than inventing one mid-teardown.
Contributor
|
@schickling-assistant this should be per-machine, so I think it should be in: I'll prepare a PR and add you as reviewer. |
28 tasks
schickling
added
area:catalog
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #31.
This is the bounded custom-PTY-root half of #45, rebased onto current
main.The teardown half of that older PR was already implemented independently on
main, so it is intentionally absent here.
Problem
The supervisor can run with an explicit shared
PTY_ROOT, while an independentreader such as
st2 pty,st2 env, orst2 doctorfalls back to<catalog>/pty. The same catalog then has two answers for where its live tasksare. In the current dotfiles rollout this made the supervisor's seats visible in
the global registry while
st2 pty list --jsonreturned[].Contract
An optional
<catalog>/catalog.kdldeclares the registry:Resolution is:
PTY_ROOT;<catalog>/pty.The ambient override remains first so hermetic eval partitions keep working.
st2 validaterejects unknown catalog fields, preventing a typo from silentlyrecreating a split registry.
Verification
main:st2 pty list --jsonreturned[];st2-root-contract-e2esession.cargo test --lib --test catalog_config: 152 library tests and 3 catalogintegration tests passed.
nix flake check -L: exit 0; all six x86_64-linux checks passed.git diff --check origin/main...HEAD: passed.No live catalog, service, or PTY registry was changed.
Posted on behalf of @schickling
agent_nameagent_session_idagent_toolagent_tool_versionagent_runtimeagent_modelruntime_profileskills_manifestworktreemachinetooling_profile