alissa-tools-github-devloop 0.8.19__tar.gz → 0.8.20__tar.gz

{alissa_tools_github_devloop-0.8.19/src/main/alissa_tools_github_devloop.egg-info → alissa_tools_github_devloop-0.8.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.8.19
+Version: 0.8.20
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

{alissa_tools_github_devloop-0.8.19 → alissa_tools_github_devloop-0.8.20}/src/main/alissa/tools/github/devloop/janitor.py

@@ -42,16 +42,58 @@ from .proc import CommandError, run
 
 log = logging.getLogger(__name__)
 
-# A task workspace's directory name, which is ALSO its branch name: the
-# directives mandate `git worktree add TASK-<n>-<DESC>` with <n> the worker's
-# own implementation task, and `pr_task_ref` in loop.py already reads the same
-# shape off a PR's head ref. Full-matched, never prefix-matched, for
-# `parse_worker_session`'s reason: this module's consumer deletes directories,
-# and `TASK-` matches anything an operator felt like naming that way. The
-# description charset is the branch charset the fix edge already refuses to
-# leave (`[A-Za-z0-9._-]+`), so a name that would need shell quoting is not
-# one of ours.
-TASK_WORKSPACE_RE = re.compile(r"TASK-(?P<task>\d+)(?:-(?P<desc>[A-Za-z0-9._-]+))?")
+# A task workspace's directory name. The directives mandate `git worktree add
+# TASK-<n>-<DESC>` with <n> the worker's own implementation task, and
+# `pr_task_ref` in loop.py reads the same shape off a PR's head ref -- and,
+# since issue #115, the PR-side directives tolerate a branch behind one
+# `task/` prefix and then say `git worktree add task--TASK-<n>-<DESC>
+# task/TASK-<n>-<DESC>`: the directory is the branch with `/` rewritten to
+# `--` (WORKTREE_DIR_SEPARATOR) so the worktree stays a flat direct child of
+# the hub. So a workspace directory is the flat shape, or the flat shape
+# behind `task--`, or `task--<n>-<desc>` (the `TASK-` literal dropped, the
+# third shape the incident's workers produced). Full-matched, never
+# prefix-matched, for `parse_worker_session`'s reason: this module's consumer
+# deletes directories, and `TASK-` matches anything an operator felt like
+# naming that way. The description charset is the branch charset the fix
+# edge already refuses to leave (`[A-Za-z0-9._-]+`), so a name that would
+# need shell quoting is not one of ours.
+TASK_WORKSPACE_RE = re.compile(
+    r"(?:task--(?:TASK-)?|TASK-)(?P<task>\d+)(?:-(?P<desc>[A-Za-z0-9._-]+))?"
+)
+
+# The same grammar as a BRANCH name -- the directory grammar with the
+# rewritten separator put back. `is_task_branch` asks this one; the two are
+# kept side by side so the pair a `task--…` directory promises (`task/…`
+# checked out in it) is one mapping stated once (`branch_of_dir`).
+TASK_BRANCH_RE = re.compile(
+    r"(?:task/(?:TASK-)?|TASK-)(?P<task>\d+)(?:-(?P<desc>[A-Za-z0-9._-]+))?"
+)
+
+# What a branch's `/` becomes in its worktree directory's name, and the
+# prefix that marks a directory as carrying one. Only a directory that BEGINS
+# with `task--` is ever read back as a prefixed branch, so a flat branch that
+# happens to contain `--` mid-name maps to itself in both directions.
+WORKTREE_DIR_SEPARATOR = "--"
+_PREFIXED_DIR = "task" + WORKTREE_DIR_SEPARATOR
+_PREFIXED_BRANCH = "task/"
+
+
+def dir_of_branch(branch: str) -> str:
+    """The worktree directory name for `branch`: `/` rewritten to `--`, so a
+    `task/TASK-<n>-<DESC>` branch lives in `task--TASK-<n>-<DESC>` and a flat
+    branch in a directory of its own name. Pure string mapping -- the shape
+    gates are the caller's (`loop.worktree_dir` applies them)."""
+    return branch.replace("/", WORKTREE_DIR_SEPARATOR)
+
+
+def branch_of_dir(name: str) -> str:
+    """The branch a workspace directory `name` promises: the inverse of
+    `dir_of_branch` for the one prefix the daemon tolerates. `task--X` ->
+    `task/X`; anything else is its own branch name."""
+    if name.startswith(_PREFIXED_DIR):
+        return _PREFIXED_BRANCH + name[len(_PREFIXED_DIR):]
+    return name
+
 
 # Where the `archive` holdout policy pushes unpushed work (issue #99): a NEW
 # ref under this prefix, named after the task branch. Never the task branch
@@ -85,12 +127,14 @@ DEFAULT_CACHE_PATHS: "tuple[str, ...]" = (
 class TaskWorkspace:
     """One per-task workspace directory, parsed back into what it is.
 
-    `branch` is the directory name verbatim -- the two are the same string by
-    construction (`git worktree add TASK-<n>-<DESC>` names the worktree
-    directory and the branch together), and keeping both names for one value
-    is what makes the removal code read honestly: the directory is removed by
-    path, the branch is deleted by name, and a future layout where they differ
-    has one place to fix.
+    `branch` is the branch the directory name PROMISES (`branch_of_dir`):
+    the directory name itself for the flat shape (`git worktree add
+    TASK-<n>-<DESC>` names the worktree directory and the branch together),
+    and `task/…` for a `task--…` directory (the PR-side directives' flat
+    worktree dir for a tolerated `task/`-prefixed branch, issue #115). The
+    removal code reads honestly either way: the directory is removed by path,
+    the branch is deleted by name, and the reclaim's first gate checks that
+    the checked-out branch IS the promised one.
     """
 
     path: Path
@@ -125,18 +169,23 @@ def parse_task_workspace(path: Path, hub: Path) -> "TaskWorkspace | None":
     if match is None:
         return None
     return TaskWorkspace(
-        path=path, branch=path.name, task=int(match["task"]), hub=hub
+        path=path,
+        branch=branch_of_dir(path.name),
+        task=int(match["task"]),
+        hub=hub,
     )
 
 
 def is_task_branch(name: str) -> bool:
-    """Is `name` one of devloop's own task branches (`TASK-<n>-<DESC>`)?
-
-    The same full-match grammar `parse_task_workspace` admits directories
-    with, re-asserted by name at the one place that pushes: the archive path
-    writes a ref to the remote, and its name is derived from this one, so a
-    branch the daemon did not create must never get a `holdout/` twin."""
-    return TASK_WORKSPACE_RE.fullmatch(name) is not None
+    """Is `name` one of devloop's own task branches (`TASK-<n>-<DESC>`, or the
+    tolerated `task/TASK-<n>-<DESC>` / `task/<n>-<desc>`)?
+
+    The branch twin of the full-match grammar `parse_task_workspace` admits
+    directories with, re-asserted by name at the one place that pushes: the
+    archive path writes a ref to the remote, and its name is derived from
+    this one, so a branch the daemon did not create must never get a
+    `holdout/` twin."""
+    return TASK_BRANCH_RE.fullmatch(name) is not None
 
 
 def holdout_ref(branch: str) -> str:

{alissa_tools_github_devloop-0.8.19 → alissa_tools_github_devloop-0.8.20}/src/main/alissa/tools/github/devloop/loop.py

@@ -223,7 +223,9 @@ attempt number in, and a fresh budget reusing attempt 1 could collide with
 a prior epoch's zombie session. With no readable labeled event the budget
 conservatively stays lifetime-wide (the pre-epoch behavior). The re-fetch
 guards mirror the fix edge's: closed/merged between search and fetch, a
-foreign author, and a foreign-shaped head ref all skip.
+foreign author, and a foreign-shaped head ref all skip (a `task/`-prefixed
+worker branch is NOT foreign since issue #115 -- WORKER_HEAD_REF -- and the
+skip is paged on the PR once per head rather than logged every poll).
 
 All three edges share ONE backpressure valve, `max_sessions` (0 = unlimited,
 the default -- today's behavior preserved). The daemon spawns a session per
@@ -696,6 +698,23 @@ _REVIEW_SEAT = (
     "foreign session the daemon reaps, and its verdict reaches nobody. "
 )
 
+# The branch-NAME rule, stated as a hard MUST with its negative and its
+# consequence (issue #115). The 2026-09-09/10 studio incident: three workers
+# in one window named their branches `task/…` despite the golden-path line
+# above -- the common convention won over a directive that only stated the
+# positive. The daemon now TOLERATES exactly that one deviation on the way
+# back in (WORKER_HEAD_REF), but the rule is still the flat shape, because
+# every other prefix is still foreign and the tolerance is a repair, not a
+# licence. Shared by the issue edge (where the branch is created) and, as a
+# restatement, by the fix and maintain directives (where it is reused).
+_BRANCH_RULE = (
+    "The branch name is a hard rule, not a convention: name the branch "
+    "exactly `TASK-<n>-<DESC>` — NO `task/`, `feat/` or any other prefix, no "
+    "lowercase `task-`; the daemon's fix and maintain edges only spawn on "
+    "that shape, and a PR on any other shape gets no fix round, no "
+    "maintenance and no resume until an operator renames it. "
+)
+
 DEV_DIRECTIVE = (
     "You are an IMPLEMENTER, not a reviewer. Implement GitHub issue "
     "{issue_url} (attempt {attempt} of {cap}) — the issue is your "
@@ -708,7 +727,8 @@ DEV_DIRECTIVE = (
     "origin collides with every sibling of that origin), from there (one "
     "task = one branch = one worktree; never clone, never work directly on "
     "main). "
-    "Implement to the issue's acceptance criteria and VERIFY locally (run the "
+    + _BRANCH_RULE
+    + "Implement to the issue's acceptance criteria and VERIFY locally (run the "
     "repo's test/style/type scripts) before publishing. Open a DRAFT PR whose "
     "body contains `Closes #{number}` and BOTH task refs — the origin task "
     "AND your implementation task: the PR body is the canonical cross-actor "
@@ -758,10 +778,12 @@ RESUME_DIRECTIVE = (
     "session got. Golden path: your cwd is the repo's worktree hub ROOT and "
     "the PR's head branch `{head_ref}` ALREADY EXISTS — REUSE its worktree if "
     "one is still on the volume (the dead session's work is in it), otherwise "
-    "re-attach it with `git worktree add {head_ref} {head_ref}`. Work ONLY on "
-    "that branch: never a new branch, never a clone, never main, and NEVER a "
-    "second PR — the open one IS the deliverable, and pushing more commits to "
-    "it is how you deliver. "
+    "re-attach it with `git worktree add {worktree_dir} {head_ref}` (the "
+    "directory and the branch differ only when the branch carries a prefix: "
+    "`/` becomes `--` in the directory name). Work ONLY on that branch, "
+    "under its EXISTING name: never a new branch, never a rename, never a "
+    "clone, never main, and NEVER a second PR — the open one IS the "
+    "deliverable, and pushing more commits to it is how you deliver. "
     "Then complete the ORIGINAL acceptance criteria — the issue's criteria "
     "are unchanged and still authoritative — and VERIFY locally (run the "
     "repo's test/style/type scripts) before publishing. NEVER force-push: "
@@ -798,9 +820,13 @@ FIX_DIRECTIVE = (
     "of your job: the PR body is the canonical cross-actor record. "
     "Golden path: your cwd is the repo's worktree hub ROOT and the PR's head "
     "branch `{head_ref}` already exists — re-attach its worktree with `git "
-    "worktree add {head_ref} {head_ref}` if it is missing, and work ONLY on "
-    "that branch (never a new branch, never a clone, never main). "
-    "FIRST verify the triage of every prior review finding per CR8: exactly "
+    "worktree add {worktree_dir} {head_ref}` if it is missing (the directory "
+    "and the branch differ only when the branch carries a prefix: `/` becomes "
+    "`--` in the directory name), and work ONLY on that branch under its "
+    "EXISTING name (never a new branch, never a rename, never a clone, never "
+    "main). "
+    + _BRANCH_RULE
+    + "FIRST verify the triage of every prior review finding per CR8: exactly "
     "one reasoned `[triage:*]` reply on each finding's thread — post any that "
     "are missing. Then fix the pursued findings on the same branch and VERIFY "
     "locally (run the repo's test/style/type scripts). "
@@ -847,10 +873,13 @@ FIX_RESUME_DIRECTIVE = (
     "far the dead session got. Golden path: your cwd is the repo's worktree "
     "hub ROOT and the PR's head branch `{head_ref}` ALREADY EXISTS — REUSE "
     "its worktree if one is still on the volume (the dead session's work is "
-    "in it), otherwise re-attach it with `git worktree add {head_ref} "
-    "{head_ref}`. Work ONLY on that branch: never a new branch, never a "
-    "clone, never main, and NEVER a second PR. "
-    "The dead session may have posted SOME of its CR8 triage replies already: "
+    "in it), otherwise re-attach it with `git worktree add {worktree_dir} "
+    "{head_ref}` (the directory and the branch differ only when the branch "
+    "carries a prefix: `/` becomes `--` in the directory name). Work ONLY on "
+    "that branch under its EXISTING name: never a new branch, never a "
+    "rename, never a clone, never main, and NEVER a second PR. "
+    + _BRANCH_RULE
+    + "The dead session may have posted SOME of its CR8 triage replies already: "
     "read every finding's thread and post exactly the ones that are missing — "
     "one reasoned `[triage:*]` reply per finding, NEVER a duplicate on a "
     "thread it already answered. Then fix the pursued findings, completing "
@@ -890,9 +919,13 @@ MAINTAIN_DIRECTIVE = (
     "freshen it. "
     "Golden path: your cwd is the repo's worktree hub ROOT and the PR's head "
     "branch `{head_ref}` already exists — re-attach its worktree with `git "
-    "worktree add {head_ref} {head_ref}` if it is missing, and work ONLY on "
-    "that branch (never a new branch, never a clone, never main). "
-    "FIRST the idempotent no-op check: if the branch is already conflict-free "
+    "worktree add {worktree_dir} {head_ref}` if it is missing (the directory "
+    "and the branch differ only when the branch carries a prefix: `/` becomes "
+    "`--` in the directory name), and work ONLY on that branch under its "
+    "EXISTING name (never a new branch, never a rename, never a clone, never "
+    "main). "
+    + _BRANCH_RULE
+    + "FIRST the idempotent no-op check: if the branch is already conflict-free "
     "AND current vs origin/main, remove the `{label}` label from the PR "
     "(`gh pr edit {number} --remove-label \"{label}\"`) and exit — push "
     "nothing, re-request nobody; this no-op path is what makes retries safe. "
@@ -1032,6 +1065,21 @@ STACKED_BASE_COMMENT = (
     "belongs to release gating, not to the PR graph."
 )
 
+FOREIGN_HEAD_COMMENT = (
+    "**Dev loop: foreign-shaped head ref `{head_ref}`** — the daemon will not "
+    "run fix or maintain rounds on it. Worker branches must be named exactly "
+    "`TASK-<n>-<DESC>` (a single `task/` prefix is tolerated: "
+    "`task/TASK-<n>-<DESC>` or `task/<n>-<desc>`); any other prefix, a "
+    "second `/`, whitespace or shell metacharacters keep the daemon off the "
+    "branch, because the name is interpolated into a worker session's "
+    "prompt as a worktree path and a shell token. Until the head moves, "
+    "review findings on this PR reach no session and a maintenance label is "
+    "ignored. Operator options: rename the branch (`git branch -m` + push, "
+    "then re-open or retarget the PR), or re-open the PR from a "
+    "`TASK-<n>-<DESC>` branch. Paged once per head; a new head on the same "
+    "shape pages again."
+)
+
 ASSIGNMENT_REJECTED_COMMENT = (
     "**Dev loop cannot start** — the daemon tried to self-assign this issue "
     "as its in-flight marker, but GitHub silently dropped the assignment: "
@@ -1251,6 +1299,16 @@ ESCALATION_ORPHAN_REJECTED = "orphan-rejected"
 # number, like every other PR-side kind here.
 ESCALATION_STACKED_BASE = "stacked-base"
 
+# The fix/maintain edges' foreign-shaped-head skip, paged ON the PR once per
+# (PR, head) (`foreign_head_kind`, issue #115). Before it, the skip was one
+# WARNING per poll in a log nobody tails and NOTHING on the PR: three
+# reviewed studio PRs sat for 1-12 h behind it. Keyed per HEAD, not per PR,
+# because the remedy is to move the head (rename the branch, re-open from a
+# `TASK-<n>-<DESC>` one) and a PR whose head moved and is still foreign has
+# earned a second page. The `foreign-head` prefix keeps these rows from
+# colliding with any issue-edge kind when an issue and a PR share a number.
+ESCALATION_FOREIGN_HEAD = "foreign-head"
+
 # The `archive` holdout policy could not archive a workspace (issue #99): the
 # commit, the push to the holdout ref, or the ls-remote verification failed,
 # or the remote sha did not equal the local HEAD. Keyed per WORKSPACE slug
@@ -1341,6 +1399,11 @@ def rerequest_rejected_kind(round_: int, head_sha: str) -> str:
     return f"{ESCALATION_REREQUEST_REJECTED}:r{round_}@{head_sha}"
 
 
+def foreign_head_kind(head_sha: str) -> str:
+    """The ledger kind for the foreign-shaped-head page on ONE (PR, head)."""
+    return f"{ESCALATION_FOREIGN_HEAD}:{head_sha}"
+
+
 def orphan_kind(head_sha: str) -> str:
     """The ledger kind that marks ONE draft's mechanical handoff as DONE.
 
@@ -1521,16 +1584,60 @@ STALLED_DEFER_MULTIPLE = 2
 # long enough to need scrolling is one nobody reads.
 DISK_OFFENDERS = 3
 
-# The daemon's own branch shape. head_ref reaches every worker directive as
-# BOTH a worktree path and a shell token (`git worktree add {head_ref}
-# {head_ref}`), and a PR's head branch is not strictly self-authored (anyone
-# with push access can move it) -- so every PR-side spawn gates on it: the fix
-# and maintain edges via `_foreign_head_skip`, the issue edge's resume via
-# `_resumable_pr`. Slashes that would nest the worktree path, whitespace and
-# shell metacharacters are all outside it, and a ref outside this shape is not
-# this daemon's work anyway: skip conservatively rather than sanitize.
+# The daemon's own branch shape -- the one its directives NAME (`TASK-<n>-
+# <DESC>`, flat). head_ref reaches every worker directive as a shell token
+# (`git worktree add {worktree_dir} {head_ref}`), and a PR's head branch is
+# not strictly self-authored (anyone with push access can move it) -- so every
+# PR-side spawn gates on a shape test: the fix and maintain edges via
+# `_foreign_head_skip`, the issue edge's resume via `_resumable_pr`. This is
+# also the shape the WORKTREE DIRECTORY must have (`worktree_dir`), since a
+# slash there would nest the worktree under the hub. Whitespace and shell
+# metacharacters are all outside it: skip conservatively rather than sanitize.
 DAEMON_HEAD_REF = re.compile(r"[A-Za-z0-9._-]+")
 
+# The shape a WORKER'S branch is tolerated in: the daemon's own flat shape, or
+# that shape behind exactly one `task/` prefix (issue #115). The 2026-09-09/10
+# studio incident: three of five worker sessions in one window named their
+# branches `task/TASK-<n>-<desc>` / `task/<n>-<desc>` despite the directive,
+# and DAEMON_HEAD_REF -- flat by design, because head_ref used to be the
+# worktree PATH as well as the branch -- stranded all three: no fix round, no
+# maintain, no resume, a WARNING per poll for 12 h. The work was complete and
+# reviewed; only the gate stood between it and a fix session. So the PR-side
+# gates admit this ONE common deviation, with the worktree path derived by
+# `worktree_dir` so the directory stays flat. Everything else stays foreign:
+# any other prefix (`feat/x`), a second slash (`a/b/c`), whitespace, shell
+# metacharacters. `DAEMON_HEAD_REF` stays what the daemon itself names, and
+# DEV_DIRECTIVE still forbids the prefix -- tolerating it on the way back in
+# is not the same as licensing it on the way out.
+WORKER_HEAD_REF = re.compile(r"(?:task/)?[A-Za-z0-9._-]+")
+
+
+def worktree_dir(head_ref: str) -> str:
+    """The worktree DIRECTORY a PR-side directive tells its session to create
+    for `head_ref`: the branch name with `/` rewritten to `--`, so the
+    worktree stays a flat direct child of the hub whatever the branch is
+    called (`task/TASK-42384172-sales-chat-surface` ->
+    `task--TASK-42384172-sales-chat-surface`; a flat name maps to itself).
+
+    Both values are interpolated into an agent prompt as shell tokens, so
+    BOTH pass the shape tests before anything is rendered: the branch must be
+    WORKER_HEAD_REF and the directory DAEMON_HEAD_REF (flat, no metacharacters).
+    A `head_ref` that fails either raises rather than rendering -- the gates
+    upstream (`_foreign_head_skip`, `_resumable_pr`) are what keep such a ref
+    from reaching here, and this is the assertion that they did. The mapping
+    itself is the janitor's (`janitor.dir_of_branch`), so the directory the
+    directive names and the one the janitor reclaims cannot drift apart.
+    """
+    if not WORKER_HEAD_REF.fullmatch(head_ref or ""):
+        raise ValueError(f"head ref {head_ref!r} is not a worker branch shape")
+    directory = janitor.dir_of_branch(head_ref)
+    if not DAEMON_HEAD_REF.fullmatch(directory):
+        raise ValueError(
+            f"worktree dir {directory!r} for head ref {head_ref!r} is not flat"
+        )
+    return directory
+
+
 # GitHub's closing keywords, the PROVENANCE signal behind a resume. Every
 # other admission test the resume applies asks what STATE a PR is in (open,
 # draft, unreviewed, self-authored, daemon-shaped head) -- and a sibling
@@ -1621,6 +1728,14 @@ def closed_issue_numbers(body: str, owner: str, repo: str) -> "tuple[int, ...]":
 # mid-name is not the convention.
 DAEMON_TASK_BRANCH = re.compile(r"TASK-(\d+)(?:-|$)")
 
+# The same convention as a WORKER may have written it (issue #115, the
+# tolerated deviation WORKER_HEAD_REF admits): the flat form, or the flat form
+# behind one `task/`, or `task/<n>-<desc>` with the `TASK-` literal dropped --
+# the three shapes the studio incident's workers actually produced. The task
+# number is the segment after the prefix either way (`task/609837646-…` counts
+# as TASK-609837646). Still anchored at the start, still no other prefix.
+WORKER_TASK_BRANCH = re.compile(r"(?:task/(?:TASK-)?|TASK-)(\d+)(?:-|$)")
+
 # The follow-up PR's provenance trailer, mandated by _APPROVE_FOLLOWUP and read
 # by the orphan sweep's liveness matrix.
 #
@@ -1680,7 +1795,9 @@ def pr_task_ref(head_ref: str, body: str) -> "int | None":
     dead session cannot have failed to establish (it exists before the PR
     does), while a body ref can be missing precisely because the session died
     before writing it. Falling back to the body still catches the PR whose
-    branch was named some other way but whose record is intact.
+    branch was named some other way but whose record is intact. The branch is
+    read with WORKER_TASK_BRANCH, so a `task/`-prefixed worker branch names
+    its task exactly as a flat one does (issue #115).
 
     Deliberately NOT `parse_task_ref`: that reads the `Alissa-Task:` TRAILER an
     ISSUE carries, and a PR body's task refs are prose ("origin TASK-1, mine
@@ -1688,7 +1805,7 @@ def pr_task_ref(head_ref: str, body: str) -> "int | None":
     logging and the activity line only -- nothing keys off WHICH task it is,
     only that the PR names one.
     """
-    match = DAEMON_TASK_BRANCH.match(head_ref or "")
+    match = WORKER_TASK_BRANCH.match(head_ref or "")
     if match:
         return int(match.group(1))
     match = TASK_REF_RE.search(body or "")
@@ -2965,6 +3082,7 @@ class DevWatcher:
                 session=name,
                 pr_url=resume_pr.url,
                 head_ref=resume_pr.head_ref,
+                worktree_dir=worktree_dir(resume_pr.head_ref),
                 dead_session=dead_session,
             )
         else:
@@ -3121,11 +3239,12 @@ class DevWatcher:
         timeline: still OPEN, authored by the token identity (a foreign PR
         must never grow a session pushing to its branch -- `linked_open_prs`
         filters on open + same-repo only, so a collaborator's or a fork's PR
-        qualifies there), and a head ref of this daemon's own flat shape.
-        Resolving head_ref here is also what lets RESUME_DIRECTIVE NAME the
-        branch instead of telling the agent to derive it from the PR -- an
-        unsanitized token read out of GitHub is exactly what DAEMON_HEAD_REF
-        exists to keep out of an agent prompt.
+        qualifies there), and a head ref of a worker branch shape
+        (WORKER_HEAD_REF: the daemon's own flat shape, or that shape behind
+        one tolerated `task/`). Resolving head_ref here is also what lets
+        RESUME_DIRECTIVE NAME the branch instead of telling the agent to
+        derive it from the PR -- an unsanitized token read out of GitHub is
+        exactly what the shape test exists to keep out of an agent prompt.
 
         Those four tests all ask what STATE a PR is in; none asks whether it
         is OURS. `linked_open_prs` admits any open same-repo PR that
@@ -3212,7 +3331,7 @@ class DevWatcher:
                     pr.author,
                 )
                 continue
-            if not DAEMON_HEAD_REF.fullmatch(pr.head_ref):
+            if not WORKER_HEAD_REF.fullmatch(pr.head_ref):
                 log.warning(
                     "%s: %s head ref %r does not match the daemon's own "
                     "branch shape — not resuming onto a foreign-shaped "
@@ -4507,9 +4626,10 @@ class DevWatcher:
         # head_ref reaches nothing but log lines here (the sweep spawns no
         # session, so it never becomes a worktree path or a shell token), but
         # the shape is still the provenance signal every other PR-side act
-        # gates on: this daemon only ever creates flat `TASK-<n>-<DESC>`
-        # branches, so a ref outside that shape is not its work.
-        if not DAEMON_HEAD_REF.fullmatch(pr.head_ref):
+        # gates on: this daemon's workers create flat `TASK-<n>-<DESC>`
+        # branches (or, tolerated, the same behind one `task/` -- issue
+        # #115), so a ref outside that shape is not its work.
+        if not WORKER_HEAD_REF.fullmatch(pr.head_ref):
             return Decision(
                 Action.SKIPPED,
                 f"draft head ref {pr.head_ref!r} does not match the daemon's "
@@ -5423,28 +5543,92 @@ class DevWatcher:
 
     def _foreign_head_skip(self, pr: PullRequest, attempt: int) -> "Decision | None":
         """The head-ref shape guard for the PR-side edges that evaluate ONE
-        PR (fix and maintain): this daemon only ever creates flat
-        `TASK-<n>-<DESC>` branches, so a ref outside DAEMON_HEAD_REF is not
-        its work. Returns the SKIPPED Decision, or None when the ref is safe
-        to interpolate. (The issue edge's resume applies the same shape test
-        via `_resumable_pr`, which filters candidates rather than skipping
-        the item.)"""
-        if DAEMON_HEAD_REF.fullmatch(pr.head_ref):
+        PR (fix and maintain): this daemon's workers create flat
+        `TASK-<n>-<DESC>` branches -- or, tolerated since issue #115, the
+        same behind exactly one `task/` -- so a ref outside WORKER_HEAD_REF
+        is not its work. Returns the SKIPPED Decision, or None when the ref
+        is safe to interpolate (as `worktree_dir(head_ref)` + `head_ref`).
+        (The issue edge's resume applies the same shape test via
+        `_resumable_pr`, which filters candidates rather than skipping the
+        item.)
+
+        A skip is PAGED on the PR, once per (PR, head) -- `_page_foreign_head`
+        -- rather than logged at WARNING every poll: the skip is a standing
+        condition nothing else in the system will ever surface (no session is
+        spawned, so no activity line; the reviewer daemon has done its part),
+        and the 2026-09-09/10 incident measured the cost of a log-only signal
+        at 1-12 h per PR. The decision itself is unchanged by the page.
+        """
+        if WORKER_HEAD_REF.fullmatch(pr.head_ref):
             return None
-        log.warning(
-            "%s head ref %r does not match the daemon's own branch shape "
-            "— not spawning a worker session on a foreign-shaped branch",
-            pr.pr_slug,
-            pr.head_ref,
-        )
+        self._page_foreign_head(pr)
         return Decision(
             Action.SKIPPED,
             f"head ref {pr.head_ref!r} does not match the daemon's own "
-            f"branch shape ([A-Za-z0-9._-]+) — foreign-shaped branch, "
-            f"not this daemon's work",
+            f"branch shape (TASK-<n>-<DESC>, or task/ + that) — "
+            f"foreign-shaped branch, not this daemon's work",
             attempt,
         )
 
+    def _page_foreign_head(self, pr: PullRequest) -> bool:
+        """Page the operator ONCE per (PR, head) that the head-ref guard is
+        skipping this PR, on the PR. Returns whether the page was raised.
+
+        `_check_stacked_base`'s doctrine: advisory by construction (the guard
+        still skips; nothing renames or closes anything), and the row lands
+        only AFTER the comment posts, so a transient POST failure retries next
+        poll rather than being recorded as delivered. Dry-run logs and records
+        nothing. Every poll after the first sees the row and logs at DEBUG --
+        the per-poll WARNING this replaces was the silence the incident hid
+        behind. A head with no readable sha cannot be keyed and keeps the
+        per-poll WARNING instead of paging (only reachable from a malformed
+        payload).
+        """
+        if not pr.head_sha:
+            log.warning(
+                "%s head ref %r does not match the daemon's own branch shape "
+                "— not spawning a worker session on a foreign-shaped branch "
+                "(no head sha to key a page on)",
+                pr.pr_slug,
+                pr.head_ref,
+            )
+            return False
+        kind = foreign_head_kind(pr.head_sha)
+        if self.state.escalated(pr.full_name, pr.number, kind):
+            log.debug(
+                "%s head ref %r is foreign-shaped — skipped (already paged "
+                "on head %s)",
+                pr.pr_slug,
+                pr.head_ref,
+                pr.head_sha[:8],
+            )
+            return False
+
+        log.error(
+            "FOREIGN HEAD %s: head ref %r does not match the daemon's own "
+            "branch shape — no fix or maintain round will spawn on it; "
+            "paging the operator on the PR once for head %s",
+            pr.pr_slug,
+            pr.head_ref,
+            pr.head_sha[:8],
+        )
+        body = FOREIGN_HEAD_COMMENT.format(head_ref=pr.head_ref)
+        if self.config.dry_run:
+            log.info("[dry-run] would comment on %s:\n%s", pr.pr_slug, body)
+            return False
+        try:
+            self.github.comment(pr.owner, pr.repo, pr.number, body)
+        except CommandError as exc:
+            log.error(
+                "could not post the foreign-head comment on %s: %s — not "
+                "recording the page; it retries next poll",
+                pr.pr_slug,
+                exc,
+            )
+            return False
+        self.state.record_escalation(pr.full_name, pr.number, kind)
+        return True
+
     def _spawn_fix(
         self,
         pr: PullRequest,
@@ -5521,6 +5705,7 @@ class DevWatcher:
             attempt=attempt,
             cap=self.config.attempt_cap,
             head_ref=pr.head_ref,
+            worktree_dir=worktree_dir(pr.head_ref),
             # Re-request the reviewer whose request_changes this round
             # answers -- precise, and always resolvable (the review exists).
             reviewer=review.author,
@@ -5780,6 +5965,7 @@ class DevWatcher:
             attempt=attempt,
             cap=self.config.attempt_cap,
             head_ref=pr.head_ref,
+            worktree_dir=worktree_dir(pr.head_ref),
             reviewers=reviewers,
             session=name,
         )

alissa_tools_github_devloop-0.8.20/src/main/alissa/tools/github/devloop/version

@@ -0,0 +1 @@
+0.8.20

{alissa_tools_github_devloop-0.8.19 → alissa_tools_github_devloop-0.8.20/src/main/alissa_tools_github_devloop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.8.19
+Version: 0.8.20
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

alissa_tools_github_devloop-0.8.19/src/main/alissa/tools/github/devloop/version

@@ -1 +0,0 @@
-0.8.19