arkaos 4.46.0 → 4.48.0

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v4.46.0 — 89 agents, 17 departments, 332 skills, 297 commands, 19 ADRs.
+> v4.48.0 — 89 agents, 17 departments, 332 skills, 297 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.46.0
+4.48.0

package/core/egress/policy.py

@@ -28,6 +28,7 @@ import re
 from dataclasses import dataclass, field
 from datetime import datetime
 from pathlib import Path
+from typing import Any
 
 from core.egress import allowlist, audit, redact
 from core.governance.harness_scanner import secret_labels
@@ -42,7 +43,7 @@ class Finding:
     #          # | audit-unavailable | payload-not-text | guard-failure
     token: str
 
-    def to_audit(self, salt: bytes = b"") -> dict:
+    def to_audit(self, salt: bytes = b"") -> dict[str, Any]:
         return {
             "kind": self.kind,
             "token_sha16": (
@@ -64,7 +65,7 @@ class EgressDecision:
     redacted_sha256: str = ""
     audited: bool = False
 
-    def to_audit(self, salt: bytes = b"") -> dict:
+    def to_audit(self, salt: bytes = b"") -> dict[str, Any]:
         return {
             "allowed": self.allowed,
             "destination": self.destination,
@@ -99,26 +100,43 @@ def evaluate(
 ) -> EgressDecision:
     """Judge one payload against the policy. Never raises.
 
-    ``home`` scopes the home-path check and the default allowlist /
-    audit locations; ``now`` pins allowlist expiry for tests.
+    ``home`` scopes the home-path check, the redaction config and the
+    default allowlist / audit locations; ``now`` pins allowlist expiry
+    for tests.
     """
     destination = _safe_str(destination)
-    # Digest computed ONCE, before any failure path, so no handler
-    # ever re-executes the operation that failed (QG D1 r2 E-B1).
-    payload_digest = _sha256(text) if isinstance(text, str) else ""
+    # ONCE, before any failure path, so no handler re-runs what
+    # failed. Named `digest`: `payload_digest` shadowed the public
+    # function here (QG D2 r12, Francisca M2).
+    digest = payload_digest(text) if isinstance(text, str) else ""
     try:
         decision = _judge(
             text, destination, config_path, home, allowlist_path, now
         )
     except Exception as exc:  # never-raises boundary — deny, not crash
-        decision = EgressDecision(
-            allowed=False, destination=destination,
-            payload_sha256=payload_digest,
-            findings=[Finding("guard-failure", type(exc).__name__)],
-        )
+        decision = _guard_failure(destination, digest, exc)
     return _audited(decision, home, audit_path, now)
 
 
+def _guard_failure(
+    destination: str, digest: str, exc: BaseException
+) -> EgressDecision:
+    return EgressDecision(
+        allowed=False, destination=destination, payload_sha256=digest,
+        findings=[Finding("guard-failure", type(exc).__name__)],
+    )
+
+
+def default_redaction_config_path(home: Path | None = None) -> Path:
+    """The identifier list *home* implies.
+
+    Mirrors ``leak_scanner._DEFAULT_CONFIG_PATH`` for the real home, so
+    scoping by ``home`` never changes production behaviour — pinned by
+    ``test_egress_policy.py`` rather than by this comment.
+    """
+    return (home or Path.home()) / ".arkaos" / "redaction-clients.json"
+
+
 def _safe_str(value: object) -> str:
     try:
         return str(value)
@@ -150,7 +168,7 @@ def _audited(
     return decision
 
 
-def enforce(text: object, destination: str, **kwargs) -> str:
+def enforce(text: object, destination: str, **kwargs: Any) -> str:
     """The redacted text cleared to leave, or :class:`EgressDeniedError`."""
     decision = evaluate(text, destination, **kwargs)
     if not decision.allowed or decision.redacted_text is None:
@@ -167,41 +185,70 @@ def _judge(
     now: datetime | None,
 ) -> EgressDecision:
     if not isinstance(text, str):
-        return EgressDecision(
-            allowed=False, destination=destination, payload_sha256="",
-            findings=[Finding("payload-not-text", type(text).__name__)],
-        )
+        return _not_text(destination, text)
     decision = EgressDecision(
         allowed=False, destination=destination,
-        payload_sha256=_sha256(text),
+        payload_sha256=payload_digest(text),
     )
-    clean, failure = _redacted(text, config_path)
-    if failure is not None:
-        decision.findings.append(failure)
+    # One scoped path for both layers: scoping only the redaction call
+    # left residual_identifiers reading the real machine's list
+    # (QG D2 r3, Francisca B1).
+    scoped = _scoped_config(config_path, home)
+    clean = _redacted(text, scoped)
+    if isinstance(clean, Finding):
+        decision.findings.append(clean)
         return decision
     _collect_findings(
-        decision, clean, destination, config_path, home, allowlist_path, now
+        decision, clean, destination, scoped, home, allowlist_path, now
     )
     if not decision.findings:
         decision.allowed = True
         decision.redacted_text = clean
-        decision.redacted_sha256 = _sha256(clean)
+        decision.redacted_sha256 = payload_digest(clean)
     return decision
 
 
-def _sha256(text: str) -> str:
+def _not_text(destination: str, text: object) -> EgressDecision:
+    return EgressDecision(
+        allowed=False, destination=destination, payload_sha256="",
+        findings=[Finding("payload-not-text", type(text).__name__)],
+    )
+
+
+def payload_digest(text: str) -> str:
     """Total over any str — surrogatepass, because a payload holding a
     lone surrogate (routine from errors="surrogateescape" decoding or
     json.loads of an escape) must be DIGESTIBLE to be denied with an
-    audit line (QG D1 r2 E-B1)."""
+    audit line (QG D1 r2 E-B1).
+
+    Public because callers outside this package need the same digest
+    the audit trail records; reaching for a private symbol made a D1
+    rename a silent runtime break downstream (QG D2 r1, Francisca M6).
+    """
     payload = text.encode("utf-8", errors="surrogatepass")
     return hashlib.sha256(payload).hexdigest()
 
 
-def _redacted(
-    text: str, config_path: Path | None
-) -> tuple[str | None, Finding | None]:
-    """``(clean_text, None)`` or ``(None, denial_finding)``.
+def _scoped_config(config_path: Path | None, home: Path | None) -> Path | None:
+    """The redaction config *home* implies, unless one was named.
+
+    ``home`` scoped ``allowlist_path`` and ``audit_path`` but NOT the
+    redaction config, so a caller passing ``home=`` and forgetting
+    ``config_path`` judged paths against one home while redacting
+    against another (QG D2 r1, Francisca M7).
+
+    Called from inside ``_judge``, i.e. inside ``evaluate``'s try: the
+    same defaulting one frame up sat OUTSIDE it, and a non-Path home
+    turned the never-raises boundary into a TypeError — the very shape
+    QG D1 r2 F-M5 already closed once.
+    """
+    if config_path is not None or home is None:
+        return config_path
+    return default_redaction_config_path(home)
+
+
+def _redacted(text: str, config_path: Path | None) -> str | Finding:
+    """The clean text, or the finding that denies it.
 
     A redaction that CRASHES proves nothing about the payload — same
     posture as a missing config: denied, never allowlistable (QG D1
@@ -209,11 +256,16 @@ def _redacted(
     """
     try:
         clean, _counts = redact.redact(text, config_path)
-        return clean, None
+        # Annotated: redact() is untyped, so `clean` arrives as Any and
+        # the union return silently degrades to Any (mypy no-any-return,
+        # surfaced only with --follow-imports=skip —
+        # QG D2 r3, Francisca M3).
+        clean_text: str = clean
+        return clean_text
     except redact.SanitizerConfigMissing:
-        return None, Finding("redaction-config-missing", "")
+        return Finding("redaction-config-missing", "")
     except Exception as exc:
-        return None, Finding("redaction-failed", type(exc).__name__)
+        return Finding("redaction-failed", type(exc).__name__)
 
 
 def _collect_findings(

package/core/harness/cli.py

@@ -0,0 +1,143 @@
+"""CLI for the harness manager — ``npx arkaos harness <verb>``.
+
+Verbs: ``status`` (read-only), ``assert`` (apply policies), ``restore``
+(assert + re-seed adopted surfaces), ``harden`` (assert + scanner
+grade, nonzero exit below B), ``flags`` (read, or set with an explicit
+``--set name=value``). Every verb but ``flags`` takes ``--json``.
+Exit codes are the contract the Node wrapper propagates verbatim.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from core.harness.manager import ClaudeConfigManager
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    handler = {
+        "status": _status,
+        "assert": _assert,
+        "restore": _restore,
+        "harden": _harden,
+        "flags": _flags,
+    }[args.verb]
+    try:
+        return handler(ClaudeConfigManager(), args)
+    except Exception as exc:  # operators get a message, never a traceback
+        print(f"harness {args.verb} failed: {exc}", file=sys.stderr)
+        return 1
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m core.harness.cli",
+        description="Assert and report ArkaOS ownership of the harness.",
+    )
+    sub = parser.add_subparsers(dest="verb", required=True)
+    for verb in ("status", "assert", "restore", "harden"):
+        sub.add_parser(verb).add_argument(
+            "--json", action="store_true", dest="as_json"
+        )
+    flags = sub.add_parser("flags")
+    flags.add_argument(
+        "--set", dest="assignment", default=None,
+        help=(
+            "hardEnforcement|specialistEnforcement: true|false; "
+            "frontendGate: off|warn|hard; read-only without it"
+        ),
+    )
+    return parser
+
+
+def _status(manager: ClaudeConfigManager, args) -> int:
+    report = manager.status()
+    if getattr(args, "as_json", False):
+        print(json.dumps(report, indent=2))
+        return 0
+    _print_drift(report["drift"])
+    return 0
+
+
+def _print_drift(drift_report: dict) -> None:
+    print(f"settings: {drift_report['settings_path']}")
+    print(f"ok: {drift_report['ok']}")
+    for finding in drift_report["findings"]:
+        print(
+            f"  [{finding['status']}] {finding['where']} — "
+            f"{finding['detail']}"
+        )
+    if not drift_report["findings"]:
+        print("  no drift")
+
+
+def _assert(manager: ClaudeConfigManager, args) -> int:
+    return _print_report(manager.assert_ownership(), args)
+
+
+def _restore(manager: ClaudeConfigManager, args) -> int:
+    return _print_report(manager.restore(), args)
+
+
+def _harden(manager: ClaudeConfigManager, args) -> int:
+    report, grade = manager.harden()
+    code = _print_report(report, args, extra={"scan_grade": grade})
+    if not getattr(args, "as_json", False):
+        print(f"post-assert scan grade: {grade}")
+    if code:
+        return code
+    return 0 if grade in ("A", "B") else 2
+
+
+def _flags(manager: ClaudeConfigManager, args) -> int:
+    if args.assignment:
+        name, separator, raw = args.assignment.partition("=")
+        if not separator or not raw.strip():
+            print("flags --set expects name=value", file=sys.stderr)
+            return 1
+        try:
+            flags = manager.set_flag(name.strip(), _parse_value(raw.strip()))
+        except ValueError as exc:
+            print(str(exc), file=sys.stderr)
+            return 1
+    else:
+        flags = manager.read_flags()
+    print(json.dumps(flags, indent=2))
+    return 0
+
+
+def _parse_value(raw: str) -> object:
+    if raw.lower() in ("true", "false"):
+        return raw.lower() == "true"
+    return raw.lower()
+
+
+def _print_report(report, args=None, extra: dict | None = None) -> int:
+    if getattr(args, "as_json", False):
+        print(json.dumps({**report.to_dict(), **(extra or {})}, indent=2))
+        return 1 if report.refused or _has_refusal(report) else 0
+    if report.refused:
+        print(f"{report.verb}: refused — {report.refused}", file=sys.stderr)
+        print(
+            "  nothing was written; fix or remove the file and re-run",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"{report.verb}: changed={report.changed}")
+    for action in report.actions:
+        if action.action == "noop":
+            continue
+        detail = f" ({action.detail})" if action.detail else ""
+        print(f"  {action.action}: {action.surface}{detail}")
+    return 1 if _has_refusal(report) else 0
+
+
+def _has_refusal(report) -> bool:
+    return any(a.action == "refused" for a in report.actions)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/core/harness/drift.py

@@ -26,6 +26,9 @@ ignore the report (the harness_scanner noise lesson).
 
 from __future__ import annotations
 
+import os
+import re
+import shlex
 import sys
 from dataclasses import dataclass, field
 from enum import StrEnum
@@ -187,16 +190,147 @@ def _check_hooks(
     hooks = settings.get("hooks")
     hooks = hooks if isinstance(hooks, dict) else {}
     is_windows = (platform or sys.platform) == "win32"
+    accepted = _accepted_hook_dirs(report.settings_path, hooks_root)
     for reg in spec.hook_registrations:
         if reg.posix_only and is_windows:
             continue
         if reg.conditional and not _script_deployed(reg, hooks_root):
             continue
-        _check_registration(report, reg, hooks.get(reg.event))
+        _check_registration(report, reg, hooks.get(reg.event), accepted)
+
+
+def _accepted_hook_dirs(
+    settings_path: Path, hooks_root: str | None
+) -> frozenset[str] | None:
+    """Directories an ArkaOS hook command may legitimately live in.
+
+    Three: what the installer writes (``~/.arkaos/config/hooks`` —
+    adapters/claude-code.js joins installDir with config/hooks;
+    omitting it read every healthy install as stale and repointed it
+    at the purgeable npx cache, QG C2 r1 Francisca B1), the
+    ``~/.arkaos/lib`` snapshot, and the current resolved root.
+    Anything else with an ArkaOS basename is a STALE root — the
+    split-root failure mode basename matching hid (#439 M6).
+
+    None when the root cannot be resolved: without a reference point
+    staleness cannot be judged, and flagging everything is noise.
+    """
+    home = settings_path.parent.parent  # <home>/.claude/settings.json
+    try:
+        arkaos = paths.arkaos_home(home)
+        return frozenset(
+            _normalised(candidate)
+            for candidate in (
+                arkaos / "config" / "hooks",
+                arkaos / "lib" / "config" / "hooks",
+                paths.hooks_dir(hooks_root),
+            )
+        )
+    except OSError:
+        return None
+
+
+def _normalised(path: Path) -> str:
+    """Comparable form of a directory path.
+
+    Case-folded and lexically normalised: a case variant or a ``..``
+    segment names the same directory on the operator's filesystem and
+    must not read as a different root (QG C2 r1 M2). ``resolve()`` is
+    deliberately not used — it hits the filesystem and would make a
+    read-only scan depend on what happens to exist.
+    """
+    return os.path.normcase(os.path.normpath(str(path)))
+
+
+def hook_command_path(command: object) -> Path:
+    """The script path inside a hook ``command`` string.
+
+    Operators write commands with surrounding quotes and with
+    interpreter prefixes (``bash /path/hook.sh``); matching on the raw
+    string appended a DUPLICATE registration and stripped the prefix
+    (QG C2 r1, Francisca B7). One normaliser, used by every consumer.
+    """
+    text = str(command or "").strip()
+    if not text:
+        return Path("")
+    parts = shlex.split(text) if _splittable(text) else [text]
+    parts = _before_shell_operator(parts)
+    for token in reversed(parts):
+        if token.endswith(_HOOK_SUFFIXES):
+            return Path(token)
+    for token in reversed(parts):
+        if "/" in token or "\\" in token:
+            return Path(token)
+    return Path(parts[-1]) if parts else Path("")
+
+
+_SHELL_OPERATOR_RE = re.compile(r"[|;&>]")
+_HOOK_SUFFIXES = (".sh", ".ps1", ".cjs")
+
+
+def _before_shell_operator(parts: list[str]) -> list[str]:
+    """Tokens up to the first shell operator.
+
+    Load-bearing whenever the SECOND command or the redirect target
+    would win the scan: ``stop.sh 2>/tmp/hook-debug.sh`` ends in a
+    hook suffix, ``stop.sh && /usr/local/bin/notify.sh`` chains a
+    second script, and ``bash <dir>/stop 2>/dev/null`` has no suffix
+    at all — in each case the wrong token is read as the script, the
+    ArkaOS entry goes unrecognised, and assert appends a SECOND
+    registration that fires the hook twice (QG C2 r2 Francisca B2;
+    the ``2>/dev/null`` example first documented here was already
+    handled by the suffix scan, QG C2 r3 Eduardo).
+
+    Operators attach to the previous token as often as they stand
+    alone (``stop.sh;`` vs ``stop.sh ;``), so both forms cut.
+    """
+    kept: list[str] = []
+    for token in parts:
+        head = _operator_head(token)
+        if head is None:
+            kept.append(token)
+            continue
+        if head:
+            kept.append(head)
+        break
+    return kept or parts
+
+
+def _operator_head(token: str) -> str | None:
+    """Text before a genuine shell operator in ``token``, else None.
+
+    An operator CHARACTER is not an operator POSITION: a directory
+    named ``R&D`` or ``a;b`` is an ordinary path, and cutting there
+    made the manager stop recognising the entry it had just written —
+    assert went non-idempotent, appending a Stop group per run
+    (QG C2 r4, Francisca B2; the regression came from the r3 fix for
+    the duplication bug, not from the original code). A cut is
+    genuine only where a shell would see one: at the start of the
+    token, right after a hook script, or after a file-descriptor
+    number.
+    """
+    match = _SHELL_OPERATOR_RE.search(token)
+    if match is None:
+        return None
+    head = token[: match.start()]
+    if not head or head.isdigit() or head.endswith(_HOOK_SUFFIXES):
+        return head
+    return None
+
+
+def _splittable(text: str) -> bool:
+    try:
+        shlex.split(text)
+        return True
+    except ValueError:
+        return False
 
 
 def _check_registration(
-    report: DriftReport, reg: HookRegistration, entries: Any
+    report: DriftReport,
+    reg: HookRegistration,
+    entries: Any,
+    accepted: frozenset[str] | None,
 ) -> None:
     where = f"hooks.{reg.event}" + (
         f"[matcher={reg.matcher}]" if reg.matcher else ""
@@ -210,14 +344,31 @@ def _check_registration(
             )
         )
         return
+    for detail in entry_divergences(entry, reg, accepted):
+        report.findings.append(
+            DriftFinding("settings:hooks", DriftStatus.DIVERGED, where, detail)
+        )
+
+
+def entry_divergences(
+    entry: dict, reg: HookRegistration, accepted: frozenset[str] | None
+) -> list[str]:
+    """Why an existing ArkaOS entry diverges from spec — [] when clean.
+
+    Shared with the C2 manager so drift and repair can never disagree
+    about what counts as divergent.
+    """
+    divergences = []
     timeout = entry.get("timeout")
     if timeout != reg.timeout:
-        report.findings.append(
-            DriftFinding(
-                "settings:hooks", DriftStatus.DIVERGED, where,
-                f"timeout is {timeout!r}, spec says {reg.timeout}",
-            )
+        divergences.append(f"timeout is {timeout!r}, spec says {reg.timeout}")
+    command_dir = hook_command_path(entry.get("command")).parent
+    if accepted is not None and _normalised(command_dir) not in accepted:
+        divergences.append(
+            f"stale-root: {reg.script} points at {command_dir}, not "
+            f"the current ArkaOS hooks dir"
         )
+    return divergences
 
 
 def _find_entry(reg: HookRegistration, entries: Any) -> dict | None:
@@ -233,8 +384,8 @@ def _find_entry(reg: HookRegistration, entries: Any) -> dict | None:
         for inner in group.get("hooks") or []:
             if not isinstance(inner, dict):
                 continue
-            command = str(inner.get("command", ""))
-            if command and Path(command).name in wanted:
+            name = hook_command_path(inner.get("command")).name
+            if name and name in wanted:
                 return inner
     return None