From bc823e6b4b8f834ae947ffa6ff61f97439a978c6 Mon Sep 17 00:00:00 2001 From: Willow Sparks Date: Sat, 21 Nov 2026 02:02:48 +0000 Subject: [PATCH 1/6] fix(session): write child artifacts to the agent's artifacts tree The artifact dir came from `dirname(dirname(log))/session-artifacts/`. That holds for a top-level session, whose log sits in `sessions/`, but a child's log already sits inside `session-artifacts//`, so the child appended a second tree under its parent's partition and its own child a third. `session::artifacts` resolves the tree once: the nearest ancestor named `session-artifacts` within the two levels a partition can nest, else the session dir's sibling. The bounded probe keeps `session-artifacts-archive` from matching. `list --check` and `sessions --check` report every nested root with its size, read-only, so an operator can verify duplicates before removing anything. Refs #71 --- .changes/nested-session-artifacts-roots.md | 1 + crates/pa-cli/src/command_registry.rs | 6 +- crates/pa-cli/src/daemon_command.rs | 80 ++++++++++ .../tests/print_inline_subagents_e2e.rs | 12 +- crates/pa-core/src/session/artifacts.rs | 150 ++++++++++++++++++ crates/pa-core/src/session/manager/queries.rs | 10 +- crates/pa-core/src/session/mod.rs | 1 + crates/pa-core/src/session_engine/mod.rs | 9 +- crates/pa-daemon/src/scheduled_jobs.rs | 7 +- 9 files changed, 251 insertions(+), 25 deletions(-) create mode 100644 .changes/nested-session-artifacts-roots.md create mode 100644 crates/pa-core/src/session/artifacts.rs diff --git a/.changes/nested-session-artifacts-roots.md b/.changes/nested-session-artifacts-roots.md new file mode 100644 index 000000000..643126d96 --- /dev/null +++ b/.changes/nested-session-artifacts-roots.md @@ -0,0 +1 @@ +- Child sessions write artifacts to the agent's `session-artifacts` tree instead of nesting a second tree under their parent's partition, and `list --check` / `sessions --check` report every nested root with its size. diff --git a/crates/pa-cli/src/command_registry.rs b/crates/pa-cli/src/command_registry.rs index 39fe99d48..ee0c7b937 100644 --- a/crates/pa-cli/src/command_registry.rs +++ b/crates/pa-cli/src/command_registry.rs @@ -50,20 +50,22 @@ pub const COMMAND_SPECS: &[CommandSpec] = &[ CommandSpec::new(&["agents"], "agents", "Search and open sessions"), CommandSpec::new( &["list"], - "list [--all] [--json]", + "list [--all] [--check] [--json]", "List agents", ) .options(&[ "-a, --all Include saved agents", + "--check Report nested session-artifacts roots", "--json Print JSON", ]), CommandSpec::new( &["sessions"], - "sessions [--all] [--json]", + "sessions [--all] [--check] [--json]", "Show agent status, activity, and usage", ) .options(&[ "-a, --all Include saved agents", + "--check Report nested session-artifacts roots", "--json Print JSON", ]), CommandSpec::new( diff --git a/crates/pa-cli/src/daemon_command.rs b/crates/pa-cli/src/daemon_command.rs index 3c23393a1..39e6f30c7 100644 --- a/crates/pa-cli/src/daemon_command.rs +++ b/crates/pa-cli/src/daemon_command.rs @@ -19,6 +19,7 @@ use crate::daemon_session_list::{ struct ParsedDaemonCommand { socket_path: PathBuf, json: bool, + check: bool, positionals: Vec, /// `--help`/`-h` becomes the internal no-op `help` command, exactly like the TS /// `runDaemonClientCommand` fallthrough. @@ -32,6 +33,10 @@ pub(crate) fn run_daemon_command(command: &str, args: &[String]) -> Result<()> { if parsed.help { return Ok(()); } + if parsed.check { + run_artifacts_check(parsed.json); + return Ok(()); + } let mut client = DaemonClient::connect(&parsed.socket_path)?; match command { "list" => run_list(&mut client, &parsed.positionals, parsed.json), @@ -49,6 +54,7 @@ pub(crate) fn run_daemon_command(command: &str, args: &[String]) -> Result<()> { fn parse_daemon_command(command: &str, args: &[String]) -> Result { let mut socket_path = default_socket_path(); let mut json = false; + let mut check = false; let mut positionals: Vec = Vec::new(); let mut passthrough = false; let mut index = 0; @@ -71,6 +77,7 @@ fn parse_daemon_command(command: &str, args: &[String]) -> Result Result>(), + "totalBytes": on_disk, + })); + return; + } + if nested.is_empty() { + println!("No nested session-artifacts roots under {}", root.display()); + return; + } + println!( + "Nested session-artifacts roots under {}: {}", + root.display(), + nested.len() + ); + for entry in &nested { + println!( + "{:>10} {}", + format_bytes(entry.bytes), + entry.path.display() + ); + } + println!( + "\n{:>10} on disk in {} nested roots", + format_bytes(on_disk), + nested.len() + ); +} + +/// A byte count with a binary unit, two decimals above a kibibyte. +fn format_bytes(bytes: u64) -> String { + const UNITS: [&str; 4] = ["KiB", "MiB", "GiB", "TiB"]; + if bytes < 1024 { + return format!("{bytes} B"); + } + let mut value = bytes as f64 / 1024.0; + let mut unit = 0; + while value >= 1024.0 && unit + 1 < UNITS.len() { + value /= 1024.0; + unit += 1; + } + format!("{value:.2} {}", UNITS[unit]) +} + fn default_socket_path() -> PathBuf { crate::config::resolve_daemon_socket_path(None) } diff --git a/crates/pa-cli/tests/print_inline_subagents_e2e.rs b/crates/pa-cli/tests/print_inline_subagents_e2e.rs index 9a9a413d9..ae467bddd 100644 --- a/crates/pa-cli/tests/print_inline_subagents_e2e.rs +++ b/crates/pa-cli/tests/print_inline_subagents_e2e.rs @@ -344,17 +344,17 @@ fn print_inline_subagents_wait_for_replies_and_combine_them() { "the child finished its task: {text}" ); // The exit disposal proof: the child's kernel was disposed with - // its final namespace snapshot BEFORE the process exited. The - // child's artifact dir follows the shared - // `dirname(sessionDir)/session-artifacts/` layout, so - // it lands beside the child's session dir (under the parent's - // artifacts tree), not inside it. + // its final namespace snapshot BEFORE the process exited. A child + // partition is keyed by session id in the agent's artifacts tree, + // never in a second `session-artifacts` tree nested under the + // parent's partition. let child_id = child_files[0] .file_stem() .and_then(|stem| stem.to_str()) .expect("the child session id") .to_string(); - let snapshot = artifacts + let snapshot = lane + .agent_dir .join("session-artifacts") .join(&child_id) .join("kernel-state.dill"); diff --git a/crates/pa-core/src/session/artifacts.rs b/crates/pa-core/src/session/artifacts.rs new file mode 100644 index 000000000..10abae298 --- /dev/null +++ b/crates/pa-core/src/session/artifacts.rs @@ -0,0 +1,150 @@ +//! Per-session artifact partitions: one directory per session under the agent's artifacts tree. + +use std::path::{Path, PathBuf}; + +const ARTIFACTS_DIR_NAME: &str = "session-artifacts"; + +/// The artifacts tree that owns a session dir. A session dir already inside the tree (an RLM +/// child's partition under `//`) belongs to that tree; a top-level session +/// dir's tree is its sibling `session-artifacts` directory. The probe is bounded to the two +/// levels a partition can nest, so an unrelated directory deeper in the path never matches. +#[must_use] +pub fn session_artifacts_root(session_dir: &Path) -> Option { + for ancestor in session_dir.ancestors().skip(1).take(2) { + if ancestor + .file_name() + .is_some_and(|name| name == ARTIFACTS_DIR_NAME) + { + return Some(ancestor.to_path_buf()); + } + } + Some(session_dir.parent()?.join(ARTIFACTS_DIR_NAME)) +} + +/// One session's artifact partition: the agent-level artifacts tree keyed by session id, so a +/// child never nests a second `session-artifacts` tree under its parent's partition. +#[must_use] +pub fn session_artifact_dir(session_dir: &Path, session_id: &str) -> Option { + Some(session_artifacts_root(session_dir)?.join(session_id)) +} + +/// A `session-artifacts` tree found inside another one, with the bytes its files occupy. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct NestedArtifactsRoot { + pub path: PathBuf, + pub bytes: u64, +} + +/// Every `session-artifacts` root below `artifacts_root`, each sized over its whole subtree. +/// Read-only: nothing under the tree is created, renamed, or removed. +#[must_use] +pub fn nested_artifacts_roots(artifacts_root: &Path) -> Vec { + let mut nested = Vec::new(); + collect_nested_roots(artifacts_root, &mut nested); + nested.sort_by(|left, right| left.path.cmp(&right.path)); + nested +} + +fn collect_nested_roots(dir: &Path, nested: &mut Vec) { + let Ok(entries) = std::fs::read_dir(dir) else { + return; + }; + for entry in entries.flatten() { + if !entry.file_type().is_ok_and(|file_type| file_type.is_dir()) { + continue; + } + let path = entry.path(); + if path + .file_name() + .is_some_and(|name| name == ARTIFACTS_DIR_NAME) + { + nested.push(NestedArtifactsRoot { + bytes: subtree_bytes(&path), + path: path.clone(), + }); + } + collect_nested_roots(&path, nested); + } +} + +fn subtree_bytes(dir: &Path) -> u64 { + let Ok(entries) = std::fs::read_dir(dir) else { + return 0; + }; + let mut total = 0; + for entry in entries.flatten() { + let Ok(file_type) = entry.file_type() else { + continue; + }; + if file_type.is_dir() { + total += subtree_bytes(&entry.path()); + } else if file_type.is_file() { + total += entry.metadata().map_or(0, |metadata| metadata.len()); + } + } + total +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn top_level_session_partitions_beside_the_session_tree() { + let dir = Path::new("/agent/sessions"); + assert_eq!( + session_artifacts_root(dir), + Some(PathBuf::from("/agent/session-artifacts")) + ); + assert_eq!( + session_artifact_dir(dir, "s1"), + Some(PathBuf::from("/agent/session-artifacts/s1")) + ); + } + + #[test] + fn child_partitions_use_the_agents_artifacts_tree_not_a_nested_one() { + let child_dir = Path::new("/agent/session-artifacts/parent/sub-1"); + assert_eq!( + session_artifacts_root(child_dir), + Some(PathBuf::from("/agent/session-artifacts")) + ); + assert_eq!( + session_artifact_dir(child_dir, "child-session"), + Some(PathBuf::from("/agent/session-artifacts/child-session")) + ); + } + + #[test] + fn nested_roots_are_reported_with_the_bytes_below_them() { + let agent = tempfile::tempdir().expect("agent dir"); + let nested = agent + .path() + .join("session-artifacts/parent/session-artifacts/child"); + std::fs::create_dir_all(nested.join("session-artifacts")).expect("nested tree"); + std::fs::write(nested.join("kernel-state.dill"), [0_u8; 8]).expect("file"); + std::fs::write(nested.join("session-artifacts/snapshot.dill"), [0_u8; 4]).expect("file"); + + let roots = nested_artifacts_roots(&agent.path().join("session-artifacts")); + assert_eq!(roots.len(), 2, "both nested roots: {roots:?}"); + assert_eq!( + roots[0].path, + nested.parent().expect("child tree"), + "the shallow root sorts first" + ); + assert_eq!(roots[1].path, nested.join("session-artifacts")); + assert_eq!(roots[0].bytes, 12, "the shallow root counts its subtree"); + assert_eq!(roots[1].bytes, 4, "the deep root counts only its own files"); + } + + #[test] + fn an_unrelated_ancestor_name_is_not_an_artifacts_tree() { + let dir = Path::new("/srv/session-artifacts-archive/agent/sessions"); + assert_eq!( + session_artifact_dir(dir, "s1"), + Some(PathBuf::from( + "/srv/session-artifacts-archive/agent/session-artifacts/s1" + )) + ); + } +} diff --git a/crates/pa-core/src/session/manager/queries.rs b/crates/pa-core/src/session/manager/queries.rs index 4be69c2c2..de1031a01 100644 --- a/crates/pa-core/src/session/manager/queries.rs +++ b/crates/pa-core/src/session/manager/queries.rs @@ -2,6 +2,7 @@ //! history snapshot, the branch scans, the window-backed reads, and the getters. use super::{FileEntry, Path, SessionHeader, SessionManager, SessionTree}; +use crate::session::artifacts; impl SessionManager { /// The active compacted context without hydrating old message bodies: an @@ -310,18 +311,13 @@ impl SessionManager { self.window = None; Ok(()) } - /// Session artifact directory (`dirname(sessionDir)/session-artifacts/`); + /// Session artifact directory (the agent's artifacts tree, keyed by session id); /// only persisted sessions have one. #[must_use] pub fn get_session_artifact_dir(&self) -> Option { self.persist - .then(|| { - self.session_dir - .parent() - .map(|root| root.join("session-artifacts")) - }) + .then(|| artifacts::session_artifact_dir(&self.session_dir, &self.session_id)) .flatten() - .map(|root| root.join(&self.session_id)) } #[must_use] diff --git a/crates/pa-core/src/session/mod.rs b/crates/pa-core/src/session/mod.rs index 100e480d1..d4c890304 100644 --- a/crates/pa-core/src/session/mod.rs +++ b/crates/pa-core/src/session/mod.rs @@ -1,4 +1,5 @@ //! Session entry parsing, migration, context reconstruction, and tree. +pub mod artifacts; pub mod discovery; pub mod manager; pub mod manager_ext; diff --git a/crates/pa-core/src/session_engine/mod.rs b/crates/pa-core/src/session_engine/mod.rs index 5df99682b..abf9d568f 100644 --- a/crates/pa-core/src/session_engine/mod.rs +++ b/crates/pa-core/src/session_engine/mod.rs @@ -814,13 +814,12 @@ pub(crate) fn session_message_to_loop(message: &SessionAgentMessage) -> Option`). +/// Session artifact directory implied by a conversation-log path: the agent's artifacts tree, +/// keyed by the log's session id. #[must_use] pub fn session_artifact_dir_for_log(log: &std::path::Path) -> Option { - let id = log.file_stem()?.to_string_lossy().to_string(); - let artifacts_root = log.parent()?.parent()?.join("session-artifacts"); - Some(artifacts_root.join(id)) + let id = log.file_stem()?.to_string_lossy(); + crate::session::artifacts::session_artifact_dir(log.parent()?, &id) } /// Rows that fail the conversion drop. diff --git a/crates/pa-daemon/src/scheduled_jobs.rs b/crates/pa-daemon/src/scheduled_jobs.rs index 4e009717d..e15a25def 100644 --- a/crates/pa-daemon/src/scheduled_jobs.rs +++ b/crates/pa-daemon/src/scheduled_jobs.rs @@ -27,12 +27,9 @@ use crate::worker::{QueuedItem, SessionCore, Worker}; /// turn must not pin the dispatch lane forever). const FIRE_SETTLE_TIMEOUT_MS: u64 = 15 * 60 * 1000; -/// The session-artifact directory for one session file: `/../session-artifacts/`. +/// The session-artifact directory for one session file: the agent's artifacts tree keyed by id. pub(crate) fn session_artifact_dir(session_file: &Path, session_id: &str) -> Option { - session_file - .parent()? - .parent() - .map(|root| root.join("session-artifacts").join(session_id)) + pa_core::session::artifacts::session_artifact_dir(session_file.parent()?, session_id) } /// The scheduler hooks: how a claimed job reaches this session. -- knotmirror 0.0.1 From 36452f653f661ca176d5e5824db1294cb7bf5e89 Mon Sep 17 00:00:00 2001 From: Willow Sparks Date: Sat, 21 Nov 2026 02:22:44 +0000 Subject: [PATCH 2/6] fix(cli): resolve --check from the listing's session dir Review follow-ups on #73: - `--check` derives its tree from the session dir the listing scans, so `PRIME_AGENT_SESSION_DIR` (and any future `--session-dir` plumbing) reports the tree the daemon actually uses instead of `/session-artifacts`. - The report says `outermost roots only`, because a root's size covers its subtree, and a report test pins both the lines and the total. - `--check` is a text report only. The unrequested JSON schema is dropped rather than added to the public CLI contract. - The subagent e2e asserts the other half of the fix: no second `session-artifacts` tree is created under the parent's partition. - The `session_artifacts_root` doc now states what the two-level probe actually does, including that legacy depth-3 session dirs keep their existing nested partition, and the scan doc notes that sizes skip symlinks and treat unreadable dirs as zero. --- crates/pa-cli/src/daemon_command.rs | 100 ++++++++++++------ .../tests/print_inline_subagents_e2e.rs | 7 ++ crates/pa-core/src/session/artifacts.rs | 18 +++- 3 files changed, 89 insertions(+), 36 deletions(-) diff --git a/crates/pa-cli/src/daemon_command.rs b/crates/pa-cli/src/daemon_command.rs index 39e6f30c7..b26d746a9 100644 --- a/crates/pa-cli/src/daemon_command.rs +++ b/crates/pa-cli/src/daemon_command.rs @@ -6,6 +6,7 @@ use std::path::{Path, PathBuf}; use anyhow::{anyhow, bail, Result}; +use pa_core::session::artifacts::NestedArtifactsRoot; use pa_types::daemon::DaemonCommand; use serde_json::{json, Value}; @@ -34,7 +35,10 @@ pub(crate) fn run_daemon_command(command: &str, args: &[String]) -> Result<()> { return Ok(()); } if parsed.check { - run_artifacts_check(parsed.json); + if parsed.json { + bail!("--check prints a text report; it is not a JSON command"); + } + run_artifacts_check()?; return Ok(()); } let mut client = DaemonClient::connect(&parsed.socket_path)?; @@ -111,12 +115,30 @@ fn parse_daemon_command(command: &str, args: &[String]) -> Result Result<()> { + let sessions_dir = pa_daemon::paths::sessions_dir(&crate::config::get_agent_dir())?; + let root = pa_core::session::artifacts::session_artifacts_root(&sessions_dir) + .ok_or_else(|| anyhow!("{} has no parent directory", sessions_dir.display()))?; let nested = pa_core::session::artifacts::nested_artifacts_roots(&root); - // A root inside another root is already counted by its ancestor. - let on_disk: u64 = nested + print!("{}", artifacts_check_report(&root, &nested)); + Ok(()) +} + +/// The `--check` report: one line per nested root, then the space those roots hold. A root's +/// size covers its whole subtree, so the total adds only the roots that are not inside another +/// listed root; the deeper lines are already counted by their parents. +fn artifacts_check_report(root: &Path, nested: &[NestedArtifactsRoot]) -> String { + use std::fmt::Write as _; + + if nested.is_empty() { + return format!( + "No nested session-artifacts roots under {}\n", + root.display() + ); + } + let outermost: u64 = nested .iter() .filter(|entry| { !nested @@ -125,41 +147,25 @@ fn run_artifacts_check(json: bool) { }) .map(|entry| entry.bytes) .sum(); - if json { - print_json(&json!({ - "root": root.display().to_string(), - "nestedRoots": nested - .iter() - .map(|entry| json!({ - "path": entry.path.display().to_string(), - "bytes": entry.bytes, - })) - .collect::>(), - "totalBytes": on_disk, - })); - return; - } - if nested.is_empty() { - println!("No nested session-artifacts roots under {}", root.display()); - return; - } - println!( - "Nested session-artifacts roots under {}: {}", + let mut report = format!( + "Nested session-artifacts roots under {}: {}\n", root.display(), nested.len() ); - for entry in &nested { - println!( + for entry in nested { + let _ = writeln!( + report, "{:>10} {}", format_bytes(entry.bytes), entry.path.display() ); } - println!( - "\n{:>10} on disk in {} nested roots", - format_bytes(on_disk), - nested.len() + let _ = writeln!( + report, + "\n{:>10} outermost roots only", + format_bytes(outermost) ); + report } /// A byte count with a binary unit, two decimals above a kibibyte. @@ -751,6 +757,36 @@ mod tests { assert_eq!(missing.to_string(), "--daemon-socket requires a value"); } + #[test] + fn the_check_report_sizes_the_outermost_roots_only() { + let nested = [ + NestedArtifactsRoot { + path: PathBuf::from("/agent/session-artifacts/p/session-artifacts"), + bytes: 1536, + }, + NestedArtifactsRoot { + path: PathBuf::from( + "/agent/session-artifacts/p/session-artifacts/c/session-artifacts", + ), + bytes: 512, + }, + ]; + assert_eq!( + artifacts_check_report(Path::new("/agent/session-artifacts"), &nested), + concat!( + "Nested session-artifacts roots under /agent/session-artifacts: 2\n", + " 1.50 KiB /agent/session-artifacts/p/session-artifacts\n", + " 512 B /agent/session-artifacts/p/session-artifacts/c/session-artifacts\n", + "\n", + " 1.50 KiB outermost roots only\n", + ) + ); + assert_eq!( + artifacts_check_report(Path::new("/agent/session-artifacts"), &[]), + "No nested session-artifacts roots under /agent/session-artifacts\n" + ); + } + #[test] fn separator_passes_through_only_for_send_and_cron() { let send = parse_daemon_command("send", &args(&["target", "--", "hi", "there"])).unwrap(); diff --git a/crates/pa-cli/tests/print_inline_subagents_e2e.rs b/crates/pa-cli/tests/print_inline_subagents_e2e.rs index ae467bddd..96359c269 100644 --- a/crates/pa-cli/tests/print_inline_subagents_e2e.rs +++ b/crates/pa-cli/tests/print_inline_subagents_e2e.rs @@ -363,6 +363,13 @@ fn print_inline_subagents_wait_for_replies_and_combine_them() { "the disposed kernel's final snapshot landed at {}", snapshot.display() ); + // The other half of the fix: the child wrote nothing into a second + // tree under its parent's partition. + assert!( + !artifacts.join("session-artifacts").exists(), + "no nested artifacts tree under the parent's partition: {}", + artifacts.display() + ); } } diff --git a/crates/pa-core/src/session/artifacts.rs b/crates/pa-core/src/session/artifacts.rs index 10abae298..2139dd3cf 100644 --- a/crates/pa-core/src/session/artifacts.rs +++ b/crates/pa-core/src/session/artifacts.rs @@ -4,10 +4,17 @@ use std::path::{Path, PathBuf}; const ARTIFACTS_DIR_NAME: &str = "session-artifacts"; -/// The artifacts tree that owns a session dir. A session dir already inside the tree (an RLM -/// child's partition under `//`) belongs to that tree; a top-level session -/// dir's tree is its sibling `session-artifacts` directory. The probe is bounded to the two -/// levels a partition can nest, so an unrelated directory deeper in the path never matches. +/// The artifacts tree that owns a session dir: the nearest ancestor named `session-artifacts`, +/// probed at distances one and two, else the dir's sibling `session-artifacts` directory. +/// +/// The bound matches the two layouts a live session dir can have. A top-level dir is +/// `/` (distance one is the agent dir, which is not the tree). A current child +/// dir is exactly `/session-artifacts//` (distance two is the tree). A dir +/// written by the pre-fix formula, `/session-artifacts//session-artifacts/`, +/// resolves to the inner tree at distance two, so those children keep their existing partition +/// instead of moving. Probing further would not help: an unrelated ancestor named +/// `session-artifacts` at distance one or two still matches, which is why this stays a probe of +/// the session dir's own surroundings rather than a search up the whole path. #[must_use] pub fn session_artifacts_root(session_dir: &Path) -> Option { for ancestor in session_dir.ancestors().skip(1).take(2) { @@ -37,6 +44,9 @@ pub struct NestedArtifactsRoot { /// Every `session-artifacts` root below `artifacts_root`, each sized over its whole subtree. /// Read-only: nothing under the tree is created, renamed, or removed. +/// +/// A size counts regular files only: symlinks are skipped, so a link cycle cannot be followed, +/// and an unreadable directory contributes zero rather than failing the report. #[must_use] pub fn nested_artifacts_roots(artifacts_root: &Path) -> Vec { let mut nested = Vec::new(); -- knotmirror 0.0.1 From d36e16b4ee0afa40f29842c189f48b0662615c0d Mon Sep 17 00:00:00 2001 From: Willow Sparks Date: Sat, 21 Nov 2026 02:25:21 +0000 Subject: [PATCH 3/6] fix(cli): refuse stale arguments alongside --check `--check` reads the tree before any daemon request, so a leftover operand (an `-a`, or a `--session-dir` the listing does not accept today) would have been dropped on the floor while the report still printed. Refuse it with the argument instead. --- crates/pa-cli/src/daemon_command.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/crates/pa-cli/src/daemon_command.rs b/crates/pa-cli/src/daemon_command.rs index b26d746a9..09c4df4b7 100644 --- a/crates/pa-cli/src/daemon_command.rs +++ b/crates/pa-cli/src/daemon_command.rs @@ -38,6 +38,12 @@ pub(crate) fn run_daemon_command(command: &str, args: &[String]) -> Result<()> { if parsed.json { bail!("--check prints a text report; it is not a JSON command"); } + if !parsed.positionals.is_empty() { + bail!( + "--check takes no other arguments: {}", + parsed.positionals.join(" ") + ); + } run_artifacts_check()?; return Ok(()); } -- knotmirror 0.0.1 From bef7d763ab0e72c5727fd037b1f1e55c3e506701 Mon Sep 17 00:00:00 2001 From: Willow Sparks Date: Sat, 21 Nov 2026 02:35:17 +0000 Subject: [PATCH 4/6] docs(cli): state what --check does and does not follow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review follow-ups on #73: - `help list` / `help sessions` now say `--check` is a text report that takes no other option, and that it follows only the session dir an unqualified listing scans: it does not consult `--session-dir`, `PRIME_AGENT_CODING_AGENT_SESSION_DIR`, or the settings `sessionDir`, because the daemon's no-argument listing ignores those too. The usage line no longer advertises `--all --check --json` as one combinable form. - `session_artifacts_root` describes the shapes it actually meets: a current child dir matches at distance two, a dir inside a tree the old formula left behind matches that inner tree at distance one, and a deeper legacy dir falls back to its own sibling `session-artifacts` — which is where the pre-fix formula already wrote, so nothing moves. --- crates/pa-cli/src/command_registry.rs | 16 ++++++++++++---- crates/pa-core/src/session/artifacts.rs | 22 ++++++++++++---------- 2 files changed, 24 insertions(+), 14 deletions(-) diff --git a/crates/pa-cli/src/command_registry.rs b/crates/pa-cli/src/command_registry.rs index ee0c7b937..3ef3fd1fd 100644 --- a/crates/pa-cli/src/command_registry.rs +++ b/crates/pa-cli/src/command_registry.rs @@ -50,22 +50,30 @@ pub const COMMAND_SPECS: &[CommandSpec] = &[ CommandSpec::new(&["agents"], "agents", "Search and open sessions"), CommandSpec::new( &["list"], - "list [--all] [--check] [--json]", + "list [--all] [--json] | list --check", "List agents", ) + .description( + "--check follows only the session dir an unqualified listing scans. It does not consult \ + --session-dir, PRIME_AGENT_CODING_AGENT_SESSION_DIR, or the settings sessionDir.", + ) .options(&[ "-a, --all Include saved agents", - "--check Report nested session-artifacts roots", + "--check Report nested session-artifacts roots (text report only; no other options)", "--json Print JSON", ]), CommandSpec::new( &["sessions"], - "sessions [--all] [--check] [--json]", + "sessions [--all] [--json] | sessions --check", "Show agent status, activity, and usage", ) + .description( + "--check follows only the session dir an unqualified listing scans. It does not consult \ + --session-dir, PRIME_AGENT_CODING_AGENT_SESSION_DIR, or the settings sessionDir.", + ) .options(&[ "-a, --all Include saved agents", - "--check Report nested session-artifacts roots", + "--check Report nested session-artifacts roots (text report only; no other options)", "--json Print JSON", ]), CommandSpec::new( diff --git a/crates/pa-core/src/session/artifacts.rs b/crates/pa-core/src/session/artifacts.rs index 2139dd3cf..08fc3a2f4 100644 --- a/crates/pa-core/src/session/artifacts.rs +++ b/crates/pa-core/src/session/artifacts.rs @@ -4,17 +4,19 @@ use std::path::{Path, PathBuf}; const ARTIFACTS_DIR_NAME: &str = "session-artifacts"; -/// The artifacts tree that owns a session dir: the nearest ancestor named `session-artifacts`, -/// probed at distances one and two, else the dir's sibling `session-artifacts` directory. +/// The artifacts tree that owns a session dir: the nearest ancestor named `session-artifacts` +/// at distance one or two, else the dir's sibling `session-artifacts` directory. /// -/// The bound matches the two layouts a live session dir can have. A top-level dir is -/// `/` (distance one is the agent dir, which is not the tree). A current child -/// dir is exactly `/session-artifacts//` (distance two is the tree). A dir -/// written by the pre-fix formula, `/session-artifacts//session-artifacts/`, -/// resolves to the inner tree at distance two, so those children keep their existing partition -/// instead of moving. Probing further would not help: an unrelated ancestor named -/// `session-artifacts` at distance one or two still matches, which is why this stays a probe of -/// the session dir's own surroundings rather than a search up the whole path. +/// Every live shape is covered. A top-level dir is `/`, whose sibling is the +/// tree. A current child dir is `/session-artifacts//`, whose distance-two +/// ancestor is the tree. A dir inside a tree the old formula left behind, +/// `/session-artifacts//session-artifacts/`, matches that inner tree at +/// distance one. A deeper legacy dir, such as `/session-artifacts///`, +/// matches neither and falls back to `/session-artifacts///session-artifacts` +/// — which is where the pre-fix formula already put that session's artifacts, so it stays on its +/// existing partition without moving. The probe reads the session dir's own surroundings rather +/// than searching the path: an unrelated ancestor named `session-artifacts` at distance one or +/// two still matches, and a deeper one never does. #[must_use] pub fn session_artifacts_root(session_dir: &Path) -> Option { for ancestor in session_dir.ancestors().skip(1).take(2) { -- knotmirror 0.0.1 From 530c350f446375c3a2ec194436b8f12a7bc1fca6 Mon Sep 17 00:00:00 2001 From: Willow Sparks Date: Sat, 21 Nov 2026 02:37:24 +0000 Subject: [PATCH 5/6] docs(cli): say --check takes no other listing options `--daemon-socket` (and `--socket`) are consumed before the report runs and never used, so "no other options" was not literally true. The help now scopes the restriction to listing options. --- crates/pa-cli/src/command_registry.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/pa-cli/src/command_registry.rs b/crates/pa-cli/src/command_registry.rs index 3ef3fd1fd..d5635fa2e 100644 --- a/crates/pa-cli/src/command_registry.rs +++ b/crates/pa-cli/src/command_registry.rs @@ -59,7 +59,7 @@ pub const COMMAND_SPECS: &[CommandSpec] = &[ ) .options(&[ "-a, --all Include saved agents", - "--check Report nested session-artifacts roots (text report only; no other options)", + "--check Report nested session-artifacts roots (text report only; no other listing options)", "--json Print JSON", ]), CommandSpec::new( @@ -73,7 +73,7 @@ pub const COMMAND_SPECS: &[CommandSpec] = &[ ) .options(&[ "-a, --all Include saved agents", - "--check Report nested session-artifacts roots (text report only; no other options)", + "--check Report nested session-artifacts roots (text report only; no other listing options)", "--json Print JSON", ]), CommandSpec::new( -- knotmirror 0.0.1 From b0e82d311bf9524264378d0a50c27c2789a1b7f4 Mon Sep 17 00:00:00 2001 From: Willow Sparks Date: Sat, 21 Nov 2026 03:00:48 +0000 Subject: [PATCH 6/6] test(cli): declare the list and sessions help as native contracts `--check` has no TypeScript counterpart, so its help lines diverge by design and the differential corpus compared them against TS. Both pages now have declared native contracts with fixtures under `tests/fixtures/native-cli-contract/`, the same shape as `help`, `help package`, and `help update`: the TS snapshot pins the reference output, the native snapshot pins ours, and the contract also runs when no TS binary is installed. --- crates/pa-cli/tests/differential_cli.rs | 20 +++++++++++++++---- .../native-cli-contract/native-list-help.txt | 11 ++++++++++ .../native-sessions-help.txt | 11 ++++++++++ .../native-cli-contract/ts-list-help.txt | 8 ++++++++ .../native-cli-contract/ts-sessions-help.txt | 8 ++++++++ 5 files changed, 54 insertions(+), 4 deletions(-) create mode 100644 crates/pa-cli/tests/fixtures/native-cli-contract/native-list-help.txt create mode 100644 crates/pa-cli/tests/fixtures/native-cli-contract/native-sessions-help.txt create mode 100644 crates/pa-cli/tests/fixtures/native-cli-contract/ts-list-help.txt create mode 100644 crates/pa-cli/tests/fixtures/native-cli-contract/ts-sessions-help.txt diff --git a/crates/pa-cli/tests/differential_cli.rs b/crates/pa-cli/tests/differential_cli.rs index a28c78093..7173594da 100644 --- a/crates/pa-cli/tests/differential_cli.rs +++ b/crates/pa-cli/tests/differential_cli.rs @@ -459,10 +459,12 @@ fn sandbox(prefix: &str) -> PathBuf { } // These are declared native contracts, not stream fallbacks. Help snapshots are -// derived from each command registry and its formatter. Native update/package -// behavior is documented in docs/legacy-upgrade-contract.md. args.rs tests pin -// bounded u32 and unknown-option validation; model list declares only [search], -// not a --json option. ACP shares the native non-interactive @file rejection. +// derived from each command registry and its formatter. `list` and `sessions` +// declare the `--check` artifacts report, which has no TypeScript counterpart. +// Native update/package behavior is documented in docs/legacy-upgrade-contract.md. +// args.rs tests pin bounded u32 and unknown-option validation; model list +// declares only [search], not a --json option. ACP shares the native +// non-interactive @file rejection. // TypeScript reference: archive/typescript-2026-10-18, commit // 239dbe344fcaf671af9898906ff952be73995614. fn declared_output_matches( @@ -507,6 +509,14 @@ fn declared_native_contract( ts.is_none_or(|ts| declared_output_matches(ts, 0, include_str!("fixtures/native-cli-contract/ts-help.txt"), "", roots)) && declared_output_matches(native, 0, include_str!("fixtures/native-cli-contract/native-help.txt"), "", roots), ), + ["help", "list"] => Some( + ts.is_none_or(|ts| declared_output_matches(ts, 0, include_str!("fixtures/native-cli-contract/ts-list-help.txt"), "", roots)) + && declared_output_matches(native, 0, include_str!("fixtures/native-cli-contract/native-list-help.txt"), "", roots), + ), + ["help", "sessions"] => Some( + ts.is_none_or(|ts| declared_output_matches(ts, 0, include_str!("fixtures/native-cli-contract/ts-sessions-help.txt"), "", roots)) + && declared_output_matches(native, 0, include_str!("fixtures/native-cli-contract/native-sessions-help.txt"), "", roots), + ), ["help", "package"] => Some( ts.is_none_or(|ts| declared_output_matches(ts, 0, include_str!("fixtures/native-cli-contract/ts-package-help.txt"), "", roots)) && declared_output_matches(native, 0, include_str!("fixtures/native-cli-contract/native-package-help.txt"), "", roots), @@ -577,6 +587,8 @@ fn native_cli_contract_fixtures() { &["--help"][..], &["-h"], &["help"], + &["help", "list"], + &["help", "sessions"], &["help", "package"], &["help", "update"], &["--mode", "rpc", "@file.txt"], diff --git a/crates/pa-cli/tests/fixtures/native-cli-contract/native-list-help.txt b/crates/pa-cli/tests/fixtures/native-cli-contract/native-list-help.txt new file mode 100644 index 000000000..d365ed546 --- /dev/null +++ b/crates/pa-cli/tests/fixtures/native-cli-contract/native-list-help.txt @@ -0,0 +1,11 @@ +Usage: + prime-agent list [--all] [--json] | list --check + +List agents. + +--check follows only the session dir an unqualified listing scans. It does not consult --session-dir, PRIME_AGENT_CODING_AGENT_SESSION_DIR, or the settings sessionDir. + +Options: + -a, --all Include saved agents + --check Report nested session-artifacts roots (text report only; no other listing options) + --json Print JSON diff --git a/crates/pa-cli/tests/fixtures/native-cli-contract/native-sessions-help.txt b/crates/pa-cli/tests/fixtures/native-cli-contract/native-sessions-help.txt new file mode 100644 index 000000000..236f58ab9 --- /dev/null +++ b/crates/pa-cli/tests/fixtures/native-cli-contract/native-sessions-help.txt @@ -0,0 +1,11 @@ +Usage: + prime-agent sessions [--all] [--json] | sessions --check + +Show agent status, activity, and usage. + +--check follows only the session dir an unqualified listing scans. It does not consult --session-dir, PRIME_AGENT_CODING_AGENT_SESSION_DIR, or the settings sessionDir. + +Options: + -a, --all Include saved agents + --check Report nested session-artifacts roots (text report only; no other listing options) + --json Print JSON diff --git a/crates/pa-cli/tests/fixtures/native-cli-contract/ts-list-help.txt b/crates/pa-cli/tests/fixtures/native-cli-contract/ts-list-help.txt new file mode 100644 index 000000000..1578b407a --- /dev/null +++ b/crates/pa-cli/tests/fixtures/native-cli-contract/ts-list-help.txt @@ -0,0 +1,8 @@ +Usage: + prime-agent list [--all] [--json] + +List agents. + +Options: + -a, --all Include saved agents + --json Print JSON diff --git a/crates/pa-cli/tests/fixtures/native-cli-contract/ts-sessions-help.txt b/crates/pa-cli/tests/fixtures/native-cli-contract/ts-sessions-help.txt new file mode 100644 index 000000000..2038d8471 --- /dev/null +++ b/crates/pa-cli/tests/fixtures/native-cli-contract/ts-sessions-help.txt @@ -0,0 +1,8 @@ +Usage: + prime-agent sessions [--all] [--json] + +Show agent status, activity, and usage. + +Options: + -a, --all Include saved agents + --json Print JSON -- knotmirror 0.0.1