arkaos 3.73.0 → 3.74.0

package/VERSION

@@ -1 +1 @@
-3.73.0
+3.74.0

package/arka/skills/flow/SKILL.md

@@ -73,6 +73,16 @@ state the gap explicitly and propose filling it.
 Dispatch specialists via the `Agent` tool. The squad lead from Phase 3
 names them. Specialists run in parallel when work is independent.
 
+**Experience injection (PR3 v3.74.0).** When a specialist is dispatched,
+Synapse layer `L2.6 AgentExperiences`
+(`core/synapse/agent_experiences_layer.py`) detects the
+`[arka:dispatch] <from> -> <to>` marker and loads the top-5 most recent
+`Experience` records for the target agent from
+`~/.arkaos/agents/<agent_id>/experiences.jsonl`. The records list past
+Quality Gate REJECTED verdicts with their blockers and patterns. The
+dispatched specialist must read them and avoid repeating the failure
+modes. Operator-side audit: `python -m core.governance.agent_experiences_cli list <agent_id>`.
+
 **Dispatch must be announced (NON-NEGOTIABLE `dispatch-must-be-announced`).**
 Immediately before each `Agent` tool call, emit on its own line:
 
@@ -140,7 +150,13 @@ For each item, in order:
    injection, missing auth, data exposure.
    - Fail → back to the todo.
 5. **Quality Gate** — Marta (CQO) orchestrates the right specialists
-   for the area. If a specialist is missing, stop and advise the user
+   for the area. After Marta returns the verdict, the orchestrator MUST
+   call `core.governance.cqo_experience_recorder.record_from_verdict(...)`
+   when verdict is REJECTED (constitution rule `agent-experience-persistence`,
+   MUST level — PR3 v3.74.0). The recorder parses the blockers and writes
+   one Experience to the failing agent's log so the lesson is visible on
+   the next dispatch via the L2.6 Synapse layer. If a specialist is
+   missing, stop and advise the user
    to create one via `/arka personas` + provide the knowledge.
    - Fail → back to the todo.
 6. Document — save the completed work to Obsidian + vector DB.

package/config/constitution.yaml

@@ -193,6 +193,11 @@ enforcement_levels:
         rule: "Dispatch subagents only when task requires >3 Reads or >5 Greps or isolated context. Never parallel subagents sharing state. Prefer main thread for trivial tasks."
         enforcement: "warning"
 
+      # ─── Rule added in PR3 Squad Intelligence Upgrade (2026-05-28) ───────
+      - id: agent-experience-persistence
+        rule: "Quality Gate REJECTED verdicts MUST result in an Experience record for the failing agent, written to ~/.arkaos/agents/<agent_id>/experiences.jsonl via core.governance.cqo_experience_recorder. Next dispatch of that agent loads the experiences via the Synapse L2.6 layer (core.synapse.agent_experiences_layer) so the lesson carries across sessions. Without this, REJECTED reports evaporate as conversation turns and the same structural mistakes recur."
+        enforcement: "PR3 v3.74.0 ships the storage, parser, and Synapse layer. v3.74.1 will wire a PostToolUse hook on the Agent tool that auto-records on REJECTED verdicts. Until then orchestrators MUST call cqo_experience_recorder.record_from_verdict() after every CQO dispatch. Audit via python -m core.governance.agent_experiences_cli list <agent_id>."
+
   should:
     description: "Best practices. Encouraged but not enforced."
     rules:

package/core/governance/agent_experiences.py

@@ -0,0 +1,176 @@
+"""Agent experience persistence — Quality Gate feedback loop store.
+
+When Marta (CQO) rejects an agent's work, an `Experience` record is
+appended to `~/.arkaos/agents/<agent_id>/experiences.jsonl`. The next
+time that agent is dispatched, recent experiences are injected as
+context so the agent inherits prior failures across sessions.
+
+This closes the long-standing QG learning gap: rejection reports used
+to live only in the PR thread; the agent that failed had no way to
+recall the structural mistake on the next pass. The Paulo of next
+month now sees what the Paulo of today learned the hard way.
+
+PR3 of the Squad Intelligence Upgrade.
+"""
+
+from __future__ import annotations
+
+import json
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+from core.shared import safe_session_id as _safe_session_id_module
+
+try:
+    import fcntl  # POSIX only
+    _HAS_FLOCK = True
+except ImportError:
+    _HAS_FLOCK = False
+
+
+AGENTS_ROOT: Path = Path.home() / ".arkaos" / "agents"
+
+
+@dataclass
+class Experience:
+    """One QG verdict (or other lesson) captured for an agent.
+
+    `patterns` is a list (not a single string) because a verdict can fail
+    on multiple structural issues at once — e.g. function-length AND
+    governance-gap. PR3 v3.74.0 changed from `pattern: str | None` to
+    `patterns: list[str]` after Marta's QG-B6 ruled first-match-wins was
+    masking secondary patterns.
+    """
+
+    ts: str
+    agent_id: str
+    session_id: str
+    context: str
+    verdict: str
+    blockers: list[str] = field(default_factory=list)
+    patterns: list[str] = field(default_factory=list)
+    fix_applied: str | None = None
+    references: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+
+
+def experience_to_dict(exp: Experience) -> dict:
+    """Public serialiser for callers that need to persist outside this store."""
+    return asdict(exp)
+
+
+@contextmanager
+def _locked_append(path: Path):
+    """Append to `path` under POSIX flock; Windows falls back to O_APPEND atomicity."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fh = path.open("a", encoding="utf-8")
+    try:
+        if _HAS_FLOCK:
+            fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+        yield fh
+    finally:
+        if _HAS_FLOCK:
+            try:
+                fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
+            except OSError:
+                pass
+        fh.close()
+
+
+def _safe_agent_id(agent_id: str) -> str | None:
+    """Apply the same allowlist as session IDs (CWE-22 path-traversal guard)."""
+    return _safe_session_id_module.safe_session_id(agent_id)
+
+
+def _path_for(agent_id: str) -> Path | None:
+    safe = _safe_agent_id(agent_id)
+    if safe is None:
+        return None
+    return AGENTS_ROOT / safe / "experiences.jsonl"
+
+
+def record_experience(experience: Experience) -> None:
+    """Append an experience to the agent's JSONL.
+
+    Silently drops the record when the agent_id fails the safe-id check
+    or when filesystem I/O fails — recording must never block whatever
+    triggered the QG verdict.
+    """
+    path = _path_for(experience.agent_id)
+    if path is None:
+        return
+    try:
+        with _locked_append(path) as fh:
+            fh.write(json.dumps(asdict(experience)) + "\n")
+    except OSError:
+        return
+
+
+def _parse_entry(line: str) -> Experience | None:
+    """Decode one JSONL line into an Experience, or return None on bad input."""
+    try:
+        data = json.loads(line)
+    except json.JSONDecodeError:
+        return None
+    try:
+        return Experience(**data)
+    except (TypeError, ValueError):
+        return None
+
+
+def _filter_entry(
+    exp: Experience, since: datetime | None, tag: str | None
+) -> bool:
+    """Return True if the entry passes both filters."""
+    if since is not None:
+        try:
+            ts = datetime.fromisoformat(exp.ts)
+        except (TypeError, ValueError):
+            return False
+        if ts < since:
+            return False
+    if tag is not None and tag not in (exp.tags or []):
+        return False
+    return True
+
+
+def _read_entries(
+    path: Path, since: datetime | None, tag: str | None
+) -> list[Experience]:
+    """Parse the JSONL and apply filters. Empty on I/O error."""
+    entries: list[Experience] = []
+    try:
+        with path.open(encoding="utf-8") as fh:
+            for line in fh:
+                if not line.strip():
+                    continue
+                exp = _parse_entry(line)
+                if exp is None:
+                    continue
+                if _filter_entry(exp, since, tag):
+                    entries.append(exp)
+    except OSError:
+        return []
+    return entries
+
+
+def query_experiences(
+    agent_id: str,
+    *,
+    limit: int = 5,
+    since: datetime | None = None,
+    tag: str | None = None,
+) -> list[Experience]:
+    """Read experiences for an agent. Most recent first.
+
+    Empty list when the agent has no record or the agent_id is unsafe.
+    Malformed JSONL lines are skipped silently.
+    """
+    path = _path_for(agent_id)
+    if path is None or not path.exists():
+        return []
+    entries = _read_entries(path, since, tag)
+    entries.sort(key=lambda e: e.ts, reverse=True)
+    return entries[:limit]

package/core/governance/agent_experiences_cli.py

@@ -0,0 +1,98 @@
+"""CLI viewer for agent experiences.
+
+Usage:
+    python -m core.governance.agent_experiences_cli list <agent_id> [options]
+
+Options:
+    --limit N        Show at most N most-recent experiences (default 10)
+    --since DATE     ISO date or datetime (e.g. 2026-05-01)
+    --tag TAG        Show only entries with this tag
+
+Examples:
+    python -m core.governance.agent_experiences_cli list tech-lead-paulo
+    python -m core.governance.agent_experiences_cli list cqo-marta --limit 5
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import datetime
+
+from core.governance.agent_experiences import query_experiences
+
+
+def _format_experience(exp, index: int) -> str:
+    lines = [
+        f"  [{index}] {exp.ts}  {exp.verdict}  {exp.context}",
+    ]
+    if exp.patterns:
+        lines.append(f"        patterns: {', '.join(exp.patterns)}")
+    for blocker in (exp.blockers or [])[:5]:
+        lines.append(f"        - {blocker}")
+    if exp.fix_applied:
+        lines.append(f"        fix: {exp.fix_applied}")
+    if exp.references:
+        refs = ", ".join(exp.references[:3])
+        lines.append(f"        refs: {refs}")
+    if exp.tags:
+        lines.append(f"        tags: {', '.join(exp.tags)}")
+    return "\n".join(lines)
+
+
+def _parse_since(value: str) -> datetime:
+    """Accept either an ISO date (YYYY-MM-DD) or full ISO datetime."""
+    for fmt in ("%Y-%m-%dT%H:%M:%S%z", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%d"):
+        try:
+            return datetime.strptime(value, fmt)
+        except ValueError:
+            continue
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError as exc:
+        raise SystemExit(f"error: invalid --since value: {value}") from exc
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m core.governance.agent_experiences_cli",
+        description="Inspect Quality Gate experience records for an agent.",
+    )
+    subparsers = parser.add_subparsers(dest="cmd", required=True)
+    list_p = subparsers.add_parser("list", help="List experiences for an agent.")
+    list_p.add_argument("agent_id", help="Agent ID, e.g. tech-lead-paulo")
+    list_p.add_argument("--limit", type=int, default=10, help="Max records (default 10)")
+    list_p.add_argument("--since", default=None, help="ISO date or datetime cutoff")
+    list_p.add_argument("--tag", default=None, help="Filter by tag")
+    return parser
+
+
+def _print_results(agent_id: str, experiences: list) -> int:
+    if not experiences:
+        print(f"No experiences recorded for {agent_id}.")
+        return 0
+    print(
+        f"Experiences for {agent_id} "
+        f"({len(experiences)} record(s), most recent first):\n"
+    )
+    for i, exp in enumerate(experiences, start=1):
+        print(_format_experience(exp, i))
+        print()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv if argv is not None else sys.argv[1:])
+    if args.cmd != "list":
+        parser.print_help()
+        return 2
+    since = _parse_since(args.since) if args.since else None
+    experiences = query_experiences(
+        args.agent_id, limit=args.limit, since=since, tag=args.tag
+    )
+    return _print_results(args.agent_id, experiences)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/core/governance/cqo_experience_recorder.py

@@ -0,0 +1,172 @@
+"""Parse Marta (CQO) verdict text and persist Experience records.
+
+When the orchestrator dispatches the `cqo` subagent for a Quality Gate
+review, Marta returns a verdict in a stable format (`Quality Gate
+Verdict: APPROVED|REJECTED`, with blockers labelled `B1.`, `B2.`,
+`M1.`, ...). This module parses that text and, when the verdict is
+REJECTED, appends an `Experience` to the failing agent's log so future
+dispatches inherit the lesson.
+
+For PR3 v1 the recorder is invoked manually by the orchestrator after a
+CQO dispatch. A future PR can wire it into a PostToolUse hook on the
+`Agent` tool so the persistence happens automatically.
+
+PR3 of the Squad Intelligence Upgrade.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from core.governance.agent_experiences import (
+    Experience,
+    record_experience,
+)
+
+
+_VERDICT_RE = re.compile(
+    r"Quality Gate Verdict:\s*(APPROVED|REJECTED)", re.IGNORECASE
+)
+
+# Blocker headings used by Marta across the codebase. Examples observed:
+# `**B1.` `**B2.` `**M1.` (markdown bold + dot/colon)
+# `B1.` `B1:` (plain)
+# `B1 description` (space-only separator — PR3 v3.74.0 widened per QG B5)
+# `B10.` `B11.` (double-digit labels)
+#
+# Documented limitation: inline blocker references mid-paragraph
+# (e.g., "The reviewer noted B1. is problematic") are NOT extracted —
+# only line-anchored labels qualify. This is intentional to keep
+# false-positive rate low; if we ever need inline capture, add a
+# separate pass with a stricter context check.
+_BLOCKER_RE = re.compile(
+    r"^(?:\*\*)?\s*([BMN])(\d+)[\s\.:](?:\s*\*\*)?\s*(.+?)(?:\*\*)?$",
+    re.MULTILINE,
+)
+
+# Common pattern hints Marta surfaces. Order matters — first match wins.
+_PATTERN_HINTS: tuple[tuple[str, str], ...] = (
+    (r"function length|line ceiling|\d+\s+lines?|exceeds.*line", "function-length-violation"),
+    (r"command[ -]injection|CWE-77|shell escape", "command-injection-risk"),
+    (r"path[ -]traversal|CWE-22", "path-traversal-risk"),
+    (r"undocumented|missing.*constitution|not in flow", "governance-gap"),
+    (r"missing.*test|zero.*coverage|no pytest", "test-coverage-gap"),
+    (r"workaround|hack|shortcut|TODO", "shortcut-applied"),
+    (r"client name|leak|confidential", "confidentiality-risk"),
+    (r"sycophancy|yes[- ]man|capitulat", "sycophancy-violation"),
+)
+
+
+@dataclass
+class ParsedVerdict:
+    """Structured view of a Marta verdict string."""
+
+    verdict: str  # "APPROVED" | "REJECTED" | "UNKNOWN"
+    blockers: list[str]
+    patterns: list[str]
+
+
+def parse_cqo_verdict(text: str) -> ParsedVerdict:
+    """Extract verdict, blocker list, and ALL matching pattern hints."""
+    if not text:
+        return ParsedVerdict(verdict="UNKNOWN", blockers=[], patterns=[])
+    verdict = _extract_verdict(text)
+    blockers = _extract_blockers(text) if verdict == "REJECTED" else []
+    patterns = _classify_patterns(text) if verdict == "REJECTED" else []
+    return ParsedVerdict(verdict=verdict, blockers=blockers, patterns=patterns)
+
+
+def _extract_verdict(text: str) -> str:
+    match = _VERDICT_RE.search(text)
+    if not match:
+        return "UNKNOWN"
+    return match.group(1).upper()
+
+
+def _extract_blockers(text: str) -> list[str]:
+    """Capture lines that start with a blocker label (B/M/N + digits)."""
+    blockers: list[str] = []
+    for match in _BLOCKER_RE.finditer(text):
+        kind, num, headline = match.group(1), match.group(2), match.group(3)
+        # Strip markdown markers and trailing whitespace.
+        headline = headline.replace("**", "").strip()
+        # Cap headline length so a single misformatted line cannot dominate.
+        if len(headline) > 200:
+            headline = headline[:197] + "..."
+        blockers.append(f"{kind}{num}: {headline}")
+    return blockers
+
+
+def _classify_patterns(text: str) -> list[str]:
+    """Return ALL matching pattern labels, in registry order.
+
+    First-match-wins was masking secondary patterns (PR3 QG-B6): a
+    verdict citing both governance-gap and function-length would be
+    classified only as function-length, and the agent would miss the
+    structural lesson. Returning all matches lets the dispatched agent
+    see every category at once.
+    """
+    lowered = text.lower()
+    matched: list[str] = []
+    for pattern, label in _PATTERN_HINTS:
+        if re.search(pattern, lowered, re.IGNORECASE):
+            matched.append(label)
+    return matched
+
+
+def _build_experience(
+    parsed: "ParsedVerdict",
+    *,
+    agent_id: str,
+    session_id: str,
+    context: str,
+    references: list[str] | None,
+    tags: list[str] | None,
+    fix_applied: str | None,
+) -> Experience:
+    """Compose an Experience from a parsed REJECTED verdict + caller metadata."""
+    return Experience(
+        ts=datetime.now(timezone.utc).isoformat(),
+        agent_id=agent_id,
+        session_id=session_id,
+        context=context,
+        verdict="REJECTED",
+        blockers=parsed.blockers,
+        patterns=parsed.patterns,
+        fix_applied=fix_applied,
+        references=references or [],
+        tags=tags or [],
+    )
+
+
+def record_from_verdict(
+    *,
+    verdict_text: str,
+    agent_id: str,
+    session_id: str,
+    context: str,
+    references: list[str] | None = None,
+    tags: list[str] | None = None,
+    fix_applied: str | None = None,
+) -> Experience | None:
+    """Parse `verdict_text` and append one Experience to `agent_id`'s log.
+
+    Returns the persisted Experience, or None when the verdict is not
+    REJECTED (APPROVED + UNKNOWN are not lessons worth recording).
+    """
+    parsed = parse_cqo_verdict(verdict_text)
+    if parsed.verdict != "REJECTED":
+        return None
+    experience = _build_experience(
+        parsed,
+        agent_id=agent_id,
+        session_id=session_id,
+        context=context,
+        references=references,
+        tags=tags,
+        fix_applied=fix_applied,
+    )
+    record_experience(experience)
+    return experience

package/core/synapse/agent_experiences_layer.py

@@ -0,0 +1,117 @@
+"""Synapse layer L2.6 — Agent Experience injection.
+
+When the user prompt contains `[arka:dispatch] <from> -> <target>`, this
+layer queries `core.governance.agent_experiences` for the target agent's
+recent experiences (REJECTED verdicts, lessons captured by the QG loop)
+and injects them as context so the dispatched specialist inherits prior
+failures across sessions.
+
+Designed as a standalone `Layer` subclass — engine wiring happens in a
+follow-up release (v3.74.1). For PR3 v1, callers (the UserPromptSubmit
+hook, or a manual dispatch wrapper) invoke `compute()` directly.
+
+Cache TTL: 30s. The experience file is appended-to, not rewritten, so a
+short TTL keeps newly-recorded lessons visible to the immediately-next
+dispatch.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+
+from core.governance.agent_experiences import Experience, query_experiences
+from core.synapse.layers import Layer, LayerResult, PromptContext
+
+
+# Mirror the parser in core.workflow.specialist_enforcer so we recognise
+# the same marker the operator (and the constitution rule
+# `dispatch-must-be-announced`) require for specialist dispatches.
+_DISPATCH_RE = re.compile(
+    r"\[arka:dispatch\]\s*[\w-]+\s*->\s*([\w-]+)", re.IGNORECASE
+)
+
+
+class AgentExperiencesLayer(Layer):
+    """L2.6 — inject recent experiences for the dispatched specialist."""
+
+    def __init__(self, limit: int = 5) -> None:
+        self._limit = limit
+
+    @property
+    def id(self) -> str:
+        return "L2.6"
+
+    @property
+    def name(self) -> str:
+        return "AgentExperiences"
+
+    @property
+    def cache_ttl(self) -> int:
+        return 30
+
+    @property
+    def priority(self) -> int:
+        return 25  # after AgentLayer (L2 prio 20), before KBContext (L2.5)
+
+    def compute(self, ctx: PromptContext) -> LayerResult:
+        start = time.time()
+        target = _extract_dispatch_target(ctx.user_input)
+        if target is None:
+            return self._empty_result(start)
+
+        experiences = query_experiences(target, limit=self._limit)
+        if not experiences:
+            return self._empty_result(start, tag=f"[agent-experiences:{target} none]")
+
+        content = format_experiences(target, experiences)
+        ms = int((time.time() - start) * 1000)
+        return LayerResult(
+            layer_id=self.id,
+            tag=f"[agent-experiences:{target} count:{len(experiences)}]",
+            content=content,
+            tokens_est=max(1, len(content) // 4),
+            compute_ms=ms,
+            cached=False,
+        )
+
+    def _empty_result(self, start: float, tag: str = "") -> LayerResult:
+        return LayerResult(
+            layer_id=self.id,
+            tag=tag,
+            content="",
+            tokens_est=0,
+            compute_ms=int((time.time() - start) * 1000),
+            cached=False,
+        )
+
+
+def _extract_dispatch_target(user_input: str) -> str | None:
+    """Return the agent id from the most recent `[arka:dispatch]` marker."""
+    if not user_input:
+        return None
+    matches = list(_DISPATCH_RE.finditer(user_input))
+    if not matches:
+        return None
+    return matches[-1].group(1).lower()
+
+
+def format_experiences(target: str, experiences: list[Experience]) -> str:
+    """Render a compact, model-readable summary of past lessons."""
+    lines = [f"Past lessons for {target} (most recent first):"]
+    for i, exp in enumerate(experiences, start=1):
+        verdict = exp.verdict or "?"
+        context = exp.context or "(no context)"
+        head = f"  {i}. [{verdict}] {context}"
+        if exp.patterns:
+            head += f" — patterns: {', '.join(exp.patterns)}"
+        lines.append(head)
+        for blocker in (exp.blockers or [])[:3]:
+            lines.append(f"     - {blocker}")
+        if exp.fix_applied:
+            lines.append(f"     fix: {exp.fix_applied}")
+        if exp.references:
+            refs = ", ".join(exp.references[:2])
+            lines.append(f"     refs: {refs}")
+    lines.append("Apply these lessons proactively. Do not repeat the rejected patterns.")
+    return "\n".join(lines)

package/installer/cli.js

@@ -92,10 +92,12 @@ async function main() {
       break;
     }
 
-    case "doctor":
+    case "doctor": {
       const { doctor } = await import("./doctor.js");
-      await doctor();
+      const fixMode = positionals.slice(1).includes("--fix") || values.fix === true;
+      await doctor({ fix: fixMode });
       break;
+    }
 
     case "update":
       const { update } = await import("./update.js");

package/installer/doctor.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
-import { getArkaosPython, getVenvPython, canImportCore, getRepoRoot } from "./python-resolver.js";
+import { getArkaosPython, getVenvPython, canImportCore, getRepoRoot, diagnoseVenv, ensureVenvHealthy } from "./python-resolver.js";
 import { IS_WINDOWS, HOOK_EXT, CMD_FINDER } from "./platform.js";
 import { checkNode, checkObsidian, checkOllama } from "./system-tools.js";
 
@@ -54,10 +54,21 @@ const checks = [
   },
   {
     name: "venv",
-    description: "ArkaOS virtual environment exists",
-    severity: "warn",
-    check: () => existsSync(getVenvPython()),
-    fix: () => "Run: npx arkaos@latest update (creates venv automatically)",
+    // PR2 v3.73.1: promoted from "warn" to "fail" — without the venv, the
+    // dashboard cannot start at all (start-dashboard.{sh,ps1} now fail fast
+    // instead of falling back to ambient python3 with missing deps).
+    description: "ArkaOS virtual environment exists and is runnable",
+    severity: "fail",
+    check: () => {
+      const venvDir = join(INSTALL_DIR, "venv");
+      const d = diagnoseVenv(venvDir);
+      return d.healthy;
+    },
+    fix: () => {
+      const venvDir = join(INSTALL_DIR, "venv");
+      const d = diagnoseVenv(venvDir);
+      return `Run: npx arkaos doctor --fix  (current state: ${d.reason})`;
+    },
   },
   {
     name: "hooks-dir",
@@ -241,8 +252,33 @@ if (IS_WINDOWS) {
   );
 }
 
-export async function doctor() {
-  console.log("\n  ArkaOS Doctor — Health Checks\n");
+export async function doctor(options = {}) {
+  const fixMode = !!options.fix;
+  console.log(`\n  ArkaOS Doctor — Health Checks${fixMode ? " (--fix)" : ""}\n`);
+
+  // ─── --fix: repair the venv before reporting checks (PR2 v3.73.1) ────
+  // Targeted, idempotent self-heal: detects broken symlinks / version
+  // drift / missing bin/python and recreates the venv with --clear so
+  // the subsequent venv check has a chance of passing.
+  if (fixMode) {
+    const venvDir = join(INSTALL_DIR, "venv");
+    const before = diagnoseVenv(venvDir);
+    if (before.healthy) {
+      console.log("  ℹ Venv already healthy — no repair needed");
+    } else {
+      console.log(`  → Repairing venv (current state: ${before.reason})`);
+      const result = ensureVenvHealthy({
+        venvDir,
+        log: (msg) => console.log("    " + msg.trim()),
+      });
+      if (result.healthy && result.repaired) {
+        console.log("  ✓ Venv repaired");
+      } else if (!result.healthy) {
+        console.log(`  ✗ Venv repair failed (${result.reason})`);
+      }
+    }
+    console.log("");
+  }
 
   let passed = 0;
   let warned = 0;

package/installer/python-resolver.js

@@ -6,7 +6,7 @@
  * and guarantees the doctor checks the same interpreter the installer uses.
  */
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir, platform } from "node:os";
 import { execSync } from "node:child_process";
@@ -94,6 +94,134 @@ export function findSystemPython() {
   return null;
 }
 
+/**
+ * Diagnose a venv directory. Pure read-only — does not modify anything.
+ * Returns { healthy: bool, reason: string, pythonPath?: string }.
+ *
+ * Reasons:
+ *  - "missing"        — venv dir absent OR bin/python absent (no symlink)
+ *  - "broken-symlink" — bin/python is a symlink to a missing target
+ *                       (typical after Homebrew rotates Python patch versions)
+ *  - "version-failed" — python --version exec failed (corrupt binary)
+ *  - "ok"             — venv healthy, python runs
+ */
+export function diagnoseVenv(venvDir) {
+  const isWin = platform() === "win32";
+  const pythonPath = isWin
+    ? join(venvDir, "Scripts", "python.exe")
+    : join(venvDir, "bin", "python");
+
+  // existsSync FOLLOWS symlinks, so a broken symlink returns false here
+  // even when the symlink itself is present on disk. Distinguish via lstat.
+  if (!existsSync(pythonPath)) {
+    let isBroken = false;
+    try {
+      const stat = lstatSync(pythonPath);
+      if (stat.isSymbolicLink()) isBroken = true;
+    } catch {
+      // pythonPath doesn't exist at all — fall through as "missing"
+    }
+    return {
+      healthy: false,
+      reason: isBroken ? "broken-symlink" : "missing",
+    };
+  }
+
+  // pythonPath exists. Try to run it — guards against corrupt-but-present
+  // binaries (e.g., a non-executable file placed at bin/python by accident).
+  try {
+    const out = execSync(`"${pythonPath}" --version 2>&1`, {
+      stdio: "pipe",
+      timeout: 5000,
+    }).toString();
+    if (!/Python 3/.test(out)) {
+      return { healthy: false, reason: "version-failed", pythonPath };
+    }
+    return { healthy: true, reason: "ok", pythonPath };
+  } catch {
+    return { healthy: false, reason: "version-failed", pythonPath };
+  }
+}
+
+
+/**
+ * Ensure the venv is healthy, repairing if needed.
+ * Returns { healthy: bool, repaired: bool, reason: string }.
+ *
+ * Repair strategy: `python -m venv --clear` removes the stale bin/ Scripts
+ * directories (closing the broken-symlink and version-failed cases) and
+ * recreates them against the currently resolvable system Python. The
+ * post-repair venv is re-diagnosed to confirm health before returning.
+ *
+ * Options:
+ *  - venvDir  (default: ~/.arkaos/venv)
+ *  - log      (default: console.log)
+ *  - skipDeps (default: false) — when true, do not attempt pip upgrades
+ *             after repair. Used by tests to keep them fast/offline.
+ */
+export function ensureVenvHealthy(options = {}) {
+  const venvDir = options.venvDir || join(INSTALL_DIR, "venv");
+  const log = options.log || console.log;
+  const skipDeps = !!options.skipDeps;
+
+  const diagnosis = diagnoseVenv(venvDir);
+  if (diagnosis.healthy) {
+    log(`         ✓ Venv healthy at ${venvDir}`);
+    return { healthy: true, repaired: false, reason: "already-healthy" };
+  }
+
+  log(`         ⚠ Venv ${diagnosis.reason} at ${venvDir} — repairing`);
+
+  const systemPython = findSystemPython();
+  if (!systemPython) {
+    return {
+      healthy: false,
+      repaired: false,
+      reason: `${diagnosis.reason}-and-no-system-python`,
+    };
+  }
+
+  try {
+    execSync(`"${systemPython}" -m venv --clear "${venvDir}"`, {
+      stdio: "pipe",
+      timeout: 60000,
+    });
+    log(`         ✓ Venv recreated at ${venvDir}`);
+  } catch (err) {
+    const msg = (err && err.message ? err.message : String(err)).slice(0, 100);
+    return {
+      healthy: false,
+      repaired: false,
+      reason: `recreate-failed: ${msg}`,
+    };
+  }
+
+  const post = diagnoseVenv(venvDir);
+  if (!post.healthy) {
+    return {
+      healthy: false,
+      repaired: true,
+      reason: `repaired-but-still-unhealthy: ${post.reason}`,
+    };
+  }
+
+  if (!skipDeps) {
+    try {
+      execSync(`"${post.pythonPath}" -m pip install --upgrade pip --quiet`, {
+        stdio: "pipe",
+        timeout: 60000,
+      });
+    } catch { /* pip upgrade is non-critical */ }
+  }
+
+  return {
+    healthy: true,
+    repaired: true,
+    reason: `repaired-from-${diagnosis.reason}`,
+  };
+}
+
+
 /**
  * Create the ArkaOS venv if it doesn't exist.
  * Returns true on success, false on failure.

package/installer/update.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, writeFileSync, copyFileSync, chmodSync, mkdir
 import { join, dirname, resolve } from "node:path";
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
-import { ensureVenv, getArkaosPython, pipInstall } from "./python-resolver.js";
+import { ensureVenv, ensureVenvHealthy, getArkaosPython, pipInstall } from "./python-resolver.js";
 import { getRuntimeConfig } from "./detect-runtime.js";
 import { loadAdapter } from "./index.js";
 import { migrateUserData, printMigrationReport } from "./migrate-user-data.js";
@@ -103,10 +103,15 @@ export async function update() {
   // ── 1. Update Python deps (using venv) ──
   console.log("  [1/8] Updating Python dependencies...");
 
-  // Ensure venv exists (creates one if missing — fixes PEP 668)
-  const venvOk = ensureVenv((msg) => console.log(msg));
-  if (!venvOk) {
-    console.log("         \u26a0 Could not create venv — trying system Python with PEP 668 handling");
+  // Ensure venv is healthy (creates, repairs broken symlinks, or no-ops).
+  // PR2 v3.73.1 — previously a stale broken-symlink venv could pass the
+  // existence check, and the dashboard would silently fall back to ambient
+  // python3 without sqlite-vec/fastembed.
+  const venvHealth = ensureVenvHealthy({ log: (msg) => console.log(msg) });
+  if (!venvHealth.healthy) {
+    console.log(`         \u26a0 Venv unhealthy (${venvHealth.reason}) - falling back to system Python with PEP 668 handling`);
+  } else if (venvHealth.repaired) {
+    console.log(`         \u2713 Venv repaired (${venvHealth.reason})`);
   }
 
   const pythonCmd = getArkaosPython();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "3.73.0",
+  "version": "3.74.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "3.73.0"
+version = "3.74.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/start-dashboard.ps1

@@ -82,10 +82,13 @@ Write-Host ''
 Write-Host '  ArkaOS Dashboard'
 Write-Host '  -----------------'
 
-# --- Locate Python ---------------------------------------------------------
-# Prefer the ArkaOS venv python recorded in the install manifest so the
-# dashboard API runs against the same interpreter the installer uses.
-function Find-Python {
+# --- Locate ArkaOS venv Python (PR2 v3.73.1 — no ambient fallback) --------
+# Previously this function fell back to system python/python3/py when the
+# venv wasn't available. That hid broken-venv conditions and produced
+# half-working dashboards without sqlite-vec/fastembed. Now we look only at
+# the manifest pythonCmd and the venv path, and fail fast with actionable
+# remediation otherwise.
+function Find-VenvPython {
     $manifest = Join-Path $arkaosHome 'install-manifest.json'
     if (Test-Path -LiteralPath $manifest) {
         try {
@@ -97,17 +100,22 @@ function Find-Python {
     }
     $venvPy = Join-Path $arkaosHome 'venv\Scripts\python.exe'
     if (Test-Path -LiteralPath $venvPy) { return $venvPy }
-    foreach ($cmd in 'python','python3','py') {
-        $found = Get-Command $cmd -ErrorAction SilentlyContinue
-        if ($found) { return $found.Source }
-    }
     return $null
 }
 
-$python = Find-Python
+$python = Find-VenvPython
 if (-not $python) {
-    Write-Host '  Error: no usable Python interpreter found.' -ForegroundColor Red
-    Write-Host '  Install Python 3.11+ and rerun.'             -ForegroundColor DarkGray
+    Write-Host ''
+    Write-Host "  X ArkaOS venv unavailable at $arkaosHome\venv\Scripts\python.exe" -ForegroundColor Red
+    Write-Host ''
+    Write-Host '    The dashboard must run from the ArkaOS venv so that'      -ForegroundColor DarkGray
+    Write-Host '    sqlite-vec, fastembed, fastapi, and uvicorn are present.' -ForegroundColor DarkGray
+    Write-Host '    The ambient python fallback was removed in v3.73.1.'      -ForegroundColor DarkGray
+    Write-Host ''
+    Write-Host '    Fix:' -ForegroundColor DarkGray
+    Write-Host '      npx arkaos doctor --fix       (repairs broken venv in place)'    -ForegroundColor DarkGray
+    Write-Host '      npx arkaos@latest update      (full reinstall, slower)'          -ForegroundColor DarkGray
+    Write-Host ''
     exit 1
 }
 

package/scripts/start-dashboard.sh

@@ -6,9 +6,31 @@ ARKAOS_ROOT="${ARKAOS_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
 DASHBOARD_DIR="${ARKAOS_ROOT}/dashboard"
 PID_FILE="$HOME/.arkaos/dashboard.pid"
 PORT_FILE="$HOME/.arkaos/dashboard.ports"
+VENV_PYTHON="$HOME/.arkaos/venv/bin/python"
 
 mkdir -p "$HOME/.arkaos"
 
+# ── Venv guard (PR2 v3.73.1 — Force Specialist Dispatch dogfood) ──
+# Previously the dashboard fell back to ambient `python3` when the venv
+# wasn't available. That hid broken-venv conditions (Homebrew patch
+# rotations leaving dangling symlinks) and produced half-working dashboards
+# without sqlite-vec / fastembed. Now we fail fast with a clear remediation.
+# `[ -x ]` follows symlinks, so a broken symlink correctly fails the test.
+if [ ! -x "$VENV_PYTHON" ]; then
+  echo ""
+  echo "  ✗ ArkaOS venv unavailable at $VENV_PYTHON"
+  echo ""
+  echo "    The dashboard must run from the ArkaOS venv so that"
+  echo "    sqlite-vec, fastembed, fastapi, and uvicorn are present."
+  echo "    The ambient python3 fallback was removed in v3.73.1."
+  echo ""
+  echo "    Fix:"
+  echo "      npx arkaos doctor --fix       (repairs broken venv in place)"
+  echo "      npx arkaos@latest update      (full reinstall, slower)"
+  echo ""
+  exit 1
+fi
+
 # ── Kill existing if running ──
 if [ -f "$PID_FILE" ]; then
   while read -r pid; do
@@ -38,7 +60,7 @@ echo "  ─────────────────"
 # ── Start FastAPI backend ──
 API_LOG="$HOME/.arkaos/api.log"
 echo "  Starting API on :${API_PORT}..."
-ARKAOS_ROOT="$ARKAOS_ROOT" python3 "${ARKAOS_ROOT}/scripts/dashboard-api.py" --port "$API_PORT" > "$API_LOG" 2>&1 &
+ARKAOS_ROOT="$ARKAOS_ROOT" "$VENV_PYTHON" "${ARKAOS_ROOT}/scripts/dashboard-api.py" --port "$API_PORT" > "$API_LOG" 2>&1 &
 API_PID=$!
 
 # Wait for API with health check (up to 10 seconds)