orbi-cli 0.7.0__tar.gz → 0.7.2__tar.gz

{orbi_cli-0.7.0 → orbi_cli-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orbi-cli
-Version: 0.7.0
+Version: 0.7.2
 Summary: Orbi — local AI development worker: claims GitHub Issues, runs Pi in isolated worktrees, and delivers PRs (GitHub Issues + labels are the only state store).
 Author: xqliu
 License-Expression: AGPL-3.0-only OR LicenseRef-Sustainable-Use-1.0
@@ -18,7 +18,7 @@ English | [简体中文](README.zh-CN.md)
 
 # Orbi
 
-**Label a GitHub Issue. Get back a reviewed, merged PR — and a release.**
+**Label a GitHub Issue. Get back a reviewed, merged PR. Release when you decide.**
 
 [Try Orbi Cloud — 3 merged deliveries free](https://orbi.build/?ref=gh-readme) · no server, no credit card required
 
@@ -26,7 +26,7 @@ English | [简体中文](README.zh-CN.md)
 
 **See one real loop:** [Issue #1367](https://github.com/orbi-build/orbi/issues/1367) → [PR #1370](https://github.com/orbi-build/orbi/pull/1370) → [Release v0.5.47](https://github.com/orbi-build/orbi/releases/tag/v0.5.47)
 
-Orbi is an open-source autonomous coding agent: label a GitHub Issue `ai-ready`, and it writes the code in an isolated worktree, opens a PR, has an independent review session check it against the Issue's acceptance criteria, merges only the reviewed head, and cuts a tagged release. GitHub Issues are the only state store—no database, queue, or daemon.
+Orbi is an open-source **software dark factory**: a software delivery system for GitHub. You define the goal and acceptance criteria in an Issue and label it `ai-ready`; Orbi implements it in an isolated worktree, runs tests, opens a PR, and takes it through independent review, fixes, and merge. When you request a release, Orbi runs the release gates and publishes the tag and release notes. GitHub Issues are the only state store—no database, queue, or daemon.
 
 **Ledger:** [merged PRs](https://github.com/orbi-build/orbi/pulls?q=is:merged) · [closed Issues](https://github.com/orbi-build/orbi/issues?q=is:closed) · [tagged releases](https://github.com/orbi-build/orbi/releases) — the repository is the record.
 
@@ -60,7 +60,7 @@ orbi doctor --config orbi.toml  # 6. verify deployment health
 
 ## The loop, in 35 seconds
 
-That same loop, recorded from the live GitHub pages — including the review that rejected the first attempt:
+Another real delivery, recorded from the live GitHub pages — including the review that rejected the first attempt:
 
 <video src="https://github.com/user-attachments/assets/1f0d3a62-5fc9-44ae-bf68-b312a6a55f85" controls muted></video>
 

{orbi_cli-0.7.0 → orbi_cli-0.7.2}/README.md

@@ -2,7 +2,7 @@ English | [简体中文](README.zh-CN.md)
 
 # Orbi
 
-**Label a GitHub Issue. Get back a reviewed, merged PR — and a release.**
+**Label a GitHub Issue. Get back a reviewed, merged PR. Release when you decide.**
 
 [Try Orbi Cloud — 3 merged deliveries free](https://orbi.build/?ref=gh-readme) · no server, no credit card required
 
@@ -10,7 +10,7 @@ English | [简体中文](README.zh-CN.md)
 
 **See one real loop:** [Issue #1367](https://github.com/orbi-build/orbi/issues/1367) → [PR #1370](https://github.com/orbi-build/orbi/pull/1370) → [Release v0.5.47](https://github.com/orbi-build/orbi/releases/tag/v0.5.47)
 
-Orbi is an open-source autonomous coding agent: label a GitHub Issue `ai-ready`, and it writes the code in an isolated worktree, opens a PR, has an independent review session check it against the Issue's acceptance criteria, merges only the reviewed head, and cuts a tagged release. GitHub Issues are the only state store—no database, queue, or daemon.
+Orbi is an open-source **software dark factory**: a software delivery system for GitHub. You define the goal and acceptance criteria in an Issue and label it `ai-ready`; Orbi implements it in an isolated worktree, runs tests, opens a PR, and takes it through independent review, fixes, and merge. When you request a release, Orbi runs the release gates and publishes the tag and release notes. GitHub Issues are the only state store—no database, queue, or daemon.
 
 **Ledger:** [merged PRs](https://github.com/orbi-build/orbi/pulls?q=is:merged) · [closed Issues](https://github.com/orbi-build/orbi/issues?q=is:closed) · [tagged releases](https://github.com/orbi-build/orbi/releases) — the repository is the record.
 
@@ -44,7 +44,7 @@ orbi doctor --config orbi.toml  # 6. verify deployment health
 
 ## The loop, in 35 seconds
 
-That same loop, recorded from the live GitHub pages — including the review that rejected the first attempt:
+Another real delivery, recorded from the live GitHub pages — including the review that rejected the first attempt:
 
 <video src="https://github.com/user-attachments/assets/1f0d3a62-5fc9-44ae-bf68-b312a6a55f85" controls muted></video>
 

{orbi_cli-0.7.0 → orbi_cli-0.7.2}/pyproject.toml

@@ -44,7 +44,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "orbi-cli"
-version = "0.7.0"
+version = "0.7.2"
 description = "Orbi — local AI development worker: claims GitHub Issues, runs Pi in isolated worktrees, and delivers PRs (GitHub Issues + labels are the only state store)."
 readme = "README.md"
 requires-python = ">=3.14"

{orbi_cli-0.7.0 → orbi_cli-0.7.2}/src/orbi/__init__.py

@@ -18,4 +18,4 @@ the package would shadow the installed package for every process with
 the checkout root on sys.path. The direct-execution compatibility entry
 is `python3 -m orbi.cli` (development path only).
 """
-__version__ = "0.7.0"
+__version__ = "0.7.2"

{orbi_cli-0.7.0 → orbi_cli-0.7.2}/src/orbi/branch_reclaim.py

@@ -20,17 +20,39 @@ import logging
 import re
 import subprocess
 from pathlib import Path
+from typing import TYPE_CHECKING
 from urllib.parse import quote
 
-from orbi import config as config_domain
 from orbi.journal import GIT_NETWORK_TIMEOUT_SECONDS, event, run_command
 
+if TYPE_CHECKING:
+    # Annotation-only: `config` reaches `notify` through `release` and
+    # `github`, so a runtime import here would close a cycle once `notify`
+    # imports this module (the `read_merged_pull_requests` scan, #1674).
+    from orbi import config as config_domain
+
 # Remote delivery-branch reclamation: the tick-start pass deletes at most
 # this many merged-PR `orbi/*` branches per tick, so a large backlog (255
 # branches on 2026-09-28) drains over ticks and one tick never spends
 # unbounded time on `gh api` deletes. The same bound as the worktree pass.
 BRANCH_RECLAIM_MAX_PER_TICK = 25
 
+# The one merged-PR read the notification scan uses (Issue #1674). The
+# repository connection, not the search API: a just-merged PR is visible
+# at once, while the search index can lag and a lagged PR older than the
+# watermark would then be skipped forever. A merge updates the PR, so
+# recent merges come first; 100 is GitHub's page maximum.
+MERGED_PULL_REQUESTS_QUERY = """query($owner: String!, $name: String!) {
+  repository(owner: $owner, name: $name) {
+    pullRequests(
+      states: MERGED, first: 100,
+      orderBy: {field: UPDATED_AT, direction: DESC}
+    ) {
+      nodes { number title url headRefName mergedAt }
+    }
+  }
+}"""
+
 
 def delete_remote_branch(source_repo: str, branch: str) -> None:
     """Delete one remote branch through the GitHub REST API.
@@ -126,6 +148,31 @@ def _merged_pr_heads(prs: list[dict]) -> dict[str, set[str]]:
     return heads
 
 
+def read_merged_pull_requests(source_repo: str) -> list[dict]:
+    """Read the most recently updated MERGED PRs (one GraphQL page).
+
+    The read the notification scan uses (Issue #1674). A malformed
+    payload (a failed read, an unexpected shape) raises so the caller
+    records one ``notify_failed reason=merged_check_failed`` and leaves
+    its watermark unchanged; a malformed node is skipped, never guessed
+    into a merge.
+    """
+    owner, _, name = source_repo.partition("/")
+    raw = run_command(
+        [
+            "gh", "api", "graphql",
+            "-f", f"query={MERGED_PULL_REQUESTS_QUERY}",
+            "-f", f"owner={owner}", "-f", f"name={name}",
+        ],
+        timeout=GIT_NETWORK_TIMEOUT_SECONDS,
+        log_command=["gh", "api", "graphql", "merged_pull_requests"],
+    )
+    nodes = json.loads(raw)["data"]["repository"]["pullRequests"]["nodes"]
+    if not isinstance(nodes, list):
+        raise ValueError("malformed merged-pull-request read")
+    return [node for node in nodes if isinstance(node, dict)]
+
+
 def reclaim_merged_delivery_branches(config: config_domain.RunnerConfig) -> None:
     """Delete remote `orbi/*` branches whose delivery PR has MERGED.
 

{orbi_cli-0.7.0 → orbi_cli-0.7.2}/src/orbi/claim.py

@@ -29,7 +29,7 @@ from orbi.delivery_scene import (
     EXTERNAL_PR_MARKER, DeliveryScene, _issue_label_set, body_markers, classify,
 )
 from orbi.github import (
-    _epic_audit, _verify_epic_complete, apply_label_patch, close_issue,
+    _verify_epic_complete, apply_label_patch, close_issue,
     comment_issue, issue_comments, issue_priority, issue_view,
     latest_run_marker, list_issues, milestone_open_issue_count,
     open_blocker_numbers, open_pr_for_branch, pr_comments,
@@ -38,9 +38,12 @@ from orbi.github import (
 from orbi.gitops import task_branch
 from orbi.journal import LOGGER, current_run_id, event, new_run_id, set_run_id
 from orbi.pilot_slots import slot_held_deliveries, slot_occupancy
+from orbi import language
 from orbi.progress import run_marker
-from orbi.release import release_target_milestone
-from orbi.repo_config import RepoConfigError, RepoPolicy, load_repo_policy
+from orbi.release import _epic_audit, epic_audit_posted, release_target_milestone
+from orbi.repo_config import (
+    RepoConfigError, RepoPolicy, load_repo_policy, merged_repo_language,
+)
 
 
 class ResumeHooks(NamedTuple):
@@ -48,11 +51,14 @@ class ResumeHooks(NamedTuple):
 
     The physical scene handling of `pick_resumable_delivery` plus the PR
     comment writer `reconcile_orphan_prs` reports its orphan through.
+    Every hook that writes a comment takes the claim's already-resolved
+    per-repository `language_code` (Issue #1687): the claim knows the
+    merged repository config before the first comment is written.
     """
     resume_scene: Callable[[list[dict]], dict]
-    route_external_pr_ticket: Callable[[dict, str], bool]
-    block_scene_failure: Callable[[dict, ValueError, str, list[dict]], None]
-    recover_missing_pr_scene: Callable[[dict, str, Path], dict | None]
+    route_external_pr_ticket: Callable[..., bool]
+    block_scene_failure: Callable[..., None]
+    recover_missing_pr_scene: Callable[..., dict | None]
     has_recoverable_pr_scene: Callable[[dict, str, Path], bool]
     comment_pr: Callable[..., None]
 
@@ -194,7 +200,7 @@ def is_release(issue: dict) -> bool:
     return False
 
 
-def reconcile_open_epics(repo: str, run_id: str) -> list[str]:
+def reconcile_open_epics(repo: str, run_id: str, language_code: str) -> list[str]:
     """Sweep open Epics once per tick; ordinary pickup must not depend on it."""
     epics = list_issues(
         repo, state="open", search=f"label:{EPIC_LABEL}",
@@ -210,9 +216,9 @@ def reconcile_open_epics(repo: str, run_id: str) -> list[str]:
             event("epic_kept_open", issue=number, repo=repo, reason=reason)
             evidence.append(f"Epic #{number} kept open: {reason}")
             continue
-        audit = _epic_audit(child_evidence)
+        audit = _epic_audit(child_evidence, None, language_code)
         comments = issue_comments(int(number), repo=repo)
-        if not any(audit in str(comment.get("body", "")) for comment in comments):
+        if not epic_audit_posted(comments, child_evidence):
             comment_issue(int(number), repo=repo,
                          body=f"<!-- orbi:run={run_id} -->\n{audit}\nrun_id={run_id}")
         close_issue(int(number), repo=repo)
@@ -242,7 +248,7 @@ def orphan_pr_branch_issue(head_ref: object) -> int | None:
 
 
 def reconcile_orphan_prs(
-    repo: str, run_id: str, *, hooks: ResumeHooks,
+    repo: str, run_id: str, *, hooks: ResumeHooks, language_code: str,
 ) -> list[str]:
     """Report open delivery PRs whose source Issue is closed.
 
@@ -286,11 +292,10 @@ def reconcile_orphan_prs(
             pr_number, repo=repo,
             body=(
                 f"{ORPHAN_PR_MARK}\n{run_marker(run_id)}\n"
-                f"Orbi orphan PR: the source Issue #{issue_number} is "
-                f"closed while this PR is still open, so it will never "
-                f"be merged automatically. Human decision: merge this "
-                f"PR to keep the work, or close it.\n"
-                f"run_id={run_id}"
+                + language.text(
+                    language_code, "claim.orphan_pr",
+                    issue_number=issue_number, run_id=run_id,
+                )
             ),
         )
         event(
@@ -637,6 +642,7 @@ def pick_next_issue(
 def pick_resumable_delivery(
     repo: str, slot_dir: Path, max_concurrency: int,
     repo_dir: Path | None = None, *, hooks: ResumeHooks,
+    language_code: str,
 ) -> tuple[dict, dict] | None:
     """Return the newest FREE opened-PR delivery and its resume scene.
 
@@ -732,15 +738,15 @@ def pick_resumable_delivery(
             # probe the #726 external route first; otherwise this is the
             # ONLY trigger of `block_scene_failure` — a present-but-broken
             # scene is a writer bug or tampering and needs a human.
-            if hooks.route_external_pr_ticket(issue, repo):
+            if hooks.route_external_pr_ticket(issue, repo, language_code=language_code):
                 continue
-            hooks.block_scene_failure(issue, exc, repo, comments)
+            hooks.block_scene_failure(issue, exc, repo, comments, language_code=language_code)
             continue
         except scene.SceneMissingError as exc:
             # No trusted comment carries a scene at all — a distinct branch
             # from corruption. The original #726 incident was
             # exactly this shape, so the external route is probed first.
-            if hooks.route_external_pr_ticket(issue, repo):
+            if hooks.route_external_pr_ticket(issue, repo, language_code=language_code):
                 continue
             # Issue #1216: `awaiting_merge` can deliberately remove the
             # queue label before the delivery returns to `ai-fix-needed`.
@@ -772,7 +778,7 @@ def pick_resumable_delivery(
             # scene comment write. Retry it from the durable local run
             # state; keep ai-pr-opened for another tick if the retry fails.
             recovered = (
-                hooks.recover_missing_pr_scene(issue, repo, repo_dir)
+                hooks.recover_missing_pr_scene(issue, repo, repo_dir, language_code=language_code)
                 if repo_dir is not None else None
             )
             if recovered is not None:
@@ -795,15 +801,9 @@ def pick_resumable_delivery(
                     )
                     comment_issue(
                         number, repo=repo,
-                        body=(f"{marker}\n" if marker else "") + (
-                            f"Orbi failed: {exc}; no trusted 'Orbi opened PR' "
-                            "scene comment exists on this Issue, so the "
-                            "opened-PR delivery cannot be resumed — this is an "
-                            "external precondition the AI cannot safely judge "
-                            "or fix, so it cannot be recovered automatically "
-                            "(the Issue stays ai-blocked until a human "
-                            "decides) — restore the trusted 'Orbi opened PR' "
-                            "scene comment or relabel the Issue ai-fix-needed"
+                        body=(f"{marker}\n" if marker else "")
+                        + language.text(
+                            language_code, "claim.scene_missing", error=exc,
                         ),
                     )
                 except Exception:
@@ -873,10 +873,12 @@ def pick_next_delivery(
         tick_run_id = new_run_id()
         set_run_id(tick_run_id)
     for repo in repos:
+        repo_language = (language.DEFAULT_LANGUAGE if config is None
+                         else merged_repo_language(config, repo))
         # Epic reconciliation is a per-tick bypass: a broken GitHub query or
         # mutation must never prevent the ordinary delivery scans.
         try:
-            reconcile_open_epics(repo, tick_run_id)
+            reconcile_open_epics(repo, tick_run_id, repo_language)
         except Exception:
             LOGGER.exception("epic_reconcile_failed repo=%s", repo)
         # Milestone reconciliation intentionally follows the Epic sweep so a
@@ -905,18 +907,15 @@ def pick_next_delivery(
         # pattern: a broken GitHub query must never prevent the ordinary
         # delivery scans.
         try:
-            reconcile_orphan_prs(repo, tick_run_id, hooks=hooks)
+            reconcile_orphan_prs(repo, tick_run_id, hooks=hooks,
+                                 language_code=repo_language)
         except Exception:
             LOGGER.exception("orphan_pr_reconcile_failed repo=%s", repo)
-        if config is None:
-            selected = pick_resumable_delivery(
-                repo, slot_dir, max_concurrency, hooks=hooks,
-            )
-        else:
-            selected = pick_resumable_delivery(
-                repo, slot_dir, max_concurrency, config.repo_dir,
-                hooks=hooks,
-            )
+        selected = pick_resumable_delivery(
+            repo, slot_dir, max_concurrency,
+            repo_dir=config.repo_dir if config is not None else None,
+            hooks=hooks, language_code=repo_language,
+        )
         if selected is not None:
             issue, scene = selected
             return repo, issue, scene

{orbi_cli-0.7.0 → orbi_cli-0.7.2}/src/orbi/clarify.py

@@ -33,6 +33,7 @@ import re
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
+from orbi import language, notify
 from orbi.delivery_labels import NEEDS_DETAIL_LABEL, READY_LABEL
 from orbi.github import comment_issue, edit_issue
 from orbi.journal import event
@@ -43,24 +44,23 @@ if TYPE_CHECKING:
     from orbi.config import RunnerConfig
 
 
-# The three semantic checks, in the identifier -> human-terms shape the
-# comment renders: the model answers with the identifiers, the person
-# reads the sentence.
+# The three semantic check identifiers the model answers with, mapped to
+# the catalog key of the human sentence the comment renders. The JSON
+# protocol is unchanged (#1660): the identifiers stay machine values, and
+# only the RENDERER turns each one into a sentence in the run's message
+# language (English and Chinese both live in the shared catalog).
 MISSING: dict[str, str] = {
-    "observable_result": (
-        "No observable result: the ticket never says what a user sees or "
-        "does differently once the change ships."
-    ),
-    "acceptance_condition": (
-        "No acceptance condition: there is no concrete way to tell a "
-        "finished delivery from an unfinished one."
-    ),
-    "single_outcome": (
-        "More than one outcome: the ticket asks for several unrelated "
-        "things instead of one fix or one change."
-    ),
+    "observable_result": "clarify.missing.observable_result",
+    "acceptance_condition": "clarify.missing.acceptance_condition",
+    "single_outcome": "clarify.missing.single_outcome",
 }
 
+
+def missing_text(item: str, language_code: str,
+                 ) -> str:
+    """The human sentence for one failed check, in one language."""
+    return language.text(language_code, MISSING[item])
+
 CLARIFY_SYSTEM_PROMPT = (
     "You are Orbi's ticket gate. Before an unattended delivery starts, "
     "you decide whether this Issue states enough to deliver it. Judge "
@@ -153,7 +153,8 @@ def parse_verdict(output: str) -> ClarifyVerdict | None:
 
 
 def render_comment(issue: dict, verdict: ClarifyVerdict, run_id: str, *,
-                   ready_label: str = READY_LABEL) -> str:
+                   ready_label: str = READY_LABEL,
+                   language_code: str) -> str:
     """Render the ONE comment that names the missing pieces.
 
     The first line mentions the Issue author (`@<login>`, #1336) so the
@@ -162,29 +163,31 @@ def render_comment(issue: dict, verdict: ClarifyVerdict, run_id: str, *,
     before. `ready_label` is the repository's claim label (default
     `ai-ready`, #527): the repair instruction names the label the claim
     scan really reads, never a hardcoded default a custom-label
-    repository does not use.
+    repository does not use. The comment ends with the community help
+    line (Issue #1684): this stop asks the author to step in.
     """
-    pieces = "\n".join(f"- {MISSING[item]}" for item in verdict.missing)
+    def message(key: str, **fields: object) -> str:
+        return language.text(language_code, key, **fields)
+
+    pieces = "\n".join(
+        f"- {missing_text(item, language_code)}" for item in verdict.missing
+    )
     mention = _author_mention(issue)
     prefix = f"{mention}\n" if mention else ""
     return (
         f"{prefix}"
         f"{run_marker(run_id)}\n"
-        "**Orbi: this ticket is not ready to deliver.**\n\n"
-        "The pre-flight check says the Issue does not state pieces a "
-        "delivery needs:\n\n"
+        f"{message('clarify.heading')}\n\n"
+        f"{message('clarify.intro')}\n\n"
         f"{pieces}\n\n"
-        "Edit the Issue body into this shape, then add the "
-        f"`{ready_label}` label again:\n\n"
+        f"{message('clarify.repair', ready_label=ready_label)}\n\n"
         "```\n"
-        "Outcome: what a user does, and what they should see differently.\n"
-        "Acceptance: how a finished delivery is told apart from an "
-        "unfinished one.\n"
+        f"{message('clarify.repair_outcome')}\n"
+        f"{message('clarify.repair_acceptance')}\n"
         "```\n\n"
-        "Orbi re-checks the ticket when it claims it and starts the "
-        "delivery once the pieces are there. Until then the ticket "
-        f"carries `{NEEDS_DETAIL_LABEL}` and waits for you.\n\n"
-        f"run_id={run_id}\n"
+        f"{message('clarify.followup', needs_detail_label=NEEDS_DETAIL_LABEL)}"
+        f"\n\nrun_id={run_id}"
+        f"\n\n{message('help.community')}\n"
     )
 
 
@@ -241,6 +244,7 @@ def enforce(issue: dict, config: RunnerConfig, source_repo: str,
             issue["number"], repo=source_repo,
             body=render_comment(
                 issue, verdict, run_id, ready_label=ready_label,
+                language_code=language.of(config),
             ),
         )
         edit_issue(
@@ -253,6 +257,14 @@ def enforce(issue: dict, config: RunnerConfig, source_repo: str,
             issue=issue["number"], reason=type(exc).__name__,
         )
         return True
+    # Tell the person outside GitHub (Issue #1673): OUTSIDE the try (a
+    # notify problem must never turn the failed-write branch into "deliver
+    # anyway") and every stop sends — the old `ai-needs-detail` can still
+    # be on a ticket someone just re-readied.
+    notify.label_added(
+        source_repo, issue["number"], NEEDS_DETAIL_LABEL,
+        issue.get("title"),
+    )
     event(
         "clarify_needs_detail", issue=issue["number"],
         missing=",".join(verdict.missing),

{orbi_cli-0.7.0 → orbi_cli-0.7.2}/src/orbi/cli.py

@@ -36,6 +36,7 @@ from orbi import (
     config as config_domain,
     engine_source,
     git_transport,
+    notify,
     runner,
     scheduler,
     suggest,
@@ -156,11 +157,12 @@ def dispatch_issue(repo: str, title: str, body: str, *,
 
 
 def list_labeled_issues(repo: str, label: str, state: str = "open",
-                        search: str | None = None) -> list[dict]:
+                        search: str | None = None, *,
+                        timeout: int | None = None) -> list[dict]:
     """Return the newest Issues matching a label search (gh lists newest first)."""
     return list_issues(
         repo, state=state, search=search or f"label:{label}",
-        json_fields="number,title,url,state", limit=1,
+        json_fields="number,title,url,state", limit=1, timeout=timeout,
     )
 
 
@@ -170,8 +172,14 @@ def current_issue(repo: str) -> dict | None:
 
 
 def ready_issue(repo: str) -> dict | None:
+    """The ready queue, read under the status cycle's bound.
+
+    The status view owns this read, so a stalled `gh issue list` fails
+    the observation within the bound instead of hanging it (Issue #1668).
+    """
     issues = list_labeled_issues(
         repo, READY_LABEL, search=f"label:{READY_LABEL} -label:{IN_PROGRESS_LABEL}",
+        timeout=status_observe.STATUS_READ_TIMEOUT_SECONDS,
     )
     return issues[0] if issues else None
 
@@ -186,7 +194,10 @@ def recent_result(repo: str) -> dict | None:
     """
     newest = None
     for label in RESULT_LABELS:
-        for issue in list_labeled_issues(repo, label, state="all"):
+        for issue in list_labeled_issues(
+            repo, label, state="all",
+            timeout=status_observe.STATUS_READ_TIMEOUT_SECONDS,
+        ):
             if newest is None or int(issue["number"]) > int(newest["number"]):
                 newest = issue
     return newest
@@ -409,6 +420,7 @@ def doctor_report(config: config_domain.RunnerConfig, installed_dir: Path | None
             f"{finding['provider']} key={finding['variable']} "
             f"{finding['state']} (file: {finding['path']})"
         )
+    lines.extend(notify.doctor_lines(config))
     provider = pilot_setup.model_provider_status(config)
     if provider["state"] == "ok":
         lines.append(
@@ -574,25 +586,7 @@ def main(argv: list[str] | None = None) -> int:
         "--repo", default=None,
         help="source repo (default: first configured source)",
     )
-    suggest_parser = subparsers.add_parser(
-        "suggest", parents=[common],
-        help="read the repository and propose up to three Issues to "
-             "deliver (interactive; --json prints the Suggestions "
-             "document)",
-    )
-    suggest_parser.add_argument(
-        "--repo", default=None,
-        help="source repo (default: first configured source)",
-    )
-    suggest_parser.add_argument(
-        "--json", action="store_true",
-        help="print the Suggestions document to stdout and write nothing",
-    )
-    suggest_parser.add_argument(
-        "--locale", choices=["zh", "en"], default=None,
-        help="write the suggestions and the repository summary in this "
-             "language (default: the repository's own language)",
-    )
+    suggest.register_cli(subparsers, common)
     status_parser = subparsers.add_parser(
         "status", parents=[common],
         help="show every active delivery with attributed local activity, "
@@ -695,6 +689,7 @@ def main(argv: list[str] | None = None) -> int:
         "title",
         help="the exact Milestone title, e.g. v0.6.0 (must be unique)",
     )
+    notify.register_cli(subparsers, common)
     args = parser.parse_args(argv)
     configure_logging()
 
@@ -773,10 +768,11 @@ def main(argv: list[str] | None = None) -> int:
             # enforces the key), so they load the config with the
             # doctor's lenient provider flags.
             check_provider_api_keys=args.command not in (
-                "doctor", "sync-engine-source", "milestone",
+                "doctor", "sync-engine-source", "milestone", "notify",
             ),
             allow_missing_pi_providers=args.command in (
                 "setup", "doctor", "sync-engine-source", "milestone",
+                "notify",
             ),
         )
         validate_config(config)
@@ -836,7 +832,7 @@ def main(argv: list[str] | None = None) -> int:
             )
         return suggest.run_suggest(
             config, repo, json_output=args.json, locale=args.locale,
-            dispatch_issue=dispatch_issue,
+            count=args.count, dispatch_issue=dispatch_issue,
         )
     elif args.command == "session":
         path = find_session_file(config.repo_dir)
@@ -890,6 +886,8 @@ def main(argv: list[str] | None = None) -> int:
             return 1
     elif args.command == "doctor":
         print(doctor_report(config, args.installed_dir))
+    elif args.command == "notify":
+        return notify.test_command(config)
     elif args.command == "setup":
         try:
             result = pilot_setup.run_setup(

orbi_cli-0.7.2/src/orbi/comment_kind.py

@@ -0,0 +1,68 @@
+"""Canonical, display-independent comment kinds (Issue #1659).
+
+Every run-scoped comment starts with the hidden run marker
+(`<!-- orbi:run=<run_id> -->`). The four KINDED comments carry one more
+hidden marker on the line right after it:
+
+    <!-- orbi:comment=started -->
+    <!-- orbi:comment=failure -->
+    <!-- orbi:comment=review-round -->
+    <!-- orbi:comment=merged -->
+
+so a consumer identifies the comment without parsing a translatable
+heading. The kind is read only from that anchored prefix; a
+marker-shaped string quoted in prose, a raw log or a code fence is not
+official metadata. Progress comments stay deliberately kindless: their
+documented formal prefix (the run marker followed immediately by the
+`orbi:progress:v1` block) identifies them.
+
+The module is pure (the `scene` model): every function is a
+deterministic function of its input string, with no I/O, so the writer
+and every reader share one definition.
+"""
+from __future__ import annotations
+
+import re
+
+COMMENT_KIND_STARTED = "started"
+COMMENT_KIND_FAILURE = "failure"
+COMMENT_KIND_REVIEW_ROUND = "review-round"
+COMMENT_KIND_MERGED = "merged"
+COMMENT_KINDS = (
+    COMMENT_KIND_STARTED, COMMENT_KIND_FAILURE,
+    COMMENT_KIND_REVIEW_ROUND, COMMENT_KIND_MERGED,
+)
+COMMENT_KIND_TEMPLATE = "<!-- orbi:comment={kind} -->"
+COMMENT_KIND_PATTERN = re.compile(r"<!-- orbi:comment=([a-z-]+) -->")
+
+# The official metadata prefix, anchored at the body's start: the run
+# marker on the first line and, on a kinded comment, the kind marker on
+# the line immediately after. Anchoring means a marker-shaped string
+# quoted in prose, a raw log or a code fence is never read as metadata.
+_KIND_PREFIX_RE = re.compile(
+    r"\A<!-- orbi:run=[0-9a-f]{8} -->\r?\n<!-- orbi:comment=([a-z-]+) -->"
+)
+
+
+def comment_kind_marker(kind: str) -> str:
+    """Render the hidden canonical kind marker for one comment kind."""
+    if kind not in COMMENT_KINDS:
+        raise ValueError(f"unknown comment kind: {kind!r}")
+    return COMMENT_KIND_TEMPLATE.format(kind=kind)
+
+
+def comment_kind(body: object) -> str | None:
+    """The canonical kind from the body's official metadata prefix.
+
+    None means the body carries no kind marker in that prefix: a
+    historical comment (read through the existing English fallback) or a
+    kindless comment (progress, opened PR, short milestone). The kind is
+    read only from the anchored prefix, so a marker-shaped string inside
+    a raw log, a details fold or a code fence is never official
+    metadata. An unsupported kind is returned verbatim, never
+    reinterpreted through the prose next to it.
+    """
+    if not isinstance(body, str):
+        return None
+    match = _KIND_PREFIX_RE.match(body)
+    return match.group(1) if match is not None else None