@phnx-labs/agents-cli 1.20.76 → 1.20.78

package/dist/lib/activity.js

@@ -34,6 +34,8 @@ export const MILESTONE_EVENTS = [
     'pushed',
     'subagent.spawned',
     'artifact.created',
+    'task.completed',
+    'checklist.created',
     'status.posted',
 ];
 const MILESTONE_SET = new Set(MILESTONE_EVENTS);
@@ -238,6 +240,8 @@ export const EVENT_STYLE = {
     'pushed': { glyph: '↥', color: chalk.yellow, label: 'pushed' },
     'subagent.spawned': { glyph: '⑂', color: chalk.magenta, label: 'sub-agent spawned' },
     'artifact.created': { glyph: '▤', color: chalk.cyan, label: 'artifact' },
+    'task.completed': { glyph: '✓', color: chalk.green, label: 'task completed' },
+    'checklist.created': { glyph: '☐', color: chalk.cyan, label: 'checklist created' },
     'status.posted': { glyph: '▸', color: chalk.white, label: 'status' },
     'file.edited': { glyph: '·', color: chalk.gray, label: 'file edited' },
 };
@@ -266,15 +270,17 @@ export function formatActivityLine(ev, opts = {}) {
  * line per event to ~/.agents/.history/activity/<sessionId>.jsonl.
  *
  * Matcher-gated to mutating/milestone tools (Bash|Task|ExitPlanMode|Write|
- * Edit|MultiEdit) so read-only tools never pay the hook cost. Fail-open: any
- * error is swallowed so a logging hiccup never blocks a tool call.
+ * Edit|MultiEdit|TodoWrite|update_plan|TaskUpdate|todo_write|TaskCreate) so
+ * read-only tools never pay the hook cost. Fail-open: any error is swallowed so
+ * a logging hiccup never blocks a tool call.
  */
 export const ACTIVITY_LOG_HOOK_SCRIPT = `#!/usr/bin/env python3
 """Append agent-activity events for \`agents feed\` / \`agents activity\`.
 
 Bound to PreToolUse (ExitPlanMode, Task) and PostToolUse (Bash, Write, Edit,
-MultiEdit). One append-only file per session; read-only tools never trigger it
-because the manifest matcher excludes them.
+MultiEdit, TodoWrite, update_plan, TaskUpdate, todo_write, TaskCreate). One
+append-only file per session; read-only tools never trigger it because the
+manifest matcher excludes them.
 
 Sub-agent gate: when the payload carries \`agent_type\`, this is a Task/Agent
 sub-agent -- skip so only the top-level agent logs its own activity.
@@ -293,7 +299,7 @@ MAX_LOG_BYTES = 5 * 1024 * 1024  # cap a pathological session's log
 MILESTONE_EVENTS = {
     "plan.created", "pr.opened", "pr.merged", "worktree.created",
     "worktree.removed", "commit.created", "pushed", "subagent.spawned",
-    "artifact.created", "status.posted",
+    "artifact.created", "task.completed", "checklist.created", "status.posted",
 }
 
 # Deliverable file types + locations -- a Write here is a recognizable artifact
@@ -304,6 +310,14 @@ ARTIFACT_EXTS = {
 }
 ARTIFACT_DIR_HINTS = ("/tmp/", "/downloads/", "/.agents/artifacts/")
 
+# Checklist tools across harnesses. The value is the key that holds the item list.
+CHECKLIST_TOOLS = {
+    "TodoWrite": "todos",
+    "todo_write": "todos",
+    "TaskUpdate": "tasks",
+    "update_plan": "plan",
+}
+
 
 def is_artifact(file_path):
     low = (file_path or "").lower()
@@ -379,11 +393,418 @@ def extract_url(tool_response):
     return m.group(0).rstrip(").,") if m else None
 
 
+def _checklist_items(tool_input, kind):
+    """Extract normalized checklist items from tool input."""
+    if not isinstance(tool_input, dict):
+        return []
+    if kind == "todos":
+        arr = tool_input.get("todos") or []
+    elif kind == "tasks":
+        arr = tool_input.get("tasks") or []
+        if not arr and "taskId" in tool_input:
+            arr = [tool_input]
+    elif kind == "plan":
+        arr = tool_input.get("plan") or []
+    else:
+        return []
+    if not isinstance(arr, list):
+        return []
+
+    items = []
+    for t in arr:
+        if not isinstance(t, dict):
+            continue
+        subject = (
+            t.get("content") or
+            t.get("text") or
+            t.get("step") or
+            t.get("title") or
+            t.get("description") or
+            t.get("activeForm") or
+            ""
+        )
+        if not isinstance(subject, str):
+            subject = str(subject)
+        subject = subject.strip()
+        item_id = t.get("id") or t.get("taskId") or subject
+        if not item_id:
+            continue
+        status = str(t.get("status", "") or "").lower()
+        items.append({"id": item_id, "subject": subject, "status": status})
+    return items
+
+
+def _read_transcript_checklists(transcript_path, current_tool, current_items):
+    """Tail-read the session transcript and return the previous checklist state.
+
+    The most recent checklist entry is assumed to be the current tool call if
+    it carries the same ids; skip that one and return the next older checklist
+    state (or None if there isn't one).
+    """
+    if not transcript_path or not os.path.exists(transcript_path):
+        return None
+    try:
+        size = os.path.getsize(transcript_path)
+        start = max(0, size - 512 * 1024)
+        with open(transcript_path, "r", encoding="utf-8", errors="ignore") as f:
+            f.seek(start)
+            if start > 0:
+                f.readline()  # drop a leading partial line
+            lines = f.readlines()
+    except Exception:
+        return None
+
+    current_ids = {str(item.get("id")) for item in current_items if item.get("id")}
+    skipped_current = False
+    for line in reversed(lines):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            record = json.loads(line)
+        except Exception:
+            continue
+        if not isinstance(record, dict):
+            continue
+
+        tool_uses = []
+        if isinstance(record.get("tool_use"), list):
+            tool_uses = record["tool_use"]
+        elif record.get("name"):
+            tool_uses = [record]
+        elif record.get("tool_name"):
+            tool_uses = [record]
+
+        for tu in reversed(tool_uses):
+            if not isinstance(tu, dict):
+                continue
+            name = tu.get("name") or tu.get("tool_name") or ""
+            if name not in CHECKLIST_TOOLS:
+                continue
+            kind = CHECKLIST_TOOLS[name]
+            args = tu.get("input") or tu.get("tool_input") or tu.get("arguments") or {}
+            if isinstance(args, str):
+                try:
+                    args = json.loads(args)
+                except Exception:
+                    continue
+            items = _checklist_items(args, kind)
+            if not items:
+                continue
+            ids = {str(item.get("id")) for item in items if item.get("id")}
+            # Skip the most recent matching checklist entry once; that is the
+            # current call already reflected in the transcript.
+            if not skipped_current and name == current_tool and ids == current_ids:
+                skipped_current = True
+                continue
+            return items
+    return None
+
+
+def _has_previous_task_create(transcript_path, current_tool_use_id=""):
+    """Return True if the transcript contains a TaskCreate before the current one."""
+    if not transcript_path or not os.path.exists(transcript_path):
+        return False
+    try:
+        with open(transcript_path, "r", encoding="utf-8", errors="ignore") as f:
+            lines = f.readlines()
+    except Exception:
+        return False
+
+    for line in reversed(lines):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            record = json.loads(line)
+        except Exception:
+            continue
+        if not isinstance(record, dict):
+            continue
+
+        tool_uses = []
+        msg = record.get("message", {})
+        if isinstance(msg, dict) and isinstance(msg.get("content"), list):
+            tool_uses = [
+                c for c in msg["content"]
+                if isinstance(c, dict) and c.get("type") == "tool_use"
+            ]
+        elif isinstance(record.get("tool_use"), list):
+            tool_uses = record["tool_use"]
+        elif record.get("name"):
+            tool_uses = [record]
+
+        for tu in reversed(tool_uses):
+            if not isinstance(tu, dict):
+                continue
+            if (tu.get("name") or tu.get("tool_name")) == "TaskCreate":
+                if tu.get("id") != current_tool_use_id:
+                    return True
+    return False
+
+
+def _claude_task_state(transcript_path, exclude_task_id=None):
+    """Fold Claude TaskCreate/TaskUpdate calls into a task id -> subject/status map.
+
+    TaskCreate provides the subject (and id via toolUseResult); TaskUpdate
+    provides the status. If exclude_task_id is given, the last TaskUpdate for
+    that id is skipped (it is the current call already reflected in the
+    transcript).
+    """
+    state = {}
+    if not transcript_path or not os.path.exists(transcript_path):
+        return state
+    try:
+        with open(transcript_path, "r", encoding="utf-8", errors="ignore") as f:
+            lines = f.readlines()
+    except Exception:
+        return state
+
+    updates = []  # (task_id, status, line_index)
+    for idx, line in enumerate(lines):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            record = json.loads(line)
+        except Exception:
+            continue
+        if not isinstance(record, dict):
+            continue
+
+        tool_uses = []
+        msg = record.get("message", {})
+        if isinstance(msg, dict) and isinstance(msg.get("content"), list):
+            tool_uses = [
+                c for c in msg["content"]
+                if isinstance(c, dict) and c.get("type") == "tool_use"
+            ]
+        elif isinstance(record.get("tool_use"), list):
+            tool_uses = record["tool_use"]
+        elif record.get("name"):
+            tool_uses = [record]
+
+        for tu in tool_uses:
+            if not isinstance(tu, dict):
+                continue
+            name = tu.get("name") or ""
+            args = tu.get("input") or tu.get("tool_input") or {}
+            if isinstance(args, str):
+                try:
+                    args = json.loads(args)
+                except Exception:
+                    continue
+            if name == "TaskCreate":
+                subject = (
+                    args.get("subject") or
+                    args.get("description") or
+                    args.get("title") or
+                    ""
+                )
+                if subject:
+                    # Link subject to the tool_use id so the result can map it.
+                    tool_id = tu.get("id")
+                    if tool_id:
+                        state.setdefault("__pending_subject", {})[tool_id] = subject
+
+        tool_result = record.get("toolUseResult") or {}
+        if not isinstance(tool_result, dict):
+            continue
+        task = tool_result.get("task")
+        if isinstance(task, dict):
+            task_id = str(task.get("id") or task.get("taskId") or "")
+            if task_id:
+                state.setdefault(task_id, {})
+                if task.get("subject"):
+                    state[task_id]["subject"] = task["subject"]
+                if task.get("status"):
+                    state[task_id]["status"] = str(task.get("status")).lower()
+                # Link any pending subject from the matching tool_use id.
+                tool_use_id = record.get("tool_use_id") or ""
+                pending = state.get("__pending_subject", {})
+                if tool_use_id and tool_use_id in pending:
+                    state[task_id]["subject"] = pending[tool_use_id]
+        task_id = str(tool_result.get("taskId") or "")
+        status_change = tool_result.get("statusChange") or {}
+        status = status_change.get("to") or tool_result.get("status")
+        if task_id and status:
+            state.setdefault(task_id, {})
+            state[task_id]["status"] = str(status).lower()
+            updates.append((task_id, str(status).lower(), idx))
+
+    if exclude_task_id and updates:
+        for i in range(len(updates) - 1, -1, -1):
+            if updates[i][0] == exclude_task_id:
+                del updates[i]
+                break
+        # Rebuild statuses from remaining updates.
+        for task_id in list(state.keys()):
+            if task_id.startswith("__"):
+                continue
+            if "subject" not in state[task_id]:
+                del state[task_id]
+            else:
+                state[task_id].pop("status", None)
+        for task_id, status, _ in updates:
+            if task_id in state:
+                state[task_id]["status"] = status
+
+    # Drop tasks removed from the checklist (deleted/cancelled): they are gone
+    # from the user-visible list, so they must not count toward the N/M total.
+    for task_id in list(state.keys()):
+        if task_id.startswith("__"):
+            continue
+        if state[task_id].get("status") in ("deleted", "cancelled", "canceled", "removed"):
+            del state[task_id]
+
+    # Drop internal bookkeeping.
+    state.pop("__pending_subject", None)
+    return state
+
+
+def _checklist_events(payload, hook_event):
+    """Return a list of (event, detail) tuples for checklist tool calls."""
+    if hook_event != "PostToolUse":
+        return []
+    tool_name = payload.get("tool_name", "")
+    tool_input = payload.get("tool_input", {}) or {}
+
+    if tool_name == "TaskCreate":
+        subject = (
+            tool_input.get("subject") or
+            tool_input.get("description") or
+            tool_input.get("title") or
+            "task"
+        )
+        # Only announce the checklist on the very first task creation.
+        current_tool_use_id = payload.get("tool_use_id", "")
+        transcript_path = payload.get("transcript_path")
+        if _has_previous_task_create(transcript_path, current_tool_use_id):
+            return []
+        return [("checklist.created", subject)]
+
+    if tool_name not in CHECKLIST_TOOLS:
+        return []
+
+    kind = CHECKLIST_TOOLS[tool_name]
+    items = _checklist_items(tool_input, kind)
+    if not items:
+        return []
+
+    # Full-list tools (TodoWrite, update_plan) send the whole checklist every
+    # time. Per-task update tools (TaskUpdate) send only the changed item, so
+    # totals and subject must be resolved from the previous full-list state.
+    list_key = {"todos": "todos", "tasks": "tasks", "plan": "plan"}.get(kind)
+    is_full_list = list_key is not None and list_key in tool_input
+
+    previous = _read_transcript_checklists(
+        payload.get("transcript_path"), tool_name, items
+    )
+
+    if not is_full_list and previous:
+        total = len(previous)
+        previous_done = {
+            str(i.get("id")) for i in previous
+            if i.get("status") == "completed" and i.get("id")
+        }
+        done_count = len(previous_done)
+        events = []
+        for item in items:
+            if item.get("status") != "completed":
+                continue
+            item_id = str(item.get("id"))
+            if item_id in previous_done:
+                continue
+            subject = item.get("subject")
+            if not subject:
+                for p in previous:
+                    if str(p.get("id")) == item_id and p.get("subject"):
+                        subject = p["subject"]
+                        break
+            if not subject:
+                subject = "task"
+            done_count += 1
+            events.append(("task.completed", f"{subject} {done_count}/{total} done"))
+        return events
+
+    # For TaskUpdate without a previous full-list state, fold the Claude
+    # TaskCreate/TaskUpdate history to resolve subject and N/M.
+    if tool_name == "TaskUpdate" and previous is None:
+        task_id = str(items[0].get("id")) if items else ""
+        task_state = _claude_task_state(
+            payload.get("transcript_path"), exclude_task_id=task_id
+        )
+        if task_state:
+            total = len(task_state)
+            previous_done = {
+                tid for tid, info in task_state.items()
+                if info.get("status") == "completed"
+            }
+            done_count = len(previous_done)
+            if task_id in task_state and items[0].get("status") == "completed" and task_id not in previous_done:
+                subject = task_state[task_id].get("subject") or "task"
+                return [("task.completed", f"{subject} {done_count + 1}/{total} done")]
+            return []
+
+    total = len(items)
+    completed = [i for i in items if i.get("status") == "completed"]
+
+    if previous is None:
+        # First checklist call in this session.
+        events = []
+        events.append(("checklist.created", f"{total} task{'s' if total != 1 else ''}"))
+        for item in completed:
+            events.append((
+                "task.completed",
+                f"{item['subject']} {len(completed)}/{total} done",
+            ))
+        return events
+
+    previous_done = {
+        str(i.get("id")) for i in previous
+        if i.get("status") == "completed" and i.get("id")
+    }
+    newly_completed = [
+        i for i in completed
+        if str(i.get("id")) not in previous_done
+    ]
+    if not newly_completed:
+        return []
+
+    done_count = len(completed)
+    events = []
+    for item in newly_completed:
+        events.append((
+            "task.completed",
+            f"{item['subject']} {done_count}/{total} done",
+        ))
+    return events
+
+
+def _make_record(event, detail, tool_name):
+    tier = "milestone" if event in MILESTONE_EVENTS else "activity"
+    record = {
+        "v": 1,
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "event": event,
+        "tier": tier,
+    }
+    if detail:
+        record["detail"] = detail
+    record["tool"] = tool_name
+    return record
+
+
 def build_event(payload, hook_event):
     tool_name = payload.get("tool_name", "")
     tool_input = payload.get("tool_input", {}) or {}
     tool_response = payload.get("tool_response", {})
 
+    # Checklist completions first -- cheap guard above already filtered tool name.
+    checklist = _checklist_events(payload, hook_event)
+    if checklist:
+        return [_make_record(event, detail, tool_name) for event, detail in checklist], tool_name
+
     event = None
     detail = None
     url = None
@@ -414,21 +835,12 @@ def build_event(payload, hook_event):
             detail = os.path.basename(fp) if fp else tool_name
 
     if not event:
-        return None, tool_name
+        return [], tool_name
 
-    tier = "milestone" if event in MILESTONE_EVENTS else "activity"
-    record = {
-        "v": 1,
-        "ts": datetime.now(timezone.utc).isoformat(),
-        "event": event,
-        "tier": tier,
-    }
-    if detail:
-        record["detail"] = detail
+    record = _make_record(event, detail, tool_name)
     if url:
         record["url"] = url
-    record["tool"] = tool_name
-    return record, tool_name
+    return [record], tool_name
 
 
 def main():
@@ -447,8 +859,8 @@ def main():
         return
 
     hook_event = payload.get("hook_event_name", "")
-    record, tool_name = build_event(payload, hook_event)
-    if not record:
+    records, tool_name = build_event(payload, hook_event)
+    if not records:
         return
 
     safe_session = re.sub(r"[^A-Za-z0-9._-]", "-", session_id) or "unknown"
@@ -463,27 +875,29 @@ def main():
     hostname = os.environ.get("AGENTS_SYNC_MACHINE_ID") or socket.gethostname()
     host = re.sub(r"[^a-z0-9_-]", "-", hostname.split(".")[0].strip().lower()) or "unknown"
 
-    record["sessionId"] = session_id
-    record["mailboxId"] = mailbox_id
-    record["host"] = host
-    record["runtime"] = os.environ.get("AGENTS_RUNTIME", "headless")
-    cwd = payload.get("cwd") or os.environ.get("AGENTS_CWD")
-    if cwd:
-        record["cwd"] = cwd
-    agent = os.environ.get("AGENTS_AGENT_NAME") or "claude"
-    record["agent"] = agent
+    for record in records:
+        record["sessionId"] = session_id
+        record["mailboxId"] = mailbox_id
+        record["host"] = host
+        record["runtime"] = os.environ.get("AGENTS_RUNTIME", "headless")
+        cwd = payload.get("cwd") or os.environ.get("AGENTS_CWD")
+        if cwd:
+            record["cwd"] = cwd
+        agent = os.environ.get("AGENTS_AGENT_NAME") or "claude"
+        record["agent"] = agent
 
     try:
         os.makedirs(activity_dir, exist_ok=True)
         # Cap growth: once over the size limit, keep only milestones.
-        if record["tier"] != "milestone":
-            try:
-                if os.path.getsize(target) > MAX_LOG_BYTES:
-                    return
-            except OSError:
-                pass
+        try:
+            over_limit = os.path.getsize(target) > MAX_LOG_BYTES
+        except OSError:
+            over_limit = False
         with open(target, "a") as f:
-            f.write(json.dumps(record) + "\\n")
+            for record in records:
+                if over_limit and record.get("tier") != "milestone":
+                    continue
+                f.write(json.dumps(record) + "\\n")
     except Exception:
         pass  # fail open
 
@@ -506,7 +920,7 @@ export const ACTIVITY_HOOK_DEFINITIONS = {
     'activity-log-result': {
         agents: ['claude'],
         events: ['PostToolUse'],
-        matcher: 'Bash|Write|Edit|MultiEdit',
+        matcher: 'Bash|Write|Edit|MultiEdit|TodoWrite|update_plan|TaskUpdate|todo_write|TaskCreate',
         script: '11-activity-log.py',
         timeout: 5,
     },

package/dist/lib/agents.d.ts

@@ -265,27 +265,6 @@ export declare function __resetAntigravityKeychainCacheForTest(): void;
  * Sync, no Keychain, no network — safe on the `agents run` hot path.
  */
 export declare function isClaudeCredentialFileBlank(base: string, platform?: NodeJS.Platform): boolean;
-/**
- * Whether a Claude version home holds its OWN on-disk credential — a non-blank
- * `.claude/.credentials.json` (the store Claude Code writes on login off macOS)
- * or a `.claude/.oauth_token` file (the keychain-less shim fallback, shims.ts).
- *
- * RUSH-1979: the routines daemon injects one ambient `CLAUDE_CODE_OAUTH_TOKEN`
- * (RUSH-1759) so a token-less default account still authenticates. But Claude —
- * and the Linux shim's own `-z CLAUDE_CODE_OAUTH_TOKEN` guard — both prefer that
- * env var over a pinned account's config dir, so when balanced rotation pins a
- * specific account's `CLAUDE_CONFIG_DIR` the ambient token shadows it: the pool
- * is inert and every fire 401s on the one stale token. A routine spawn drops the
- * ambient token when the pinned account has its own credential (this returns
- * true) so the account authenticates itself; when it does not (the RUSH-1759
- * default), the injected token is kept.
- *
- * Off-darwin only, mirroring {@link isClaudeCredentialFileBlank}: on macOS the
- * login Keychain is the canonical store and probing it raises an auth sheet, and
- * there the daemon injects no token to shadow (broker-only, usually absent), so
- * returning false changes nothing. Sync, no Keychain, no network.
- */
-export declare function claudeHomeHasOwnCredential(base: string, platform?: NodeJS.Platform): boolean;
 export declare function getAccountInfo(agentId: AgentId, home?: string): Promise<AccountInfo>;
 /**
  * Determine when the agent was last used by checking session file mtimes,

package/dist/lib/agents.js

@@ -1404,43 +1404,6 @@ export function isClaudeCredentialFileBlank(base, platform = process.platform) {
         return false;
     }
 }
-/**
- * Whether a Claude version home holds its OWN on-disk credential — a non-blank
- * `.claude/.credentials.json` (the store Claude Code writes on login off macOS)
- * or a `.claude/.oauth_token` file (the keychain-less shim fallback, shims.ts).
- *
- * RUSH-1979: the routines daemon injects one ambient `CLAUDE_CODE_OAUTH_TOKEN`
- * (RUSH-1759) so a token-less default account still authenticates. But Claude —
- * and the Linux shim's own `-z CLAUDE_CODE_OAUTH_TOKEN` guard — both prefer that
- * env var over a pinned account's config dir, so when balanced rotation pins a
- * specific account's `CLAUDE_CONFIG_DIR` the ambient token shadows it: the pool
- * is inert and every fire 401s on the one stale token. A routine spawn drops the
- * ambient token when the pinned account has its own credential (this returns
- * true) so the account authenticates itself; when it does not (the RUSH-1759
- * default), the injected token is kept.
- *
- * Off-darwin only, mirroring {@link isClaudeCredentialFileBlank}: on macOS the
- * login Keychain is the canonical store and probing it raises an auth sheet, and
- * there the daemon injects no token to shadow (broker-only, usually absent), so
- * returning false changes nothing. Sync, no Keychain, no network.
- */
-export function claudeHomeHasOwnCredential(base, platform = process.platform) {
-    if (platform === 'darwin')
-        return false;
-    if (fs.existsSync(path.join(base, '.claude', '.oauth_token')))
-        return true;
-    try {
-        const raw = fs.readFileSync(path.join(base, '.claude', '.credentials.json'), 'utf-8');
-        const oauth = JSON.parse(raw).claudeAiOauth;
-        if (!oauth)
-            return false;
-        const nonEmpty = (v) => typeof v === 'string' && v.trim().length > 0;
-        return nonEmpty(oauth.accessToken) || nonEmpty(oauth.refreshToken);
-    }
-    catch {
-        return false;
-    }
-}
 export async function getAccountInfo(agentId, home) {
     const base = home || os.homedir();
     const empty = {

package/dist/lib/auto-pull.d.ts

@@ -2,12 +2,13 @@
  * Background sync for tracked git repos:
  *   - System repo (~/.agents/.system/) is read-only locally — fast-forward auto-pull is safe.
  *   - User repo (~/.agents/) and enabled extras may have local commits, so we only
- *     `git fetch` and write a status marker. Next CLI invocation surfaces a one-line
- *     notice if upstream is ahead. Pulling is left to the user via `agents repo pull`.
+ *     `git fetch` and write a status marker. `agents doctor` surfaces these markers
+ *     as a "Repo updates" section instead of printing to stderr on every command.
+ *     Pulling is left to the user via `agents repo pull`.
  *
  * Public API:
- *   spawnDetachedSync()           — fire-and-forget; never blocks the foreground command.
- *   printPendingUpdateNotices()   — synchronous; reads markers and prints + consumes them.
+ *   spawnDetachedSync()      — fire-and-forget; never blocks the foreground command.
+ *   readRepoBehindMarkers()  — synchronous; reads markers without consuming them.
  */
 /** Per-repo lock file path. mtime acts as a recency check. */
 export declare function lockFilePath(alias: string): string;
@@ -24,8 +25,15 @@ export interface FetchStatusMarker {
 /** Spawn the detached worker. No-op when AGENTS_NO_AUTOPULL=1 is set. */
 export declare function spawnDetachedSync(): void;
 /**
- * Read any pending status markers and print one-line notices for repos that
- * are behind upstream. Markers are deleted after printing so notices don't
- * repeat on every invocation. Synchronous, cheap (small JSON files).
+ * Read all current status markers and return those where the local repo is
+ * behind upstream. Markers are NOT deleted — they persist until the next
+ * background fetch overwrites them with fresh data.
+ *
+ * Synchronous, cheap (small JSON files). Used by `agents doctor` to surface
+ * repo-behind warnings in one place instead of printing to stderr on every
+ * command.
+ *
+ * @param fetchDir - Override the fetch state dir (for tests). Defaults to the
+ *   production getFetchCacheDir() path.
  */
-export declare function printPendingUpdateNotices(): void;
+export declare function readRepoBehindMarkers(fetchDir?: string): FetchStatusMarker[];