arkaos 4.13.2 → 4.14.1

package/core/hooks/session_start.py

@@ -0,0 +1,322 @@
+"""SessionStart — consolidated entrypoint (F2-2, hook-hygiene completion).
+
+Replaces the 13 python spawn sites of the old ``session-start.sh``
+(profile x2, sync drift, forge YAML x4, Model Fabric, reorganizer
+trigger, dashboard config read, rehydrator, memory recap, final JSON
+print) with ONE python process that emits the full ``systemMessage``.
+Measured baseline before this consolidation: 251ms p50 (isolated floor,
+benchmarks/results.md); each spawn costs ~20-80ms.
+
+Section order preserved exactly from the shell version:
+    banner+greeting → workflow line → version+forge+drift →
+    evidence-flow contract → meta-tag contract → Model Fabric directive
+    → [SESSION] rehydrator resume → [SESSION-MEMORY] recap → JSON out.
+Background side effects (reorganizer trigger, dashboard ensure) stay
+detached and are config-gated; the NEW ``cognition.reorganize_on_session``
+gate lands here (QG F2-1 follow-up, endorsed for this PR).
+
+The shell wrapper only resolves the interpreter and ``exec``s this
+module; with no usable venv it emits a static banner (fail-open).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import time
+from datetime import UTC, datetime
+from pathlib import Path
+
+from core.hooks._shared import get_str, read_stdin_json, repo_path
+
+_BUDGET_MS = 300
+_RECAP_ITEMS = 3
+_SUMMARY_CHARS = 130
+
+_BANNER = (
+    "\n╔══════════════════════════════════════════════╗\n"
+    "║                                              ║\n"
+    "║              A R K A   O S                   ║\n"
+    "║                                              ║\n"
+    "║   The Operating System for AI Teams          ║\n"
+    "║                  by WizardingCode            ║\n"
+    "║                                              ║\n"
+    "╚══════════════════════════════════════════════╝\n"
+)
+
+_EVIDENCE_CONTRACT = (
+    "\n\n[ARKA:EVIDENCE-FLOW] NON-NEGOTIABLE. Every non-trivial request runs"
+    " the 4-gate evidence flow (constitution rule evidence-flow; source"
+    " arka/skills/flow/SKILL.md):"
+    "\n  G1 CONTEXT ([arka:routing] <dept> -> <lead> + KB/graph grounding,"
+    " cite or declare gap)"
+    "\n  G2 PLAN (short plan -> EXPLICIT user approval; silence != approval)"
+    "\n  G3 EXECUTE (closes only with real test run on record: command + exit 0)"
+    "\n  G4 REVIEW (executable checks: lint/type/coverage/security/spell ->"
+    " honest summary)"
+    "\nEmit [arka:gate:N] at each gate start. Gates pass on evidence, never"
+    " on narration."
+    "\nBypass ONLY via [arka:trivial] <reason> for single-file edits under"
+    " 10 lines."
+)
+
+_META_TAG_CONTRACT = (
+    "\n\n[ARKA:META-TAG] Every substantive response ends with a single line:"
+    "\n  [arka:meta] kb=N research=X persona=Y gap=Z critic=W"
+    "\nFields: kb=N (Obsidian/KB notes consulted), research=X (MCPs invoked:"
+    " perplexity,exa,context7,firecrawl,xmcp or 'none'), persona=Y (advisor"
+    " name or 'orchestrator'), gap=Z (KB gap topic or 'none'), critic=W"
+    " (passed|failed|skipped)."
+    "\nMandatory after: EFFECT tool calls, plan/recommendation outputs, QG"
+    " verdicts. Optional for pure read-only status replies."
+    "\nAbsence is measured by the Stop hook (warn-only in v2.34.0) before"
+    " promotion to hard enforcement."
+)
+
+
+def _config() -> dict:
+    try:
+        data = json.loads(
+            (Path.home() / ".arkaos" / "config.json").read_text(encoding="utf-8")
+        )
+        return data if isinstance(data, dict) else {}
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _profile() -> tuple[str, str]:
+    try:
+        data = json.loads(
+            (Path.home() / ".arkaos" / "profile.json").read_text(encoding="utf-8")
+        )
+        name = data.get("name") or data.get("role") or "founder"
+        return str(name), str(data.get("company") or "WizardingCode")
+    except (OSError, json.JSONDecodeError, AttributeError):
+        return "founder", "WizardingCode"
+
+
+def _version(repo: str) -> str:
+    candidates = [Path.home() / ".arkaos" / "lib" / "VERSION"]
+    if repo:
+        candidates.insert(0, Path(repo) / "VERSION")
+    for candidate in candidates:
+        try:
+            if candidate.is_file():
+                return candidate.read_text(encoding="utf-8").strip()
+        except OSError:
+            continue
+    return "2.x"
+
+
+def _drift(version: str) -> str:
+    sync_state = Path.home() / ".arkaos" / "sync-state.json"
+    if not sync_state.is_file():
+        return "\n[arka:update-available] Never synced. Run /arka update."
+    try:
+        synced = str(json.loads(sync_state.read_text(encoding="utf-8"))["version"])
+    except (OSError, json.JSONDecodeError, KeyError):
+        synced = "none"
+    if synced != version:
+        return (
+            f"\n[arka:update-available] Core v{version} != synced"
+            f" v{synced}. Run /arka update."
+        )
+    return ""
+
+
+def _workflow_line() -> str:
+    try:
+        from core.workflow.state import get_state
+
+        state = get_state()
+    except Exception:  # degraded env — banner never breaks
+        return ""
+    if not state:
+        return ""
+    phases = state.get("phases") or {}
+    completed = sum(
+        1 for p in phases.values()
+        if isinstance(p, dict) and p.get("status") == "completed"
+    )
+    line = f"\nWorkflow: {state.get('workflow', '')} ({completed}/{len(phases)})"
+    if state.get("branch"):
+        line += f" branch:{state['branch']}"
+    violations = len(state.get("violations") or [])
+    if violations:
+        line += f" VIOLATIONS:{violations}"
+    return line + "\n"
+
+
+def _forge_line() -> str:
+    try:
+        from core.forge.persistence import get_active_plan
+
+        plan = get_active_plan()
+    except Exception:
+        return ""
+    if plan is None:
+        return ""
+    name = getattr(plan, "name", "")
+    status = getattr(plan, "status", "")
+    phases = len(getattr(plan, "plan_phases", []) or [])
+    if status == "approved":
+        return f"\n  ⚒ Forge plan pending: {name} | Phases: {phases} | /forge resume"
+    if status == "executing":
+        governance = getattr(plan, "governance", None)
+        branch = getattr(governance, "branch_strategy", "") or "" if governance else ""
+        return f"\n  ⚒ Forge executing: {name} | Phases: {phases} | Branch: {branch}"
+    return ""
+
+
+def _model_fabric() -> str:
+    try:
+        from core.runtime.model_routing_context import routing_directive
+
+        directive = routing_directive()
+        return f"\n\n{directive}" if directive else ""
+    except Exception:
+        return ""
+
+
+def _session_resume() -> str:
+    try:
+        from core.memory.rehydrator import build_resume_context
+
+        ctx = build_resume_context()
+    except Exception:
+        return ""
+    if not ctx:
+        return ""
+    return "\n\n[SESSION] " + ctx.replace("\n", "\n[SESSION] ")
+
+
+def _spawn_detached(cmd: list[str], repo: str, log_path: Path | None = None) -> None:
+    stdout = subprocess.DEVNULL
+    handle = None
+    try:
+        if log_path is not None:
+            log_path.parent.mkdir(parents=True, exist_ok=True)
+            handle = log_path.open("a")
+            stdout = handle
+        subprocess.Popen(
+            cmd,
+            stdout=stdout,
+            stderr=subprocess.STDOUT if handle else subprocess.DEVNULL,
+            env={**os.environ, "PYTHONPATH": repo, "ARKAOS_NO_BROWSER": "1"},
+            cwd=repo or None,
+            start_new_session=True,
+        )
+    except Exception:
+        pass
+    finally:
+        if handle is not None:
+            handle.close()  # the child keeps its own inherited fd
+
+
+def _trigger_reorganizer(repo: str, config: dict) -> None:
+    """Stale-aware AND config-gated: ``cognition.reorganize_on_session``
+    (default True) — the F2-1 QG follow-up gate lands here. The staleness
+    guard uses UTC, same basis as before."""
+    cognition = config.get("cognition") or {}
+    if not cognition.get("reorganize_on_session", True):
+        return
+    today = datetime.now(UTC).strftime("%Y-%m-%d")
+    proposal = Path.home() / ".arkaos" / "reorganize-proposals" / f"{today}.md"
+    if proposal.is_file() or not repo:
+        return
+    _spawn_detached([sys.executable, "-m", "core.cognition.reorganizer_cli"], repo)
+
+
+def _ensure_dashboard(repo: str, config: dict) -> None:
+    dashboard = config.get("dashboard") or {}
+    if not dashboard.get("ensure_on_session", True):
+        return
+    script = Path(repo) / "scripts" / "start-dashboard.sh" if repo else None
+    if script is None or not script.is_file():
+        return
+    _spawn_detached(
+        ["bash", str(script), "ensure"], repo,
+        log_path=Path.home() / ".arkaos" / "logs" / "dashboard-ensure.log",
+    )
+
+
+def build_message(cwd: str) -> str:
+    repo = repo_path()
+    config = _config()
+    name, company = _profile()
+    version = _version(repo)
+    msg = _BANNER + f"\nOlá, {name} ({company})\n"
+    msg += _workflow_line()
+    msg += f"ArkaOS v{version}"
+    msg += _forge_line()
+    msg += _drift(version)
+    msg += _EVIDENCE_CONTRACT
+    msg += _META_TAG_CONTRACT
+    msg += _model_fabric()
+    _trigger_reorganizer(repo, config)
+    _ensure_dashboard(repo, config)
+    msg += _session_resume()
+    recap = build_recap(cwd)
+    if recap:
+        msg += f"\n\n{recap}"
+    return msg
+
+
+def build_recap(cwd: str, budget_ms: int = _BUDGET_MS) -> str:
+    """[SESSION-MEMORY] importance+recency recap (F1-A3, semantics kept)."""
+    start = time.monotonic()
+    try:
+        from core.memory.semantic_store import (
+            SessionMemoryStore,
+            default_db_path,
+            neutralize_summary,
+        )
+        if not default_db_path().is_file():
+            return ""
+        # Scope-or-skip (defense-in-depth, mirrors L9.5): no resolvable
+        # project ⇒ no recap — never a silently-global read.
+        project = Path(cwd).name if cwd else ""
+        if not project:
+            return ""
+        store = SessionMemoryStore()
+        records = store.recent(project_name=project, limit=_RECAP_ITEMS)
+        if not records or (time.monotonic() - start) * 1000 > budget_ms:
+            return ""
+        lines = ["[SESSION-MEMORY] Prior turns (importance+recency — not semantic):"]
+        for record in records:
+            summary = neutralize_summary(record.summary)[:_SUMMARY_CHARS]
+            if not summary:
+                continue
+            lines.append(f"[SESSION-MEMORY] - {record.ts[:10]}: {summary}")
+        if len(lines) == 1:
+            return ""
+        backends = ",".join(sorted({r.embedding_backend for r in records})) or "none"
+        lines.append(
+            f"[SESSION-MEMORY] shown: {len(lines) - 1} turns ({project}),"
+            f" backends={backends}"
+        )
+        return "\n".join(lines)
+    except Exception:  # recap is best-effort, banner never breaks
+        return ""
+
+
+def main(stdin_json: dict | None = None) -> int:
+    if stdin_json is None:
+        stdin_json, _ = read_stdin_json()
+    cwd = (
+        get_str(stdin_json, "cwd")
+        or os.environ.get("ARKA_HOOK_CWD", "")
+        or os.getcwd()
+    )
+    try:
+        message = build_message(cwd)
+    except Exception:  # absolute fail-open: static banner, exit 0
+        message = _BANNER + "\nOlá, founder (WizardingCode)\nArkaOS"
+    print(json.dumps({"systemMessage": message}))
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

package/core/hooks/stop.py

@@ -35,6 +35,7 @@ from core.hooks._shared import (
     ensure_root_on_path,
     get_str,
     read_stdin_json,
+    repo_path,
     resolve_arkaos_root,
     safe_session_id,
 )
@@ -392,6 +393,67 @@ def _auto_doc_enqueue(
         pass
 
 
+def _session_memory_enabled() -> bool:
+    """``memory.sessionMemory`` (default True) + env kill-switch."""
+    if os.environ.get("ARKA_SESSION_MEMORY", "").strip() == "0":
+        return False
+    config_path = Path.home() / ".arkaos" / "config.json"
+    try:
+        data = json.loads(config_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return True
+    memory_cfg = data.get("memory") or {}
+    return bool(memory_cfg.get("sessionMemory", True))
+
+
+def _enqueue_turn_capture(session_id: str, transcript_path: str, cwd: str) -> None:
+    """F1-A2: fire-and-forget semantic turn capture — runs for EVERY
+    turn (before the WF_MARKER gate), all cost paid in the detached
+    worker, never on this hook."""
+    if not session_id or not transcript_path or not _session_memory_enabled():
+        return
+    repo = repo_path()
+    if not repo or not Path(repo).is_dir():
+        return
+    try:
+        import subprocess
+        import sys as _sys
+        subprocess.Popen(
+            [_sys.executable, "-m", "core.memory.turn_capture",
+             session_id, transcript_path, cwd or ""],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            env={**os.environ, "PYTHONPATH": repo},
+            start_new_session=True,  # same pattern as _enqueue_cognition_capture
+        )
+    except Exception:  # noqa: BLE001 — capture is best-effort, hook never breaks
+        pass
+
+
+def _enqueue_routing_rebuild() -> None:
+    """F1-B1: throttled detached rebuild of routing-scores.json (mtime
+    > 1h). One stat on the hot path; the aggregation runs detached."""
+    try:
+        from core.governance.routing_feedback import stale
+        if not stale(max_age_seconds=3600):
+            return
+        repo = repo_path()
+        if not repo or not Path(repo).is_dir():
+            return
+        import subprocess
+        import sys as _sys
+        subprocess.Popen(
+            [_sys.executable, "-m", "core.governance.routing_feedback_cli",
+             "rebuild"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            env={**os.environ, "PYTHONPATH": repo},
+            start_new_session=True,
+        )
+    except Exception:  # noqa: BLE001 — rebuild is best-effort, hook never breaks
+        pass
+
+
 def main(stdin_json: dict | None = None) -> int:
     if stdin_json is None:
         stdin_json, _ = read_stdin_json()
@@ -417,6 +479,13 @@ def main(stdin_json: dict | None = None) -> int:
 
     _native_usage(transcript_path, session_id, raw)
 
+    try:
+        _enqueue_turn_capture(session_id, transcript_path, cwd)
+    except Exception:  # noqa: BLE001 — never let capture break the hook
+        pass
+
+    _enqueue_routing_rebuild()
+
     # Only evaluate sessions where the classifier flagged creation intent.
     wf_marker = arkaos_temp_dir("arkaos-wf-required") / session_id if session_id else None
     if wf_marker is None or not safe_session_id(session_id) or not wf_marker.is_file():

package/core/hooks/subagent_stop.py

@@ -0,0 +1,186 @@
+"""SubagentStop — consolidated entrypoint (F2-4, Claude Code reform).
+
+Fires when a dispatched subagent (Task tool) finishes. Two jobs, both
+WARN-only (this hook never blocks — the subagent already ran):
+
+1. Persist the subagent's final output to the session store so the
+   orchestrator's audit trail includes what each specialist produced
+   (the ArkaOS QG story: nothing a specialist ships is invisible).
+2. Run the same honesty checks the Stop hook runs on the main turn —
+   phantom-action (does the output narrate effects with no tool calls?)
+   and meta-tag presence — and, when the output looks deliverable-shaped,
+   emit a stderr nudge to route it through the Quality Gate.
+
+Telemetry (warn mode, same discipline as the Stop hook): one line per
+subagent to ``~/.arkaos/telemetry/subagent-stop.jsonl``. Gate flag
+``ARKA_SUBAGENT_QA`` = ``warn`` (default) | ``off``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+
+from core.hooks._shared import (
+    ensure_root_on_path,
+    get_str,
+    read_stdin_json,
+    resolve_arkaos_root,
+    safe_session_id,
+)
+
+_TELEMETRY = Path.home() / ".arkaos" / "telemetry" / "subagent-stop.jsonl"
+# A subagent output "looks deliverable-shaped" when it claims a build/fix
+# a human would want gated — a cheap heuristic, warn-only, never blocks.
+_DELIVERABLE_RE = None  # compiled lazily
+
+
+def _qa_mode() -> str:
+    mode = os.environ.get("ARKA_SUBAGENT_QA", "").strip().lower()
+    return mode if mode in ("warn", "off") else "warn"
+
+
+def _read_transcript(path: str) -> str | None:
+    if not path:
+        return None
+    try:
+        # errors="replace": an invalid-UTF-8 transcript must not raise
+        # UnicodeDecodeError (this hook promises never to block). ValueError
+        # guards a null-byte path arriving from stdin JSON.
+        return Path(path).read_text(encoding="utf-8", errors="replace")
+    except (OSError, ValueError):
+        return None
+
+
+def _final_assistant_text(transcript_path: str, raw: str | None) -> str:
+    try:
+        from core.workflow.flow_enforcer import _load_last_assistant_messages
+
+        msgs = _load_last_assistant_messages(transcript_path, 1, raw_text=raw)
+        return msgs[-1] if msgs else ""
+    except Exception:  # best-effort — hook never breaks
+        return ""
+
+
+def _persist_output(session_id: str, agent_id: str, text: str) -> None:
+    if not session_id or not text:
+        return
+    try:
+        from core.evals.sanitizer import SanitizerConfigMissing, sanitize_text
+        from core.memory.session_store import AgentOutput, SessionStore
+
+        try:
+            clean, _counts = sanitize_text(text[:4000])
+        except SanitizerConfigMissing:
+            clean = ""  # no sanitizer config => metadata only (recipes precedent)
+        store = SessionStore(session_id)
+        store.save_agent_output(AgentOutput(
+            agent_id=agent_id or "subagent",
+            phase_id="subagent-stop",
+            output=clean,
+            at=datetime.now(UTC).isoformat(),
+        ))
+    except Exception:  # persistence is best-effort
+        pass
+
+
+def _looks_deliverable(text: str) -> bool:
+    global _DELIVERABLE_RE
+    if _DELIVERABLE_RE is None:
+        import re
+        _DELIVERABLE_RE = re.compile(
+            r"\b(implemented|created|added|fixed|refactored|built|wrote|"
+            r"shipped|migrated|deployed)\b",
+            re.IGNORECASE,
+        )
+    return bool(_DELIVERABLE_RE.search(text))
+
+
+def _run_qa(text: str, raw: str | None) -> dict:
+    result = {"phantom": "skipped", "meta_tag": "skipped", "deliverable": False}
+    try:
+        from core.governance.meta_tag_check import check_meta_tag
+        from core.governance.phantom_action_check import check_phantom_actions
+
+        phantom = check_phantom_actions(text, raw)
+        result["phantom"] = "pass" if phantom.passed else "phantom-action"
+        meta = check_meta_tag(text)
+        result["meta_tag"] = "present" if meta.passed else "missing"
+        result["deliverable"] = _looks_deliverable(text)
+    except Exception:  # QA is best-effort — never break the hook
+        pass
+    return result
+
+
+def _record(session_id: str, agent_id: str, qa: dict) -> None:
+    entry = {
+        "ts": datetime.now(UTC).isoformat(),
+        "mode": "warn",
+        "session_id": session_id,
+        "agent_id": agent_id,
+        **qa,
+    }
+    try:
+        _TELEMETRY.parent.mkdir(parents=True, exist_ok=True)
+        with _TELEMETRY.open("a", encoding="utf-8") as fh:
+            fh.write(json.dumps(entry) + "\n")
+    except OSError:
+        pass
+
+
+def _nudge(agent_id: str, qa: dict) -> str:
+    parts = []
+    if qa.get("phantom") == "phantom-action":
+        parts.append("narrates effects with no tool calls in the subagent turn")
+    if qa.get("meta_tag") == "missing":
+        parts.append("no [arka:meta] line")
+    if qa.get("deliverable") and parts:
+        return (
+            f"[arka:subagent-qa] {agent_id or 'subagent'} output looks"
+            f" deliverable-shaped but {'; '.join(parts)} — route it through"
+            f" the Quality Gate before accepting."
+        )
+    return ""
+
+
+def main(stdin_json: dict | None = None) -> int:
+    if stdin_json is None:
+        stdin_json, _ = read_stdin_json()
+    root = resolve_arkaos_root()
+    ensure_root_on_path(root)
+
+    session_id = get_str(stdin_json, "session_id")
+    if session_id and not safe_session_id(session_id):
+        return 0
+    agent_id = get_str(stdin_json, "subagent_type") or get_str(stdin_json, "agent_type")
+    transcript_path = get_str(stdin_json, "transcript_path")
+
+    if _qa_mode() == "off":
+        return 0
+
+    raw = _read_transcript(transcript_path)
+    text = _final_assistant_text(transcript_path, raw)
+    if not text:
+        return 0
+
+    _persist_output(session_id, agent_id, text)
+    qa = _run_qa(text, raw)
+    _record(session_id, agent_id, qa)
+
+    # The nudge must reach the ORCHESTRATOR. Claude Code discards hook
+    # stderr at exit 0 (it only surfaces stderr on a deny/exit 2), so a
+    # stderr nudge here would be inert. additionalContext on stdout is the
+    # channel the model actually receives.
+    nudge = _nudge(agent_id, qa)
+    if nudge:
+        print(json.dumps({"hookSpecificOutput": {
+            "hookEventName": "SubagentStop",
+            "additionalContext": nudge,
+        }}))
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

package/core/hooks/user_prompt_submit.py

@@ -207,7 +207,7 @@ def _invalidate_turn_caches(session_id: str) -> None:
 # ─── Section 4: Synapse bridge (in-process) ──────────────────────────────
 
 
-def _run_bridge(root: str, user_input: str, session_id: str) -> str:
+def _run_bridge(root: str, user_input: str, session_id: str, cwd: str = "") -> str:
     bridge_path = Path(root) / "scripts" / "synapse-bridge.py"
     if not bridge_path.is_file() or not Path(root).is_dir():
         return ""
@@ -221,10 +221,12 @@ def _run_bridge(root: str, user_input: str, session_id: str) -> str:
         # The old hook piped bridge stderr to /dev/null — keep it quiet.
         with contextlib.redirect_stderr(io.StringIO()):
             spec.loader.exec_module(module)
-            output, code = module.run_bridge(
-                {"user_input": user_input, "session_id": session_id},
-                Path(root),
-            )
+            payload = {"user_input": user_input, "session_id": session_id}
+            if cwd:
+                # Explicit hook cwd — L9.5 scopes cross-session memory by
+                # project; an unscoped search would leak across clients.
+                payload["cwd"] = cwd
+            output, code = module.run_bridge(payload, Path(root))
         if code == 0:
             return str(output.get("context_string", ""))
     except Exception:
@@ -573,7 +575,9 @@ def main(stdin_json: dict | None = None, raw: str = "") -> int:
         user_input = raw[:2000]
 
     # ─── Synapse bridge + tags ───────────────────────────────────────
-    python_result = _run_bridge(root, user_input, session_id)
+    python_result = _run_bridge(
+        root, user_input, session_id, get_str(stdin_json, "cwd")
+    )
     if python_result:
         wf_tag = _workflow_tag()
         if wf_tag: