alissa-tools-github-devloop 0.8.12__tar.gz → 0.8.13__tar.gz

{alissa_tools_github_devloop-0.8.12/src/main/alissa_tools_github_devloop.egg-info → alissa_tools_github_devloop-0.8.13}/PKG-INFO

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

{alissa_tools_github_devloop-0.8.12 → alissa_tools_github_devloop-0.8.13}/src/main/alissa/tools/github/devloop/config.py

@@ -64,6 +64,17 @@ FOREIGN_IGNORE = "ignore"  # today's behavior: never even considered
 
 _FOREIGN_POLICIES = {FOREIGN_REAP, FOREIGN_WARN, FOREIGN_IGNORE}
 
+# What the workspace janitor does about a dirty HOLDOUT -- a task workspace
+# whose anchor PR is terminal but which carries uncommitted or unpushed work
+# (issue #99). `warn` is the invariant as it has always been read: never
+# delete unpushed work, say so once per episode. `archive` keeps the invariant
+# and adds a way out: the work is committed, pushed to a NEW
+# `refs/heads/holdout/<branch>` ref, verified there, and only then reclaimed.
+HOLDOUT_WARN = "warn"  # track and warn (once per 24 h); never touch the tree
+HOLDOUT_ARCHIVE = "archive"  # commit, push to holdout/<branch>, verify, reclaim
+
+_HOLDOUT_POLICIES = {HOLDOUT_WARN, HOLDOUT_ARCHIVE}
+
 CONFIG_FILENAME = "devloop.config.json"
 
 # Comma-separated reviewer logins; authoritative when set, even if empty.
@@ -130,6 +141,7 @@ CONFIG_KEYS = (
     "janitor_enabled",
     "janitor_grace_minutes",
     "janitor_interval_minutes",
+    "janitor_holdout_policy",
     "cache_cap_mb",
     "cache_paths",
     "disk_warn_percent",
@@ -518,6 +530,21 @@ class Config:
     # so the telemetry line never goes quiet. 0 means every poll.
     janitor_interval_minutes: int = 10
 
+    # What the janitor does about a dirty holdout (issue #99). Default `warn`:
+    # the workspace is tracked in the `janitor_holdouts` ledger table, warned
+    # about on first sighting and at most once per 24 h after that (DEBUG in
+    # between), and never touched -- the "never delete unpushed work"
+    # invariant exactly as before, minus the ~3,000 identical WARNING lines a
+    # day the fleet measured. `archive` is opt-in: a holdout whose anchor is
+    # terminal and whose branch is a task branch has its work committed (when
+    # dirty), pushed to a NEW `refs/heads/holdout/<branch>` ref (never the
+    # task branch, never force), verified there by `ls-remote`, and only then
+    # reclaimed like a clean workspace. Any failure leaves the workspace in
+    # place -- at worst with its work committed locally, never removed -- and
+    # pages `janitor-archive-failed` once per workspace. The commit stages
+    # EVERY untracked, non-ignored file, scratch directories included.
+    janitor_holdout_policy: str = HOLDOUT_WARN
+
     # The cache bound, in MiB: package-manager caches over this are trimmed
     # oldest-entry-first back under it. 0 disables the trim entirely. A cache
     # is a legitimate speed tradeoff -- the default is generous on purpose
@@ -853,6 +880,19 @@ class Config:
                 f"got {janitor_interval}"
             )
 
+        # The holdout policy. An enum validated by NAME like
+        # foreign_session_policy: a typo would otherwise be "not archive",
+        # i.e. silently the default, for an operator who set the key to opt
+        # INTO a git push -- the one outcome they cannot have wanted.
+        holdout_policy = str(
+            raw.get("janitor_holdout_policy", cls.janitor_holdout_policy)
+        ).strip()
+        if holdout_policy not in _HOLDOUT_POLICIES:
+            raise ValueError(
+                f"janitor_holdout_policy must be one of "
+                f"{sorted(_HOLDOUT_POLICIES)}, got {holdout_policy!r}"
+            )
+
         cache_cap = int(raw.get("cache_cap_mb", cls.cache_cap_mb))
         if cache_cap < 0:
             raise ValueError(
@@ -924,6 +964,7 @@ class Config:
             janitor_enabled=bool(raw.get("janitor_enabled", cls.janitor_enabled)),
             janitor_grace_minutes=janitor_grace,
             janitor_interval_minutes=janitor_interval,
+            janitor_holdout_policy=holdout_policy,
             cache_cap_mb=cache_cap,
             cache_paths=_string_list(
                 raw.get("cache_paths", cls.cache_paths), "cache_paths"

{alissa_tools_github_devloop-0.8.12 → alissa_tools_github_devloop-0.8.13}/src/main/alissa/tools/github/devloop/janitor.py

@@ -53,6 +53,18 @@ log = logging.getLogger(__name__)
 # one of ours.
 TASK_WORKSPACE_RE = re.compile(r"TASK-(?P<task>\d+)(?:-(?P<desc>[A-Za-z0-9._-]+))?")
 
+# 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
+# itself -- its PR is closed, and a push there would resurrect a dead lane --
+# and never `--force`, so a ref that already exists at a different sha refuses
+# the push and the workspace stays. An operator recovers the work with
+# `git fetch origin holdout/<branch>`.
+HOLDOUT_REF_PREFIX = "refs/heads/holdout/"
+
+# The remote the archive pushes to. The dev identity already pushes task
+# branches to it; the archive needs no new permission.
+HOLDOUT_REMOTE = "origin"
+
 # Package-manager caches, as they land in this image and every other
 # Debian-ish agent container. Used only when the operator configures no
 # `cache_paths` of their own; entries that do not exist are skipped silently,
@@ -117,6 +129,21 @@ def parse_task_workspace(path: Path, hub: Path) -> "TaskWorkspace | None":
     )
 
 
+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
+
+
+def holdout_ref(branch: str) -> str:
+    """The full ref the archive pushes `branch`'s work to."""
+    return f"{HOLDOUT_REF_PREFIX}{branch}"
+
+
 def scan_hub(hub: Path) -> "list[TaskWorkspace]":
     """Every task workspace directly under `hub`, sorted by name.
 
@@ -375,6 +402,58 @@ def delete_branch(common: Path, branch: str, runner: "Runner" = run) -> None:
     _git(["branch", "-D", branch], common, runner)
 
 
+# -- the archive's git plumbing (issue #99) --------------------------------
+#
+# Three commands, each one step of the `archive` holdout policy, each doing
+# exactly what its name says and nothing else: the ORDER (commit only when
+# dirty, push to the holdout ref, verify by ls-remote, and only then remove)
+# and every refusal live in `loop.DevWatcher._archive_holdout`. All three
+# raise CommandError on failure, which the caller turns into "the workspace
+# stays" -- nothing here decides.
+
+
+def commit_all(path: Path, message: str, runner: "Runner" = run) -> None:
+    """`git add -A && git commit --allow-empty -m <message>` in `path`.
+
+    `-A` stages every uncommitted change `dirty_entries` reported, untracked
+    files included, because that is precisely the work the holdout exists to
+    keep; ignored build output stays ignored. That is BROADER than "the
+    work": a `.harness/` or `.fu…prep/` scratch directory a session left
+    behind is untracked and not ignored, so it goes into the commit and onto
+    the remote ref too. The caller logs the entry count before this runs and
+    the docs say so -- an operator opting into `archive` opts into that. `--allow-empty` so a status that
+    went clean between the check and the commit still yields a commit that
+    carries the message -- the archive's provenance line on the ref."""
+    _git(["add", "-A"], path, runner)
+    _git(["commit", "--allow-empty", "-m", message], path, runner)
+
+
+def push_ref(path: Path, ref: str, runner: "Runner" = run) -> None:
+    """`git push origin HEAD:<ref>` from `path`. Deliberately WITHOUT
+    `--force`, ever: a ref that already exists at another sha rejects the
+    push, and the caller keeps the workspace. `ref` is a full ref name
+    (`refs/heads/holdout/<branch>`), so git cannot resolve it to anything but
+    a branch under `holdout/`."""
+    _git(["push", HOLDOUT_REMOTE, f"HEAD:{ref}"], path, runner)
+
+
+def remote_ref_sha(path: Path, ref: str, runner: "Runner" = run) -> "str | None":
+    """The sha `ref` points at on the remote, per `git ls-remote origin
+    <ref>`, or None when the remote has no such ref.
+
+    THE verification step: the archive deletes only when this equals the
+    local HEAD. A remote that cannot be asked raises (the caller keeps the
+    workspace and says why); a remote that answers "no such ref" is the same
+    verdict spelled quietly, hence None rather than a raise -- the caller
+    compares it to a real sha and refuses."""
+    out = _git(["ls-remote", HOLDOUT_REMOTE, ref], path, runner)
+    for line in out.splitlines():
+        sha, _, name = line.strip().partition("\t")
+        if name == ref and sha:
+            return sha
+    return None
+
+
 def remove_tree(path: Path) -> None:
     """Delete a standalone checkout's directory outright.
 

{alissa_tools_github_devloop-0.8.12 → alissa_tools_github_devloop-0.8.13}/src/main/alissa/tools/github/devloop/loop.py

@@ -357,11 +357,26 @@ deletes) AND a workspace holding nothing that is not already on GitHub: a
 clean `git status --porcelain` and a local tip that matches a head GitHub saw
 on the branch. That last pair is the one that matters -- unpushed work is
 exactly what the approve-race taught this fleet can exist after a merge -- and
-failing it is not a quiet skip: the workspace is logged as a HOLDOUT at
-warning level on EVERY pass, because nothing in this daemon will ever clear
-that state on its own. Removal is `git worktree remove` (no `--force`, so
-git's own refusal to delete untracked work is a second, independent guard) +
-`prune` + `branch -D`, or a plain directory removal for a standalone checkout.
+failing it is not a quiet skip: the workspace is a HOLDOUT, tracked in the
+`janitor_holdouts` ledger table and logged at WARNING with its anchor evidence
+on first sighting and at most once per 24 h after that (DEBUG in between --
+the fleet measured ~3,000 identical WARNING lines a day from 21 holdouts
+warned on every 10-minute sweep, issue #99), listed by name on every pass's
+summary line and in the console, and cleared with one INFO line the sweep
+that no longer finds the directory. Under the default `janitor_holdout_policy`
+of `warn` that is all: nothing in this daemon touches the tree. Under the
+opt-in `archive` policy a holdout whose anchor is terminal and whose branch is
+a task branch is given a way out that keeps the invariant -- its work is
+committed (when dirty), pushed to a NEW `refs/heads/holdout/<branch>` ref
+(never the task branch, never force), VERIFIED there by `ls-remote` against
+the local HEAD, and only then reclaimed like a clean workspace; any failure
+leaves the workspace in place -- at worst with its work committed locally,
+never removed -- and pages `janitor-archive-failed` once. What the commit
+captures is EVERY untracked, non-ignored file (scratch directories included):
+the ref is a durable copy of the whole tree, which the docs say plainly.
+Removal is `git worktree remove` (no `--force`, so git's own refusal to delete
+untracked work is a second, independent guard) + `prune` + `branch -D`, or a
+plain directory removal for a standalone checkout.
 Only direct `TASK-<n>-<DESC>` children of the hubs of ALLOWLISTED repos are
 ever candidates; a removal that fails logs and skips, and the walk continues.
 
@@ -395,6 +410,7 @@ from .bows import BowRepoSource
 from .config import (
     FOREIGN_IGNORE,
     FOREIGN_REAP,
+    HOLDOUT_ARCHIVE,
     HUB_ADD,
     ON_MISSING_SKIP,
     ON_MISSING_WARN,
@@ -1182,6 +1198,25 @@ ESCALATION_ORPHAN_REJECTED = "orphan-rejected"
 # number, like every other PR-side kind here.
 ESCALATION_STACKED_BASE = "stacked-base"
 
+# 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
+# (`archive_failed_kind`) so a fleet with 21 holdouts pages once for each,
+# and rows carry the anchor PR's coordinates so the console can link them.
+ESCALATION_ARCHIVE_FAILED = "janitor-archive-failed"
+
+# How often a dirty holdout is re-warned about after its first sighting. The
+# sweeps in between log the same evidence at DEBUG. A day, not the janitor
+# interval: the state is permanent by construction, so the line's job is to
+# stay findable in a day's log, not to be the log.
+HOLDOUT_WARN_INTERVAL = 24 * 3600
+
+
+def archive_failed_kind(slug: str) -> str:
+    """The ledger kind that dedupes ONE workspace's archive-failure page."""
+    return f"{ESCALATION_ARCHIVE_FAILED}:{slug}"
+
+
 # CR6 verdict words, spelled exactly as reviewloop's alissa.py spells them --
 # the envelope tie-breaker (see DevWatcher.envelope_verdict) must return
 # these strings, so the two daemons read one vocabulary.
@@ -1764,6 +1799,28 @@ class Reclaim:
     freed: int = 0
     dirty: "tuple[str, ...]" = ()
     trimmed: int = 0
+    # How many of `removed` were dirty holdouts the `archive` policy pushed to
+    # a `holdout/<branch>` ref first (issue #99). A subset, not a sibling:
+    # an archived workspace IS reclaimed and its bytes ARE in `freed`; the
+    # count is kept so the summary line can say which reclaims took a push.
+    archived: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class Holdout:
+    """WHY one workspace with a terminal anchor must be kept (issue #99).
+
+    `reason` is the sentence the WARNING carries. `uncommitted` says `git
+    status` showed work (the archive commits before it pushes); `head` is the
+    local tip when it could be read. `archivable` is the archive policy's
+    admission test, and it is False for exactly the verdicts that are not
+    evidence -- a status or a HEAD that could not be READ. "I could not
+    check" licenses keeping the directory; it licenses nothing else."""
+
+    reason: str
+    uncommitted: bool = False
+    head: "str | None" = None
+    archivable: bool = False
 
 
 @dataclass(frozen=True, slots=True)
@@ -6515,14 +6572,16 @@ class DevWatcher:
         then judged by `_reclaim_workspace`, whose failures are caught per
         workspace: one unremovable directory must not stop the walk that would
         have freed the next twelve."""
-        scanned = removed = freed = 0
+        scanned = removed = freed = archived = 0
         dirty: list[str] = []
         for owner, repo in self._watched_repos():
             hub = self.config.hub_for(owner, repo)
             if not hub.is_dir():
                 continue
+            found: set[str] = set()
             for workspace in janitor.scan_hub(hub):
                 scanned += 1
+                found.add(workspace.slug)
                 try:
                     outcome = self._reclaim_workspace(
                         workspace, owner, repo, roster
@@ -6537,14 +6596,31 @@ class DevWatcher:
                     continue
                 if outcome is None:
                     continue
-                gone, size = outcome
+                gone, size, pushed = outcome
                 if gone:
                     removed += 1
                     freed += size
+                    archived += int(pushed)
+                    # Reclaimed (archived included): its directory is gone,
+                    # so its ledger row -- if it had one -- clears on THIS
+                    # sweep rather than the next.
+                    found.discard(workspace.slug)
                 else:
                     dirty.append(workspace.slug)
+            # The holdout ledger is pruned per hub WALKED, against every
+            # directory the walk found (held out or not): a row goes only
+            # when its directory is provably gone -- pushed and reclaimed,
+            # archived, or removed by hand -- never because this pass
+            # skipped a hub. One INFO line per cleared episode, the first
+            # and last thing the log says about it after the warning. Not
+            # under dry-run: a dry pass writes no gate (see `_note_holdout`).
+            if self.config.dry_run:
+                continue
+            for slug in self.state.prune_janitor_holdouts(str(hub), found):
+                log.info("janitor: holdout cleared %s", slug)
         return Reclaim(
-            scanned=scanned, removed=removed, freed=freed, dirty=tuple(dirty)
+            scanned=scanned, removed=removed, freed=freed, dirty=tuple(dirty),
+            archived=archived,
         )
 
     def _reclaim_workspace(
@@ -6553,9 +6629,11 @@ class DevWatcher:
         owner: str,
         repo: str,
         roster: "SessionLiveness | None",
-    ) -> "tuple[bool, int] | None":
-        """Judge ONE task workspace: `(removed, bytes)` when it acted, or None
-        when the workspace was spared.
+    ) -> "tuple[bool, int, bool] | None":
+        """Judge ONE task workspace: `(removed, bytes, archived)` when it
+        acted -- `removed` False for a holdout it kept, `archived` True for a
+        holdout the `archive` policy pushed before reclaiming -- or None when
+        the workspace was spared.
 
         The gates, cheapest and most conservative first -- every one of them
         SPARES, and only a workspace that clears all of them is touched:
@@ -6584,11 +6662,18 @@ class DevWatcher:
           what stands between this sweep and someone's unpushed work, and they
           WARN rather than skipping quietly (see below).
 
-        The dirty gates warn on EVERY pass, by design and not by oversight. A
-        workspace with a terminal anchor and unpushed commits is a permanent
-        holdout -- nothing in this daemon will ever clear it, and its disk is
-        never coming back -- so it is exactly the state that must not decay
-        into a debug line nobody greps for.
+        The dirty gates do not skip quietly, by design: a workspace with a
+        terminal anchor and unpushed work is a permanent HOLDOUT -- nothing in
+        the `warn` policy will ever clear it, and its disk is never coming
+        back -- so it is exactly the state that must not decay into a debug
+        line nobody greps for. But it must not become the log either (issue
+        #99: 21 holdouts x 144 sweeps a day), so the WARNING is once per
+        episode and once per 24 h after that, with the sweeps in between at
+        DEBUG (`_note_holdout`); the per-pass summary line names every holdout
+        every pass regardless. Under the `archive` policy a holdout the
+        evidence supports is then handed to `_archive_holdout`, which either
+        reclaims it behind a verified remote copy or leaves it exactly as it
+        was.
         """
         path = workspace.path
         branch = janitor.current_branch(path)
@@ -6647,13 +6732,15 @@ class DevWatcher:
 
         holdout = self._dirty_holdout(workspace, newest, pulls)
         if holdout is not None:
-            log.warning(
-                "janitor: HOLDOUT %s — anchor #%d is terminal (%s) but the "
-                "workspace %s; never deleting unpushed work. This will not "
-                "clear on its own: push it, or remove the directory by hand",
-                workspace.slug, newest.number, reason, holdout,
-            )
-            return False, 0
+            self._note_holdout(workspace, newest, reason, holdout)
+            if (
+                self.config.janitor_holdout_policy == HOLDOUT_ARCHIVE
+                and holdout.archivable
+            ):
+                freed = self._archive_holdout(workspace, newest, reason, holdout)
+                if freed is not None:
+                    return True, freed, True
+            return False, 0, False
 
         size = janitor.dir_size(path)
         if self.config.dry_run:
@@ -6661,14 +6748,14 @@ class DevWatcher:
                 "[dry-run] would reclaim %s (anchor #%d: %s; %s)",
                 workspace.slug, newest.number, reason, janitor.human(size),
             )
-            return True, size
+            return True, size, False
 
         self._remove_workspace(workspace)
         log.info(
             "janitor: reclaimed %s (anchor #%d: %s; %s freed)",
             workspace.slug, newest.number, reason, janitor.human(size),
         )
-        return True, size
+        return True, size, False
 
     def _terminal_for(
         self, pull: PullRequest, path: Path
@@ -6697,7 +6784,7 @@ class DevWatcher:
         workspace: "janitor.TaskWorkspace",
         newest: PullRequest,
         pulls: "tuple[PullRequest, ...]",
-    ) -> "str | None":
+    ) -> "Holdout | None":
         """Why this workspace must be kept despite a terminal anchor, or None
         when it holds nothing that is not already on GitHub.
 
@@ -6713,29 +6800,248 @@ class DevWatcher:
         it merged forever.
 
         A status or a HEAD that cannot be READ is a holdout too: "I could not
-        check" and "there is nothing to lose" are not the same sentence."""
+        check" and "there is nothing to lose" are not the same sentence. Those
+        two verdicts are the ones the `archive` policy refuses
+        (`Holdout.archivable` False): they are the absence of evidence, and
+        the archive acts on evidence only."""
         try:
             dirty = janitor.dirty_entries(workspace.path)
         except CommandError as exc:
-            return f"status could not be read ({exc})"
+            return Holdout(f"status could not be read ({exc})")
+        head = janitor.head_sha(workspace.path)
         if dirty:
-            return (
+            return Holdout(
                 f"has {len(dirty)} uncommitted change(s), e.g. "
-                f"{dirty[0].strip()!r}"
+                f"{dirty[0].strip()!r}",
+                uncommitted=True, head=head, archivable=head is not None,
             )
 
-        head = janitor.head_sha(workspace.path)
         if head is None:
-            return "HEAD could not be read"
+            return Holdout("HEAD could not be read")
         published = {pull.head_sha for pull in pulls if pull.head_sha}
         if head not in published:
-            return (
+            return Holdout(
                 f"is at {head[:8]}, which is not a head GitHub saw on this "
                 f"branch (newest PR #{newest.number} merged "
-                f"{(newest.head_sha or '?')[:8]}) — it carries unpushed commits"
+                f"{(newest.head_sha or '?')[:8]}) — it carries unpushed commits",
+                head=head, archivable=True,
             )
         return None
 
+    def _note_holdout(
+        self,
+        workspace: "janitor.TaskWorkspace",
+        newest: PullRequest,
+        reason: str,
+        holdout: Holdout,
+    ) -> None:
+        """Record one sighting of a holdout and log it at the level its
+        episode has earned (issue #99).
+
+        WARNING with the full anchor evidence on the FIRST sighting -- the
+        ledger has no row -- and again once `HOLDOUT_WARN_INTERVAL` has
+        passed since the last warning; DEBUG, same evidence, on every sweep
+        in between. The per-pass summary line (`_log_disk`) still names the
+        holdout on every pass, so the console and the sentinel see the count
+        whatever this logs. The row is upserted either way so its `reason`
+        tracks the tree (a holdout that was dirty and is now merely unpushed
+        reads that way in the console), and `last_warned` moves only on a
+        warning -- that is what "at most once per 24 h" means.
+
+        Wall-clock, like every ledger timestamp: a restart must not re-page
+        21 holdouts, and a monotonic clock would.
+
+        Under dry-run the row is READ but never written (review round 1):
+        `janitor_holdouts` is a dedupe gate, not only an observation table,
+        and this file's convention is that a dry pass consumes no once-only
+        gate -- otherwise `--dry-run --once` against the production ledger
+        would silence the live WARNING for a day."""
+        hub = str(workspace.hub)
+        row = self.state.janitor_holdout(hub, workspace.slug)
+        now = time.time()
+        if row is None:
+            level, since = logging.WARNING, ""
+        elif now - int(row["last_warned"]) >= HOLDOUT_WARN_INTERVAL:
+            level = logging.WARNING
+            since = (
+                f" (held out for {int((now - int(row['first_seen'])) // 3600)} h; "
+                f"this is the daily reminder)"
+            )
+        else:
+            level, since = logging.DEBUG, ""
+        log.log(
+            level,
+            "janitor: HOLDOUT %s — anchor #%d is terminal (%s) but the "
+            "workspace %s; never deleting unpushed work. This will not clear "
+            "on its own: push it, remove the directory by hand, or set "
+            "janitor_holdout_policy: archive%s",
+            workspace.slug, newest.number, reason, holdout.reason, since,
+        )
+        if self.config.dry_run:
+            return
+        self.state.record_janitor_holdout(
+            hub, workspace.slug, holdout.reason, warned=level == logging.WARNING
+        )
+
+    def _archive_holdout(
+        self,
+        workspace: "janitor.TaskWorkspace",
+        newest: PullRequest,
+        reason: str,
+        holdout: Holdout,
+    ) -> "int | None":
+        """The `archive` policy for ONE holdout: the bytes freed when the
+        workspace was archived and reclaimed, or None when it stays.
+
+        Four steps, every one logged, every failure leaving the workspace in
+        place -- at worst with its work committed locally, since step 1
+        precedes the push -- and never removed:
+
+        1. `git add -A && git commit --allow-empty` in the worktree -- only
+           when the tree is dirty; an unpushed-commits-only holdout has
+           nothing to commit and goes straight to 2. `-A` stages EVERY
+           untracked, non-ignored file -- a `.harness/` or `.fu…prep/`
+           scratch directory included -- and the log says how many entries
+           are about to become a durable remote copy;
+        2. `git push origin HEAD:refs/heads/holdout/<branch>` -- a NEW ref,
+           never the task branch (its PR is closed; a push there would
+           resurrect a dead lane), never `--force`;
+        3. `git ls-remote origin refs/heads/holdout/<branch>` must equal the
+           local HEAD. THE gate: this is the only condition under which
+           deletion is allowed, and it is checked against the remote's
+           answer, not the push's exit code;
+        4. `_remove_workspace`, exactly as the clean-reclaim path does.
+
+        Two refusals precede them. The branch must parse as a task branch
+        (`janitor.is_task_branch`): the scan already admitted the directory
+        by that grammar, but this is the step that names a ref on the remote
+        after it, so it is re-asserted here, at the push. And the holdout
+        must be `archivable` -- a verdict made of evidence, not of a status
+        or a HEAD that could not be read; that refusal is the caller's.
+
+        A push or verification failure pages `janitor-archive-failed` once
+        per workspace (`_escalate_archive_failed`) with git's stderr, and the
+        holdout keeps warning on its 24 h cadence. Dry-run narrates every
+        step and performs none. Failures of step 4 raise to the walk, which
+        logs and continues -- the remote copy exists by then, so the
+        directory is only disk."""
+        slug = workspace.slug
+        branch = workspace.branch
+        if not janitor.is_task_branch(branch):
+            log.warning(
+                "janitor: archive refused for %s — %r is not a task branch, "
+                "and only devloop's own TASK-<n>-… branches get a holdout/ "
+                "ref; the workspace stays", slug, branch,
+            )
+            return None
+        ref = janitor.holdout_ref(branch)
+        path = workspace.path
+        commit = holdout.uncommitted
+        # The message claims a commit "for archiving", not an archive: the
+        # archive is only real once step 3 verified it, and this commit is
+        # what an operator finds on the task branch when a push failed.
+        message = (
+            f"holdout: unpushed work committed by devloop janitor for "
+            f"archiving (anchor #{newest.number} {reason})"
+        )
+        if self.config.dry_run:
+            log.info(
+                "[dry-run] would archive %s: %spush HEAD to %s, verify the "
+                "remote sha equals HEAD by ls-remote, then reclaim the "
+                "workspace (anchor #%d: %s)",
+                slug,
+                f"commit {holdout.reason} as {message!r}, " if commit else "",
+                ref, newest.number, reason,
+            )
+            return None
+        committed = False
+        try:
+            if commit:
+                entries = janitor.dirty_entries(path)
+                log.info(
+                    "janitor: archive %s — committing %d untracked/modified "
+                    "entr(ies) (every non-ignored file, scratch directories "
+                    "included), e.g. %s",
+                    slug, len(entries),
+                    ", ".join(repr(e.strip()) for e in entries[:3]) or "nothing",
+                )
+                janitor.commit_all(path, message)
+                committed = True
+                log.info(
+                    "janitor: archive %s — committed the uncommitted work "
+                    "(%s)", slug, holdout.reason,
+                )
+            head = janitor.head_sha(path)
+            if head is None:
+                raise CommandError(
+                    ["git", "rev-parse", "HEAD"], 1,
+                    "HEAD could not be read before the push",
+                )
+            janitor.push_ref(path, ref)
+            log.info("janitor: archive %s — pushed %s to %s", slug, head[:8], ref)
+            remote = janitor.remote_ref_sha(path, ref)
+            if remote != head:
+                raise CommandError(
+                    ["git", "ls-remote", janitor.HOLDOUT_REMOTE, ref], 1,
+                    f"{ref} on {janitor.HOLDOUT_REMOTE} is at "
+                    f"{remote or 'no such ref'}, local HEAD is {head} — "
+                    f"the remote copy is not verified",
+                )
+        except CommandError as exc:
+            self._escalate_archive_failed(workspace, newest, exc, committed)
+            return None
+        log.info(
+            "janitor: archive %s — verified %s on %s equals HEAD %s; "
+            "reclaiming", slug, ref, janitor.HOLDOUT_REMOTE, head[:8],
+        )
+        size = janitor.dir_size(path)
+        self._remove_workspace(workspace)
+        log.info(
+            "janitor: archived %s to %s and reclaimed it (anchor #%d: %s; %s "
+            "freed). Recover the work with `git fetch %s %s`",
+            slug, ref, newest.number, reason, janitor.human(size),
+            janitor.HOLDOUT_REMOTE, ref[len("refs/heads/"):],
+        )
+        return size
+
+    def _escalate_archive_failed(
+        self,
+        workspace: "janitor.TaskWorkspace",
+        newest: PullRequest,
+        exc: CommandError,
+        committed: bool,
+    ) -> None:
+        """Page the operator ONCE per workspace that the archive could not
+        push or verify, with git's stderr. The page is the ERROR line plus a
+        ledger row the console inbox renders (linked to the anchor PR --
+        there is no comment: the PR is closed, and a closed PR is not where
+        anyone is reading). Later failures of the same workspace log at DEBUG;
+        the holdout itself keeps warning on its own 24 h cadence.
+
+        `committed` says whether step 1 ran before the failure: the workspace
+        is then in place with its work as a LOCAL commit, not "untouched",
+        and the line says so (review round 1) -- it is the one place an
+        operator reads when something went wrong."""
+        kind = archive_failed_kind(workspace.slug)
+        stderr = (exc.stderr or "").strip()
+        state = (
+            "in place with its work committed locally (not pushed)" if committed
+            else "in place, unchanged"
+        )
+        if self.state.escalated(newest.full_name, newest.number, kind):
+            log.debug(
+                "janitor: archive of %s failed again (%s); already escalated",
+                workspace.slug, exc,
+            )
+            return
+        log.error(
+            "janitor: ARCHIVE FAILED for %s — %s; the workspace stays a "
+            "holdout, %s (git said: %s). Escalating to operator (once per "
+            "workspace)",
+            workspace.slug, exc, state, stderr or "nothing",
+        )
+        self.state.record_escalation(newest.full_name, newest.number, kind)
+
     def _remove_workspace(self, workspace: "janitor.TaskWorkspace") -> None:
         """Remove one proven-reclaimable workspace and its local branch.
 
@@ -6884,7 +7190,7 @@ class DevWatcher:
         log.log(
             logging.WARNING if over else logging.INFO,
             "disk: %s of %s used (%s%%%s) on %s%s; hubs: %s%s; reclaimed %d "
-            "workspace(s) freeing %s this pass (%d scanned, %d dirty "
+            "workspace(s)%s freeing %s this pass (%d scanned, %d dirty "
             "holdout(s)%s)",
             janitor.human(usage["used_bytes"]),
             janitor.human(usage["total_bytes"]),
@@ -6895,6 +7201,7 @@ class DevWatcher:
             breakdown,
             f"; top: {offenders}" if over else "",
             reclaim.removed,
+            f" ({reclaim.archived} archived)" if reclaim.archived else "",
             janitor.human(reclaim.freed),
             reclaim.scanned,
             len(reclaim.dirty),

{alissa_tools_github_devloop-0.8.12 → alissa_tools_github_devloop-0.8.13}/src/main/alissa/tools/github/devloop/state.py

@@ -59,6 +59,18 @@ 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 `janitor_holdouts` table is the workspace janitor's memory of its dirty
+HOLDOUTS (issue #99): task workspaces whose anchor PR is terminal but which
+carry uncommitted or unpushed work, so the janitor will never delete them.
+One row per (hub, slug), upserted on every sweep that finds the workspace
+still held out: `first_seen` dates the episode, `last_warned` is the clock
+the once-per-24h WARNING cadence runs on (the sweeps in between log the same
+evidence at DEBUG), and `reason` is the sentence the warning carries. Rows are
+NOT permanent -- the janitor prunes, per hub it walked, every row whose
+directory it no longer found (pushed and reclaimed, archived, or removed by
+hand), logging one `holdout cleared` line; a directory that comes back starts
+a fresh episode. `read_janitor_holdouts` is the console's reader.
+
 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
@@ -143,6 +155,15 @@ CREATE TABLE IF NOT EXISTS activity_log (
     PRIMARY KEY (repo_slug, number, kind)
 );
 
+CREATE TABLE IF NOT EXISTS janitor_holdouts (
+    hub         TEXT    NOT NULL,
+    slug        TEXT    NOT NULL,
+    first_seen  INTEGER NOT NULL,
+    last_warned INTEGER NOT NULL,
+    reason      TEXT    NOT NULL,
+    PRIMARY KEY (hub, slug)
+);
+
 CREATE TABLE IF NOT EXISTS poll_snapshots (
     id                  INTEGER PRIMARY KEY AUTOINCREMENT,
     ts                  INTEGER NOT NULL,
@@ -899,6 +920,101 @@ class State:
                 f"record_activity({repo_slug}#{number}, {kind})", write),
         )
 
+    # -- janitor holdouts (issue #99) ---------------------------------------
+    #
+    # The workspace janitor's once-per-episode memory. Every method here is
+    # keyed (hub, slug): `hub` is the hub directory the workspace lives under
+    # and `slug` is `janitor.TaskWorkspace.slug` (`<hub name>/<branch>`), the
+    # name the log lines and the console use. Timestamps are wall-clock
+    # seconds like every other row in this ledger -- `last_warned` outlives a
+    # daemon restart on purpose, so a restart does not re-page every holdout.
+
+    def janitor_holdout(self, hub: str, slug: str) -> "dict | None":
+        """The row for one holdout, or None when the janitor has not recorded
+        it (a first sighting, or an episode that was cleared)."""
+        row = self._db.execute(
+            "SELECT hub, slug, first_seen, last_warned, reason "
+            "FROM janitor_holdouts WHERE hub=? AND slug=?",
+            (hub, slug),
+        ).fetchone()
+        return None if row is None else dict(row)
+
+    def record_janitor_holdout(
+        self, hub: str, slug: str, reason: str, *, warned: bool
+    ) -> None:
+        """Upsert one holdout sighting. A NEW row carries `first_seen` and
+        `last_warned` both stamped now (the first sighting is always warned);
+        an existing row keeps `first_seen`, takes the fresh `reason`, and
+        moves `last_warned` only when the caller says this sweep WARNED --
+        that is what makes the cadence "at most once per 24 h" rather than
+        "24 h after the last sweep".
+
+        BEST-EFFORT (see _best_effort): this is cadence bookkeeping. A row
+        that does not land costs the pre-#99 behaviour for that holdout --
+        the WARNING repeats next sweep -- which on a wedged store is the
+        right failure: the store's own warnings are already saying why."""
+        ts = int(time.time())
+
+        def write() -> None:
+            self._db.execute(
+                "INSERT INTO janitor_holdouts "
+                "(hub, slug, first_seen, last_warned, reason) "
+                "VALUES (?,?,?,?,?) "
+                "ON CONFLICT(hub, slug) DO UPDATE SET "
+                "reason=excluded.reason, "
+                "last_warned=CASE WHEN ? THEN excluded.last_warned "
+                "ELSE janitor_holdouts.last_warned END",
+                (hub, slug, ts, ts, reason, 1 if warned else 0),
+            )
+            self._db.commit()
+
+        self._best_effort(f"record_janitor_holdout({slug})", write)
+
+    def prune_janitor_holdouts(self, hub: str, keep: "set[str]") -> "list[str]":
+        """Drop the rows of ONE hub whose slug is not in `keep`, returning
+        the slugs dropped (empty when nothing was dropped, or when the store
+        refused the write). The janitor calls this once per hub it actually
+        WALKED, passing every workspace it found there -- so a row goes only
+        when its directory is provably gone, never because a sweep skipped
+        that hub or could not list it.
+
+        BEST-EFFORT like `prune_escalations`, and with its SELECT-inside-the-
+        closure shape for the same reason: the ordinary case deletes nothing,
+        and a closure that only read must not be taken as proof that the
+        store accepts writes."""
+        dropped: "list[str]" = []
+
+        def write() -> "bool | None":
+            del dropped[:]
+            rows = self._db.execute(
+                "SELECT slug FROM janitor_holdouts WHERE hub=?", (hub,)
+            ).fetchall()
+            dropped.extend(
+                row["slug"] for row in rows if row["slug"] not in keep
+            )
+            if not dropped:
+                return False
+            for slug in dropped:
+                self._db.execute(
+                    "DELETE FROM janitor_holdouts WHERE hub=? AND slug=?",
+                    (hub, slug),
+                )
+            self._db.commit()
+            return True
+
+        wrote = self._best_effort(f"prune_janitor_holdouts({hub})", write)
+        return list(dropped) if wrote else []
+
+    def read_janitor_holdouts(self) -> "list[dict]":
+        """Every holdout row, oldest episode first -- the console's
+        "Holdouts (N)" list. No GitHub call: the janitor already wrote down
+        everything the panel shows."""
+        rows = self._db.execute(
+            "SELECT hub, slug, first_seen, last_warned, reason "
+            "FROM janitor_holdouts ORDER BY first_seen ASC, slug ASC"
+        ).fetchall()
+        return [dict(row) for row in rows]
+
     # -- poll snapshots (the UI sidecar's exhaust buffer) ------------------
 
     def record_snapshot(

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

@@ -0,0 +1 @@
+0.8.13

{alissa_tools_github_devloop-0.8.12 → alissa_tools_github_devloop-0.8.13}/src/main/alissa/tools/github/devloop/webui/page.py

@@ -317,6 +317,10 @@ _DASHBOARD = """<!doctype html>
   <section class="panel"><p class="overline">Worker Tasks</p><div id="tasks"></div></section>
 </div>
 
+<section class="panel"><p class="overline">Holdouts (<span id="holdouts-count">0</span>)
+  &middot; <span class="muted">dirty task workspaces the janitor keeps</span></p>
+  <div id="holdouts"></div></section>
+
 <section class="panel"><p class="overline">Sessions</p><div id="sessions"></div></section>
 
 <section class="panel">
@@ -406,10 +410,14 @@ _JS = r"""
       var pct = t.rate.limit ? Math.round(100 * (t.rate.limit - t.rate.remaining) / t.rate.limit) : 0;
       out += tile('GH Rate', t.rate.remaining + ' / ' + t.rate.limit, 'used ' + pct + '%', pct);
     } else { out += tile('GH Rate', '--', 'unavailable'); }
+    // The holdout count rides the disk tile's sub-line: a holdout is disk
+    // the janitor will never get back on its own, so it belongs next to the
+    // number it explains. The list itself is the Holdouts panel below.
+    var hsub = t.holdouts ? ' \u00b7 ' + t.holdouts + ' holdout' + (t.holdouts === 1 ? '' : 's') : '';
     if (t.volume) {
-      var vsub = bytes(t.volume.used_bytes) + ' / ' + bytes(t.volume.total_bytes);
+      var vsub = bytes(t.volume.used_bytes) + ' / ' + bytes(t.volume.total_bytes) + hsub;
       out += tile('Volume', t.volume.percent + '%', vsub, t.volume.percent);
-    } else { out += tile('Volume', '--', 'unavailable'); }
+    } else { out += tile('Volume', '--', 'unavailable' + hsub); }
     out += tile('Queue Depth', t.queue_depth, 'candidates last poll');
     el('tiles').innerHTML = out;
   }
@@ -460,6 +468,18 @@ _JS = r"""
     }).join('');
   }
 
+  function renderHoldouts(items) {
+    // Read from the janitor_holdouts ledger table, never from GitHub: the
+    // daemon already wrote down why each one is kept. Oldest episode first.
+    el('holdouts-count').textContent = items.length;
+    if (!items.length) { el('holdouts').innerHTML = '<div class="empty">No holdouts.</div>'; return; }
+    el('holdouts').innerHTML = items.map(function (h) {
+      return '<div class="inbox-item"><span class="mono">' + esc(h.slug) + '</span>' +
+        '<span class="muted task-title" title="' + esc(h.reason) + '">' + esc(h.reason) + '</span>' +
+        '<span class="muted num">' + dur(h.age_seconds) + '</span></div>';
+    }).join('');
+  }
+
   function renderTasks(tasks) {
     if (!tasks.length) { el('tasks').innerHTML = '<div class="empty">No worker tasks listed.</div>'; return; }
     el('tasks').innerHTML = tasks.map(function (t) {
@@ -538,6 +558,7 @@ _JS = r"""
     sparkline(el('spark-active'), d.sparklines.active_sessions);
     renderPipeline(d.pipeline);
     renderInbox(d.inbox);
+    renderHoldouts(d.holdouts || []);
     renderTasks(d.tasks);
     renderSessions(d.sessions);
     renderLog(d.log);

{alissa_tools_github_devloop-0.8.12 → alissa_tools_github_devloop-0.8.13}/src/main/alissa/tools/github/devloop/webui/sources.py

@@ -52,6 +52,12 @@ from . import sysinfo
 # touches none of it. The agreement with `loop.ESCALATION_FOREIGN_SESSION` is
 # pinned by a test instead.
 FOREIGN_SESSION_KIND = "foreign-session"
+# The archive-failure page of the workspace janitor (issue #99). Its rows
+# carry the anchor PULL REQUEST's coordinates in the `issue` column, like the
+# fix-cap/maintain/orphan families, so the inbox links them as PRs. A literal
+# for FOREIGN_SESSION_KIND's reason; agreement with
+# `loop.ESCALATION_ARCHIVE_FAILED` is pinned by a test.
+ARCHIVE_FAILED_KIND = "janitor-archive-failed"
 
 # How many recent snapshots feed the sparklines / pipeline board.
 SPARK_POINTS = 60
@@ -192,6 +198,27 @@ class Sources:
     def snapshots(self, limit: int = SPARK_POINTS) -> "list[dict]":
         return self._read_state([], lambda st: st.read_snapshots(limit))
 
+    def holdouts(self) -> "list[dict]":
+        """The janitor's dirty holdouts from the `janitor_holdouts` ledger
+        table (issue #99), oldest episode first, each with its age -- the
+        console's "Holdouts (N)" list beside the disk tile. Read-only and
+        zero GitHub cost: the janitor already wrote down the anchor verdict
+        and the reason, and a panel that re-derived them would spend one
+        `pulls?head=` call per holdout per refresh."""
+        rows = self._read_state([], lambda st: st.read_janitor_holdouts())
+        now = int(self._wall())
+        return [
+            {
+                "hub": row["hub"],
+                "slug": row["slug"],
+                "reason": row["reason"],
+                "first_seen": row["first_seen"],
+                "last_warned": row["last_warned"],
+                "age_seconds": max(0, now - int(row["first_seen"])),
+            }
+            for row in rows
+        ]
+
     def ledgers(self) -> dict:
         empty: "dict[str, list]" = {
             "spawns": [], "fix_spawns": [],
@@ -439,6 +466,7 @@ class Sources:
         sessions = self.sessions()
         rate = self.rate_limit()
         disk = sysinfo.disk_usage(self.config.workspace_root)
+        holdouts = self.holdouts()
 
         # Sparklines want oldest -> newest for left-to-right drawing.
         chrono = list(reversed(snaps))
@@ -499,6 +527,7 @@ class Sources:
                 "active_sessions": active,
                 "rate": rate,
                 "volume": disk,
+                "holdouts": len(holdouts),
                 "queue_depth": candidates,
             },
             "sparklines": sparklines,
@@ -508,6 +537,7 @@ class Sources:
                 "edges": pipeline,
             },
             "inbox": inbox,
+            "holdouts": holdouts,
             "sessions": sessions,
             "tasks": self.worker_tasks(),
             "log": self.log_tail(),
@@ -519,9 +549,12 @@ class Sources:
         for row in escalations:
             kind = row["kind"]
             number = row["issue"]
-            # fix-*/maintain-*/orphan-* rows store a PR number in the `issue`
-            # column; everything else is an issue number.
-            is_pr = kind.startswith(("fix-cap", "maintain", "orphan"))
+            # fix-*/maintain-*/orphan-*/janitor-archive-failed rows store a
+            # PR number in the `issue` column; everything else is an issue
+            # number.
+            is_pr = kind.startswith(
+                ("fix-cap", "maintain", "orphan", ARCHIVE_FAILED_KIND)
+            )
             leaf = "pull" if is_pr else "issues"
             # foreign-session rows have NO GitHub artifact behind them (issue
             # #95): the subject is a tmux session, and their repo_slug/issue

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

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

@@ -1 +0,0 @@
-0.8.12