fix(#788): skills show not-found emitted duplicate JSON error envelope; use exit(1) instead of Err propagation

ROADMAP.md

@@ -7735,3 +7735,11 @@ Original filing (2026-04-18): the session emitted `SessionStart hook (completed)
 783. **`claw --output-format json init` success envelope was missing `hint` field; idempotent re-init was not structurally detectable** — dogfooded 2026-05-27 on `32c9276f`. The init JSON envelope had no `hint` field (absent, not null), and no field to distinguish a fresh init from a re-init without checking `created.len() == 0`. Orchestrators had to inspect `created` array length to detect idempotent behavior. Fix: (1) added `hint` field to init JSON envelope — fresh path points at `CLAUDE.md + doctor`; idempotent path says "already initialised, run doctor"; (2) added `already_initialized: bool` field — `true` when `created` and `updated` are both empty (all artifacts skipped). Both test cases (fresh + re-init) covered by `init_json_envelope_has_hint_and_already_initialized_783`. 42 CLI contract tests pass. [SCOPE: claw-code] Source: Jobdori init-envelope probe on `32c9276f`, 2026-05-27.
 
 784. **`claw export` had two opaque arg-error paths returning `error_kind:"unknown"` + `hint:null`** — dogfooded 2026-05-27 on `81fe0ccb` (pinpoint by Gaebal-gajae). `claw export --output` (missing flag value) emitted plain `"missing value for --output"` with no typed prefix; `claw export a.md b.md` (extra positional) emitted plain `"unexpected export argument: second.md"`. Both classified as `unknown+null`. Fix: (1) `--output` missing-value error now uses `missing_flag_value:` prefix + `\n` usage hint; (2) extra positional now uses `unexpected_extra_args:` prefix + `\n` usage hint; (3) classifier `unexpected_extra_args` arm extended to match both `starts_with("unexpected extra arguments")` (prose form, #766) and `starts_with("unexpected_extra_args:")` (typed prefix form, #784). Integration test `export_arg_errors_have_typed_kind_and_hint_784` covers both paths. 43 CLI contract tests pass. [SCOPE: claw-code] Source: Gaebal-gajae pinpoint + Jobdori implementation on `81fe0ccb`, 2026-05-27.
+
+785. **`claw dump` (typo/near-miss for dump-manifests) returned `error_kind:"unknown"` — no classifier arm for `"unknown subcommand:"` prose prefix** — dogfooded 2026-05-27 on `e628b4bb`. Any unknown top-level subcommand that triggers the suggestion path emitted `"unknown subcommand: <x>.\nDid you mean <y>"` but `classify_error_kind` had no arm for that prefix; all fell to the `"unknown"` catch-all. The hint was non-null (the suggestion text was extracted by `split_error_hint`) but `error_kind` was undifferentiated. Fix: added `starts_with("unknown subcommand:")` → `"unknown_subcommand"` arm. Unit test assertion + integration test `unknown_subcommand_returns_typed_kind_785` using `claw dump` as the trigger. 44 CLI contract tests pass. [SCOPE: claw-code] Source: Jobdori subcommand-classifier probe on `e628b4bb`, 2026-05-27.
+
+786. **`claw dump-manifests --manifests-dir` (missing value) and `--manifests-dir=` (empty) both returned `error_kind:"unknown"` + `hint:null`** — dogfooded 2026-05-27 on `87f43347` (pinpoint by Gaebal-gajae). Both missing `--manifests-dir` branches in `parse_dump_manifests_args` emitted plain `"--manifests-dir requires a path"` with no typed prefix; `classify_error_kind` had no matching arm so they fell to `"unknown"`. Fix: both branches now use `missing_flag_value:` prefix + `\n` usage hint. Integration test `dump_manifests_missing_dir_has_typed_kind_and_hint_786` covers both cases. 45 CLI contract tests pass. [SCOPE: claw-code] Source: Gaebal-gajae pinpoint + Jobdori implementation on `87f43347`, 2026-05-27.
+
+787. **`claw --resume /tmp` (directory path) returned `error_kind:"session_load_failed"` + `hint:null`; resume error emission sites didn't apply `fallback_hint_for_error_kind`** — dogfooded 2026-05-27 on `22b423b6`. Two gaps: (1) the OS error `"Is a directory (os error 21)"` had no classifier arm, falling to generic `session_load_failed`; (2) both resume error emission paths (session load at line 3338, command execution at line 3484) called `split_error_hint` but not `fallback_hint_for_error_kind`, so API-layer errors with no `\n` always got `hint:null`. Fix: added `session_path_is_directory` classifier arm for `"Is a directory"` / `"os error 21"` messages; added `fallback_hint_for_error_kind` fallback to both resume error sites; added `session_path_is_directory` and `session_load_failed` to `fallback_hint_for_error_kind`. Unit test + integration test `resume_directory_path_returns_typed_kind_and_hint_787`. 46 CLI contract tests pass. [SCOPE: claw-code] Source: Jobdori resume-path probe on `22b423b6`, 2026-05-27.
+
+788. **`claw --output-format json skills show <not-found>` emitted two JSON objects — one from the skills handler, one duplicate from the top-level error path** — dogfooded 2026-05-27 on `113145a4`. `print_skills` in JSON mode called `println!` to emit the `skill_not_found` error envelope, then returned `Err(...)`. The `?` propagation triggered the top-level error handler which emitted a second `action:"abort"` JSON envelope on stderr. Callers reading both stdout and stderr got two JSON objects with the same `error_kind` but different `action` fields — the first was the authoritative response, the second was a duplicate. Fix: replaced `return Err(...)` with `std::process::exit(1)` after the skills error JSON is emitted, mirroring the existing `is_help_action` guard pattern. Integration test `skills_show_not_found_emits_single_json_object_788` asserts exactly 1 JSON object on stdout and no JSON on stderr. 47 CLI contract tests pass. [SCOPE: claw-code] Source: Jobdori skills double-emission probe on `113145a4`, 2026-05-27.

rust/crates/rusty-claude-cli/src/main.rs

@@ -283,6 +283,9 @@ fn classify_error_kind(message: &str) -> &'static str {
         // error message is "failed to restore session: legacy session is missing workspace
         // binding: ...", so the specific arm must be checked first.
         "legacy_session_no_workspace_binding"
+    } else if message.contains("Is a directory") || message.contains("os error 21") {
+        // #787: --resume given a directory path instead of a .jsonl file
+        "session_path_is_directory"
     } else if message.contains("failed to restore session") {
         "session_load_failed"
     } else if message.contains("unsupported ACP invocation") {
@@ -349,6 +352,9 @@ fn classify_error_kind(message: &str) -> &'static str {
     } else if message.contains("has been removed.") {
         // #765: removed subcommands (login, logout) — hint contains migration guidance
         "removed_subcommand"
+    } else if message.starts_with("unknown subcommand:") {
+        // #785: typo/unknown top-level subcommand (e.g. `claw dump` → did you mean dump-manifests?)
+        "unknown_subcommand"
     } else if message.starts_with("unexpected extra arguments")
         || message.starts_with("unexpected_extra_args:")
     {
@@ -398,6 +404,13 @@ fn fallback_hint_for_error_kind(kind: &str) -> Option<&'static str> {
         "missing_credentials" => {
             Some("Set ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN before running claw.")
         }
+        // #787: session load failures have no \n-delimited hint from the OS error path
+        "session_load_failed" => Some(
+            "Pass a path to a .jsonl session file, not a directory. Managed sessions live in .claw/sessions/.",
+        ),
+        "session_path_is_directory" => Some(
+            "--resume expects a .jsonl session file path, not a directory. Run `claw --output-format json /session list` to list managed sessions.",
+        ),
         _ => None,
     }
 }
@@ -2156,14 +2169,15 @@ fn parse_dump_manifests_args(
         if arg == "--manifests-dir" {
             let value = args
                 .get(index + 1)
-                .ok_or_else(|| String::from("--manifests-dir requires a path"))?;
+                .ok_or_else(|| String::from("missing_flag_value: --manifests-dir requires a path.\nUsage: claw dump-manifests --manifests-dir <path> [--output-format json]"))?;
             manifests_dir = Some(PathBuf::from(value));
             index += 2;
             continue;
         }
         if let Some(value) = arg.strip_prefix("--manifests-dir=") {
             if value.is_empty() {
-                return Err(String::from("--manifests-dir requires a path"));
+                // #786: empty --manifests-dir= is also a missing value
+                return Err(String::from("missing_flag_value: --manifests-dir requires a path.\nUsage: claw dump-manifests --manifests-dir <path> [--output-format json]"));
             }
             manifests_dir = Some(PathBuf::from(value));
             index += 1;
@@ -3323,7 +3337,10 @@ fn resume_session(session_path: &Path, commands: &[String], output_format: CliOu
                 // #77: classify session load errors for downstream consumers
                 let full_message = format!("failed to restore session: {error}");
                 let kind = classify_error_kind(&full_message);
-                let (short_reason, hint) = split_error_hint(&full_message);
+                let (short_reason, inline_hint) = split_error_hint(&full_message);
+                // #787: fall back to kind-derived hint when message has no \n delimiter
+                let hint =
+                    inline_hint.or_else(|| fallback_hint_for_error_kind(kind).map(String::from));
                 eprintln!(
                     "{}",
                     serde_json::json!({
@@ -3468,7 +3485,10 @@ fn resume_session(session_path: &Path, commands: &[String], output_format: CliOu
                     // hardcoded "resume_command_error" + prose in the error field
                     let full_error = error.to_string();
                     let error_kind = classify_error_kind(&full_error);
-                    let (short_reason, hint) = split_error_hint(&full_error);
+                    let (short_reason, inline_hint) = split_error_hint(&full_error);
+                    // #787: fall back to kind-derived hint when error has no \n delimiter
+                    let hint = inline_hint
+                        .or_else(|| fallback_hint_for_error_kind(error_kind).map(String::from));
                     eprintln!(
                         "{}",
                         serde_json::json!({
@@ -6313,12 +6333,10 @@ impl LiveCli {
                 let is_help_action = result.get("action").and_then(|v| v.as_str()) == Some("help");
                 println!("{}", serde_json::to_string_pretty(&result)?);
                 if is_error && !is_help_action {
-                    return Err(result
-                        .get("message")
-                        .and_then(|v| v.as_str())
-                        .unwrap_or("skills command failed")
-                        .to_string()
-                        .into());
+                    // #788: the error JSON is already emitted above; returning Err here
+                    // would cause the top-level handler to emit a second error envelope.
+                    // Exit directly to signal failure without a duplicate envelope.
+                    std::process::exit(1);
                 }
             }
         }
@@ -13005,10 +13023,20 @@ mod tests {
             classify_error_kind("failed to restore session: file not found"),
             "session_load_failed"
         );
+        // #787: directory-as-session-path gets its own kind (precedes generic session_load_failed)
+        assert_eq!(
+            classify_error_kind("failed to restore session: Is a directory (os error 21)"),
+            "session_path_is_directory"
+        );
         assert_eq!(
             classify_error_kind("unrecognized argument `--foo` for subcommand `doctor`"),
             "cli_parse"
         );
+        // #785: unknown top-level subcommand (typo or unrecognised command)
+        assert_eq!(
+            classify_error_kind("unknown subcommand: dump.\nDid you mean     dump-manifests"),
+            "unknown_subcommand"
+        );
         assert_eq!(
             classify_error_kind("unsupported ACP invocation. Use `claw acp`."),
             "unsupported_acp_invocation"

rust/crates/rusty-claude-cli/tests/output_format_contract.rs

@@ -2502,3 +2502,266 @@ fn export_arg_errors_have_typed_kind_and_hint_784() {
         "hint must reference export usage, got: {h2:?}"
     );
 }
+
+#[test]
+fn unknown_subcommand_returns_typed_kind_785() {
+    // #785: `claw dump` (a near-miss for dump-manifests) returned error_kind:"unknown"
+    // because the classifier had no arm for "unknown subcommand:" prose prefix.
+    // Fix: added "unknown_subcommand" arm in classify_error_kind.
+    let root = unique_temp_dir("unknown-subcommand-785");
+    fs::create_dir_all(&root).expect("temp dir");
+    std::process::Command::new("git")
+        .args(["init", "-q"])
+        .current_dir(&root)
+        .output()
+        .ok();
+
+    // "dump" is close enough to "dump-manifests" to trigger the typo suggestion path
+    let output = run_claw(&root, &["--output-format", "json", "dump"], &[]);
+    assert!(!output.status.success(), "unknown subcommand should fail");
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    let j: serde_json::Value = stderr
+        .lines()
+        .find(|l| l.trim_start().starts_with('{'))
+        .and_then(|l| serde_json::from_str(l).ok())
+        .expect("unknown subcommand should emit JSON error");
+    assert_eq!(
+        j["error_kind"], "unknown_subcommand",
+        "unknown subcommand should return unknown_subcommand kind, got {:?}",
+        j["error_kind"]
+    );
+    // hint should point at the suggestion and/or --help
+    let hint = j["hint"].as_str().unwrap_or("");
+    assert!(
+        hint.contains("dump-manifests") || hint.contains("--help") || hint.contains("claw"),
+        "hint should reference the suggested subcommand or help, got: {hint:?}"
+    );
+}
+
+#[test]
+fn dump_manifests_missing_dir_has_typed_kind_and_hint_786() {
+    // #786: `claw dump-manifests --manifests-dir` (no value) and `--manifests-dir=` (empty)
+    // both emitted plain "--manifests-dir requires a path" with error_kind:"unknown" + hint:null.
+    // Fix: use missing_flag_value: prefix + \n usage hint.
+    let root = unique_temp_dir("dump-manifests-missing-dir-786");
+    fs::create_dir_all(&root).expect("temp dir");
+    std::process::Command::new("git")
+        .args(["init", "-q"])
+        .current_dir(&root)
+        .output()
+        .ok();
+
+    // Case 1: --manifests-dir with no following value (next arg is --output-format)
+    let out1 = run_claw(
+        &root,
+        &[
+            "--output-format",
+            "json",
+            "dump-manifests",
+            "--manifests-dir",
+            "--output-format",
+            "json",
+        ],
+        &[],
+    );
+    assert!(!out1.status.success());
+    let stderr1 = String::from_utf8_lossy(&out1.stderr);
+    let j1: serde_json::Value = stderr1
+        .lines()
+        .find(|l| l.trim_start().starts_with('{'))
+        .and_then(|l| serde_json::from_str(l).ok())
+        .expect("missing --manifests-dir value should emit JSON error");
+    assert_eq!(
+        j1["error_kind"], "missing_flag_value",
+        "missing --manifests-dir value should be missing_flag_value, got {:?}",
+        j1["error_kind"]
+    );
+    let h1 = j1["hint"]
+        .as_str()
+        .expect("missing_flag_value must have hint (#786)");
+    assert!(
+        h1.contains("dump-manifests") || h1.contains("manifests-dir"),
+        "hint should reference dump-manifests usage, got: {h1:?}"
+    );
+
+    // Case 2: --manifests-dir= with empty value
+    let out2 = run_claw(
+        &root,
+        &[
+            "--output-format",
+            "json",
+            "dump-manifests",
+            "--manifests-dir=",
+        ],
+        &[],
+    );
+    assert!(!out2.status.success());
+    let stderr2 = String::from_utf8_lossy(&out2.stderr);
+    let j2: serde_json::Value = stderr2
+        .lines()
+        .find(|l| l.trim_start().starts_with('{'))
+        .and_then(|l| serde_json::from_str(l).ok())
+        .expect("empty --manifests-dir= should emit JSON error");
+    assert_eq!(
+        j2["error_kind"], "missing_flag_value",
+        "empty --manifests-dir= should be missing_flag_value, got {:?}",
+        j2["error_kind"]
+    );
+    let h2 = j2["hint"]
+        .as_str()
+        .expect("missing_flag_value must have hint (#786)");
+    assert!(!h2.is_empty(), "hint must not be empty");
+}
+
+#[test]
+fn resume_directory_path_returns_typed_kind_and_hint_787() {
+    // #787: `claw --resume /tmp` (directory instead of .jsonl file) returned
+    // error_kind:"session_load_failed" + hint:null. The OS error "Is a directory (os error 21)"
+    // had no \n delimiter so split_error_hint returned None, and the resume error path
+    // didn't call fallback_hint_for_error_kind.
+    // Fix: (1) added session_path_is_directory classifier arm for os error 21;
+    //      (2) wired fallback_hint_for_error_kind into both resume error emission sites.
+    let root = unique_temp_dir("resume-dir-787");
+    fs::create_dir_all(&root).expect("temp dir");
+    std::process::Command::new("git")
+        .args(["init", "-q"])
+        .current_dir(&root)
+        .output()
+        .ok();
+
+    // Pass the root directory itself as the session path
+    let output = run_claw(
+        &root,
+        &[
+            "--output-format",
+            "json",
+            "--resume",
+            root.to_str().unwrap(),
+            "/status",
+        ],
+        &[],
+    );
+    assert!(
+        !output.status.success(),
+        "resume with directory should fail"
+    );
+    let stderr = String::from_utf8_lossy(&output.stderr);
+    let j: serde_json::Value = stderr
+        .lines()
+        .find(|l| l.trim_start().starts_with('{'))
+        .and_then(|l| serde_json::from_str(l).ok())
+        .expect("resume with directory should emit JSON error");
+    assert_eq!(
+        j["error_kind"], "session_path_is_directory",
+        "directory resume path should return session_path_is_directory, got {:?}",
+        j["error_kind"]
+    );
+    let hint = j["hint"]
+        .as_str()
+        .expect("session_path_is_directory must have hint (#787)");
+    assert!(
+        hint.contains(".jsonl") || hint.contains("session") || hint.contains("file"),
+        "hint should explain expected path format, got: {hint:?}"
+    );
+}
+
+#[test]
+fn skills_show_not_found_emits_single_json_object_788() {
+    // #788: `claw --output-format json skills show no-such-skill` emitted TWO JSON objects:
+    // one from the skills handler (action:"show", status:"error") and a second from the
+    // top-level error handler (action:"abort"). The skills handler returned Err() after
+    // printing its JSON, which caused the ? propagation to trigger a duplicate envelope.
+    // Fix: exit(1) directly after the skills JSON is emitted instead of returning Err.
+    let root = unique_temp_dir("skills-show-double-emit-788");
+    fs::create_dir_all(&root).expect("temp dir");
+    std::process::Command::new("git")
+        .args(["init", "-q"])
+        .current_dir(&root)
+        .output()
+        .ok();
+
+    let output = run_claw(
+        &root,
+        &[
+            "--output-format",
+            "json",
+            "skills",
+            "show",
+            "no-such-skill-xyz",
+        ],
+        &[],
+    );
+    assert!(!output.status.success(), "skills show unknown should fail");
+    // Skills handler emits JSON to stdout; the duplicate was on stderr from the main error path.
+    // After fix: stdout has 1 JSON object, stderr has none (no duplicate).
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    let stderr = String::from_utf8_lossy(&output.stderr);
+
+    // Count JSON objects in stdout — must be exactly 1
+    let json_objects: Vec<serde_json::Value> = {
+        let mut objects = Vec::new();
+        let mut remaining = stdout.trim();
+        while !remaining.is_empty() {
+            match serde_json::from_str::<serde_json::Value>(remaining) {
+                Ok(v) => {
+                    objects.push(v);
+                    break;
+                }
+                Err(_) => {
+                    // Try finding a complete JSON object
+                    if let Some(pos) = remaining.find('{') {
+                        remaining = &remaining[pos..];
+                        let mut depth = 0i32;
+                        let mut end = 0;
+                        for (i, c) in remaining.char_indices() {
+                            match c {
+                                '{' => depth += 1,
+                                '}' => {
+                                    depth -= 1;
+                                    if depth == 0 {
+                                        end = i + 1;
+                                        break;
+                                    }
+                                }
+                                _ => {}
+                            }
+                        }
+                        if end > 0 {
+                            if let Ok(v) = serde_json::from_str(&remaining[..end]) {
+                                objects.push(v);
+                                remaining = remaining[end..].trim_start();
+                            } else {
+                                break;
+                            }
+                        } else {
+                            break;
+                        }
+                    } else {
+                        break;
+                    }
+                }
+            }
+        }
+        objects
+    };
+
+    assert_eq!(
+        json_objects.len(),
+        1,
+        "skills show not-found must emit exactly 1 JSON object on stdout, got {}. stdout: {} stderr: {}",
+        json_objects.len(),
+        stdout,
+        stderr
+    );
+    // Verify stderr has no duplicate error JSON (the pre-#788 bug was a second abort envelope here)
+    let stderr_has_json = stderr.lines().any(|l| l.trim_start().starts_with('{'));
+    assert!(
+        !stderr_has_json,
+        "stderr must have no duplicate JSON error envelope, got: {stderr}"
+    );
+    assert_eq!(
+        json_objects[0]["error_kind"], "skill_not_found",
+        "single JSON object must have skill_not_found error_kind"
+    );
+    assert_eq!(json_objects[0]["status"], "error");
+}