devops-bot-sdk 1.6.73__tar.gz → 1.6.75__tar.gz

{devops_bot_sdk-1.6.73 → devops_bot_sdk-1.6.75}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.6.73
+Version: 1.6.75
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.6.73 → devops_bot_sdk-1.6.75}/devops_bot_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.6.73
+Version: 1.6.75
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.6.73 → devops_bot_sdk-1.6.75}/devops_bot_sdk.egg-info/SOURCES.txt

@@ -141,7 +141,7 @@ sdk/ui/static/schedules.html
 sdk/ui/static/setup.html
 sdk/ui/static/styles.css
 sdk/ui/static/tickets.html
-sdk/vendor/aidraftsman-cli-0.1.0.tgz
+tests/test_activity_claude_runs.py
 tests/test_activity_collectors.py
 tests/test_activity_core.py
 tests/test_activity_live_tracking.py

{devops_bot_sdk-1.6.73 → devops_bot_sdk-1.6.75}/pyproject.toml

@@ -68,7 +68,7 @@ where = ["."]
 include = ["sdk*"]
 
 [tool.setuptools.package-data]
-sdk = ["py.typed", "ui/static/*", "vendor/*.tgz"]
+sdk = ["py.typed", "ui/static/*"]
 
 [tool.ruff]
 line-length   = 100

{devops_bot_sdk-1.6.73 → devops_bot_sdk-1.6.75}/sdk/__init__.py

@@ -1,6 +1,6 @@
 """AgentOS Desktop SDK — thin HTTPS/SSE client for the Electron app.
 
-Version: 1.6.73
+Version: 1.6.75
 
 Public surface:
   BackendClient.from_config()        — create client from ~/.agentos/config.toml
@@ -34,7 +34,7 @@ Rules:
   - All data egress through submit_webhook only
 """
 
-__version__ = "1.6.73"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
+__version__ = "1.6.75"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
 __author__  = "AgentOS"   # sdk.client.SDK_VERSION and the UI server version all read this.
 
 from sdk.client import BackendClient

{devops_bot_sdk-1.6.73 → devops_bot_sdk-1.6.75}/sdk/activity/recorder.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 import logging
 import time
 import uuid
+from contextvars import ContextVar
 from typing import Any
 
 from sdk.activity import settings
@@ -41,6 +42,17 @@ _FILE_TOOLS = {"Write", "Edit", "MultiEdit", "NotebookEdit", "Read"}
 #: SDK-origin records are exact, not inferred — hence full confidence.
 _SDK_CONFIDENCE = 100
 
+#: The agent run open in THIS task's context. ``local_exec.run_claude_local``
+#: records every claude run it starts, unless a caller (agentd) already opened one
+#: around it — this is how the two avoid recording the same run twice. A
+#: ContextVar, not a global: concurrent runs live in separate asyncio tasks.
+_open_run: ContextVar[str | None] = ContextVar("agentos_open_agent_run", default=None)
+
+
+def active_run_id() -> str | None:
+    """The agent run already open in the current context, if any."""
+    return _open_run.get()
+
 
 def record_session(session: ActivitySession) -> bool:
     """Queue a session (or its update). ``False`` when disabled or on any failure."""
@@ -94,6 +106,7 @@ def agent_run_started(
 ) -> str:
     """Record that agentos started an agent run. Returns the session key."""
     key = agent_session_key(run_id)
+    _open_run.set(run_id)
     record_session(
         ActivitySession(
             externalKey=key,
@@ -134,6 +147,8 @@ def agent_run_finished(
 ) -> None:
     """Record the end of an agent run and close its session."""
     key = agent_session_key(run_id)
+    if _open_run.get() == run_id:
+        _open_run.set(None)
     now = time.time()
     record_session(
         ActivitySession(

{devops_bot_sdk-1.6.73 → devops_bot_sdk-1.6.75}/sdk/cli.py

@@ -1383,13 +1383,15 @@ def _browser_command(args: list[str]) -> None:
 # ── fallback ─────────────────────────────────────────────────────────────
 
 def _fallback_usage() -> None:
-    print("usage: agentos fallback install                 # npm-install the bundled CLI now")
+    print("usage: agentos fallback install                 # where `ad` is, or how to install it")
     print("       agentos fallback login [--browser | --api-key [KEY]] [--base-url URL] [--no-browser]")
     print("       agentos fallback status [--verify]       # --verify asks the server too")
     print("       agentos fallback logout")
     print()
-    print("  When the `claude` CLI is not working, tickets re-run on the AI Draftsman CLI")
-    print("  bundled with the SDK. It needs its own login, made as the user the SDK runs as.")
+    print("  When the `claude` CLI is not available (not installed or logged out), tickets")
+    print("  run on the AI Draftsman CLI (`ad`) installed on this machine. A claude usage")
+    print("  limit is NOT a fallback: that run pauses and resumes on claude.")
+    print("  `ad` needs its own login, made as the user the SDK runs as.")
     print()
     print("  --browser       prints a sign-in code and a link; approve it on the AI Draftsman")
     print("                  frontend from any machine — works on a headless VPS")
@@ -1409,14 +1411,15 @@ def _fallback_command(args: list[str]) -> None:
         if le._fallback_disabled():
             print("error: the fallback is disabled (AGENTOS_FALLBACK_CLI=off)")
             sys.exit(1)
-        cli = asyncio.run(le.ensure_fallback_cli())
+        # The SDK no longer installs the CLI: it is updated continuously, so the
+        # copy on the machine is the one to use. This only reports where it is.
+        cli = le.fallback_cli_path()
         if not cli:
-            print("error: could not install the AI Draftsman CLI (Node.js 20+ and npm are needed)")
+            print(f"error: the AI Draftsman CLI (`ad`) was not found. Install it with:\n"
+                  f"  {le.FALLBACK_INSTALL_HINT}\n"
+                  "or point AGENTOS_FALLBACK_CLI at it in ~/.agentos/.env")
             sys.exit(1)
-        print(f"installed: {cli}")
-        ad = Path(cli).with_name("ad.cmd" if cli.lower().endswith(".cmd") else "ad")
-        if ad.exists():
-            print(f"also as  : {ad}   (the same CLI under its short name)")
+        print(f"found    : {cli}")
         print("next     : agentos fallback login")
         return
 

{devops_bot_sdk-1.6.73 → devops_bot_sdk-1.6.75}/sdk/local_exec.py

@@ -1045,16 +1045,23 @@ async def _run_claude_cli(
 
 
 # ── Fallback: the AI Draftsman CLI ─────────────────────────────────────────
-# When the `claude` CLI is not working — not installed, logged out, out of
-# usage, or dying before it even starts a session — the ticket is re-run on
-# our own AI Draftsman CLI (`aidraftsman`, npm package @aidraftsman/cli) instead
-# of failing or parking. It is the same job against the same project dir: the
-# prompt goes in on stdin, `-p --output-format json` prints one JSON object.
-# The CLI is bundled in sdk/vendor/ and npm-installed into ~/.agentos/aidraftsman
-# the first time it is needed; one already on PATH is used instead. It needs
-# its own login on the box, as the user the SDK runs as: `agentos fallback
-# login` (browser sign-in code or an API key), or AD_API_KEY in the env.
-# `agentos fallback status --verify` checks it against the server.
+# When the `claude` CLI is not AVAILABLE — not installed, logged out, or dying
+# before it even starts a session — the ticket runs on our own AI Draftsman CLI
+# (`ad`, npm package @aidraftsman/cli) instead of failing or parking. It is the
+# same job against the same project dir: the prompt goes in on stdin,
+# `-p --output-format json` prints one JSON object.
+#
+# A claude USAGE LIMIT is not "unavailable": that run parks and resumes on the
+# same claude session when the window resets, and is never handed to another
+# model mid-ticket.
+#
+# The CLI is the one already installed on the machine (`ad` on PATH, or an npm
+# global bin dir the service's PATH may not include). The SDK never installs it:
+# it is updated continuously, and a copy pinned inside the SDK went stale the
+# day after it shipped. It needs its own login on the box, as the user the SDK
+# runs as: `agentos fallback login` (browser sign-in code or an API key), or
+# AD_API_KEY in the env. `agentos fallback status --verify` checks it against
+# the server.
 #
 # What it does NOT do: honour the PreToolUse approval guard, resume a Claude
 # session, or stream progress events. So a resumed run never falls back (the
@@ -1064,7 +1071,7 @@ async def _run_claude_cli(
 # AGENTOS_FALLBACK_PERMISSION_MODE=bypass to let it run every command.
 #
 # Settings (process env or ~/.agentos/.env):
-#   AGENTOS_FALLBACK_CLI              path to the CLI (default: PATH, then bundled), or "off"
+#   AGENTOS_FALLBACK_CLI              path to the CLI (default: `ad` on PATH), or "off"
 #   AGENTOS_FALLBACK_AGENT            agent id/name for `--agent` (default: gateway's choice)
 #   AGENTOS_FALLBACK_PERMISSION_MODE  default | acceptEdits | plan | bypass
 
@@ -1082,91 +1089,54 @@ def _setting(key: str) -> str:
         return ""
 
 
-#: The CLI ships inside the SDK (sdk/vendor/*.tgz) so every box has it without
-#: a separate install step; it is npm-installed from there on first use.
-_VENDOR_DIR = Path(__file__).parent / "vendor"
+#: How to get the CLI when it is missing — shown in every "not found" message.
+FALLBACK_INSTALL_HINT = "npm install -g @aidraftsman/cli"
 
 
 def _fallback_disabled() -> bool:
     return _setting("AGENTOS_FALLBACK_CLI").lower() in ("off", "0", "false", "no", "none")
 
 
-def _bundled_tarball() -> Path | None:
-    tarballs = sorted(_VENDOR_DIR.glob("aidraftsman-cli-*.tgz"))
-    return tarballs[-1] if tarballs else None
-
-
-def _bundled_bin(tarball: Path) -> Path:
-    """Where the bundled tarball's `aidraftsman` lands once installed.
-
-    One prefix per tarball name, so an SDK update that ships a new CLI version
-    installs it fresh rather than reusing the old one.
-    """
-    prefix = config._CONFIG_DIR / "aidraftsman" / tarball.name.removesuffix(".tgz")
-    name = "aidraftsman.cmd" if sys.platform == "win32" else "aidraftsman"
-    return prefix / "node_modules" / ".bin" / name
+def _npm_global_bins() -> list[Path]:
+    """npm's global bin dirs, for a service whose PATH does not include them."""
+    if sys.platform == "win32":
+        appdata = os.environ.get("APPDATA")
+        return [Path(appdata) / "npm"] if appdata else []
+    home = Path.home()
+    return [home / ".npm-global" / "bin", home / ".local" / "bin",
+            Path("/usr/local/bin"), Path("/usr/bin")]
 
 
 def fallback_cli_path() -> str | None:
-    """Absolute path to an installed `aidraftsman` CLI, or None if absent or disabled.
+    """Absolute path to the installed AI Draftsman CLI, or None if absent or disabled.
 
-    Resolution order: ``AGENTOS_FALLBACK_CLI``, then ``aidraftsman`` or ``ad``
-    on ``PATH``, then the copy installed from the bundled tarball. Never installs anything — see
-    :func:`ensure_fallback_cli` for that.
+    Resolution order: ``AGENTOS_FALLBACK_CLI``, then ``ad`` (and its long name
+    ``aidraftsman``) on ``PATH``, then npm's global bin dirs. Never installs
+    anything — the CLI on the machine is the one kept up to date.
     """
     if _fallback_disabled():
         return None
     override = _setting("AGENTOS_FALLBACK_CLI")
     if override and Path(override).exists():
         return override
-    # The package installs the same entry point under two names; a box may
-    # only have `ad` on PATH.
-    for name in ("aidraftsman", "ad"):
+    names = ("ad", "aidraftsman")
+    for name in names:
         found = shutil.which(name)
         if found:
             return found
-    tarball = _bundled_tarball()
-    if tarball and _bundled_bin(tarball).exists():
-        return str(_bundled_bin(tarball))
+    suffixes = (".cmd", ".exe", "") if sys.platform == "win32" else ("",)
+    for d in _npm_global_bins():
+        for name in names:
+            for suffix in suffixes:
+                candidate = d / f"{name}{suffix}"
+                if candidate.is_file():
+                    return str(candidate)
     return None
 
 
-def _install_bundled(tarball: Path) -> str | None:
-    """``npm install`` the bundled tarball into a private prefix (no sudo, no -g)."""
-    npm = shutil.which("npm")
-    if not npm:
-        print("aidraftsman fallback unavailable: npm not found (Node.js 20+ required)", flush=True)
-        return None
-    bin_path = _bundled_bin(tarball)
-    prefix = bin_path.parents[2]
-    prefix.mkdir(parents=True, exist_ok=True)
-    cmd = [npm, "install", "--prefix", str(prefix), "--no-audit", "--no-fund",
-           "--omit=dev", str(tarball)]
-    if sys.platform == "win32" and npm.lower().endswith((".cmd", ".bat")):
-        cmd = [os.environ.get("COMSPEC", "cmd.exe"), "/c", *cmd]
-    print(f"installing bundled {tarball.name} into {prefix}", flush=True)
-    try:
-        proc = subprocess.run(cmd, capture_output=True, text=True, errors="replace",
-                              timeout=600)
-    except Exception as exc:  # noqa: BLE001 — never raise into a ticket run
-        print(f"aidraftsman install failed: {exc}", flush=True)
-        return None
-    if proc.returncode != 0 or not bin_path.exists():
-        print(f"aidraftsman install failed: {(proc.stderr or proc.stdout).strip()[-300:]}",
-              flush=True)
-        return None
-    return str(bin_path)
-
-
 async def ensure_fallback_cli() -> str | None:
-    """:func:`fallback_cli_path`, installing the bundled CLI first if needed."""
-    found = fallback_cli_path()
-    if found or _fallback_disabled():
-        return found
-    tarball = _bundled_tarball()
-    if not tarball:
-        return None
-    return await asyncio.to_thread(_install_bundled, tarball)
+    """:func:`fallback_cli_path`. Kept for callers; it no longer installs anything."""
+    return fallback_cli_path()
 
 
 def _fallback_argv(cli: str, *args: str) -> list[str]:
@@ -1200,7 +1170,7 @@ def fallback_status(*, verify: bool = False, timeout: float = 20.0) -> dict:
         return out
     cli = fallback_cli_path()
     if not cli:
-        out["error"] = "not installed — run `agentos fallback install`"
+        out["error"] = f"`ad` not found — install it with `{FALLBACK_INSTALL_HINT}`"
         return out
     out.update(installed=True, path=cli)
     try:
@@ -1238,8 +1208,8 @@ def fallback_status(*, verify: bool = False, timeout: float = 20.0) -> dict:
 #: Shown when neither CLI can take a ticket; the entry points' "CLI missing" error.
 NO_LOCAL_CLI_MESSAGE = (
     "Neither the Claude Code CLI nor the AI Draftsman fallback is ready on this "
-    "machine. Install claude and run `claude setup-token`, or run "
-    "`agentos fallback install` then `agentos fallback login`."
+    "machine. Install claude and run `claude setup-token`, or install the AI "
+    f"Draftsman CLI (`{FALLBACK_INSTALL_HINT}`) and run `agentos fallback login`."
 )
 
 
@@ -1274,13 +1244,12 @@ def fallback_login(*, method: str | None = None, api_key: str | None = None,
     a link to approve on the AI Draftsman frontend (works on a headless VPS: open
     the link on any machine), ``method="api-key"`` validates and stores a key
     from Settings → API keys (prompted with hidden input when ``api_key`` is not
-    given). ``None`` shows the CLI's own menu. Installs the bundled CLI first.
+    given). ``None`` shows the CLI's own menu.
     """
-    cli = asyncio.run(ensure_fallback_cli())
+    cli = fallback_cli_path()
     if not cli:
-        print("error: the AI Draftsman CLI is not available "
-              "(Node.js 20+ and npm are needed to install the bundled copy, "
-              "or it is disabled with AGENTOS_FALLBACK_CLI=off)")
+        print("error: the AI Draftsman CLI (`ad`) was not found — install it with "
+              f"`{FALLBACK_INSTALL_HINT}` (or it is disabled with AGENTOS_FALLBACK_CLI=off)")
         return 1
     args = ["auth", "login"]
     if api_key:
@@ -1317,7 +1286,11 @@ def _claude_not_working(result: dict[str, Any]) -> bool:
     """
     if result.get("ok"):
         return False
-    if result.get("auth_expired") or result.get("limit_exceeded"):
+    if result.get("limit_exceeded"):
+        # Out of usage is not "unavailable": the run parks and resumes on the same
+        # claude session when the window resets (local_exec's limit handling).
+        return False
+    if result.get("auth_expired"):
         return True
     if result.get("context_exceeded") or result.get("output_cap_exceeded"):
         return False
@@ -1356,9 +1329,8 @@ async def run_fallback_cli(
     """Run ``prompt`` on the AI Draftsman CLI. Same result shape as the claude run."""
     cli = await ensure_fallback_cli()
     if not cli:
-        return _result(ok=False, error="AI Draftsman CLI not available (needs Node.js 20+ "
-                                       "and npm to install the bundled copy; "
-                                       "`agentos fallback install`).",
+        return _result(ok=False, error="AI Draftsman CLI (`ad`) not found on this "
+                                       f"machine — install it with `{FALLBACK_INSTALL_HINT}`.",
                        tier=tier, provider=provider)
 
     path = Path(project_path).expanduser()
@@ -1462,11 +1434,94 @@ async def run_claude_local(
     settings_env: dict[str, str] | None = None,
     tier: str | None = None,
     provider: str | None = None,
+    activity_label: str | None = None,
 ) -> dict[str, Any]:
     """Run the local `claude` CLI; if the CLI itself is not working, re-run on
     the AI Draftsman CLI. See ``_run_claude_cli`` for the arguments and the
     result shape, and the fallback notes above ``run_fallback_cli``.
+
+    Every run is recorded in the VPS activity trail as an AGENT_RUN session with
+    its tool calls — ticket runs, scheduled runs and panel runs alike, since they
+    all come through here. Before this only agentd recorded its runs, so the
+    trail showed no agent work at all for most VPSes. A caller that already
+    opened a run (agentd) is left to record its own; ``activity_label`` names the
+    run, defaulting to the repository it ran in.
     """
+    from sdk.activity import recorder as _audit
+
+    if _audit.active_run_id() is not None:
+        return await _run_claude_local(
+            prompt, project_path, allowed_tools=allowed_tools, on_event=on_event,
+            timeout=timeout, github_token=github_token,
+            resume_session_id=resume_session_id, approval_dir=approval_dir,
+            idle_timeout=idle_timeout, max_output_tokens=max_output_tokens,
+            extra_env=extra_env, unset_env=unset_env, settings_env=settings_env,
+            tier=tier, provider=provider,
+        )
+
+    import uuid as _uuid
+
+    run_id = str(_uuid.uuid4())
+    label = activity_label or f"claude: {Path(project_path).name or project_path}"
+    _audit.agent_run_started(run_id, agent_name=label[:255])
+
+    async def _audited(event: dict) -> None:
+        if isinstance(event, dict) and event.get("type") == "assistant":
+            content = (event.get("message") or {}).get("content") or []
+            for block in content:
+                if isinstance(block, dict) and block.get("type") == "tool_use":
+                    _audit.agent_tool_call(run_id, str(block.get("name") or "tool"),
+                                           block.get("input"))
+        if on_event is not None:
+            await on_event(event)
+
+    try:
+        result = await _run_claude_local(
+            prompt, project_path, allowed_tools=allowed_tools, on_event=_audited,
+            timeout=timeout, github_token=github_token,
+            resume_session_id=resume_session_id, approval_dir=approval_dir,
+            idle_timeout=idle_timeout, max_output_tokens=max_output_tokens,
+            extra_env={**(extra_env or {}), "AGENTOS_ACTOR": "agent",
+                       "AGENTOS_RUN_ID": run_id},
+            unset_env=unset_env, settings_env=settings_env, tier=tier, provider=provider,
+        )
+    except BaseException as exc:  # incl. CancelledError: the session must still close
+        _audit.agent_run_finished(run_id, ok=False, agent_name=label[:255],
+                                  detail=(str(exc) or type(exc).__name__)[:500])
+        raise
+    ok = bool(result.get("ok"))
+    _audit.agent_run_finished(run_id, ok=ok, agent_name=label[:255],
+                              detail=None if ok else str(result.get("error") or "")[:500])
+    return result
+
+
+async def _run_claude_local(
+    prompt: str,
+    project_path: str,
+    *,
+    allowed_tools: list[str] | None,
+    on_event: EventHandler | None,
+    timeout: float,
+    github_token: str | None,
+    resume_session_id: str | None,
+    approval_dir: str | None,
+    idle_timeout: float,
+    max_output_tokens: int | None,
+    extra_env: dict[str, str] | None,
+    unset_env: list[str] | None,
+    settings_env: dict[str, str] | None,
+    tier: str | None,
+    provider: str | None,
+) -> dict[str, Any]:
+    """The un-audited body of :func:`run_claude_local`."""
+    if not resume_session_id and not is_available() and fallback_cli_path():
+        # No claude here at all: go straight to `ad` rather than spawn a
+        # process that cannot exist just to learn that it failed.
+        print("claude CLI not installed — running on the AI Draftsman CLI", flush=True)
+        return await run_fallback_cli(
+            prompt, project_path, timeout=timeout, github_token=github_token,
+            extra_env=extra_env, tier=tier, provider=provider,
+        )
     result = await _run_claude_cli(
         prompt, project_path,
         allowed_tools=allowed_tools, on_event=on_event, timeout=timeout,

devops_bot_sdk-1.6.75/tests/test_activity_claude_runs.py

@@ -0,0 +1,134 @@
+"""Every claude run is recorded in the VPS activity trail as an AGENT_RUN session.
+
+Before this, only agentd recorded its runs. Ticket runs (the auto-loop),
+scheduled runs and panel runs all reach ``local_exec.run_claude_local`` and
+recorded nothing, so most VPSes showed no agent work at all — and a run that
+failed (a logged-out ``claude``) left no trace of having been attempted.
+"""
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+
+from sdk import local_exec
+from sdk.activity import recorder, settings
+
+
+@pytest.fixture(autouse=True)
+def _isolated(tmp_path, monkeypatch):
+    import sdk.config as cfg
+
+    monkeypatch.setattr(cfg, "_dotenv_value", lambda key: "")
+    for name in ("AGENTOS_ACTIVITY", "AGENTOS_ACTIVITY_AUDIT"):
+        monkeypatch.delenv(name, raising=False)
+    monkeypatch.setattr(settings, "spool_path", lambda: tmp_path / "activity.db")
+    settings.reset_spool()
+    yield
+    settings.reset_spool()
+
+
+def _queued():
+    chunk = settings.get_spool().next_chunk()
+    rows = sorted(chunk.rows, key=lambda r: r.seq) if chunk else []
+    return ([r.wire for r in rows if r.kind == "session"],
+            [r.wire for r in rows if r.kind == "event"])
+
+
+def _fake_cli(monkeypatch, result, events=(), seen=None):
+    async def fake(prompt, project_path, **kw):
+        if seen is not None:
+            seen.update(kw)
+        for ev in events if kw["on_event"] else ():
+            await kw["on_event"](ev)
+        if isinstance(result, BaseException):
+            raise result
+        return result
+
+    monkeypatch.setattr(local_exec, "_run_claude_cli", fake)
+    monkeypatch.setattr(local_exec, "_claude_not_working", lambda r: False)
+
+
+_TOOL_EVENT = {"type": "assistant", "message": {"content": [
+    {"type": "text", "text": "editing"},
+    {"type": "tool_use", "name": "Edit", "input": {"file_path": "/repo/app.py"}},
+]}}
+
+
+def test_a_successful_run_is_an_agent_session_with_its_tool_calls(monkeypatch):
+    seen: dict = {}
+    forwarded: list = []
+
+    async def caller_hook(ev):
+        forwarded.append(ev)
+
+    _fake_cli(monkeypatch, {"ok": True, "result": "done"}, [_TOOL_EVENT], seen)
+    out = asyncio.run(local_exec.run_claude_local("p", "/work/wellnessgram",
+                                                  on_event=caller_hook))
+
+    assert out["ok"] is True
+    assert forwarded == [_TOOL_EVENT]          # the caller's own hook still runs
+    sessions, events = _queued()
+    assert {s["kind"] for s in sessions} == {"AGENT_RUN"}
+    run_id = sessions[0]["agentRunId"]
+    assert "endedAt" in sessions[-1]
+    assert [(e["category"], e["action"]) for e in events] == [
+        ("AGENT_RUN", "run.start"), ("AGENT_TOOL_CALL", "Edit"), ("AGENT_RUN", "run.end")]
+    assert {e["agentRunId"] for e in events} == {run_id}
+    assert events[0]["processName"] == "claude: wellnessgram"
+    assert events[1]["target"] == "/repo/app.py"
+    assert events[-1]["exitCode"] == 0
+    # the child process is tagged so OS-level events can be tied to the run
+    assert seen["extra_env"]["AGENTOS_RUN_ID"] == run_id
+    assert seen["extra_env"]["AGENTOS_ACTOR"] == "agent"
+
+
+def test_a_failed_run_is_recorded_with_its_error(monkeypatch):
+    _fake_cli(monkeypatch, {"ok": False, "error": "Not logged in · Please run /login"})
+    asyncio.run(local_exec.run_claude_local("p", "/work/repo", activity_label="ticket AP2-1"))
+
+    _, events = _queued()
+    end = events[-1]
+    assert (end["action"], end["exitCode"], end["severity"]) == ("run.end", 1, "WARNING")
+    assert "Not logged in" in end["target"]
+    assert events[0]["processName"] == "ticket AP2-1"
+
+
+def test_a_crashed_or_cancelled_run_still_closes_its_session(monkeypatch):
+    _fake_cli(monkeypatch, asyncio.CancelledError())
+    with pytest.raises(asyncio.CancelledError):
+        asyncio.run(local_exec.run_claude_local("p", "/work/repo"))
+
+    sessions, events = _queued()
+    assert "endedAt" in sessions[-1]
+    assert (events[-1]["action"], events[-1]["exitCode"]) == ("run.end", 1)
+    assert recorder.active_run_id() is None
+
+
+def test_a_run_inside_an_agentd_run_is_not_recorded_twice(monkeypatch):
+    seen: dict = {}
+    _fake_cli(monkeypatch, {"ok": True}, [_TOOL_EVENT], seen)
+
+    async def agentd_style():
+        recorder.agent_run_started("RUN-OUTER", agent_name="my-agent")
+        await local_exec.run_claude_local("p", "/work/repo")
+        recorder.agent_run_finished("RUN-OUTER", ok=True, agent_name="my-agent")
+
+    asyncio.run(agentd_style())
+
+    sessions, events = _queued()
+    assert {s["agentRunId"] for s in sessions} == {"RUN-OUTER"}
+    assert [e["action"] for e in events] == ["run.start", "run.end"]
+    assert "AGENTOS_RUN_ID" not in (seen["extra_env"] or {})
+
+
+def test_the_open_run_is_released_when_the_run_ends(monkeypatch):
+    _fake_cli(monkeypatch, {"ok": True})
+
+    async def two_runs():
+        await local_exec.run_claude_local("p", "/work/a")
+        await local_exec.run_claude_local("p", "/work/b")
+
+    asyncio.run(two_runs())
+    sessions, _ = _queued()
+    assert len({s["agentRunId"] for s in sessions}) == 2