alissa-tools-github-devloop 0.8.40__py3-none-any.whl → 0.8.42__py3-none-any.whl

alissa/tools/github/devloop/config.py

@@ -284,6 +284,8 @@ CONFIG_KEYS = (
     "attempt_cap",
     "stale_minutes",
     "max_sessions",
+    "spawn_headroom_threads",
+    "spawn_headroom_memory_pct",
     "reap_grace_minutes",
     "foreign_session_policy",
     "foreign_session_allow_prefixes",
@@ -535,6 +537,19 @@ class Config:
     # listing, so enabling it costs no extra GitHub or CLI calls.
     max_sessions: int = 0
 
+    # Headroom-aware admission (issue #162): a session count does not bound
+    # what the sessions RUN -- an idle claude holds ~16 threads, a test suite
+    # or a Chromium screenshot 100-200+ -- and the container's cgroup v2
+    # `pids.max` counts THREADS. When `pids.max - pids.current` falls under
+    # `spawn_headroom_threads`, or the free share of `memory.max` under
+    # `spawn_headroom_memory_pct`, a pass spawns nothing new: every spawn
+    # (resumes and fix rounds included) defers on the capacity valve and is
+    # re-decided next poll. 0 turns either guard off; an unlimited (`max`) or
+    # unreadable cgroup file turns its guard off too. The 2026-10-13 outage
+    # (a `gh` fork failing EAGAIN at ~1000 threads) set the defaults.
+    spawn_headroom_threads: int = 300
+    spawn_headroom_memory_pct: int = 15
+
     # The reaper's grace: how long a worker session must have been QUIET (no
     # tmux activity) before a terminal anchor licenses killing it. The point
     # is the window right after an anchor goes terminal -- a PR merges while
@@ -1154,6 +1169,25 @@ class Config:
                 f"max_sessions must be >= 0 (0 = unlimited), got {max_sessions}"
             )
 
+        headroom_threads = int(
+            raw.get("spawn_headroom_threads", cls.spawn_headroom_threads)
+        )
+        if headroom_threads < 0:
+            raise ValueError(
+                f"spawn_headroom_threads must be >= 0 (0 = off), got "
+                f"{headroom_threads}"
+            )
+        headroom_memory = int(
+            raw.get("spawn_headroom_memory_pct", cls.spawn_headroom_memory_pct)
+        )
+        # Capped at 90: a reserve of the whole limit would hold every spawn
+        # for ever on any container that has started anything at all.
+        if not 0 <= headroom_memory <= 90:
+            raise ValueError(
+                f"spawn_headroom_memory_pct must be between 0 and 90 (0 = "
+                f"off), got {headroom_memory}"
+            )
+
         # The reaper's grace, validated like the two below it -- same 0
         # sentinel, and a negative value is the only invalid one (it would
         # make every listed session instantly reapable, which is the one
@@ -1340,6 +1374,8 @@ class Config:
             attempt_cap=cap,
             stale_minutes=stale,
             max_sessions=max_sessions,
+            spawn_headroom_threads=headroom_threads,
+            spawn_headroom_memory_pct=headroom_memory,
             reap_grace_minutes=reap_grace,
             foreign_session_policy=foreign_policy,
             foreign_session_allow_prefixes=normalize_session_prefixes(

alissa/tools/github/devloop/loop.py

@@ -451,6 +451,7 @@ import calendar
 import dataclasses
 import json
 import logging
+import os
 import re
 import sqlite3
 import time
@@ -464,6 +465,7 @@ from . import janitor
 from . import fleet_vitals as fleet_vitals_mod
 from . import loop_events as loop_events_mod
 from . import parking as parking_mod
+from . import proc as proc_mod
 from . import prompts as prompts_mod
 from .alissa import MANAGED_PREFIX, SHELL_COMMANDS, Alissa
 from .alissa_client import AlissaClient
@@ -915,6 +917,117 @@ RESUME_DIRECTIVE = (
     "(best-effort — the daemon's reaper sweep collects stragglers)."
 )
 
+# The discovery round's directive (issue #164, design
+# alissa-build-discovery.md §3.2, lane DS-7). Sent INSTEAD of DEV_DIRECTIVE
+# when the issue carries the trailer `Alissa-Kind: discovery` (rendered by
+# Studio's feed_plan since DS-1): a no-code round in the PLANS repository
+# that reads a code repository at the SHA pinned by `Alissa-Reads:` and writes
+# one knowledge-base directory. What differs from the develop contract, and
+# why each difference is load-bearing:
+#
+# - The read is DETACHED and read-only (a scratch `--detach` worktree off a
+#   hub of the read repo, else `gh api …?ref=<sha>`): no branch exists that
+#   could be pushed, and the push guard (docker/claude/hooks/guard-shell.py,
+#   armed by `write_discovery_marker`) refuses any push that is not to the
+#   plans repository anyway.
+# - The read is bounded by the SHA, not by a file count (D1: no rationing);
+#   only the OUTPUT is bounded, with the findings schema's own limits.
+# - The local `--kb` lint gates the push: findings the linter refuses never
+#   leave the machine, so the run of record never sees them.
+# - The PR is opened READY, carries the discovery marker on a line of its
+#   own, and requests NO reviewer: revloop skips a marked PR confined to
+#   knowledge-base/ (§3.3), orcloop merges it on the lint of record (§3.5),
+#   and a draft would sit unmergeable until the orphan sweep flipped it.
+# - No delivery note: the findings ARE the narrative, and their reader is a
+#   linter and a plan, not a human validator deciding on a merge.
+#
+# The {trailer_note} slot renders to nothing when the trailers parse; see
+# render_discovery_directive for what it says when they do not.
+DISCOVERY_DIRECTIVE = (
+    "You are a DISCOVERY worker, not an implementer and not a reviewer: this "
+    "round writes NO code. Answer the questions of GitHub issue {issue_url} "
+    "(attempt {attempt} of {cap}) by READING code, and record the answers as "
+    "findings — the issue is your self-contained spec, its numbered "
+    "questions are what you answer, and its acceptance criteria are "
+    "authoritative. {task_instruction} {trailer_note}"
+    "Golden path: your cwd is the worktree hub ROOT of the PLANS repository "
+    "{plans_repo} — create the task worktree there with `git worktree add "
+    "TASK-<n>-<DESC>`, where <n> is YOUR IMPLEMENTATION task's number (the "
+    "downstream task YOU created, NOT the origin task's), from there (one "
+    "task = one branch = one worktree; never clone, never work directly on "
+    "main). "
+    + _BRANCH_RULE
+    + _SHELL_RULE
+    + "READ the code at the pinned SHA and nowhere else, read-only: "
+    "`{read_repo}` at `{read_sha}` (the issue's `Alissa-Reads:` trailer). "
+    "If this workspace holds a hub of {read_repo} (a sibling of your hub "
+    "root with a `.source/`), read through a DETACHED scratch worktree: `git "
+    "-C <hub> worktree add --detach <scratch> {read_sha}` (fetch that SHA "
+    "into the hub first if it is missing) — no branch, never pushed — and "
+    "remove it with `git -C <hub> worktree remove --force <scratch>` when "
+    "you are done. Otherwise read through `gh api "
+    "repos/{read_repo}/contents/<path>?ref={read_sha}` and `gh search "
+    "code`. Never clone {read_repo}, and never commit or push to it: this "
+    "session's push guard refuses any `git push` to a repository other than "
+    "{plans_repo}. Never open a deny-listed path (`.env*`, `*.pem`, `*.key`, "
+    "`*.p12`, `id_rsa*`, `*secret*`, `*credential*`, `.npmrc`, `.git/**`, "
+    "`**/node_modules/**`). The read is bounded by the SHA, not by a file "
+    "count — read whatever the questions need; what is bounded is the "
+    "OUTPUT. "
+    "WRITE exactly one directory, `{kb_dir}/`, holding `findings.md` and "
+    "nothing else; no other file anywhere in the repository changes. "
+    "`findings.md` follows the findings schema v1 (`schema/findings.v1.json` "
+    "in the plans repository, and the knowledge-base section of its "
+    "README): YAML frontmatter with `schema: alissa-findings/v1`, `task` = "
+    "the origin task, `reads` = `{read_repo}` at `{read_sha}`, every "
+    "question either answered with cites (repo, path, line range and the "
+    "file's git blob SHA at the pinned SHA) or marked `unanswerable` with a "
+    "reason; then a `## Summary` and one section per question. Stay inside "
+    "the schema's limits: at most 32 KB, 1–12 questions, 12 risks, 8 "
+    "suggested tasks and 24 cites per entry, 400 lines per cite, 1,200 "
+    "characters of Summary and 6,000 per question's section. "
+    "LINT it locally before anything leaves the machine: `node "
+    "lint/plan-lint.ts --kb {kb_dir}` from your worktree (`npm ci` first if "
+    "`node_modules` is missing), with this seat's own `ALISSA_API_TOKEN` in "
+    "the environment for the K6 task check and the K7 cite check. Findings "
+    "the local run refuses are NEVER pushed — fix them and rerun until it "
+    "passes; `plan-lint could not run` is a refusal, not a pass. "
+    "Then commit, push the branch to {plans_repo}, and open a READY (not "
+    "draft) pull request whose body contains `Closes #{number}`, BOTH task "
+    "refs — the origin task AND your implementation task — and the marker "
+    "`<!-- alissa-discovery v1 -->` on a line of its own. That is the "
+    "body's single closing claim: never put a closing keyword (`close`, "
+    "`fix`, `resolve` and their forms) before any other issue reference. "
+    + _DEFAULT_BASE
+    + "Attach the PR URL to your implementation task as evidence, and attach "
+    "a `Findings` evidence item to the origin task — the `## Summary` "
+    "section; one line per question (`q1 · answered · high`); the risk "
+    "count; the PR URL and the blob URL of `findings.md` at the head commit "
+    "— or, if the origin task refuses that write, to your implementation "
+    "task, saying so in the PR body. Then move your implementation task to "
+    "pending_validation. Do NOT request a reviewer — no `gh pr edit … "
+    "--add-reviewer …`, no review skill: a discovery PR is checked by the "
+    "plan-lint run of record and merged on it. NEVER merge, never push to "
+    "main, and do NOT create further ali-* sessions — this loop is depth-1. "
+    "Once your task is pending_validation and the PR is open, your last "
+    "act: run `alissa tmux kill {session}` to end this session and free the "
+    "machine (best-effort — the daemon's reaper sweep collects stragglers)."
+)
+
+# Part of DISCOVERY_DIRECTIVE's {trailer_note} when the issue's `Alissa-Reads:`
+# trailer is absent or not `<owner>/<repo>@<40-hex sha>`. There is then no
+# pinned SHA to read, and a worker that picked one (the default branch's
+# head, say) would write findings K6 refuses at the run of record -- so the
+# round stops instead, and the defect goes where the plan author sees it.
+DISCOVERY_READS_MISSING_NOTE = (
+    "This issue's `Alissa-Reads:` trailer is missing or malformed, so there "
+    "is NO pinned SHA: do not pick one yourself. Comment on the issue naming "
+    "the defect (it must read `Alissa-Reads: <owner>/<repo>@<40-hex sha>`), "
+    "leave your implementation task in_progress with that note, open no "
+    "pull request, and run `alissa tmux kill {session}` to end this "
+    "session. "
+)
+
 # The handover clause (issue #121), shared by FIX_DIRECTIVE and
 # FIX_RESUME_DIRECTIVE. When a later review round lands on the head a fix
 # session is still working (the 2026-09-15 studio#1243 shape: a phantom round
@@ -1708,6 +1821,139 @@ def marker_file_name(tmux_session: str) -> str:
     return safe + ".json"
 
 
+# -- discovery rounds (issue #164) ---------------------------------------
+#
+# The trailers Studio's feed_plan renders on a discovery issue (design
+# alissa-build-discovery.md §2.2). Line-anchored and MULTILINE like
+# `Alissa-Task:`: a trailer sits on a line of its own, so a body QUOTING one
+# mid-sentence (a design issue explaining discovery) is not a discovery issue.
+_DISCOVERY_KIND_RE = re.compile(r"^Alissa-Kind:[ \t]*discovery[ \t]*\r?$", re.MULTILINE)
+_ALISSA_READS_RE = re.compile(
+    r"^Alissa-Reads:[ \t]*(?P<repo>[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)"
+    r"@(?P<sha>[0-9a-f]{40})[ \t]*\r?$",
+    re.MULTILINE,
+)
+_KB_SCOPE_RE = re.compile(
+    r"^Autonomous-Scope:[ \t]*(?P<dir>knowledge-base/\d{4}/\d{2}/\d{2}/TASK-\d+)"
+    r"/\*\*[ \t]*\r?$",
+    re.MULTILINE,
+)
+
+# The knowledge-base directory a discovery directive names when the issue's
+# `Autonomous-Scope:` does not spell one (feed_plan always derives it), and
+# the sentence telling the worker how to fill it in.
+DISCOVERY_KB_DIR_FALLBACK = "knowledge-base/<YYYY>/<MM>/<DD>/TASK-<n>"
+DISCOVERY_KB_DIR_NOTE = (
+    "This issue's `Autonomous-Scope:` does not name the knowledge-base "
+    "directory: in `knowledge-base/<YYYY>/<MM>/<DD>/TASK-<n>/` below, <n> is "
+    "the ORIGIN task's number and the date its creation day (UTC). "
+)
+
+# Where the daemon leaves the marker that arms the push guard for one
+# discovery session, and the env var both sides read it from. The daemon and
+# every worker run in one container with one environment, so the hook
+# (docker/claude/hooks/guard-shell.py, which spells the same default) and
+# this module agree on the directory without a config key.
+DISCOVERY_DIR_ENV = "ALISSA_DISCOVERY_DIR"
+DEFAULT_DISCOVERY_DIR = "/workspace/.discovery"
+
+
+@dataclass(frozen=True)
+class Discovery:
+    """What a discovery issue's trailers say. `read_repo`/`read_sha` are None
+    when `Alissa-Reads:` is absent or malformed, `kb_dir` when
+    `Autonomous-Scope:` is not one knowledge-base directory."""
+
+    read_repo: "str | None"
+    read_sha: "str | None"
+    kb_dir: "str | None"
+
+
+def discovery_of(body: "str | None") -> "Discovery | None":
+    """The discovery trailers of an issue body, or None when it does not
+    carry `Alissa-Kind: discovery` -- the one signal that selects
+    DISCOVERY_DIRECTIVE. The first `Alissa-Reads:` wins."""
+    text = body or ""
+    if not _DISCOVERY_KIND_RE.search(text):
+        return None
+    reads = _ALISSA_READS_RE.search(text)
+    scope = _KB_SCOPE_RE.search(text)
+    return Discovery(
+        read_repo=reads.group("repo") if reads else None,
+        read_sha=reads.group("sha") if reads else None,
+        kb_dir=scope.group("dir") if scope else None,
+    )
+
+
+def render_discovery_directive(
+    *,
+    issue_url: str,
+    number: int,
+    attempt: int,
+    cap: int,
+    task_instruction: str,
+    plans_repo: str,
+    session: str,
+    discovery: Discovery,
+) -> str:
+    """DISCOVERY_DIRECTIVE for one issue. A missing `Alissa-Reads:` renders
+    the read target as placeholders plus DISCOVERY_READS_MISSING_NOTE (stop,
+    do not guess a SHA); a missing knowledge-base scope renders
+    DISCOVERY_KB_DIR_FALLBACK plus DISCOVERY_KB_DIR_NOTE."""
+    notes = ""
+    if discovery.read_repo is None or discovery.read_sha is None:
+        notes += DISCOVERY_READS_MISSING_NOTE.format(session=session)
+    if discovery.kb_dir is None:
+        notes += DISCOVERY_KB_DIR_NOTE
+    return DISCOVERY_DIRECTIVE.format(
+        issue_url=issue_url,
+        number=number,
+        attempt=attempt,
+        cap=cap,
+        task_instruction=task_instruction,
+        trailer_note=notes,
+        plans_repo=plans_repo,
+        read_repo=discovery.read_repo or "<owner>/<repo>",
+        read_sha=discovery.read_sha or "<sha>",
+        kb_dir=discovery.kb_dir or DISCOVERY_KB_DIR_FALLBACK,
+        session=session,
+    )
+
+
+def discovery_dir() -> Path:
+    return Path(os.environ.get(DISCOVERY_DIR_ENV, "").strip() or DEFAULT_DISCOVERY_DIR)
+
+
+def write_discovery_marker(session: str, plans_repo: str, number: int, discovery: Discovery) -> Path:
+    """Arm the push guard for the managed session `session` (its tmux name is
+    `ali-<session>`, the name the hook reads from `$ALISSA_TMUX_SESSION`):
+    `<discovery_dir>/<tmux name>.json`, spelled like the waiting marker
+    (`marker_file_name`), naming the one repository the session may push to.
+    Written atomically (temp file + rename) so the hook never reads a torn
+    file. Raises OSError; the caller stands the spawn down rather than start a
+    discovery session the guard does not know about. Never removed: a
+    session name is unique per issue and attempt, so a stale marker can only
+    ever guard a later session on the same discovery issue."""
+    tmux_name = f"{MANAGED_PREFIX}{session}"
+    folder = discovery_dir()
+    folder.mkdir(parents=True, exist_ok=True)
+    path = folder / marker_file_name(tmux_name)
+    payload = {
+        "session": tmux_name,
+        "plansRepo": plans_repo,
+        "issue": number,
+        "reads": (
+            f"{discovery.read_repo}@{discovery.read_sha}"
+            if discovery.read_repo is not None
+            else None
+        ),
+    }
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(json.dumps(payload, sort_keys=True) + "\n", encoding="utf-8")
+    os.replace(tmp, path)
+    return path
+
+
 # The first-run-dialog wedge's once-per-episode marker (issue #123; see
 # first_run_dialog_kind). Like ESCALATION_WEDGED an ACT, not a page: the
 # daemon killed a session whose pane showed one of Claude Code's first-run
@@ -2689,6 +2935,112 @@ class DiskReport:
     offenders: "tuple[tuple[str, int], ...]" = ()
 
 
+# The container's cgroup v2 mount (issue #162). A module global, read at each
+# call, so a test can point every watcher at a fake cgroup directory.
+CGROUP_ROOT = Path("/sys/fs/cgroup")
+
+
+def _cgroup_value(path: Path) -> "int | str | None":
+    """One cgroup v2 counter file: its integer, the string "max" (no limit),
+    or None when it is absent, unreadable, or malformed."""
+    try:
+        raw = path.read_text().split()[0]
+    except (OSError, ValueError, IndexError):
+        return None
+    if raw == "max":
+        return "max"
+    try:
+        return int(raw)
+    except ValueError:
+        return None
+
+
+def _cgroup_stat(path: Path, field: str) -> int:
+    """One `key value` line of a cgroup `memory.stat`; 0 when unreadable --
+    it only ever ADDS headroom (reclaimable page cache), so a missing stat
+    reads the conservative way."""
+    try:
+        for line in path.read_text().splitlines():
+            key, _, value = line.partition(" ")
+            if key == field:
+                return int(value.strip())
+    except (OSError, ValueError):
+        return 0
+    return 0
+
+
+@dataclass(frozen=True)
+class Headroom:
+    """One pass's cgroup headroom reading (issue #162).
+
+    `low` names every guard whose reserve is breached, in the poll-summary
+    wording (`threads 812/1000, reserve 300`), and is empty when the pass may
+    spawn. `unreadable` names every ENABLED guard whose files could not be
+    read: that guard is off this pass (failing open, like the max_sessions
+    budget on a listing failure -- a missing file must not freeze spawning)
+    and the watcher warns about it once."""
+
+    low: "tuple[str, ...]" = ()
+    unreadable: "tuple[str, ...]" = ()
+
+    @property
+    def reason(self) -> "str | None":
+        """`headroom (threads 812/1000, reserve 300)`, or None when no
+        reserve is breached."""
+        if not self.low:
+            return None
+        return f"headroom ({'; '.join(self.low)})"
+
+
+def read_headroom(
+    threads_reserve: int,
+    memory_pct: int,
+    cgroup_root: "Path | None" = None,
+) -> Headroom:
+    """Read cgroup v2 `pids.current`/`pids.max` and `memory.current`/
+    `memory.max` and judge them against the two reserves. A reserve of 0 is
+    that guard off (its files are not even read); a `max` limit is unlimited,
+    so that guard is off too. `pids.max` counts THREADS, not processes --
+    which is why a session count alone never bounded it. Free memory is the
+    limit minus what is charged, with the inactive page cache the kernel
+    would drop under pressure (`memory.stat inactive_file`) counted as free:
+    a container that just walked a few big checkouts is not out of memory."""
+    root = CGROUP_ROOT if cgroup_root is None else cgroup_root
+    low: "list[str]" = []
+    unreadable: "list[str]" = []
+    if threads_reserve > 0:
+        current = _cgroup_value(root / "pids.current")
+        limit = _cgroup_value(root / "pids.max")
+        if not isinstance(current, int) or limit is None:
+            unreadable.append("threads")
+        elif isinstance(limit, int) and limit - current < threads_reserve:
+            low.append(f"threads {current}/{limit}, reserve {threads_reserve}")
+    if memory_pct > 0:
+        current = _cgroup_value(root / "memory.current")
+        limit = _cgroup_value(root / "memory.max")
+        if not isinstance(current, int) or limit is None:
+            unreadable.append("memory")
+        elif isinstance(limit, int) and limit > 0:
+            charged = max(0, current - _cgroup_stat(root / "memory.stat", "inactive_file"))
+            free = max(0, limit - charged)
+            if free * 100 < memory_pct * limit:
+                low.append(
+                    f"memory {free * 100 // limit}% free of "
+                    f"{limit / (1 << 30):.1f} GiB, reserve {memory_pct}%"
+                )
+    return Headroom(low=tuple(low), unreadable=tuple(unreadable))
+
+
+def cgroup_threads(cgroup_root: "Path | None" = None) -> "str | None":
+    """`pids 998/1000` for a log line, or None when unreadable."""
+    root = CGROUP_ROOT if cgroup_root is None else cgroup_root
+    current = _cgroup_value(root / "pids.current")
+    limit = _cgroup_value(root / "pids.max")
+    if not isinstance(current, int) or limit is None:
+        return None
+    return f"pids {current}/{limit}"
+
+
 class SessionBudget:
     """The per-pass concurrency budget behind `max_sessions`.
 
@@ -2727,10 +3079,18 @@ class SessionBudget:
         hold: "str | None" = None,
         probe: bool = False,
         limited: int = 0,
+        headroom: "str | None" = None,
     ):
         self.limit = limit
         self.active = active
         self.reserved = 0
+        # The cgroup headroom guard (issue #162): while the container's
+        # thread or memory reserve is breached, every reserve() is refused --
+        # resumes, fix rounds and the usage-limit probe included, since each
+        # is a new session with the same footprint. It defers on the
+        # capacity valve (claims nothing, re-decided next poll); `headroom`
+        # is the reason, `headroom (threads 812/1000, reserve 300)`.
+        self.headroom = headroom
         # The prompt responder's spawn hold (issue #127): while an account-
         # level notice (an expired login, a hit limit, no credits) is on a
         # worker's screen, NEW sessions would only burn attempts against a
@@ -2763,7 +3123,10 @@ class SessionBudget:
     def reserve(self) -> bool:
         """Claim one slot if the cap allows. Unlimited always grants -- unless
         the responder's hold stands, which refuses every spawn but the one
-        probe a usage-limit hold admits (issue #144)."""
+        probe a usage-limit hold admits (issue #144). A breached cgroup
+        headroom reserve refuses everything, the probe too (issue #162)."""
+        if self.headroom:
+            return False
         if self.hold:
             if not self.probe or self._probe_taken:
                 return False
@@ -2797,13 +3160,20 @@ class SessionBudget:
     def defer_token(self) -> "str | None":
         """The loop-events defer token a DEFERRED decision off this budget
         carries: the hold's own token while it stands, else None (the
-        emitter reads None as the capacity valve)."""
+        emitter reads None as the capacity valve). A headroom deferral is
+        the capacity valve too (issue #162), even under a hold: the guard
+        refused it first."""
+        if self.headroom:
+            return None
         return loop_events_mod.DEFER_PROMPT_HOLD if self.hold else None
 
     def deferral(self) -> str:
         """The DEFERRED decision's reason -- `at capacity k/k`, the operator's
         signal that the cap (not per-item state) is what held the spawn --
-        or the responder's hold, which names the notice standing in the way."""
+        or the responder's hold, which names the notice standing in the way,
+        or the cgroup headroom reserve the container is under (issue #162)."""
+        if self.headroom:
+            return f"{self.headroom}; retrying next poll"
         if self.hold:
             return f"spawns held by the prompt responder — {self.hold}"
         return f"at capacity {self.used}/{self.limit}; retrying next poll"
@@ -3408,6 +3778,10 @@ class DevWatcher:
         # The reaper's warn-once latch for a CLI without `tmux kill` (kills
         # are best-effort; the condition is per-process, not per-session).
         self._kill_warned = False
+        # The headroom guard's warn-once latch (issue #162): the guards whose
+        # cgroup files could not be read. Per-process like the one above --
+        # an unreadable cgroup does not become readable between polls.
+        self._headroom_warned: "set[str]" = set()
         # The BOW-derived allowlist (`repos_source: "bows"`), or None in
         # static mode -- in which nothing below this line ever runs and the
         # allowlist is `config.repos`, unchanged.
@@ -4114,6 +4488,11 @@ class DevWatcher:
             "resolution"
         )
         regenerate_rule = self._regenerate_rule(issue.owner, issue.repo)
+        # A discovery issue (issue #164) gets DISCOVERY_DIRECTIVE on a fresh
+        # spawn; a resume keeps RESUME_DIRECTIVE (it finishes a PR that
+        # already exists). Both are discovery SESSIONS, so both get the
+        # push-guard marker below.
+        discovery = discovery_of(issue.body)
         if resume_pr is not None:
             directive = RESUME_DIRECTIVE.format(
                 issue_url=issue.url,
@@ -4129,6 +4508,17 @@ class DevWatcher:
                 dead_session=dead_session,
                 regenerate_rule=regenerate_rule,
             )
+        elif discovery is not None:
+            directive = render_discovery_directive(
+                issue_url=issue.url,
+                number=issue.number,
+                attempt=attempt,
+                cap=self.config.attempt_cap,
+                task_instruction=task_instruction,
+                plans_repo=issue.full_name,
+                session=name,
+                discovery=discovery,
+            )
         else:
             directive = DEV_DIRECTIVE.format(
                 issue_url=issue.url,
@@ -4179,6 +4569,32 @@ class DevWatcher:
                 attempt - 1,
             )
 
+        # The push guard's marker (issue #164), before the assignment and the
+        # enqueue: a discovery session must never exist without it, because
+        # the marker is the only thing that tells the shell guard to refuse
+        # its pushes to the read repository. A marker that cannot be written
+        # stands the spawn down exactly like an unreadable issue -- nothing
+        # claimed, the slot handed back, retried next poll. The issue
+        # edge's own repository is the plans repository: Autonomous-Dev of a
+        # discovery issue is the fleet's plans repo (design §2.2).
+        if discovery is not None and not self.config.dry_run:
+            try:
+                write_discovery_marker(name, issue.full_name, issue.number, discovery)
+            except OSError as exc:
+                if budget is not None:
+                    budget.release()
+                log.warning(
+                    "%s: could not write the discovery push-guard marker for "
+                    "%s (%s) — standing the spawn down this pass",
+                    issue.issue_slug, name, exc,
+                )
+                return Decision(
+                    Action.SKIPPED,
+                    f"discovery push-guard marker could not be written ({exc}) "
+                    f"— retried next poll",
+                    attempt - 1,
+                )
+
         # assign_self FIRST: the assignment is the server-side in-flight
         # marker, so it must land before anything is enqueued -- a crash
         # between the two leaves an assigned-but-sessionless issue (safe:
@@ -10234,8 +10650,14 @@ class DevWatcher:
         roster fails CLOSED in the same breath -- an unlisted roster answers
         INDETERMINATE, so a hiccup can never manufacture a resume.
         `max_sessions=0` also yields an unlimited budget -- the default, so
-        nothing changes until an operator opts in."""
+        nothing changes until an operator opts in.
+
+        The cgroup headroom guard (issue #162) is read here too, from files
+        rather than the listing, so it stands through a listing failure: a
+        container out of threads is exactly the one whose `tmux ls` fork
+        fails, and failing the budget open THEN would spawn into the wall."""
         limit = self.config.max_sessions or None
+        headroom = self._read_headroom()
         try:
             sessions = self.alissa.list_sessions()
         except CommandError as exc:
@@ -10250,7 +10672,7 @@ class DevWatcher:
             limit_hold, _probe = self._limit_gate(None)
             return (
                 Sweep(reaped=0, names=set(), hold=limit_hold),
-                SessionBudget(None, 0, hold=limit_hold),
+                SessionBudget(None, 0, hold=limit_hold, headroom=headroom),
                 SessionLiveness(None),
             )
         sweep = self._reap_sessions(sessions)
@@ -10295,10 +10717,60 @@ class DevWatcher:
         )
         return (
             sweep,
-            SessionBudget(limit, active, hold=sweep.hold, probe=probe, limited=limited),
+            SessionBudget(
+                limit, active, hold=sweep.hold, probe=probe, limited=limited,
+                headroom=headroom,
+            ),
             SessionLiveness(sessions, gone),
         )
 
+    def _read_headroom(self) -> "str | None":
+        """The pass's headroom deferral reason, or None when the pass may
+        spawn (issue #162). Logs the breach at WARNING (the operator's signal
+        that the container, not the session cap, is what holds the fleet),
+        and an unreadable guard ONCE per process -- that guard is off."""
+        reading = read_headroom(
+            self.config.spawn_headroom_threads,
+            self.config.spawn_headroom_memory_pct,
+        )
+        for guard in reading.unreadable:
+            if guard in self._headroom_warned:
+                continue
+            self._headroom_warned.add(guard)
+            log.warning(
+                "headroom: the cgroup v2 %s files under %s cannot be read — "
+                "the %s headroom guard is OFF (spawns are not held on it)",
+                guard, CGROUP_ROOT,
+                "spawn_headroom_threads" if guard == "threads"
+                else "spawn_headroom_memory_pct",
+            )
+        if reading.reason:
+            log.warning(
+                "%s: HOLDING new worker spawns this pass (resumes and fix "
+                "rounds included); live sessions keep running and the next "
+                "poll re-reads the cgroup", reading.reason,
+            )
+        return reading.reason
+
+    def _warn_start_failures(self) -> None:
+        """ONE warning per poll for every command that could not even start
+        (issue #162): the fork or exec failed -- EAGAIN at the cgroup's
+        pids.max on 2026-10-13 -- and `proc.run` raised it as the
+        CommandError its caller already handles. Names the errno(s) and the
+        thread budget when the cgroup reads."""
+        failures = proc_mod.take_start_failures()
+        if not failures:
+            return
+        names = ", ".join(sorted(Counter(failures)))
+        threads = cgroup_threads()
+        log.warning(
+            "%d command(s) could not start this poll (%s)%s — the container "
+            "is likely at its process/thread or memory limit; the poll's "
+            "failure paths handled each one",
+            len(failures), names,
+            f"; cgroup {threads}" if threads else "",
+        )
+
     def _check_session_cap(self, active: int, sweep: Sweep) -> None:
         """Page-worthy log when the machine is STILL over `max_sessions` after
         the sweep.
@@ -11259,7 +11731,7 @@ class DevWatcher:
             "poll summary: %d candidate(s) — %d spawned, %d in-flight, "
             "%d skipped, %d escalated, %d capped, %d deferred; "
             "%d worker session(s) reaped, %d foreign; %d parked on a prompt, "
-            "%d answered%s; vitals: %s",
+            "%d answered%s%s; vitals: %s",
             len(results),
             counts[Action.SPAWNED],
             counts[Action.IN_FLIGHT],
@@ -11272,6 +11744,7 @@ class DevWatcher:
             len(sweep.waiting),
             sweep.answered,
             " (spawns HELD)" if sweep.hold else "",
+            f"; deferred: {budget.headroom}" if budget.headroom else "",
             vitals,
         )
         return results
@@ -11701,6 +12174,11 @@ class DevWatcher:
                         "not a GitHub or auth failure; retrying in %ds",
                         exc, backoff,
                     )
+                finally:
+                    # After whichever branch ran, before the sleep: a fork
+                    # failure is usually caught deep in the pass, so a
+                    # "successful" poll is where it most often surfaces.
+                    self._warn_start_failures()
                 time.sleep(backoff)
             except KeyboardInterrupt:
                 log.info("stopping")

alissa/tools/github/devloop/proc.py

@@ -3,6 +3,7 @@ their own auth handling; we never touch tokens ourselves."""
 
 from __future__ import annotations
 
+import errno
 import json
 import logging
 import os
@@ -20,6 +21,29 @@ class CommandError(RuntimeError):
         super().__init__(f"{argv[0]} exited {returncode}: {stderr.strip()[:400]}")
 
 
+# The errno names of every command that could not even START (fork/exec
+# failed) since the last take_start_failures(). Issue #162: at the container's
+# cgroup pids.max a fork raises BlockingIOError (EAGAIN), which run() now
+# turns into a CommandError so each caller's existing failure path handles it;
+# the daemon loop drains this list once per poll to log ONE warning naming
+# the errno and the thread budget, instead of one per failed command.
+_start_failures: "list[str]" = []
+
+
+def _errno_name(exc: OSError) -> str:
+    if exc.errno is None:
+        return type(exc).__name__
+    return errno.errorcode.get(exc.errno, str(exc.errno))
+
+
+def take_start_failures() -> "list[str]":
+    """The errno names of the commands that failed to start since the last
+    call, oldest first; clears the list."""
+    taken = list(_start_failures)
+    _start_failures.clear()
+    return taken
+
+
 def run(
     argv: Sequence[str],
     *,
@@ -39,6 +63,17 @@ def run(
         )
     except subprocess.TimeoutExpired as exc:
         raise CommandError(argv, -1, f"timed out after {timeout}s") from exc
+    except OSError as exc:
+        # The command never ran: the fork or the exec failed (EAGAIN at the
+        # cgroup's pids.max, ENOMEM, a missing binary). Raised as the
+        # CommandError every caller already handles -- the 2026-10-13 outage
+        # was a BlockingIOError escaping run_forever, which only catches
+        # CommandError, and taking the whole daemon down with it.
+        name = _errno_name(exc)
+        _start_failures.append(name)
+        raise CommandError(
+            argv, -1, f"could not start {argv[0]}: {name}: {exc.strerror or exc}"
+        ) from exc
 
     if check and proc.returncode != 0:
         raise CommandError(argv, proc.returncode, proc.stderr)

alissa/tools/github/devloop/version

@@ -1 +1 @@
-0.8.40
+0.8.42

{alissa_tools_github_devloop-0.8.40.dist-info → alissa_tools_github_devloop-0.8.42.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.8.40
+Version: 0.8.42
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera
@@ -148,6 +148,52 @@ issue immediately before every enqueue: a closed issue is `SKIPPED` "issue
 closed between search and spawn", nothing is claimed, and the reserved slot
 is handed back. The respawn-with-resume on an open draft PR is unchanged.
 
+## The discovery round (issue #164)
+
+A discovery issue is a no-code lane in the fleet's **plans repository**
+(design `alissa-build-discovery.md` §3.2, lane DS-7a). Studio's `feed_plan`
+renders it with the trailers `Alissa-Kind: discovery`, `Alissa-Reads:
+<owner>/<repo>@<40-hex sha>` (the code repository it reads, at a pinned SHA)
+and `Autonomous-Scope: knowledge-base/<YYYY>/<MM>/<DD>/TASK-<n>/**`. The
+issue edge spawns the ordinary develop session — same name, same caps, same
+liveness rules — with `DISCOVERY_DIRECTIVE` (in `loop.py`, byte-pinned in
+`test_discovery.py`) instead of `DEV_DIRECTIVE`. Every other issue gets
+today's directive byte for byte; a resume of a dead discovery session keeps
+`RESUME_DIRECTIVE`.
+
+The directive has the worker:
+
+1. create its `TASK-<n>-<DESC>` branch in the plans repository, the branch
+   grammar unchanged;
+2. read the code at the pinned SHA, read-only — a `git -C <hub> worktree add
+   --detach <scratch> <sha>` when the workspace has a hub of the read
+   repository (no branch, removed at the end), otherwise `gh api
+   repos/<repo>/contents/<path>?ref=<sha>` and `gh search code`; never a
+   clone, never a commit or push there. The read is bounded by the SHA, not a
+   file count; the output by the findings schema's limits;
+3. write exactly one directory, `knowledge-base/<YYYY>/<MM>/<DD>/TASK-<n>/`,
+   holding only `findings.md` (findings schema v1, `schema/findings.v1.json`
+   in the plans repository);
+4. run `node lint/plan-lint.ts --kb <dir>` locally with its own
+   `ALISSA_API_TOKEN` (K6/K7) and never push findings it refuses;
+5. open a ready pull request with `Closes #<n>`, both task refs and the
+   marker `<!-- alissa-discovery v1 -->` on a line of its own, attach a
+   `Findings` evidence item, move its task to `pending_validation`, request
+   **no** reviewer (revloop skips such PRs; orcloop merges on the lint of
+   record) and end its session.
+
+**The push guard.** Before it enqueues a discovery session (fresh or
+resumed), the daemon writes `${ALISSA_DISCOVERY_DIR:-/workspace/.discovery}/
+ali-<session>.json` naming the plans repository; a marker that cannot be
+written stands the spawn down for the pass. The container's shell guard
+(`docker/claude/hooks/guard-shell.py`) finds the marker through
+`$ALISSA_TMUX_SESSION` and refuses, with a PreToolUse deny and a reason, any
+`git push` from that session whose destination is not the plans repository —
+resolved from the remote name or URL in the directory the push runs in
+(`-C`, `cd`), and refused outright when it cannot be resolved. Sessions with
+no marker are untouched. `ALISSA_SHELL_GUARD=off` disables this guard with
+the rest.
+
 ## License
 
 Licensed under the

{alissa_tools_github_devloop-0.8.40.dist-info → alissa_tools_github_devloop-0.8.42.dist-info}/RECORD

@@ -3,18 +3,18 @@ alissa/tools/github/devloop/__main__.py,sha256=5p_SjwpOvdyTA8pPr54gS-RP99itkydVc
 alissa/tools/github/devloop/alissa.py,sha256=TJU4eSZc2MvP35HewCwBKvhPAel32vKjtt3ApSPDLrM,18064
 alissa/tools/github/devloop/alissa_client.py,sha256=wmpXYWf9ThcLeYnz6gGeDz7gj5BpYjduuVASMc-QOOY,14873
 alissa/tools/github/devloop/bows.py,sha256=pzDNMRk_S78FX7vMNYMlXHxW6VPHPo1Xd2EzFMgVCUM,17325
-alissa/tools/github/devloop/config.py,sha256=VKeyTsXfoRSDltuU1h9UqjrHGE6YvgCQDvimDt3BH58,73330
+alissa/tools/github/devloop/config.py,sha256=j6W0Wrz7smFdFdSs3g5S6xadcxfFS5YEhQDL64yAuJk,75109
 alissa/tools/github/devloop/fleet_vitals.py,sha256=Hl2xshweh7A9R0N7fyYRg2WzHN4aNefVlt0TiXCv8zk,24979
 alissa/tools/github/devloop/ghclient.py,sha256=tYUHwmoy9CBBt-jSOz9nuAl8lpMvm1LH4A-wHx25bss,71842
 alissa/tools/github/devloop/hubs.py,sha256=yjnsnSHLG7GNNP8X2hILeAMV6P5n4JGc_IaAxpSP_YQ,18974
 alissa/tools/github/devloop/janitor.py,sha256=R8REoHBeY2cfW7fYJVhKr-F5z9Mjlc-vmv-z4KtvBZc,27360
-alissa/tools/github/devloop/loop.py,sha256=A28TYgoz4l0MxOIJ5ypc1fo4A8KPKzjMWsPDv5jZIgs,590661
+alissa/tools/github/devloop/loop.py,sha256=uMfuomSdIPC8KkWUGF0OrW3RR9OSC1txKVnXGZ1SeIc,613973
 alissa/tools/github/devloop/loop_events.py,sha256=tmso0OALqY2yAPW2Fo6ae0sYetQIdIeIYooJ2Sc2cc4,37921
 alissa/tools/github/devloop/parking.py,sha256=2Sys1bh_hG8qbq7cO9RxW1F1kAu3dCWHnvwg_iAFVvY,7987
-alissa/tools/github/devloop/proc.py,sha256=_dDr3g76WEf2DRyLUz1Dzl4KvLVptJant_UZOrRixNk,1649
+alissa/tools/github/devloop/proc.py,sha256=nzfsxJSHFWRQcrXmfv588KazFysv8dVQrhMPH1q5eRk,3134
 alissa/tools/github/devloop/prompts.py,sha256=VzN6ec5eF2wwg7QSCRg52WLcxo-tGbGRgQbc4HSahUc,55169
 alissa/tools/github/devloop/state.py,sha256=uVwhbkogUTjWXXFq-COKzUeYrpuGbHzi05CjfEzAtPA,88668
-alissa/tools/github/devloop/version,sha256=Iu0zRmy7L74fnLuqsTvu96vsUQo8I7iy8DwL-jhPqXs,7
+alissa/tools/github/devloop/version,sha256=AuempWUg4vcEdSLs24Raav8UvlQqlRrI2s1oyudhK4I,7
 alissa/tools/github/devloop/version.py,sha256=znuuOaitXGrBpbskNy78_rlVpFdtmKmk_3k1ACxZrl0,1418
 alissa/tools/github/devloop/webui/__init__.py,sha256=vdXYoyGYzD7BrJ5lV6XdH8Bpw_pej8-RK0hjfxop7-8,1513
 alissa/tools/github/devloop/webui/__main__.py,sha256=wORyW5AkgsniK0TZcrOrvm_P7Q4Mr-fH-4S6qj9XcgA,6137
@@ -23,10 +23,10 @@ alissa/tools/github/devloop/webui/page.py,sha256=4OD3e01ByvVM4Wo04AZyFuyOYTFEMT2
 alissa/tools/github/devloop/webui/server.py,sha256=YuUmcng5qdWqSurcuyxH3FKKkBBfrpDtvtZLidJOGiU,26226
 alissa/tools/github/devloop/webui/sources.py,sha256=Ud8357-Ag4qC39V3mlepqnArui9p1fTJ058bAdN29Jc,36730
 alissa/tools/github/devloop/webui/sysinfo.py,sha256=ptlogH9alFv0vZ-pQfyUaA3w-K7LQS3tQHGv0d8Tdlk,9649
-alissa_tools_github_devloop-0.8.40.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-alissa_tools_github_devloop-0.8.40.dist-info/licenses/NOTICE,sha256=FKstNs3uw_tQod4_1XcFLD1FUTJQXf4FC0oXJAOA_HE,260
-alissa_tools_github_devloop-0.8.40.dist-info/METADATA,sha256=uSiJc6s7Y4u9uz8MTj1oETKuZVJfCtE_NmMSYsvkKyE,8093
-alissa_tools_github_devloop-0.8.40.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-alissa_tools_github_devloop-0.8.40.dist-info/entry_points.txt,sha256=8aC7Ajzx4bu9ZRR37a40IDfuStacvZP5KsAxY1dbFKU,145
-alissa_tools_github_devloop-0.8.40.dist-info/top_level.txt,sha256=DodjDg-l-TWQnlxG-Vuc3G5sB4O7cWGQwe6XrVx3u-A,7
-alissa_tools_github_devloop-0.8.40.dist-info/RECORD,,
+alissa_tools_github_devloop-0.8.42.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+alissa_tools_github_devloop-0.8.42.dist-info/licenses/NOTICE,sha256=FKstNs3uw_tQod4_1XcFLD1FUTJQXf4FC0oXJAOA_HE,260
+alissa_tools_github_devloop-0.8.42.dist-info/METADATA,sha256=ZITb9-7j5ZOmFkpcc4wmIz6DRT7_1HygSpTD7sHLp50,10759
+alissa_tools_github_devloop-0.8.42.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+alissa_tools_github_devloop-0.8.42.dist-info/entry_points.txt,sha256=8aC7Ajzx4bu9ZRR37a40IDfuStacvZP5KsAxY1dbFKU,145
+alissa_tools_github_devloop-0.8.42.dist-info/top_level.txt,sha256=DodjDg-l-TWQnlxG-Vuc3G5sB4O7cWGQwe6XrVx3u-A,7
+alissa_tools_github_devloop-0.8.42.dist-info/RECORD,,