arkaos 2.22.0 → 2.25.0

package/README.md

@@ -8,7 +8,7 @@
 npx arkaos install
 ```
 
-[![npm](https://img.shields.io/npm/v/arkaos)](https://www.npmjs.com/package/arkaos) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Tests](https://img.shields.io/badge/tests-1993%20passing-brightgreen)]()
+[![npm](https://img.shields.io/npm/v/arkaos)](https://www.npmjs.com/package/arkaos) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Tests](https://img.shields.io/badge/tests-3025%20passing-brightgreen)]()
 
 ---
 
@@ -228,6 +228,84 @@ arkaos scheduler logs         # View logs
 
 ---
 
+## Intelligence Loop (v2.21.0+)
+
+Three-layer system that makes ArkaOS consult its brain before going external, and write every session's learnings back to the vault automatically. The system compounds daily — tomorrow's ArkaOS is smarter than today's.
+
+### Synapse L2.5 — KB Context Injection (v2.21.0)
+
+On every user prompt, ArkaOS runs semantic search against the Obsidian vault and injects the top relevant notes (with wikilinks and excerpts) as context **before the model starts planning**. The agent sees what the vault already knows, naturally — no hard gate, no friction.
+
+- Top 3–5 notes by similarity
+- Jaccard fallback when vector store absent
+- Feature flag `synapse.l25KbContext` default `true`
+- Kill switch `ARKA_BYPASS_L25=1`
+
+### Research Gate — Natural Nudge (v2.21.0)
+
+When an agent tries `Context7`, `WebSearch`, `WebFetch`, or `Firecrawl` without consulting Obsidian first:
+
+- **First attempt** → natural PT-PT nudge listing top 3 vault hits. Allows the call.
+- **Second attempt in same turn** → deny. The nudge wasn't enough.
+
+Feature flag `hooks.kbFirst` default `false` in v2.21.0 — dormant until operator flips. Kill switch `ARKA_BYPASS_KB_FIRST=1` (audited).
+
+### Auto-Documentor + Cataloger + Relator (v2.21.0)
+
+After every approved session, an async worker writes the learnings back to the vault:
+
+1. **Extract** — parses the transcript for sources consulted, decisions made, deliverables produced
+2. **Classify** — cataloger chooses the right taxonomic home (code pattern, persona, client strategy, marketing test, ADR, research finding, framework, or session fallback)
+3. **Write** — creates the note at the correct vault path with frontmatter + tags
+4. **Relate** — relator finds semantically similar existing notes, creates bidirectional `[[wikilinks]]`, updates MOCs
+
+The vault becomes a relational graph that grows with every session.
+
+### LLM Agnostic Auto-Documentor (v2.22.0)
+
+The synthesis LLM call is runtime-agnostic. **Zero model hardcoding.** Whatever runtime you have configured decides the model:
+
+| Provider | Default | Model decided by |
+|---|---|---|
+| `subagent` | ✅ | Active runtime's headless CLI (`claude -p`, `gemini -p …`) |
+| `anthropic-direct` | — | `ANTHROPIC_MODEL` env var; no code default |
+| `stub` | tests | Template fallback |
+
+Fallback chain `subagent → anthropic-direct → stub` never raises. Prompt caching ON by default (5-min TTL `cache_control: ephemeral` on system block).
+
+### Budget Telemetry + `/arka costs` (v2.22.0)
+
+Every LLM call appends to `~/.arkaos/telemetry/llm-cost.jsonl` with tokens, cache hits, and estimated cost. Per [ADR-011](docs/adr/), this is **visibility only — never blocks**.
+
+```bash
+/arka costs           # today (default)
+/arka costs week      # last 7 days
+/arka costs month     # last 30 days
+/arka costs sessions  # top 10 expensive sessions
+```
+
+Soft advisory when a single session exceeds $5 equivalent. No hard caps.
+
+### Flow Marker v2 (v2.21.0)
+
+The constitutional 13-phase flow enforcement (binding in v2.20) got a turn-scoped marker cache, eliminating the cross-turn false positives that triggered on subagent dispatch and short user continuations. ADR-compliant: cache accelerates ALLOW decisions only; the transcript remains authoritative for DENY.
+
+### Polish & Consolidation (v2.22.1)
+
+- `core/shared/safe_session_id.py` — single source of truth for the path-traversal / injection allowlist, deduped across 6 modules (100% coverage, 33 security-contract tests)
+- Gemini CLI headless live (`gemini -p "…" --output-format json`)
+- `_MAX_FALLBACK_NOTES = 2000` bound on Synapse L2.5 degraded-mode scan
+- Auto-documentor coverage lifted 93% → 98%
+- Template synthesiser now mirrors LLM prompt structure (Key Facts → Decisions → Sources)
+
+### ADRs
+
+- [`2026-04-20-flow-marker-v2.md`](docs/adr/2026-04-20-flow-marker-v2.md) — turn-scoped cache amendment
+- [`2026-04-20-kb-first-intelligence.md`](docs/adr/2026-04-20-kb-first-intelligence.md) — Synapse L2.5 + gate + auto-documentor
+- [`2026-04-20-llm-agnostic.md`](docs/adr/2026-04-20-llm-agnostic.md) — runtime-agnostic LLM wiring
+
+---
+
 ## Ecosystem Management
 
 ArkaOS manages client projects as **ecosystems** — groups of related projects with dedicated squads.
@@ -370,21 +448,39 @@ Full documentation is available on the **[GitHub Wiki](https://github.com/andrea
 
 ## CLI Reference
 
+**Installer (terminal):**
+
 ```bash
-npx arkaos install       # Fresh install (auto-detects runtime)
-npx arkaos update        # Update to latest version
-npx arkaos migrate       # Migrate from v1
-npx arkaos doctor        # Health check
-npx arkaos dashboard     # Start monitoring dashboard
-npx arkaos keys          # Manage API keys
-npx arkaos uninstall     # Remove ArkaOS
+npx arkaos install             # Fresh install (auto-detects runtime)
+npx arkaos@latest update       # Update core + hooks to latest version
+npx arkaos migrate             # Migrate from v1
+npx arkaos doctor              # Health check
+npx arkaos dashboard           # Start monitoring dashboard
+npx arkaos keys                # Manage API keys
+npx arkaos uninstall           # Remove ArkaOS
 ```
 
+**In-session commands (inside Claude Code / Codex / Gemini / Cursor):**
+
+```
+/arka update                   # Sync all project configs after core update
+/arka status                   # System health + LLM costs (24h)
+/arka costs [today|week|month|all|sessions]  # LLM cost visibility
+/arka index                    # (Re)index Obsidian vault into vector store
+/arka search <query>           # Semantic search in knowledge base
+/arka standup                  # Daily standup (projects, blockers, updates)
+/arka onboard <path>           # Onboard an existing project
+/arka conclave                 # Personal AI advisory board
+/do <description>              # Universal routing — natural language to department
+```
+
+Department commands: `/dev`, `/mkt`, `/brand`, `/fin`, `/strat`, `/ecom`, `/kb`, `/ops`, `/pm`, `/saas`, `/landing`, `/content`, `/community`, `/sales`, `/lead`, `/org`.
+
 ---
 
 ## Contributing
 
-See [CONTRIBUTING.md](.github/CONTRIBUTING.md). PRs welcome — all changes require passing the full test suite (1,993 tests) and Quality Gate review.
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md). PRs welcome — all changes require passing the full test suite (3,025 tests) and Quality Gate review.
 
 ## License
 

package/VERSION

@@ -1 +1 @@
-2.22.0
+2.25.0

package/arka/SKILL.md

@@ -122,6 +122,7 @@ violation (squad-routing, arka-supremacy, spec-driven, mandatory-qa).
 | `/arka search <query>` | Semantic search in knowledge base |
 | `/arka keys` | Manage API keys (OpenAI, Google, fal.ai) |
 | `/arka personas` | Manage AI personas (create, clone to agent) |
+| `/arka resume <PR_URL>` | Re-enter the Claude Code session that produced a PR (GitHub / GitLab / Bitbucket). Wraps the native `/resume` from Claude Code 2.1.122+. Useful with `arka-spec` and `arka-release` archaeology. |
 | `/do <description>` | Universal routing — natural language to department command |
 
 ## Universal Orchestrator (/do)

package/arka/skills/comfyui/SKILL.md

@@ -19,8 +19,8 @@ Full-spectrum AI media production platform. From ComfyUI node engineering to Hol
 
 | Project | Type | Stack | Path |
 |---------|------|-------|------|
-| **purz-comfyui-workflows** | Workflow Collection | ComfyUI JSON (7 workflows, 110+ nodes) | `/Users/andreagroferreira/AIProjects/purz-comfyui-workflows` |
-| **lora_tester** | CLI Tool + Gallery | Python 3.8+ (stdlib) + Vanilla HTML/JS | `/Users/andreagroferreira/AIProjects/lora_tester` |
+| **purz-comfyui-workflows** | Workflow Collection | ComfyUI JSON (7 workflows, 110+ nodes) | `${ARKA_OS_REPOS}/purz-comfyui-workflows` |
+| **lora_tester** | CLI Tool + Gallery | Python 3.8+ (stdlib) + Vanilla HTML/JS | `${ARKA_OS_REPOS}/lora_tester` |
 
 ## Squads
 

package/arka/skills/comfyui/references/workflows.md

@@ -7,8 +7,8 @@ Referenced from SKILL.md. Read only when needed.
 For EVERY `/comfyui` request, follow this workflow:
 
 ### Phase 1 — Context Loading
-1. Read ComfyUI skill reference: `/Users/andreagroferreira/AIProjects/lora_tester/.claude/skills/comfy_local/skill.md`
-2. Check available workflows: `ls /Users/andreagroferreira/AIProjects/purz-comfyui-workflows/`
+1. Read ComfyUI skill reference: `${ARKA_OS_REPOS}/lora_tester/.claude/skills/comfy_local/skill.md`
+2. Check available workflows: `ls ${ARKA_OS_REPOS}/purz-comfyui-workflows/`
 3. Check ComfyUI server: `curl -s http://localhost:8188/system_stats 2>/dev/null`
 4. Load project context for affected repos
 5. Identify which squad(s) the request needs
@@ -320,8 +320,8 @@ while pending:
 curl -s http://localhost:8188/system_stats 2>/dev/null
 
 # Project status
-cd /Users/andreagroferreira/AIProjects/purz-comfyui-workflows && git log --oneline -5
-cd /Users/andreagroferreira/AIProjects/lora_tester && git log --oneline -5
+cd ${ARKA_OS_REPOS}/purz-comfyui-workflows && git log --oneline -5
+cd ${ARKA_OS_REPOS}/lora_tester && git log --oneline -5
 ```
 
 Present as:
@@ -403,10 +403,10 @@ When Iris (Node Researcher) investigates custom nodes:
 
 ## Obsidian Output
 
-All documentation: `/Users/andreagroferreira/Documents/Personal/Projects/WizardingCode Internal/ComfyUI/`
+All documentation: `${VAULT_PATH}/Projects/ComfyUI/`
 
 ```
-WizardingCode Internal/ComfyUI/
+Projects/ComfyUI/
 ├── Home.md                    <- Ecosystem overview
 ├── Workflows/
 │   ├── LTX-2 T2V.md

package/arka/skills/costs/SKILL.md

@@ -55,6 +55,17 @@ Source:
 One JSONL line per LLM call, written by every provider adapter.
 Malformed lines are skipped and counted, never raised.
 
+## Cost-tuning levers
+
+Outside this skill's scope but worth surfacing alongside the summary:
+
+| Lever | Where | Effect |
+| --- | --- | --- |
+| `ARKAOS_LLM_PROVIDER` | env | Switch between Anthropic, OpenAI, Gemini adapters per the multi-LLM router. |
+| `ANTHROPIC_BEDROCK_SERVICE_TIER` | env (Claude Code 2.1.122+) | `default` / `flex` / `priority`. Only relevant when routing through AWS Bedrock — `flex` cuts cost ~50 % on non-urgent workloads at the price of higher tail latency. |
+| Agent `model:` field | `departments/*/agents/*.yaml` | Per-agent override per the model-routing matrix in CLAUDE.md. Mechanical roles default to haiku, C-suite to opus. |
+| Quality Gate model | constitution rule (NON-NEGOTIABLE) | Marta / Eduardo / Francisca always run on opus regardless of the cost ceiling. |
+
 ## Non-negotiables
 
 1. Read-only. This skill never edits state.

package/config/cognition/prompts/dreaming.md

@@ -8,7 +8,7 @@ You are ArkaOS performing your nightly Dreaming session. Your job is to review e
 - Read any file from any project
 - Read git logs and diffs
 - Search the web (WebSearch, Firecrawl)
-- Write to Obsidian vault at ~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/
+- Write to Obsidian vault at ${VAULT_PATH}/Projects/ArkaOS/
 - Write to ~/.arkaos/ (captures, insights, logs, knowledge)
 - Use browser for research
 - Read online documentation
@@ -81,7 +81,7 @@ from core.cognition.memory.writer import DualWriter
 
 writer = DualWriter(
     obsidian_base=os.path.expanduser(
-        "~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Knowledge Base"
+        "${VAULT_PATH}/Projects/ArkaOS/Knowledge Base"
     ),
     vector_db_path=os.path.expanduser("~/.arkaos/knowledge.db"),
 )
@@ -113,7 +113,7 @@ Use `DualWriter.write()` for each KnowledgeEntry. This automatically writes to b
 ## Phase 6: Report + Evolution Metrics
 
 Write daily report to Obsidian:
-`~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Dreaming/YYYY-MM-DD.md`
+`${VAULT_PATH}/Projects/ArkaOS/Dreaming/YYYY-MM-DD.md`
 
 Format:
 ```markdown

package/config/cognition/prompts/research.md

@@ -8,7 +8,7 @@ You are ArkaOS performing your daily Research session. Your job is to stay curre
 - Read any file from any project
 - Read git logs
 - Search the web extensively (WebSearch, Firecrawl)
-- Write to Obsidian vault at ~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/
+- Write to Obsidian vault at ${VAULT_PATH}/Projects/ArkaOS/
 - Write to ~/.arkaos/ (insights, logs, knowledge, profiles)
 - Use browser for deep research
 - Read online documentation, blogs, changelogs, GitHub releases
@@ -94,7 +94,7 @@ from core.cognition.memory.writer import DualWriter
 
 writer = DualWriter(
     obsidian_base=os.path.expanduser(
-        "~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Knowledge Base"
+        "${VAULT_PATH}/Projects/ArkaOS/Knowledge Base"
     ),
     vector_db_path=os.path.expanduser("~/.arkaos/knowledge.db"),
 )
@@ -114,7 +114,7 @@ writer.write(entry)
 ## Phase 5: Cross-Reference with Dreaming
 
 1. Read tonight's Dreaming report (if it exists):
-   `~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Dreaming/YYYY-MM-DD.md`
+   `${VAULT_PATH}/Projects/ArkaOS/Dreaming/YYYY-MM-DD.md`
 
 2. Read pending insights from `~/.arkaos/insights.db`:
 ```python
@@ -145,7 +145,7 @@ store.save(insight)
 ## Phase 6: Intelligence Briefing
 
 Write daily briefing to Obsidian:
-`~/Documents/Personal/Projects/WizardingCode Internal/ArkaOS/Research/YYYY-MM-DD.md`
+`${VAULT_PATH}/Projects/ArkaOS/Research/YYYY-MM-DD.md`
 
 Format:
 ```markdown

package/config/hooks/user-prompt-submit.sh

@@ -368,7 +368,12 @@ else
 fi
 
 # ─── Metrics ─────────────────────────────────────────────────────────────
+# Count @-mentions in the prompt for at_mention_frequency telemetry. Mirrors
+# the claude_code.at_mention OpenTelemetry event introduced in Claude Code
+# 2.1.122, but works on any version because we count from the same input
+# the hook already receives.
+at_mentions=$(printf '%s' "$user_input" | grep -oE '(^|[[:space:]])@[A-Za-z0-9_./-]+' | wc -l | tr -d ' ')
 elapsed=$(_hook_ms)
 if [ "$elapsed" -gt 0 ] 2>/dev/null; then
-  echo "{\"hook\":\"user-prompt-submit-v2\",\"ms\":$elapsed}" >> "$CACHE_DIR/hook-metrics.jsonl" 2>/dev/null
+  echo "{\"hook\":\"user-prompt-submit-v2\",\"ms\":$elapsed,\"at_mentions\":${at_mentions:-0}}" >> "$CACHE_DIR/hook-metrics.jsonl" 2>/dev/null
 fi

package/core/cognition/auto_documentor.py

@@ -21,16 +21,28 @@ from __future__ import annotations
 
 import json
 import re
+from contextlib import contextmanager
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Iterable
 
 from core.obsidian import cataloger as _cataloger
 from core.obsidian import relator as _relator
 from core.obsidian.writer import ObsidianWriter
+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
 
-SAFE_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
+
+# Re-export for backward compatibility with any external importers.
+SAFE_SESSION_ID_RE = _safe_session_id_module.SAFE_SESSION_ID_RE
+
+AUTO_DOC_TELEMETRY_PATH = Path.home() / ".arkaos" / "telemetry" / "auto_doc.jsonl"
 
 _URL_RE = re.compile(r"https?://[^\s\)\]\"']+")
 _FILE_PATH_RE = re.compile(r"(?:^|[\s`'])(/[A-Za-z0-9_./\-]+\.[A-Za-z0-9]+)")
@@ -58,8 +70,8 @@ _SYSTEM_PROMPT = (
     "(150-300 words) summarising the session. Structure: short intro, "
     "then markdown sections for Key Facts, Decisions, and Sources. "
     "Preserve every URL and file path verbatim. Use Obsidian wikilinks "
-    "([[Topic]]) for reusable concepts. No preamble, no sign-off, no "
-    "meta commentary about the model or prompt. Output only markdown."
+    "([[Topic]]) for reusable concepts. Do not include preamble, sign-off, "
+    "or meta commentary about the model or prompt. Output only markdown."
 )
 
 
@@ -329,18 +341,52 @@ def _build_synthesis_prompt(learning: Learning) -> str:
     return "\n".join(lines)
 
 
+def _extract_key_facts(learning: Learning, limit: int = 5) -> list[str]:
+    """Pull 3-5 bullet candidates from the learning content.
+
+    Used by the template fallback so both the LLM and template paths
+    produce a ``## Key Facts`` section in the same order as
+    ``_SYSTEM_PROMPT`` requires.
+    """
+    text = (learning.content or "").strip()
+    if not text:
+        return []
+    paragraphs = [p.strip() for p in re.split(r"\n\s*\n", text) if p.strip()]
+    bullets: list[str] = []
+    for para in paragraphs:
+        for raw in para.splitlines():
+            line = raw.strip().lstrip("-*• ").strip()
+            # Skip markdown section headings; they aren't facts.
+            if not line or line.startswith("#"):
+                continue
+            if line.startswith(">") or line.startswith("`"):
+                continue
+            if len(line) < 8:
+                continue
+            bullets.append(line[:240])
+            if len(bullets) >= limit:
+                return bullets
+        if len(bullets) >= limit:
+            break
+    return bullets
+
+
 def _template_synthesize(learning: Learning) -> str:
-    parts = [f"# {learning.topic}", ""]
+    # Section order mirrors _SYSTEM_PROMPT: Key Facts → Decisions →
+    # Sources. Keeping both synthesis paths aligned means downstream
+    # consumers (MOC generation, relator) never branch on provider.
+    parts: list[str] = [f"# {learning.topic}", ""]
     parts.append(f"> {_AUTO_DOC_SUFFIX}.")
     parts.append("")
     if learning.content.strip():
         parts.append(learning.content.strip())
         parts.append("")
-    if learning.sources:
-        parts.append("## Sources")
+    key_facts = _extract_key_facts(learning)
+    if key_facts:
+        parts.append("## Key Facts")
         parts.append("")
-        for src in learning.sources[:20]:
-            parts.append(f"- {src}")
+        for fact in key_facts:
+            parts.append(f"- {fact}")
         parts.append("")
     if learning.decisions:
         parts.append("## Decisions")
@@ -348,6 +394,12 @@ def _template_synthesize(learning: Learning) -> str:
         for dec in learning.decisions[:10]:
             parts.append(f"- {dec}")
         parts.append("")
+    if learning.sources:
+        parts.append("## Sources")
+        parts.append("")
+        for src in learning.sources[:20]:
+            parts.append(f"- {src}")
+        parts.append("")
     return "\n".join(parts).rstrip() + "\n"
 
 
@@ -391,13 +443,78 @@ def _document_one(
     meta.setdefault("auto_documented", True)
     try:
         plan = _cataloger.plan(body, meta)
-    except ValueError:
+    except ValueError as exc:
+        _log_auto_doc_event(
+            session_id=session_id,
+            event="classification-failed",
+            topic=learning.topic,
+            reason=str(exc),
+        )
+        return None
+    if plan is None:
+        _log_auto_doc_event(
+            session_id=session_id,
+            event="succeeded-empty",
+            topic=learning.topic,
+            reason="cataloger returned no plan",
+        )
         return None
     note_path = _cataloger.execute(plan, body, writer)
     _relate_note(note_path, body, vault_path, plan)
+    _log_auto_doc_event(
+        session_id=session_id,
+        event="succeeded-wrote-note",
+        topic=learning.topic,
+        reason=str(note_path),
+    )
     return note_path
 
 
+@contextmanager
+def _locked_append(path: Path):
+    """Append to ``path`` under an exclusive advisory lock (POSIX flock).
+
+    Mirrors the pattern in ``core/workflow/flow_enforcer._locked_append``
+    — see that module for the platform-fallback rationale.
+    """
+    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 _log_auto_doc_event(
+    *,
+    session_id: str,
+    event: str,
+    topic: str,
+    reason: str,
+) -> None:
+    """Append a structured auto-doc telemetry entry, degrade silently."""
+    entry = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "session_id": session_id,
+        "event": event,
+        "topic": topic[:120],
+        "reason": reason[:240],
+    }
+    try:
+        with _locked_append(AUTO_DOC_TELEMETRY_PATH) as fh:
+            fh.write(json.dumps(entry) + "\n")
+    except OSError:
+        # Telemetry failures must never break the doc job.
+        return
+
+
 def _relate_note(note_path: Path, body: str, vault_path: Path, plan) -> None:
     try:
         related = _relator.find_related(
@@ -428,6 +545,4 @@ def _append_related_block(note_path: Path, related) -> None:
 
 
 def _safe_session_id(session_id: str) -> bool:
-    if not isinstance(session_id, str) or not session_id:
-        return False
-    return bool(SAFE_SESSION_ID_RE.match(session_id))
+    return _safe_session_id_module.safe_session_id(session_id) is not None

package/core/cognition/capture/collector.py

@@ -7,13 +7,20 @@ from datetime import datetime, timezone
 
 from core.cognition.capture.store import CaptureStore
 from core.cognition.memory.schemas import RawCapture
+from core.runtime.path_resolver import ProfileMissingError, project_root_regex
+
+_FALLBACK_REGEX = re.compile(
+    r"((?:/Users|/home)/\S+/(?:Herd|Work|AIProjects|code|repos))[/\\]([^\s/\\]+)"
+)
 
 
 def _detect_project(digest: str) -> tuple[str, str]:
     """Try to detect project name and path from digest content."""
-    path_match = re.search(
-        r"(/Users/\S+/(?:Herd|Work|AIProjects)/([^\s/]+))", digest
-    )
+    try:
+        regex = project_root_regex()
+    except ProfileMissingError:
+        regex = _FALLBACK_REGEX
+    path_match = regex.search(digest)
     if path_match:
         return path_match.group(2).rstrip("/"), path_match.group(1).rstrip("/")
     return "unknown", os.getcwd()

package/core/cognition/scheduler/daemon.py

@@ -144,6 +144,11 @@ class ArkaScheduler:
         claude_bin = self._resolve_claude_binary()
         prompt_path = os.path.expanduser(schedule.prompt_file)
         prompt_content = Path(prompt_path).read_text(encoding="utf-8")
+        try:
+            from core.runtime.path_resolver import resolve
+            prompt_content = resolve(prompt_content)
+        except Exception:
+            pass  # fall back to raw template if profile unavailable
         return [claude_bin, "-p", prompt_content, "--dangerously-skip-permissions"]
 
     # ------------------------------------------------------------------

package/core/jobs/auto_doc_worker.py

@@ -28,7 +28,6 @@ from __future__ import annotations
 import argparse
 import json
 import os
-import re
 import sys
 import time
 import uuid
@@ -36,9 +35,12 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
+from core.shared import safe_session_id as _safe_session_id_module
+
 
 MAX_ATTEMPTS = 3
-SAFE_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
+# Re-export for backward compatibility with any external importers.
+SAFE_SESSION_ID_RE = _safe_session_id_module.SAFE_SESSION_ID_RE
 _QUEUE_SUBDIRS = ("pending", "processing", "completed", "failed")
 
 
@@ -77,7 +79,7 @@ def enqueue_job(
     """Write a pending job file. Returns the job id."""
     root = queue_root or _queue_root()
     _ensure_queue(root)
-    safe = session_id if SAFE_SESSION_ID_RE.match(session_id or "") else "unknown"
+    safe = _safe_session_id_module.safe_session_id(session_id or "") or "unknown"
     job_id = f"{int(time.time())}-{uuid.uuid4().hex[:12]}"
     payload = {
         "job_id": job_id,

package/core/obsidian/writer.py

@@ -130,14 +130,15 @@ class ObsidianWriter:
 
         if config_path.exists():
             try:
+                from core.runtime.path_resolver import resolve
                 config = json.loads(config_path.read_text())
-                vault = config.get("vault_path", "")
-                if vault and Path(vault).exists():
+                vault = resolve(config.get("vault_path", ""))
+                if vault and not vault.startswith("${") and Path(vault).exists():
                     return Path(vault)
-            except (json.JSONDecodeError, OSError):
+            except (json.JSONDecodeError, OSError, Exception):
                 pass
 
-        # 3. Environment variable
+        # 3. Environment variable (legacy fallback only — path_resolver handles ARKAOS_VAULT_PATH)
         env_vault = os.environ.get("ARKAOS_VAULT", "")
         if env_vault and Path(env_vault).exists():
             return Path(env_vault)