alissa-tools-github-devloop 0.5.0__tar.gz → 0.5.1__tar.gz

{alissa_tools_github_devloop-0.5.0/src/main/alissa_tools_github_devloop.egg-info → alissa_tools_github_devloop-0.5.1}/PKG-INFO

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

{alissa_tools_github_devloop-0.5.0 → alissa_tools_github_devloop-0.5.1}/src/main/alissa/tools/github/devloop/ghclient.py

@@ -147,6 +147,20 @@ class Review:
         return bool(self.body.strip())
 
 
+@dataclass(frozen=True)
+class IssueComment:
+    """An issue comment on an issue OR a PR (a PR is an issue on the issues
+    endpoints). Distinct from Review: issue comments live on the
+    `/issues/{n}/comments` endpoints and never create review records, so
+    posting or PATCHing one can never disturb the fix edge's round counting
+    or its author-activity liveness probe -- the non-interference the
+    mechanical activity comment leans on."""
+
+    id: int
+    author: str
+    body: str
+
+
 class RateLimited(RuntimeError):
     pass
 
@@ -739,3 +753,50 @@ class GitHub:
             "-f",
             f"body={body}",
         )
+
+    def issue_comments(
+        self, owner: str, repo: str, number: int
+    ) -> list[IssueComment]:
+        """Issue comments on an issue or PR (find-or-create reads these to
+        locate THE activity comment). per_page=100 is a documented single-page
+        window like the searches -- the activity comment is authored by the
+        daemon itself, so it lands on the first page unless a hundred other
+        comments were filed after it, and even then find-or-create degrades to
+        creating a second activity comment, never to touching a foreign one.
+        Malformed entries are tolerated (never fatal): one odd comment must not
+        wedge a spawn's telemetry."""
+        data = (
+            self._api(
+                "-X",
+                "GET",
+                f"repos/{owner}/{repo}/issues/{number}/comments",
+                "-f",
+                "per_page=100",
+            )
+            or []
+        )
+        if not isinstance(data, list):
+            return []
+        return [
+            IssueComment(
+                id=int(c.get("id") or 0),
+                author=(c.get("user") or {}).get("login", ""),
+                body=c.get("body") or "",
+            )
+            for c in data
+            if isinstance(c, dict)
+        ]
+
+    def update_comment(
+        self, owner: str, repo: str, comment_id: int, body: str
+    ) -> None:
+        """PATCH an existing issue comment's body -- the append half of the
+        activity comment's find-or-create. Keyed on the comment id, so it only
+        ever rewrites a comment the caller already located and authored."""
+        self._api(
+            "-X",
+            "PATCH",
+            f"repos/{owner}/{repo}/issues/comments/{comment_id}",
+            "-f",
+            f"body={body}",
+        )

{alissa_tools_github_devloop-0.5.0 → alissa_tools_github_devloop-0.5.1}/src/main/alissa/tools/github/devloop/loop.py

@@ -101,6 +101,22 @@ new), oldest-first within each edge, so a scarce budget is spent by priority
 and the deferrals fall on the newest, lowest-priority items. Deferrals are
 counted in the INFO poll summary and in the snapshot exhaust.
 
+Every spawn, retry, and capacity-deferral across all three edges also leaves a
+MECHANICAL ACTIVITY line on its trigger artifact -- on the issue for issue-edge
+spawns, on the PR for fix- and maintain-edge spawns -- via a single find-or-create
+comment keyed on the hidden `<!-- alissa-devloop:activity -->` marker AND own
+authorship (a spoofed marker from another author is never touched). This is the
+devloop mirror of reviewloop's activity comment: from GitHub alone an operator
+can see the daemon spawned, retried a presumed-dead session, or deferred at
+capacity, instead of having to read the daemon's own logs. It is telemetry,
+never a gate: appended AFTER the spawn's side effects, best-effort (a comment
+failure logs and is swallowed), and fully dry-run gated. Capacity-deferral lines
+are deduped to one per episode (the prospective session name is the episode key,
+recorded in the separate `activity_log` ledger) so a re-decided deferral never
+spams the comment; spawn lines self-dedupe on their own spawn ledger row. Being
+plain issue comments, they create no review records, never move the fix edge's
+author-activity liveness signal, and never register as operator escalations.
+
 Finally, every pass runs the SESSION REAPER: finished `develop-*`/`fix-*`
 worker sessions otherwise idle in tmux forever (observed live on the reviewer
 daemon, 2026-07-22 -- and dev workers are worse, because they block through
@@ -315,6 +331,30 @@ ASSIGNMENT_REJECTED_COMMENT = (
     "until then no developer session will be spawned for this issue."
 )
 
+# The hidden marker that identifies THE mechanical activity comment on a
+# trigger artifact (the issue for issue-edge spawns; the PR for fix- and
+# maintain-edge spawns). Find-or-create keys on it AND on own authorship --
+# anyone can paste the marker into their own comment, and a spoofed marker
+# must never be PATCHed -- so every append lands in the same single comment
+# however many spawns, retries, and deferrals the daemon logs. The mirror of
+# reviewloop's `<!-- alissa-reviewloop:activity -->`; the two daemons keep
+# distinct markers so their comments never collide on a shared PR.
+ACTIVITY_MARKER = "<!-- alissa-devloop:activity -->"
+
+ACTIVITY_HEADER = (
+    ACTIVITY_MARKER + "\n"
+    "**Dev-loop activity** — the daemon's mechanical spawn/retry/deferral "
+    "log; one line is appended each time it queues (or defers) a worker "
+    "session for this item. Not an operator page — escalations are separate "
+    "comments."
+)
+
+# The activity-log dedupe kind prefix for a capacity-deferral episode. Unlike
+# a spawn (which records a ledger row and so logs its line exactly once), a
+# deferral is re-decided every poll while the max_sessions cap holds, so its
+# line is deduped per episode -- see deferral_activity_kind.
+ACTIVITY_DEFERRED = "deferred"
+
 
 # Escalation-ledger kinds. Cap-out, assignment-rejection, and a stalled
 # linked-PR deferral have different operator remedies (raise attempt_cap vs
@@ -410,6 +450,22 @@ def stalled_kind(attempt: int) -> str:
     return f"{ESCALATION_STALLED}:a{attempt}"
 
 
+def deferral_activity_kind(session: str) -> str:
+    """The activity-log kind that dedupes ONE capacity-deferral episode's line.
+
+    A max_sessions deferral is re-decided every poll and claims nothing (no
+    ledger row), so an unguarded append would grow the activity comment by one
+    identical "deferred — at capacity" line per poll for as long as the cap
+    holds. One line per episode carries the same information. The prospective
+    session name is the episode identity: while an item defers it records no
+    spawn, so its attempt/round -- and thus its deterministic session name --
+    does not advance across the episode; the moment a slot frees the item
+    spawns under that same name and logs its spawn line. Mirror of reviewloop's
+    deferral_activity_kind. The row lands only AFTER the line posts (see
+    DevWatcher._log_deferral), so a transient failure retries next poll."""
+    return f"{ACTIVITY_DEFERRED}:{session}"
+
+
 # The floor under the linked-PR deferral: an open linked PR defers the stale
 # retry indefinitely -- correct for a live review loop, silent forever for a
 # session that died with its draft PR open (the deferral sits ABOVE the cap
@@ -732,7 +788,9 @@ class DevWatcher:
                     issue.issue_slug,
                 )
 
-        return self._spawn(issue, attempt, task_number, budget)
+        return self._spawn(
+            issue, attempt, task_number, budget, reenqueued=age is not None
+        )
 
     # -- actions -----------------------------------------------------------
 
@@ -742,13 +800,28 @@ class DevWatcher:
         attempt: int,
         task_number: int | None,
         budget: "SessionBudget | None" = None,
+        *,
+        reenqueued: bool = False,
     ) -> Decision:
+        name = session_name(issue, attempt)
         # The max_sessions gate, FIRST -- before the self-assign that marks
         # the issue in-flight, before any hub clone. A full budget defers:
         # the item claims nothing (no assignment, no ledger row, so no
         # staleness clock starts) and stays a clean candidate for the next
-        # poll. reserve() consumes the slot only when it grants.
+        # poll. reserve() consumes the slot only when it grants. The deferral
+        # logs ONE mechanical activity line per episode (best-effort) so the
+        # backpressure is visible on the issue, not just in the daemon's logs.
         if budget is not None and not budget.reserve():
+            self._log_deferral(
+                issue.owner,
+                issue.repo,
+                issue.number,
+                issue.full_name,
+                name,
+                "issue edge",
+                budget,
+                issue.issue_slug,
+            )
             return Decision(Action.DEFERRED, budget.deferral(), attempt)
 
         hub, problem = self._ensure_hub(issue.owner, issue.repo)
@@ -765,7 +838,6 @@ class DevWatcher:
             "none resolved — follow the alissa-pr-review skill's reviewer "
             "resolution"
         )
-        name = session_name(issue, attempt)
         directive = DEV_DIRECTIVE.format(
             issue_url=issue.url,
             number=issue.number,
@@ -808,6 +880,23 @@ class DevWatcher:
                 session=name,
             )
 
+        # AFTER the spawn side effects on purpose: the activity comment is
+        # telemetry and must never gate the spawn it reports on. A retry
+        # (a previously in-flight attempt presumed dead) says so; attempt 1
+        # is a plain spawn.
+        context = (
+            "re-enqueued — previous session presumed dead"
+            if reenqueued
+            else "spawned"
+        )
+        self._append_activity(
+            issue.owner,
+            issue.repo,
+            issue.number,
+            self._activity_line(name, "issue edge", context),
+            issue.issue_slug,
+        )
+
         return Decision(
             Action.SPAWNED,
             f"session {name} → {task_ref or 'no origin task'}",
@@ -1104,7 +1193,9 @@ class DevWatcher:
                 attempts + 1,
             )
 
-        return self._spawn_fix(pr, round_, attempts + 1, newest, budget)
+        return self._spawn_fix(
+            pr, round_, attempts + 1, newest, budget, reenqueued=age is not None
+        )
 
     def _reviewer_reviews(
         self, pr: PullRequest, records: list[Review]
@@ -1257,17 +1348,30 @@ class DevWatcher:
         attempt: int,
         review: Review,
         budget: "SessionBudget | None" = None,
+        *,
+        reenqueued: bool = False,
     ) -> Decision:
         skipped = self._foreign_head_skip(pr, attempt)
         if skipped is not None:
             return skipped
 
+        name = fix_session_name(pr, round_, attempt)
         # The max_sessions gate, after the foreign-head skip (that PR is not
         # this daemon's work, so it must not consume or defer a slot) and
         # before the ledger row. A full budget defers with nothing recorded --
         # the fix ledger stays untouched, so the round is re-evaluated cleanly
-        # next poll.
+        # next poll. The deferral logs ONE activity line per episode on the PR.
         if budget is not None and not budget.reserve():
+            self._log_deferral(
+                pr.owner,
+                pr.repo,
+                pr.number,
+                pr.full_name,
+                name,
+                "fix edge",
+                budget,
+                pr.pr_slug,
+            )
             return Decision(
                 Action.DEFERRED, budget.deferral(), attempt, round=round_
             )
@@ -1276,7 +1380,6 @@ class DevWatcher:
         if problem is not None:
             return Decision(Action.SKIPPED, problem, attempt)
 
-        name = fix_session_name(pr, round_, attempt)
         directive = FIX_DIRECTIVE.format(
             pr_url=pr.url,
             number=pr.number,
@@ -1311,6 +1414,21 @@ class DevWatcher:
                 session=name,
             )
 
+        # AFTER the spawn side effects: telemetry, never a gate. The session
+        # name carries the round and attempt; the context marks a retry.
+        context = (
+            "re-enqueued — previous session presumed dead"
+            if reenqueued
+            else "spawned"
+        )
+        self._append_activity(
+            pr.owner,
+            pr.repo,
+            pr.number,
+            self._activity_line(name, "fix edge", context),
+            pr.pr_slug,
+        )
+
         return Decision(
             Action.SPAWNED,
             f"fix session {name} → round {round_} ({review.author}: "
@@ -1434,7 +1552,10 @@ class DevWatcher:
         # a fresh request reusing attempt 1 could collide with a prior
         # epoch's still-idling session.
         return self._spawn_maintain(
-            pr, self.state.maintain_max_attempt(pr.full_name, number) + 1, budget
+            pr,
+            self.state.maintain_max_attempt(pr.full_name, number) + 1,
+            budget,
+            reenqueued=age is not None,
         )
 
     def _spawn_maintain(
@@ -1442,16 +1563,30 @@ class DevWatcher:
         pr: PullRequest,
         attempt: int,
         budget: "SessionBudget | None" = None,
+        *,
+        reenqueued: bool = False,
     ) -> Decision:
         skipped = self._foreign_head_skip(pr, attempt)
         if skipped is not None:
             return skipped
 
+        name = maintain_session_name(pr, attempt)
         # The max_sessions gate, after the foreign-head skip and before the
         # ledger row (as in _spawn_fix). A full budget defers with nothing
         # recorded; the label stays as the operator's standing ask, so the
-        # request is picked up again next poll once a slot frees.
+        # request is picked up again next poll once a slot frees. The deferral
+        # logs ONE activity line per episode on the PR.
         if budget is not None and not budget.reserve():
+            self._log_deferral(
+                pr.owner,
+                pr.repo,
+                pr.number,
+                pr.full_name,
+                name,
+                "maintain edge",
+                budget,
+                pr.pr_slug,
+            )
             return Decision(Action.DEFERRED, budget.deferral(), attempt)
 
         hub, problem = self._ensure_hub(pr.owner, pr.repo)
@@ -1465,7 +1600,6 @@ class DevWatcher:
             "the PR's existing reviewers (none resolved in config — "
             "re-request whoever reviewed it)"
         )
-        name = maintain_session_name(pr, attempt)
         directive = MAINTAIN_DIRECTIVE.format(
             pr_url=pr.url,
             number=pr.number,
@@ -1497,6 +1631,21 @@ class DevWatcher:
                 session=name,
             )
 
+        # AFTER the spawn side effects: telemetry, never a gate. The session
+        # name carries the attempt; the context marks a retry.
+        context = (
+            "re-enqueued — previous session presumed dead"
+            if reenqueued
+            else "spawned"
+        )
+        self._append_activity(
+            pr.owner,
+            pr.repo,
+            pr.number,
+            self._activity_line(name, "maintain edge", context),
+            pr.pr_slug,
+        )
+
         return Decision(
             Action.SPAWNED,
             f"maintenance session {name} (label {self.config.maintain_label!r} "
@@ -1540,6 +1689,83 @@ class DevWatcher:
             )
         self.state.record_escalation(pr.full_name, pr.number, kind)
 
+    # -- the mechanical activity comment -----------------------------------
+
+    def _activity_line(self, session: str, edge: str, context: str) -> str:
+        """One activity-log line: a UTC timestamp, the session name, the edge,
+        and the event's context. gmtime (UTC) so lines read unambiguously
+        whatever timezone the daemon host runs in; the deterministic session
+        name already carries the issue/PR, attempt, and (fix edge) round."""
+        ts = time.strftime("%Y-%m-%d %H:%M:%S UTC", time.gmtime())
+        return f"- {ts} — `{session}` — {edge} — {context}"
+
+    def _append_activity(
+        self, owner: str, repo: str, number: int, line: str, slug: str
+    ) -> bool:
+        """Append one line to THE activity comment on this issue/PR; True if it
+        landed. Find-or-create: the artifact's issue comments are filtered to
+        OWN authorship AND the hidden marker, and the line is PATCH-appended to
+        the first match; with no match, one marker-carrying comment is created.
+        A marker pasted by anyone else fails the author filter and is never
+        touched.
+
+        Best-effort by contract: this is telemetry ABOUT a spawn/deferral the
+        daemon has already decided, so no failure here may surface to the
+        caller or gate the decision. Fully dry-run gated (a dry pass logs the
+        would-be line and posts nothing). The except is deliberately broad --
+        `_api` turns rate-limit errors into RateLimited (not CommandError), and
+        letting that fly out of a spawn path would fail the whole poll over a
+        log line; a client missing issue_comments degrades the same clean
+        way."""
+        if self.config.dry_run:
+            log.info("[dry-run] would append activity line on %s: %s", slug, line)
+            return False
+        try:
+            mine = [
+                c
+                for c in self.github.issue_comments(owner, repo, number)
+                if c.author == self.github.login and ACTIVITY_MARKER in c.body
+            ]
+            if mine:
+                self.github.update_comment(
+                    owner, repo, mine[0].id, mine[0].body + "\n" + line
+                )
+            else:
+                self.github.comment(
+                    owner, repo, number, ACTIVITY_HEADER + "\n" + line
+                )
+        except Exception as exc:
+            log.warning("could not append activity line on %s: %s", slug, exc)
+            return False
+        return True
+
+    def _log_deferral(
+        self,
+        owner: str,
+        repo: str,
+        number: int,
+        slug_key: str,
+        session: str,
+        edge: str,
+        budget: "SessionBudget",
+        display_slug: str,
+    ) -> None:
+        """Append ONE activity line for a capacity-deferral episode, deduped on
+        the prospective session name so the comment gains one line per episode,
+        not one per poll. `slug_key` is the ledger key (`owner/repo`); `number`
+        is the issue OR PR number; `display_slug` is the log slug. Best-effort
+        and dry-run gated via _append_activity, and the dedupe row lands only
+        AFTER the line posts, so a transient failure retries next poll --
+        exactly once per episode."""
+        kind = deferral_activity_kind(session)
+        if self.state.activity_logged(slug_key, number, kind):
+            return
+        line = self._activity_line(
+            session, edge, f"deferred — {budget.deferral()}"
+        )
+        if self._append_activity(owner, repo, number, line, display_slug):
+            self.state.record_activity(slug_key, number, kind)
+
     def _ensure_hub(self, owner: str, repo: str) -> tuple[Path, str | None]:
         """Resolve a spawn's cwd (the hub ROOT), hub-ifying the repo first if
         configured. Shared by all three edges (issue, fix, and maintenance

{alissa_tools_github_devloop-0.5.0 → alissa_tools_github_devloop-0.5.1}/src/main/alissa/tools/github/devloop/state.py

@@ -41,6 +41,15 @@ free-form TEXT: a caller can narrow a kind's dedupe scope by folding more
 key into the string (the stalled ping is keyed per deferral episode,
 "stalled:a<attempt>" -- see loop.stalled_kind).
 
+The `activity_log` table is the mechanical activity comment's dedupe, kept
+SEPARATE from `escalations` on purpose: an activity line is telemetry, never
+an operator page, so it must not register as an escalation (activity_logged()
+and escalated() are independent ledgers). Only capacity-DEFERRAL lines need a
+row -- a deferral is re-decided every poll, so an undeduped append would spam
+one line per poll -- keyed (repo_slug, number, kind) where kind folds the
+prospective session name (loop.deferral_activity_kind). Spawn lines self-
+dedupe on their own spawn ledger row and take no activity_log row.
+
 The `poll_snapshots` table is a different animal from the ledgers above: it
 records what each poll pass OBSERVED, not what the daemon must remember to
 avoid double-work. One row per pass carries the timing, the per-edge
@@ -106,6 +115,14 @@ CREATE TABLE IF NOT EXISTS maintain_spawns (
     PRIMARY KEY (repo_slug, number, attempt)
 );
 
+CREATE TABLE IF NOT EXISTS activity_log (
+    repo_slug TEXT    NOT NULL,
+    number    INTEGER NOT NULL,
+    kind      TEXT    NOT NULL,
+    logged_at INTEGER NOT NULL,
+    PRIMARY KEY (repo_slug, number, kind)
+);
+
 CREATE TABLE IF NOT EXISTS poll_snapshots (
     id                  INTEGER PRIMARY KEY AUTOINCREMENT,
     ts                  INTEGER NOT NULL,
@@ -350,6 +367,43 @@ class State:
         )
         self._db.commit()
 
+    # -- mechanical activity comment dedupe -------------------------------
+    #
+    # A SEPARATE table from `escalations` on purpose: an activity line is
+    # telemetry, not an operator page, so it must never register as an
+    # escalation (`escalated()` must stay blind to it -- the operator-comment
+    # dedupe and the activity dedupe are independent ledgers). Only the
+    # capacity-DEFERRAL line needs a dedupe row: a deferral is re-decided every
+    # poll, so an undeduped append would grow the activity comment by one
+    # identical line per poll for as long as the cap holds. Spawn lines append
+    # unconditionally -- an attempt spawns once (its spawn ledger row prevents a
+    # re-spawn), so it self-dedupes. `number` is the issue OR PR number; `kind`
+    # folds the prospective session name (deferral_activity_kind), which is
+    # stable across the deferral episode (nothing is recorded while deferring,
+    # so the attempt/round -- and thus the session name -- does not advance).
+
+    def activity_logged(self, repo_slug: str, number: int, kind: str) -> bool:
+        """Whether this activity KIND already landed a line -- the
+        once-per-episode gate for capacity-deferral telemetry. Independent of
+        `escalated()`: a deferral line is not an operator escalation."""
+        row = self._db.execute(
+            "SELECT 1 FROM activity_log WHERE repo_slug=? AND number=? AND kind=?",
+            (repo_slug, number, kind),
+        ).fetchone()
+        return row is not None
+
+    def record_activity(self, repo_slug: str, number: int, kind: str) -> None:
+        """Idempotent per kind: OR IGNORE keeps the first line's timestamp.
+        Recorded by the caller only AFTER the append lands, so a transient
+        comment failure retries next poll and the line lands exactly once per
+        episode."""
+        self._db.execute(
+            "INSERT OR IGNORE INTO activity_log "
+            "(repo_slug, number, kind, logged_at) VALUES (?,?,?,?)",
+            (repo_slug, number, kind, int(time.time())),
+        )
+        self._db.commit()
+
     # -- poll snapshots (the UI sidecar's exhaust buffer) ------------------
 
     def record_snapshot(

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

@@ -0,0 +1 @@
+0.5.1

{alissa_tools_github_devloop-0.5.0 → alissa_tools_github_devloop-0.5.1/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.5.0
+Version: 0.5.1
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera

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

@@ -1 +0,0 @@
-0.5.0