alissa-tools-github-devloop 0.8.22__tar.gz → 0.8.24__tar.gz

{alissa_tools_github_devloop-0.8.22/src/main/alissa_tools_github_devloop.egg-info → alissa_tools_github_devloop-0.8.24}/PKG-INFO

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

alissa_tools_github_devloop-0.8.24/src/main/alissa/tools/github/devloop/hubs.py

@@ -0,0 +1,427 @@
+"""Hub trust: keeping Claude Code's per-directory "trust this folder?" gate
+pre-accepted for every directory a dev session may start in (issue #123).
+
+Claude Code asks, once per directory, whether the folder it was started in is
+trusted -- and `--dangerously-skip-permissions` does NOT suppress that
+dialog. A headless session that meets it hangs: the directive `alissa tmux
+queue` types into the pane is swallowed by the prompt, the session sits in
+the roster reading ALIVE, and the daemon's liveness discipline (correctly)
+declines to respawn over a listed session. Observed 2026-09-16 on
+`dark-devloop-shared`: 108 minutes on `ali-fhr/docs.alissa.app#10`, until an
+operator accepted the dialog by hand.
+
+The container entrypoint seeds the gate at boot for the hubs it can NAME at
+boot: `{root}/{basename}` for every entry in `ALISSA_DEV_REPOS`, plus every
+hub already on disk. Under `repos_source: bows` `ALISSA_DEV_REPOS` is empty
+-- the allowlist is DERIVED from the feed Bodies of Work at runtime -- so a
+repo hub-ified after boot was never trusted. This module closes that gap
+from the daemon's side, in three places the loop calls:
+
+* after every successful feed refresh: the derived list is written to
+  `{root}/.alissa-derived-repos` (`DERIVED_REPOS_FILENAME`) so the NEXT boot's
+  entrypoint seeding can read it, and the derived hubs are trusted right
+  away, hub-ified or not (trusting a path that does not exist yet is exactly
+  what the entrypoint already does for the static allowlist);
+* at hub-ify time and before every spawn (`DevWatcher._ensure_hub`): the hub
+  root, `{hub}/main`, and every `{hub}/TASK-*` worktree on disk;
+* after a first-run-dialog wedge kill: the hub the wedged session started in,
+  so the re-enqueued attempt does not meet the same prompt.
+
+The merge is the entrypoint's, transposed: load-then-update of
+`~/.claude.json` and `$CLAUDE_CONFIG_DIR/.claude.json` (when set --
+`CLAUDE_CONFIG_DIR` reliably relocates only the credential file, so both
+targets are written and whichever claude reads carries the flag), only ever
+ADDING `projects[<path>].hasTrustDialogAccepted = true`. Idempotent: a target
+that already carries every entry is not rewritten at all, which is also what
+keeps the daemon's writes off a file Claude Code itself rewrites -- the only
+time this module touches the file is when a NEW directory has to be
+trusted. That write is guarded on three sides, because Claude Code itself
+rewrites the same file while sessions run (`_trust_hub` runs before EVERY
+spawn, and the `TASK-*` glob makes most of those writes real ones): the
+temp-file + rename keeps a concurrent READER from ever seeing a torn file;
+a compare-and-swap immediately before the rename (the file must still hold
+the bytes the merge was computed from) keeps the OTHER WRITER's update
+from being discarded wholesale -- the payload is the whole file, so a lost
+update could drop another session's `projects` entries or the persisted
+login; and a re-read after the rename catches a writer that landed right
+after ours and dropped OUR entries. Either miss restarts the merge on top
+of the newer file, a bounded number of times, and giving up is one WARNING.
+Never raises: trust is a convenience for the session about to spawn, and a
+failed write is one WARNING, never a lost poll.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Iterable, Sequence
+
+log = logging.getLogger(__name__)
+
+# The file the daemon writes the derived (bows-mode) allowlist to, under the
+# workspace root, one `owner/repo` per line -- and the file the entrypoint's
+# first-run seeding reads at the NEXT boot (`ALISSA_DERIVED_REPOS_FILE`
+# overrides the location on both sides).
+DERIVED_REPOS_FILENAME = ".alissa-derived-repos"
+ENV_DERIVED_REPOS_FILE = "ALISSA_DERIVED_REPOS_FILE"
+
+# The state file Claude Code keeps its per-directory trust in, relative to
+# $HOME and to $CLAUDE_CONFIG_DIR.
+CLAUDE_STATE_FILENAME = ".claude.json"
+ENV_CLAUDE_CONFIG_DIR = "CLAUDE_CONFIG_DIR"
+TRUST_KEY = "hasTrustDialogAccepted"
+
+# What a pane PARKED on one of Claude Code's first-run gates shows -- and
+# what corroborates that it is parked there rather than merely mentioning
+# it (PR #124 review round 1). The gates' words are quoted by this repo's
+# README, CHANGELOG, this module and issue #123, so a session that cats any
+# of them, greps the tree or shows its own diff has them on screen while at
+# work -- and a match kills the session. The classifier therefore asks for
+# the gate's SHAPE, not its vocabulary (see `pane_shows_first_run_dialog`):
+#
+# * the gate's ACCEPT option (`FIRST_RUN_DIALOG_OPTIONS`) is one of the last
+#   `FIRST_RUN_DIALOG_TAIL_LINES` non-blank lines of the capture, once the
+#   selection cursor, option numbering and box drawing are stripped;
+# * nothing follows it but the gate's own chrome (`FIRST_RUN_DIALOG_CHROME`):
+#   a session that printed ANYTHING after the text -- a spinner, a tool
+#   call, the `>` input prompt an idle session sits at, a shell prompt --
+#   is not on the gate;
+# * the gate's QUESTION (`FIRST_RUN_DIALOG_MARKERS`) appears at or above
+#   the option line.
+#
+# The trust dialog reads "Quick safety check: Is this a project you created
+# or one you trust? … ❯ No, exit / Yes, I trust this folder"; the
+# bypass-permissions gate reads "WARNING: Claude Code running in Bypass
+# Permissions mode … No, exit / Yes, I accept" (either option order, with
+# or without numbering, an optional "Enter to confirm · Esc to exit" footer
+# and box drawing). Both are gates the entrypoint's seeding is meant to
+# pre-answer, so a pane parked on either is a session the seeding missed,
+# not a session at work.
+FIRST_RUN_DIALOG_MARKERS = (
+    "trust this folder",
+    "bypass permissions mode",
+)
+FIRST_RUN_DIALOG_OPTIONS = (
+    "yes, i trust this folder",
+    "yes, i accept",
+)
+FIRST_RUN_DIALOG_CHROME = (
+    "no, exit",
+    "enter to confirm",
+)
+FIRST_RUN_DIALOG_TAIL_LINES = 6
+
+# What a gate draws AROUND its text: box drawing, the selection cursor and
+# whitespace (stripped from both ends of a line), then "1." / "2)" option
+# numbering. Nothing else is stripped -- a diff's `+`, a markdown bullet,
+# a quote's backtick and the `>` of Claude Code's input prompt all stay,
+# which is what keeps a line that merely quotes a gate from reading as one.
+_DIALOG_DECORATION = "❯ \t│┃║╭╮╰╯┌┐└┘├┤┬┴┼─━═"
+_DIALOG_NUMBERING = re.compile(r"^\d+[.)]\s*")
+
+# How many times `seed_trust` restarts a merge that another writer moved
+# the file under (see the module docstring) before it gives up with a
+# WARNING. Claude Code's own rewrites are bursts around a session's start
+# and end, not a stream, so a second pass is expected to land.
+SEED_TRUST_ATTEMPTS = 3
+
+# The wedge classification the loop logs and records for a stale session
+# whose pane shows one of those gates.
+WEDGE_FIRST_RUN_DIALOG = "wedged:first-run-dialog"
+
+
+def claude_state_targets(
+    home: "Path | str | None" = None, config_dir: "Path | str | None" = None
+) -> "list[Path]":
+    """The `.claude.json` files to merge trust into: `$HOME/.claude.json`,
+    plus `$CLAUDE_CONFIG_DIR/.claude.json` when that variable is set and
+    non-blank. Both arguments default to the environment (`~` expansion
+    honours `HOME`), which is what lets a test point the merge at scratch
+    directories without touching the daemon's own files."""
+    home_dir = Path(home) if home is not None else Path(os.path.expanduser("~"))
+    targets = [home_dir / CLAUDE_STATE_FILENAME]
+    raw = (
+        str(config_dir)
+        if config_dir is not None
+        else os.environ.get(ENV_CLAUDE_CONFIG_DIR, "")
+    ).strip()
+    if raw:
+        extra = Path(raw) / CLAUDE_STATE_FILENAME
+        if extra != targets[0]:
+            targets.append(extra)
+    return targets
+
+
+def hub_trust_paths(hub: "Path | str") -> "list[Path]":
+    """Every directory a session on this hub may START in: the hub root
+    (where develop/fix/maintain sessions are spawned), `{hub}/main`, and each
+    `{hub}/TASK-*` worktree already on disk (a retried or resumed attempt may
+    be started inside a surviving worktree). The root and `main` are listed
+    whether or not they exist yet -- the point of seeding is to be there
+    BEFORE the directory is used."""
+    root = Path(hub)
+    paths = [root, root / "main"]
+    try:
+        worktrees = sorted(
+            p for p in root.glob("TASK-*") if p.is_dir()
+        )
+    except OSError:
+        worktrees = []
+    paths.extend(worktrees)
+    return paths
+
+
+def _load_state(path: Path) -> "tuple[str | None, dict]":
+    """The state file's raw text (None when absent) and its parsed object
+    (`{}` when absent or not a JSON object). Only ABSENCE is folded into
+    "start fresh": an unparseable file raises `ValueError` up to
+    `seed_trust`, which skips that target rather than replacing it (a
+    corrupt state file is never silently overwritten). The raw text is what
+    `_write_atomic` compares against before its rename."""
+    try:
+        with open(path, encoding="utf-8") as fh:
+            raw = fh.read()
+    except FileNotFoundError:
+        return None, {}
+    data = json.loads(raw)
+    return raw, (data if isinstance(data, dict) else {})
+
+
+def _raw_text(path: Path) -> "str | None":
+    try:
+        return path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+
+
+def _write_atomic(path: Path, data: dict, expected: "str | None") -> bool:
+    """Write `data` over `path` by temp file + rename -- unless the file no
+    longer holds `expected` (the raw text the caller merged from), in which
+    case nothing is replaced and False is returned so the caller merges
+    again on top of whoever wrote in between. The rename keeps READERS
+    safe (never a torn file); the check before it keeps the OTHER WRITER's
+    update safe, down to the gap between the check and the rename."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    with open(tmp, "w", encoding="utf-8") as fh:
+        json.dump(data, fh, indent=2)
+        fh.write("\n")
+    if _raw_text(path) != expected:
+        tmp.unlink(missing_ok=True)
+        return False
+    os.replace(tmp, path)
+    return True
+
+
+def _add_trust(state: dict, wanted: "list[str]") -> "list[str]":
+    """Merge `projects[<path>].hasTrustDialogAccepted = true` for every
+    wanted path into `state` (in place, repairing a missing or non-object
+    `projects`). Returns the paths that were NOT already trusted."""
+    projects = state.get("projects")
+    if not isinstance(projects, dict):
+        projects = {}
+        state["projects"] = projects
+    added = []
+    for p in wanted:
+        entry = projects.get(p)
+        if not isinstance(entry, dict):
+            entry = {}
+            projects[p] = entry
+        if entry.get(TRUST_KEY) is not True:
+            entry[TRUST_KEY] = True
+            added.append(p)
+    return added
+
+
+def _untrusted(state: dict, wanted: "list[str]") -> "list[str]":
+    projects = state.get("projects")
+    if not isinstance(projects, dict):
+        return list(wanted)
+    return [
+        p for p in wanted
+        if not isinstance(projects.get(p), dict)
+        or projects[p].get(TRUST_KEY) is not True
+    ]
+
+
+def _merge_target(target: Path, wanted: "list[str]") -> bool:
+    """Merge `wanted` into ONE claude state file. True when the file was
+    written. Load, merge, compare-and-swap, verify -- and start over, up to
+    SEED_TRUST_ATTEMPTS times, whenever another writer moved the file
+    between the load and the rename (the swap refuses) or right after the
+    rename (the verify finds an entry missing). Never raises."""
+    wrote = False
+    for _ in range(SEED_TRUST_ATTEMPTS):
+        try:
+            raw, state = _load_state(target)
+        except (OSError, ValueError) as exc:
+            if wrote:
+                # Our write landed; whoever replaced it since left something
+                # this daemon will not touch. Nothing more to do here.
+                log.debug("trust: %s unreadable after the merge (%s)", target, exc)
+                return True
+            log.warning(
+                "trust: could not read %s (%s) — leaving it untouched; the "
+                "directories are NOT pre-trusted there: %s",
+                target, exc, ", ".join(wanted),
+            )
+            return False
+        added = _add_trust(state, wanted)
+        if not added:
+            # Every entry is present: it always was, or the pass before
+            # this one landed and survived.
+            return wrote
+        try:
+            swapped = _write_atomic(target, state, raw)
+        except OSError as exc:
+            log.warning(
+                "trust: could not write %s (%s) — the directories are NOT "
+                "pre-trusted there: %s", target, exc, ", ".join(added),
+            )
+            return wrote
+        if not swapped:
+            log.info(
+                "trust: %s changed underneath the merge — merging %s again "
+                "on top of the newer file", target, ", ".join(added),
+            )
+            continue
+        wrote = True
+        try:
+            _, after = _load_state(target)
+        except (OSError, ValueError) as exc:
+            log.debug("trust: %s unreadable right after the merge (%s)", target, exc)
+            return True
+        missing = _untrusted(after, wanted)
+        if not missing:
+            log.debug("trust: %s now pre-trusts %s", target, ", ".join(added))
+            return True
+        log.info(
+            "trust: %s was rewritten right after the merge and lost %s — "
+            "merging again", target, ", ".join(missing),
+        )
+    log.warning(
+        "trust: gave up merging into %s after %d attempts — another writer "
+        "kept rewriting it, so the directories may NOT be pre-trusted there: %s",
+        target, SEED_TRUST_ATTEMPTS, ", ".join(wanted),
+    )
+    return wrote
+
+
+def seed_trust(
+    paths: "Iterable[Path | str]",
+    *,
+    home: "Path | str | None" = None,
+    config_dir: "Path | str | None" = None,
+) -> "list[Path]":
+    """Merge `projects[<path>].hasTrustDialogAccepted = true` for every path
+    into every claude state target. Returns the targets that were WRITTEN
+    (a target already carrying every entry is left untouched -- byte for
+    byte, no rewrite). Never raises and never removes anything: an
+    unparseable target is skipped with a WARNING rather than replaced, a
+    failed write is a WARNING too, and a target another writer keeps
+    moving under the merge is retried a bounded number of times (see
+    `_merge_target` and the module docstring) before that, too, is one
+    WARNING.
+
+    Paths are recorded as absolute strings, which is how Claude Code keys
+    them; a relative path is resolved against the cwd, which is never what a
+    caller means, so callers pass absolute hubs."""
+    wanted = [os.fspath(Path(p)) for p in paths]
+    changed: "list[Path]" = []
+    if not wanted:
+        return changed
+    for target in claude_state_targets(home, config_dir):
+        if _merge_target(target, wanted):
+            changed.append(target)
+    return changed
+
+
+def derived_repos_path(root: "Path | str") -> Path:
+    """Where the derived allowlist is written under this workspace root, or
+    wherever `ALISSA_DERIVED_REPOS_FILE` points (the same override the
+    entrypoint honours, so an operator relocating one relocates both)."""
+    override = os.environ.get(ENV_DERIVED_REPOS_FILE, "").strip()
+    if override:
+        return Path(override)
+    return Path(root) / DERIVED_REPOS_FILENAME
+
+
+def write_derived_repos(root: "Path | str", repos: "Sequence[str]") -> "Path | None":
+    """Record the derived allowlist, one `owner/repo` per line, for the next
+    boot's entrypoint seeding. Rewritten only when the content differs.
+    Returns the path written, or None when nothing changed or the write
+    failed (logged; never raised -- the daemon has already trusted the hubs
+    itself, so this file only matters to a future boot)."""
+    path = derived_repos_path(root)
+    body = "".join(f"{r}\n" for r in repos)
+    try:
+        if path.is_file() and path.read_text(encoding="utf-8") == body:
+            return None
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_name(path.name + ".tmp")
+        tmp.write_text(body, encoding="utf-8")
+        os.replace(tmp, path)
+    except OSError as exc:
+        log.warning(
+            "could not record the derived allowlist at %s (%s) — the next "
+            "boot's entrypoint seeding will not pre-trust these hubs until a "
+            "refresh succeeds: %s", path, exc, ", ".join(repos),
+        )
+        return None
+    return path
+
+
+def read_derived_repos(root: "Path | str") -> "tuple[str, ...]":
+    """The recorded derived allowlist (`owner/repo` per line; blank lines and
+    `#` comments ignored), or `()` when absent or unreadable."""
+    path = derived_repos_path(root)
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return ()
+    out = []
+    for line in text.splitlines():
+        line = line.strip()
+        if line and not line.startswith("#") and "/" in line:
+            out.append(line)
+    return tuple(out)
+
+
+def _dialog_line(line: str) -> str:
+    """A pane line reduced to the text a gate would render there (see
+    _DIALOG_DECORATION), casefolded."""
+    text = line.strip(_DIALOG_DECORATION)
+    text = _DIALOG_NUMBERING.sub("", text).strip(_DIALOG_DECORATION)
+    return text.casefold()
+
+
+def _is_dialog_chrome(text: str) -> bool:
+    return any(text.startswith(chrome) for chrome in FIRST_RUN_DIALOG_CHROME)
+
+
+def pane_shows_first_run_dialog(pane: str) -> bool:
+    """Whether a session's terminal tail is PARKED on one of Claude Code's
+    first-run gates: the gate's accept option among the last
+    FIRST_RUN_DIALOG_TAIL_LINES non-blank lines, nothing but the gate's own
+    chrome below it, and the gate's question at or above it (the notes on
+    FIRST_RUN_DIALOG_MARKERS say why each leg is there). An empty capture
+    (the CLI could not tail) is never a dialog -- absence of evidence keeps
+    the defer -- and neither is a pane that merely MENTIONS a gate: a
+    session at work or idle at its prompt has printed something below the
+    words, and that something is not the gate's chrome."""
+    if not pane:
+        return False
+    lines = [t for t in (_dialog_line(ln) for ln in pane.splitlines()) if t]
+    tail = lines[-FIRST_RUN_DIALOG_TAIL_LINES:]
+    for offset in range(len(tail) - 1, -1, -1):
+        if any(tail[offset].startswith(o) for o in FIRST_RUN_DIALOG_OPTIONS):
+            break
+    else:
+        return False
+    if not all(_is_dialog_chrome(t) for t in tail[offset + 1:]):
+        return False
+    above = lines[:len(lines) - len(tail) + offset + 1]
+    return any(m in t for t in above for m in FIRST_RUN_DIALOG_MARKERS)