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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.8.12
+Version: 0.8.14
 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.14}/src/main/alissa/tools/github/devloop/__main__.py

@@ -282,6 +282,26 @@ def build_parser() -> argparse.ArgumentParser:
         "(two overlapping instances can then both spawn on one item)",
     )
 
+    loop_events = over.add_mutually_exclusive_group()
+    loop_events.add_argument(
+        "--loop-events",
+        dest="loop_events_enabled",
+        action="store_true",
+        default=None,
+        help="push one idempotent batch of loop events (spawns, defers, "
+        "cap-outs, stalls, hand-offs, reaps, escalations) per poll pass to "
+        "Studio's POST /v1/loop-events on the alissa endpoint — best-effort, "
+        "never fatal. ALISSA_DEV_LOOP_EVENTS_ENABLED (non-blank) overrides "
+        "even this flag",
+    )
+    loop_events.add_argument(
+        "--no-loop-events",
+        dest="loop_events_enabled",
+        action="store_false",
+        help="never push loop telemetry, even if the config enables it "
+        "(the default: the push is opt-in)",
+    )
+
     janitor = over.add_mutually_exclusive_group()
     janitor.add_argument(
         "--janitor",
@@ -386,6 +406,7 @@ def overrides_from(args: argparse.Namespace) -> dict:
         "orphan_sweep_enabled": args.orphan_sweep_enabled,
         "orphan_grace_minutes": args.orphan_grace_minutes,
         "activity_claims_enabled": args.activity_claims_enabled,
+        "loop_events_enabled": args.loop_events_enabled,
         "janitor_enabled": args.janitor_enabled,
         "janitor_grace_minutes": args.janitor_grace_minutes,
         "janitor_interval_minutes": args.janitor_interval_minutes,
@@ -500,6 +521,13 @@ def log_effective_config(config: Config, login: str) -> None:
         config.cache_cap_mb,
         config.disk_warn_percent,
     )
+    log.info(
+        "loop_events=%s%s",
+        config.loop_events_enabled,
+        f" (one batch per pass → POST {config.alissa_endpoint}"
+        f"/v1/loop-events, best-effort)"
+        if config.loop_events_enabled else "",
+    )
     log.debug("hub_template: %s", config.hub_template)
     log.debug(
         "cache_paths: %s",

{alissa_tools_github_devloop-0.8.12 → alissa_tools_github_devloop-0.8.14}/src/main/alissa/tools/github/devloop/alissa_client.py

@@ -22,7 +22,12 @@ already authenticates — the same transport, endpoints and taxonomy orcloop's
 `urllib` only: the distribution ships no third-party runtime dependency, and
 this must not be the change that adds one.
 
-Endpoints, both verified against the live API:
+Since issue #101 the adapter also carries the daemon's ONE write —
+``POST /v1/loop-events`` (`post_loop_events`), the loop-telemetry push — over
+the same transport, token and taxonomy, so the daemon still reads and writes
+Alissa through a single REST idiom.
+
+Endpoints, the reads both verified against the live API:
 
 ``GET /v1/ping``
     ``{"pong", "timestamp", "userId", "actorId", "displayName"}`` — the
@@ -141,22 +146,32 @@ class AlissaClient:
         self._token = token if token is not None else os.environ.get(ENV_TOKEN)
         self._timeout = timeout
 
-    def _request(self, path: str) -> object:
-        """One GET. Every failure leaves as a taxonomy exception — the caller
-        never sees a raw urllib error or an HTTP status."""
+    def _request(
+        self, path: str, *, method: str = "GET", body: object = None
+    ) -> object:
+        """One call. Every failure leaves as a taxonomy exception — the caller
+        never sees a raw urllib error or an HTTP status. `body`, when given,
+        is JSON-serialised and sent with the matching Content-Type (the shape
+        every write on this API takes)."""
         if not self._token:
             # No token at all is an auth condition, not a transport one: the
             # operator must set the env var. Fail the way a 401 would, so the
             # boot path treats it as permanent rather than retrying forever.
             raise AlissaAuthError(0, f"{ENV_TOKEN} is not set")
 
+        headers = {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self._token}",
+        }
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
         req = urllib.request.Request(
             f"{self.base}{path}",
-            method="GET",
-            headers={
-                "Accept": "application/json",
-                "Authorization": f"Bearer {self._token}",
-            },
+            method=method,
+            data=data,
+            headers=headers,
         )
         try:
             with urllib.request.urlopen(req, timeout=self._timeout) as resp:
@@ -226,6 +241,27 @@ class AlissaClient:
             display_name=str(row.get("displayName") or ""),
         )
 
+    def post_loop_events(self, events: "list[dict]") -> "dict":
+        """Push one batch of loop-telemetry events (issue #101).
+
+        ``POST /v1/loop-events`` (fahera-mx/studio.alissa.app, `API.md` →
+        "Loop telemetry — ingest"): 1–200 events per call, idempotent on the
+        caller's `dedupeKey` — a repeated key is a silent duplicate, never an
+        error — and any shape error fails the WHOLE batch with a 400 naming
+        the offending index. The batch bound and the event shapes are the
+        CALLER's contract (`loop_events.py` derives and splits); this method
+        is just the transport, returning the server's
+        ``{"accepted": n, "duplicates": m}`` verbatim.
+
+        Failures leave as the taxonomy like every other call here. The one
+        caller is best-effort by design — it catches AlissaError, warns once
+        and moves on — so nothing extra is softened at this layer.
+        """
+        payload = self._request(
+            "/v1/loop-events", method="POST", body={"events": list(events)}
+        )
+        return payload if isinstance(payload, dict) else {}
+
     def list_bodies_of_work(self) -> "list[BodyOfWork]":
         """Every Body of Work this actor owns OR collaborates on — ONE call.
 

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

@@ -21,6 +21,8 @@ var > `--repos-source` > the config key. A BLANK env var means "not set" here
 (unlike ALISSA_DEV_REVIEWERS, where empty is a meaningful answer): an unset
 platform variable reference renders as the empty string, and that must fall
 through to the config rather than fail the daemon's boot on a mode of `''`.
+`loop_events_enabled` rides the same shape of rail through
+`ALISSA_DEV_LOOP_EVENTS_ENABLED`, with the same blank-falls-through rule.
 """
 
 from __future__ import annotations
@@ -64,6 +66,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.
@@ -77,6 +90,18 @@ ENV_REPOS_SOURCE = "ALISSA_DEV_REPOS_SOURCE"
 # `alissa_endpoint` so one deployment can point both daemons at one API.
 DEFAULT_ALISSA_ENDPOINT = "https://api.alissa.app"
 
+# The loop-telemetry rail (issue #101): `loop_events_enabled` ridden the way
+# ALISSA_DEV_REPOS_SOURCE rides repos_source — a NON-BLANK value here wins
+# over the CLI and the file alike, and a blank one falls through (an unset
+# platform variable reference renders as "", which must not decide anything).
+# Accepted spellings are 1/true/0/false, case-insensitive; anything else is a
+# config error at boot — a typo silently read as false would leave an operator
+# staring at a variable that does nothing.
+ENV_LOOP_EVENTS = "ALISSA_DEV_LOOP_EVENTS_ENABLED"
+
+_ENV_BOOL_TRUE = frozenset(("1", "true"))
+_ENV_BOOL_FALSE = frozenset(("0", "false"))
+
 # What an Alissa actor id looks like: a 32-character opaque handle of
 # lower-case letters and digits (`j5706fv7xe5jy1k5wdwzacab9s8axcd2`). Every id
 # the API mints has this shape, and `bow_owners` is checked against it so a
@@ -127,9 +152,11 @@ CONFIG_KEYS = (
     "orphan_sweep_enabled",
     "orphan_grace_minutes",
     "activity_claims_enabled",
+    "loop_events_enabled",
     "janitor_enabled",
     "janitor_grace_minutes",
     "janitor_interval_minutes",
+    "janitor_holdout_policy",
     "cache_cap_mb",
     "cache_paths",
     "disk_warn_percent",
@@ -487,6 +514,18 @@ class Config:
     # that would rather not pay the extra comments fetch.
     activity_claims_enabled: bool = True
 
+    # The loop-telemetry push (issue #101): at the end of each poll pass,
+    # POST one idempotent batch of the ledger-derived loop events — spawns,
+    # defers, cap-outs, stalls, hand-offs, reaps, escalations — to Studio's
+    # /v1/loop-events on `alissa_endpoint`, over the same REST client and
+    # token `bows` mode reads with. Best-effort and never fatal: a failed
+    # push warns once and the pass completes, and deterministic dedupe keys
+    # make re-emission harmless. Default OFF — the push writes to an external
+    # service on every pass, so it is the operator's to opt into; disabled,
+    # no request is ever made. ALISSA_DEV_LOOP_EVENTS_ENABLED (non-blank)
+    # wins over the CLI and the file, repos_source's rail exactly.
+    loop_events_enabled: bool = False
+
     # The workspace janitor (issue #74): the filesystem sibling of the session
     # reaper. Every worker session materializes a per-task workspace under its
     # repo's hub (a `TASK-<n>-<DESC>` worktree plus whatever its lane installs
@@ -518,6 +557,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
@@ -732,6 +786,28 @@ class Config:
                 + (f" (from {ENV_REPOS_SOURCE})" if env_source else "")
             )
 
+        # The loop-telemetry rail, repos_source's shape exactly: a NON-BLANK
+        # ALISSA_DEV_LOOP_EVENTS_ENABLED wins over the CLI and the file, and
+        # blank falls through. Validated by NAME like the enums — a typo read
+        # as false would silently disable a push the operator asked for.
+        loop_events = bool(
+            raw.get("loop_events_enabled", cls.loop_events_enabled)
+        )
+        env_loop_events = (os.environ if environ is None else environ).get(
+            ENV_LOOP_EVENTS, ""
+        ).strip()
+        if env_loop_events:
+            lowered = env_loop_events.casefold()
+            if lowered in _ENV_BOOL_TRUE:
+                loop_events = True
+            elif lowered in _ENV_BOOL_FALSE:
+                loop_events = False
+            else:
+                raise ValueError(
+                    f"{ENV_LOOP_EVENTS} must be one of 1/true/0/false "
+                    f"(case-insensitive), got {env_loop_events!r}"
+                )
+
         bow_owners = normalize_bow_owners(raw.get("bow_owners", cls.bow_owners))
 
         refresh_polls = int(
@@ -853,6 +929,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(
@@ -921,9 +1010,11 @@ class Config:
             activity_claims_enabled=bool(
                 raw.get("activity_claims_enabled", cls.activity_claims_enabled)
             ),
+            loop_events_enabled=loop_events,
             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.14}/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.