HTTP API: recover

The input of recover.orphans: how old a stray must be, and whether to act.

use majordomus_cli::capability::builtin::recover::RecoverOrphansInput;

// The wire form the shell tool, an MCP client or an HTTP POST sends.
let act: RecoverOrphansInput =
    serde_json::from_str(r#"{"older_than_seconds":43200,"check":false}"#).unwrap();
assert_eq!(act.older_than_seconds, 43_200);
assert!(!act.check);

// `check` defaults to true, and that direction is deliberate: this capability deletes
// files, and a caller that forgets the field gets a plan rather than a sweep.
let forgot: RecoverOrphansInput =
    serde_json::from_str(r#"{"older_than_seconds":43200}"#).unwrap();
assert!(forgot.check, "the safe value is the default one");

// The threshold has no default at all. `session.stranded_after` is a policy value, and
// a reader that carried its own copy would be a second place the number lives.
assert!(serde_json::from_str::<RecoverOrphansInput>(r#"{"check":true}"#).is_err());

// Unknown fields are refused rather than ignored: a caller that misspells `check` is
// told so instead of having a sweep silently run.
assert!(serde_json::from_str::<RecoverOrphansInput>(
    r#"{"older_than_seconds":1,"chek":true}"#).is_err());

What one sweep found and what it did about it.

The counts are derived from strays rather than accumulated beside it, so a reader can check the report against itself and a surface that renders the list cannot disagree with the surface that renders the total.

use majordomus_cli::capability::builtin::recover::RecoverOrphansResult;

let plan: RecoverOrphansResult = serde_json::from_str(r#"{
    "older_than_seconds": 43200, "check": true, "strays": [],
    "removable": 0, "removed": 0, "unmeasurable": 0
}"#).unwrap();
// a check never removes anything, whatever it found
assert_eq!(plan.removed, 0);
assert!(plan.check);

One stray file, its verdict, and the evidence that produced it.

Every field that decided something is carried, because the rule this command is shaped around requires the value that decided a verdict to be visible before the verdict acts: a surface that printed "orphan" without the age, the episode and the file that already holds it would be asking to be trusted rather than read.

use majordomus_cli::capability::builtin::recover::{Stray, StrayKind, StrayVerdict};
use serde_json::json;

let s: Stray = serde_json::from_value(json!({
    "path": ".ai/repo/sessions/.tmp.a1b2c3",
    "kind": "publish_temp",
    "verdict": "orphan",
    "age_seconds": 90_000,
    "session_id": "s-0007",
    "published_at": ".ai/repo/sessions/2026-09-11--s-0007.md",
    "removable": true,
    "removed": false,
})).unwrap();
assert_eq!(s.verdict, StrayVerdict::Orphan);
assert_eq!(s.kind, StrayKind::PublishTemp);
// removable and removed are different facts: a check run reports the first and never
// the second, which is what makes `--check` readable as a plan rather than a report.
assert!(s.removable && !s.removed);

// and an unmeasurable one carries no age at all, rather than a zero that would read as
// "brand new" to anything that compared it with a threshold
let u: Stray = serde_json::from_value(json!({
    "path": ".mj-stage.xyz", "kind": "staging_dir", "verdict": "unmeasurable",
    "removable": false, "removed": false,
})).unwrap();
assert!(u.age_seconds.is_none());

What kind of stray a path is, decided by where it is and how it is named rather than by what is in it. The content decides the verdict; this decides which question to ask.

The word a kind is reported under is also the word it is read back from, and a word this version does not know is refused rather than read as the nearest kind:

use majordomus_cli::capability::builtin::recover::StrayKind;
for kind in [StrayKind::PublishTemp, StrayKind::RenameTemp, StrayKind::StagingDir] {
    let word = serde_json::to_value(kind).unwrap();
    assert_eq!(serde_json::from_value::<StrayKind>(word).unwrap(), kind);
}
assert!(serde_json::from_value::<StrayKind>(serde_json::json!("temp")).is_err());

What this stray is, decided by reading it.

The five words are lib/recover.sh's, deliberately: a person who has read the command's output should not have to learn the same five facts twice because a second surface chose its own vocabulary.

That vocabulary is closed. Every verdict reads back as itself, and there is no sixth word: a surface that invents one gets an error rather than a verdict nobody meant.

use majordomus_cli::capability::builtin::recover::StrayVerdict::{self, *};
let all = [Live, Orphan, Incomplete, Foreign, Unmeasurable];
let words: Vec<&str> = all.iter().map(|v| v.as_str()).collect();
assert_eq!(words, ["live", "orphan", "incomplete", "foreign", "unmeasurable"]);
for v in all {
    let word = serde_json::json!(v.as_str());
    assert_eq!(serde_json::from_value::<StrayVerdict>(word).unwrap(), v);
}
assert!(serde_json::from_value::<StrayVerdict>(serde_json::json!("stale")).is_err());