alissa-tools-github-devloop 0.8.41__tar.gz → 0.8.43__tar.gz

{alissa_tools_github_devloop-0.8.41/src/main/alissa_tools_github_devloop.egg-info → alissa_tools_github_devloop-0.8.43}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alissa-tools-github-devloop
-Version: 0.8.41
+Version: 0.8.43
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera
@@ -148,6 +148,78 @@ 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.
+
+## Seat parking: what counts as managed (issue #166)
+
+The idle block on `GET /api/state` (`parking.idle_block`, issue #153) is what
+orcloop's D2 invariant reads before it drains and parks the seat: idle only
+when `live == managed == queued == owed == 0` with no timer and a fresh pass.
+`live` and `managed` come from `alissa tmux ls --json`:
+
+- a row is **live** unless it says otherwise (its `live` flag, else
+  `status != "gone"`);
+- a row is **managed** when it is live, **or** when it is dead but its
+  session still backs a lane the seat holds — the session named by a stage
+  of the latest poll snapshot that is owed or in flight (`spawned` /
+  `in-flight`), any session the spawn ledgers record on such a stage's lane
+  (an earlier attempt the lane may still resume), or a session the alissa
+  queue holds an undispatched item for;
+- a dead row backing none of these is an **orphan**: it is not managed, and
+  is reported in the block's `gone` field as `{count, sessions}` so the
+  console and orcloop's logs still show it.
+
+Unknown is never idle: a failed listing leaves `live`, `managed` and `gone`
+null, and before the first completed pass (no snapshot to read lanes from)
+every dead row stays managed. The console only reports an orphan — it never
+kills or reaps one. The fleet-vitals push applies the same rule to
+`sessions.managed` and `idle.managed` (Studio's park guard reads both) and
+leaves `gone` out, since Studio's idle schema is strict.
+
 ## License
 
 Licensed under the

{alissa_tools_github_devloop-0.8.41 → alissa_tools_github_devloop-0.8.43}/README.md

@@ -126,6 +126,78 @@ 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.
+
+## Seat parking: what counts as managed (issue #166)
+
+The idle block on `GET /api/state` (`parking.idle_block`, issue #153) is what
+orcloop's D2 invariant reads before it drains and parks the seat: idle only
+when `live == managed == queued == owed == 0` with no timer and a fresh pass.
+`live` and `managed` come from `alissa tmux ls --json`:
+
+- a row is **live** unless it says otherwise (its `live` flag, else
+  `status != "gone"`);
+- a row is **managed** when it is live, **or** when it is dead but its
+  session still backs a lane the seat holds — the session named by a stage
+  of the latest poll snapshot that is owed or in flight (`spawned` /
+  `in-flight`), any session the spawn ledgers record on such a stage's lane
+  (an earlier attempt the lane may still resume), or a session the alissa
+  queue holds an undispatched item for;
+- a dead row backing none of these is an **orphan**: it is not managed, and
+  is reported in the block's `gone` field as `{count, sessions}` so the
+  console and orcloop's logs still show it.
+
+Unknown is never idle: a failed listing leaves `live`, `managed` and `gone`
+null, and before the first completed pass (no snapshot to read lanes from)
+every dead row stays managed. The console only reports an orphan — it never
+kills or reaps one. The fleet-vitals push applies the same rule to
+`sessions.managed` and `idle.managed` (Studio's park guard reads both) and
+leaves `gone` out, since Studio's idle schema is strict.
+
 ## License
 
 Licensed under the

{alissa_tools_github_devloop-0.8.41 → alissa_tools_github_devloop-0.8.43}/src/main/alissa/tools/github/devloop/fleet_vitals.py

@@ -257,7 +257,8 @@ def build_snapshot(
     `queued` (the undispatched alissa queue items, None when unread) and
     `drain` (the holding drain row, or None) feed the `idle` block, whose
     owed / timers come from the latest poll snapshot and whose live /
-    managed come from `roster` -- the same reading as `sessions`.
+    managed come from `roster` -- the same reading as `sessions`, with a dead
+    row backing no held lane left out of `managed` (issue #166).
 
     `config` is the seat's `config_block`, or None to leave the key out
     (the console's push, which has no derived answer to give)."""
@@ -275,13 +276,20 @@ def build_snapshot(
             if session and session not in repo_by_session:
                 repo_by_session[str(session)] = str(row["repo_slug"])
 
+    # A dead row counts as managed only while it backs a lane the seat still
+    # holds (issue #166): Studio's park guard reads `sessions.managed` as well
+    # as the idle block's, so both follow the console's rule.
+    roster_live, roster_managed, _gone = parking.roster_counts(
+        roster, parking.lane_sessions(latest, ledgers=ledgers),
+    )
+
     sessions_block: "dict | None" = None
     session_list: "list[dict] | None" = None
     if roster is not None:
         records = sources.sessions(listing=[dict(r) for r in roster])
         sessions_block = {
             "live": sum(1 for r in records if r.get("live")),
-            "managed": len(records),
+            "managed": roster_managed,
         }
         session_list = [
             _session_row(r, repo_by_session=repo_by_session, parse_session=parse)
@@ -307,11 +315,13 @@ def build_snapshot(
             + int(latest.get("revert_candidates") or 0)
         )
 
-    roster_live, roster_managed = parking.roster_counts(roster)
     idle = parking.idle_block(
         latest, live=roster_live, managed=roster_managed, queued=queued,
         drain=drain, now=now_ts,
     )
+    # `gone` is the console's observation; Studio's idle schema is strict and
+    # does not carry it.
+    idle.pop("gone", None)
 
     drift = sources.drift()
     snapshot = {

{alissa_tools_github_devloop-0.8.41 → alissa_tools_github_devloop-0.8.43}/src/main/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
@@ -916,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
@@ -1709,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
@@ -4243,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,
@@ -4258,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,
@@ -4308,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:

{alissa_tools_github_devloop-0.8.41 → alissa_tools_github_devloop-0.8.43}/src/main/alissa/tools/github/devloop/parking.py

@@ -8,8 +8,8 @@ the devloop half of that contract, shared by the daemon (which computes the
 verdict per pass and pushes it with the fleet vitals) and the console (which
 serves it on ``GET /api/state`` and runs the drain handshake):
 
-* **The idle block.** ``{asOf, passAt, owed, live, managed, queued, timers,
-  drainedAt}``. `owed` counts the candidates whose LAST evaluation was an
+* **The idle block.** ``{asOf, passAt, owed, live, managed, queued, gone,
+  timers, drainedAt}``. `owed` counts the candidates whose LAST evaluation was an
   action or a timer the seat owns (a spawn, a fresh spawn row in its stale
   window, an owed respawn, a deferral, a pending stall ping, a grace the seat
   is waiting out, an evaluation that failed); a candidate the seat has
@@ -17,7 +17,9 @@ serves it on ``GET /api/state`` and runs the drain handshake):
   owed. Each pass records the verdict per candidate on its poll snapshot's
   stage (`owed`, `timer`), so the block is read back from the snapshot and
   costs no GitHub call. `live` / `managed` / `queued` are read from tmux and
-  the alissa queue by whoever builds the block.
+  the alissa queue by whoever builds the block. `managed` is the live rows
+  plus the dead rows whose session backs a lane the seat still holds; a dead
+  row backing nothing is reported under `gone` instead (`roster_counts`).
 * **Unknown is never idle.** No snapshot yet → `owed` is null; a listing that
   failed → `live` / `managed` / `queued` are null. `idle_refusals` reads every
   null as a refusal.
@@ -29,7 +31,7 @@ serves it on ``GET /api/state`` and runs the drain handshake):
 from __future__ import annotations
 
 from datetime import datetime, timezone
-from typing import Iterable, Mapping, Sequence
+from typing import Collection, Iterable, Mapping, Sequence
 
 # The timer kinds of the design's idle block (§2.1). devloop owns the first
 # three; the last two are revloop's and are listed so the union is stated once.
@@ -111,19 +113,107 @@ def queued_items(queues: "object") -> "int | None":
     return count
 
 
+# The tmux prefix `alissa tmux` puts on a managed session's real name
+# (`alissa.MANAGED_PREFIX`, restated so this module imports nothing of the
+# daemon's). A listing row carries both spellings (`name` bare, `session`
+# prefixed), a snapshot stage the bare one, a queue the prefixed one.
+MANAGED_PREFIX = "ali-"
+
+# The spawn ledgers (`Sources.ledgers` keys) with the snapshot edge each one
+# feeds, the column holding its issue / PR number, and the slug separator the
+# poll snapshot uses for it (`owner/repo#7`, `owner/repo#pr16`).
+LEDGER_LANES = (
+    ("spawns", "issue", "issue", "#"),
+    ("fix_spawns", "fix", "number", "#pr"),
+    ("maintain_spawns", "maintain", "number", "#pr"),
+    ("revert_spawns", "revert", "number", "#pr"),
+)
+
+# A stage holding one of these actions has a worker in flight on it whatever
+# its owed verdict says: its session is never an orphan.
+IN_FLIGHT_ACTIONS = frozenset({"spawned", "in-flight"})
+
+
+def bare_session(name: "object") -> str:
+    """A session name without its `ali-` tmux prefix ("" for a non-name)."""
+    text = str(name or "")
+    return text[len(MANAGED_PREFIX):] if text.startswith(MANAGED_PREFIX) else text
+
+
+def lane_sessions(
+    snapshot: "Mapping | None",
+    *,
+    ledgers: "Mapping | None" = None,
+    queues: "object" = None,
+) -> "frozenset[str] | None":
+    """The bare names of the sessions that back a lane the seat still holds
+    (issue #166): the session a stage that is owed or in flight names; every
+    session the spawn ledgers record on such a stage's lane (an earlier
+    attempt the lane may still resume); and every session the alissa queue
+    holds an undispatched item for. None before the first pass -- with no
+    snapshot nothing can be called an orphan, so every row stays managed."""
+    if snapshot is None:
+        return None
+    names: "set[str]" = set()
+    held: "set[tuple[str, str]]" = set()
+    for stage in snapshot.get("stages") or ():
+        if not isinstance(stage, Mapping):
+            continue
+        if not (stage_owed(stage) or stage.get("stage") in IN_FLIGHT_ACTIONS):
+            continue
+        held.add((str(stage.get("edge") or ""), str(stage.get("slug") or "")))
+        if stage.get("session"):
+            names.add(bare_session(stage["session"]))
+    for table, edge, column, sep in LEDGER_LANES:
+        for row in (ledgers or {}).get(table) or ():
+            lane = (edge, f"{row.get('repo_slug')}{sep}{row.get(column)}")
+            if lane in held and row.get("session"):
+                names.add(bare_session(row["session"]))
+    if isinstance(queues, list):
+        for queue in queues:
+            if not isinstance(queue, Mapping):
+                continue
+            if any(
+                isinstance(item, Mapping) and not item.get("lastDispatchedAt")
+                for item in queue.get("items") or ()
+            ):
+                names.add(bare_session(queue.get("session")))
+    names.discard("")
+    return frozenset(names)
+
+
 def roster_counts(
     roster: "Sequence[Mapping] | None",
-) -> "tuple[int | None, int | None]":
-    """`(live, managed)` from an ``alissa tmux ls --json`` listing, the
-    fleet-vitals `sessions` rule: a row is live unless it says otherwise.
-    `(None, None)` when the listing failed."""
+    lanes: "Collection[str] | None" = None,
+) -> "tuple[int | None, int | None, list[str] | None]":
+    """`(live, managed, gone)` from an ``alissa tmux ls --json`` listing.
+
+    A row is live unless it says otherwise (the fleet-vitals `sessions`
+    rule: its `live` flag, else `status != "gone"`). A row is MANAGED when it
+    is live or when its session backs a lane the seat still holds -- `lanes`,
+    the bare names `lane_sessions` returns. A dead row matching no lane is an
+    orphan: it is not managed, and its name is reported in `gone` instead
+    (issue #166 -- one such row kept orcloop's `managed == 0` from ever
+    holding). `lanes=None` (no completed pass to read lanes from) keeps every
+    row managed: unknown is never idle. `(None, None, None)` when the listing
+    failed."""
     if roster is None:
-        return None, None
-    rows = [r for r in roster if isinstance(r, Mapping)]
-    live = sum(
-        1 for r in rows if bool(r.get("live", r.get("status") != "gone"))
-    )
-    return live, len(rows)
+        return None, None, None
+    live = managed = 0
+    gone: "list[str]" = []
+    for row in roster:
+        if not isinstance(row, Mapping):
+            continue
+        if bool(row.get("live", row.get("status") != "gone")):
+            live += 1
+            managed += 1
+            continue
+        name = bare_session(row.get("name") or row.get("session"))
+        if lanes is None or name in lanes or bare_session(row.get("session")) in lanes:
+            managed += 1
+        else:
+            gone.append(name)
+    return live, managed, sorted(gone)
 
 
 def idle_block(
@@ -134,10 +224,13 @@ def idle_block(
     queued: "int | None",
     drain: "Mapping | None",
     now: "float | int",
+    gone: "Sequence[str] | None" = None,
 ) -> dict:
     """The seat's idle block from its latest poll snapshot (None before the
     first pass) and the caller's live readings. `drain` is the holding drain
-    row (`State.drain`) or None."""
+    row (`State.drain`) or None. `gone` is `roster_counts`' orphaned rows,
+    reported as `{count, sessions}` (null when the listing was not read) --
+    an observation for the operator, never a refusal."""
     stages: "Iterable[Mapping]" = (snapshot or {}).get("stages") or ()
     owed: "int | None" = None
     timers: "list[dict]" = []
@@ -157,6 +250,10 @@ def idle_block(
         "live": live,
         "managed": managed,
         "queued": queued,
+        "gone": (
+            {"count": len(gone), "sessions": list(gone)}
+            if gone is not None else None
+        ),
         "timers": timers,
         "drainedAt": iso(drain.get("drained_at")) if drain else None,
     }

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

@@ -0,0 +1 @@
+0.8.43

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

@@ -438,17 +438,25 @@ class Sources:
         a drain holds. A caller that already holds the listing (None when it
         failed) or the latest snapshot (None before the first pass) hands it
         in; anything not handed in is read here. A failed listing is null
-        counts, never zeros."""
+        counts, never zeros. A dead row backing no lane the seat holds is
+        reported under `gone`, not counted as managed (issue #166)."""
         if latest is _UNREAD:
             snaps = self.snapshots(1)
             latest = snaps[0] if snaps else None
         if listing is _UNREAD:
             listing = self._safe_json(["alissa", "tmux", "ls", "--json"])
         roster = listing if isinstance(listing, list) else None
-        live, managed = parking.roster_counts(roster)
+        snapshot = latest if isinstance(latest, dict) else None
+        queues = self._safe_json(["alissa", "tmux", "queue", "ls", "--json"])
+        # A dead row counts as managed only while it backs a lane the seat
+        # still holds (issue #166).
+        lanes = parking.lane_sessions(
+            snapshot, ledgers=self.ledgers(), queues=queues,
+        )
+        live, managed, gone = parking.roster_counts(roster, lanes)
         return parking.idle_block(
-            latest if isinstance(latest, dict) else None,
-            live=live, managed=managed, queued=self.queued(),
+            snapshot, live=live, managed=managed,
+            queued=parking.queued_items(queues), gone=gone,
             drain=self.drain(), now=self._wall(),
         )
 

{alissa_tools_github_devloop-0.8.41 → alissa_tools_github_devloop-0.8.43/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.41
+Version: 0.8.43
 Summary: ALISSA-TOOLS-GITHUB-DEVLOOP
 Home-page: https://alissa.app
 Author: Fahera
@@ -148,6 +148,78 @@ 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.
+
+## Seat parking: what counts as managed (issue #166)
+
+The idle block on `GET /api/state` (`parking.idle_block`, issue #153) is what
+orcloop's D2 invariant reads before it drains and parks the seat: idle only
+when `live == managed == queued == owed == 0` with no timer and a fresh pass.
+`live` and `managed` come from `alissa tmux ls --json`:
+
+- a row is **live** unless it says otherwise (its `live` flag, else
+  `status != "gone"`);
+- a row is **managed** when it is live, **or** when it is dead but its
+  session still backs a lane the seat holds — the session named by a stage
+  of the latest poll snapshot that is owed or in flight (`spawned` /
+  `in-flight`), any session the spawn ledgers record on such a stage's lane
+  (an earlier attempt the lane may still resume), or a session the alissa
+  queue holds an undispatched item for;
+- a dead row backing none of these is an **orphan**: it is not managed, and
+  is reported in the block's `gone` field as `{count, sessions}` so the
+  console and orcloop's logs still show it.
+
+Unknown is never idle: a failed listing leaves `live`, `managed` and `gone`
+null, and before the first completed pass (no snapshot to read lanes from)
+every dead row stays managed. The console only reports an orphan — it never
+kills or reaps one. The fleet-vitals push applies the same rule to
+`sessions.managed` and `idle.managed` (Studio's park guard reads both) and
+leaves `gone` out, since Studio's idle schema is strict.
+
 ## License
 
 Licensed under the

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

@@ -1 +0,0 @@
-0.8.41