@phnx-labs/agents-cli 1.22.53 → 1.22.54

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

@@ -342,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 = 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";
+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    # A resolution tombstone is written BEFORE unlink (matching TS recordAnswer)\n    # so a stale lifecycle re-read cannot resurrect this generation.\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        now_iso = datetime.now(timezone.utc).isoformat()\n        try:\n            fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)\n            record = {\n                \"answeredAt\": now_iso,\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        # Tombstone first, then drop the open-block view. A missing/corrupt\n        # block means there is nothing to resolve; fail open.\n        existing = read_json(target)\n        if isinstance(existing, dict):\n            generation = existing.get(\"generation\") or existing.get(\"ts\")\n            if generation:\n                tombstone = {\n                    \"blockId\": block_id,\n                    \"generation\": generation,\n                    \"resolvedAt\": now_iso,\n                    \"reason\": \"answered\",\n                }\n                source_cursor = existing.get(\"sourceCursor\")\n                if source_cursor:\n                    tombstone[\"sourceCursor\"] = source_cursor\n                write_json(\n                    os.path.join(feed_dir, \"resolutions\", f\"{block_id}.json\"),\n                    tombstone,\n                )\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

@@ -666,13 +666,16 @@ def main():
     # Terminal answers (human typed in the TUI) record an answered marker and
     # remove the block file so the feed stops showing it within one poll cycle.
     # The marker stays behind so a concurrent surface cannot double-answer.
+    # A resolution tombstone is written BEFORE unlink (matching TS recordAnswer)
+    # so a stale lifecycle re-read cannot resurrect this generation.
     if hook_event == "UserPromptSubmit":
         os.makedirs(answered_dir, exist_ok=True)
         marker = os.path.join(answered_dir, f"{block_id}.json")
+        now_iso = datetime.now(timezone.utc).isoformat()
         try:
             fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)
             record = {
-                "answeredAt": datetime.now(timezone.utc).isoformat(),
+                "answeredAt": now_iso,
                 "answeredFrom": "terminal",
             }
             with os.fdopen(fd, "w") as f:
@@ -681,6 +684,25 @@ def main():
             pass
         except Exception:
             pass
+        # Tombstone first, then drop the open-block view. A missing/corrupt
+        # block means there is nothing to resolve; fail open.
+        existing = read_json(target)
+        if isinstance(existing, dict):
+            generation = existing.get("generation") or existing.get("ts")
+            if generation:
+                tombstone = {
+                    "blockId": block_id,
+                    "generation": generation,
+                    "resolvedAt": now_iso,
+                    "reason": "answered",
+                }
+                source_cursor = existing.get("sourceCursor")
+                if source_cursor:
+                    tombstone["sourceCursor"] = source_cursor
+                write_json(
+                    os.path.join(feed_dir, "resolutions", f"{block_id}.json"),
+                    tombstone,
+                )
         # Remove the visible block so the feed drops the answered question.
         try:
             os.unlink(target)

package/dist/lib/feed-broadcast.js

@@ -7,7 +7,7 @@
  * a GitHub issue) hears nothing at all. So a post can also be mirrored outward.
  *
  * Sinks are **argv templates from config**, never hardcoded integrations. This
- * CLI ships Apache-2.0 and must not depend on one person's tracker or messaging
+ * CLI ships under FSL-1.1-Apache-2.0 and must not depend on one person's tracker or messaging
  * stack; declaring `[linear, update, "{ticket}", --comment, "{text}"]` in
  * `agents.yaml` keeps the coupling in the operator's config where it belongs,
  * and lets someone else point the same mechanism at `jira`, `gh issue comment`,

package/dist/lib/fleet/apply.d.ts

@@ -45,6 +45,13 @@ export interface SourceAuth {
     /** The captured file payloads, keyed by agent. */
     filesByAgent: Map<string, AuthFilePayload[]>;
 }
+/**
+ * Bundles `fleet apply` considers for push. The reserved file-backed `auth`
+ * bundle is always included when it exists locally — it is the fleet-shared
+ * setup-token store and must not wait on `--provision-secrets` / a manifest
+ * list (PHNX-2371).
+ */
+export declare function fleetSecretsBundles(declared: string[] | undefined): string[];
 export interface DiffContext {
     /** agents-cli version the source is on — the fleet target version. */
     targetCliVersion: string;
@@ -95,6 +102,10 @@ export interface SecretPushDecision {
  * auto-provisions its OWN machine-local key — so each box ends up with an
  * unshared at-rest key and NO passphrase is forwarded. That is the direct
  * alternative to the fleet-wide shared secret this ticket exists to remove.
+ *
+ * The reserved `auth` bundle is the exception: it is always file-backed
+ * (SEC-GAP-3) and is pushed even without `--provision-secrets`, because it is
+ * the one fleet-shared setup-token store (PHNX-2371).
  */
 export declare function decideSecretPush(bundle: string, desired: DeviceDesired, probe: DeviceProbe, ctx: DiffContext): SecretPushDecision;
 export interface ProbeOptions {

package/dist/lib/fleet/apply.js

@@ -9,6 +9,7 @@
  */
 import * as os from 'os';
 import { pushBundleToHost } from '../secrets/push.js';
+import { AUTH_BUNDLE_NAME, inspectReservedAuthBundle, isReservedBundleName } from '../secrets/bundles.js';
 import { deviceIdentityArgs, sshTargetFor } from '../devices/connect.js';
 import { readyProbe, bootstrapAgentsCli } from '../hosts/ready.js';
 import { buildRemoteAgentsInvocation } from '../hosts/remote-cmd.js';
@@ -88,6 +89,20 @@ export function parseInstalledVersions(stdout) {
         return undefined;
     }
 }
+/**
+ * Bundles `fleet apply` considers for push. The reserved file-backed `auth`
+ * bundle is always included when it exists locally — it is the fleet-shared
+ * setup-token store and must not wait on `--provision-secrets` / a manifest
+ * list (PHNX-2371).
+ */
+export function fleetSecretsBundles(declared) {
+    const out = [...(declared ?? [])];
+    const auth = inspectReservedAuthBundle();
+    if (auth.exists && auth.ok && !out.includes(AUTH_BUNDLE_NAME)) {
+        out.push(AUTH_BUNDLE_NAME);
+    }
+    return out;
+}
 /** Pure: desired vs probed -> per-device diff + flat action list. */
 export function diffFleet(desired, probes, ctx) {
     const devices = [];
@@ -208,12 +223,17 @@ export function diffFleet(desired, probes, ctx) {
  * auto-provisions its OWN machine-local key — so each box ends up with an
  * unshared at-rest key and NO passphrase is forwarded. That is the direct
  * alternative to the fleet-wide shared secret this ticket exists to remove.
+ *
+ * The reserved `auth` bundle is the exception: it is always file-backed
+ * (SEC-GAP-3) and is pushed even without `--provision-secrets`, because it is
+ * the one fleet-shared setup-token store (PHNX-2371).
  */
 export function decideSecretPush(bundle, desired, probe, ctx) {
     const device = desired.device;
-    const backend = probe.platform === 'linux' ? 'file' : 'keychain';
+    const reserved = isReservedBundleName(bundle);
+    const backend = reserved || probe.platform === 'linux' ? 'file' : 'keychain';
     const manual = `recreate secrets bundle '${bundle}' (\`agents ssh ${device} -- secrets create ${bundle}\`)`;
-    if (!ctx.provisionSecrets) {
+    if (!ctx.provisionSecrets && !reserved) {
         return { push: false, backend, reason: `${manual} — or re-run with --provision-secrets to push it` };
     }
     if (!probe.reachable) {
@@ -416,7 +436,7 @@ export function reconcileDevice(row, device, ctx) {
             ok = false;
             continue;
         }
-        const backend = device.platform === 'linux' ? 'file' : 'keychain';
+        const backend = isReservedBundleName(bundle) || device.platform === 'linux' ? 'file' : 'keychain';
         try {
             const out = pushBundleToHost(bundle, target, {
                 remoteBackend: backend,

package/dist/lib/fleet/auth-sync.js

@@ -136,9 +136,11 @@ export const FLEET_LOGIN_FLOWS = {
         successFile: successFileFor('opencode'),
     },
     // claude: interactive `/login` inside the TUI is a loopback browser flow, and
-    // the token is keychain-bound on macOS. A headless `claude setup-token` device
-    // variant exists (TODO: wire as a device-code flow with a captured pattern);
-    // until then claude is flagged non-remotable.
+    // the token is keychain-bound on macOS. That native login stays per-box and
+    // is never copied. The shareable `claude setup-token` mint is a different
+    // credential class — wired as `agents accounts mint claude` / `agents auth mint`
+    // (`lib/auth-mint.ts`), not as a fleet-login device-code flow (a setup-token
+    // is account-scoped, not per-machine).
     claude: {
         loginCommand: 'claude',
         flowType: 'loopback',

package/dist/lib/help.d.ts

@@ -18,6 +18,15 @@ export interface CommandGroup {
  * any group fall back to a plain "Commands:" section below the groups.
  */
 export declare function registerCommandGroups(parent: Command, groups: readonly CommandGroup[]): void;
+/**
+ * Front-door command groups shown on `agents --help`. Derived from measured
+ * reach: tier 1 = setup/run/sessions/view, tier 2 = teams/browser/secrets/
+ * devices/accounts/add. The remaining groups stay discoverable through the
+ * pointer rendered below these groups.
+ */
+export declare const FRONT_DOOR_COMMAND_GROUPS: readonly CommandGroup[];
+/** Mark the root program so its help only renders front-door groups + a pointer. */
+export declare function setCompactRootHelp(program: Command): void;
 /** Examples + Notes blocks attached to a command via setHelpSections. */
 export interface HelpSections {
     examples?: string;

package/dist/lib/help.js

@@ -7,6 +7,27 @@ const commandGroupRegistry = new WeakMap();
 export function registerCommandGroups(parent, groups) {
     commandGroupRegistry.set(parent, groups);
 }
+/**
+ * Front-door command groups shown on `agents --help`. Derived from measured
+ * reach: tier 1 = setup/run/sessions/view, tier 2 = teams/browser/secrets/
+ * devices/accounts/add. The remaining groups stay discoverable through the
+ * pointer rendered below these groups.
+ */
+export const FRONT_DOOR_COMMAND_GROUPS = [
+    {
+        title: 'Quick start',
+        names: ['setup', 'view', 'run', 'sessions'],
+    },
+    {
+        title: 'Most-used',
+        names: ['teams', 'browser', 'secrets', 'devices', 'accounts', 'add'],
+    },
+];
+const compactRootHelp = new WeakMap();
+/** Mark the root program so its help only renders front-door groups + a pointer. */
+export function setCompactRootHelp(program) {
+    compactRootHelp.set(program, true);
+}
 const helpSectionRegistry = new WeakMap();
 /**
  * Attach an Examples block (rendered between the description and Arguments)
@@ -136,7 +157,14 @@ function formatHelpCommandsFirst(cmd, helper) {
             output = output.concat([`${title}:`, formatList(subs.map(renderCommand)), '']);
         }
         const remaining = visibleCommands.filter((s) => !placed.has(s.name()));
-        if (remaining.length > 0) {
+        if (compactRootHelp.get(cmd)) {
+            output = output.concat([
+                'Commands:',
+                `  See "${cmd.name()} --help-all" for every command.`,
+                '',
+            ]);
+        }
+        else if (remaining.length > 0) {
             output = output.concat(['Commands:', formatList(remaining.map(renderCommand)), '']);
         }
     }

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

@@ -17,7 +17,7 @@
  * "not supported" message — never commander's raw `unknown option`.
  */
 import { type Host } from './types.js';
-import { type DeviceProfile, type DeviceRegistry } from '../devices/registry.js';
+import { type DeviceRegistry } from '../devices/registry.js';
 import { runLocalCommand, runOnDevice } from '../devices/fleet.js';
 /** Re-export for callers that historically imported flagValue from this module. */
 export { flagValue, hasHostRoutingFlag } from './routing-flag.js';
@@ -69,15 +69,6 @@ export interface FleetPassthroughOptions {
     /** Override this machine's id (tests). Defaults to `machineId()`. */
     self?: string;
 }
-/**
- * Prefix a fan-out remote command so the far side sees AGENTS_FLEET_REMOTE=1 —
- * the same marker the single-target dispatch sets via env. `wrapRemoteCommand`
- * joins the argv with spaces (POSIX) or base64-encodes it for PowerShell, so a
- * shell-appropriate leading token rides through both: `env VAR=1 …` on POSIX,
- * `$env:VAR='1'; …` on PowerShell. Only remote (non-self) targets get it; the
- * self target runs locally and must stay ungated.
- */
-export declare function markFleetRemote(cmd: string[], device: DeviceProfile): string[];
 /** Run `agents <command> …` across every registered device and render the roster. */
 export declare function runFleetPassthrough(command: string, allArgs: string[], spec: RemoteSpec, opts?: FleetPassthroughOptions): Promise<boolean>;
 /**

package/dist/lib/hosts/passthrough.js

@@ -32,6 +32,7 @@ import { isDeviceInteractive, resolveInteractiveDevice, interactiveUnsetError, }
 import { flagValue, hasHostRoutingFlag } from './routing-flag.js';
 import { loadDevices } from '../devices/registry.js';
 import { isSelfHost } from '../devices/self-host.js';
+import { markFleetRemote } from '../devices/connect.js';
 import { fanOutDevices, planFleetTargets, runLocalCommand, runOnDevice, } from '../devices/fleet.js';
 import { platformGroupLabel } from '../devices/health-report.js';
 import { isKnownTopLevelCommand } from '../startup/command-registry.js';
@@ -368,19 +369,6 @@ function renderFleetRoster(command, forwarded, results, self) {
         console.log(chalk.gray(summaryParts.join(' · ')));
     }
 }
-/**
- * Prefix a fan-out remote command so the far side sees AGENTS_FLEET_REMOTE=1 —
- * the same marker the single-target dispatch sets via env. `wrapRemoteCommand`
- * joins the argv with spaces (POSIX) or base64-encodes it for PowerShell, so a
- * shell-appropriate leading token rides through both: `env VAR=1 …` on POSIX,
- * `$env:VAR='1'; …` on PowerShell. Only remote (non-self) targets get it; the
- * self target runs locally and must stay ungated.
- */
-export function markFleetRemote(cmd, device) {
-    return device.shell === 'powershell'
-        ? [`$env:AGENTS_FLEET_REMOTE='1';`, ...cmd]
-        : ['env', 'AGENTS_FLEET_REMOTE=1', ...cmd];
-}
 /** Run `agents <command> …` across every registered device and render the roster. */
 export async function runFleetPassthrough(command, allArgs, spec, opts = {}) {
     const self = opts.self ?? machineId();

package/dist/lib/installations/versions.js

@@ -49,7 +49,7 @@ import { emit } from '../feed/events.js';
 import { safeJoin } from '../paths.js';
 import { readSkillSourceCommandMarker, shouldAlsoInstallCommandAsSkill, shouldInstallCommandAsSkill, } from '../command-skills.js';
 import { getWriter, getDetector } from '../staleness/registry.js';
-import { syncMemoryToVersionHome } from '../memory.js';
+import { syncMemoryToVersionHome, syncClaudeProjectMemoryDir } from '../memory.js';
 import { listPluginSkillNames, resolveCommandSource, resolveSkillSource } from '../staleness/writers/sources.js';
 import { syncProjectResourcesToAgent } from '../project-resources.js';
 import { installClaudeStatusLine } from '../claude-statusline.js';
@@ -2860,6 +2860,14 @@ export function syncResourcesToVersion(agent, version, selection, options = {})
     if (supports(agent, 'memory', version).ok) {
         syncMemoryToVersionHome(agent, versionHome, cwd);
     }
+    // Claude Code's own NATIVE per-project auto-memory (.claude/projects/<key>/memory/,
+    // PHNX-2817) is a separate, unmanaged directory Claude writes into itself — make it
+    // version-independent the same way project-level rules already are, via a shared
+    // symlink, so a note survives an agent version upgrade instead of vanishing into a
+    // fresh, empty version home.
+    if (agent === 'claude') {
+        syncClaudeProjectMemoryDir(versionHome, cwd);
+    }
     // Prune resources deleted from source (RUSH-2438). Runs only on a repo-scope
     // reconcile (`options.prune`) with a caller selection — a full sync
     // (`!userPassedSelection`) already sweeps orphans above, and an additive

package/dist/lib/linux-userns.d.ts

@@ -0,0 +1,58 @@
+/** Path of the AppArmor knob that gates unprivileged userns on Ubuntu 23.10+. */
+export declare const APPARMOR_USERNS_SYSCTL_PATH = "/proc/sys/kernel/apparmor_restrict_unprivileged_userns";
+export type UsernsState = 
+/** A new user namespace with a uid map can be created — Codex's sandbox works. */
+'ok'
+/** Unprivileged userns is restricted — Codex's bwrap sandbox cannot start. */
+ | 'blocked'
+/** Could not determine (non-Linux, or the probe could not run). */
+ | 'unknown';
+export interface UsernsStatus {
+    state: UsernsState;
+    /** One-line human reason, present when `blocked` or `unknown`. */
+    reason?: string;
+}
+/** The raw signals the pure interpreter reasons over. */
+export interface UsernsInputs {
+    platform: NodeJS.Platform;
+    /**
+     * Contents of {@link APPARMOR_USERNS_SYSCTL_PATH} trimmed, or null when the
+     * file is absent (older kernels / no AppArmor userns mediation).
+     */
+    apparmorRestrict: string | null;
+    /**
+     * Result of actually attempting to create a user namespace with a uid map:
+     *   - 'ok'      → the probe created the namespace and mapped root.
+     *   - 'denied'  → the kernel refused the uid_map write (the restricted case).
+     *   - 'no-tool' → the probe binary (`unshare`) was missing or failed to spawn.
+     */
+    unshareProbe: 'ok' | 'denied' | 'no-tool';
+}
+/**
+ * Decide userns availability from raw signals. Pure — no I/O.
+ *
+ * The definitive signal is the actual probe: if we successfully created a userns
+ * and wrote a uid map, the sandbox works regardless of the sysctl (an AppArmor
+ * profile may grant a specific binary `userns` even while the global knob is 1).
+ * A denied probe is a hard `blocked`. When the probe tool is missing we fall back
+ * to the sysctl: `1` → `blocked`, `0`/absent → `unknown` (we could not prove it,
+ * and refuse to claim `ok` we did not observe).
+ */
+export declare function interpretUsernsInputs(inputs: UsernsInputs): UsernsStatus;
+/** Read the AppArmor userns sysctl, or null when the file is absent. */
+export declare function readApparmorRestrict(sysctlPath?: string): string | null;
+/**
+ * Actually try to create a user namespace and map root inside it — the same
+ * operation bwrap performs (`unshare --user --map-root-user`). This is the ground
+ * truth: it observes exactly what the kernel/AppArmor policy permits for *this*
+ * process, rather than inferring from the sysctl alone.
+ */
+export declare function probeUnshare(): 'ok' | 'denied' | 'no-tool';
+/**
+ * Resolve whether an unprivileged user namespace can be created on this host,
+ * cached for the process (the answer is a stable property of the box). Non-Linux
+ * short-circuits to `ok` without spawning anything.
+ */
+export declare function probeUnprivilegedUserns(platform?: NodeJS.Platform): UsernsStatus;
+/** Test-only: drop the process cache so a test can re-probe. */
+export declare function resetUsernsCacheForTests(): void;

package/dist/lib/linux-userns.js

@@ -0,0 +1,116 @@
+/**
+ * Unprivileged user-namespace availability on Linux — the capability Codex's
+ * Linux sandbox needs, and the one Ubuntu 23.10+ restricts by default.
+ *
+ * Codex ≥0.146 implements its `read-only` and `workspace-write` sandbox modes on
+ * Linux with a bundled **bubblewrap** (`bwrap`), extracted per-run to
+ * `$CODEX_HOME/tmp/arg0/codex-XXXX/` and exec'd from a memfd. bwrap sets up its
+ * mounts inside a fresh **unprivileged user namespace** (`--unshare-user`, then a
+ * write to `/proc/self/uid_map`). Ubuntu 24.04 ships
+ * `kernel.apparmor_restrict_unprivileged_userns=1`, which denies that to an
+ * unconfined binary — so bwrap dies with `bwrap: setting up uid map: Permission
+ * denied` and a headless Codex run lands zero tools (no file writes, no shell).
+ * `danger-full-access` (our `skip` mode) drops the sandbox and is the only mode
+ * that avoids bwrap; the legacy Landlock backend is gone (`use_linux_sandbox_bwrap`
+ * is `removed`, `use_legacy_landlock` panics under the permission-profile model).
+ *
+ * This module is the single detector. It is pure at its core
+ * ({@link interpretUsernsInputs}) so the decision is unit-testable without a
+ * shell, and {@link probeUnprivilegedUserns} gathers the real inputs once per
+ * process. See PHNX-3285.
+ */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+/** Path of the AppArmor knob that gates unprivileged userns on Ubuntu 23.10+. */
+export const APPARMOR_USERNS_SYSCTL_PATH = '/proc/sys/kernel/apparmor_restrict_unprivileged_userns';
+/**
+ * Decide userns availability from raw signals. Pure — no I/O.
+ *
+ * The definitive signal is the actual probe: if we successfully created a userns
+ * and wrote a uid map, the sandbox works regardless of the sysctl (an AppArmor
+ * profile may grant a specific binary `userns` even while the global knob is 1).
+ * A denied probe is a hard `blocked`. When the probe tool is missing we fall back
+ * to the sysctl: `1` → `blocked`, `0`/absent → `unknown` (we could not prove it,
+ * and refuse to claim `ok` we did not observe).
+ */
+export function interpretUsernsInputs(inputs) {
+    if (inputs.platform !== 'linux')
+        return { state: 'ok' };
+    if (inputs.unshareProbe === 'ok')
+        return { state: 'ok' };
+    if (inputs.unshareProbe === 'denied') {
+        const via = inputs.apparmorRestrict === '1'
+            ? ' (kernel.apparmor_restrict_unprivileged_userns=1)'
+            : '';
+        return {
+            state: 'blocked',
+            reason: `the kernel denied creating an unprivileged user namespace${via}`,
+        };
+    }
+    // Probe tool unavailable — lean on the AppArmor knob.
+    if (inputs.apparmorRestrict === '1') {
+        return {
+            state: 'blocked',
+            reason: 'unprivileged user namespaces are AppArmor-restricted ' +
+                '(kernel.apparmor_restrict_unprivileged_userns=1) and `unshare` was not available to confirm',
+        };
+    }
+    return {
+        state: 'unknown',
+        reason: '`unshare` was not available to probe user-namespace support',
+    };
+}
+/** Read the AppArmor userns sysctl, or null when the file is absent. */
+export function readApparmorRestrict(sysctlPath = APPARMOR_USERNS_SYSCTL_PATH) {
+    try {
+        return fs.readFileSync(sysctlPath, 'utf8').trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Actually try to create a user namespace and map root inside it — the same
+ * operation bwrap performs (`unshare --user --map-root-user`). This is the ground
+ * truth: it observes exactly what the kernel/AppArmor policy permits for *this*
+ * process, rather than inferring from the sysctl alone.
+ */
+export function probeUnshare() {
+    try {
+        execFileSync('unshare', ['--user', '--map-root-user', 'true'], {
+            stdio: 'ignore',
+            timeout: 5000,
+        });
+        return 'ok';
+    }
+    catch (err) {
+        // ENOENT / spawn failure → the tool isn't here; anything else (nonzero exit
+        // from the denied uid_map write) is the restricted case.
+        const code = err?.code;
+        if (code === 'ENOENT')
+            return 'no-tool';
+        return 'denied';
+    }
+}
+let cached = null;
+/**
+ * Resolve whether an unprivileged user namespace can be created on this host,
+ * cached for the process (the answer is a stable property of the box). Non-Linux
+ * short-circuits to `ok` without spawning anything.
+ */
+export function probeUnprivilegedUserns(platform = process.platform) {
+    if (platform !== 'linux')
+        return { state: 'ok' };
+    if (cached)
+        return cached;
+    cached = interpretUsernsInputs({
+        platform,
+        apparmorRestrict: readApparmorRestrict(),
+        unshareProbe: probeUnshare(),
+    });
+    return cached;
+}
+/** Test-only: drop the process cache so a test can re-probe. */
+export function resetUsernsCacheForTests() {
+    cached = null;
+}

package/dist/lib/memory.d.ts

@@ -53,3 +53,29 @@ export declare function rebuildMemoryIndex(dir: string): void;
 export declare function memoryTargetDir(agent: AgentId): string;
 /** Copy canonical layered memory into one version home. Returns fact names written. */
 export declare function syncMemoryToVersionHome(agent: AgentId, versionHome: string, cwd?: string): string[];
+/**
+ * Canonical shared dir for Claude Code's NATIVE per-project auto-memory —
+ * `<versionHome>/.claude/projects/<project-key>/memory/*.md`, the freeform
+ * notes Claude writes for itself during a session. Distinct from the layered
+ * `memory` resource above (~/.agents/memory/ facts synced into
+ * `.claude/memory/`): this dir is keyed by project (via
+ * {@link claudeProjectDirName}), not by agent version, and Claude Code itself
+ * decides what goes in it — agents-cli only makes the directory
+ * version-independent, never writes into it.
+ */
+export declare function getClaudeProjectMemoryDir(cwd: string): string;
+/**
+ * Make Claude Code's native per-project memory dir version-independent by
+ * symlinking `<versionHome>/.claude/projects/<project-key>/memory/` into the
+ * one canonical dir every installed Claude version's home shares for this
+ * project (PHNX-2817). Without this, `getVersionHomePath` gives every
+ * installed version its own isolated HOME, so a note written under one
+ * version is invisible under another — the directory is just empty there.
+ *
+ * Idempotent and safe to call on every sync: a dir already linked to the
+ * canonical target is left alone; a PRE-EXISTING real directory with content
+ * (the common case today, since this bug has always left one behind) has its
+ * files migrated into the canonical dir first — never discarded — before
+ * being replaced by the symlink.
+ */
+export declare function syncClaudeProjectMemoryDir(versionHome: string, cwd?: string): void;