`st2 up --once --agent` silently reconciles the whole catalog

[schickling-assistant]

--agent is only consulted inside the --materialize-only branch, but clap also accepts it with --once. The one-shot path then calls the unselected whole-catalog reconciler and can launch every missing sibling while appearing targeted.

This was observed on st2 0.1.0+33d159b and remains accepted on current main 58c4851 after #50. #50 provides the correct exact task selector (--task); this issue is about making the older materialization-only selector fail closed outside its valid mode.

Minimal deterministic reproduction

A two-agent catalog uses harmless exec tasks (true) plus a recording pty shim that returns an empty list. Run:

st2 up --catalog "$catalog" --host repro --once --agent one

Both repro.one.work and repro.two.work appear under launched, and both workspaces are materialized. The shim records one pty list --json; no real PTY registry is involved.

The source-level reproducer passes at 33d159b:

running 1 test
test agent_selector_does_not_scope_once_reconciliation ... ok

test result: ok. 1 passed; 0 failed

Expected

--agent is a materialization-only selector. Using it without --materialize-only must refuse before workspace writes or runner inspection, and the diagnostic should point operators to --task for targeted one-shot reconciliation.

Actual

--agent is silently ignored by --once, which performs whole-catalog discovery, materialization, runner listing, planning, and execution.

RCA

src/main.rs::up filters found.specs by agent only inside if materialize_only { ... return Ok(()) }. The later if once branch calls unfiltered up_once(root, ...). Clap declares neither requires = "materialize_only" nor an equivalent runtime refusal.

Principled fix

Make --agent require --materialize-only, keep --task as the sole selected reconcile API, and add CLI proofs that the invalid combination refuses before workspace mutation and pty list.

Posted on behalf of @schickling

field	value
agent_name	co2-bear
agent_session_id	a078daee-6f98-4916-91a8-d21291407789
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/mnx8agbdq3wiyb6vz63lhgscgazkrn98-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/5r69m9k2llmri3na81518zx0a7y0d3cn-agent-skills-corpus/share/agent-skills/manifest.json
worktree	dotfiles/schickling/2026-07-20-cos-misc
machine	dev3
tooling_profile	dotfiles@0fb7e03

[schickling-assistant]

Closing as already fixed by #50. I initially inspected its CLI declaration and selected reconcile path but missed the fail-closed dispatch guard added in the same merge:

if agent.is_some() && !materialize_only {
    anyhow::bail!("--agent requires --materialize-only");
}

Verified provenance: git blame attributes the guard to merge 58c48515. The incident binary was 33d159b, which predates #50; current main refuses before up(...), so before workspace writes and runner inspection. The actionable local fix is to update the installed st2 and use --task for selected one-shot reconciliation.

Posted on behalf of @schickling

field	value
agent_name	co2-bear
agent_session_id	a078daee-6f98-4916-91a8-d21291407789
agent_tool	Codex CLI
agent_tool_version	0.145.0
agent_runtime	Codex CLI 0.145.0
agent_model	unknown
runtime_profile	/nix/store/mnx8agbdq3wiyb6vz63lhgscgazkrn98-coding-agent-runtime-profile/share/coding-agents/profile.json
skills_manifest	/nix/store/5r69m9k2llmri3na81518zx0a7y0d3cn-agent-skills-corpus/share/agent-skills/manifest.json
worktree	st2/schickling-assistant/2026-07-30-agent-selector-fail-closed
machine	dev3
tooling_profile	dotfiles@0fb7e03