synlynk 0.27.5__py3-none-any.whl

synlynk/__init__.py

@@ -0,0 +1,3672 @@
+#!/usr/bin/env python3
+import sys
+import os
+import re
+from typing import Optional, Tuple, Union
+import sqlite3 as _sqlite3
+import importlib as _importlib
+
+from synlynk._constants import (
+    HARNESS_CAPABILITY_BASELINES,
+    HARNESS_TIMEOUT_PATTERNS,
+    QUOTA_PATTERNS,
+    VERSION,
+    _INSTALL_SCRIPT_URL,
+    NEXT_GEN_FLEET,
+    EXTENDED_FLEET,
+)
+
+__version__ = VERSION
+
+_IS_TESTING = "pytest" in sys.modules or any("pytest" in str(arg) for arg in sys.argv)
+_FAST_CLI = not _IS_TESTING and (
+    os.environ.get("SYNLYNK_CLI_ENTRYPOINT") == "1" or (
+        os.path.basename(sys.argv[0]) in {"synlynk", "synlynk.py"}
+        or (os.path.basename(sys.argv[0]) == "__main__.py" and "synlynk" in str(sys.argv[0]))
+    ) or any(flag in sys.argv[1:] for flag in ("-h", "--help", "--version"))
+)
+
+
+def _vizor_daemon_process() -> bool:
+    """True only for the machine-scoped Vizor daemon or its ensure tick.
+
+    Those processes start with cwd set to the daemon home, which is not a git
+    checkout. Skipping product-root resolution here must not weaken gh:#1831
+    for any other import.
+    """
+    if os.environ.get("SYNLYNK_VIZOR_DAEMON") == "1":
+        return True
+    # python -m synlynk.vizor_daemon sets argv[0] to the module file, so the
+    # basename covers that invocation. A later argv entry that only names the
+    # module is not this process (gh:#1831).
+    names = {"vizor_daemon.py", "vizor_ensure.py"}
+    argv0 = os.path.basename(sys.argv[0]) if sys.argv else ""
+    return argv0 in names
+
+if not _FAST_CLI:
+    import argparse
+    from pathlib import Path
+    from synlynk.db import _try_sync_arc_by_version
+
+# The compatibility surface below historically relied on these names being
+# available from the package module.  Keep that behavior for imports/tests,
+# but do not pay for the modules on the subprocess CLI fast path.
+if not _FAST_CLI:
+    import json
+    import shutil
+    import subprocess
+    import tempfile
+    import threading
+    import time
+    import urllib.request
+
+
+_LEGACY_MODULES = (
+    "upgrade", "sentinel", "probe", "fencing", "dispatch", "quota", "costs",
+    "capability_roles", "taxonomy", "doctor", "team", "heal", "support_engineer",
+    "backlog", "backlog_extractor", "charter_injection", "context", "jobs",
+    "story_provisioning", "daemon", "instructions", "scan", "hud", "platform_status",
+    "logs", "wizard", "launch", "circuit_breaker", "capability_probe", "wal_ledger",
+    "worktree_lease", "governs_compressed",
+)
+
+
+def _load_legacy_imports():
+    """Load the historical package-level exports on demand.
+
+    The package has long re-exported nearly every CLI implementation symbol.
+    Keep that API, but avoid importing the entire command graph while argparse
+    is only constructing or displaying the parser.
+    """
+    # Restore module globals used by the older package-level helpers when a
+    # non-observability command leaves the fast CLI path.
+    for module_name in ("json", "shutil", "subprocess", "tempfile", "threading", "time"):
+        module = _importlib.import_module(module_name)
+        globals()[module_name] = module
+    globals()["urllib"] = _importlib.import_module("urllib")
+    _importlib.import_module("urllib.request")
+    launch_templates = _importlib.import_module("synlynk.launch_templates")
+    db_schema = _importlib.import_module("synlynk.db_schema")
+    globals()["LAUNCH_TASK_TEMPLATES"] = launch_templates.LAUNCH_TASK_TEMPLATES
+    globals()["_DB_SCHEMA"] = db_schema._DB_SCHEMA
+    globals()["_DB_SCORES_VIEW"] = db_schema._DB_SCORES_VIEW
+
+    for module_name in _LEGACY_MODULES:
+        module = _importlib.import_module(f"synlynk.{module_name}")
+        globals().update({
+            name: value
+            for name, value in vars(module).items()
+            if not name.startswith("__") and name not in globals()
+        })
+    # Importing a submodule also installs it as a package attribute. Restore
+    # the historical function export where the names intentionally collide.
+    globals()["upgrade"] = _importlib.import_module("synlynk.upgrade").upgrade
+    globals()["cmd_ecosystem_status"] = _importlib.import_module("synlynk.status").cmd_status
+    globals()["cmd_viz"] = _importlib.import_module("synlynk.viz").cmd_viz
+    globals()["cmd_schedule"] = _importlib.import_module("synlynk.scheduler").cmd_schedule
+    globals()["main"], globals()["cmd_watch"] = (
+        _importlib.import_module("synlynk.cli").main,
+        _importlib.import_module("synlynk.cli").cmd_watch,
+    )
+    db = _importlib.import_module("synlynk.db")
+    globals().update({
+        name: value
+        for name, value in vars(db).items()
+        if not name.startswith("__") and name not in globals()
+    })
+
+
+def main(argv=None):
+    """Lazy compatibility entry point for installed console scripts."""
+    cli_tokens = list(argv) if argv is not None else sys.argv[1:]
+    if _FAST_CLI and cli_tokens and cli_tokens[0] in {"jobs", "status"}:
+        from synlynk._fast_cli import run_fast_command
+
+        if run_fast_command(cli_tokens) is True:
+            return None
+    return _importlib.import_module("synlynk.cli").main(argv)
+
+
+def __getattr__(name):
+    """Lazily preserve compatibility exports removed from the fast path."""
+    if name in {"LAUNCH_TASK_TEMPLATES", "_DB_SCHEMA", "_DB_SCORES_VIEW"}:
+        module_name = "synlynk.launch_templates" if name == "LAUNCH_TASK_TEMPLATES" else "synlynk.db_schema"
+        value = getattr(_importlib.import_module(module_name), name)
+        globals()[name] = value
+        return value
+    raise AttributeError(name)
+
+CYCLE_COLORS = {
+    "dream":   "#a78bfa",
+    "design":  "#60a5fa",
+    "plan":    "#34d399",
+    "build":   "#fbbf24",
+    "ship":    "#f87171",
+    "sustain": "#94a3b8",
+}
+
+CYCLE_DESCRIPTIONS = {
+    "dream":   "What's worth building\nIdeate, assess, identify opportunities\n",
+    "design":  "Brainstorm -> spec -> UX\nTurn ideas into a concrete brief\n",
+    "plan":    "Implementation plan, story breakdown, agent wave schedule\n",
+    "build":   "Dispatch agents, run jobs, iterate on diffs\n",
+    "ship":    "Cut release, changelog, publish\n",
+    "sustain": "Monitor, patch, community, docs, support\n",
+}
+
+CYCLE_DEFAULT_AGENTS = {
+    "dream":   ["claude"],
+    "design":  ["claude"],
+    "plan":    ["claude"],
+    "build":   ["agy", "codex", "grok"],
+    "ship":    ["claude"],
+    "sustain": ["claude", "agy", "codex", "grok"],
+}
+
+CORE_TEMPLATE_IDS = {"arch-review", "product-assessment", "lifecycle-setup"}
+
+# Capability scores within this gap are considered ties → break on cost (#140).
+_CAPABILITY_COST_TIE_GAP = 0.15
+
+def _launch_visible_template_ids() -> set:
+    tier1_primary_ids = {
+        entry["command"]
+        for entry in entries_for_tier(1)
+        if entry["prominence"] == "primary"
+    }
+    return CORE_TEMPLATE_IDS | tier1_primary_ids
+
+
+def _launch_visible_templates() -> list:
+    from synlynk.launch_templates import LAUNCH_TASK_TEMPLATES
+
+    visible_ids = _launch_visible_template_ids()
+    return [template for template in LAUNCH_TASK_TEMPLATES if template["id"] in visible_ids]
+
+
+def _template_matches(template: dict, scan: dict) -> bool:
+    """Returns True if the template's trigger condition is met by scan."""
+    condition = template.get("trigger_condition")
+    if condition is None:
+        return True
+    try:
+        return bool(condition(scan))
+    except Exception:
+        return False
+
+
+def _select_launch_tasks(scan: dict) -> list:
+    """Returns ordered list of 3-5 matching templates (core first, bonus sorted by specificity)."""
+    eligible = [t for t in _launch_visible_templates() if _template_matches(t, scan)]
+    core = [t for t in eligible if t["id"] in CORE_TEMPLATE_IDS]
+    bonus = [t for t in eligible if t["id"] not in CORE_TEMPLATE_IDS]
+    return (core + bonus)[:5]
+
+
+def _render_prompt(template: dict, scan: dict) -> str:
+    """Substitutes {variables} in prompt_template from scan data. Missing vars become ''."""
+    import datetime as _datetime
+    import re as _re
+
+    repos = scan.get("repos", [])
+    primary = repos[0] if repos else {}
+    tests = scan.get("tests") or {}
+    source = scan.get("source") or []
+    complexity = scan.get("complexity") or {}
+    git = scan.get("git") or {}
+    gap_functions = tests.get("gap_functions", [])
+    if gap_functions:
+        gap_functions_text = ", ".join(
+            g.get("name", str(g)) if isinstance(g, dict) else str(g)
+            for g in gap_functions
+        )
+    else:
+        gap_functions_text = "none"
+    typed_pct = (
+        int(sum(f.get("typed_pct", 0) for f in source) / max(len(source), 1))
+        if source
+        else int(scan.get("typed_pct", 0) or 0)
+    )
+    largest_file = max(source, key=lambda f: f.get("lines", 0), default={})
+    largest_fn = {}
+    for file_info in source:
+        for fn in file_info.get("largest_fns", []):
+            if fn.get("lines", 0) > largest_fn.get("lines", 0):
+                largest_fn = {
+                    "name": fn.get("name", ""),
+                    "lines": fn.get("lines", 0),
+                    "file": file_info.get("path", ""),
+                }
+    hotspots = complexity.get("hotspots", [])
+    top_hotspot = max(hotspots, key=lambda h: h.get("lines", 0), default={})
+    churn = git.get("churn", [])
+    hot_file = churn[0].get("path", "") if churn else ""
+    commit_count = churn[0].get("commits", 0) if churn else 0
+    variables = {
+        "workspace": scan.get("workspace_name", ""),
+        "stack": ", ".join(primary.get("stack_labels", [])) or "unknown",
+        "repo_name": primary.get("name", ""),
+        "topology": scan.get("topology", "single"),
+        "test_count": str(scan.get("test_ratio", 0)),
+        "gap_functions": gap_functions_text,
+        "typed_pct": str(typed_pct),
+        "largest_file": largest_file.get("path", ""),
+        "largest_file_lines": str(largest_file.get("lines", 0)),
+        "largest_file_fns": str(largest_file.get("functions", 0)),
+        "largest_fn": largest_fn.get("name", ""),
+        "largest_fn_lines": str(largest_fn.get("lines", 0)),
+        "top_hotspot": top_hotspot.get("fn") or os.path.basename(top_hotspot.get("path", "")),
+        "top_hotspot_lines": str(top_hotspot.get("lines", 0)),
+        "hot_file": hot_file,
+        "commit_count": str(commit_count),
+        "date": _datetime.date.today().isoformat(),
+        "agent": template.get("agent", "claude"),
+    }
+    text = template.get("prompt_template", "")
+
+    def _replace(match):
+        key = match.group(1)
+        return variables.get(key, "")
+
+    return _re.sub(r"\{(\w+)\}", _replace, text)
+
+
+TASK_STATUSES = {
+    "[ ]": "active",
+    "[x]": "done",
+    "[-]": "deferred",
+    "[~]": "superseded",
+    "[>]": "absorbed",
+}
+
+
+def _project_root() -> str:
+    """Return the shared repo root for the current git worktree.
+
+    Raises RuntimeError if git-common-dir resolution fails, unless
+    SYNLYNK_ALLOW_CWD_FALLBACK=1 is set (see gh:#1831 — a silent CWD
+    fallback here previously minted duplicate per-directory legacy
+    state.db shards for the same project).
+    """
+    import subprocess
+
+    try:
+        common = subprocess.check_output(
+            ["git", "rev-parse", "--path-format=absolute", "--git-common-dir"],
+            stderr=subprocess.DEVNULL,
+        ).decode().strip()
+        if common:
+            return os.path.abspath(os.path.join(common, ".."))
+    except Exception as exc:
+        if os.environ.get("SYNLYNK_ALLOW_CWD_FALLBACK") == "1":
+            return os.getcwd()
+        raise RuntimeError(
+            "could not resolve git-common-dir; refusing to silently fall back "
+            "to the current working directory (this previously minted stray "
+            "per-directory state shards — see gh:#1831). Set "
+            "SYNLYNK_ALLOW_CWD_FALLBACK=1 to override."
+        ) from exc
+    return os.getcwd()
+
+
+def _working_tree_root() -> str:
+    """Return the root of the current checkout, not its shared Git directory."""
+    import subprocess
+
+    try:
+        root = subprocess.check_output(
+            ["git", "rev-parse", "--show-toplevel"],
+            stderr=subprocess.DEVNULL,
+        ).decode().strip()
+        if root:
+            return os.path.abspath(root)
+        raise ValueError("git returned an empty worktree root")
+    except Exception as exc:
+        if os.environ.get("SYNLYNK_ALLOW_CWD_FALLBACK") == "1":
+            return os.getcwd()
+        raise RuntimeError(
+            "could not resolve git worktree root; refusing to write generated "
+            "project docs relative to an unknown checkout"
+        ) from exc
+
+
+def _get_project_root() -> str:
+    """Backwards-compatible alias for callers that expect a root helper."""
+    return _project_root()
+
+
+def _resolve_db_path() -> str:
+    """Resolve the product graph, migrating the legacy path once if needed."""
+    if os.environ.get("SYNLYNK_STATE_DB_PATH"):
+        return os.environ["SYNLYNK_STATE_DB_PATH"]
+
+    from synlynk.product_store import identity_slug_from_config, migrate_state_db_if_needed, state_db_path
+    from synlynk.state_registry import canonical_path
+
+    root = _project_root()
+    slug = identity_slug_from_config(root)
+    try:
+        path = canonical_path(
+            slug,
+            state_db_path(slug),
+            allow_unregistered_existing=os.environ.get("SYNLYNK_ALLOW_REGISTRY_RECOVERY") == "1",
+        )
+    except Exception as exc:
+        if "no canonical registry entry" in str(exc):
+            if not os.path.exists(os.path.join(root, ".synlynk", "config.json")):
+                return str(state_db_path(slug))
+            raise type(exc)(
+                f"{exc}; run SYNLYNK_ALLOW_REGISTRY_RECOVERY=1 synlynk state register "
+                f"--slug {slug} --path {state_db_path(slug)}"
+            ) from exc
+        raise
+    if not _IS_TESTING:
+        try:
+            migrate_state_db_if_needed(root)
+        except (PermissionError, OSError):
+            pass
+    return str(path)
+
+
+def _is_git_worktree() -> bool:
+    """Return whether the current directory is a linked git worktree."""
+    import subprocess
+
+    try:
+        git_dir_output = subprocess.check_output(
+            ["git", "rev-parse", "--path-format=absolute", "--git-dir"],
+            stderr=subprocess.DEVNULL,
+        )
+        common_dir_output = subprocess.check_output(
+            ["git", "rev-parse", "--path-format=absolute", "--git-common-dir"],
+            stderr=subprocess.DEVNULL,
+        )
+        git_dir = git_dir_output.decode() if isinstance(git_dir_output, bytes) else str(git_dir_output)
+        common_dir = common_dir_output.decode() if isinstance(common_dir_output, bytes) else str(common_dir_output)
+        git_dir = git_dir.strip()
+        common_dir = common_dir.strip()
+        return os.path.realpath(git_dir) != os.path.realpath(common_dir)
+    except (OSError, subprocess.CalledProcessError):
+        return False
+
+
+# Resolve once at import time so ordinary test doubles for subprocess calls do
+# not accidentally change DB-path safety decisions mid-test.
+# The linked-worktree guard only protects pytest from accidentally touching the
+# shared product ledger.  The CLI fast path has no pytest state to isolate and
+# must not pay for two git subprocesses before a read-only command starts.
+_INITIAL_GIT_WORKTREE = False if (_FAST_CLI or _vizor_daemon_process()) else _is_git_worktree()
+
+
+def _test_isolation_db_path() -> str:
+    """Return a process-local DB path for pytest worktree execution."""
+    import hashlib
+    import tempfile
+
+    key = hashlib.md5(os.path.abspath(os.getcwd()).encode()).hexdigest()[:12]
+    return os.path.join(tempfile.gettempdir(), "synlynk-test-db", f"{key}-{os.getpid()}.db")
+
+
+def _should_isolate_worktree_db(db_path: str) -> bool:
+    """Limit the worktree guard to test execution unless explicitly disabled."""
+    if os.environ.get("SYNLYNK_ALLOW_SHARED_STATE_DB") == "1":
+        return False
+    if not (_INITIAL_GIT_WORKTREE and os.environ.get("PYTEST_CURRENT_TEST")):
+        return False
+    # Explicit test DB_PATH overrides (including tmp_path fixtures) are already
+    # isolated and must keep working in a worktree. Only the canonical product
+    # ledger location is guarded.
+    canonical_root = os.path.abspath(os.path.expanduser("~/.synlynk/projects"))
+    return os.path.abspath(db_path).startswith(canonical_root + os.sep)
+
+
+# The Vizor daemon home is not a checkout. Point DB_PATH at devnull so import
+# cannot mint a product ledger there (gh:#1831). Nothing in the daemon opens it.
+if _FAST_CLI:
+    DB_PATH = os.environ.get("SYNLYNK_STATE_DB_PATH")
+elif _vizor_daemon_process():
+    DB_PATH = os.devnull
+else:
+    DB_PATH = _resolve_db_path()
+# The configured path is intentionally distinct from the path selected by the
+# last successful connection.  Away sandboxes may need the local fallback.
+ACTIVE_DB_PATH = None
+
+
+def _migrate_db_with_schema_retry(conn: _sqlite3.Connection) -> None:
+    """Retry the one SQLite error caused by a concurrent schema refresh.
+
+    Two short-lived CLI connections can both bootstrap an older state DB.  One
+    connection may commit an additive migration after the other prepared a
+    schema statement, which SQLite reports as ``database schema has changed``.
+    The migration is idempotent; retrying it refreshes that connection's schema
+    cache.  Other operational failures remain fail-closed.
+    """
+    from synlynk.db import _migrate_db
+
+    for attempt in range(3):
+        try:
+            _migrate_db(conn)
+            return
+        except _sqlite3.OperationalError as exc:
+            if "database schema has changed" not in str(exc).lower() or attempt == 2:
+                raise
+            try:
+                conn.rollback()
+            except _sqlite3.Error:
+                pass
+
+
+def migrate_cost_entries_for_compaction(db_path: str) -> None:
+    conn = _sqlite3.connect(db_path)
+    try:
+        existing_cols = {row[1] for row in conn.execute("PRAGMA table_info(cost_entries)")}
+        if "compaction_event_type" not in existing_cols:
+            conn.execute("ALTER TABLE cost_entries ADD COLUMN compaction_event_type TEXT")
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def log_cost_entry(db_path: str, harness: str, tokens_in: int, tokens_out: int,
+                    total_cost_usd: float, compaction_event_type=None) -> None:
+    """Record a compaction-related cost row through the single sanctioned
+    cost_entries write path (db.py's _insert_cost_row), not raw SQL here."""
+    import datetime
+    from synlynk.db import _insert_cost_row
+
+    _insert_cost_row(
+        session_date=datetime.date.today().isoformat(),
+        agent=harness,
+        harness=harness,
+        input_tokens=tokens_in,
+        output_tokens=tokens_out,
+        total_cost_usd=total_cost_usd,
+        compaction_event_type=compaction_event_type,
+        db_path=db_path,
+    )
+
+
+
+
+def _get_db(
+    db_path: str = None,
+    read_only: bool = False,
+    *,
+    migrate: bool = True,
+) -> _sqlite3.Connection:
+    """Return a SQLite connection to state.db.
+
+    ``read_only=True`` opens the selected ledger through SQLite's read-only
+    URI mode and deliberately skips directory creation, WAL setup, and
+    migrations.  Inspection callers use this mode so status cannot mutate or
+    silently substitute the product ledger.
+
+    SYNLYNK_STATE_DB_PATH, if set, is used verbatim and takes precedence over
+    everything below: no nested-worktree guard, no fallback chain. A caller
+    setting this env var has made a deliberate choice about ledger location
+    (e.g. a sandbox restricted to the repo workspace root, where neither the
+    home path nor the tmpdir fallback is reachable). If that path is itself
+    unwritable, the resulting exception propagates uncaught — an explicit
+    override that fails should surface loudly, not be silently re-routed.
+    See #681.
+
+    Fallback to ./.synlynk/state.db is disabled by default. A local ledger is
+    a different source of truth and must never be selected silently when the
+    product ledger is unavailable. Sandboxed callers that explicitly accept
+    an isolated, non-canonical ledger may set
+    SYNLYNK_ALLOW_STATE_DB_FALLBACK=1. Dispatched-agent sandboxes commonly
+    mount $HOME read-only; that surfaces as OSError(EROFS) from os.makedirs
+    (not PermissionError) or as sqlite3.OperationalError from connect when
+    the directory already exists. See #648 and the Sev1 state-integrity
+    incident #1655.
+
+    Primary product ledger must not live under job/feature worktrees when the
+    home path is the intended path (#330 / fleet S2a). If an operator
+    explicitly enables the sandbox fallback, it uses a path that never lands
+    under worktrees (tmpdir when cwd is a job/feature worktree) so the
+    nested_state matrix stays clean.
+
+    During pytest execution from a linked worktree, the canonical shared path is
+    redirected to a process-local temporary DB to protect the live ledger. Set
+    SYNLYNK_ALLOW_SHARED_STATE_DB=1 only for tests that explicitly exercise
+    shared-DB behavior.
+    """
+    global ACTIVE_DB_PATH, DB_PATH
+    ACTIVE_DB_PATH = None
+
+    if DB_PATH is None:
+        DB_PATH = _resolve_db_path()
+
+    def _check_write_capability(path: str) -> None:
+        """Check access to *path* without opening SQLite or changing it."""
+        import tempfile
+
+        parent = os.path.dirname(path) or "."
+        if os.path.exists(path):
+            fd = os.open(path, os.O_RDWR)
+            os.close(fd)
+            return
+
+        # A new database has no file to open yet.  Probe the parent directory
+        # with a disposable file instead of creating the candidate database
+        # before its write capability has been established.
+        fd, probe = tempfile.mkstemp(dir=parent, prefix=".synlynk-write-probe-")
+        os.close(fd)
+        os.unlink(probe)
+
+    def _connect(path: str, *, read_only: bool = False, migrate: bool = True) -> _sqlite3.Connection:
+        global ACTIVE_DB_PATH
+        if read_only:
+            wal_path = f"{path}-wal"
+            has_wal = os.path.exists(wal_path) and os.path.getsize(wal_path) > 0
+            if has_wal:
+                # An immutable connection intentionally ignores WAL frames and
+                # would expose stale state.  Take a consistent online-backup
+                # snapshot into memory instead; callers still get a read-only
+                # inspection connection without mutating the source ledger.
+                source_conn = _sqlite3.connect(
+                    f"file:{os.path.abspath(path)}?mode=ro", uri=True, timeout=30.0
+                )
+                conn = _sqlite3.connect(":memory:")
+                try:
+                    source_conn.backup(conn)
+                finally:
+                    source_conn.close()
+            else:
+                conn = _sqlite3.connect(
+                    f"file:{os.path.abspath(path)}?mode=ro&immutable=1",
+                    uri=True,
+                    timeout=30.0,
+                )
+            try:
+                conn.execute("PRAGMA busy_timeout=30000")
+                conn.execute("PRAGMA foreign_keys=ON")
+                quick_check = conn.execute("PRAGMA quick_check").fetchone()[0]
+                if quick_check != "ok":
+                    raise _sqlite3.DatabaseError(
+                        f"state database failed quick_check: {quick_check}"
+                    )
+            except Exception:
+                conn.close()
+                raise
+            ACTIVE_DB_PATH = os.path.abspath(path)
+            return conn
+        os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+        _check_write_capability(path)
+        conn = _sqlite3.connect(path, timeout=30.0)
+        try:
+            conn.isolation_level = None
+            # Do this before WAL setup or migrations.  BEGIN IMMEDIATE only
+            # acquires a write reservation; rolling it back leaves the
+            # candidate database and its sidecars byte-identical on failure.
+            conn.execute("BEGIN IMMEDIATE")
+            conn.execute("ROLLBACK")
+            from synlynk.wal_ledger import ensure_wal_pragmas
+            ensure_wal_pragmas(conn)
+            if migrate:
+                _migrate_db_with_schema_retry(conn)
+            if migrate and not _IS_TESTING and os.path.abspath(path) == os.path.abspath(DB_PATH):
+                from synlynk.product_store import identity_slug_from_config
+                from synlynk.state_registry import ensure_registered_product, identity_metadata, product_identity
+
+                slug = identity_slug_from_config(_project_root())
+                repo_root = Path(_project_root())
+                entry = ensure_registered_product(
+                    slug,
+                    Path(path),
+                    product_identity(slug, _project_root()),
+                    repo_path=repo_root,
+                )
+                if entry.get("repo_path") != str(repo_root.resolve()):
+                    from synlynk.state_registry import update_registered_product
+
+                    update_registered_product(slug, repo_path=str(repo_root.resolve()))
+                identity_metadata(conn, product_id=entry["product_id"], mode="canonical", path=Path(path))
+                conn.commit()
+        except Exception:
+            conn.close()
+            raise
+        ACTIVE_DB_PATH = os.path.abspath(path)
+        return conn
+
+    if db_path is not None:
+        return _connect(db_path, read_only=read_only, migrate=migrate)
+
+    override = os.environ.get("SYNLYNK_STATE_DB_PATH")
+    if override:
+        # Explicit overrides remain authoritative: failures propagate and do
+        # not silently select another ledger.
+        return _connect(override, read_only=read_only, migrate=migrate)
+
+    if read_only:
+        # Read-only inspection must fail on an unavailable/corrupt canonical
+        # ledger rather than falling back to a stale repo or sandbox copy.
+        return _connect(DB_PATH, read_only=True, migrate=migrate)
+
+    from synlynk.fleet import assert_not_nested_product_ledger, sandbox_fallback_db_path
+
+    db_path = DB_PATH
+    if _should_isolate_worktree_db(db_path):
+        db_path = _test_isolation_db_path()
+        print(
+            "warning: pytest is running from a git worktree; using isolated "
+            f"state DB at {db_path}. Set SYNLYNK_ALLOW_SHARED_STATE_DB=1 only "
+            "for an intentional shared-DB test.",
+            file=sys.stderr,
+        )
+    try:
+        assert_not_nested_product_ledger(db_path, home_writable=True)
+        return _connect(db_path, migrate=migrate)
+    # RuntimeError from nested-ledger refusal must not trigger fallback.
+    except (OSError, _sqlite3.OperationalError) as exc:
+        if os.environ.get("SYNLYNK_ALLOW_STATE_DB_FALLBACK") != "1":
+            raise RuntimeError(
+                "canonical state DB unavailable or unusable at "
+                f"{os.path.abspath(db_path)}: {exc}; refusing to select a "
+                "non-canonical fallback. Set SYNLYNK_STATE_DB_PATH to an "
+                "explicit verified ledger, or set "
+                "SYNLYNK_ALLOW_STATE_DB_FALLBACK=1 only for an intentional "
+                "isolated sandbox."
+            ) from exc
+        fallback_path = sandbox_fallback_db_path()
+        print(
+            f"warning: cannot open canonical project state DB at {db_path} "
+            f"({exc}); explicitly falling back with "
+            "SYNLYNK_ALLOW_STATE_DB_FALLBACK=1 — using isolated "
+            f"ledger {fallback_path}",
+            file=sys.stderr,
+        )
+        return _connect(fallback_path, migrate=migrate)
+
+
+def get_state_db_path() -> str:
+    """Return the effective state DB path, including the last fallback choice."""
+    return os.path.abspath(
+        os.environ.get("SYNLYNK_STATE_DB_PATH") or ACTIVE_DB_PATH or DB_PATH
+    )
+
+
+def open_state_db(
+    *,
+    product_id: str | None = None,
+    mode: str = "canonical",
+    read_only: bool = False,
+    explicit_path: str | None = None,
+) -> _sqlite3.Connection:
+    """Open a state ledger through an explicit, typed access mode.
+
+    ``canonical`` is the only mode used by normal product commands.  The
+    other modes are intentionally explicit so tests, backup verification, and
+    restore tooling cannot accidentally become an alternate product ledger.
+    Degraded ledgers are read-only unless an operator explicitly opts into a
+    write with ``SYNLYNK_ALLOW_DEGRADED_WRITES=1``.
+    """
+    allowed = {"canonical", "test", "backup", "restore", "degraded"}
+    if mode not in allowed:
+        raise ValueError(f"unsupported state DB mode: {mode!r}")
+    if mode == "canonical":
+        if explicit_path is not None:
+            from synlynk.product_store import identity_slug_from_config, state_db_path
+            from synlynk.state_registry import canonical_path
+
+            slug = identity_slug_from_config(_project_root())
+            expected = canonical_path(slug, state_db_path(slug)).resolve()
+            requested = Path(explicit_path).expanduser().resolve()
+            if requested != expected:
+                raise RuntimeError(
+                    f"canonical state DB path mismatch: expected {expected}, requested {requested}"
+                )
+        return _get_db(db_path=explicit_path, read_only=read_only) if explicit_path else _get_db(read_only=read_only)
+    if explicit_path is None:
+        raise ValueError(f"mode={mode!r} requires explicit_path")
+    if mode == "degraded" and not read_only and os.environ.get("SYNLYNK_ALLOW_DEGRADED_WRITES") != "1":
+        raise RuntimeError(
+            "degraded state DB access is read-only by default; set "
+            "SYNLYNK_ALLOW_DEGRADED_WRITES=1 for an intentional write"
+        )
+    return _get_db(db_path=explicit_path, read_only=read_only or mode in {"backup"})
+
+
+
+def _is_migrated() -> bool:
+    return os.path.exists(os.path.join(_project_root(), ".synlynk", ".synlynk_migrated"))
+
+
+_GENERATED_DOC_FILES = ("roadmap.md", "todo.md", "memory.md", "costs.md")
+
+
+def _generated_docs_locked(replace_generated_docs: bool = False, root: str = None) -> bool:
+    """True when init/brownfield must not raw-write the generated 4-docs.
+
+    Checks the given root and its git-common-dir parent so a linked worktree
+    of a migrated product is locked even if the worktree has no local marker.
+    """
+    if replace_generated_docs:
+        return False
+    check_roots = []
+    if root:
+        check_roots.append(os.path.abspath(root))
+        try:
+            common = subprocess.check_output(
+                ["git", "rev-parse", "--path-format=absolute", "--git-common-dir"],
+                cwd=root,
+                stderr=subprocess.DEVNULL,
+            ).decode().strip()
+            if common:
+                check_roots.append(os.path.abspath(os.path.join(common, "..")))
+        except Exception:
+            pass
+    else:
+        check_roots.append(_project_root())
+        check_roots.append(os.getcwd())
+    seen = set()
+    for r in check_roots:
+        real = os.path.realpath(r)
+        if real in seen:
+            continue
+        seen.add(real)
+        if os.path.exists(os.path.join(real, ".synlynk", ".synlynk_migrated")):
+            return True
+    return False
+
+
+def _synlynk_project_docs_dir() -> str:
+    return os.path.join(_project_root(), ".synlynk", "project-docs")
+
+
+def _dr_sync(relative_path: str) -> None:
+    if not _generated_doc_side_effects_allowed():
+        return
+
+    from synlynk.db import _resolved_docs_dir
+
+    # Root resolution is mandatory even when the DR destination is absolute:
+    # the source document must belong to the invoking checkout.
+    root = _working_tree_root()
+    src = os.path.join(_resolved_docs_dir(), relative_path)
+    try:
+        workspace_path = os.path.join(root, '.synlynk', 'workspace.json')
+        legacy_path = os.path.join(root, '.synlynk', 'config.json')
+        cfg_path = workspace_path if os.path.exists(workspace_path) else legacy_path
+        if not os.path.exists(cfg_path):
+            return
+        with open(cfg_path) as f:
+            cfg = json.load(f)
+        dr_path = cfg.get('dr_sync_path')
+        if not dr_path:
+            return
+        dr_path = os.path.expanduser(str(dr_path))
+    except Exception:
+        pass
+        return
+    if not os.path.isabs(dr_path):
+        dr_path = os.path.abspath(os.path.join(root, dr_path))
+        try:
+            inside_root = os.path.commonpath(
+                [os.path.realpath(root), os.path.realpath(dr_path)]
+            ) == os.path.realpath(root)
+        except ValueError:
+            inside_root = False
+        if not inside_root:
+            raise RuntimeError("relative dr_sync_path escapes the current checkout")
+    if not os.path.isdir(dr_path) or not os.path.exists(src):
+        return
+    dst = os.path.join(dr_path, 'project-docs', relative_path)
+    try:
+        os.makedirs(os.path.dirname(os.path.abspath(dst)), exist_ok=True)
+        import shutil as _shutil
+        _shutil.copy2(src, dst)
+    except Exception:
+        pass
+
+
+def _generated_doc_side_effects_allowed() -> bool:
+    """Return false for dispatcher jobs that must not emit project-wide docs."""
+    return "SYNLYNK_JOB_ID" not in os.environ
+
+
+def _seed_verb_map(db_conn):
+    db_conn.executemany("""
+        INSERT OR IGNORE INTO harness_verb_map
+                (synlynk_verb, verb_category, harness_name, harness_command, supported, partial_notes)
+        VALUES (?,?,?,?,?,?)
+    """, _VERB_MAP_SEED)
+    db_conn.commit()
+
+
+def _check_verb_support(verb: str, harness_name: str, db_conn) -> dict:
+    row = db_conn.execute(
+        "SELECT supported, partial_notes, harness_command FROM harness_verb_map WHERE synlynk_verb=? AND harness_name=?",
+        (verb, harness_name)
+    ).fetchone()
+    if not row:
+        return {"supported": "unknown", "block": False, "warn": False, "notes": None, "command": None}
+    supported, notes, cmd = row
+    return {
+        "supported": supported,
+        "block": supported == "none",
+        "warn": supported == "partial",
+        "notes": notes,
+        "command": cmd,
+    }
+
+
+def _load_agent_config(name: str) -> dict:
+    """Load .harnesses/<name>.json or .agents/<name>.json. Raises FileNotFoundError with clear message."""
+    import json as _json
+    candidates = [
+        os.path.join(".harnesses", f"{name}.json"),
+        os.path.join("harnesses", f"{name}.json"),
+        os.path.join(".agents", f"{name}.json"),
+        os.path.join("agents", f"{name}.json"),
+    ]
+    path = next((candidate for candidate in candidates if os.path.exists(candidate)), candidates[0])
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"No agent config found at {path}")
+    with open(path) as f:
+        return _json.load(f)
+
+
+def _load_agent_profile(harness_name: str, agents_dir: str = ".agents") -> dict:
+    """Load a harness profile and normalize harness/model defaults."""
+    import json as _json
+
+    candidates = [
+        os.path.join(agents_dir, f"{harness_name}.json"),
+        os.path.join(".harnesses", f"{harness_name}.json"),
+        os.path.join("harnesses", f"{harness_name}.json"),
+        os.path.join(".agents", f"{harness_name}.json"),
+        os.path.join("agents", f"{harness_name}.json"),
+    ]
+    path = next((candidate for candidate in candidates if os.path.exists(candidate)), candidates[0])
+    if not os.path.exists(path):
+        return {"agent": harness_name, "harness": harness_name, "model": "unknown"}
+    try:
+        with open(path) as f:
+            profile = _json.load(f)
+    except (OSError, ValueError, TypeError):
+        return {"agent": harness_name, "harness": harness_name, "model": "unknown"}
+    profile.setdefault("harness", harness_name)
+    profile.setdefault("model", "unknown")
+    return profile
+
+
+def _dispatch_flags_for_agent(agent: str) -> list:
+    """Return the executable dispatch flags for a harness baseline.
+
+    Supports both the legacy list form and the structured mapping form.
+    """
+    baselines = HARNESS_CAPABILITY_BASELINES.get(agent, {})
+    dispatch_flags = baselines.get("dispatch_flags", [])
+    if isinstance(dispatch_flags, dict):
+        ordered = []
+        for flag in dispatch_flags.get("required_flags", []) or []:
+            if flag not in ordered:
+                ordered.append(flag)
+        return ordered
+    return list(dispatch_flags or [])
+
+
+def cmd_roles(fix: bool = False) -> None:
+    """Print current agent role table from config.
+
+    With --fix, regenerate role fences and repair SOP sections.
+    """
+    cfg = load_config()
+    roles = cfg.get("roles", {})
+    if isinstance(roles, dict):
+        visible_agents = [agent for agent in roles if agent]
+    elif isinstance(roles, (list, tuple)):
+        visible_agents = [agent for agent in roles if agent]
+    else:
+        visible_agents = []
+
+    print(f"\n  {_BOLD}synlynk roles{_RESET}\n")
+    print(f"  {'agent':<10}  {'roles':<40}  {'directive file':<12}  fence")
+    print(f"  {'─' * 10}  {'─' * 40}  {'─' * 12}  {'─' * 10}")
+
+    for agent in visible_agents:
+        role_list = roles.get(agent, []) if isinstance(roles, dict) else []
+        fname = _directive_file_for_agent(agent)
+        roles_str = ", ".join(role_list) if isinstance(role_list, list) else str(role_list)
+        file_exists = os.path.exists(fname)
+        fence_present = False
+        if file_exists:
+            try:
+                with open(fname) as f:
+                    fence_present = "<!-- synlynk:harness" in f.read()
+            except IOError:
+                pass
+        file_status = fname if file_exists else f"{fname} (missing)"
+        fence_status = f"{_GREEN}✓{_RESET}" if fence_present else f"{_YELLOW}missing{_RESET}"
+        print(f"  {agent:<10}  {roles_str:<40}  {file_status:<12}  {fence_status}")
+
+        if fix and file_exists and not fence_present:
+            roles_line = ", ".join(role_list) if isinstance(role_list, list) else str(role_list)
+            try:
+                _upsert_harness_fence(
+                    fname,
+                    harness_version="roles",
+                    body=f"## Your Role\n{roles_line}\n",
+                )
+                print(f"    {_GREEN}✓{_RESET} wrote role fence to {fname}")
+            except Exception as exc:
+                print(f"    {_YELLOW}⚠{_RESET} could not write {fname}: {exc}")
+
+    if fix:
+        try:
+            _repair_sops_only(cfg=cfg, dry_run=False)
+        except Exception as exc:
+            print(f"  {_YELLOW}⚠{_RESET} could not repair SOP sections: {exc}")
+
+    print()
+    if not fix:
+        missing = [
+            _directive_file_for_agent(a)
+            for a in visible_agents
+            if os.path.exists(_directive_file_for_agent(a))
+            and not _fence_exists(_directive_file_for_agent(a))
+        ]
+        if missing:
+            print(f"  {_DIM}Run `synlynk roles --fix` to write missing role fences and repair SOP sections{_RESET}\n")
+    if not visible_agents:
+        print(f"  {_DIM}No agents in roles to display{_RESET}\n")
+
+
+
+
+_ENGG_DOMAIN_PATTERNS = [
+    ("data",         [r"etl", r"pipeline/", r"schema\.sql", r"migrations/", r"dbt/"]),
+    ("ml",           [r"ml/", r"models/", r"train\.", r"inference/", r"embeddings/"]),
+    ("security",     [r"auth/", r"oauth", r"jwt", r"crypto", r"certs/"]),
+    ("devops",       [r"\.github/", r"dockerfile", r"terraform", r"pulumi", r"k8s/", r"helm/"]),
+    ("frontend",     [r"components/", r"pages/", r"\.tsx?", r"\.vue", r"\.svelte", r"styles/"]),
+    ("backend",      [r"api/", r"routes/", r"handlers/", r"controllers/", r"services/"]),
+    ("testing",      [r"tests/", r"test_", r"spec/", r"\.spec\.", r"fixtures/"]),
+    ("docs",         [r"docs/", r"readme", r"\.md$", r"changelogs?"]),
+    ("architecture", [r"design/", r"specs/", r"adr/", r"diagrams/"]),
+]
+
+def _infer_engg_domain(log_text: str) -> str:
+    """Infers engineering domain from file path patterns in job log output."""
+    lower = log_text.lower()
+    for domain, patterns in _ENGG_DOMAIN_PATTERNS:
+        if any(re.search(p, lower) for p in patterns):
+            return domain
+    return "unknown"
+
+
+JOBS_FILE = ".synlynk/jobs.json"
+LOGS_DIR = ".synlynk/logs"
+PROMPTS_DIR = ".synlynk/prompts"
+
+_VERB_MAP_SEED = [
+    # (synlynk_verb, category, agent, harness_command, supported, partial_notes)
+    ("dispatch.task",     "dispatch",      "claude", "claude --print {task}", "full", None),
+    ("dispatch.task",     "dispatch",      "agy",    "agy -p {task}", "full", None),
+    ("dispatch.task",     "dispatch",      "grok",   "grok --single {task}", "full", None),
+    ("dispatch.task",     "dispatch",      "codex",  "codex exec - -s workspace-write", "full", None),
+    ("dispatch.headless", "dispatch",      "claude", "claude --print {task}", "full", None),
+    ("dispatch.headless", "dispatch",      "agy",    "agy -p {task}", "partial", "May hang without PTY on some agy versions"),
+    ("dispatch.headless", "dispatch",      "grok",   "grok --single {task}", "partial", "Network dep required"),
+    ("dispatch.headless", "dispatch",      "codex",  "codex exec - -s workspace-write", "full", None),
+    ("dispatch.resume",   "dispatch",      "claude", "claude --resume {session_id}", "full", None),
+    ("dispatch.resume",   "dispatch",      "agy",    None, "none", None),
+    ("dispatch.resume",   "dispatch",      "grok",   None, "none", None),
+    ("dispatch.resume",   "dispatch",      "codex",  None, "none", None),
+    ("dispatch.approve",  "dispatch",      "claude", "claude --allowedTools {tools}", "full", None),
+    ("dispatch.approve",  "dispatch",      "agy",    None, "none", None),
+    ("dispatch.approve",  "dispatch",      "grok",   None, "none", None),
+    ("dispatch.approve",  "dispatch",      "codex",  None, "partial", "ask-for-approval=untrusted only"),
+    ("dispatch.model",    "dispatch",      "claude", "--model {model}", "full", None),
+    ("dispatch.model",    "dispatch",      "agy",    "--model {model}", "full", None),
+    ("dispatch.model",    "dispatch",      "grok",   "--model {model}", "full", None),
+    ("dispatch.model",    "dispatch",      "codex",  "--model {model}", "full", None),
+    ("dispatch.tools",    "dispatch",      "claude", "--allowedTools {tools}", "full", None),
+    ("dispatch.tools",    "dispatch",      "agy",    None, "partial", "No tool_list flag"),
+    ("dispatch.tools",    "dispatch",      "grok",   None, "none", None),
+    ("dispatch.tools",    "dispatch",      "codex",  None, "partial", "ask-for-approval only"),
+    ("dispatch.context",  "dispatch",      "claude", "claude --print {task}", "full", None),
+    ("dispatch.context",  "dispatch",      "agy",    "agy -p {task}", "full", None),
+    ("dispatch.context",  "dispatch",      "grok",   "grok --prompt {task}", "partial", "No explicit context file flag"),
+    ("dispatch.context",  "dispatch",      "codex",  "codex exec - -s workspace-write", "full", None),
+    ("jobs",              "observability", "claude", None, "partial", "No native jobs subcommand"),
+    ("jobs",              "observability", "agy",    None, "none", None),
+    ("jobs",              "observability", "grok",   None, "none", None),
+    ("jobs",              "observability", "codex",  None, "none", None),
+    ("status",            "observability", "claude", None, "partial", None),
+    ("status",            "observability", "agy",    None, "none", None),
+    ("status",            "observability", "grok",   None, "none", None),
+    ("status",            "observability", "codex",  None, "none", None),
+    ("telemetry",         "observability", "claude", None, "none", None),
+    ("telemetry",         "observability", "agy",    None, "none", None),
+    ("telemetry",         "observability", "grok",   None, "none", None),
+    ("telemetry",         "observability", "codex",  None, "none", None),
+    ("costs",             "observability", "claude", None, "partial", "Token count via /cost"),
+    ("costs",             "observability", "agy",    None, "none", None),
+    ("costs",             "observability", "grok",   None, "none", None),
+    ("costs",             "observability", "codex",  None, "none", None),
+    ("probe",             "harness",       "claude", "claude --version", "full", None),
+    ("probe",             "harness",       "agy",    "agy --version", "full", None),
+    ("probe",             "harness",       "grok",   "grok --version", "full", None),
+    ("probe",             "harness",       "codex",  "codex --version", "full", None),
+    ("doctor",            "harness",       "claude", None, "full", None),
+    ("doctor",            "harness",       "agy",    None, "full", None),
+    ("doctor",            "harness",       "grok",   None, "full", None),
+    ("doctor",            "harness",       "codex",  None, "full", None),
+    ("story",             "pm",            "claude", None, "none", None),
+    ("story",             "pm",            "agy",    None, "none", None),
+    ("story",             "pm",            "grok",   None, "none", None),
+    ("story",             "pm",            "codex",  None, "none", None),
+    ("epic",              "pm",            "claude", None, "none", None),
+    ("epic",              "pm",            "agy",    None, "none", None),
+    ("epic",              "pm",            "grok",   None, "none", None),
+    ("epic",              "pm",            "codex",  None, "none", None),
+    ("decide",            "pm",            "claude", None, "none", None),
+    ("decide",            "pm",            "agy",    None, "none", None),
+    ("decide",            "pm",            "grok",   None, "none", None),
+    ("decide",            "pm",            "codex",  None, "none", None),
+    ("workspace",         "workspace",     "claude", None, "none", None),
+    ("workspace",         "workspace",     "agy",    None, "none", None),
+    ("workspace",         "workspace",     "grok",   None, "none", None),
+    ("workspace",         "workspace",     "codex",  None, "none", None),
+    ("upgrade",           "workspace",     "claude", None, "partial", "Via /upgrade slash command"),
+    ("upgrade",           "workspace",     "agy",    None, "partial", "Via agy update"),
+    ("upgrade",           "workspace",     "grok",   None, "partial", None),
+    ("upgrade",           "workspace",     "codex",  None, "partial", None),
+]
+
+RELAY_EVENT_TYPES = frozenset({
+    "story_updated",
+    "job_dispatched",
+    "job_completed",
+    "alert_raised",
+    "context_checkpoint",
+    "table_changed",
+    "broadcast",
+})
+
+
+def _build_relay_event(event_type: str, payload: dict) -> dict:
+    """Constructs a relay event dict with required base fields."""
+    if event_type not in RELAY_EVENT_TYPES:
+        raise ValueError(
+            f"unknown event type '{event_type}'. Valid: {sorted(RELAY_EVENT_TYPES)}"
+        )
+    import socket as _socket
+
+    event = {
+        "type": event_type,
+        "ts": int(time.time()),
+        "origin_node": _socket.gethostname(),
+    }
+    event.update(payload)
+    return event
+
+# Default paths scanned for agent CLI config directories.
+# Overridable in .synlynk/config.json under "agent_discovery_paths".
+AGENT_DISCOVERY_DEFAULTS = {
+    "claude": os.path.expanduser("~/.claude"),
+    "codex": os.path.expanduser("~/.codex"),
+    "agy": os.path.expanduser("~/.agy"),
+    "grok": os.path.expanduser("~/.grok"),
+}
+
+_AGENT_DIRECTIVE_FILES = {
+    "claude": "CLAUDE.md",
+    "agy": "GEMINI.md",
+    "grok": "GROK.md",
+    "codex": "AGENTS.md",
+}
+
+
+def _default_roles_for_agent(agent: str) -> list:
+    """Return the default onboarded role list for an agent."""
+    return {
+        "claude": ["pm", "review", "deploy"],
+        "agy": ["implement", "test", "css", "templates", "content"],
+        "grok": ["implement", "test", "canvas", "js", "infra"],
+        "codex": ["implement", "test", "refactor"],
+    }.get(agent, [])
+
+
+def _default_roles_map() -> dict:
+    """Return the default role mapping for supported agents."""
+    return {name: _default_roles_for_agent(name) for name in _AGENT_DIRECTIVE_FILES}
+
+
+def _directive_file_for_agent(agent: str) -> str:
+    return _AGENT_DIRECTIVE_FILES.get(agent, f"{agent}.md")
+
+
+def _write_json_atomic(path: str, payload: dict) -> None:
+    """Write a JSON file atomically within the current workspace."""
+    directory = os.path.dirname(path) or "."
+    os.makedirs(directory, exist_ok=True)
+    fd, tmp_path = tempfile.mkstemp(dir=directory, prefix=".tmp.", suffix=".json")
+    try:
+        with os.fdopen(fd, "w") as f:
+            json.dump(payload, f, indent=2)
+            f.write("\n")
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp_path, path)
+    finally:
+        if os.path.exists(tmp_path):
+            try:
+                os.remove(tmp_path)
+            except OSError:
+                pass
+
+
+_WORKSPACE_KEYS = [
+    "org", "owner", "repo", "project_id", "identity_slug", "project_docs_dir",
+    "workspace_id", "agent_slots", "workgroup_agents", "agents", "team",
+    "sync_endpoint", "dispatch", "local_auto_threshold", "local_fallback",
+    "watch_interval_seconds", "auto_smoke_test", "auto_launch_after_wizard",
+    "dispatch_mode", "fenced_commands", "nudges", "exec_timeout_minutes",
+    "stall_timeout_minutes", "review_stall_timeout_minutes", "swarm_runners",
+    "last_housekeeping_date", "features", "repo_id", "dr_sync_path", "mode",
+    "termination_grace_seconds", "cleanup_verification_timeout_seconds",
+]
+_BILLING_KEYS = ["budget", "harness_billing", "payment_models", "capability_sweep"]
+_POLICY_MIGRATED_KEYS = ["qa_gate_mode", "roles", "story_classification", "sentinel"]
+
+
+def _apply_workspace_defaults(config: dict) -> dict:
+    """Fill in schema-v1 defaults for a workspace config dict, in place and returned."""
+    defaults = {
+        "schema_version": 1,
+        "dispatch": {"stacking": "auto", "gate_suite_cmd": ""},
+        "local_auto_threshold": 0.5,
+        "local_fallback": "agy",
+        "watch_interval_seconds": 30,
+        "auto_smoke_test": False,
+        "auto_launch_after_wizard": True,
+        "dispatch_mode": "daily-grind",
+        "fenced_commands": ["dispatch", "jobs", "exec", "schedule"],
+        "nudges": {"enabled": True, "dismissed_ids": [], "last_shown": {}},
+        "org": None,
+        "owner": None,
+        "repo": None,
+        "project_id": None,
+        "identity_slug": None,
+        "project_docs_dir": "project-docs",
+        "agent_slots": {"claude": "claude", "agy": "agy", "codex": "codex", "grok": "grok"},
+        "workgroup_agents": [],
+        "last_housekeeping_date": None,
+        "team": None,
+        "sync_endpoint": None,
+        "exec_timeout_minutes": 30,
+        "stall_timeout_minutes": 30,
+        "swarm_runners": {"default": "local", "enabled": ["local"], "timeout_seconds": 900},
+        "review_stall_timeout_minutes": 90,
+        "termination_grace_seconds": 5,
+        "cleanup_verification_timeout_seconds": 300,
+        "agents": {},
+        "features": {},
+        "repo_id": None,
+        "dr_sync_path": None,
+        "mode": "solo",
+    }
+    if not isinstance(config, dict):
+        config = {}
+    for key, val in defaults.items():
+        if key not in config:
+            config[key] = val
+    for key, val in defaults["dispatch"].items():
+        if key not in config.get("dispatch", {}):
+            config.setdefault("dispatch", {})[key] = val
+    for key, val in defaults["nudges"].items():
+        if key not in config.get("nudges", {}):
+            config.setdefault("nudges", {})[key] = val
+    return config
+
+
+def load_workspace() -> dict:
+    """Load .synlynk/workspace.json with schema-v1 defaults."""
+    config_file = ".synlynk/workspace.json"
+    if not os.path.exists(config_file):
+        return _apply_workspace_defaults({})
+    try:
+        with open(config_file) as f:
+            config = json.load(f)
+        if not isinstance(config, dict):
+            return _apply_workspace_defaults({})
+        return _apply_workspace_defaults(config)
+    except (json.JSONDecodeError, IOError):
+        return _apply_workspace_defaults({})
+
+
+def _apply_billing_defaults(config: dict) -> dict:
+    """Fill in schema-v1 defaults for a billing config dict, in place and returned."""
+    defaults = {
+        "schema_version": 1,
+        "budget": {"limit_usd": 10.0, "limit_requests": 100},
+        "payment_models": {},
+        "harness_billing": _default_harness_billing(),
+        "capability_sweep": {"cost_cap_usd": 10.0},
+    }
+    if not isinstance(config, dict):
+        config = {}
+    has_harness_billing = "harness_billing" in config
+    for key, val in defaults.items():
+        if key not in config:
+            config[key] = {} if key == "harness_billing" else val
+    for key, val in defaults["budget"].items():
+        if key not in config.get("budget", {}):
+            config.setdefault("budget", {})[key] = val
+    if not isinstance(config.get("harness_billing"), dict):
+        config["harness_billing"] = _default_harness_billing()
+    elif not config["harness_billing"] and has_harness_billing:
+        config["harness_billing"] = _default_harness_billing()
+    for billing in config["harness_billing"].values():
+        if isinstance(billing, dict):
+            billing.setdefault("payment_mode", "pay_as_you_go")
+            billing.setdefault("monthly_base_fee_usd", billing.get("subscription_fee_usd", 0.0))
+            billing.setdefault("projected_monthly_tokens", 10_000_000)
+            billing.setdefault("allow_extra_usage", False)
+            billing.setdefault("extra_usage_cap_usd", None)
+    return config
+
+
+def load_billing() -> dict:
+    """Load .synlynk/billing.json with schema-v1 defaults."""
+    config_file = ".synlynk/billing.json"
+    if not os.path.exists(config_file):
+        return {
+            "schema_version": 1,
+            "budget": {"limit_usd": 10.0, "limit_requests": 100},
+            "payment_models": {},
+            "harness_billing": _default_harness_billing(),
+            "capability_sweep": {"cost_cap_usd": 10.0},
+        }
+    try:
+        with open(config_file) as f:
+            config = json.load(f)
+        if not isinstance(config, dict):
+            return {
+                "schema_version": 1,
+                "budget": {"limit_usd": 10.0, "limit_requests": 100},
+                "payment_models": {},
+                "harness_billing": _default_harness_billing(),
+                "capability_sweep": {"cost_cap_usd": 10.0},
+            }
+        return _apply_billing_defaults(config)
+    except (json.JSONDecodeError, IOError):
+        return {
+            "schema_version": 1,
+            "budget": {"limit_usd": 10.0, "limit_requests": 100},
+            "payment_models": {},
+            "harness_billing": _default_harness_billing(),
+            "capability_sweep": {"cost_cap_usd": 10.0},
+        }
+
+
+def _read_raw_policy() -> dict:
+    """Read .synlynk/policy.json without defaults, or return {} if absent/corrupt."""
+    try:
+        with open(".synlynk/policy.json") as f:
+            data = json.load(f)
+        return data if isinstance(data, dict) else {}
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _read_policy_migrated_fields(policy: dict | None = None) -> dict:
+    """Read the legacy fields that are migrated into policy.json."""
+    try:
+        from synlynk.capability_roles import _load_capability_roles
+        capability_roles = _load_capability_roles()
+    except ImportError:
+        capability_roles = None
+    if policy is None:
+        policy = _read_raw_policy()
+    result = {
+        "roles": capability_roles if capability_roles is not None else _default_roles_map(),
+        "story_classification": {"method": "heuristic"},
+        "qa_gate_mode": "block-only",
+        "sentinel": {
+            "dedup_window_seconds": 86400,
+            "active_ttl_seconds": {"CRITICAL": 180 * 86400, "WARN": 180 * 86400, "INFO": 180 * 86400},
+        },
+    }
+    if capability_roles is None and "roles" in policy:
+        result["roles"] = policy["roles"]
+    for key in ("story_classification", "qa_gate_mode", "sentinel"):
+        if key in policy:
+            result[key] = policy[key]
+    return result
+
+
+def _split_legacy_config(legacy: dict, existing_policy: dict) -> tuple[dict, dict, dict]:
+    """Partition a legacy config.json dict into workspace/billing/policy payloads.
+
+    Pure, no I/O. Workspace is the catch-all so unclaimed legacy keys are preserved.
+    """
+    claimed = set(_BILLING_KEYS) | set(_POLICY_MIGRATED_KEYS)
+    workspace_payload = {"schema_version": 1}
+    workspace_payload.update({k: v for k, v in legacy.items() if k not in claimed})
+
+    billing_payload = {"schema_version": 1}
+    billing_payload.update({k: legacy[k] for k in _BILLING_KEYS if k in legacy})
+
+    policy_payload = dict(existing_policy)
+    policy_payload.update({k: legacy[k] for k in _POLICY_MIGRATED_KEYS if k in legacy})
+    policy_payload.setdefault("schema_version", 1)
+
+    return workspace_payload, billing_payload, policy_payload
+
+
+def migrate_legacy_config_if_needed() -> bool:
+    """Explicitly split .synlynk/config.json into workspace, billing, and policy files once."""
+    legacy_path = ".synlynk/config.json"
+    workspace_path = ".synlynk/workspace.json"
+    billing_path = ".synlynk/billing.json"
+    policy_path = ".synlynk/policy.json"
+
+    if not os.path.exists(legacy_path):
+        return False
+    if os.path.exists(workspace_path) or os.path.exists(billing_path):
+        return False
+
+    try:
+        with open(legacy_path) as f:
+            legacy = json.load(f)
+    except (json.JSONDecodeError, IOError):
+        return False
+    if not isinstance(legacy, dict):
+        return False
+
+    # A present but corrupt policy file aborts the whole migration. A missing
+    # policy file is valid and uses an empty policy as its base.
+    if os.path.exists(policy_path):
+        try:
+            with open(policy_path) as f:
+                existing_policy = json.load(f)
+            if not isinstance(existing_policy, dict):
+                return False
+        except (json.JSONDecodeError, IOError):
+            return False
+    else:
+        existing_policy = {}
+
+    workspace_payload, billing_payload, policy_payload = _split_legacy_config(legacy, existing_policy)
+
+    _write_json_atomic(workspace_path, workspace_payload)
+    _write_json_atomic(billing_path, billing_payload)
+    _write_json_atomic(policy_path, policy_payload)
+    os.replace(legacy_path, legacy_path + ".bak")
+    return True
+
+# ANSI helpers used by the wizard.
+_BOLD = "\033[1m"
+_GREEN = "\033[32m"
+_YELLOW = "\033[33m"
+_CYAN = "\033[36m"
+_DIM = "\033[2m"
+_RESET = "\033[0m"
+_RED = "\033[31m"
+_MAGENTA = "\033[35m"
+
+
+def _docs_dir() -> str:
+    """Returns the configured project docs directory (defaults to 'project-docs').
+
+    Reads project_docs_dir from .synlynk/workspace.json (falls back to the
+    legacy .synlynk/config.json for projects not yet migrated). Pass
+    --docs-dir to synlynk init to set a custom location (e.g. '.' for repos
+    that keep docs at the root).
+    """
+    workspace_file = ".synlynk/workspace.json"
+    legacy_file = ".synlynk/config.json"
+    config_file = workspace_file if os.path.exists(workspace_file) else legacy_file
+    if os.path.exists(config_file):
+        try:
+            with open(config_file) as f:
+                return json.load(f).get("project_docs_dir", "project-docs")
+        except (json.JSONDecodeError, IOError):
+            pass
+    return "project-docs"
+
+
+_DEFAULT_HARNESS_BILLING = {
+    "claude": {
+        "payment_mode": "subscription",
+        "monthly_base_fee_usd": 20.0,
+        "projected_monthly_tokens": 10_000_000,
+        "allow_extra_usage": False,
+    },
+    "codex": {
+        "payment_mode": "subscription",
+        "monthly_base_fee_usd": 20.0,
+        "projected_monthly_tokens": 10_000_000,
+        "allow_extra_usage": False,
+    },
+    "agy": {
+        "payment_mode": "subscription",
+        "monthly_base_fee_usd": 20.0,
+        "projected_monthly_tokens": 10_000_000,
+        "allow_extra_usage": False,
+    },
+    "grok": {
+        "payment_mode": "subscription",
+        "monthly_base_fee_usd": 30.0,
+        "projected_monthly_tokens": 10_000_000,
+        "allow_extra_usage": False,
+    },
+}
+
+
+def _default_harness_billing() -> dict:
+    """Return an independent copy of the standard quad-harness billing seed."""
+    return {agent: dict(config) for agent, config in _DEFAULT_HARNESS_BILLING.items()}
+
+
+def load_config() -> dict:
+    """Read the composed config without writing, renaming, or deleting files."""
+    workspace_path = ".synlynk/workspace.json"
+    billing_path = ".synlynk/billing.json"
+    legacy_path = ".synlynk/config.json"
+
+    config = {"schema_version": 1}
+
+    if not os.path.exists(workspace_path) and not os.path.exists(billing_path) and os.path.exists(legacy_path):
+        legacy = None
+        try:
+            with open(legacy_path) as f:
+                legacy = json.load(f)
+        except (json.JSONDecodeError, IOError):
+            legacy = None
+        if isinstance(legacy, dict):
+            existing_policy = _read_raw_policy()
+            workspace_payload, billing_payload, policy_payload = _split_legacy_config(legacy, existing_policy)
+            config.update(_apply_workspace_defaults(workspace_payload))
+            config.update(_apply_billing_defaults(billing_payload))
+            config.update(_read_policy_migrated_fields(policy_payload))
+            return config
+
+    config.update(load_workspace())
+    config.update(load_billing())
+    config.update(_read_policy_migrated_fields())
+    return config
+
+
+def cmd_config_set(key: str, value) -> None:
+    """Set a top-level config key, routed to its owning split config file."""
+    migrate_legacy_config_if_needed()
+    if key in _BILLING_KEYS:
+        path = ".synlynk/billing.json"
+        data = load_billing()
+    elif key in _POLICY_MIGRATED_KEYS:
+        path = ".synlynk/policy.json"
+        data = _read_raw_policy()
+        data.setdefault("schema_version", 1)
+    else:
+        path = ".synlynk/workspace.json"
+        data = load_workspace()
+    data[key] = value
+    _write_json_atomic(path, data)
+    print(f"  ✓ {key} = {value!r} saved to {path}")
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+def _check_upstream_divergence() -> None:
+    """Warn if remote has commits the local branch hasn't pulled. Silent no-op otherwise."""
+    try:
+        local = subprocess.check_output(
+            ["git", "rev-parse", "HEAD"], stderr=subprocess.DEVNULL
+        ).decode().strip()
+        upstream = subprocess.check_output(
+            ["git", "rev-parse", "@{u}"], stderr=subprocess.DEVNULL
+        ).decode().strip()
+    except (subprocess.CalledProcessError, AttributeError):
+        return  # no upstream configured, detached HEAD, or not in git repo
+    if local != upstream:
+        try:
+            behind = subprocess.check_output(
+                ["git", "rev-list", "--count", "HEAD..@{u}"],
+                stderr=subprocess.DEVNULL
+            ).decode().strip()
+        except (subprocess.CalledProcessError, AttributeError):
+            behind = "?"
+        print(f"⚠  Remote has {behind} commit(s) you haven't pulled. "
+              f"Consider `git pull` before writing.\n   Continuing anyway...")
+
+
+def _seed_devlog(username: str) -> None:
+    """Creates project-docs/devlogs/<username>.md if absent. Idempotent."""
+    devlog_dir = os.path.join(_docs_dir(), "devlogs")
+    os.makedirs(devlog_dir, exist_ok=True)
+    devlog_path = os.path.join(devlog_dir, f"{username}.md")
+    if os.path.exists(devlog_path):
+        return
+    today = time.strftime("%Y-%m-%d")
+    with open(devlog_path, "w") as f:
+        f.write(f"# Devlog — @{username}\n\n")
+        f.write(f"## {today} — Joined project\n")
+        f.write("Joined via `synlynk join`.\n")
+
+
+
+
+
+
+def cmd_exit(dry_run: bool = True, remove_docs: bool = False) -> int:
+    """Reverse synlynk onboarding: strip instruction sections, remove .synlynk/ and .agents/.
+
+    Writes SYNLYNK_HANDOFF.md summarising what was configured before removal.
+    Dry-run by default — pass --confirm to execute.
+    """
+    manifest_data = _load_instruction_manifest()
+    docs = None
+    try:
+        docs = _docs_dir()
+    except Exception:
+        pass
+
+    cfg = {}
+    _cfg_path = ".synlynk/workspace.json" if os.path.exists(".synlynk/workspace.json") else ".synlynk/config.json"
+    if os.path.exists(_cfg_path):
+        try:
+            cfg = json.load(open(_cfg_path))
+        except Exception:
+            pass
+
+    # Build action list
+    strip_targets = []
+    for fpath, info in manifest_data.items():
+        style = _MARKER_STYLE_FOR_TOOL.get(info.get("tool", ""), "html")
+        strip_targets.append((fpath, style, info.get("tool", "?")))
+
+    agent_profiles = []
+    if os.path.isdir(".agents"):
+        agent_profiles = [os.path.join(".agents", f) for f in os.listdir(".agents") if f.endswith(".json")]
+
+    synlynk_dir = ".synlynk"
+    docs_dir_path = docs if (remove_docs and docs and os.path.isdir(docs)) else None
+
+    print(f"\n{_BOLD}synlynk exit{_RESET} {'(dry run — pass --confirm to execute)' if dry_run else '(executing)'}\n")
+
+    # Instruction files
+    print("  Instruction files:")
+    if strip_targets:
+        for fpath, style, tool in strip_targets:
+            exists = os.path.exists(fpath)
+            tag = "remove" if style == "none" else "strip synlynk section"
+            label = f"{_DIM}(not found){_RESET}" if not exists else ""
+            print(f"    {'→' if dry_run else '✓'} {fpath} [{tool}] — {tag} {label}")
+            if not dry_run and exists:
+                _strip_synlynk_section(fpath, style)
+    else:
+        print(f"    {_DIM}no tracked instruction files{_RESET}")
+
+    # Agent profiles
+    print("  Agent profiles:")
+    if agent_profiles:
+        for p in agent_profiles:
+            print(f"    {'→' if dry_run else '✓'} remove {p}")
+            if not dry_run:
+                os.remove(p)
+        if not dry_run and os.path.isdir(".agents"):
+            try:
+                os.rmdir(".agents")
+            except OSError:
+                pass
+    else:
+        print(f"    {_DIM}no .agents/ profiles found{_RESET}")
+
+    # .synlynk/ directory
+    print(f"  Config & state:")
+    print(f"    {'→' if dry_run else '✓'} remove {synlynk_dir}/")
+    if not dry_run and os.path.isdir(synlynk_dir):
+        import shutil as _shutil
+        _shutil.rmtree(synlynk_dir)
+
+    # project-docs (optional)
+    if docs_dir_path:
+        print(f"  Project docs:")
+        print(f"    {'→' if dry_run else '✓'} remove {docs_dir_path}/")
+        if not dry_run:
+            import shutil as _shutil
+            _shutil.rmtree(docs_dir_path)
+    elif remove_docs:
+        print(f"  Project docs: {_DIM}not found or already absent{_RESET}")
+
+    # Handoff doc
+    handoff_path = "SYNLYNK_HANDOFF.md"
+    handoff_lines = [
+        f"# synlynk handoff — {time.strftime('%Y-%m-%d')}",
+        "",
+        "synlynk was removed from this repository. This file records what was configured.",
+        "",
+        "## Configuration",
+        f"- Version: {cfg.get('synlynk_version', VERSION)}",
+        f"- Mode: {cfg.get('mode', 'unknown')}",
+        f"- Agents: {', '.join(cfg.get('agent_slots', {}).keys()) or 'unknown'}",
+        f"- Org: {cfg.get('org', 'unknown')} / {cfg.get('repo', 'unknown')}",
+        f"- Docs dir: {docs or 'unknown'}",
+        "",
+        "## Removed",
+    ]
+    for fpath, style, tool in strip_targets:
+        handoff_lines.append(f"- `{fpath}` ({tool}) — synlynk section stripped")
+    for p in agent_profiles:
+        handoff_lines.append(f"- `{p}` — removed")
+    handoff_lines += [
+        f"- `.synlynk/` — removed",
+        "",
+        "## To re-initialize",
+        "```",
+        f"synlynk init --agents {','.join(cfg.get('agent_slots', {}).keys()) or 'claude,agy,codex,grok'}",
+        "```",
+        "",
+    ]
+    print(f"  Handoff doc:")
+    print(f"    {'→' if dry_run else '✓'} write {handoff_path}")
+    if not dry_run:
+        with open(handoff_path, "w") as f:
+            f.write("\n".join(handoff_lines))
+
+    print()
+    if dry_run:
+        print(f"  Dry run complete. Run with {_CYAN}--confirm{_RESET} to apply changes.")
+    else:
+        print(f"  {_GREEN}synlynk removed.{_RESET} See {handoff_path} for re-init instructions.")
+    print()
+    return 0
+
+
+def cmd_repair(dry_run: bool = True) -> int:
+    """Exit synlynk and immediately re-initialize from the current configuration.
+
+    Reads config before exit so re-init uses the same agents/mode/org/repo/docs-dir.
+    Dry-run by default — pass --confirm to execute.
+    """
+    cfg = {}
+    _cfg_path = ".synlynk/workspace.json" if os.path.exists(".synlynk/workspace.json") else ".synlynk/config.json"
+    if os.path.exists(_cfg_path):
+        try:
+            cfg = json.load(open(_cfg_path))
+        except Exception:
+            pass
+
+    agents_str = ",".join(cfg.get("agent_slots", {}).keys()) or "claude,agy,codex,grok"
+    mode = cfg.get("mode", "solo")
+    org = cfg.get("org") or None
+    repo = cfg.get("repo") or None
+    project_id = cfg.get("project_id") or None
+    docs_dir_arg = cfg.get("docs_dir") or None
+
+    print(f"\n{_BOLD}synlynk repair{_RESET} {'(dry run — pass --confirm to execute)' if dry_run else '(executing)'}\n")
+    print(f"  Captured config: agents={agents_str}  mode={mode}  org={org or '—'}  docs-dir={docs_dir_arg or 'project-docs'}")
+    print()
+
+    print("  Step 1: exit")
+    cmd_exit(dry_run=dry_run)
+
+    print("  Step 2: re-init")
+    if dry_run:
+        print(f"    → synlynk init --agents {agents_str} --mode {mode}"
+              + (f" --org {org}" if org else "")
+              + (f" --repo {repo}" if repo else "")
+              + (f" --project-id {project_id}" if project_id else "")
+              + (f" --docs-dir {docs_dir_arg}" if docs_dir_arg else ""))
+        print()
+        print(f"  Dry run complete. Run with {_CYAN}--confirm{_RESET} to apply.")
+    else:
+        init(
+            agents=[a.strip() for a in agents_str.split(",") if a.strip()],
+            mode=mode,
+            org=org,
+            repo=repo,
+            project_id=project_id,
+            docs_dir=docs_dir_arg,
+        )
+        try:
+            from synlynk.doctor import cleanup_selftest_workspaces
+
+            removed = cleanup_selftest_workspaces()
+            if removed:
+                print(f"  ✓ Cleaned up {removed} orphaned synlynk-selftest workspace(s)")
+        except Exception:
+            pass
+        print(f"\n  {_GREEN}Repair complete.{_RESET}")
+    print()
+    return 0
+
+
+def cmd_sync(dry_run: bool = True, repair_sops: bool = False) -> int:
+    """Propagate updated synlynk artifacts to an existing repo without full re-init.
+
+    Updates: instruction file sections (CLAUDE.md, GEMINI.md, etc.), .agents/ profile
+    defaults for any slots missing from .agents/. Does NOT touch project-docs/.
+    Dry-run by default — pass --confirm to execute.
+    """
+    print(f"\n{_BOLD}synlynk sync{_RESET} {'(dry run — pass --confirm to execute)' if dry_run else '(executing)'}\n")
+
+    # --- instruction files ---
+    manifest_data = _load_instruction_manifest()
+    print("  Instruction files:")
+    if not manifest_data:
+        print(f"    {_DIM}no tracked instruction files — run synlynk init first{_RESET}")
+    else:
+        _tool_content_builders = {
+            "cursor":    (_build_cursor_mdc,            "none"),
+            "copilot":   (_build_copilot_instructions,  "html"),
+            "windsurf":  (_build_windsurf_rules,        "hash"),
+            "universal": (lambda: _build_templates().get("AI_INSTRUCTIONS.md", ""), "html"),
+        }
+        updated_manifest = {}
+        for fpath, info in manifest_data.items():
+            tool = info.get("tool", "unknown")
+            marker_style = _MARKER_STYLE_FOR_TOOL.get(tool, "html")
+            if dry_run:
+                print(f"    → {fpath} [{tool}]")
+                continue
+            if tool in _tool_content_builders:
+                builder, _ = _tool_content_builders[tool]
+                content = builder()
+            else:
+                templates = _build_templates()
+                content = templates.get(os.path.basename(fpath), "")
+            _write_instruction_file(fpath, tool, content, marker_style)
+            if os.path.exists(fpath):
+                section = _extract_synlynk_section(open(fpath).read(), marker_style)
+                if section:
+                    updated_manifest[fpath] = {"tool": tool, "sha": _compute_section_sha(section)}
+            print(f"    {_GREEN}✓{_RESET} {fpath} [{tool}]")
+        if not dry_run and updated_manifest:
+            _write_instruction_manifest(updated_manifest)
+
+    # --- agent profiles ---
+    print("  Agent profiles (.agents/):")
+    try:
+        cfg = load_config()
+    except Exception:
+        cfg = {}
+    slots = cfg.get("agent_slots", {})
+    if not slots:
+        print(f"    {_DIM}no agent slots in config{_RESET}")
+    else:
+        os.makedirs(".agents", exist_ok=True) if not dry_run else None
+        for name in slots:
+            profile_path = os.path.join(".agents", f"{name}.json")
+            if os.path.exists(profile_path):
+                print(f"    {_DIM}· {profile_path} already present — skipped{_RESET}")
+                continue
+            print(f"    {'→' if dry_run else _GREEN + '✓' + _RESET} {profile_path} — create default profile")
+            if not dry_run:
+                profile = _load_agent_profile(name)
+                os.makedirs(".agents", exist_ok=True)
+                with open(profile_path, "w") as f:
+                    json.dump(profile, f, indent=2)
+                    f.write("\n")
+
+    print()
+    if dry_run:
+        print(f"  Dry run complete. Run with {_CYAN}--confirm{_RESET} to apply.")
+    else:
+        print(f"  {_GREEN}Sync complete.{_RESET}")
+    print()
+
+    if repair_sops:
+        _repair_sops_only(load_config(), dry_run=dry_run)
+
+    return 0
+
+
+
+
+
+
+
+
+
+
+
+def _check_agent_functional(cli: str) -> Optional[str]:
+    """Runs `<cli> --version` to confirm CLI is installed and executable.
+
+    Returns version string (stdout stripped) on success, None otherwise.
+    """
+    try:
+        result = subprocess.run(
+            [cli, "--version"],
+            capture_output=True, text=True, timeout=5
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip().splitlines()[0]
+        return None
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return None
+
+
+def discover_agents(config: dict = None) -> list:
+    """Scans for installed harness CLIs and checks each is functional.
+
+    Returns list of dicts: {name, cli, version, functional, capabilities,
+    roles, discovery_path}.
+    Agents not found on disk are omitted. Agents found but failing --version
+    are included with functional=False.
+    """
+    if config is None:
+        config = load_config()
+
+    # Allow per-project overrides of discovery paths.
+    discovery_paths = {**AGENT_DISCOVERY_DEFAULTS}
+    discovery_paths.update(config.get("agent_discovery_paths", {}))
+
+    found = []
+    for name, defaults in HARNESS_CAPABILITY_BASELINES.items():
+        path = discovery_paths.get(name)
+        if path and not os.path.exists(path):
+            continue  # config dir not present — skip entirely
+        cli = defaults["cli"]
+        version = _check_agent_functional(cli)
+        found.append({
+            "name": name,
+            "cli": cli,
+            "version": version,
+            "functional": version is not None,
+            "roles": defaults["roles"],
+            "capabilities": defaults["strengths"],
+            "non_interactive_flags": defaults["non_interactive_flags"],
+            "discovery_path": path or "",
+        })
+    return found
+
+
+def probe_all_configured_harnesses(agents: list = None) -> dict:
+    """Populate probe metadata for the harnesses selected for this workspace."""
+    configured = list(agents) if agents is not None else []
+    if agents is None:
+        config = load_config()
+        configured = list(config.get("workgroup_agents") or [])
+    if agents is None and not configured:
+        configured = [entry["name"] for entry in discover_agents() if entry.get("functional")]
+    configured = list(dict.fromkeys(
+        name for name in configured if name in HARNESS_CAPABILITY_BASELINES
+    ))
+    results = {}
+    if not configured:
+        return results
+
+    from synlynk.probe import _probe_agent
+
+    db_conn = _get_db()
+    try:
+        for harness_name in configured:
+            try:
+                results[harness_name] = _probe_agent(
+                    harness_name, db_conn, fast_path_ok=False, write_fence=False
+                )
+            except Exception as exc:
+                results[harness_name] = {
+                    "status": "unavailable",
+                    "version": "unavailable",
+                    "error": str(exc),
+                }
+        db_conn.commit()
+    finally:
+        db_conn.close()
+    return results
+
+
+
+
+_INDUSTRY_KEYWORDS = {
+    "ott": ["ott", "over-the-top", "streaming service", "video platform"],
+    "streaming": ["streaming", "live stream", "media delivery"],
+    "fintech": ["fintech", "financial", "payment", "trading", "investment"],
+    "banking": ["banking", "bank", "loan", "mortgage", "deposit"],
+    "securities": ["securities", "stock", "equity", "portfolio", "brokerage"],
+    "healthcare": ["healthcare", "medical", "patient", "clinical", "health"],
+    "ecommerce": ["ecommerce", "e-commerce", "shop", "cart", "marketplace"],
+    "edtech": ["edtech", "education", "learning", "course", "student"],
+    "gaming": ["gaming", "game", "player", "leaderboard", "matchmaking"],
+}
+
+
+
+_STACK_FINGERPRINTS = [
+    ("pyproject.toml", "Python"),
+    ("setup.py", "Python"),
+    ("Cargo.toml", "Rust"),
+    ("go.mod", "Go"),
+    ("next.config.js", "Next.js"),
+    ("next.config.ts", "Next.js"),
+    ("next.config.mjs", "Next.js"),
+    ("Pulumi.yaml", "Pulumi"),
+    ("Pulumi.yml", "Pulumi"),
+    ("Dockerfile", "Docker"),
+    ("docker-compose.yml", "Docker"),
+    ("docker-compose.yaml", "Docker"),
+]
+
+_STACK_EXT_MAP = {
+    ".go": "Go",
+    ".rs": "Rust",
+}
+
+
+
+
+
+
+_KNOWN_SKILL_PATTERNS = [
+    "~/.claude/plugins/cache/superpowers-marketplace/superpowers/*/",
+    "~/.config/gstack/plugins/*/",
+]
+_SKILL_MANIFEST_NAMES = ("manifest.json", "package.json", "skill.json")
+
+
+
+
+
+
+
+
+_MONOREPO_MARKERS = ("packages", "apps", "services", "modules", "libs")
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+STAGE_KEYS = ["stack", "source", "complexity", "tests", "git", "arch"]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+def cmd_agent_configure(agent_name: str) -> None:
+    """Interactively write .agents/<agent_name>.json context-profile settings."""
+    import json as _json
+
+    if agent_name not in HARNESS_CAPABILITY_BASELINES:
+        print(f"  Unknown agent '{agent_name}'. Known: {list(HARNESS_CAPABILITY_BASELINES)}")
+        return
+
+    harnesses_dir = ".harnesses" if os.path.exists(".harnesses") or not os.path.exists(".agents") else ".agents"
+    os.makedirs(harnesses_dir, exist_ok=True)
+    path = os.path.join(harnesses_dir, f"{agent_name}.json")
+
+    existing = {}
+    if os.path.exists(path):
+        try:
+            with open(path) as f:
+                existing = _json.load(f)
+            print(f"  Existing profile at {path}:")
+            for key, value in existing.items():
+                print(f"    {key}: {value}")
+        except Exception:
+            existing = {}
+
+    print(f"\n  Configuring context profile for '{agent_name}' (press Enter to keep current)\n")
+
+    def _ask(default, desc):
+        shown = "" if default is None else str(default)
+        value = input(f"  {desc} [{shown}]: ").strip()
+        return value if value else default
+
+    context_mode = _ask(existing.get("context_mode", "task"),
+                        "context_mode (none / task / full)")
+    max_bytes_raw = _ask(existing.get("context_max_bytes", None),
+                         "context_max_bytes (int, leave blank for no limit)")
+
+    profile = {
+        "agent": agent_name,
+        "harness": existing.get("harness", agent_name),
+        "model": existing.get("model", "unknown"),
+        "context_mode": context_mode,
+    }
+    if max_bytes_raw not in ("", None):
+        try:
+            profile["context_max_bytes"] = int(max_bytes_raw)
+        except (TypeError, ValueError):
+            pass
+
+    with open(path, "w") as f:
+        _json.dump(profile, f, indent=2)
+        f.write("\n")
+    print(f"\n  {_GREEN}✓{_RESET} Written {path}")
+
+
+def cmd_agent_add(agent_name: str) -> None:
+    """Retrofit an on-PATH harness into the current project."""
+    if agent_name not in HARNESS_CAPABILITY_BASELINES:
+        print(f"  Error: unknown agent '{agent_name}'. Known: {', '.join(sorted(HARNESS_CAPABILITY_BASELINES))}")
+        return
+
+    cli_path = shutil.which(agent_name)
+    if not cli_path:
+        print(f"  Error: agent binary '{agent_name}' is not on PATH.")
+        return
+
+    config_path = ".synlynk/config.json"
+    config = load_config()
+    workgroup_agents = list(config.get("workgroup_agents") or [])
+    directive_path = _directive_file_for_agent(agent_name)
+    fence_present = _fence_exists(directive_path)
+
+    if agent_name in workgroup_agents and fence_present:
+        print(f"  {agent_name} is already fully onboarded — no changes made.")
+        return
+
+    created_directive = False
+    if not os.path.exists(directive_path):
+        templates = _build_templates()
+        template_body = templates.get(os.path.basename(directive_path), "")
+        if not template_body:
+            template_body = f"# synlynk {agent_name} instructions\n"
+        with open(directive_path, "w") as f:
+            f.write(template_body.rstrip("\n") + "\n")
+        created_directive = True
+
+    probe_results = cmd_probe(agent_name, write_fence=False) or []
+    probe_result = probe_results[0] if probe_results else {}
+
+    role_list = _default_roles_for_agent(agent_name)
+    _upsert_harness_fence(
+        directive_path,
+        harness_version="roles",
+        body=f"## Your Role\n{', '.join(role_list) if role_list else 'general'}\n",
+    )
+
+    if agent_name not in workgroup_agents:
+        workgroup_agents.append(agent_name)
+
+    agent_slots = dict(config.get("agent_slots") or {})
+    agent_slots[agent_name] = agent_name
+
+    roles = dict(config.get("roles") or {})
+    if not roles.get(agent_name):
+        roles[agent_name] = role_list
+
+    config["workgroup_agents"] = workgroup_agents
+    config["agent_slots"] = agent_slots
+    config["roles"] = roles
+    _write_json_atomic(config_path, config)
+
+    print(f"  {_GREEN}✓{_RESET} added {agent_name} to workgroup_agents")
+    print(f"  {_GREEN}✓{_RESET} added {agent_name} to agent_slots")
+    if created_directive:
+        print(f"  {_GREEN}✓{_RESET} created {directive_path} from template")
+    else:
+        print(f"  {_GREEN}✓{_RESET} updated {directive_path}")
+    print(f"  {_GREEN}✓{_RESET} wrote role fence to {directive_path}")
+    if probe_result:
+        status = "skipped (up to date)" if probe_result.get("skipped") else probe_result.get("status", "unknown")
+        print(f"  {_GREEN}✓{_RESET} probe [{agent_name}] {probe_result.get('version', 'unknown')} → {status}")
+    print(f"  {_GREEN}✓{_RESET} onboarded {agent_name} from {cli_path}")
+
+
+cmd_harness_add = cmd_agent_add
+cmd_harness_configure = cmd_agent_configure
+
+
+
+def _run_daily_housekeeping() -> None:
+    """Run the once-per-day drift check triggered by exec flow."""
+    workspace_path = ".synlynk/workspace.json"
+    legacy_path = ".synlynk/config.json"
+    if not os.path.exists(workspace_path) and not os.path.exists(legacy_path):
+        return
+
+    config = load_config()
+    today = time.strftime("%Y-%m-%d")
+    if config.get("last_housekeeping_date") == today:
+        return
+
+    workgroup_agents = [a for a in (config.get("workgroup_agents") or []) if a in HARNESS_CAPABILITY_BASELINES]
+    known_on_path = {
+        harness["name"]
+        for harness in _detect_harnesses_on_path()
+        if harness.get("name") in HARNESS_CAPABILITY_BASELINES
+    }
+    onboarded = set(workgroup_agents)
+    new_agents = sorted(known_on_path - onboarded)
+
+    printed = False
+    for agent_name in new_agents:
+        print(f"  New agent detected on PATH: {agent_name} — run `synlynk agent add {agent_name}` to onboard it")
+        printed = True
+
+    db_conn = None
+    try:
+        if workgroup_agents:
+            db_conn = _get_db()
+        for agent_name in workgroup_agents:
+            try:
+                before = db_conn.execute(
+                    "SELECT installed_version, capability_hash FROM harness_records WHERE harness_name=?",
+                    (agent_name,),
+                ).fetchone()
+                result = _probe_agent(agent_name, db_conn, write_fence=False)
+                after = db_conn.execute(
+                    "SELECT installed_version, capability_hash FROM harness_records WHERE harness_name=?",
+                    (agent_name,),
+                ).fetchone()
+            except Exception as exc:
+                print(f"  Housekeeping probe failed for {agent_name}: {exc}")
+                printed = True
+                continue
+            if before != after:
+                before_version = before[0] if before else "none"
+                after_version = after[0] if after else result.get("version", "unknown")
+                status = result.get("status", "unknown")
+                print(f"  Probe drift for {agent_name}: {before_version} → {after_version} ({status})")
+                baseline = HARNESS_CAPABILITY_BASELINES.get(agent_name)
+                if baseline is not None:
+                    baseline["last_probe_snapshot"] = {
+                        "installed_version": after_version,
+                        "capability_hash": after[1] if after else "",
+                        "status": status,
+                    }
+                printed = True
+            try:
+                _repair_sops_only(harness_name=agent_name, dry_run=False)
+            except Exception as exc:
+                print(f"  Housekeeping repair failed for {agent_name}: {exc}")
+                printed = True
+    finally:
+        if db_conn is not None:
+            db_conn.close()
+
+    config["last_housekeeping_date"] = today
+    if os.path.exists(workspace_path):
+        workspace_data = load_workspace()
+        workspace_data["last_housekeeping_date"] = today
+        _write_json_atomic(workspace_path, workspace_data)
+    else:
+        _write_json_atomic(legacy_path, config)
+
+    if not printed:
+        return
+
+
+def cmd_configure_agent(
+    name: str,
+    flags: dict = None,
+    envs: dict = None,
+    network_deps: list = None,
+) -> None:
+    """Write per-project harness overrides to .agents/<name>.json."""
+    flags = flags or {}
+    envs = envs or {}
+    network_deps = network_deps or []
+
+    os.makedirs(".agents", exist_ok=True)
+    profile_path = os.path.join(".agents", f"{name}.json")
+    profile: dict = {}
+    if os.path.exists(profile_path):
+        try:
+            with open(profile_path) as f:
+                profile = json.load(f)
+        except (json.JSONDecodeError, OSError):
+            profile = {}
+
+    overrides = profile.setdefault(
+        "harness_overrides",
+        {"dispatch_flags": {}, "env": {}, "network_deps": []},
+    )
+    overrides.setdefault("dispatch_flags", {})
+    overrides.setdefault("env", {})
+    overrides.setdefault("network_deps", [])
+
+    overrides["dispatch_flags"].update(flags)
+    overrides["env"].update(envs)
+    for dep in network_deps:
+        if dep not in overrides["network_deps"]:
+            overrides["network_deps"].append(dep)
+
+    with open(profile_path, "w") as f:
+        json.dump(profile, f, indent=2)
+        f.write("\n")
+
+    print(f"  ✓ {name}: harness overrides written to {profile_path}")
+    if flags:
+        print(f"    flags: {flags}")
+    if envs:
+        print(f"    env:   {envs}")
+    if network_deps:
+        print(f"    deps:  {network_deps}")
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+def cmd_shell(story_id: str = None) -> None:
+    """Spawns an interactive subshell with synlynk context env vars injected.
+
+    The shell runs in the current directory (worktree-per-story lands in v0.5.0).
+    On exit the calling process resumes normally.
+    """
+    shell = os.environ.get("SHELL", "/bin/bash")
+    env = {**os.environ,
+           "SYNLYNK_PROJECT_DIR": os.path.abspath("."),
+           "SYNLYNK_STORY_ID": story_id or "",
+           "SYNLYNK_CONTEXT": os.path.abspath(".synlynk/context.md")}
+    label = f"story #{story_id}" if story_id else "synlynk"
+    print(f"{_BOLD}Entering synlynk shell ({label}).{_RESET} "
+          f"Type {_CYAN}exit{_RESET} to return.")
+    subprocess.run([shell], env=env)
+    print(f"{_DIM}Returned from synlynk shell.{_RESET}")
+
+
+def cmd_launch(agent: str, story_id: str = None) -> None:
+    """Launches a harness CLI interactively in the current directory.
+
+    Pre-generates .synlynk/context-<agent>.md and starts the CLI so the
+    agent reads it as initial context. Stdout/stderr are not captured —
+    this is an interactive session. Telemetry is logged on exit.
+    """
+    if agent not in HARNESS_CAPABILITY_BASELINES:
+        print(f"Unknown agent '{agent}'. Known: {list(HARNESS_CAPABILITY_BASELINES)}")
+        return
+
+    cli = HARNESS_CAPABILITY_BASELINES[agent]["cli"]
+
+    try:
+        generate_context(scope="full")
+    except Exception:
+        pass
+    src = ".synlynk/context.md"
+    dest = f".synlynk/context-{agent}.md"
+    if os.path.exists(src):
+        import shutil as _shutil
+        _shutil.copy(src, dest)
+
+    label = f"story #{story_id}" if story_id else "interactive session"
+    print(f"{_BOLD}Launching {agent} — {label}.{_RESET}")
+    print(f"  Context: {_CYAN}{dest}{_RESET}")
+    print(f"  Exit the agent to return to synlynk.\n")
+
+    start = time.time()
+    result = subprocess.run([cli])
+    duration = time.time() - start
+
+    log_telemetry_event({"type": "launch", "agent": agent,
+                         "story_id": story_id, "exit_code": result.returncode,
+                         "duration_s": round(duration, 1)})
+    model_version = extract_model_version("", agent=agent)
+    update_costs(
+        cli,
+        0,
+        0,
+        duration,
+        cache_read_tokens=0,
+        model_version=model_version,
+        story_id=story_id,
+        agent=agent,
+        basis="none",
+    )
+    print(f"\n{_DIM}Returned from {agent}. Duration: {duration:.0f}s{_RESET}")
+
+
+
+
+def cmd_run_trio(task: str, story_id: str = None) -> None:
+    """Dispatches all functional harnesses in parallel — one job per harness.
+
+    This is a parallel convenience wrapper, NOT the sequential Trio pipeline.
+    Each agent gets the same task description and full context. For the
+    sequential Architect→Build→Verify pipeline, see the Trio Protocol spec.
+    """
+    agents = [a for a in discover_agents() if a["functional"]]
+    if not agents:
+        print("No functional agents found. Synlynk is a neutral control plane that routes coding tasks across AI vendors and local models, then proves the result. Run `synlynk init` to configure an agent.")
+        return
+    if len(agents) < 3:
+        print(f"  {_YELLOW}Only {len(agents)} agent(s) available "
+              f"(trio needs 3). Dispatching what's configured.{_RESET}")
+
+    print(f"{_BOLD}✨ Dispatching {len(agents)} agents in parallel{_RESET}")
+    print(f"  Task: {task}\n")
+
+    jobs = []
+    for ag in agents:
+        job = dispatch_agent(ag["name"], task, story_id=story_id)
+        jobs.append(job)
+        role = ag["roles"][0] if ag["roles"] else "worker"
+        print(f"  {_GREEN}▶{_RESET} [{job['id']}] {ag['name']:10} → {role}  PID {job['pid']}")
+
+    print(f"\n  {_DIM}All agents running in background.{_RESET}")
+    print(f"  Monitor with: {_CYAN}synlynk jobs{_RESET}")
+    print(f"  View output:  {_CYAN}synlynk logs <job-id>{_RESET}")
+
+
+def set_state(state: str) -> None:
+    """Writes synlynk state to .synlynk/state and updates terminal title."""
+    icons = {"watching": "●", "active": "⚡", "stopped": "○"}
+    state_file = ".synlynk/state"
+    if not os.path.exists(".synlynk"):
+        return
+    with open(state_file, "w") as f:
+        f.write(state)
+    if sys.stdout.isatty():
+        project = os.path.basename(os.getcwd())
+        title = f"{icons.get(state, '○')} synlynk: {state}  ·  {project}"
+        sys.stdout.write(f"\033]0;{title}\007")
+        sys.stdout.flush()
+
+def detect_remote_owner_repo() -> tuple:
+    """Returns (owner, repo) from git remote origin URL, or (None, None)."""
+    try:
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True, text=True
+        )
+        if result.returncode != 0:
+            return None, None
+        url = result.stdout.strip().rstrip("/")
+        if url.endswith(".git"):
+            url = url[:-4]
+        if "github.com/" in url:
+            path = url.split("github.com/")[-1]
+        elif "github.com:" in url:
+            path = url.split("github.com:")[-1]
+        else:
+            return None, None
+        parts = path.split("/")
+        return (parts[0], parts[1]) if len(parts) >= 2 else (None, None)
+    except Exception:
+        return None, None
+
+
+def _update_config(updates: dict) -> None:
+    """Merges updates into the owning split config file(s) (workspace.json / billing.json / policy.json)."""
+    if not os.path.exists(".synlynk"):
+        return
+
+    workspace_updates = {}
+    billing_updates = {}
+    policy_updates = {}
+    for key, value in updates.items():
+        if key in _BILLING_KEYS:
+            billing_updates[key] = value
+        elif key in _POLICY_MIGRATED_KEYS:
+            policy_updates[key] = value
+        else:
+            workspace_updates[key] = value
+
+    if workspace_updates:
+        workspace_data = load_workspace()
+        workspace_data.update(workspace_updates)
+        _write_json_atomic(".synlynk/workspace.json", workspace_data)
+
+    if billing_updates:
+        billing_data = load_billing()
+        billing_data.update(billing_updates)
+        _write_json_atomic(".synlynk/billing.json", billing_data)
+
+    if policy_updates:
+        policy_data = _read_raw_policy()
+        policy_data.setdefault("schema_version", 1)
+        policy_data.update(policy_updates)
+        _write_json_atomic(".synlynk/policy.json", policy_data)
+
+
+# Task 3-5: Repo scanning, maturity detection, section signals, semantic matching, GH ID extraction
+_PROJECT_DOC_NAMES = {"roadmap.md", "todo.md", "memory.md", "costs.md", "devlog.md"}
+_AGENT_FILE_NAMES = {"CLAUDE.md", "GEMINI.md", "AGENTS.md", "GROK.md", "AI_INSTRUCTIONS.md"}
+_SCAN_SKIP_DIRS = {
+    ".git", "node_modules", ".synlynk", "project-docs",
+    "__pycache__", ".venv", "venv", "env", ".next", "dist", "build",
+    "vendor", ".worktrees", "coverage", ".nyc_output", "target", "out", "tmp",
+}
+
+_SOURCE_EXTENSIONS = {
+    ".py": "python",
+    ".js": "javascript", ".mjs": "javascript", ".cjs": "javascript",
+    ".ts": "typescript", ".tsx": "typescript",
+    ".go": "go",
+    ".rs": "rust",
+    ".rb": "ruby",
+    ".java": "java",
+    ".kt": "kotlin",
+    ".sh": "shell",
+}
+
+_SOURCE_ENTRY_POINTS = {
+    "main.py", "app.py", "server.py", "index.js", "index.ts", "main.go",
+    "lib.rs", "main.rs", "app.rb", "manage.py", "wsgi.py", "asgi.py", "__init__.py",
+}
+
+_SYMBOL_PATTERNS = {
+    "python": [
+        (re.compile(r"^async def (\w+)"), "async_function"),
+        (re.compile(r"^def (\w+)"), "function"),
+        (re.compile(r"^class (\w+)"), "class"),
+        (re.compile(r"^([A-Z_]{2,})\s*="), "constant"),
+    ],
+    "javascript": [
+        (re.compile(r"^export (?:default )?(?:async )?function (\w+)"), "function"),
+        (re.compile(r"^export (?:default )?class (\w+)"), "class"),
+        (re.compile(r"^export const (\w+)"), "constant"),
+        (re.compile(r"^function (\w+)"), "function"),
+        (re.compile(r"^class (\w+)"), "class"),
+    ],
+    "typescript": [
+        (re.compile(r"^export (?:default )?(?:async )?function (\w+)"), "function"),
+        (re.compile(r"^export (?:default )?class (\w+)"), "class"),
+        (re.compile(r"^export interface (\w+)"), "interface"),
+        (re.compile(r"^export type (\w+)"), "type"),
+        (re.compile(r"^export enum (\w+)"), "enum"),
+        (re.compile(r"^export const (\w+)"), "constant"),
+        (re.compile(r"^function (\w+)"), "function"),
+        (re.compile(r"^class (\w+)"), "class"),
+    ],
+    "go": [
+        (re.compile(r"^func (?:\(\w+ \*?\w+\) )?(\w+)"), "function"),
+        (re.compile(r"^type (\w+) struct"), "struct"),
+        (re.compile(r"^type (\w+) interface"), "interface"),
+    ],
+    "rust": [
+        (re.compile(r"^pub fn (\w+)"), "function"),
+        (re.compile(r"^pub struct (\w+)"), "struct"),
+        (re.compile(r"^pub trait (\w+)"), "trait"),
+        (re.compile(r"^pub enum (\w+)"), "enum"),
+        (re.compile(r"^pub type (\w+)"), "type"),
+    ],
+    "ruby": [
+        (re.compile(r"^def (\w+)"), "function"),
+        (re.compile(r"^class (\w+)"), "class"),
+        (re.compile(r"^module (\w+)"), "module"),
+    ],
+    "java": [
+        (re.compile(r"(?:public|protected) (?:class|interface|enum) (\w+)"), "class"),
+        (re.compile(r"(?:public|protected) \w+ (\w+)\s*\("), "function"),
+    ],
+    "kotlin": [
+        (re.compile(r"^fun (\w+)"), "function"),
+        (re.compile(r"^class (\w+)"), "class"),
+        (re.compile(r"^object (\w+)"), "class"),
+        (re.compile(r"^interface (\w+)"), "interface"),
+    ],
+    "shell": [
+        (re.compile(r"^function (\w+)"), "function"),
+        (re.compile(r"^(\w+)\(\)"), "function"),
+    ],
+}
+
+SECTION_SIGNALS: dict = {
+    "## Live Issues SOP": [
+        "live issue", "live-issue", "sev1", "sev2", "sev3", "rca", "[live-",
+    ],
+    "## Mid-Session Anti-Amnesia Protocol": [
+        "25,000 tokens", "25k tokens", "compaction", "compaction imminent",
+        "mid-session", "checkpoint every",
+    ],
+    "## Mandatory 4-Doc Discipline": [
+        "roadmap.md", "devlog", "costs.md", "memory.md",
+        "mandatory document", "four doc", "4-doc",
+    ],
+    "## GitHub Projects v2 Integration": [
+        "updateProjectV2", "projectId", "PVT_", "PVTSSF_",
+        "github projects", "programme board",
+    ],
+    "## Git Worktree-First Policy": [
+        "git worktree", "worktree add", "never commit to main",
+        "never commit to master",
+    ],
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+_INSTRUCTIONS_MANIFEST = ".synlynk/instructions.json"
+
+_INSTRUCTION_TARGETS = [
+    # (path, tool, marker_style, detection_fn)
+    # detection_fn: called in init() to decide whether to write the file.
+    ("CLAUDE.md",                          "claude",    "html", lambda: True),
+    ("GEMINI.md",                          "agy",       "html", lambda: True),
+    ("AGENTS.md",                          "codex",     "html", lambda: True),
+    ("GROK.md",                            "grok",      "html", lambda: True),
+    (".cursor/rules/synlynk.mdc",          "cursor",    "none", lambda: os.path.isdir(".cursor")),
+    (".github/copilot-instructions.md",    "copilot",   "html", lambda: os.path.isdir(".github")),
+    (".windsurfrules",                     "windsurf",  "hash", lambda: True),
+    ("AI_INSTRUCTIONS.md",                 "universal", "html", lambda: True),
+]
+
+
+
+
+
+_MARKER_STYLE_FOR_TOOL = {
+    "claude":    "html",
+    "agy":       "html",
+    "codex":     "html",
+    "grok":      "html",
+    "cursor":    "none",
+    "copilot":   "html",
+    "windsurf":  "hash",
+    "universal": "html",
+}
+
+
+
+
+
+
+
+
+
+
+
+
+def _is_interactive(cmd_args: list) -> bool:
+    """Returns True if the command needs a real TTY (no stdout capture)."""
+    NON_INTERACTIVE = ["--no-tty", "--output-format json", "--print",
+                       "--non-interactive", "-p "]
+    cmd_str = " ".join(cmd_args)
+    return not any(flag in cmd_str for flag in NON_INTERACTIVE)
+
+
+def _inject_grok_rules(cmd_args: list) -> list:
+    """Adds Grok rules flags when invoking grok and the rule files exist."""
+    if not cmd_args or cmd_args[0] != "grok":
+        return list(cmd_args)
+
+    injected = [cmd_args[0]]
+    if os.path.exists("GROK.md"):
+        injected.extend(["--rules", "GROK.md"])
+    if "-p" in cmd_args and os.path.exists(os.path.join(".synlynk", "context.md")):
+        injected.extend(["--rules", os.path.join(".synlynk", "context.md")])
+    injected.extend(cmd_args[1:])
+    return injected
+
+
+def _tee_process(process, buffer: list) -> None:
+    """Reads process stdout line-by-line, writes to terminal and appends to buffer."""
+    for line in iter(process.stdout.readline, b''):
+        sys.stdout.buffer.write(line)
+        sys.stdout.buffer.flush()
+        buffer.append(line.decode('utf-8', errors='replace'))
+    process.stdout.close()
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+def _archive_old_devlog_entries(devlog_path: str, author: str) -> None:
+    """Moves devlog entries older than 30 days to devlogs/archive/YYYY-MM.md."""
+    import calendar
+    if not os.path.exists(devlog_path):
+        return
+    cutoff = time.time() - (30 * 24 * 3600)
+    pattern = re.compile(r'^## (\d{4}-\d{2}-\d{2})')
+    sections = []
+    current_lines, current_date = [], None
+    with open(devlog_path) as f:
+        for line in f:
+            m = pattern.match(line)
+            if m:
+                if current_lines:
+                    sections.append((current_date, current_lines))
+                current_date = m.group(1)
+                current_lines = [line]
+            else:
+                current_lines.append(line)
+    if current_lines:
+        sections.append((current_date, current_lines))
+
+    keep, archive_by_month, archived_dates = [], {}, []
+    for date_str, lines in sections:
+        if date_str is None:
+            keep.append((date_str, lines))
+            continue
+        try:
+            ts = calendar.timegm(time.strptime(date_str, "%Y-%m-%d"))
+            if ts < cutoff:
+                month_key = date_str[:7]
+                archive_by_month.setdefault(month_key, []).extend(lines)
+                archived_dates.append(date_str)
+            else:
+                keep.append((date_str, lines))
+        except ValueError:
+            keep.append((date_str, lines))
+
+    if not archive_by_month:
+        return
+
+    archive_dir = os.path.join(os.path.dirname(devlog_path), "archive")
+    os.makedirs(archive_dir, exist_ok=True)
+    for month_key, lines in archive_by_month.items():
+        with open(os.path.join(archive_dir, f"{month_key}.md"), "a") as f:
+            f.writelines(lines)
+
+    with open(devlog_path, "w") as f:
+        for _, lines in keep:
+            f.writelines(lines)
+
+    conn = _get_db()
+    conn.executemany(
+        "DELETE FROM devlog_entries WHERE author=? AND entry_date=?",
+        [(author, date_str) for date_str in archived_dates],
+    )
+    conn.commit()
+    conn.close()
+
+def _resolve_member_id(username: str) -> str:
+    """Looks up username in the member_aliases registry; falls back to username
+    itself when unregistered (matches audit-docs' "unregistered" finding — an
+    unregistered identity is reported, never silently reassigned)."""
+    try:
+        conn = _get_db()
+        row = conn.execute(
+            "SELECT member_id FROM member_aliases WHERE alias = ?", (username,)
+        ).fetchone()
+        conn.close()
+        return row[0] if row else username
+    except Exception:
+        return username
+
+
+def checkpoint() -> None:
+    """Archives done tasks, refreshes context, and emits a telemetry event."""
+    set_state("active")
+    _check_upstream_divergence()
+    username = get_username()
+    canonical_id = _resolve_member_id(username)
+    if _is_migrated():
+        devlog_path = os.path.join(_synlynk_project_docs_dir(), "devlogs", f"{canonical_id}.md")
+        docs_dir = _synlynk_project_docs_dir()
+    else:
+        devlog_path = os.path.join(_docs_dir(), "devlogs", f"{canonical_id}.md")
+        docs_dir = _docs_dir()
+
+    # Legacy projects may have a hand-written todo.md but no story rows yet.
+    # Import it once before checkpointing so the database remains the source of truth.
+    conn = _get_db()
+    story_count = conn.execute("SELECT COUNT(*) FROM stories").fetchone()[0]
+    if story_count == 0:
+        _import_todo_to_stories(docs_dir, conn=conn)
+        conn.commit()
+
+    resolved_rows = conn.execute(
+        "SELECT story_id, title FROM stories "
+        "WHERE archived_at IS NULL AND status IN ('done', 'superseded', 'absorbed') "
+        "ORDER BY created_at ASC, id ASC"
+    ).fetchall()
+    completed = [{"id": story_id, "text": title or story_id} for story_id, title in resolved_rows]
+    if resolved_rows:
+        archived_at = time.strftime('%Y-%m-%d %H:%M:%S')
+        conn.executemany(
+            "UPDATE stories SET archived_at=? WHERE story_id=? AND archived_at IS NULL",
+            [(archived_at, story_id) for story_id, _ in resolved_rows],
+        )
+    conn.commit()
+    conn.close()
+
+    # Write resolved tasks through to the devlog (DB row + regenerated flat file)
+    if completed:
+        body_lines = ["### Resolved (checkpoint)"]
+        for task in completed:
+            body_lines.append(f"- {task['text']}")
+        cmd_devlog_append(canonical_id, time.strftime('%Y-%m-%d'), "\n".join(body_lines) + "\n")
+    if resolved_rows:
+        _generate_todo_md()
+
+    _archive_old_devlog_entries(devlog_path, canonical_id)
+    if os.path.exists(devlog_path):
+        try:
+            with open(devlog_path, "r", encoding="utf-8") as _df:
+                _devlog_text = _df.read()
+            _discovered = extract_from_devlog_content(_devlog_text, author=canonical_id)
+            for _d in _discovered:
+                stage_discovered_work(
+                    title=_d["title"],
+                    description=_d.get("description", ""),
+                    role=_d.get("role", "dev"),
+                    stage=_d.get("stage", "open"),
+                    source_type=_d.get("source_type", "devlog"),
+                    source_ref=_d.get("source_ref", f"devlog:{canonical_id}"),
+                )
+        except Exception:
+            pass
+    generate_context()
+
+    completed_ids = [t["id"] for t in completed if t["id"]]
+    log_telemetry_event({
+        "type": "checkpoint",
+        "schema_version": 1,
+        "timestamp": time.strftime('%Y-%m-%d %H:%M:%S'),
+        "user": username,
+        "completed_task_count": len(completed),
+        "completed_task_ids": completed_ids,
+        "devlog_entry_appended": bool(completed),
+    })
+
+    total_usd, total_requests = parse_costs_md()
+    config = load_config()
+    limit_usd = config["budget"]["limit_usd"]
+    pct = (total_usd / limit_usd * 100) if limit_usd else 0
+
+    daemon = WatchDaemon()
+    set_state("watching" if daemon._is_running() else "stopped")
+
+    print(f"\n✓ checkpoint [@{username}] — {len(completed)} tasks archived, context refreshed")
+    if completed:
+        names = "  ·  ".join(f'"{t["text"][:40]}"' for t in completed[:3])
+        print(f"  Archived: {names}")
+    print(f"  Budget: ${total_usd:.2f} / ${limit_usd:.2f} ({pct:.0f}%)  ·  {total_requests} requests")
+
+def _mark_roadmap_arc_shipped(version: str) -> None:
+    """Flip a roadmap arc to shipped and sync its Milestone closed."""
+    conn = _get_db()
+    try:
+        conn.execute(
+            "UPDATE roadmap_arcs SET status='shipped' WHERE version=?", (version,)
+        )
+        conn.commit()
+    finally:
+        conn.close()
+    _try_sync_arc_by_version(version)
+
+
+def cmd_release(
+    dry_run: bool = False,
+    version: Optional[str] = None,
+    bump: bool = False,
+    minor: bool = False,
+    role: str = "pm",
+    check_docs: bool = False,
+    pr_mode: bool = False,
+    waive: Optional[list] = None,
+) -> None:
+    """Cut a named release: bump version, prepend CHANGELOG.md, write blog stub, print checklist."""
+    import datetime
+    import re
+    from synlynk.policy import check_authority
+    from synlynk.release_readme import (
+        format_readme_check_report,
+        parse_waivers,
+        validate_readme_for_release,
+    )
+
+    try:
+        waivers = parse_waivers(waive)
+    except ValueError as exc:
+        raise RuntimeError(str(exc)) from exc
+
+    if not check_docs:
+        authority = check_authority("release_cut", role=role, repo_path=os.getcwd())
+        if not authority.allowed:
+            raise RuntimeError(f"Release refused: role {role!r} is not authorized to cut a release per policy.json.")
+
+    # Resolve project root:
+    # First priority: check if a VERSION file exists in CWD. If so, root is CWD.
+    if os.path.exists(os.path.join(os.getcwd(), "VERSION")):
+        root = os.getcwd()
+    else:
+        root = _get_project_root()
+
+    version_path = os.path.join(root, "VERSION")
+    changelog_path = os.path.join(root, "CHANGELOG.md")
+    blog_dir = os.path.join(root, "docs", "blog")
+
+    # Step a: Determine next version
+    current_version = ""
+    if version:
+        next_version = version
+    else:
+        # read current VERSION file
+        if os.path.exists(version_path):
+            with open(version_path, "r") as f:
+                current_version = f.read().strip()
+        else:
+            current_version = "0.10.0"
+        
+        # parse current_version
+        parts = current_version.split(".")
+        if len(parts) >= 3:
+            try:
+                major = int(parts[0])
+                minor_ver = int(parts[1])
+                patch = int(parts[2].split("-")[0].split("+")[0]) # strip any prerelease suffix
+            except ValueError:
+                major, minor_ver, patch = 0, 10, 0
+        else:
+            major, minor_ver, patch = 0, 10, 0
+
+        if minor:
+            next_version = f"{major}.{minor_ver + 1}.0"
+        else:
+            next_version = f"{major}.{minor_ver}.{patch + 1}"
+
+    next_version = next_version.lstrip("v")
+    print(f"Proposed version: v{next_version}")
+
+    if check_docs and version is None and not minor:
+        expected_readme_version = current_version.lstrip("v")
+    else:
+        expected_readme_version = next_version
+
+    findings = validate_readme_for_release(
+        root, expected_readme_version, waivers=waivers, pr_mode=pr_mode
+    )
+    if findings and not check_docs:
+        print(f"⚡ [Marketing Ceremony] Auto-synchronizing README.md for v{expected_readme_version}...")
+        from synlynk.release_readme import collect_pytest_test_count, sync_readme_for_release
+        collected = collect_pytest_test_count(root)
+        sync_readme_for_release(root, expected_readme_version, collected_count=collected)
+        findings = validate_readme_for_release(
+            root, expected_readme_version, waivers=waivers, pr_mode=pr_mode
+        )
+
+    report = format_readme_check_report(
+        findings, expected_readme_version, waivers=waivers
+    )
+    print(report)
+    if check_docs:
+        from synlynk.release_authority import (
+            format_version_authority_report,
+            validate_release_authority,
+        )
+
+        authority_version, authority_findings = validate_release_authority(
+            root, expected_version=expected_readme_version
+        )
+        print(format_version_authority_report(authority_version, authority_findings))
+        findings.extend(authority_findings)
+    if findings:
+        if check_docs:
+            sys.exit(1)
+        raise RuntimeError(
+            "README is not synchronized for this named release. "
+            "Update README.md or re-run with --check-docs / --waive check=reason."
+        )
+    if check_docs:
+        return
+
+    # Execute marketing release ceremony across collateral
+    from synlynk.release_marketing import execute_release_ceremony
+    print(f"🚀 [Marketing Ceremony] Executing release ceremony for v{next_version}...")
+    ceremony_res = execute_release_ceremony(
+        root=root,
+        version=next_version,
+        dry_run=dry_run,
+        skip_build=False,
+    )
+    if not ceremony_res.ok:
+        print(f"⚠️ [Marketing Ceremony] Notice: {', '.join(ceremony_res.errors)}")
+    else:
+        print(f"✅ [Marketing Ceremony] Collateral synchronized (README, {len(ceremony_res.docs_updated)} docs bundles, website)")
+
+    # Step b: Read merged stories since last git tag
+    try:
+        tag_cmd = "git describe --tags --abbrev=0 2>/dev/null || echo ''"
+        last_tag = subprocess.check_output(tag_cmd, shell=True).decode("utf-8").strip()
+    except Exception:
+        last_tag = ""
+
+    if last_tag:
+        git_cmd = f"git log {last_tag}..HEAD --oneline"
+    else:
+        git_cmd = "git log -n 20 --oneline"
+
+    try:
+        log_output = subprocess.check_output(git_cmd, shell=True).decode("utf-8").strip()
+    except Exception:
+        log_output = ""
+
+    lines = log_output.splitlines() if log_output else []
+    added = []
+    fixed = []
+    changed = []
+
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        parts = line.split(" ", 1)
+        if len(parts) < 2:
+            continue
+        msg = parts[1].strip()
+        
+        match = re.match(r"^([a-zA-Z0-9_\-]+)(?:\(.*?\))?\s*:\s*(.*)", msg)
+        if match:
+            prefix = match.group(1).lower()
+        else:
+            prefix = ""
+
+        if prefix == "feat":
+            added.append(msg)
+        elif prefix == "fix":
+            fixed.append(msg)
+        else:
+            changed.append(msg)
+
+    # Step c: Build CHANGELOG entry
+    today = datetime.date.today().isoformat()
+    changelog_parts = [f"## [v{next_version}] - {today}"]
+    if added:
+        changelog_parts.append("### Added")
+        changelog_parts.extend(f"- {item}" for item in added)
+    if fixed:
+        changelog_parts.append("### Fixed")
+        changelog_parts.extend(f"- {item}" for item in fixed)
+    if changed:
+        changelog_parts.append("### Changed")
+        changelog_parts.extend(f"- {item}" for item in changed)
+    
+    changelog_entry = "\n".join(changelog_parts) + "\n\n"
+
+    # Step d: Build blog post stub
+    # Determine NN
+    next_nn = 0
+    if os.path.exists(blog_dir):
+        existing_numbers = []
+        for name in os.listdir(blog_dir):
+            if name.endswith(".md"):
+                match = re.match(r"^(\d+)-", name)
+                if match:
+                    existing_numbers.append(int(match.group(1)))
+        if existing_numbers:
+            next_nn = max(existing_numbers) + 1
+
+    nn_str = f"{next_nn:02d}"
+    blog_filename = f"{nn_str}-prTBD-v{next_version}.md"
+    blog_path = os.path.join(blog_dir, blog_filename)
+
+    # Read template from docs/blog/README.md if it exists
+    readme_path = os.path.join(blog_dir, "README.md")
+    template_content = None
+    if os.path.exists(readme_path):
+        try:
+            with open(readme_path, "r") as f:
+                readme_text = f.read()
+            h_idx = readme_text.find("## Per-PR Post Template")
+            if h_idx != -1:
+                sub = readme_text[h_idx:]
+                m_idx = sub.find("```markdown")
+                if m_idx != -1:
+                    start_idx = m_idx + len("```markdown")
+                    end_idx = sub.find("```", start_idx)
+                    if end_idx != -1:
+                        template_content = sub[start_idx:end_idx].strip()
+        except Exception:
+            pass
+
+    if not template_content:
+        template_content = """---
+title: "PR #N — <theme>"
+date: YYYY-MM-DD
+series: "Building the OS for Multi-Agent Development"
+post: N
+pr: "#N"
+merged: YYYY-MM-DD (or status: open)
+---
+
+## The Broader Goal at the End of the Previous PR
+[What was the stated/understood goal before this work started?]
+
+## Strategic Shifts in This PR (if any)
+[What changed in the broader strategy? What moved the goalpost and why?]
+
+## What This PR Shipped
+[Deep technical description: commands, key implementation decisions, data structures, test approach]
+
+## Brainstorm Visuals Used
+[Links to any HTML brainstorm files in docs/brainstorm/ that informed decisions in this PR]
+
+## What This Achieved on the Path to Autonomy
+[Specific ways this PR advances the eventual goal of autonomous multi-agent dispatch]
+
+## Strategic Note: The Goal at the End of This PR
+[The new goalpost, as understood after this PR's decisions]"""
+
+    stub_content = template_content
+    stub_content = stub_content.replace('title: "PR #N — <theme>"', f'title: "PR #TBD — v{next_version} Release"')
+    stub_content = stub_content.replace('date: YYYY-MM-DD', f'date: {today}')
+    stub_content = stub_content.replace('post: N', f'post: {next_nn}')
+    stub_content = stub_content.replace('pr: "#N"', 'pr: "#TBD"')
+    stub_content = stub_content.replace('merged: YYYY-MM-DD (or status: open)', 'status: open')
+    stub_content = stub_content.replace('merged: status' + ': open', 'status: open')
+
+    if dry_run:
+        # Step f: In dry-run mode, print everything but write nothing
+        print("\n--- Proposed CHANGELOG Entry ---")
+        print(changelog_entry.strip())
+        print("\n--- Proposed Blog Post Stub ---")
+        print(f"Path: docs/blog/{blog_filename}")
+        print(stub_content.strip())
+        print("\n--------------------------------")
+    else:
+        # Write the single canonical VERSION source.
+        with open(version_path, "w") as f:
+            f.write(next_version + "\n")
+
+        # Prepend to CHANGELOG.md (create if missing)
+        if os.path.exists(changelog_path):
+            with open(changelog_path, "r") as f:
+                old_content = f.read()
+            match = re.search(r"##\s*\[v?\d+\.\d+\.\d+\]", old_content)
+            if match:
+                idx = match.start()
+                new_changelog = old_content[:idx] + changelog_entry + "---\n\n" + old_content[idx:]
+            else:
+                idx = old_content.find("## ")
+                if idx != -1:
+                    new_changelog = old_content[:idx] + changelog_entry + "---\n\n" + old_content[idx:]
+                else:
+                    new_changelog = old_content + "\n\n" + changelog_entry
+        else:
+            new_changelog = "# Changelog\n\nAll notable changes to synlynk are documented here.\n\n" + changelog_entry
+            
+        with open(changelog_path, "w") as f:
+            f.write(new_changelog)
+
+        # Write blog post stub
+        os.makedirs(os.path.dirname(blog_path), exist_ok=True)
+        with open(blog_path, "w") as f:
+            f.write(stub_content + "\n")
+
+    # Step e: Print named release checklist
+    print(f"synlynk release checklist for v{next_version}")
+    print("[x] VERSION bumped")
+    print("[x] CHANGELOG entry written")
+    print(f"[x] Blog post stub: docs/blog/{blog_filename}")
+    print("[x] README synchronized (version, collected test-count not pass/fail, hero, install, links, commands)")
+    print("[x] Marketing Release Ceremony completed:")
+    print("    - [x] GitHub README synchronized")
+    print(f"    - [{'x' if ceremony_res.website_updated else ' '}] Synlynk.com website (website/) updated for release")
+    print(f"    - [{'x' if ceremony_res.docs_updated else ' '}] Synlynk Docs bundles synchronized: Quick Start, Official Reference, Command Ref (HTML & PDF)")
+    print(f"[ ] git tag v{next_version} && git push --tags")
+    print(f"[ ] gh release create v{next_version}")
+    if dry_run:
+        print(f"  [ ] Roadmap row would be marked shipped and Milestone closed — {next_version}")
+    else:
+        _mark_roadmap_arc_shipped(next_version)
+        print(f"  [x] Roadmap row marked shipped and Milestone closed — {next_version}")
+
+
+def cmd_marketing_ceremony(
+    version: Optional[str] = None,
+    dry_run: bool = False,
+    skip_build: bool = False,
+) -> None:
+    """Execute the Marketing Release Ceremony across README, docs bundles, and website."""
+    from synlynk.release_marketing import execute_release_ceremony
+
+    root = os.getcwd()
+    if not os.path.exists(os.path.join(root, "VERSION")):
+        try:
+            root = _get_project_root()
+        except Exception:
+            root = os.getcwd()
+
+    if not version:
+        version_file = os.path.join(root, "VERSION")
+        if os.path.isfile(version_file):
+            with open(version_file, "r", encoding="utf-8") as f:
+                version = f.read().strip()
+        else:
+            version = "0.20.0"
+
+    print(f"🚀 Executing Marketing Release Ceremony for v{version.lstrip('v')} (dry_run={dry_run})...")
+    res = execute_release_ceremony(
+        root=root,
+        version=version,
+        dry_run=dry_run,
+        skip_build=skip_build,
+    )
+    if not res.ok:
+        print(f"❌ Marketing Release Ceremony failed: {', '.join(res.errors)}")
+        sys.exit(1)
+
+    prefix = "[DRY-RUN] " if res.dry_run else ""
+    print(f"✅ {prefix}Marketing Release Ceremony completed successfully for v{res.version}.")
+    print(f"  - README updated: {res.readme_updated}")
+    print(f"  - Docs bundles updated: {len(res.docs_updated)} files ({', '.join(res.docs_updated) if res.docs_updated else 'none'})")
+    print(f"  - Website metadata updated: {res.website_updated}")
+    print(f"  - Website build ok: {res.website_build_ok}")
+
+
+def cmd_marketing_sync_pr(pr_number: Union[int, str], dry_run: bool = False) -> None:
+    """Executes the limited-treatment marketing sync for a merged pull request."""
+    from synlynk.marketing import cmd_marketing_sync_pr as _impl
+    return _impl(pr_number=pr_number, dry_run=dry_run)
+
+
+def cmd_status(json_output: bool = False, platform: bool = False) -> None:
+    """Displays project state dashboard. Exits 1 if sentinel active or budget exceeded."""
+    if platform:
+        has_alert = _print_platform_health()
+        sys.exit(1 if has_alert else 0)
+
+    username = get_username()
+    mode = get_mode()
+
+    # Active tasks
+    active_tasks = []
+    todo_path = "project-docs/todo.md"
+    if os.path.exists(todo_path):
+        with open(todo_path) as f:
+            for line in f:
+                if "- [ ]" in line:
+                    id_m = re.search(r'<!--\s*id:\s*(\d+)\s*-->', line)
+                    text = re.sub(r'-\s*\[ \]\s*', '', line).strip()
+                    text = re.sub(r'<!--.*?-->', '', text).strip()
+                    active_tasks.append({"id": id_m.group(1) if id_m else None, "text": text})
+
+    telemetry_events = _load_telemetry_events()
+
+    # Last checkpoint from telemetry
+    last_checkpoint = None
+    for e in reversed(telemetry_events):
+        if e.get("type") == "checkpoint":
+            last_checkpoint = e
+            break
+
+    # Sentinel alerts
+    sentinel_file = ".synlynk/sentinel.md"
+    sentinel_alerts = _read_sentinel_alerts(sentinel_path=sentinel_file)
+
+    # Budget
+    total_usd, total_requests = parse_costs_md()
+    config = load_config()
+    limit_usd = config["budget"]["limit_usd"]
+    limit_reqs = config["budget"]["limit_requests"]
+
+    # Watcher
+    daemon = WatchDaemon()
+    watcher_running = daemon._is_running()
+    last_trigger_file = None
+    for e in reversed(telemetry_events):
+        if e.get("type") == "watch_trigger":
+            last_trigger_file = e.get("changed_file")
+            break
+
+    # Teammates (team mode)
+    teammates = []
+    if mode == "team":
+        devlogs_dir = "project-docs/devlogs"
+        if os.path.exists(devlogs_dir):
+            for fname in sorted(os.listdir(devlogs_dir)):
+                if fname.endswith(".md") and fname not in (f"{username}.md", "README.md"):
+                    fpath = os.path.join(devlogs_dir, fname)
+                    teammates.append({
+                        "user": fname[:-3],
+                        "last_active": _get_last_devlog_date(fpath),
+                    })
+
+    has_alert = bool(sentinel_alerts) or total_usd >= limit_usd or total_requests >= limit_reqs
+
+    if json_output:
+        data = {
+            "schema_version": 1,
+            "timestamp": time.strftime('%Y-%m-%dT%H:%M:%S'),
+            "user": username,
+            "mode": mode,
+            "active_tasks": active_tasks,
+            "last_checkpoint": last_checkpoint,
+            "sentinel": {"alerts": sentinel_alerts},
+            "budget": {
+                "used_usd": round(total_usd, 4),
+                "limit_usd": limit_usd,
+                "requests": total_requests,
+                "limit_requests": limit_reqs,
+            },
+            "watcher": {"running": watcher_running, "last_trigger_file": last_trigger_file},
+            "teammates": teammates,
+        }
+        print(json.dumps(data, indent=2))
+        sys.exit(1 if has_alert else 0)
+
+    # Human output
+    sep = "─" * 45
+    print(sep)
+    print(f" synlynk status · @{username} · {mode} mode")
+    print(sep)
+    print(f" ACTIVE TASKS ({len(active_tasks)})")
+    for t in active_tasks:
+        tid = f"#{t['id']}" if t['id'] else ""
+        print(f"   [ ] {t['text']:<40} {tid}")
+    print()
+    print(" LAST CHECKPOINT")
+    if last_checkpoint:
+        print(f"   @{last_checkpoint.get('user')} · {last_checkpoint.get('timestamp')} · "
+              f"{last_checkpoint.get('completed_task_count', 0)} tasks archived")
+    else:
+        print("   No checkpoints yet")
+    print()
+    print(" SENTINEL")
+    if sentinel_alerts:
+        for alert in sentinel_alerts:
+            print(f"   ⚠ {alert}")
+    else:
+        print("   ✓ No alerts")
+    print()
+    pct = (total_usd / limit_usd * 100) if limit_usd else 0
+    print(" BUDGET")
+    print(f"   ${total_usd:.2f} / ${limit_usd:.2f} ({pct:.0f}%)  ·  {total_requests} / {limit_reqs} requests")
+    avg_cost, remaining_execs = _compute_burn_rate()
+    if avg_cost > 0:
+        runway = f"~{remaining_execs:,} execs remaining" if remaining_execs is not None else "N/A"
+        print(f"   Burn:   ${avg_cost:.4f}/exec avg  |  {runway} at current pace")
+    print()
+    icon = "●" if watcher_running else "○"
+    state = "Running" if watcher_running else "Stopped"
+    trigger = f"  ·  last trigger {last_trigger_file}" if last_trigger_file else ""
+    print(f" WATCHER\n   {icon} {state}{trigger}")
+    sentinel_path = os.path.join(os.getcwd(), ".synlynk", "sentinel.md")
+    check_daemon_health(sentinel_path=sentinel_path)
+    check_stall(sentinel_path=sentinel_path)
+    if mode == "team" and teammates:
+        print()
+        print(" TEAMMATES")
+        for tm in teammates:
+            print(f"   @{tm['user']:<12} · last active {tm['last_active']}")
+    print()
+    print(f" {_CYAN}CAPABILITY LEDGER{_RESET}")
+    try:
+        _cl_conn = _get_db()
+        _cl_rows = _cl_conn.execute(
+            "SELECT agent, model_version, engg_domain, phase, weighted_score, sample_count "
+            "FROM capability_scores ORDER BY weighted_score DESC LIMIT 3"
+        ).fetchall()
+        _cl_conn.close()
+    except Exception:
+        _cl_rows = []
+    if _cl_rows:
+        print(f"   {'Agent':<10} {'Model':<22} {'Domain':<8} {'Phase':<10} {'Score':>6}  N")
+        for _ag, _mv, _dom, _ph, _sc, _n in _cl_rows:
+            _sc_str = f"{_sc:.2f}" if _sc is not None else "  —  "
+            print(f"   {_GREEN}{_ag:<10}{_RESET} {_mv:<22} {_dom:<8} {_ph:<10} {_sc_str:>6}  {_n}")
+    else:
+        print("   No capability data yet.")
+    print(sep)
+    sys.exit(1 if has_alert else 0)
+
+def init(force: bool = False, agents: list = None,
+         org: str = None, repo: str = None, project_id: str = None,
+         mode: str = "solo", dry_run: bool = False, quiet: bool = False,
+         replace_generated_docs: bool = False,
+         non_interactive: bool = False) -> None:
+    """Progressive wizard: semantic scan → harness discovery → doc bootstrap → nudge."""
+
+    # An explicit non-interactive flag always uses defaults.  Otherwise keep
+    # prompting even when stdin is not a TTY: callers and tests may provide a
+    # working input function.  Closed/exhausted stdin is handled below via
+    # EOFError, which preserves the headless subprocess fallback.
+    auto_defaults = bool(non_interactive)
+
+    def _print_step(n: int, label: str) -> None:
+        print(f"\n{_BOLD}{_CYAN}Step {n}/{_TOTAL_STEPS} — {label}{_RESET}")
+
+    _TOTAL_STEPS = 6
+
+    # ── Step 1: Detect existing state ──────────────────────────────────────
+    _print_step(1, "Scanning repository")
+    synlynk_exists = os.path.exists(".synlynk")
+    if synlynk_exists and not force:
+        print(f"  {_YELLOW}⚠ .synlynk/ already exists.{_RESET} "
+              "Use --force to reinitialise.\n  Updating agent files only.")
+
+    if dry_run:
+        print("  DRY RUN — no files will be written\n")
+        dd_preview = _docs_dir()
+        for d in [dd_preview, os.path.join(dd_preview, "devlogs"), ".synlynk", LOGS_DIR, PROMPTS_DIR]:
+            if not os.path.exists(d):
+                print(f"  would create: {d}/")
+        print("  would always overwrite (marker_style='none', regardless of --force):")
+        for fpath in (".cursor/rules/synlynk.mdc", ".github/copilot-instructions.md",
+                      ".windsurfrules", "AI_INSTRUCTIONS.md"):
+            if os.path.exists(fpath):
+                print(f"    ⚠ {fpath}  (already exists — would be overwritten unconditionally)")
+            else:
+                print(f"    {fpath}  (would be created)")
+        return
+
+    scan = _static_scan(".")
+    print(f"  Project : {_BOLD}{scan['project_name']}{_RESET}")
+    print(f"  Commits : {scan['commit_count']}")
+    print(f"  Languages: {', '.join(scan['languages']) or 'unknown'}")
+    if scan["recent_topics"]:
+        print(f"  Recent  : {scan['recent_topics'][0]}")
+    if not scan["has_structured_commits"] and scan["commit_count"] > 0:
+        print(f"  {_DIM}⚠ Commit messages don't follow a structured convention — "
+              "skeleton quality may be lower. Review generated docs before proceeding.{_RESET}")
+
+    # ── Step 2: Agent discovery ─────────────────────────────────────────────
+    _print_step(2, "Discovering agents")
+    discovered = discover_agents()
+    functional = [a for a in discovered if a["functional"]]
+    non_functional = [a for a in discovered if not a["functional"]]
+
+    if functional:
+        print(f"\n  {_BOLD}{_GREEN}✨ Synlynk is ready to route coding tasks:{_RESET}")
+        for ag in functional:
+            roles = ", ".join(ag["roles"])
+            print(f"    {_GREEN}✓ {ag['name']:10}{_RESET} {ag['version']}  "
+                  f"roles: {roles}")
+    else:
+        print(f"  {_YELLOW}No agents detected. Install Claude, Gemini, or Codex to route coding tasks.{_RESET}")
+
+    if non_functional:
+        print(f"\n  {_DIM}Found but not configured (run --version failed):{_RESET}")
+        for ag in non_functional:
+            print(f"    {_DIM}✗ {ag['name']} — check API key / install{_RESET}")
+
+    from synlynk.rollback import rollback_checkpoint
+
+    config_path = os.path.join(".synlynk", "config.json")
+    rates_path = os.path.join(".synlynk", "model_rates.json")
+    with rollback_checkpoint("init", untracked_paths=[
+        os.path.join(".git", "hooks", "pre-commit"),
+        config_path,
+        os.path.join(".synlynk", "instructions.json"),
+        rates_path,
+        "project-docs",
+        "roadmap.md",
+        "memory.md",
+        "todo.md",
+        "CLAUDE.md",
+        "GEMINI.md",
+        "AGENTS.md",
+        "GROK.md",
+        ".cursor/rules/synlynk.mdc",
+        ".github/copilot-instructions.md",
+        ".windsurfrules",
+        "AI_INSTRUCTIONS.md",
+    ]):
+        # ── Step 3: Create directories + write skeleton ─────────────────────
+        dd = _docs_dir()
+        _print_step(3, f"Bootstrapping {dd}/")
+        for d in [dd, os.path.join(dd, "devlogs"), ".synlynk",
+                  LOGS_DIR, PROMPTS_DIR]:
+            if not os.path.exists(d):
+                os.makedirs(d)
+
+        written = _write_informed_skeleton(
+            scan, skip_existing=not force, replace_generated_docs=replace_generated_docs
+        )
+        if written:
+            for p, label in written:
+                print(f"  {_GREEN}✓{_RESET} {p}  {_DIM}({label}){_RESET}")
+        else:
+            print(f"  {_DIM}All docs already exist — skipped (use --force to overwrite){_RESET}")
+
+        # Write agent instruction files using _write_instruction_file().
+        agent_set = set(agents) if agents is not None else {a["name"] for a in functional} or {"claude", "agy", "codex", "grok"}
+        templates = _build_templates(org=org, repo=repo, project_id=project_id)
+
+        # Core trio: only write if agent was discovered as functional.
+        trio_content = {
+            "CLAUDE.md":   (templates.get("CLAUDE.md", ""), "html"),
+            "GEMINI.md":   (templates.get("GEMINI.md", ""), "html"),
+            "AGENTS.md":   (templates.get("AGENTS.md", ""), "html"),
+            "GROK.md":     (templates.get("GROK.md", ""), "html"),
+        }
+        _agent_guards = {"CLAUDE.md": "claude", "GEMINI.md": "agy", "AGENTS.md": "codex", "GROK.md": "grok"}
+        for fname, (content, mstyle) in trio_content.items():
+            required = _agent_guards[fname]
+            if required not in agent_set:
+                continue
+            _write_instruction_file(fname, required, content, mstyle)
+
+        # Extended targets: written based on environment detection.
+        # Guards are sourced from _INSTRUCTION_TARGETS[i][3] (detection_fn).
+        _target_detection = {fpath: fn for fpath, _, _, fn in _INSTRUCTION_TARGETS}
+        extended = [
+            (".cursor/rules/synlynk.mdc",       "cursor",    "none", _build_cursor_mdc()),
+            (".github/copilot-instructions.md",  "copilot",   "html", _build_copilot_instructions()),
+            (".windsurfrules",                   "windsurf",  "hash", _build_windsurf_rules()),
+            ("AI_INSTRUCTIONS.md",              "universal",  "html", templates.get("AI_INSTRUCTIONS.md", "")),
+        ]
+        for fpath, tool, mstyle, content in extended:
+            if _target_detection[fpath]():
+                # marker_style='none' means synlynk owns the whole file — always overwrites
+                _write_instruction_file(fpath, tool, content, mstyle)
+
+        # Write manifest of all tracked files with their SHAs.
+        manifest_entries = {}
+        for fpath, tool, mstyle, _ in _INSTRUCTION_TARGETS:
+            if not os.path.exists(fpath):
+                continue
+            file_content = open(fpath).read()
+            section = _extract_synlynk_section(file_content, mstyle)
+            if section is not None:
+                manifest_entries[fpath] = {"tool": tool, "sha": _compute_section_sha(section)}
+        if manifest_entries:
+            _write_instruction_manifest(manifest_entries)
+
+        install_pre_commit_hook(repo_root=Path.cwd())
+
+        # Write config.json if needed.
+        config_json_content = templates.get("config.json", "")
+        if config_json_content:
+            if not os.path.exists(config_path) or force:
+                try:
+                    config_payload = json.loads(config_json_content)
+                except (TypeError, json.JSONDecodeError):
+                    config_payload = None
+                if isinstance(config_payload, dict):
+                    config_payload.setdefault("local_auto_threshold", 0.5)
+                    config_payload.setdefault("local_fallback", "agy")
+                    config_json_content = json.dumps(config_payload, indent=2) + "\n"
+                with open(config_path, "w") as f:
+                    f.write(config_json_content)
+
+        if not os.path.exists(rates_path):
+            from synlynk.costs import _HARDCODED_FALLBACK_RATES
+            rates_seed = dict(_HARDCODED_FALLBACK_RATES)
+            rates_seed["rates_updated_at"] = time.strftime("%Y-%m-%d")
+            with open(rates_path, "w") as f:
+                json.dump(rates_seed, f, indent=2)
+            print(f"  ✓ Created {rates_path}")
+
+    # ── Step 4: LLM enrichment offer ────────────────────────────────────────
+    if not quiet:
+        _print_step(4, "LLM enrichment (optional)")
+        if functional:
+            enricher = functional[0]
+            print(f"  I found {scan['commit_count']} commits and {len(scan['recent_topics'])} "
+                  f"recent topics.\n  Want me to ask {enricher['name']} to synthesise a roadmap "
+                  f"from this? (costs tokens)")
+            answer = ""
+            if not auto_defaults:
+                try:
+                    answer = input("  [y/N] ").strip().lower()
+                except EOFError:
+                    auto_defaults = True
+            if answer == "y":
+                print(f"  {_DIM}Calling {enricher['cli']} --print...{_RESET}", end=" ", flush=True)
+                ok = _llm_enrich(enricher["name"], enricher["cli"], scan)
+                print(f"{_GREEN}done{_RESET}" if ok else f"{_YELLOW}failed — keeping skeleton{_RESET}")
+        else:
+            print(f"  {_DIM}No functional agent available — skipping enrichment{_RESET}")
+
+    # ── Step 5: Cloud directory nudge ────────────────────────────────────────
+    inferred = _infer_industry()
+    if quiet:
+        email = ""
+        industry = inferred
+    else:
+        _print_step(5, "Team & cloud setup (optional)")
+        print("  Add a collaborator or share this workspace with your team.")
+        print("  Leave blank to skip.")
+        if auto_defaults:
+            email = ""
+            industry = inferred
+        else:
+            try:
+                email = input("  Email or synlynk ID: ").strip()
+                industry = input(f"  Industry vertical [{inferred}]: ").strip() or inferred
+            except EOFError:
+                auto_defaults = True
+                email = ""
+                industry = inferred
+        if industry not in list(_INDUSTRY_KEYWORDS.keys()) + ["unknown"]:
+            industry = "unknown"
+
+    # ── Step 6: Finalise config ──────────────────────────────────────────────
+    _print_step(6, "Finalising")
+    synlynk_config_path = os.path.join("project-docs", ".synlynk_config.json")
+    if not os.path.exists(synlynk_config_path) or force:
+        config_data = {"mode": mode, "version": VERSION,
+                       "init_timestamp": time.strftime("%Y-%m-%dT%H:%M:%S")}
+        with open(synlynk_config_path, "w") as f:
+            json.dump(config_data, f, indent=2)
+
+    _update_config({
+        "workgroup_agents": [a["name"] for a in functional],
+        "workgroup_invite_email": email or None,
+        "industry": industry,
+    })
+
+    set_state("stopped")
+    from synlynk.capability_sweep import _seed_capability_ledger_from_baseline
+
+    _seed_capability_ledger_from_baseline(_get_db())
+
+    # LIVE-21: make probe metadata available before the first dispatch.  Do
+    # not probe fallback names when no harness is installed: some harness
+    # probes perform network checks and init must retain its fast headless
+    # path.  Explicit ``agents=`` remains authoritative.
+    if agents is not None:
+        probe_targets = sorted(set(agents))
+    else:
+        # Keep the legacy no-argument init path bounded.  Explicitly selected
+        # harnesses are probed here; otherwise first dispatch performs the
+        # defensive inline probe for the discovered harness.
+        probe_targets = []
+    probe_all_configured_harnesses(probe_targets)
+
+    if auto_defaults:
+        print(f"  Auto-selected defaults: enrichment=no, email=empty, industry={industry}")
+
+    print(f"\n{_BOLD}{_GREEN}✓ synlynk initialised — Synlynk is a neutral control plane that routes coding tasks across AI vendors and local models, then proves the result.{_RESET}")
+    if functional:
+        agent_names = " + ".join(a["name"] for a in functional)
+        print(f"\n  {_BOLD}✨ Magic Moment 2 — dispatch agents now:{_RESET}")
+        print(f"    {_CYAN}synlynk dispatch {functional[0]['name']} --task \"your task\"{_RESET}")
+        if len(functional) >= 3:
+            print(f"    {_CYAN}synlynk run --trio --task \"your task\"{_RESET}  "
+                  f"← runs {agent_names} in parallel")
+    print(f"\n  Background Supervision:")
+    print(f"    {_CYAN}synlynk daemon --install-service{_RESET}  ← supervise daemon across reboots (launchd/systemd)")
+    print(f"\n  Next: {_DIM}synlynk status  ·  synlynk jobs  ·  synlynk dispatch --help{_RESET}\n")
+
+# --- module extractions (backwards compat) ---
+# Normal library imports retain the historical package-level exports. CLI
+# startup skips this fan-out until after argparse has parsed the command.
+if not _FAST_CLI and not _vizor_daemon_process():
+    _load_legacy_imports()