arkaos 4.49.0 → 5.1.0

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v4.49.0 — 89 agents, 17 departments, 333 skills, 298 commands, 19 ADRs.
+> v5.1.0 — 89 agents, 17 departments, 333 skills, 298 commands, 19 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-4.49.0
+5.1.0

package/core/governance/harness_scanner.py

@@ -19,10 +19,12 @@ with a letter grade; it prints nothing, exits nothing, and touches
 nothing. The ``--fix`` path is a later slice and must be able to trust
 that a scan never mutated what it measured.
 
-Never raises on hostile input. A settings file that is truncated,
+Never raises on hostile CONTENT. A settings file that is truncated,
 binary, or full of nulls is a FINDING, not a traceback — a scanner that
 dies on the config it was pointed at reports nothing at all, which is
-the worst possible outcome for a security tool.
+the worst possible outcome for a security tool. A config it could not
+READ is the opposite case and raises deliberately, so the caller can
+refuse it by name instead of grading what it never opened; see `scan`.
 
 Engine behind ``npx arkaos shield`` and the ``doctor`` advisory section.
 """
@@ -39,6 +41,34 @@ from pathlib import Path
 _MAX_FILE_BYTES = 2 * 1024 * 1024
 
 
+def is_readable_file(path: Path) -> bool:
+    """Is `path` a regular file — and RAISE when we could not find out.
+
+    `Path.is_file()` cannot carry this contract across interpreters.
+    Python 3.14 reimplemented it to delegate to `os.path.isfile()`,
+    which swallows every OSError and answers False, so an unreadable
+    config read as "not there": the scanner counted zero files and
+    printed "Grade A (100/100) — nothing to report." for a directory it
+    never opened, on exactly the fresh machines and CI containers where
+    no venv exists and an ambient python3 is selected. The root and the
+    config file reach this call as `root / name`, and their two refusals
+    are built on this raise. `_check_hook_script` repeats the same
+    raising stat but renders EACCES as a HIGH `hook-script-unreadable`
+    finding, which grades B and exits 0 — the same discipline, and
+    deliberately NOT a refusal, since a refusal here means exit 2 (QG C3
+    r9 and r10, Francisca, reproduced side by side on 3.13 and 3.14;
+    vocabulary corrected at r15 by Marta, who executed the exit code).
+
+    ENOENT and ENOTDIR mean the file is absent, which is a real answer.
+    Every other errno — EACCES, EPERM, ELOOP — means we could not look,
+    which is not an answer and must never be graded.
+    """
+    try:
+        return stat.S_ISREG(path.stat().st_mode)
+    except (FileNotFoundError, NotADirectoryError):
+        return False
+
+
 class Severity(StrEnum):
     """How much a finding costs. Declaration order is report order."""
 
@@ -421,33 +451,69 @@ def _check_hook_command(command: str, where: str) -> list[Finding]:
 
 
 def _check_hook_script(command: str, where: str) -> list[Finding]:
-    """The file the hook executes — does it exist, can anyone rewrite it?"""
+    """The file the hook executes — does it exist, can anyone rewrite it?
+
+    ONE stat, three named outcomes. `path.exists()` could not carry this:
+    it raises on 3.13 and answers False on 3.14, and the raise reached
+    the per-file backstop, which throws away every finding already found
+    for that settings file and leaves one LOW `scanner-error`. Measured
+    on one config holding a CRITICAL dangerous-allow plus a hook whose
+    target sat in a mode-000 directory: 3.14 graded F (51/100, 3
+    findings, exit 2), 3.13 graded **A (98/100), exit 0**, rules
+    `['scanner-error']` — and that is the JSON `installer/doctor.js`
+    reads. One unstat-able hook target laundered every CRITICAL in the
+    file (QG C3 r10, Francisca B1, reproduced side by side).
+    """
     path = _script_path(command)
     if path is None:
         return []
-    if not path.exists():
-        return [Finding(
-            rule="hook-script-missing",
-            severity=Severity.HIGH,
-            where=where,
-            detail=f"the hook points at {path}, which does not exist — the "
-                   f"hook silently does nothing.",
-            fix="Restore the script, or remove the hook. If it is an "
-                "ArkaOS hook, `npx arkaos install --force` reinstalls it.",
-        )]
-    if _is_group_or_world_writable(path):
-        return [Finding(
-            rule="hook-world-writable",
-            severity=Severity.HIGH,
-            where=where,
-            detail=f"{path} is writable by group or others — any local "
-                   f"process can rewrite what the agent executes on every "
-                   f"tool call.",
-            fix=f"chmod go-w {path}",
-        )]
+    try:
+        mode = path.stat().st_mode
+    except (FileNotFoundError, NotADirectoryError):
+        return [_hook_script_missing(path, where)]
+    except OSError as exc:
+        return [_hook_script_unreadable(path, where, exc)]
+    if _is_group_or_world_writable(mode):
+        return [_hook_world_writable(path, where)]
     return []
 
 
+def _hook_script_missing(path: Path, where: str) -> Finding:
+    return Finding(
+        rule="hook-script-missing",
+        severity=Severity.HIGH,
+        where=where,
+        detail=f"the hook points at {path}, which does not exist — the "
+               f"hook silently does nothing.",
+        fix="Restore the script, or remove the hook. If it is an "
+            "ArkaOS hook, `npx arkaos install --force` reinstalls it.",
+    )
+
+
+def _hook_script_unreadable(path: Path, where: str, exc: OSError) -> Finding:
+    return Finding(
+        rule="hook-script-unreadable",
+        severity=Severity.HIGH,
+        where=where,
+        detail=f"the hook points at {path}, which could not be read "
+               f"({exc.strerror}) — its permissions and its contents are "
+               f"UNAUDITED. Treat as unaudited, not as clean.",
+        fix=f"Make {path} readable by the account that runs the agent, or "
+            f"point the hook somewhere auditable.",
+    )
+
+
+def _hook_world_writable(path: Path, where: str) -> Finding:
+    return Finding(
+        rule="hook-world-writable",
+        severity=Severity.HIGH,
+        where=where,
+        detail=f"{path} is writable by group or others — any local process "
+               f"can rewrite what the agent executes on every tool call.",
+        fix=f"chmod go-w {path}",
+    )
+
+
 def _script_path(command: str) -> Path | None:
     """The leading absolute path of a hook command, when it has one.
 
@@ -465,11 +531,13 @@ def _script_path(command: str) -> Path | None:
         return Path(first)
 
 
-def _is_group_or_world_writable(path: Path) -> bool:
-    try:
-        mode = path.stat().st_mode
-    except OSError:
-        return False
+def _is_group_or_world_writable(mode: int) -> bool:
+    """Mode bits only. The stat that produced them owns the error path.
+
+    This used to stat the file itself and swallow OSError into False —
+    "we could not tell" answering "safe", the exact direction a security
+    check must never take (QG C3 r10, Francisca B1).
+    """
     return bool(mode & (stat.S_IWGRP | stat.S_IWOTH))
 
 
@@ -755,7 +823,17 @@ def _safe_scan_file(
 
 
 def scan(root: Path) -> ScanReport:
-    """Scan a harness config tree. Read-only. Never raises."""
+    """Scan a harness config tree. Read-only.
+
+    RAISES, deliberately, when a config cannot be READ: an unreadable
+    root or candidate propagates its OSError so the caller can refuse it
+    by name. Callers must use `harness_scanner_cli._safe_scan`, which is
+    built to catch exactly that. Per-FILE failures do not raise — they
+    are absorbed by `_safe_scan_file` into a `scanner-error` finding, so
+    one malformed config cannot end the scan (QG C3 r10, Francisca M2:
+    "Never raises" became false when the refusal family was built on the
+    raise, and the two docstrings said opposite things).
+    """
     try:
         root = Path(root).expanduser()
     except (RuntimeError, ValueError):
@@ -769,7 +847,7 @@ def scan(root: Path) -> ScanReport:
     for names, scanner in groups:
         for name in names:
             path = root / name
-            if path.is_file():
+            if is_readable_file(path):
                 report.files_scanned += 1
                 report.findings.extend(_safe_scan_file(scanner, path, name))
     report.findings.sort(key=lambda f: (-PENALTY[f.severity], f.rule))

package/core/governance/harness_scanner_cli.py

@@ -8,14 +8,24 @@ permissions themselves live in the user settings. A tool that reports a
 clean bill of health because it only looked at one of them is worse than
 no tool.
 
-Exit codes: 0 = grade A/B, 1 = grade C/D, 2 = grade F or a CRITICAL
-finding. CI can gate on it.
+Exit codes: 0 = grade A/B, 1 = grade C/D, 2 = grade F, a CRITICAL
+finding, or a REFUSAL. A refusal is a root we could not read: any root
+the operator NAMED, every root when none was readable, or ANY root —
+the defaults included — that raised while we scanned it (mode 000, a
+root-owned config, a container uid mismatch). Only a MISSING default
+root is exempt: a fresh machine has no ``~/.claude``, so it is noted on
+stderr and the readable roots set the code; failing there would break
+every CI container. CI can gate on the exit code. A refusal is never a
+pass: a config we never opened cannot be graded, and saying "nothing to
+report" about it would be the clean-looking run this tool exists to
+prevent.
 """
 
 from __future__ import annotations
 
 import argparse
 import json
+import stat
 import sys
 from pathlib import Path
 
@@ -36,8 +46,17 @@ _ICON = {
 
 
 def merge(reports: list[ScanReport]) -> ScanReport:
-    """One grade for the operator, not one per file they must add up."""
-    merged = ScanReport(root=reports[0].root if reports else Path("."))
+    """One grade for the operator, not one per file they must add up.
+
+    Merging nothing raises. An empty list produced a grade-A 100/100
+    report, so every caller that forgot to check got a clean bill of
+    health for a scan that never happened — twice in this module, and
+    the next caller would inherit it (QG C3 r7, Francisca M1). Grading
+    nothing is a programming error, not a passing grade.
+    """
+    if not reports:
+        raise ValueError("merge() of no reports: nothing was scanned")
+    merged = ScanReport(root=reports[0].root)
     for report in reports:
         merged.files_scanned += report.files_scanned
         for finding in report.findings:
@@ -98,7 +117,69 @@ def _roots(args: argparse.Namespace) -> list[Path]:
     return [Path.home() / ".claude", Path.cwd()]
 
 
-def main(argv: list[str] | None = None) -> int:
+def _partition_roots(
+    args: argparse.Namespace,
+) -> tuple[list[Path], list[Path], bool]:
+    """Split the requested roots, and say whether the OPERATOR named them.
+
+    Provenance travels with the partition rather than being re-derived
+    from ``args.path`` at each use: the wording and the exit code both
+    depend on it, and two derivations five lines apart is the structural
+    precondition of every defect this module produced across six rounds
+    (QG C3 r7, Francisca M3).
+    """
+    requested = _roots(args)
+    readable = [root for root in requested if _looks_like_dir(root)]
+    unreadable = [root for root in requested if root not in readable]
+    return readable, unreadable, bool(args.path)
+
+
+def _looks_like_dir(root: Path) -> bool:
+    """Is `root` a directory we should try to scan?
+
+    "We could not tell" must answer YES, so the root reaches `_safe_scan`
+    and comes back as a REFUSAL. Answering NO would file it under
+    "skipped", which for a DEFAULT root exits 0 — a clean run over a
+    config nobody read. `Path.is_dir()` cannot express that: it raises on
+    3.13 (an unhandled traceback out of `main`) and swallows on 3.14
+    (silently skipped), so neither interpreter produced the refusal
+    (QG C3 r9, Francisca B1, sibling of the scan() probe).
+    """
+    try:
+        return stat.S_ISDIR(root.stat().st_mode)
+    except (FileNotFoundError, NotADirectoryError):
+        return False  # genuinely absent — the exemption case
+    except OSError:
+        return True  # cannot tell: let _safe_scan refuse it by name
+
+
+def _skipped_notice(readable: list[Path], skipped: list[Path],
+                    named: bool) -> str:
+    """Name every requested root that was never opened.
+
+    A root the operator NAMED and we silently dropped is a clean bill of
+    health for something we never read: `shield ~/.claude/settings.json`
+    — the file rather than its directory, a normal invocation — was
+    answered with "Grade A (100/100) — nothing to report." on the read-only
+    path and with a bare exit 2 on --fix (QG C3 r5, Francisca B2).
+
+    REFUSED is used exactly when the run will exit 2 for this reason, so
+    the word and the exit code never disagree (QG C3 r6, Francisca B1).
+    A missing DEFAULT root is a note instead: a fresh machine has no
+    ~/.claude and must not fail CI over it. Written to stderr so
+    `--json` stdout stays parseable.
+    """
+    paths = ", ".join(str(root) for root in skipped)
+    subject = ("a readable directory" if len(skipped) == 1
+               else "readable directories")
+    if not readable:
+        return f"REFUSED: no readable config root — {paths}"
+    if named:
+        return f"REFUSED: not {subject} — {paths}"
+    return f"note: skipped, not {subject} — {paths}"
+
+
+def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="arkaos shield",
         description=(
@@ -107,7 +188,13 @@ def main(argv: list[str] | None = None) -> int:
             "injection, unpinned MCP servers, prompt injection in "
             "instruction files."
         ),
-        epilog="Exit: 0 = A/B, 1 = C/D, 2 = F or any CRITICAL finding.",
+        epilog=(
+            "Exit: 0 = A/B, 1 = C/D, 2 = F, any CRITICAL finding, or a "
+            "root we could not read — any root YOU named, every root "
+            "when none was readable, or any root that raised while we "
+            "scanned it. Only a MISSING default root (~/.claude on a "
+            "fresh machine) is noted on stderr instead of failing the run."
+        ),
     )
     parser.add_argument(
         "path", nargs="*",
@@ -117,14 +204,139 @@ def main(argv: list[str] | None = None) -> int:
         "--json", action="store_true", dest="as_json",
         help="Machine-readable output.",
     )
+    _add_fix_arguments(parser)
+    return parser
+
+
+def _add_fix_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--fix", action="store_true",
+        help=(
+            "Plan the mechanical fixes (dangerous-command allow rules, "
+            "missing deny list). Prints every finding it cannot fix and "
+            "why — unscoped rules need your pattern, so they are named, "
+            "never dropped. Writes nothing without --apply."
+        ),
+    )
+    parser.add_argument(
+        "--apply", action="store_true",
+        help="With --fix: write the changes, after a timestamped backup.",
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
     args = parser.parse_args(argv)
+    if args.apply and not args.fix:
+        # Silently degrading a destructive flag into a read-only scan is
+        # a trap: the operator believes they wrote (QG C3 r1, Francisca M1).
+        parser.error("--apply requires --fix")
+
+    roots, skipped, named = _partition_roots(args)
+    if skipped:
+        print(_skipped_notice(roots, skipped, named), file=sys.stderr)
+    if not roots:
+        return 2  # nothing was read, so nothing can be graded
+    code = _fix(roots, args) if args.fix else _grade(roots, args)
+    if skipped and named:
+        # A root the OPERATOR NAMED and we never opened is a refusal
+        # even when the others reported: the run cannot claim to have
+        # graded what it was asked for (QG C3 r6, Francisca B1). Only a
+        # MISSING default root is exempt — a fresh machine has no
+        # ~/.claude. A default root that EXISTS and cannot be read is
+        # refused by _grade/_fix, not here (QG C3 r7, Eduardo B1).
+        return 2
+    return code
+
 
-    report = merge([scan(root) for root in _roots(args) if root.is_dir()])
+def _grade(roots: list[Path], args: argparse.Namespace) -> int:
+    """Read-only path: grade what we could read, refuse the rest.
+
+    Guarded for the same reason the fix path is: `scan` raises on a root
+    it cannot list, and leaving one call site bare only moves the
+    traceback (QG C3 r4, Francisca B2).
+    """
+    reports, refusals = [], []
+    for root in roots:
+        result = _safe_scan(root)
+        if isinstance(result, str):
+            refusals.append(result)
+        else:
+            reports.append(result)
+    for refusal in refusals:
+        print(refusal, file=sys.stderr)
+    if not reports:
+        return 2
+    report = merge(reports)
     if args.as_json:
         print(json.dumps(report.to_dict(), indent=2))
     else:
         print(render(report))
-    return exit_code(report)
+    return 2 if refusals else exit_code(report)
+
+
+def _safe_scan(root: Path) -> ScanReport | str:
+    """Scan a root, or say why it could not be scanned.
+
+    ``scan`` is not never-raises: an unreadable ROOT (mode 000, a
+    root-owned config, a container uid mismatch) passes the is_dir()
+    filter and then raises PermissionError from the first is_file()
+    (QG C3 r4, Francisca B2, reproduced end to end). A security tool
+    that answers a locked directory with a traceback has told the
+    operator nothing.
+    """
+    try:
+        return scan(root)
+    except OSError as exc:
+        return f"REFUSED: cannot scan {root} — {exc}"
+
+
+def _fix(roots: list[Path], args: argparse.Namespace) -> int:
+    """Remediate each root, then grade what is left.
+
+    The exit code stays the scanner's contract and is computed from the
+    RE-SCAN: a fix run that leaves criticals still exits 2.
+    """
+    payloads, rendered, graded = [], [], []
+    for root in roots:
+        payload, text, after = _fix_one(root, args)
+        payloads.append(payload)
+        rendered.append(text)
+        if after is not None:
+            graded.append(after)
+    if args.as_json:
+        print(json.dumps(payloads, indent=2))
+    else:
+        print("\n\n".join(rendered))
+    if not graded or len(graded) < len(roots):
+        # `not graded` is not redundant with the caller's guard: without
+        # it, exit_code(merge([])) grades an empty read as A and returns
+        # 0 — the r5 B2 defect surviving one level down, where the two
+        # guards above only masked it (QG C3 r6).
+        return 2
+    return exit_code(merge(graded))
+
+
+def _fix_one(root: Path,
+             args: argparse.Namespace) -> tuple[dict, str, ScanReport | None]:
+    """Remediate one root and re-grade it; None means the re-scan refused.
+
+    The re-scan happens ONCE and its report is what both the printed
+    grade and the exit code are computed from. Scanning a second time to
+    derive the exit code graded a different read than the one on screen
+    (QG C3 r5, Francisca M1), and dropped what `fix` itself planned when
+    the re-scan refused (her M3).
+    """
+    from core.harness import remediation
+
+    fix_report = remediation.fix(root, apply=args.apply)
+    after = _safe_scan(root)
+    if isinstance(after, str):
+        return ({"root": str(root), **fix_report.to_dict(), "refused": after},
+                f"{root}\n{remediation.render(fix_report)}\n{after}", None)
+    return ({"root": str(root), **fix_report.to_dict(),
+             "grade_after": after.grade},
+            f"{root}\n{remediation.render(fix_report, after)}", after)
 
 
 if __name__ == "__main__":