@phnx-labs/agents-cli 1.22.52 → 1.22.53

package/dist/lib/feed/feed.d.ts

@@ -76,7 +76,12 @@ export interface OpenBlock {
     source?: AttentionSource;
     /** Lifecycle state. Derived from the answer/continue markers when absent — see {@link deriveBlockState}. */
     state?: AttentionState;
-    /** Where in the source this block's generation sits — carried onto its resolution tombstone. */
+    /**
+     * Where in the source this block's generation sits — stamped at write time
+     * (`buildDeclaredBlock`, the feed-publish hook) and carried onto its resolution
+     * tombstone. Without a write-time cursor a new generation is suppressed whenever
+     * `session.lastActivityMs` is unresolvable (cloud / remote / index-lag).
+     */
     sourceCursor?: SourceCursor;
     /** Indexed launch origin, added at read time when the live session is known. */
     origin?: 'cli' | 'routine';
@@ -319,6 +324,9 @@ export interface DeclareBlockInput {
  * `costOfDelay: high` because a declared block is, by definition, an agent that
  * has already stopped making progress — that is what makes it worth interrupting
  * someone over, and what `feed --dispatch`'s urgency filter keys off.
+ *
+ * `sourceCursor` is stamped from `ts` at write time so a fresh generation is
+ * comparable even when the live session's `lastActivityMs` is unresolvable.
  */
 export declare function buildDeclaredBlock(agent: DeclaringAgent, input: DeclareBlockInput): OpenBlock;
 /** Atomic write a block record to the feed store. Clears stale lifecycle state. */
@@ -334,7 +342,7 @@ export declare function removeBlock(blockId: string, root?: string): boolean;
  * Embedded so it ships with the compiled CLI and can be installed to the
  * CLI-writable user hooks dir without a separate file in the npm tarball.
  */
-export declare const FEED_PUBLISH_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"Publish and clear open-block records for `agents feed`.\n\nThe manifest invokes this script for top-level AskUserQuestion calls, waiting\nnotifications, question answers, and session lifecycle events. One atomic file\nper session means a new block replaces the previous block. Answer/resume/stop\nevents remove it so `agents feed` only lists decisions that are still open.\n\nSub-agent gate: when the PreToolUse payload carries `agent_type`, this is a\nTask/Agent subagent -- skip. Only the top-level agent publishes. Verified on\nClaude Code 2.1.170 (2026-07).\n\nFail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport sys\nimport json\nimport re\nimport socket\nimport tempfile\nfrom datetime import datetime, timezone\n\nWAITING_NOTIFICATION_TYPES = {\n    \"permission_prompt\",\n    \"idle_prompt\",\n    \"elicitation_dialog\",\n}\nCLEAR_EVENTS = {\n    \"PostToolUse\",\n    \"Stop\",\n    \"SessionEnd\",\n}\n# Codex emits a PermissionRequest event (not Claude's Notification) when it\n# blocks on an approval prompt. Claude never fires PermissionRequest, so the\n# same script handles both: PermissionRequest maps to an approval-class block\n# with a high cost-of-delay so 'agents feed --dispatch' pages it as urgent.\n\n\ndef read_json(path):\n    try:\n        with open(path) as f:\n            return json.load(f)\n    except Exception:\n        return None\n\n\ndef write_json(path, value):\n    dir_name = os.path.dirname(path)\n    os.makedirs(dir_name, exist_ok=True)\n    fd, tmp = tempfile.mkstemp(dir=dir_name, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(value, f, indent=2)\n        os.replace(tmp, path)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\ndef project_from_cwd(cwd):\n    \"\"\"Basename of cwd, with worktree paths resolved to their repo name.\"\"\"\n    if not cwd:\n        return None\n    norm = cwd.replace(\"\\\\\", \"/\").rstrip(\"/\")\n    if not norm:\n        return None\n    marker = \"/.agents/worktrees/\"\n    idx = norm.find(marker)\n    if idx > 0:\n        repo_path = norm[:idx]\n        base = repo_path[repo_path.rfind(\"/\") + 1:]\n        if base:\n            return base\n    base = norm[norm.rfind(\"/\") + 1:]\n    return base or None\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate.\n    if payload.get(\"agent_type\"):\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    safe_session_id = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id)\n    block_id = f\"block-{safe_session_id}\"\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    feed_dir = os.path.join(home, \".agents\", \".history\", \"feed\")\n    answered_dir = os.path.join(feed_dir, \"answered\")\n    asks_dir = os.path.join(feed_dir, \"asks\")\n    target = os.path.join(feed_dir, f\"{block_id}.json\")\n    hook_event = payload.get(\"hook_event_name\", \"PreToolUse\")\n\n    if hook_event in CLEAR_EVENTS:\n        # A declared block (`agents feed post --blocked`) is the agent explicitly\n        # saying it is stuck. Unlike a question/notification/approval block -- which\n        # tracks an in-flight harness prompt that a lifecycle event resolves -- a\n        # declared block stays open until it is actually ANSWERED. So while it is\n        # still UNANSWERED, Stop/SessionEnd/PostToolUse must never silently drop it:\n        # otherwise the needs-you record vanishes the moment the agent parks the block\n        # and its turn ends -- exactly when the owner still needs to see and answer it.\n        # Once it IS answered (an answered marker exists), it clears like any other\n        # block by falling through below -- which frees that marker too, so a later\n        # `--blocked` in the same session is not falsely locked as already-answered\n        # (recordAnswer creates the marker with O_EXCL).\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            answered = os.path.exists(os.path.join(answered_dir, f\"{block_id}.json\"))\n            if existing.get(\"kind\") == \"declared\" and not answered:\n                return\n        except Exception:\n            pass\n        # A matcher-less PostToolUse clear (registered for Codex so an approved\n        # tool clears its approval card) must NOT wipe an open AskUserQuestion\n        # while an unrelated tool runs mid-question -- those are cleared only by\n        # the AskUserQuestion-matched PostToolUse. So on PostToolUse, keep a\n        # 'question' block; approval/notification blocks clear once the tool runs.\n        if hook_event == \"PostToolUse\":\n            try:\n                with open(target) as existing_file:\n                    existing = json.load(existing_file)\n                if existing.get(\"kind\") == \"question\" and payload.get(\"tool_name\") != \"AskUserQuestion\":\n                    return\n            except Exception:\n                pass\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        # Also clear the answered marker so a future question for this session\n        # is not permanently locked.\n        try:\n            os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    # Terminal answers (human typed in the TUI) record an answered marker and\n    # remove the block file so the feed stops showing it within one poll cycle.\n    # The marker stays behind so a concurrent surface cannot double-answer.\n    if hook_event == \"UserPromptSubmit\":\n        os.makedirs(answered_dir, exist_ok=True)\n        marker = os.path.join(answered_dir, f\"{block_id}.json\")\n        try:\n            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)\n            record = {\n                \"answeredAt\": datetime.now(timezone.utc).isoformat(),\n                \"answeredFrom\": \"terminal\",\n            }\n            with os.fdopen(fd, \"w\") as f:\n                json.dump(record, f, indent=2)\n        except FileExistsError:\n            pass\n        except Exception:\n            pass\n        # Remove the visible block so the feed drops the answered question.\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    notification_type = None\n    codex_approval = False\n    if hook_event == \"Notification\":\n        notification_type = payload.get(\"notification_type\", \"\")\n        if notification_type not in WAITING_NOTIFICATION_TYPES:\n            return\n        # Claude emits a generic permission notification after presenting an\n        # AskUserQuestion. Keep the structured questions and options already\n        # published for this session instead of replacing them with that less\n        # useful notification text.\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            if existing.get(\"kind\") == \"question\":\n                return\n        except Exception:\n            pass\n        message = payload.get(\"message\", \"\")\n        if not message:\n            return\n        normalized_questions = [{\n            \"text\": message,\n            \"header\": payload.get(\"title\") or notification_type.replace(\"_\", \" \").title(),\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n    elif hook_event == \"PermissionRequest\":\n        # Codex approval prompt. The payload mirrors PreToolUse (tool_name,\n        # tool_input) but carries no questions -- Codex is asking to run a tool,\n        # not asking the operator a multiple-choice question. Publish it as a\n        # notification-kind approval block naming the tool so the feed and the\n        # phone notifier can surface it, and so AGI EXT can bridge\n        # it to a VS Code notification.\n        tool_name = payload.get(\"tool_name\") or \"a tool\"\n        tool_input = payload.get(\"tool_input\", {})\n        command = \"\"\n        if isinstance(tool_input, dict):\n            command = (\n                tool_input.get(\"command\")\n                or tool_input.get(\"cmd\")\n                or tool_input.get(\"path\")\n                or \"\"\n            )\n            if isinstance(command, list):\n                command = \" \".join(str(c) for c in command)\n        detail = f\": {command}\" if command else \"\"\n        normalized_questions = [{\n            \"text\": f\"Codex needs approval to run {tool_name}{detail}\",\n            \"header\": \"Approval needed\",\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n        notification_type = \"permission_prompt\"\n        codex_approval = True\n    else:\n        tool_input = payload.get(\"tool_input\", {})\n        questions = tool_input.get(\"questions\", [])\n        if not questions:\n            return\n        normalized_questions = []\n        for q in questions:\n            if not isinstance(q, dict):\n                continue\n            question = {\n                \"text\": q.get(\"question\", q.get(\"header\", \"\")),\n                \"header\": q.get(\"header\"),\n                \"multiSelect\": q.get(\"multiSelect\", False),\n            }\n            raw_opts = q.get(\"options\", [])\n            if raw_opts:\n                question[\"options\"] = [\n                    {\"label\": o.get(\"label\", \"\"), \"description\": o.get(\"description\")}\n                    for o in raw_opts\n                    if isinstance(o, dict)\n                ]\n            normalized_questions.append(question)\n        if not normalized_questions:\n            return\n        kind = \"question\"\n\n    # Identity from env (set by agents-cli at spawn).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n\n    now_iso = datetime.now(timezone.utc).isoformat()\n    stats_path = os.path.join(asks_dir, f\"{safe_session_id}.json\")\n    stats = read_json(stats_path) or {}\n    recent = stats.get(\"recentAskTimestamps\") if isinstance(stats, dict) else []\n    if not isinstance(recent, list):\n        recent = []\n    recent.append(now_iso)\n    # Keep enough history for rolling one-hour needy detection without unbounded\n    # per-session files. The TypeScript reader applies the exact time window.\n    recent = recent[-200:]\n    write_json(stats_path, {\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"firstAskAt\": stats.get(\"firstAskAt\") or now_iso,\n        \"lastAskAt\": now_iso,\n        \"totalAskCount\": int(stats.get(\"totalAskCount\") or 0) + 1,\n        \"recentAskTimestamps\": recent,\n    })\n\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = hostname.split(\".\")[0].strip().lower()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", host) or \"unknown\"\n\n    runtime = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n    cwd = payload.get(\"cwd\") or os.environ.get(\"AGENTS_CWD\")\n    project = project_from_cwd(cwd)\n\n    block = {\n        \"blockId\": block_id,\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"host\": host,\n        \"runtime\": runtime,\n        \"ts\": now_iso,\n        \"questions\": normalized_questions,\n        \"kind\": kind,\n    }\n    if project:\n        block[\"project\"] = project\n    if notification_type:\n        block[\"notificationType\"] = notification_type\n\n    # A Codex PermissionRequest is a real approval gate: mark it approval-class\n    # with a high cost-of-delay so 'agents feed --dispatch' classifies it urgent\n    # (isPhoneUrgent gates on costOfDelay >= phoneNotifyThreshold, default\n    # 'medium') and pages the phone. A plain 'deny' is the safe default.\n    if codex_approval:\n        block[\"blockClass\"] = \"approval\"\n        block[\"costOfDelay\"] = \"high\"\n        block[\"safeDefault\"] = \"deny\"\n\n    # Optional multi-operator control metadata passed by the agent in the\n    # AskUserQuestion tool_input. Defaults keep the existing behavior. A Codex\n    # PermissionRequest carries tool ARGS in tool_input (command/path), not\n    # operator controls, so it is excluded here -- its class/cost is stamped\n    # above from codex_approval.\n    controls = payload.get(\"tool_input\", {}) if hook_event not in (\"Notification\", \"PermissionRequest\") else {}\n    block_class = controls.get(\"blockClass\") if isinstance(controls, dict) else None\n    if block_class in (\"approval\", \"decision\"):\n        block[\"blockClass\"] = block_class\n    consequence = controls.get(\"consequence\") if isinstance(controls, dict) else None\n    if consequence:\n        block[\"consequence\"] = consequence\n    allowed = controls.get(\"allowedOperators\") if isinstance(controls, dict) else None\n    if isinstance(allowed, list):\n        block[\"allowedOperators\"] = [str(a) for a in allowed]\n    timeout = controls.get(\"timeoutMinutes\") if isinstance(controls, dict) else None\n    if isinstance(timeout, (int, float)) and timeout > 0:\n        block[\"timeoutMinutes\"] = int(timeout)\n    safe_default = controls.get(\"safeDefault\") if isinstance(controls, dict) else None\n    if isinstance(safe_default, str):\n        block[\"safeDefault\"] = safe_default\n    cost = controls.get(\"costOfDelay\") if isinstance(controls, dict) else None\n    if cost in (\"low\", \"medium\", \"high\"):\n        block[\"costOfDelay\"] = cost\n\n    # Publishing a new question clears any stale answered marker from the\n    # previous question in this session.\n    try:\n        os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n    except FileNotFoundError:\n        pass\n    except Exception:\n        pass\n\n    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a\n    # HOME override on every platform. Use the same anchor so hooks and the CLI\n    # always read/write one feed store (including temp-home and sandbox runs).\n    os.makedirs(feed_dir, exist_ok=True)\n\n    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(block, f, indent=2)\n        os.replace(tmp, target)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
+export declare const FEED_PUBLISH_HOOK_SCRIPT = "#!/usr/bin/env python3\n\"\"\"Publish and clear open-block records for `agents feed`.\n\nThe manifest invokes this script for top-level AskUserQuestion calls, waiting\nnotifications, question answers, and session lifecycle events. One atomic file\nper session means a new block replaces the previous block. Answer/resume/stop\nevents remove it so `agents feed` only lists decisions that are still open.\n\nSub-agent gate: when the PreToolUse payload carries `agent_type`, this is a\nTask/Agent subagent -- skip. Only the top-level agent publishes. Verified on\nClaude Code 2.1.170 (2026-07).\n\nFail-open: ANY error is swallowed so a feed hiccup never blocks a tool call.\n\"\"\"\nimport os\nimport sys\nimport json\nimport re\nimport socket\nimport tempfile\nfrom datetime import datetime, timezone\n\nWAITING_NOTIFICATION_TYPES = {\n    \"permission_prompt\",\n    \"idle_prompt\",\n    \"elicitation_dialog\",\n}\nCLEAR_EVENTS = {\n    \"PostToolUse\",\n    \"Stop\",\n    \"SessionEnd\",\n}\n# Codex emits a PermissionRequest event (not Claude's Notification) when it\n# blocks on an approval prompt. Claude never fires PermissionRequest, so the\n# same script handles both: PermissionRequest maps to an approval-class block\n# with a high cost-of-delay so 'agents feed --dispatch' pages it as urgent.\n\n\ndef read_json(path):\n    try:\n        with open(path) as f:\n            return json.load(f)\n    except Exception:\n        return None\n\n\ndef write_json(path, value):\n    dir_name = os.path.dirname(path)\n    os.makedirs(dir_name, exist_ok=True)\n    fd, tmp = tempfile.mkstemp(dir=dir_name, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(value, f, indent=2)\n        os.replace(tmp, path)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\ndef project_from_cwd(cwd):\n    \"\"\"Basename of cwd, with worktree paths resolved to their repo name.\"\"\"\n    if not cwd:\n        return None\n    norm = cwd.replace(\"\\\\\", \"/\").rstrip(\"/\")\n    if not norm:\n        return None\n    marker = \"/.agents/worktrees/\"\n    idx = norm.find(marker)\n    if idx > 0:\n        repo_path = norm[:idx]\n        base = repo_path[repo_path.rfind(\"/\") + 1:]\n        if base:\n            return base\n    base = norm[norm.rfind(\"/\") + 1:]\n    return base or None\n\n\ndef main():\n    raw = sys.stdin.read()\n    try:\n        payload = json.loads(raw) if raw.strip() else {}\n    except Exception:\n        return\n\n    # Sub-agent gate.\n    if payload.get(\"agent_type\"):\n        return\n\n    session_id = payload.get(\"session_id\", \"\")\n    if not session_id:\n        return\n\n    safe_session_id = re.sub(r\"[^A-Za-z0-9._-]\", \"-\", session_id)\n    block_id = f\"block-{safe_session_id}\"\n    home = os.environ.get(\"HOME\") or os.path.expanduser(\"~\")\n    feed_dir = os.path.join(home, \".agents\", \".history\", \"feed\")\n    answered_dir = os.path.join(feed_dir, \"answered\")\n    asks_dir = os.path.join(feed_dir, \"asks\")\n    target = os.path.join(feed_dir, f\"{block_id}.json\")\n    hook_event = payload.get(\"hook_event_name\", \"PreToolUse\")\n\n    if hook_event in CLEAR_EVENTS:\n        # A declared block (`agents feed post --blocked`) is the agent explicitly\n        # saying it is stuck. Unlike a question/notification/approval block -- which\n        # tracks an in-flight harness prompt that a lifecycle event resolves -- a\n        # declared block stays open until it is actually ANSWERED. So while it is\n        # still UNANSWERED, Stop/SessionEnd/PostToolUse must never silently drop it:\n        # otherwise the needs-you record vanishes the moment the agent parks the block\n        # and its turn ends -- exactly when the owner still needs to see and answer it.\n        # Once it IS answered (an answered marker exists), it clears like any other\n        # block by falling through below -- which frees that marker too, so a later\n        # `--blocked` in the same session is not falsely locked as already-answered\n        # (recordAnswer creates the marker with O_EXCL).\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            answered = os.path.exists(os.path.join(answered_dir, f\"{block_id}.json\"))\n            if existing.get(\"kind\") == \"declared\" and not answered:\n                return\n        except Exception:\n            pass\n        # A matcher-less PostToolUse clear (registered for Codex so an approved\n        # tool clears its approval card) must NOT wipe an open AskUserQuestion\n        # while an unrelated tool runs mid-question -- those are cleared only by\n        # the AskUserQuestion-matched PostToolUse. So on PostToolUse, keep a\n        # 'question' block; approval/notification blocks clear once the tool runs.\n        if hook_event == \"PostToolUse\":\n            try:\n                with open(target) as existing_file:\n                    existing = json.load(existing_file)\n                if existing.get(\"kind\") == \"question\" and payload.get(\"tool_name\") != \"AskUserQuestion\":\n                    return\n            except Exception:\n                pass\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        # Also clear the answered marker so a future question for this session\n        # is not permanently locked.\n        try:\n            os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    # Terminal answers (human typed in the TUI) record an answered marker and\n    # remove the block file so the feed stops showing it within one poll cycle.\n    # The marker stays behind so a concurrent surface cannot double-answer.\n    if hook_event == \"UserPromptSubmit\":\n        os.makedirs(answered_dir, exist_ok=True)\n        marker = os.path.join(answered_dir, f\"{block_id}.json\")\n        try:\n            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)\n            record = {\n                \"answeredAt\": datetime.now(timezone.utc).isoformat(),\n                \"answeredFrom\": \"terminal\",\n            }\n            with os.fdopen(fd, \"w\") as f:\n                json.dump(record, f, indent=2)\n        except FileExistsError:\n            pass\n        except Exception:\n            pass\n        # Remove the visible block so the feed drops the answered question.\n        try:\n            os.unlink(target)\n        except FileNotFoundError:\n            pass\n        except Exception:\n            pass\n        return\n\n    notification_type = None\n    codex_approval = False\n    if hook_event == \"Notification\":\n        notification_type = payload.get(\"notification_type\", \"\")\n        if notification_type not in WAITING_NOTIFICATION_TYPES:\n            return\n        # Claude emits a generic permission notification after presenting an\n        # AskUserQuestion. Keep the structured questions and options already\n        # published for this session instead of replacing them with that less\n        # useful notification text.\n        try:\n            with open(target) as existing_file:\n                existing = json.load(existing_file)\n            if existing.get(\"kind\") == \"question\":\n                return\n        except Exception:\n            pass\n        message = payload.get(\"message\", \"\")\n        if not message:\n            return\n        normalized_questions = [{\n            \"text\": message,\n            \"header\": payload.get(\"title\") or notification_type.replace(\"_\", \" \").title(),\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n    elif hook_event == \"PermissionRequest\":\n        # Codex approval prompt. The payload mirrors PreToolUse (tool_name,\n        # tool_input) but carries no questions -- Codex is asking to run a tool,\n        # not asking the operator a multiple-choice question. Publish it as a\n        # notification-kind approval block naming the tool so the feed and the\n        # phone notifier can surface it, and so AGI EXT can bridge\n        # it to a VS Code notification.\n        tool_name = payload.get(\"tool_name\") or \"a tool\"\n        tool_input = payload.get(\"tool_input\", {})\n        command = \"\"\n        if isinstance(tool_input, dict):\n            command = (\n                tool_input.get(\"command\")\n                or tool_input.get(\"cmd\")\n                or tool_input.get(\"path\")\n                or \"\"\n            )\n            if isinstance(command, list):\n                command = \" \".join(str(c) for c in command)\n        detail = f\": {command}\" if command else \"\"\n        normalized_questions = [{\n            \"text\": f\"Codex needs approval to run {tool_name}{detail}\",\n            \"header\": \"Approval needed\",\n            \"multiSelect\": False,\n        }]\n        kind = \"notification\"\n        notification_type = \"permission_prompt\"\n        codex_approval = True\n    else:\n        tool_input = payload.get(\"tool_input\", {})\n        questions = tool_input.get(\"questions\", [])\n        if not questions:\n            return\n        normalized_questions = []\n        for q in questions:\n            if not isinstance(q, dict):\n                continue\n            question = {\n                \"text\": q.get(\"question\", q.get(\"header\", \"\")),\n                \"header\": q.get(\"header\"),\n                \"multiSelect\": q.get(\"multiSelect\", False),\n            }\n            raw_opts = q.get(\"options\", [])\n            if raw_opts:\n                question[\"options\"] = [\n                    {\"label\": o.get(\"label\", \"\"), \"description\": o.get(\"description\")}\n                    for o in raw_opts\n                    if isinstance(o, dict)\n                ]\n            normalized_questions.append(question)\n        if not normalized_questions:\n            return\n        kind = \"question\"\n\n    # Identity from env (set by agents-cli at spawn).\n    mailbox_id = os.path.basename(\n        os.environ.get(\"AGENTS_MAILBOX_DIR\", \"\").rstrip(\"/\")\n    ) or session_id\n\n    now = datetime.now(timezone.utc)\n    now_iso = now.isoformat()\n    now_ms = int(now.timestamp() * 1000)\n    stats_path = os.path.join(asks_dir, f\"{safe_session_id}.json\")\n    stats = read_json(stats_path) or {}\n    recent = stats.get(\"recentAskTimestamps\") if isinstance(stats, dict) else []\n    if not isinstance(recent, list):\n        recent = []\n    recent.append(now_iso)\n    # Keep enough history for rolling one-hour needy detection without unbounded\n    # per-session files. The TypeScript reader applies the exact time window.\n    recent = recent[-200:]\n    write_json(stats_path, {\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"firstAskAt\": stats.get(\"firstAskAt\") or now_iso,\n        \"lastAskAt\": now_iso,\n        \"totalAskCount\": int(stats.get(\"totalAskCount\") or 0) + 1,\n        \"recentAskTimestamps\": recent,\n    })\n\n    hostname = os.environ.get(\"AGENTS_SYNC_MACHINE_ID\") or socket.gethostname()\n    host = hostname.split(\".\")[0].strip().lower()\n    host = re.sub(r\"[^a-z0-9_-]\", \"-\", host) or \"unknown\"\n\n    runtime = os.environ.get(\"AGENTS_RUNTIME\", \"headless\")\n    cwd = payload.get(\"cwd\") or os.environ.get(\"AGENTS_CWD\")\n    project = project_from_cwd(cwd)\n\n    block = {\n        \"blockId\": block_id,\n        \"sessionId\": session_id,\n        \"mailboxId\": mailbox_id,\n        \"host\": host,\n        \"runtime\": runtime,\n        \"ts\": now_iso,\n        # Write-time cursor so a new generation is not suppressed when\n        # session.lastActivityMs is unresolvable (cloud / remote / index-lag).\n        \"sourceCursor\": {\"lastActivityMs\": now_ms},\n        \"questions\": normalized_questions,\n        \"kind\": kind,\n    }\n    if project:\n        block[\"project\"] = project\n    if notification_type:\n        block[\"notificationType\"] = notification_type\n\n    # A Codex PermissionRequest is a real approval gate: mark it approval-class\n    # with a high cost-of-delay so 'agents feed --dispatch' classifies it urgent\n    # (isPhoneUrgent gates on costOfDelay >= phoneNotifyThreshold, default\n    # 'medium') and pages the phone. A plain 'deny' is the safe default.\n    if codex_approval:\n        block[\"blockClass\"] = \"approval\"\n        block[\"costOfDelay\"] = \"high\"\n        block[\"safeDefault\"] = \"deny\"\n\n    # Optional multi-operator control metadata passed by the agent in the\n    # AskUserQuestion tool_input. Defaults keep the existing behavior. A Codex\n    # PermissionRequest carries tool ARGS in tool_input (command/path), not\n    # operator controls, so it is excluded here -- its class/cost is stamped\n    # above from codex_approval.\n    controls = payload.get(\"tool_input\", {}) if hook_event not in (\"Notification\", \"PermissionRequest\") else {}\n    block_class = controls.get(\"blockClass\") if isinstance(controls, dict) else None\n    if block_class in (\"approval\", \"decision\"):\n        block[\"blockClass\"] = block_class\n    consequence = controls.get(\"consequence\") if isinstance(controls, dict) else None\n    if consequence:\n        block[\"consequence\"] = consequence\n    allowed = controls.get(\"allowedOperators\") if isinstance(controls, dict) else None\n    if isinstance(allowed, list):\n        block[\"allowedOperators\"] = [str(a) for a in allowed]\n    timeout = controls.get(\"timeoutMinutes\") if isinstance(controls, dict) else None\n    if isinstance(timeout, (int, float)) and timeout > 0:\n        block[\"timeoutMinutes\"] = int(timeout)\n    safe_default = controls.get(\"safeDefault\") if isinstance(controls, dict) else None\n    if isinstance(safe_default, str):\n        block[\"safeDefault\"] = safe_default\n    cost = controls.get(\"costOfDelay\") if isinstance(controls, dict) else None\n    if cost in (\"low\", \"medium\", \"high\"):\n        block[\"costOfDelay\"] = cost\n\n    # Publishing a new question clears any stale answered marker from the\n    # previous question in this session.\n    try:\n        os.unlink(os.path.join(answered_dir, f\"{block_id}.json\"))\n    except FileNotFoundError:\n        pass\n    except Exception:\n        pass\n\n    # Python's expanduser() ignores HOME on Windows, while agents-cli honors a\n    # HOME override on every platform. Use the same anchor so hooks and the CLI\n    # always read/write one feed store (including temp-home and sandbox runs).\n    os.makedirs(feed_dir, exist_ok=True)\n\n    fd, tmp = tempfile.mkstemp(dir=feed_dir, suffix=\".tmp\")\n    try:\n        with os.fdopen(fd, \"w\") as f:\n            json.dump(block, f, indent=2)\n        os.replace(tmp, target)\n    except Exception:\n        try:\n            os.unlink(tmp)\n        except Exception:\n            pass\n\n\nif __name__ == \"__main__\":\n    try:\n        main()\n    except Exception:\n        pass  # fail open\n";
 /** Manifest entry for the feed-publish hook, matching the ManifestHook shape. */
 export declare const FEED_PUBLISH_HOOK_MANIFEST: {
     name: string;

package/dist/lib/feed/feed.js

@@ -374,6 +374,9 @@ export function clearBlockLifecycle(blockId, root) {
  * `costOfDelay: high` because a declared block is, by definition, an agent that
  * has already stopped making progress — that is what makes it worth interrupting
  * someone over, and what `feed --dispatch`'s urgency filter keys off.
+ *
+ * `sourceCursor` is stamped from `ts` at write time so a fresh generation is
+ * comparable even when the live session's `lastActivityMs` is unresolvable.
  */
 export function buildDeclaredBlock(agent, input) {
     const text = input.text.trim().replace(/\s+/g, ' ');
@@ -399,6 +402,9 @@ export function buildDeclaredBlock(agent, input) {
         generation: ts,
         source: 'declared',
         state: 'open',
+        // Write-time cursor so a new generation is not suppressed when
+        // session.lastActivityMs is unresolvable (cloud / remote / index-lag).
+        sourceCursor: { lastActivityMs: Date.parse(ts) },
         kind: 'declared',
         questions: [{ text, header: 'Needs you', ...(options.length ? { options } : {}) }],
         blockClass: input.safeDefault ? 'approval' : 'decision',
@@ -769,7 +775,9 @@ def main():
         os.environ.get("AGENTS_MAILBOX_DIR", "").rstrip("/")
     ) or session_id
 
-    now_iso = datetime.now(timezone.utc).isoformat()
+    now = datetime.now(timezone.utc)
+    now_iso = now.isoformat()
+    now_ms = int(now.timestamp() * 1000)
     stats_path = os.path.join(asks_dir, f"{safe_session_id}.json")
     stats = read_json(stats_path) or {}
     recent = stats.get("recentAskTimestamps") if isinstance(stats, dict) else []
@@ -803,6 +811,9 @@ def main():
         "host": host,
         "runtime": runtime,
         "ts": now_iso,
+        # Write-time cursor so a new generation is not suppressed when
+        # session.lastActivityMs is unresolvable (cloud / remote / index-lag).
+        "sourceCursor": {"lastActivityMs": now_ms},
         "questions": normalized_questions,
         "kind": kind,
     }

package/dist/lib/hosts/dispatch.d.ts

@@ -40,9 +40,10 @@ export declare function withActorEnv(env?: Record<string, string>): Record<strin
  *
  * `extra` carries the markers that are true of ONE path rather than both — the
  * interactive dispatch adds REMOTE_INTERACTIVE_ENV, which the remote CLI reads
- * to decide it must detach. It goes through this builder rather than being
- * concatenated on at the call site so every remote env marker is exported the
- * same way, in one place.
+ * to know its stdio is an ssh link (reconnect target, `--no-follow` pane
+ * requirement). It goes through this builder rather than being concatenated on
+ * at the call site so every remote env marker is exported the same way, in one
+ * place.
  */
 export declare function remoteRunShellPrelude(agent: string, extra?: Record<string, string>): string;
 /**

package/dist/lib/hosts/dispatch.js

@@ -78,9 +78,10 @@ export function withActorEnv(env) {
  *
  * `extra` carries the markers that are true of ONE path rather than both — the
  * interactive dispatch adds REMOTE_INTERACTIVE_ENV, which the remote CLI reads
- * to decide it must detach. It goes through this builder rather than being
- * concatenated on at the call site so every remote env marker is exported the
- * same way, in one place.
+ * to know its stdio is an ssh link (reconnect target, `--no-follow` pane
+ * requirement). It goes through this builder rather than being concatenated on
+ * at the call site so every remote env marker is exported the same way, in one
+ * place.
  */
 export function remoteRunShellPrelude(agent, extra = {}) {
     const guard = agent === RUN_AUTO_KEYWORD ? { [RUN_AUTO_HOST_RESOLVED_ENV]: '1' } : {};
@@ -497,11 +498,14 @@ export async function runInteractiveOnHost(host, opts) {
     // than re-resolving from this box's SSH_CONNECTION (RUSH-2028); a `run auto`
     // dispatch also gets the chain-hop guard (remoteRunShellPrelude).
     //
-    // REMOTE_INTERACTIVE_ENV rides the same prelude and is what makes the remote
-    // agent DETACHED: its stdio is this ssh link, so without the tmux wrap a
-    // blink SIGHUPs it and the in-flight turn is gone — while reconnect.ts is
-    // built to re-attach a pane it assumes survived (RUSH-3125). Set here, on the
-    // interactive path only: `launchDetached` already setsids the headless one.
+    // REMOTE_INTERACTIVE_ENV rides the same prelude and tells the remote CLI its
+    // stdio is this ssh link: it marks the run as reconnect-managed (a drop is
+    // answered by reconnect.ts, which rejoins the live pane or resumes the
+    // session in place) and, when the launcher has no TTY (CI, scripts), requires
+    // the detached pane that is the run's only interface. Since PHNX-3316 it no
+    // longer forces the tmux wrap on a TTY-followed run — the peer's
+    // tmux.enabled decides that. Set here, on the interactive path only:
+    // `launchDetached` already setsids the headless one.
     const prelude = remoteRunShellPrelude(opts.agent, { [REMOTE_INTERACTIVE_ENV]: '1' });
     let remoteCmd = `${prelude}${cwd}${invocation}`;
     if (opts.copyCreds) {

package/dist/lib/hosts/providers/local.d.ts

@@ -2,9 +2,15 @@
  * Local host provider: the v1 directory.
  *
  * `list()` is the union of ssh-config `Host` stanzas (read-only, connection
- * details owned by ssh) and inline entries the user registered in agents.yaml.
- * The `Meta.hosts` overlay (caps/os, keyed by name) is merged onto both. We
- * never copy or rewrite ssh config.
+ * details owned by ssh) and inline entries the user registered. The host
+ * overlay (caps/os, keyed by name) is merged onto both. We never copy or
+ * rewrite ssh config.
+ *
+ * PHNX-3315: registrations are DEVICE-SCOPED — each box writes only its own
+ * `hosts:` block in `devices/<machine>/agents.yaml` (via `Meta.deviceHosts`),
+ * so N boxes no longer rewrite one shared `hosts:` map (the pull conflict).
+ * Reads are the cross-box UNION of every device doc, plus any lingering central
+ * legacy entries drained by the migration.
  */
 import type { Host, HostProvider, HostProviderCapabilities } from '../types.js';
 export declare class LocalHostProvider implements HostProvider {

package/dist/lib/hosts/providers/local.js

@@ -2,14 +2,28 @@
  * Local host provider: the v1 directory.
  *
  * `list()` is the union of ssh-config `Host` stanzas (read-only, connection
- * details owned by ssh) and inline entries the user registered in agents.yaml.
- * The `Meta.hosts` overlay (caps/os, keyed by name) is merged onto both. We
- * never copy or rewrite ssh config.
+ * details owned by ssh) and inline entries the user registered. The host
+ * overlay (caps/os, keyed by name) is merged onto both. We never copy or
+ * rewrite ssh config.
+ *
+ * PHNX-3315: registrations are DEVICE-SCOPED — each box writes only its own
+ * `hosts:` block in `devices/<machine>/agents.yaml` (via `Meta.deviceHosts`),
+ * so N boxes no longer rewrite one shared `hosts:` map (the pull conflict).
+ * Reads are the cross-box UNION of every device doc, plus any lingering central
+ * legacy entries drained by the migration.
  */
 import { readMeta, updateMeta } from '../../state.js';
+import { unionDeviceHosts } from '../../devices/device-docs.js';
 import { listSshConfigHosts, isSshConfigHost } from '../ssh-config.js';
+/** The EFFECTIVE host overlay: the cross-box union of every device doc's
+ * `hosts:` block, with any lingering central-legacy `hosts:` entries as a base
+ * (a device doc wins on a name collision). Newest `addedAt` wins across boxes. */
 function entries() {
-    return readMeta().hosts ?? {};
+    return { ...readMeta().hosts, ...unionDeviceHosts() };
+}
+/** THIS box's OWN host registrations (the writable slice in the device doc). */
+function ownEntries(meta = readMeta()) {
+    return meta.deviceHosts ?? {};
 }
 function toHost(name, entry, enrolled) {
     return {
@@ -63,19 +77,16 @@ export class LocalHostProvider {
             ...(spec.caps && spec.caps.length ? { caps: spec.caps } : {}),
             addedAt: spec.addedAt ?? new Date().toISOString(),
         };
-        updateMeta((meta) => ({ ...meta, hosts: { ...(meta.hosts ?? {}), [spec.name]: entry } }));
+        // Device-scoped: land in THIS box's device doc, never the shared central map.
+        updateMeta((meta) => ({ ...meta, deviceHosts: { ...ownEntries(meta), [spec.name]: entry } }));
         return toHost(spec.name, entry, true);
     }
     async remove(name) {
+        // A box only owns the registrations in its own device doc; drop from there.
         updateMeta((meta) => {
-            const hosts = { ...(meta.hosts ?? {}) };
+            const hosts = { ...ownEntries(meta) };
             delete hosts[name];
-            // Drop the key entirely when empty so we don't leave `hosts: {}` behind.
-            if (Object.keys(hosts).length === 0) {
-                const { hosts: _omit, ...rest } = meta;
-                return rest;
-            }
-            return { ...meta, hosts };
+            return { ...meta, deviceHosts: hosts };
         });
     }
 }

package/dist/lib/hosts/reconnect.d.ts

@@ -211,10 +211,13 @@ export declare function startConnectionTarget(opts: {
 /**
  * Decide what happens after an interactive `--device` stream returns.
  *
- * Auto-reconnect only when the link dropped (255) AND the run is tmux-hosted
- * (`willReconnect`). `--raw` is not wrapped, so it never reconnects — but it
- * still prints the session id: the user is at a shell, and EXEC-55 does not
- * exempt raw (RUSH-3227). Bundling the notice behind `!isRaw` was the miss.
+ * Auto-reconnect fires whenever the link dropped (255) and the run did not opt
+ * out with `--raw` (`willReconnect`) — wrap or no wrap. A wrapped run's pane
+ * survived, so the reattach rejoins it; a bare run's agent died with the link,
+ * so the same verb resumes the session in place from disk (PHNX-3316). `--raw`
+ * never reconnects — but it still prints the session id: the user is at a
+ * shell, and EXEC-55 does not exempt raw (RUSH-3227). Bundling the notice
+ * behind `!isRaw` was the miss.
  */
 export declare function afterInteractiveRemoteExit(opts: {
     target?: ReconnectTarget;

package/dist/lib/hosts/reconnect.js

@@ -2,34 +2,35 @@
  * Auto-reconnect for an interactive `agents run --device` session whose
  * SSH link dropped.
  *
- * A remote interactive agent runs in a DETACHED tmux session on the peer (see
- * lib/exec.ts `runInTmux`), so a network blink kills only the local ssh client —
- * the agent keeps running.
- *
- * **That premise is a guarantee, not a hope, only since RUSH-3125.** It used to
- * rest on the peer's `tmux.enabled`, an ergonomics preference that defaults OFF
- * — so on a default box the agent was a child of the sshd session, a blink
- * SIGHUPed it, and this file reconnected to a corpse while telling the user it
- * was "still running there." The interactive dispatch now exports
- * REMOTE_INTERACTIVE_ENV and exec.ts `resolveTmuxWrap` wraps on it regardless of
- * that toggle, so what is written below actually holds. Anything that would let
- * a remote interactive run reach the peer unwrapped breaks this whole file.
+ * What the reconnect lands on depends on the peer's `tmux.enabled`
+ * (PHNX-3316). With the wrap opted in, the agent runs in a DETACHED tmux
+ * session on the peer (see lib/exec.ts `runInTmux`), so a network blink kills
+ * only the local ssh client and the reattach below rejoins the live pane.
+ * With the wrap off — the fleet default — the remote agent is a child of the
+ * sshd session and a blink SIGHUPs it: the in-flight turn is lost, and the
+ * reattach RESUMES the harness session from disk instead. Both outcomes go
+ * through the same verb below; what changed in PHNX-3316 is that "resumed"
+ * is once again an honest, expected result rather than a corpse this file
+ * pretended was alive (the pre-RUSH-3125 bug), and RUSH-3125's forced wrap —
+ * which made the pane a guarantee by overriding the operator's tmux.enabled —
+ * is gone with it.
  *
  * `sshStream` reports that drop as exit code 255 (ssh's
  * own connection-layer failure; see ssh-exec.ts). Without this, exec.ts would
  * `process.exit(255)` and the user would have to notice, find the session id, and
- * `agents sessions focus` by hand. Instead we re-attach the live remote pane over
- * SSH automatically, with bounded backoff, until the user detaches cleanly (the
- * remote returns 0), the agent exits (the tmux session is gone; a non-255 code),
- * or the user interrupts the wait with Ctrl-C ({@link waitOrInterrupt} → 130).
+ * `agents sessions focus` by hand. Instead we re-attach over SSH automatically,
+ * with bounded backoff, until the user detaches cleanly (the remote returns 0),
+ * the agent exits (a non-255 code), or the user interrupts the wait with
+ * Ctrl-C ({@link waitOrInterrupt} → 130).
  *
  * The re-attach reuses the peer's OWN recovery verb — `agents sessions focus <id>
  * --local` — which JOINS the live local tmux pane there (a second client, no fork)
- * when it still exists, and RESUMES the session in place when the pane is already
- * gone. Dropping `--attach-only` is deliberate: a reattach that lands after the
- * remote pane died must not dead-end at a bare shell (the RUSH-2085 bug), it must
- * fall through to resume so the user is put back into the agent. There is one
- * re-attach implementation (the peer's focus) to keep in sync.
+ * when it exists, and RESUMES the session in place when there is no pane — which
+ * is every drop on a default (wrap-off) box. Dropping `--attach-only` is
+ * deliberate: a reattach that finds no pane must not dead-end at a bare shell
+ * (the RUSH-2085 bug), it must fall through to resume so the user is put back
+ * into the agent. There is one re-attach implementation (the peer's focus) to
+ * keep in sync.
  *
  * **What it takes to refill the budget: reached the host AND held the pane.** ssh
  * returns 255 for BOTH "couldn't connect at all" and "connected, then the link
@@ -314,10 +315,13 @@ export function startConnectionTarget(opts) {
 /**
  * Decide what happens after an interactive `--device` stream returns.
  *
- * Auto-reconnect only when the link dropped (255) AND the run is tmux-hosted
- * (`willReconnect`). `--raw` is not wrapped, so it never reconnects — but it
- * still prints the session id: the user is at a shell, and EXEC-55 does not
- * exempt raw (RUSH-3227). Bundling the notice behind `!isRaw` was the miss.
+ * Auto-reconnect fires whenever the link dropped (255) and the run did not opt
+ * out with `--raw` (`willReconnect`) — wrap or no wrap. A wrapped run's pane
+ * survived, so the reattach rejoins it; a bare run's agent died with the link,
+ * so the same verb resumes the session in place from disk (PHNX-3316). `--raw`
+ * never reconnects — but it still prints the session id: the user is at a
+ * shell, and EXEC-55 does not exempt raw (RUSH-3227). Bundling the notice
+ * behind `!isRaw` was the miss.
  */
 export function afterInteractiveRemoteExit(opts) {
     if (!opts.target)

package/dist/lib/hosts/registry.js

@@ -22,6 +22,7 @@ import { DevicesHostProvider } from './providers/devices.js';
 import { assertValidSshTarget } from '../ssh-exec.js';
 import { normalizeHost } from '../machine-id.js';
 import { readMeta } from '../state.js';
+import { unionDeviceHosts } from '../devices/device-docs.js';
 import { isSshConfigHost } from './ssh-config.js';
 import { resolveRemoteOsSync } from './remote-os.js';
 import { loadDevices } from '../devices/registry.js';
@@ -187,7 +188,9 @@ export async function matchHost(name, opts = {}) {
     catch {
         reg = {};
     }
-    const overlay = readMeta().hosts?.[host];
+    // The effective host overlay is the cross-box union of every device doc's
+    // `hosts:` block (PHNX-3315), plus any lingering central-legacy entry.
+    const overlay = { ...readMeta().hosts, ...unionDeviceHosts() }[host];
     // 1. A registered device (normalized match) — its live address/OS/presence win.
     const device = matchDevice(host, reg);
     if (device)

package/dist/lib/hosts/remote-os.js

@@ -19,6 +19,7 @@
 import { loadDevicesSync } from '../devices/registry.js';
 import { readDeviceConfigValues } from '../device-config.js';
 import { readMeta } from '../state.js';
+import { unionDeviceHosts } from '../devices/device-docs.js';
 /** Resolve the OS/platform string for a host name, or undefined if unknown. */
 export function resolveRemoteOsSync(name) {
     try {
@@ -33,5 +34,6 @@ export function resolveRemoteOsSync(name) {
         // A corrupt/unreadable device registry must never break command building —
         // fall through to the host overlay and ultimately the POSIX default.
     }
-    return readMeta().hosts?.[name]?.os;
+    // Cross-box union of the device-scoped host overlays, central legacy as base.
+    return ({ ...readMeta().hosts, ...unionDeviceHosts() }[name])?.os;
 }

package/dist/lib/session/active.d.ts

@@ -62,7 +62,7 @@ export declare function attributedSetLostPids(prev: Set<number>, next: Set<numbe
 export declare function filterCachedUnattributed(sessions: ActiveSession[], attributed: Set<number>, alive: (pid: number, startedAtMs?: number) => boolean): ActiveSession[];
 type ActiveContext = 'terminal' | 'teams' | 'cloud' | 'headless';
 /** The SessionMeta fields the live-row backfill reads — the enrichment a running process cannot report. */
-export type BackfillMeta = Pick<SessionMeta, 'version' | 'timestamp' | 'label' | 'ticketId' | 'prUrl' | 'prNumber' | 'origin' | 'routineName'>;
+export type BackfillMeta = Pick<SessionMeta, 'version' | 'timestamp' | 'label' | 'ticketId' | 'prUrl' | 'prNumber' | 'origin' | 'routineName' | 'harness'>;
 export declare function backfillActiveRowsFromMeta(sessions: ActiveSession[], metaById: Map<string, BackfillMeta>): void;
 export declare function backfillActiveRowsFromIndex(sessions: ActiveSession[]): void;
 export declare function isRunningLiveSession(s: ActiveSession): boolean;
@@ -112,6 +112,13 @@ export type RecapSource = 'label' | 'last' | 'prompt';
 export interface ActiveSession {
     context: ActiveContext;
     kind: string;
+    /**
+     * Custom harness / profile name when this live process was launched via
+     * `agents run <profile>` (e.g. `deepseek`). `kind` stays the HOST process
+     * (claude) so transcript lookup and live-signal parsers keep working.
+     * `sessions --active` displays this when set (PHNX-2935).
+     */
+    harness?: string;
     /** Specific host app — 'code', 'cursor', 'codium', 'iterm', 'terminal', 'warp', 'tmux', etc. */
     host?: string;
     pid?: number;
@@ -652,6 +659,8 @@ export declare function listUnattributedActive(attributed: Set<number>): Promise
 /** One tmux pane's resolved agent identity for the authoritative source. */
 interface PaneIdentity {
     agent: string;
+    /** Custom harness/profile name from the launch registry, when set. */
+    harness?: string;
     /** Exact session id when resolvable (launch registry, or the hook join). */
     sessionId?: string;
     /** The agent's OS pid from the launch registry (may differ from `pane_pid`). */

package/dist/lib/session/active.js

@@ -166,6 +166,8 @@ export function backfillActiveRowsFromMeta(sessions, metaById) {
             s.origin = m.origin;
         if (!s.routineName && m.routineName)
             s.routineName = m.routineName;
+        if (!s.harness && m.harness)
+            s.harness = m.harness;
     }
 }
 function loadBackfillMetaFor(sessions) {
@@ -1010,6 +1012,7 @@ export async function listTeamsActive(opts = {}) {
         return applyState({
             context: 'teams',
             kind: a.agentType,
+            harness: a.profileName ?? undefined,
             pid: a.pid ?? undefined,
             sessionId: resolvedId,
             machine: offloaded ? execHost : undefined,
@@ -1071,6 +1074,7 @@ export async function listTerminalsActive() {
         return applyState({
             context: 'terminal',
             kind: t.kind,
+            harness: pidEntry?.harness,
             host: detectHost(t.pid, procByPid),
             tty: procByPid.get(t.pid)?.tty,
             pid: t.pid,
@@ -1557,6 +1561,7 @@ async function listUnattributedActiveLive(attributed) {
         out.push(applyState({
             context,
             kind,
+            harness: entry?.harness,
             host,
             tty: procByPid.get(pid)?.tty,
             pid,
@@ -1621,7 +1626,7 @@ export function resolvePaneIdentity(pane, sessName, meta, liveEntry, getHookInde
                 terminalId: liveEntry.terminalId,
             })?.session_id
             ?? nameSessionId;
-        return { agent: liveEntry.agent, sessionId, pid: liveEntry.pid };
+        return { agent: liveEntry.agent, harness: liveEntry.harness, sessionId, pid: liveEntry.pid };
     }
     // No live-registry entry. Session-meta labels are the wrapped-origin fallback;
     // prefer them, then fall back to the name so a pane with neither a registry
@@ -1771,6 +1776,7 @@ export async function listTmuxAgentSessions() {
         out.push(applyState({
             context: 'terminal',
             kind: id.agent,
+            harness: id.harness,
             host: 'tmux',
             pid,
             sessionId: id.sessionId ?? sessionIdFromFile(sessionFile),

package/dist/lib/session/actor-sidecar.d.ts

@@ -7,6 +7,13 @@ export interface SessionActorRecord {
     initiatedBy?: 'human' | 'agent';
     /** Effective permissions mode used by the launcher. */
     mode?: SessionRunMode;
+    /**
+     * Custom harness / profile name when launched via `agents run <profile>`
+     * (e.g. `deepseek`). Joined onto the session index at scan time so a
+     * durable listing can distinguish the profile from its host agent
+     * (PHNX-2935).
+     */
+    harness?: string;
     /** Stable wrapper names that resolve to this native session id. */
     aliases?: string[];
     startedAtMs: number;

package/dist/lib/session/actor-sidecar.js

@@ -40,6 +40,7 @@ function isSafeAlias(alias) {
 function hasRecordData(record) {
     return typeof record.actor === 'string'
         || typeof record.mode === 'string'
+        || typeof record.harness === 'string'
         || (Array.isArray(record.aliases) && record.aliases.some(alias => typeof alias === 'string'));
 }
 function normalizedAliases(aliases) {
@@ -83,6 +84,7 @@ export function writeSessionAliasRecord(sessionId, alias) {
             actor: previous?.actor,
             initiatedBy: previous?.initiatedBy,
             mode: previous?.mode,
+            harness: previous?.harness,
             aliases: normalizedAliases([...(previous?.aliases ?? []), alias]),
             startedAtMs: previous?.startedAtMs ?? Date.now(),
         });

package/dist/lib/session/db.d.ts

@@ -12,7 +12,7 @@ import { type IndexedToolCall } from './tool-calls.js';
 /** Current schema version; bumped when migrations are added. Exported so tests
  * assert against the constant instead of hardcoding a number that every bump
  * then has to chase (docs/sessions.md calls the constant the source of truth). */
-export declare const SCHEMA_VERSION = 40;
+export declare const SCHEMA_VERSION = 41;
 /**
  * Bumping this invalidates every cached facet row without touching the schema
  * version, so a change to the extraction logic (a new metric, a corrected bucket)