@maudecode/talaria-web 1.16.1 → 1.18.0

package/sidecar/talaria_sidecar/methods/checkpoints.py

@@ -0,0 +1,89 @@
+"""``checkpoints.*``: a workspace's filesystem checkpoints through the Agent's own ``CheckpointManager`` (TAL-913).
+
+The Agent keeps every project's checkpoints as refs in one shared git store under the profile home; listing, diffing and
+restoring go through its manager so the store layout, the nested-repository refusal and the pre-rollback snapshot stay
+the Agent's.
+"""
+
+from __future__ import annotations
+
+from ..errors import InvalidParams, RpcError
+from ..home import profile_home_param, scoped_home
+from ..rpc import CallContext
+
+
+def checkpoint_kwargs() -> dict:
+    """The profile's ``checkpoints`` config as ``AIAgent`` kwargs, resolved as the Agent's gateway does
+    (``gateway/run.py::_checkpoint_agent_kwargs``): the legacy ``checkpoints: true`` form, else the section over
+    ``DEFAULT_CONFIG``. Only a real ``true`` turns them on, so a quoted ``"false"`` stays off."""
+    from hermes_cli.config import DEFAULT_CONFIG, load_config
+
+    section = (load_config() or {}).get("checkpoints", {})
+    if isinstance(section, bool):
+        section = {"enabled": section}
+    elif not isinstance(section, dict):
+        section = {}
+    defaults = DEFAULT_CONFIG["checkpoints"]
+    return {
+        "checkpoints_enabled": section.get("enabled", defaults["enabled"]) is True,
+        "checkpoint_max_snapshots": section.get("max_snapshots", defaults["max_snapshots"]),
+        "checkpoint_max_total_size_mb": section.get("max_total_size_mb", defaults["max_total_size_mb"]),
+        "checkpoint_max_file_size_mb": section.get("max_file_size_mb", defaults["max_file_size_mb"]),
+    }
+
+
+def _manager():
+    from tools.checkpoint_manager import CheckpointManager
+
+    kwargs = checkpoint_kwargs()
+    return CheckpointManager(enabled=kwargs["checkpoints_enabled"], max_snapshots=kwargs["checkpoint_max_snapshots"],
+                             max_total_size_mb=kwargs["checkpoint_max_total_size_mb"], max_file_size_mb=kwargs["checkpoint_max_file_size_mb"])
+
+
+def _param(params: dict, name: str) -> str:
+    value = params.get(name)
+    if not isinstance(value, str) or not value.strip():
+        raise InvalidParams(f"{name} is required")
+    return value
+
+
+def _agent_result(result: dict) -> dict:
+    """The Agent answers a refusal (unknown checkpoint, uncaptured nested repository, failed checkout) as ``success: False``."""
+    if not result.get("success"):
+        raise RpcError(str(result.get("error") or "checkpoint operation failed"), condition="checkpoint_failed")
+    return result
+
+
+def _owned(manager, workspace: str, checkpoint: str) -> str:
+    """The full hash of ``checkpoint`` among ``workspace``'s own checkpoints. The store is shared by every project and the
+    Agent's diff and restore accept any commit in it, so another workspace's hash would check that tree out here."""
+    matches = [c["hash"] for c in manager.list_checkpoints(workspace) if c.get("hash") and str(c["hash"]).startswith(checkpoint.lower())]
+    if len(matches) != 1:
+        raise RpcError(f"Checkpoint '{checkpoint}' is not a checkpoint of this workspace", condition="checkpoint_failed")
+    return matches[0]
+
+
+def register(registry) -> None:
+    @registry.method("checkpoints.list")
+    def list_(ctx: CallContext, params: dict) -> dict:
+        workspace = _param(params, "workspace")
+        with scoped_home(profile_home_param(params)):
+            from tools.checkpoint_manager import _store_path
+
+            return {"checkpoints": _manager().list_checkpoints(workspace), "store": str(_store_path())}
+
+    @registry.method("checkpoints.diff")
+    def diff(ctx: CallContext, params: dict) -> dict:
+        workspace, checkpoint = _param(params, "workspace"), _param(params, "checkpoint")
+        with scoped_home(profile_home_param(params)):
+            manager = _manager()
+            result = _agent_result(manager.diff(workspace, _owned(manager, workspace, checkpoint)))
+        return {"stat": str(result.get("stat") or ""), "diff": str(result.get("diff") or "")}
+
+    @registry.method("checkpoints.restore")
+    def restore(ctx: CallContext, params: dict) -> dict:
+        workspace, checkpoint = _param(params, "workspace"), _param(params, "checkpoint")
+        with scoped_home(profile_home_param(params)):
+            manager = _manager()
+            result = _agent_result(manager.restore(workspace, _owned(manager, workspace, checkpoint)))
+        return {"restored_to": str(result.get("restored_to") or ""), "reason": str(result.get("reason") or "")}

package/sidecar/talaria_sidecar/methods/commands.py

@@ -15,7 +15,14 @@ log = logging.getLogger("talaria_sidecar.commands")
 
 _NEVER_EXPOSE = frozenset({"sethome", "restart", "update", "commands"})
 _ALIASES = {"reload_mcp": "reload-mcp", "reload_skills": "reload-skills", "codex_runtime": "codex-runtime"}
-_ALLOWED = frozenset({"reload-mcp", "reload-skills", "codex-runtime", "credits"})
+# The commands ``commands.exec`` runs, with the catalog row the sidecar lists when the Agent registry lacks one.
+_RUNTIME_COMMANDS = {
+    "reload-mcp": ("Reload MCP servers from config", "Tools & Skills", ""),
+    "reload-skills": ("Re-scan skills from disk", "Tools & Skills", ""),
+    "codex-runtime": ("Toggle codex app-server runtime for OpenAI/Codex models", "Configuration", "[auto|codex_app_server]"),
+    "credits": ("Show your Nous credits", "Info", ""),
+}
+_ALLOWED = frozenset(_RUNTIME_COMMANDS)
 _RELOAD_MCP_LOCK = threading.Lock()
 _RELOAD_SKILLS_LOCK = threading.Lock()
 _CODEX_RUNTIME_LOCK = threading.Lock()
@@ -46,7 +53,13 @@ def list_commands() -> list[dict[str, Any]]:
         out.append({
             "name": cmd.name, "description": cmd.description, "category": cmd.category, "aliases": list(cmd.aliases),
             "args_hint": cmd.args_hint, "subcommands": list(cmd.subcommands), "cli_only": bool(cmd.cli_only), "gateway_only": bool(cmd.gateway_only),
+            "exec": cmd.name in _ALLOWED,
         })
+    listed = {c["name"] for c in out}
+    for name, (description, category, args_hint) in _RUNTIME_COMMANDS.items():
+        if name not in listed:
+            out.append({"name": name, "description": description, "category": category, "aliases": [a for a, n in _ALIASES.items() if n == name],
+                        "args_hint": args_hint, "subcommands": [], "cli_only": False, "gateway_only": False, "exec": True})
     try:
         from hermes_cli.plugins import get_plugin_commands
 
@@ -55,7 +68,7 @@ def list_commands() -> list[dict[str, Any]]:
             if name in existing or name in _NEVER_EXPOSE:
                 continue
             out.append({"name": name, "description": str(info.get("description", "Plugin command")), "category": "Plugin", "aliases": [],
-                        "args_hint": str(info.get("args_hint", "")), "subcommands": [], "cli_only": False, "gateway_only": False})
+                        "args_hint": str(info.get("args_hint", "")), "subcommands": [], "cli_only": False, "gateway_only": False, "exec": True})
     except Exception:  # noqa: BLE001 - plugin registry is optional
         log.debug("plugin command listing failed", exc_info=True)
     return out
@@ -231,6 +244,77 @@ def execute_plugin_command(command: str) -> str | None:
         return f"Plugin command error: {type(exc).__name__}"
 
 
+def _profile_bundles(skill_bundles) -> dict[str, dict[str, Any]]:
+    """The scoped profile's bundles keyed ``/slug``, read from disk the way ``scan_bundles`` reads them.
+
+    ``scan_bundles``/``get_skill_bundles`` publish one profile's bundles in a process-wide cache keyed only by mtime,
+    which cron jobs in other profiles read concurrently, so the sidecar never fills it."""
+    out: dict[str, dict[str, Any]] = {}
+    for path in skill_bundles._iter_bundle_files():
+        info = skill_bundles._load_bundle_file(path)
+        if info:
+            out.setdefault(f"/{info['slug']}", info)
+    return out
+
+
+def list_command_bundles() -> list[dict[str, Any]]:
+    """The profile's skill bundles as slash-command rows; [] when the bundle runtime is missing or fails."""
+    try:
+        import agent.skill_bundles as skill_bundles
+    except ImportError:
+        return []
+    try:
+        bundles = sorted(_profile_bundles(skill_bundles).values(), key=lambda b: b["slug"])
+    except Exception:  # noqa: BLE001
+        log.warning("Failed to list skill bundles", exc_info=True)
+        return []
+    return [{"name": str(b["slug"]).strip().lower(), "description": str(b.get("description") or "").strip() or "Skill bundle",
+             "skill_count": len(b.get("skills") or []), "source": "bundle"} for b in bundles if str(b.get("slug") or "").strip()]
+
+
+def _bundle_invocation(info: dict[str, Any], instruction: str) -> tuple[str, list[str], list[str]] | None:
+    """``build_bundle_invocation_message`` for a bundle read by ``_profile_bundles`` (that one looks it up in the shared cache),
+    skipping the skills disabled for Web chat (``skills.platform_disabled.webui``)."""
+    from agent.skill_commands import _disabled_skill_names, _load_skill_blocks, _load_skill_payload, _scaffold_header
+
+    name = info["name"]
+    loaded, missing, disabled, blocks = _load_skill_blocks(
+        [(skill or "").strip() for skill in info["skills"]], _load_skill_payload, lambda _skill: f'[Loaded as part of the "{name}" skill bundle.]',
+        None, disabled_names=_disabled_skill_names("webui"))
+    if not blocks:
+        return None
+    header = _scaffold_header(f'"{name}" skill bundle', loaded, lead_lines=[f"Bundle: {name}"], missing=missing, disabled=disabled,
+                              extra_instruction=info.get("instruction") or "", user_instruction=instruction)
+    return "\n\n".join([header, *blocks]), loaded, missing
+
+
+def resolve_bundle_command(command: str) -> dict[str, Any]:
+    """Expand ``/<bundle> [instruction]`` into the user message that loads the bundle's skills."""
+    name, instruction = parse_slash_command(command)
+    try:
+        import agent.skill_bundles as skill_bundles
+        from agent.skill_commands import resolve_slash_key
+    except ImportError as exc:
+        raise RpcError("Skill bundle runtime unavailable", condition="bundle_unavailable") from exc
+    try:
+        bundles = _profile_bundles(skill_bundles)
+        key = resolve_slash_key(name, bundles)
+        result = _bundle_invocation(bundles[key], instruction) if key else None
+    except ValueError as exc:
+        raise InvalidParams(str(exc)) from exc
+    except Exception as exc:  # noqa: BLE001
+        log.warning("Failed to resolve skill bundle command", exc_info=True)
+        raise RpcError("Skill bundle command unavailable", condition="bundle_unavailable") from exc
+    if key is None:
+        raise RpcError("Bundle command not found", condition="bundle_not_found")
+    message, loaded, missing = result or ("", [], [])
+    message = str(message or "").strip()
+    if not message:
+        raise RpcError("Bundle command returned no invocation text", condition="bundle_unavailable")
+    return {"name": key.lstrip("/"), "source": "bundle", "message": message, "loaded_skills": [str(s) for s in loaded or []],
+            "missing_skills": [str(s) for s in missing or []]}
+
+
 def resolve_moa_config(preset: str | None) -> dict:
     try:
         from hermes_cli.moa_config import moa_usage, normalize_moa_config
@@ -339,6 +423,16 @@ def register(registry) -> None:
             raise RpcError(f"unknown command {parse_slash_command(command)[0]!r}", condition="command_not_found")
         return {"output": output, "source": source}
 
+    @registry.method("commands.bundles")
+    def bundles(ctx: CallContext, params: dict) -> dict:
+        with scoped_home(profile_home_param(params)):
+            return {"bundles": list_command_bundles()}
+
+    @registry.method("commands.bundle_resolve")
+    def bundle_resolve(ctx: CallContext, params: dict) -> dict:
+        with scoped_home(profile_home_param(params)):
+            return resolve_bundle_command(str(params.get("command") or ""))
+
     @registry.method("commands.moa_preset")
     def moa(ctx: CallContext, params: dict) -> dict:
         with scoped_home(profile_home_param(params)):

package/sidecar/talaria_sidecar/methods/cron.py

@@ -33,6 +33,35 @@ _RUNNING_LOCK = threading.Lock()
 _SNAPSHOT_LOCK = threading.Lock()
 
 
+def _main_model_pin() -> tuple[str | None, str | None]:
+    """``(provider, model)`` the scoped profile's main agent runs on: the Agent's own ``cron.jobs._main_model_pin``.
+
+    Agent 0.21.3 predates that helper, so it is rebuilt from the readers 0.21.4 composes: the home's effective
+    ``config.yaml`` model and the provider the runtime resolves for it. ``(None, None)`` when no model is configured.
+    """
+    from cron import jobs
+
+    if hasattr(jobs, "_main_model_pin"):
+        return jobs._main_model_pin()
+    from hermes_cli.config_effective import load_user_config_effective
+    from hermes_constants import get_hermes_home
+
+    cfg_path = get_hermes_home() / "config.yaml"
+    cfg = load_user_config_effective(cfg_path) if cfg_path.exists() else {}
+    model_cfg = cfg.get("model") or {}
+    model = model_cfg.get("default") or model_cfg.get("model") if isinstance(model_cfg, dict) else model_cfg
+    model = model.strip() or None if isinstance(model, str) else None
+    if not model:
+        return None, None
+    provider = None
+    with contextlib.suppress(Exception):
+        from hermes_cli.runtime_provider import resolve_runtime_provider
+
+        resolved = resolve_runtime_provider(requested=None).get("provider")
+        provider = resolved.strip().lower() or None if isinstance(resolved, str) else None
+    return provider, model
+
+
 class CronUnavailable(RpcError):
     def __init__(self, exc: Exception):
         super().__init__(f"cron unavailable: {exc}", condition="cron_unavailable")
@@ -252,14 +281,18 @@ def _run_in_child(job, execution_home, ctx: CallContext):
                     process.join(timeout=5)
                     status, payload = "cancelled", ["cancelled", ""]
                     break
-                if time.monotonic() >= deadline:
-                    if process.is_alive():
-                        process.terminate()
-                        process.join(timeout=5)
-                        payload = [f"cron run subprocess produced no result within {_result_timeout(job):g}s and was terminated", ""]
-                    else:
+                if not process.is_alive():
+                    # The child may have put its result just before exiting; otherwise it died (OOM, signal) without one.
+                    try:
+                        status, *payload = result_queue.get_nowait()
+                    except queue.Empty:
                         payload = [f"cron run subprocess exited with code {process.exitcode} without producing a result", ""]
                     break
+                if time.monotonic() >= deadline:
+                    process.terminate()
+                    process.join(timeout=5)
+                    payload = [f"cron run subprocess produced no result within {_result_timeout(job):g}s and was terminated", ""]
+                    break
         process.join(timeout=5)
         if process.is_alive():
             process.terminate()
@@ -392,8 +425,6 @@ def register(registry) -> None:
         # to the store home; owner_profile only preserves management from the creating Web profile.
         if post.get("profile") and execution_home and not (model and provider) and not body.get("no_agent"):
             try:
-                from cron.jobs import _main_model_pin
-
                 with _SNAPSHOT_LOCK, scoped_home(Path(execution_home)):
                     profile_provider, profile_model = _main_model_pin()
                 if not profile_model:

package/sidecar/talaria_sidecar/methods/gateway.py

@@ -1,4 +1,4 @@
-"""``gateway.*``: Hermes gateway lifecycle through the ``hermes`` CLI (ported from api/gateway_restart.py)."""
+"""``gateway.*``: Hermes gateway lifecycle (start, stop, restart) through the ``hermes`` CLI."""
 
 from __future__ import annotations
 
@@ -16,7 +16,10 @@ from ..home import profile_home_param
 from ..rpc import CallContext
 
 log = logging.getLogger("talaria_sidecar.gateway")
-_RESTART_LOCK = threading.Lock()
+# One lifecycle action at a time across every action: overlapping `hermes gateway` subprocesses race each other.
+_ACTION_LOCK = threading.Lock()
+ACTIONS = ("start", "stop", "restart")
+_DONE = {"start": "started", "stop": "stopped", "restart": "restarted"}
 
 
 def _hermes_command() -> str:
@@ -39,9 +42,11 @@ def _drain(stream, sink: list[str]) -> None:
             pass
 
 
-def restart(home: Path, cli_profile: str | None, ctx: CallContext, *, quick_timeout: float, background_wait: float) -> dict:
-    if not _RESTART_LOCK.acquire(blocking=False):
-        return {"status": "busy", "message": "Restart already in progress. Please wait a moment and try again."}
+def control(action: str, home: Path, cli_profile: str | None, ctx: CallContext, *, quick_timeout: float, background_wait: float) -> dict:
+    if action not in ACTIONS:
+        raise InvalidParams("unsupported gateway action")
+    if not _ACTION_LOCK.acquire(blocking=False):
+        return {"status": "busy", "message": "Another gateway action is already in progress. Please wait a moment and try again."}
     try:
         env = dict(os.environ)
         env["HERMES_HOME"] = str(home)
@@ -49,9 +54,12 @@ def restart(home: Path, cli_profile: str | None, ctx: CallContext, *, quick_time
         cmd = [_hermes_command()]
         if cli_profile:
             cmd.extend(["--profile", cli_profile])
-        cmd.extend(["gateway", "restart"])
-        log.info("Restarting gateway via %s (HERMES_HOME=%s)", " ".join(cmd), home)
-        proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, env=env)
+        cmd.extend(["gateway", action])
+        log.info("Running gateway %s via %s (HERMES_HOME=%s)", action, " ".join(cmd), home)
+        try:
+            proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, env=env)
+        except FileNotFoundError:
+            return {"status": "failed", "message": "Hermes CLI not found"}
         # Drain both pipes from the start: a chatty restart must never block on a full pipe and be mistaken for a hang.
         out: list[str] = []
         err: list[str] = []
@@ -67,8 +75,8 @@ def restart(home: Path, cli_profile: str | None, ctx: CallContext, *, quick_time
         def outcome() -> dict:
             stdout, stderr = collected()
             if proc.returncode == 0:
-                return {"status": "completed", "message": "Gateway service restarted successfully", "detail": stdout or stderr}
-            return {"status": "failed", "message": f"Restart failed: {stderr or stdout}", "detail": stdout or stderr, "returncode": proc.returncode}
+                return {"status": "completed", "message": f"Gateway service {_DONE[action]} successfully", "detail": stdout or stderr}
+            return {"status": "failed", "message": f"{action.capitalize()} failed: {stderr or stdout}", "detail": stdout or stderr, "returncode": proc.returncode}
 
         ctx.emit("progress", {"phase": "started"})
         deadline = time.monotonic() + quick_timeout
@@ -90,17 +98,26 @@ def restart(home: Path, cli_profile: str | None, ctx: CallContext, *, quick_time
                 proc.kill()
                 proc.wait(timeout=5)
             collected()
-            return {"status": "failed", "message": f"Gateway restart process timed out after {background_wait:.0f}s and was terminated"}
+            return {"status": "failed", "message": f"Gateway {action} process timed out after {background_wait:.0f}s and was terminated", "timed_out": True}
         return outcome()
     finally:
-        _RESTART_LOCK.release()
+        _ACTION_LOCK.release()
 
 
 def register(registry) -> None:
-    @registry.method("gateway.restart", requires_agent=False)
-    def restart_(ctx: CallContext, params: dict) -> dict:
+    def run(ctx: CallContext, params: dict, action: str) -> dict:
         home = profile_home_param(params)
         cli_profile = params.get("cli_profile")
         if cli_profile is not None and not isinstance(cli_profile, str):
             raise InvalidParams("cli_profile must be a string")
-        return restart(home, cli_profile or None, ctx, quick_timeout=float(params.get("quick_timeout_seconds") or 2.0), background_wait=float(params.get("background_wait_seconds") or 240.0))
+        # A restart drains the old gateway first, so it gets longer than start or stop.
+        default_wait = 240.0 if action == "restart" else 60.0
+        return control(action, home, cli_profile or None, ctx, quick_timeout=float(params.get("quick_timeout_seconds") or 2.0), background_wait=float(params.get("background_wait_seconds") or default_wait))
+
+    @registry.method("gateway.control", requires_agent=False)
+    def control_(ctx: CallContext, params: dict) -> dict:
+        return run(ctx, params, str(params.get("action") or ""))
+
+    @registry.method("gateway.restart", requires_agent=False)
+    def restart_(ctx: CallContext, params: dict) -> dict:
+        return run(ctx, params, "restart")

package/sidecar/talaria_sidecar/methods/kanban.py

@@ -8,6 +8,7 @@ server; the sidecar receives typed params.
 from __future__ import annotations
 
 import json
+import secrets
 import time
 from dataclasses import asdict, is_dataclass
 from typing import Any
@@ -82,10 +83,120 @@ def _obj_dict(value):
     return dict(getattr(value, "__dict__", {}))
 
 
-def _task_dict(task):
+LIVE_CLAIM_MESSAGE = "task has a live worker; archive it to stop the worker"
+
+
+def _row_claim_live(row) -> bool:
+    """The Agent's ``_claim_is_live`` for a ``tasks`` row: a running task's worker process still holds its claim.
+
+    Releasing that claim (block, a direct status change) leaves the worker running, so the card
+    policy withholds those writes and the write paths refuse them (TAL-557). Unknown liveness counts as live.
+    """
+    if row is None or row["status"] != "running":
+        return False
+    columns = row.keys()
+    claim = {k: row[k] if k in columns else None for k in ("status", "claim_lock", "worker_pid", "worker_started_at")}
+    claimed = bool(claim["claim_lock"] and claim["worker_pid"])
+    try:
+        helper = getattr(_kb(), "_claim_is_live", None)
+    except RpcError:
+        return claimed
+    if helper is not None:
+        try:
+            return bool(helper(claim))
+        except Exception:  # noqa: BLE001 - the Agent could not decide: unknown liveness counts as live
+            return claimed
+    if not claimed:
+        return False
+    try:
+        # Agent 0.21.3 has no _claim_is_live, but its dispatcher's own worker PID check. Like its crash sweep, probe
+        # only a claim this host issued: another host's PID means nothing here, so a remote claim stays live.
+        from hermes_cli.kanban_db_dispatch import _pid_alive
+
+        if not str(claim["claim_lock"]).startswith(_kb()._host_prefix()):
+            return True
+        return bool(_pid_alive(int(claim["worker_pid"])))
+    except Exception:  # noqa: BLE001
+        return True
+
+
+def _claim_live(conn, task_id) -> bool:
+    return _row_claim_live(conn.execute("SELECT * FROM tasks WHERE id = ?", (task_id,)).fetchone())
+
+
+RUNNING_EXIT_MESSAGE = "task is running; confirm leaving Running"
+
+
+def _guard_running_exit(row, confirm_running_exit: bool) -> None:
+    """A write that takes a task out of Running needs the client's explicit confirmation, judged on the row the
+    write sees: a client's card policy can predate a dispatcher claim (TAL-557)."""
+    if row["status"] == "running" and not confirm_running_exit:
+        raise Conflict(RUNNING_EXIT_MESSAGE)
+
+
+FENCE_PREFIX = "talaria-fence:"
+FENCE_SECONDS = 60
+
+
+def _clear_stale_fences(conn) -> None:
+    """Release fences whose write never finished (the sidecar died mid-write), so the dispatcher can claim again."""
+    now = int(time.time())
+    stale = []
+    for row in conn.execute("SELECT id, claim_lock FROM tasks WHERE claim_lock LIKE ?", (FENCE_PREFIX + "%",)).fetchall():
+        try:
+            expires = int(str(row["claim_lock"])[len(FENCE_PREFIX):].split(":", 1)[0])
+        except ValueError:
+            expires = 0
+        if expires < now:
+            stale.append((row["id"], row["claim_lock"]))
+    if not stale:
+        return
+    kb = _kb()
+    with kb.write_txn(conn):
+        for task_id, fence in stale:
+            conn.execute("UPDATE tasks SET claim_lock = NULL WHERE id = ? AND claim_lock = ?", (task_id, fence))
+
+
+def _fenced(conn, task_id: str, write, *, confirm_running_exit: bool, releases_claim: bool = True):
+    """Run an Agent transition (block, complete, archive) with the dispatcher fenced out.
+
+    The Agent's helpers open their own write transaction, which cannot nest, so the checks and a fence lock share
+    one transaction first: ``claim_task`` claims only a ``ready`` task with ``claim_lock IS NULL``, so the card cannot
+    become a live run before the helper runs. ``releases_claim`` writes (block, complete) refuse a live worker's claim;
+    archive keeps it, because ``archive_task`` terminates that worker. The fence expires, so a write the sidecar never
+    finished stops holding the card once ``_clear_stale_fences`` next runs.
+    """
+    kb = _kb()
+    _clear_stale_fences(conn)
+    fence = f"{FENCE_PREFIX}{int(time.time()) + FENCE_SECONDS}:{secrets.token_hex(8)}"
+    with kb.write_txn(conn):
+        row = conn.execute("SELECT * FROM tasks WHERE id = ?", (task_id,)).fetchone()
+        if row is None:
+            raise NotFound("task not found")
+        _guard_running_exit(row, confirm_running_exit)
+        live = _row_claim_live(row)
+        if live and releases_claim:
+            raise Conflict(LIVE_CLAIM_MESSAGE)
+        # Only an unclaimed ready task is claimable; anything else needs no fence.
+        fenced = row["status"] == "ready" and row["claim_lock"] is None
+        if fenced:
+            conn.execute("UPDATE tasks SET claim_lock = ? WHERE id = ?", (fence, task_id))
+    try:
+        return write()
+    finally:
+        if fenced:
+            with kb.write_txn(conn):
+                conn.execute("UPDATE tasks SET claim_lock = NULL WHERE id = ? AND claim_lock = ?", (task_id, fence))
+
+
+def _task_dict(task, conn):
     data = _obj_dict(task)
     if not data:
         return data
+    # Facts the server's card policy needs (TAL-557): the Agent completes a non-review task only with
+    # stored or supplied evidence, and refuses to release a live worker's claim.
+    data["claim_live"] = data.get("status") == "running" and _claim_live(conn, data.get("id"))
+    data["has_completion_evidence"] = bool(str(data.get("result") or "").strip())
     try:
         age = _kb().task_age(task)
     except Exception:  # noqa: BLE001
@@ -131,12 +242,16 @@ def _validate_status(status: str) -> str:
     return value
 
 
-def _set_status_direct(conn, task_id: str, new_status: str) -> bool:
+def _set_status_direct(conn, task_id: str, new_status: str, *, confirm_running_exit: bool = False) -> bool:
     kb = _kb()
     with kb.write_txn(conn):
-        prev = conn.execute("SELECT status, current_run_id FROM tasks WHERE id = ?", (task_id,)).fetchone()
+        prev = conn.execute("SELECT * FROM tasks WHERE id = ?", (task_id,)).fetchone()
         if prev is None:
             return False
+        # Checked inside the write transaction, so a claim taken since the client's read is never released.
+        _guard_running_exit(prev, confirm_running_exit)
+        if _row_claim_live(prev):
+            raise Conflict(LIVE_CLAIM_MESSAGE)
         was_running = prev["status"] == "running"
         cur = conn.execute(
             "UPDATE tasks SET status = ?, "
@@ -202,14 +317,15 @@ def _patch_task(conn, task_id: str, body: dict) -> None:
     if "status" not in body or body.get("status") in (None, ""):
         return
     status = _validate_status(body.get("status"))
+    confirm = bool(body.get("confirm_running_exit"))
     if status == "done":
-        if not kb.complete_task(conn, task_id, result=body.get("result"), summary=body.get("summary")):
+        if not _fenced(conn, task_id, lambda: kb.complete_task(conn, task_id, result=body.get("result"), summary=body.get("summary")), confirm_running_exit=confirm):
             raise NotFound("task not found")
     elif status == "blocked":
-        if not kb.block_task(conn, task_id, reason=body.get("block_reason") or body.get("reason")):
+        if not _fenced(conn, task_id, lambda: kb.block_task(conn, task_id, reason=body.get("block_reason") or body.get("reason")), confirm_running_exit=confirm):
             raise NotFound("task not found")
     elif status == "archived":
-        if not kb.archive_task(conn, task_id):
+        if not _fenced(conn, task_id, lambda: kb.archive_task(conn, task_id), confirm_running_exit=confirm, releases_claim=False):
             raise NotFound("task not found")
     elif status == "running":
         raise InvalidParams("Cannot set status to 'running' directly; use the dispatcher/claim path")
@@ -220,10 +336,10 @@ def _patch_task(conn, task_id: str, body: dict) -> None:
         if current.status == "blocked":
             if not kb.unblock_task(conn, task_id):
                 raise NotFound("task not found")
-        elif not _set_status_direct(conn, task_id, "ready"):
+        elif not _set_status_direct(conn, task_id, "ready", confirm_running_exit=confirm):
             raise NotFound("task not found")
     elif status in ("triage", "todo"):
-        if not _set_status_direct(conn, task_id, status):
+        if not _set_status_direct(conn, task_id, status, confirm_running_exit=confirm):
             raise NotFound("task not found")
 
 
@@ -320,6 +436,7 @@ def board_payload(params: dict) -> dict:
         profile = _str(params, "profile") or "default"
         assignee = profile
     with _conn(board=board) as conn:
+        _clear_stale_fences(conn)
         latest = _latest_event_id(conn)
         if since is not None and since >= latest:
             return {"changed": False, "latest_event_id": latest, "read_only": False}
@@ -327,7 +444,7 @@ def board_payload(params: dict) -> dict:
         link_counts, comment_counts = _link_counts(conn, tasks), _comment_counts(conn)
 
         def row(task):
-            data = _task_dict(task)
+            data = _task_dict(task, conn)
             data["link_counts"] = link_counts.get(task.id, {"parents": 0, "children": 0})
             data["comment_count"] = comment_counts.get(task.id, 0)
             return data
@@ -365,7 +482,7 @@ def create_task_payload(params: dict) -> dict:
         )
         if body.get("status"):
             _patch_task(conn, task_id, {"status": body.get("status")})
-        return {"task": _task_dict(kb.get_task(conn, task_id)), "read_only": False}
+        return {"task": _task_dict(kb.get_task(conn, task_id), conn), "read_only": False}
 
 
 def patch_task_payload(params: dict) -> dict:
@@ -375,7 +492,7 @@ def patch_task_payload(params: dict) -> dict:
     kb = _kb()
     with _conn(board=_board(params)) as conn:
         _patch_task(conn, task_id, params.get("patch") or {})
-        return {"task": _task_dict(kb.get_task(conn, task_id)), "read_only": False}
+        return {"task": _task_dict(kb.get_task(conn, task_id), conn), "read_only": False}
 
 
 def comment_payload(params: dict) -> dict:
@@ -418,7 +535,7 @@ def task_detail_payload(params: dict) -> dict:
         if not task:
             raise NotFound("task not found")
         return {
-            "task": _task_dict(task),
+            "task": _task_dict(task, conn),
             "comments": [_obj_dict(c) for c in kb.list_comments(conn, task_id)],
             "events": [_obj_dict(e) for e in kb.list_events(conn, task_id)],
             "links": {"parents": kb.parent_ids(conn, task_id), "children": kb.child_ids(conn, task_id)},
@@ -533,7 +650,8 @@ def bulk_payload(params: dict) -> dict:
                     results.append(entry)
                     continue
                 if body.get("archive"):
-                    if not kb.archive_task(conn, task_id):
+                    # Bulk carries no running-exit confirmation, so a running row is refused like a card write.
+                    if not _fenced(conn, task_id, lambda: kb.archive_task(conn, task_id), confirm_running_exit=False, releases_claim=False):
                         entry.update(ok=False, error="archive refused")
                 elif body.get("status") is not None:
                     _patch_task(conn, task_id, {"status": body.get("status")})
@@ -555,11 +673,14 @@ def bulk_payload(params: dict) -> dict:
 
 
 def dispatch_payload(params: dict) -> dict:
-    kb = _kb()
-    if not hasattr(kb, "dispatch_once"):
-        raise InvalidParams("dispatcher is unavailable")
+    _kb()
+    try:
+        # Agent 0.21.6 dropped the kanban_db re-export; every supported release defines it here.
+        from hermes_cli.kanban_db_dispatch import dispatch_once
+    except Exception as exc:  # noqa: BLE001
+        raise InvalidParams("dispatcher is unavailable") from exc
     with _conn(board=_board(params)) as conn:
-        result = kb.dispatch_once(conn, dry_run=_bool(params, "dry_run"), max_spawn=_int(params, "max", 8, minimum=1, maximum=100))
+        result = dispatch_once(conn, dry_run=_bool(params, "dry_run"), max_spawn=_int(params, "max", 8, minimum=1, maximum=100))
     if isinstance(result, dict):
         return result
     try:
@@ -578,7 +699,7 @@ def task_action_payload(params: dict) -> dict:
         if not kb.get_task(conn, task_id):
             raise NotFound("task not found")
         if action == "block":
-            ok = kb.block_task(conn, task_id, reason=params.get("reason"))
+            ok = _fenced(conn, task_id, lambda: kb.block_task(conn, task_id, reason=params.get("reason")), confirm_running_exit=bool(params.get("confirm_running_exit")))
         elif action == "unblock":
             if hasattr(kb, "unblock_task"):
                 ok = kb.unblock_task(conn, task_id)
@@ -589,7 +710,7 @@ def task_action_payload(params: dict) -> dict:
             raise InvalidParams(f"invalid action: {action}")
         if not ok:
             raise Conflict(f"{action} refused")
-        return {"task": _task_dict(kb.get_task(conn, task_id)), "read_only": False}
+        return {"task": _task_dict(kb.get_task(conn, task_id), conn), "read_only": False}
 
 
 def list_boards_payload(params: dict) -> dict: