arkaos 4.13.2 → 4.14.0

package/core/synapse/session_memory_layer.py

@@ -0,0 +1,152 @@
+"""Synapse L9.5 — session semantic memory retrieval (F1-A3).
+
+Closes the memory loop opened by F1-A2: reads the per-session cache the
+detached turn-capture worker precomputed (semantic neighbours, labeled
+``ranked@HH:MMZ`` with the cache's own computed_at — or ``pre-ranked``
+when no timestamp exists; the label states WHEN the ranking happened,
+never claims it was for this prompt) plus a live keyword LIKE over the
+store for the current prompt.
+
+Honesty contract (identical to L2.5 / vector_store.py): semantic hits
+carry their cosine score; keyword hits carry ``score=None`` and are
+labeled ``keyword — NOT semantic similarity``. The layer NEVER embeds —
+zero embedding cost on the prompt hot path, ever.
+
+Flag: ``synapse.l95SessionMemory`` (default ON) + env ``ARKA_BYPASS_L95``.
+Inert (zero tokens) when the store is empty or the flag is off.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+from core.synapse.layers import Layer, LayerResult, PromptContext
+
+_MAX_ITEMS = 5
+_SUMMARY_CHARS = 160
+_LIVE_KEYWORD_K = 2
+_CACHE_SEMANTIC_K = 3
+_CONFIG_PATH = Path.home() / ".arkaos" / "config.json"
+
+
+def _l95_feature_flag_on() -> bool:
+    if os.environ.get("ARKA_BYPASS_L95", "").strip() == "1":
+        return False
+    try:
+        data = json.loads(_CONFIG_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return True
+    synapse_cfg = data.get("synapse") or {}
+    return bool(synapse_cfg.get("l95SessionMemory", True))
+
+
+def _read_session_cache(session_id: str) -> tuple[list[dict], str]:
+    """Precomputed neighbours + the timestamp they were ranked at."""
+    if not session_id:
+        return [], ""
+    path = Path.home() / ".arkaos" / "context-cache" / f"session-memory-{session_id}.json"
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return [], ""
+    if payload.get("version") != 1:
+        return [], ""
+    items = payload.get("items")
+    ranked_at = str(payload.get("computed_at") or "")
+    if not isinstance(items, list):
+        return [], ""
+    return items[:_CACHE_SEMANTIC_K], ranked_at
+
+
+def _format_item(item: dict, ranked_at: str = "") -> str:
+    from core.memory.semantic_store import neutralize_summary
+
+    summary = neutralize_summary(item.get("summary") or "")[:_SUMMARY_CHARS]
+    if not summary:
+        return ""
+    score = item.get("score")
+    if item.get("retrieval") == "semantic" and isinstance(score, (int, float)):
+        # Provenance is the payload's own computed_at (UTC isoformat) —
+        # the detached worker may lag a turn, so the label states WHEN
+        # it ranked, never claims "last turn". Z marks UTC explicitly.
+        stamp = f" ranked@{ranked_at[11:16]}Z" if len(ranked_at) >= 16 else " pre-ranked"
+        label = f"semantic {score:.2f}{stamp}"
+    else:
+        label = "keyword — NOT semantic similarity"
+    project = neutralize_summary(item.get("project_name") or "")
+    suffix = f" ({project})" if project else ""
+    return f"- [{label}] {summary}{suffix}"
+
+
+class SessionMemoryLayer(Layer):
+    """L9.5: cross-session turn memory — cache read + live keyword only."""
+
+    @property
+    def id(self) -> str:
+        return "L9.5"
+
+    @property
+    def name(self) -> str:
+        return "SessionSemanticMemory"
+
+    @property
+    def cache_ttl(self) -> int:
+        # Best-effort freshness: the cache write is detached and may lag
+        # a turn — recomputing here is one file read + one indexed LIKE.
+        return 0
+
+    @property
+    def priority(self) -> int:
+        return 91  # right after L9 SessionContext (90)
+
+    def compute(self, ctx: PromptContext) -> LayerResult:
+        start = time.time()
+        content = ""
+        try:
+            if ctx.user_input and _l95_feature_flag_on():
+                content = self._retrieve(ctx)
+        except Exception:  # noqa: BLE001 — layer must never break the prompt
+            content = ""
+        elapsed = int((time.time() - start) * 1000)
+        if not content:
+            return LayerResult(layer_id=self.id, tag="", content="",
+                               tokens_est=0, compute_ms=elapsed, cached=False)
+        count = content.count("\n- ") + (1 if content.startswith("- ") else 0)
+        return LayerResult(
+            layer_id=self.id,
+            tag=f"[session-memory:{count}]",
+            content=content,
+            tokens_est=len(content.split()),
+            compute_ms=elapsed,
+            cached=False,
+        )
+
+    def _retrieve(self, ctx: PromptContext) -> str:
+        session_id = str((ctx.extra or {}).get("session_id") or "")
+        lines: list[str] = []
+        seen: set[str] = set()
+        items, ranked_at = _read_session_cache(session_id)
+        for item in items:
+            line = _format_item(item, ranked_at)
+            if line and item.get("summary") not in seen:
+                seen.add(item.get("summary"))
+                lines.append(line)
+        # Scope-or-skip: an unscoped LIKE would surface one client's
+        # turns inside another client's prompt (QG blocker B2 —
+        # v2.18.0 confidentiality precedent). No resolvable project
+        # scope ⇒ NO live search, never a silently-global one.
+        project = ctx.project_name or (Path(ctx.cwd).name if ctx.cwd else "")
+        from core.memory.semantic_store import SessionMemoryStore, default_db_path
+        if project and default_db_path().is_file():
+            hits = SessionMemoryStore().keyword_search(
+                ctx.user_input, project, top_k=_LIVE_KEYWORD_K
+            )
+            for hit in hits:
+                line = _format_item(hit)
+                if line and hit.get("summary") not in seen:
+                    seen.add(hit.get("summary"))
+                    lines.append(line)
+        return "\n".join(lines[:_MAX_ITEMS])

package/installer/adapters/claude-code.js

@@ -79,6 +79,15 @@ export function deployProjectAgents(projectDir, sourceRoot = ARKAOS_ROOT) {
  * `shell: "powershell"` field and letting Claude Code handle the
  * PowerShell invocation itself.
  */
+// F2-6: hooks with a Node fast-path shim. POSIX-only — Windows keeps
+// the .ps1 -> Python chain untouched (the .cjs stdin contract is only
+// validated against bash-spawned hooks). Registration is conditional on
+// the deployed .cjs actually existing, so an older package or a partial
+// deploy degrades to the .sh chain instead of a dead command. Install-
+// time opt-out: ARKA_INSTALL_FASTPATH=0 registers the .sh as before
+// (runtime kill-switch is ARKA_HOOK_FASTPATH=0, read by the shim).
+const FASTPATH_HOOKS = new Set(["pre-tool-use", "post-tool-use"]);
+
 function hookEntry(hooksDir, name, timeout) {
   if (IS_WINDOWS) {
     return {
@@ -88,6 +97,21 @@ function hookEntry(hooksDir, name, timeout) {
       timeout,
     };
   }
+  if (
+    FASTPATH_HOOKS.has(name) &&
+    process.env.ARKA_INSTALL_FASTPATH !== "0" &&
+    existsSync(join(hooksDir, `${name}.cjs`)) &&
+    // QG B3: a split deploy (.cjs without _lib/fastpath) must never be
+    // registered — the shim would only ever delegate (it degrades
+    // safely, but registering the .sh directly is strictly better).
+    existsSync(join(hooksDir, "_lib", "fastpath", "engine.cjs"))
+  ) {
+    return {
+      type: "command",
+      command: join(hooksDir, `${name}.cjs`),
+      timeout,
+    };
+  }
   return {
     type: "command",
     command: join(hooksDir, `${name}.sh`),
@@ -151,6 +175,19 @@ export default {
       { hooks: [hookEntry(hooksDir, "stop", 5)] },
     ];
 
+    // SubagentStop — persist each subagent's output + warn-only honesty
+    // QA (phantom-action, meta-tag), nudging deliverable output toward the
+    // Quality Gate. 10s: transcript read + sanitize + persist (F2-4).
+    settings.hooks.SubagentStop = [
+      { hooks: [hookEntry(hooksDir, "subagent-stop", 10)] },
+    ];
+
+    // SessionEnd — final session digest (PreCompact only fires on
+    // compaction) + mark session ended. 15s (F2-4).
+    settings.hooks.SessionEnd = [
+      { hooks: [hookEntry(hooksDir, "session-end", 15)] },
+    ];
+
     // PreCompact — Session digest
     settings.hooks.PreCompact = [
       { hooks: [hookEntry(hooksDir, "pre-compact", 30)] },

package/installer/claude-plugins.js

@@ -21,6 +21,12 @@ import { join } from "node:path";
 // installed. Each entry is a GitHub `owner/repo` shorthand.
 export const DEFAULT_CLAUDE_MARKETPLACES = [
   "nextlevelbuilder/ui-ux-pro-max-skill",
+  // F2-7b: the ArkaOS marketplace itself — registered by GitHub
+  // owner/repo (NEVER a directory source anchored on the volatile npx
+  // cache). Registration costs zero context; the 16 per-department
+  // plugins stay opt-in pure (`/plugin install arkaos-<dept>@arkaos`),
+  // so DEFAULT_CLAUDE_PLUGINS deliberately does NOT change.
+  "andreagroferreira/arka-os",
 ];
 
 // Each entry is "name@marketplace" matching the `claude plugin install`

package/installer/cli.js

@@ -31,6 +31,13 @@ const { values, positionals } = parseArgs({
     // Fusion — `npx arkaos fusion [--save|--show] "question"`
     save: { type: "boolean" },
     show: { type: "boolean" },
+    // F2-7a — `npx arkaos mcp start [--write]`. Declared so it lands in
+    // `values.write` instead of a free positional under strict:false
+    // (the documented --fix lesson).
+    write: { type: "boolean" },
+    // F2-7c — `npx arkaos update --skills <curated|full>` (same
+    // strict:false declaration requirement).
+    skills: { type: "string" },
   },
   allowPositionals: true,
   strict: false,
@@ -59,6 +66,8 @@ Usage:
   npx arkaos keys             Manage API keys (OpenAI, fal.ai, etc.)
   npx arkaos models           Model Fabric: which model runs each role
   npx arkaos models set <role> <provider>/<model>  Re-route a role
+  npx arkaos mcp start        Start the arka-tools MCP server (stdio; --write enables writes)
+  npx arkaos update --skills <curated|full>  Choose the deployed skill set (default: curated on fresh installs)
   npx arkaos doctor           Run health checks
   npx arkaos uninstall        Remove ArkaOS
 
@@ -110,10 +119,11 @@ async function main() {
       break;
     }
 
-    case "update":
+    case "update": {
       const { update } = await import("./update.js");
-      await update();
+      await update({ skillsFlag: values.skills || "" });
       break;
+    }
 
     case "autostart": {
       const { autostart } = await import("./autostart.js");
@@ -230,6 +240,17 @@ async function main() {
       break;
     }
 
+    case "mcp": {
+      const verb = positionals[1];
+      if (verb !== "start") {
+        console.error('Usage: npx arkaos mcp start [--write]');
+        process.exit(1);
+      }
+      const { startServer } = await import("./mcp-runner.js");
+      process.exit(startServer({ write: Boolean(values.write) }));
+      break;
+    }
+
     default:
       console.error(`Unknown command: ${command}`);
       console.error('Run "npx arkaos help" for usage information.');

package/installer/config-seed.js

@@ -7,6 +7,7 @@
 // Seeded template keys (operator decisions):
 //   hooks.hardEnforcement = true   (PR19 v2.41.0)
 //   hooks.kbFirst         = true   (PR-3 v4.1 — KB-first ON out of the box)
+//   memory.sessionMemory  = true   (F1-A2 — session semantic memory ON)
 //
 // Returns a status object:
 //   { action: "created" | "added-key" | "noop"
@@ -21,13 +22,19 @@ import {
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 
-// Template: every hooks.* key seeded to `true` when unset.
-const SEEDED_HOOK_KEYS = ["hardEnforcement", "kbFirst"];
+// Template: every listed key seeded to `true` when unset, per section.
+const SEEDED_SECTIONS = {
+  hooks: ["hardEnforcement", "kbFirst"],
+  memory: ["sessionMemory"],
+};
 
 function defaultConfig() {
-  const hooks = {};
-  for (const key of SEEDED_HOOK_KEYS) hooks[key] = true;
-  return { hooks };
+  const config = {};
+  for (const [section, keys] of Object.entries(SEEDED_SECTIONS)) {
+    config[section] = {};
+    for (const key of keys) config[section][key] = true;
+  }
+  return config;
 }
 
 export function seedArkaosConfig({ home = homedir() } = {}) {
@@ -52,20 +59,22 @@ export function seedArkaosConfig({ home = homedir() } = {}) {
     return { action: "rewrote-corrupt", path: cfgPath, backup };
   }
 
-  config.hooks = config.hooks && typeof config.hooks === "object" ? config.hooks : {};
-
   let added = false;
   let preservedFalse = false;
-  for (const key of SEEDED_HOOK_KEYS) {
-    const current = config.hooks[key];
-    if (current === true) continue;
-    if (current === false) {
-      preservedFalse = true; // explicit user choice — never overwrite
-      continue;
+  for (const [section, keys] of Object.entries(SEEDED_SECTIONS)) {
+    const existing = config[section];
+    config[section] = existing && typeof existing === "object" ? existing : {};
+    for (const key of keys) {
+      const current = config[section][key];
+      if (current === true) continue;
+      if (current === false) {
+        preservedFalse = true; // explicit user choice — never overwrite
+        continue;
+      }
+      // Key unset (undefined, null, or any non-boolean) — set to true.
+      config[section][key] = true;
+      added = true;
     }
-    // Key unset (undefined, null, or any non-boolean) — set to true.
-    config.hooks[key] = true;
-    added = true;
   }
 
   if (added) {

package/installer/doctor.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { execSync } from "node:child_process";
@@ -34,6 +34,20 @@ export function hyperframesSkillsInstalled(
   );
 }
 
+// SQLite self-heal (F1-D1) leaves the corrupt original as
+// <db>.corrupt-<ts>.bak next to the recovered file. Their presence means
+// a store healed itself — surface it so the operator can inspect/delete.
+// baseDir is injectable for tests.
+export function corruptDbBackups(baseDir = INSTALL_DIR) {
+  try {
+    return readdirSync(baseDir, { recursive: true })
+      .map(String)
+      .filter((name) => /\.corrupt-\d+\.bak$/.test(name));
+  } catch {
+    return [];
+  }
+}
+
 export const checks = [
   {
     name: "install-dir",
@@ -95,12 +109,106 @@ export const checks = [
         "cwd-changed",
         "pre-tool-use",
         "stop",
+        "subagent-stop",
+        "session-end",
       ];
       const hooksDir = join(INSTALL_DIR, "config", "hooks");
       return required.every((h) => existsSync(join(hooksDir, `${h}${HOOK_EXT}`)));
     },
     fix: () => "Run: npx arkaos install --force",
   },
+  {
+    name: "hook-fastpath",
+    description: "Hook fast-path shims consistent (F2-6)",
+    severity: "fail",
+    check: () => {
+      // Only meaningful when the .cjs shims are deployed (POSIX installs
+      // from v4.14+). If they are, the manifest + engine + a node binary
+      // must exist, or every PreToolUse/PostToolUse fires a dead command
+      // that silently fails open — governance off with a green doctor.
+      if (IS_WINDOWS) return true;
+      const hooksDir = join(INSTALL_DIR, "config", "hooks");
+      const shims = ["pre-tool-use.cjs", "post-tool-use.cjs"]
+        .map((f) => join(hooksDir, f));
+      if (!shims.some((p) => existsSync(p))) return true; // .sh-only install
+      if (!shims.every((p) => existsSync(p))) return false; // partial deploy
+      if (!existsSync(join(hooksDir, "gate-manifest.json"))) return false;
+      if (!existsSync(join(hooksDir, "_lib", "fastpath", "engine.cjs"))) {
+        return false;
+      }
+      return commandExists("node");
+    },
+    fix: () =>
+      "Run: npx arkaos@latest update  (or export ARKA_HOOK_FASTPATH=0 to force the bash chain)",
+  },
+  {
+    name: "arka-tools-runner",
+    description: "arka-tools MCP server runnable (uv or venv with mcp SDK)",
+    severity: "warn",
+    check: () => {
+      // Deploy dir + at least one runner. WARN, never FAIL: uv OR a
+      // venv with the mcp extra is enough, and neither is mandatory
+      // for the core install (F2-7a, `npx arkaos mcp start`).
+      const toolsDir = join(
+        homedir(), ".claude", "skills", "arka", "mcp-tools");
+      if (!existsSync(join(toolsDir, "server.py"))) return false;
+      if (commandExists("uv")) return true;
+      const py = getArkaosPython();
+      if (!py) return false;
+      try {
+        // timeout parity with mcp-runner.js::venvHasMcp — a hung
+        // interpreter must not stall `npx arkaos doctor` (QG 7a M3).
+        execSync(`"${py}" -c "import mcp"`, { stdio: "ignore", timeout: 15000 });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    fix: () =>
+      "Install uv (https://docs.astral.sh/uv) or: ~/.arkaos/venv/bin/pip install 'mcp[cli]>=1.2.0' — then: npx arkaos mcp start",
+  },
+  {
+    name: "skills-surface",
+    description: "Deployed skill set matches the chosen mode (curated/full)",
+    severity: "warn",
+    check: () => {
+      // WARN-only classifier — the doctor NEVER deletes skills. Repo
+      // sub-skills outside the curated cut are "plugin-eligible"
+      // leftovers on a curated-mode machine; anything not in the
+      // generated skills-manifest (ecosystem skills like user project
+      // packs) is unknown/user and untouchable by construction.
+      let mode = "full";
+      try {
+        mode = JSON.parse(readFileSync(
+          join(INSTALL_DIR, "skills-mode.json"), "utf-8")).mode || "full";
+      } catch {}
+      if (mode !== "curated") return true;
+      const repoRoot = getRepoRoot();
+      if (!repoRoot) return true;
+      let manifest;
+      try {
+        manifest = JSON.parse(readFileSync(
+          join(repoRoot, "knowledge", "skills-manifest.json"), "utf-8"));
+      } catch {
+        return true; // older core without the manifest — nothing to judge
+      }
+      const skillsBase = join(homedir(), ".claude", "skills");
+      let leftovers = 0;
+      try {
+        for (const dir of readdirSync(skillsBase)) {
+          if (!dir.startsWith("arka-")) continue;
+          const slug = dir.slice("arka-".length);
+          const entry = manifest.skills ? manifest.skills[slug] : null;
+          if (entry && !entry.curated) leftovers++;
+        }
+      } catch {
+        return true;
+      }
+      return leftovers === 0;
+    },
+    fix: () =>
+      "Curated mode with plugin-eligible leftovers deployed (harmless, uses context budget). Install packs a la carte (/plugin install arkaos-<dept>@arkaos) or keep everything: npx arkaos update --skills full",
+  },
   {
     name: "constitution",
     description: "Constitution YAML present",
@@ -226,6 +334,13 @@ export const checks = [
     check: () => commandExists("codebase-memory-mcp"),
     fix: () => "Install codebase-memory-mcp (see mcps/registry.json entry for the one-liner), then /arka update to activate per project",
   },
+  {
+    name: "sqlite-corrupt-backups",
+    description: "No self-healed SQLite stores awaiting inspection",
+    severity: "warn",
+    check: () => corruptDbBackups().length === 0,
+    fix: () => "Inspect then delete ~/.arkaos/**/*.corrupt-*.bak",
+  },
   {
     name: "magic-api-key",
     description: "Magic API key configured (frontend UI/UX — Magic MCP)",

package/installer/hook-lib.js

@@ -23,3 +23,31 @@ export function copyHookLib(srcHooksDir, destHooksDir) {
   } catch {}
   return true;
 }
+
+// F2-6 fast-path assets: the Node shims + the generated gate manifest
+// (engine.cjs travels inside _lib/ via copyHookLib). The list lives HERE,
+// in the single shared deploy function, so index.js and update.js cannot
+// drift the way the v4.3.2 hook-lib regression did. The .sh/.ps1 hooks
+// keep deploying regardless — they are the delegation target and the
+// ARKA_HOOK_FASTPATH=0 kill-switch path. POSIX-only feature: the assets
+// still copy on Windows (harmless), but the adapter never registers them.
+export const HOOK_ASSETS = [
+  "pre-tool-use.cjs",
+  "post-tool-use.cjs",
+  "gate-manifest.json",
+];
+
+export function copyHookAssets(srcHooksDir, destHooksDir) {
+  let copied = 0;
+  for (const name of HOOK_ASSETS) {
+    const srcPath = join(srcHooksDir, name);
+    if (!existsSync(srcPath)) continue;
+    mkdirSync(destHooksDir, { recursive: true });
+    cpSync(srcPath, join(destHooksDir, name));
+    if (name.endsWith(".cjs")) {
+      try { chmodSync(join(destHooksDir, name), 0o755); } catch {}
+    }
+    copied += 1;
+  }
+  return copied;
+}