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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orbi-cli
-Version: 0.7.0
+Version: 0.7.1
 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.1}/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.1}/pyproject.toml

@@ -44,7 +44,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "orbi-cli"
-version = "0.7.0"
+version = "0.7.1"
 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.1}/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.1"

{orbi_cli-0.7.0 → orbi_cli-0.7.1}/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.1}/src/orbi/claim.py

@@ -38,6 +38,7 @@ 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
@@ -637,6 +638,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 = language.DEFAULT_LANGUAGE,
 ) -> tuple[dict, dict] | None:
     """Return the newest FREE opened-PR delivery and its resume scene.
 
@@ -795,15 +797,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:
@@ -915,7 +911,7 @@ def pick_next_delivery(
         else:
             selected = pick_resumable_delivery(
                 repo, slot_dir, max_concurrency, config.repo_dir,
-                hooks=hooks,
+                hooks=hooks, language_code=language.of(config),
             )
         if selected is not None:
             issue, scene = selected

{orbi_cli-0.7.0 → orbi_cli-0.7.1}/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 = language.DEFAULT_LANGUAGE,
+                 ) -> 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 = language.DEFAULT_LANGUAGE) -> str:
     """Render the ONE comment that names the missing pieces.
 
     The first line mentions the Issue author (`@<login>`, #1336) so the
@@ -164,27 +165,27 @@ def render_comment(issue: dict, verdict: ClarifyVerdict, run_id: str, *,
     scan really reads, never a hardcoded default a custom-label
     repository does not use.
     """
-    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}\n"
     )
 
 
@@ -241,6 +242,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 +255,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.1}/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.1/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

{orbi_cli-0.7.0 → orbi_cli-0.7.1}/src/orbi/config.py

@@ -12,7 +12,7 @@ import tomllib
 from dataclasses import dataclass
 from pathlib import Path
 
-from orbi import engine_source
+from orbi import engine_source, language
 from orbi.pi_process import PI_MODEL_WAIT_DEAD_SECONDS, PI_MODEL_WAIT_PROBE_SECONDS
 from orbi.pilot_slots import slot_dir_for
 from orbi.release import RELEASE_CI_WAIT_SECONDS, RELEASE_DELIVERIES_WAIT_SECONDS
@@ -136,6 +136,16 @@ class RunnerConfig:
     max_concurrency: int = 1
     allow_stale_runner: bool = False
     human_review_gate: bool = False
+    # Telegram notifications (Issue #1673): ON when `telegram_chat_id` is
+    # set. `ORBI_TELEGRAM_BOT_TOKEN` lives in `<deploy_home>/.orbi/env`,
+    # never here; the message language is the host-level
+    # `message_language` (#1660), read by `notify` when it is present.
+    telegram_chat_id: str | None = None
+    # The message language of Orbi's own comments (Issue #1660), validated
+    # to `zh`/`en` by `load_config`. `resolve_policy` replaces it with the
+    # repository's explicit `.github/orbi.toml` value when the file
+    # declares one; absent everywhere -> "en".
+    message_language: str = language.DEFAULT_LANGUAGE
     attribution_footer: bool = True
     attribution_link: str = "https://github.com/orbi-build/orbi"
     slot_dir: Path | None = None
@@ -254,6 +264,23 @@ def load_config(path: Path, *, check_provider_api_keys: bool = True,
     human_review_gate = data.get("human_review_gate", False)
     if not isinstance(human_review_gate, bool):
         raise ValueError("human_review_gate must be a boolean")
+    # Notifications (Issue #1673): ON when `telegram_chat_id` is a
+    # non-empty string; absent = off. A present-but-invalid value is a
+    # misconfiguration and fails the load fast (Article 4.5); the bot
+    # token itself is a separate, optional bypass and never fails a start.
+    telegram_chat_id = data.get("telegram_chat_id")
+    if telegram_chat_id is not None and (
+        not isinstance(telegram_chat_id, str) or not telegram_chat_id
+    ):
+        raise ValueError("telegram_chat_id must be a non-empty string")
+    # The message language of Orbi's comments (Issue #1660). Host-only
+    # validation: an unsupported value fails the load fast naming the file,
+    # the key, the value and the allowed values; the repository's explicit
+    # override is validated by the repository policy reader.
+    message_language = language.normalize_language(
+        data.get(language.MESSAGE_LANGUAGE_KEY, language.DEFAULT_LANGUAGE),
+        source=str(path.resolve()),
+    )
     attribution_footer = data.get("attribution_footer", True)
     if not isinstance(attribution_footer, bool):
         raise ValueError("attribution_footer must be a boolean")
@@ -458,6 +485,8 @@ def load_config(path: Path, *, check_provider_api_keys: bool = True,
         max_concurrency=max_concurrency,
         allow_stale_runner=allow_stale_runner,
         human_review_gate=human_review_gate,
+        telegram_chat_id=telegram_chat_id,
+        message_language=message_language,
         attribution_footer=attribution_footer,
         attribution_link=attribution_link,
         slot_dir=slot_dir_for(repo_dir),