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

{orbi_cli-0.7.1/src/orbi_cli.egg-info → orbi_cli-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: orbi-cli
-Version: 0.7.1
+Version: 0.7.3
 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

{orbi_cli-0.7.1 → orbi_cli-0.7.3}/pyproject.toml

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

orbi_cli-0.7.3/src/orbi/blocked_comment.py

@@ -0,0 +1,35 @@
+"""The ONE exit for a comment that blocks an Issue (Issue #1730).
+
+Ten scenes put an Issue into `ai-blocked` and each own their reason text,
+unblock step, hidden markers and extra fields. What they must NOT each own is
+the pointer to where a person can ask for help: it is appended here, once, so
+a blocked scene added later through this exit carries the community help line
+without anyone remembering to add it.
+
+A comment that is not a blocked scene (a retrying diagnostic, progress, a
+receipt) never goes through this exit and never gets the line.
+"""
+from __future__ import annotations
+
+from orbi import language
+from orbi.delivery_labels import EVENT_BLOCKED
+from orbi.github import apply_label_patch, comment_issue
+
+
+def post_blocked_comment(number: int, *, repo: str, body: str,
+                         current_labels, language_code: str) -> None:
+    """Block `number`: apply the `ai-blocked` label patch, then comment.
+
+    The order is part of the contract: the label transition lands first, the
+    comment second. The body is posted exactly as the scene rendered it,
+    followed by a blank line and the `help.community` line in the run's
+    language — added here and only here, so it appears exactly once.
+    """
+    apply_label_patch(
+        number, repo=repo, event=EVENT_BLOCKED,
+        current_labels=current_labels,
+    )
+    comment_issue(
+        number, repo=repo,
+        body=f"{body}\n\n{language.text(language_code, 'help.community')}",
+    )

{orbi_cli-0.7.1 → orbi_cli-0.7.3}/src/orbi/claim.py

@@ -18,10 +18,11 @@ from typing import NamedTuple
 
 from orbi import milestone as milestone_bookkeeping
 from orbi import scene
+from orbi.blocked_comment import post_blocked_comment
 from orbi.checks import _classify_rollup, _render_check
 from orbi.config import RunnerConfig
 from orbi.delivery_labels import (
-    AWAITING_MERGE_LABEL, BLOCKED_LABEL, EPIC_LABEL, EVENT_BLOCKED,
+    AWAITING_MERGE_LABEL, BLOCKED_LABEL, EPIC_LABEL,
     FIX_NEEDED_LABEL, IN_PROGRESS_LABEL, MERGED_LABEL, P0_LABEL,
     PR_OPENED_LABEL, READY_LABEL, RELEASE_LABEL,
 )
@@ -29,7 +30,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, 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,
@@ -40,8 +41,10 @@ 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):
@@ -49,11 +52,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]
 
@@ -195,7 +201,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}",
@@ -211,9 +217,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)
@@ -243,7 +249,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.
 
@@ -287,11 +293,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(
@@ -638,9 +643,9 @@ 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,
+    language_code: str,
 ) -> tuple[dict, dict] | None:
-    """Return the newest FREE opened-PR delivery and its resume scene.
+    """Return the oldest FREE opened-PR delivery and its resume scene.
 
     All opened-PR states are scanned: `ai-fix-needed`
     (awaiting the next review session after a finding or a base
@@ -687,12 +692,13 @@ def pick_resumable_delivery(
     excluded: `main` took it before the claim scan and holds it for the
     whole delivery.
 
-    The query page is `max_concurrency + 1` candidates. At most
+    The query page is `max_concurrency + 1` candidates, ordered OLDEST
+    Issue first (`sort:created-asc`, Issue #1734). At most
     `max_concurrency` deliveries can be held by live co-runners, so a
     free candidate is inside the page when one exists; one whose OPEN PR
-    still waits for CI (Issue #1473) is skipped too. The scan reviews the
-    newest FREE candidate (held ones are skipped before any candidate
-    read — an in-flight delivery is never touched).
+    still waits for CI (Issue #1473) is skipped too. The scan reviews
+    the oldest FREE candidate (held ones are skipped before any
+    candidate read — an in-flight delivery is never touched).
     """
     held = slot_held_deliveries(slot_dir, max_concurrency)
     # `label:a,b` is GitHub's OR within one label qualifier
@@ -712,7 +718,7 @@ def pick_resumable_delivery(
         search=(
             f"label:{FIX_NEEDED_LABEL},{PR_OPENED_LABEL},"
             f"{AWAITING_MERGE_LABEL} "
-            f"-label:{BLOCKED_LABEL} -label:{MERGED_LABEL}"
+            f"-label:{BLOCKED_LABEL} -label:{MERGED_LABEL} sort:created-asc"
         ),
         json_fields="number,title,state,url,labels,body",
         limit=max_concurrency + 1,
@@ -734,15 +740,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`.
@@ -774,7 +780,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:
@@ -791,16 +797,14 @@ def pick_resumable_delivery(
                 LOGGER.error("issue=%s resume scene is missing: %s", number, exc)
                 marker = latest_run_marker(comments)
                 try:
-                    apply_label_patch(
-                        number, repo=repo, event=EVENT_BLOCKED,
-                        current_labels={FIX_NEEDED_LABEL},
-                    )
-                    comment_issue(
+                    post_blocked_comment(
                         number, repo=repo,
                         body=(f"{marker}\n" if marker else "")
                         + language.text(
                             language_code, "claim.scene_missing", error=exc,
                         ),
+                        current_labels={FIX_NEEDED_LABEL},
+                        language_code=language_code,
                     )
                 except Exception:
                     LOGGER.exception("issue=%s failure reporting failed", number)
@@ -869,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
@@ -901,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, language_code=language.of(config),
-            )
+        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.1 → orbi_cli-0.7.3}/src/orbi/clarify.py

@@ -56,7 +56,7 @@ MISSING: dict[str, str] = {
 }
 
 
-def missing_text(item: str, language_code: str = language.DEFAULT_LANGUAGE,
+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])
@@ -154,7 +154,7 @@ def parse_verdict(output: str) -> ClarifyVerdict | None:
 
 def render_comment(issue: dict, verdict: ClarifyVerdict, run_id: str, *,
                    ready_label: str = READY_LABEL,
-                   language_code: str = language.DEFAULT_LANGUAGE) -> str:
+                   language_code: str) -> str:
     """Render the ONE comment that names the missing pieces.
 
     The first line mentions the Issue author (`@<login>`, #1336) so the
@@ -163,7 +163,8 @@ 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.
     """
     def message(key: str, **fields: object) -> str:
         return language.text(language_code, key, **fields)
@@ -185,7 +186,8 @@ def render_comment(issue: dict, verdict: ClarifyVerdict, run_id: str, *,
         f"{message('clarify.repair_acceptance')}\n"
         "```\n\n"
         f"{message('clarify.followup', needs_detail_label=NEEDS_DETAIL_LABEL)}"
-        f"\n\nrun_id={run_id}\n"
+        f"\n\nrun_id={run_id}"
+        f"\n\n{message('help.community')}\n"
     )
 
 

{orbi_cli-0.7.1 → orbi_cli-0.7.3}/src/orbi/delivery_comment.py

@@ -1,12 +1,15 @@
-"""The runner-owned run comments: the started-Pi and opened-PR scenes
-(Issue #1660).
+"""The runner-owned run comments and the PR body's footer: the
+started-Pi and opened-PR scenes (Issue #1660) and the attribution footer
+(Issue #1729).
 
 Both comments double as the run's machine-readable anchors: the started
 comment carries the `started` kind marker and the opened-PR comment
-carries the `orbi:scene:v1` block the next tick resumes from. Only their
-HEADLINE is human prose and follows the run's bound message language
-(`RunContext.language`, or an explicit `language_code`); the hidden
-markers, the field lines and the scene block stay exactly as they were.
+carries the `orbi:scene:v1` block the next tick resumes from. Their
+human text — the headline, the field labels and the stored display
+values — follows the run's bound message language (the explicit
+`language_code`); the hidden markers, the public machine rows
+(`run_id=`, `repo_config:`) and the scene block stay exactly as they
+were.
 
 Extracted from `runner.py` unchanged apart from the language, so the
 frozen runner module does not grow (Issue #1229) and a caller keeps
@@ -19,19 +22,21 @@ from orbi import language, scene
 from orbi.comment_kind import COMMENT_KIND_STARTED
 from orbi.delivery_scene import RunContext
 from orbi.journal import validate_run_id
-from orbi.progress import STARTED_HEADER, _run_info_fields, field_block
-
-
-def _language_of(ctx: RunContext, language_code: str | None) -> str:
-    """The explicit language, else the run context's bound language."""
-    if language_code is not None:
-        return language_code
-    return getattr(ctx, "language", language.DEFAULT_LANGUAGE)
+from orbi.progress import (
+    STARTED_HEADER,
+    _run_info_fields,
+    field_block,
+)
+from orbi.progress_display import (
+    field_label,
+    localized_fields,
+    vocabulary,
+)
 
 
 def started_pi_comment_body(ctx: RunContext, run_info: str,
                             extra_fields: dict | None = None, *,
-                            language_code: str | None = None) -> str:
+                            language_code: str) -> str:
     """The start comment doubles as the recoverable run scene.
 
     `extra_fields` carries the repo-config audit fields;
@@ -42,28 +47,44 @@ def started_pi_comment_body(ctx: RunContext, run_info: str,
     """
     fields = _run_info_fields(run_info)
     fields["branch"] = str(ctx.branch)
-    fields["worktree"] = str(ctx.worktree)
     if extra_fields:
         fields.update(extra_fields)
     info = _run_info_fields(run_info)
-    bound = _language_of(ctx, language_code)
+    rendered_info = {
+        key: (vocabulary(language_code, "priority", info[key])
+              if key == "priority" else info[key])
+        for key in ("run_id", "priority")
+        if key in info
+    }
     headline = language.text(
-        bound, "delivery.started_headline",
+        language_code, "delivery.started_headline",
     ) + " " + " ".join(
-        f"{key}={info[key]}" for key in ("run_id", "priority")
-        if key in info
+        f"{key}={value}" for key, value in rendered_info.items()
     )
+    detail_keys = {"base_sha", "repo_config", "branch", "session"}
     return field_block(
-        ctx.run_id, headline, fields,
-        detail_keys={"base_sha", "repo_config", "branch", "worktree", "session"},
+        ctx.run_id, headline, localized_fields(language_code, fields),
+        detail_keys={field_label(language_code, key) for key in detail_keys},
         kind=COMMENT_KIND_STARTED,
-        language_code=bound,
+        language_code=language_code,
+    )
+
+
+def pr_attribution_footer(issue: int, attribution_link: str, *,
+                          language_code: str) -> str:
+    """The PR body's attribution footer in the bound message language.
+
+    The link URL and `#<issue>` are the machine facts and stay verbatim.
+    """
+    return language.text(
+        language_code, "runner.pr_attribution",
+        link=attribution_link, issue=issue,
     )
 
 
 def opened_pr_comment_body(run_id: str, run_info: str, pr_url: str,
                            external: bool = False, *,
-                           language_code: str = language.DEFAULT_LANGUAGE,
+                           language_code: str,
                            ) -> str:
     """The PR-opened comment records the recoverable run scene.
 
@@ -95,9 +116,10 @@ def opened_pr_comment_body(run_id: str, run_info: str, pr_url: str,
         pr_url=pr_url,
         external="true" if external else "",
     )
+    detail_keys = {"base_sha", "repo_config", "branch", "session"}
     body = field_block(
-        run_id, headline, fields,
-        detail_keys={"base_sha", "repo_config", "branch", "worktree", "session"},
+        run_id, headline, localized_fields(language_code, fields),
+        detail_keys={field_label(language_code, key) for key in detail_keys},
         language_code=language_code,
     )
     lines = body.splitlines()

{orbi_cli-0.7.1 → orbi_cli-0.7.3}/src/orbi/delivery_scene.py

@@ -204,10 +204,6 @@ class RunContext:
     worktree: Path
     source_repo: str
     pr: str | None = None
-    # The run's bound message language (Issue #1660): `zh` or `en`, bound
-    # from the effective config (host + repository policy) before the
-    # first comment is written. Runtime state only -- never persisted.
-    language: str = "en"
 
 
 @dataclasses.dataclass(frozen=True)

{orbi_cli-0.7.1 → orbi_cli-0.7.3}/src/orbi/failure.py

@@ -327,7 +327,7 @@ def workflow_permission_refused(detail: str) -> bool:
 
 
 def workflow_permission_cause(
-    language_code: str = language.DEFAULT_LANGUAGE,
+    language_code: str,
 ) -> str:
     """The one-sentence cause of an Actions-workflow permission refusal."""
     return language.text(language_code, _WORKFLOW_PERMISSION_CAUSE_KEY)
@@ -335,7 +335,7 @@ def workflow_permission_cause(
 
 def workflow_permission_action(
     pr_url: str | None = None, *,
-    language_code: str = language.DEFAULT_LANGUAGE,
+    language_code: str,
 ) -> str:
     """The concrete human repair path for the workflow refusal.
 
@@ -358,7 +358,7 @@ def workflow_permission_action(
 
 
 def terminal_action(record: Failure,
-                    language_code: str = language.DEFAULT_LANGUAGE) -> str:
+                    language_code: str) -> str:
     """The reader action for the implement-phase terminal handler.
 
     An unrecognized failure says the cause could not be determined
@@ -410,7 +410,7 @@ def _workflow_permission_line(text: str) -> str | None:
 
 
 def _failure_summary(reason: str,
-                     language_code: str = language.DEFAULT_LANGUAGE) -> str:
+                     language_code: str) -> str:
     """Turn a runner exception description into a short reader summary."""
     command_failed = language.text(language_code, "failure.command_failed")
     stderr_match = re.search(r"\s+stderr=(.*)$", reason,
@@ -452,7 +452,7 @@ def _failure_comment_body(*, outcome: str, action: str, reason: str,
                          diagnosis: str, scene: str, evidence: str,
                          pr_url: str | None, issue: str, run_id: str,
                          failure_record: Failure | None = None,
-                         language_code: str = language.DEFAULT_LANGUAGE,
+                         language_code: str,
                          ) -> str:
     """Build the reader-facing hierarchy shared by classified failures.
 
@@ -529,4 +529,7 @@ def _failure_comment_body(*, outcome: str, action: str, reason: str,
     if evidence:
         details.append(evidence.lstrip())
     details.append("</details>")
+    # The blocked diagnostic's community help line is NOT added here: the
+    # ONE blocked exit appends it to every blocked comment (Issue #1730),
+    # so this renderer and that exit can never both add it.
     return "\n\n".join(parts + ["\n".join(details)])