Skip to content

martin1847/evolab / skills/cto-orchestration

cto-orchestration

Unverified

以 CTO/orchestrator 模式管理多 agent 软件交付。用户要求“你做 CTO/编排者”“派 omp/codex 去做”“goal 模式派发”、管理多会话开发或接入这套工作流时使用;“复盘/收口/retro/retrospective”“工作盘点/盘点候选/stocktake”也必须触发,盘点只提案不动工。新项目先用 repo-governance-bootstrap 建治理骨架。不用于单 agent 小任务、无需评审循环的局部改动或纯文档初始化。

FileKindSize
README.mdmarkdown5.3 KB
SKILL.mdskill md15.8 KB
references/agentctl/README.mdmarkdown26.8 KB
references/agentctl/agentctlexecutablescript57.6 KB
references/agentctl/codegraph-hooks.shexecutablescript2.5 KB
references/agentctl/cto-guard-agent.pyexecutablescript26.6 KB
references/agentctl/cto-guard-bash.pyexecutablescript150.5 KB
references/agentctl/cto-guard-edit.pyexecutablescript16.7 KB
references/agentctl/cto-guard-stop.pyexecutablescript7.6 KB
references/agentctl/duplexctl.pyexecutablescript239.5 KB
references/agentctl/guard-hooks.jsonconfig1.5 KB
references/agentctl/identity.pyexecutablescript113.5 KB
references/agentctl/post-checkout-codegraph.shscript18 B
references/agentctl/seat-census.pyscript10.8 KB
references/agentctl/watchctl.pyexecutablescript143.2 KB
references/agents-md-orchestration-section.mdmarkdown5.3 KB
references/decision-queue.mdmarkdown5.7 KB
references/dispatch-baseline.mdmarkdown3.7 KB
references/doc-lifecycle.pyexecutablescript9.2 KB
references/frontend-verify.mdmarkdown7.9 KB
references/goal-clauses.mdmarkdown8.0 KB
references/goal-preflight.pyexecutablescript40.9 KB
references/goal-template.mdmarkdown10.8 KB
references/implementation-discipline.mdmarkdown8.0 KB
references/measurement-protocol.mdmarkdown4.2 KB
references/onboarding-checklist.mdmarkdown3.2 KB
references/queue-freshness.pyexecutablescript3.8 KB
references/queue-hooks.jsonconfig617 B
references/retro-check.shexecutablescript28.2 KB
references/retro-hooks.jsonconfig2.2 KB
references/retro-reminder.shexecutablescript5.8 KB
references/retrospective.mdmarkdown7.7 KB
references/review-brief-preamble.mdmarkdown3.4 KB
references/review-dispatch.mdmarkdown14.4 KB
references/session-economics.pyexecutablescript18.2 KB
references/shock-in-the-loop.mdmarkdown3.8 KB
references/stocktake.mdmarkdown2.3 KB

references/agentctl/seat-census.py

View on GitHub
"""seat-census — which agentctl seats OF THIS REPO are RUNNING with no live watcher.

A LIBRARY, not a hook entrypoint: `cto-guard-stop.py` imports `census()` from here and is its
only consumer. It stays its own module instead of being inlined into the Stop gate so the FACT
and the VERDICT over it remain separately readable, and so a second consumer never has to
re-implement the fact.

WHERE THE FACT COMES FROM. `agentctl status <s>` appends `note: no watcher armed — arm: agentctl
watch <S>` when classify says RUNNING and the watcher pid is absent or dead (watchctl.py
`cmd_status`, the `rc == 10 and not watcher_alive(...)` branch). That note is the SINGLE SOURCE
and this script consumes only it: reading pid / lease files here would be a second liveness
implementation, and the two would drift the first time the run dir layout moved.
Side effect, stated rather than hidden: `status` is not a pure read — for a session with a
declared deliverable it publishes an idle conclusion (identity publish, fenced by the armed
token). This hook therefore does exactly what the orchestrator's own `agentctl status` does, no
more; it is the only command that carries the watcher note.

OWNERSHIP. The run dir is shared by every seat on the box, so a census is not a licence: only
seats whose meta `cwd=` sits in THE SAME REPOSITORY as this payload's cwd are ours to judge
(retro: 账内 ≠ 你的). SAME REPOSITORY is the git COMMON DIR, not the work-tree top level: the
normal shape is an orchestrator in the main checkout and its seats in SIBLING worktrees, and a
containment/top-level test called exactly that pairing foreign — the field failure this filter
was supposed to catch (audit §2). An UNDECIDABLE cwd (no git work tree, no cwd at all, a probe
that never answered) now reports BLINDNESS and an empty seat list: it used to report every seat
on the box unfiltered, so another project's unwatched seat blocked this session's turn end.

BLINDNESS IS REPORTED, NEVER SWALLOWED. When the census cannot answer (unlistable run dir,
missing agentctl, a status that never returned, the budget spent) it returns `Census.blind` with
the reason in one clause and an EMPTY seat list. Deciding what to do with that is the caller's:
the Stop gate turns it into a fail-open WARN, because there silence would read as approval.
Env: AGENT_WATCH_DIR (run dir).

PYTHON FLOOR 3.9, and it is load-bearing: the importer's shebang is `#!/usr/bin/env python3`,
which on a stock macOS host resolves to /usr/bin/python3 3.9.6. PEP 604 (`str | None`) is
evaluated at class/module level and raises TypeError THERE, i.e. this module fails to IMPORT and
the Stop gate degrades to "census module could not be loaded" — a silently disabled gate.
Annotations here use `typing.Optional`; PEP 585 (`list[str]`) is fine, it landed in 3.9.
"""
import os
import subprocess
import sys
import time

# The repo-identity predicate and the run-dir default, shared with E1 and the compaction
# reminder. Imported from THIS file's own directory: the Stop gate loads this module by path
# (the filename is hyphenated), so the sibling is not otherwise importable, and an installed
# copy has to stay self-contained.
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import identity                             # noqa: E402 — after the sys.path bootstrap above
from typing import List, NamedTuple, Optional

_META = ".duplex.meta"
_SEAT_CAP = 20                             # OWNED seats consulted per census, alphabetical
_CALL_TIMEOUT = 5.0                        # per `agentctl status` / `git rev-parse`
_CENSUS_BUDGET = 20.0                      # ownership probe + every status, so a Stop hook can
                                           # never hang a turn end. The deadline is taken BEFORE
                                           # the git call, which is inside it, not beside it.


class Census(NamedTuple):
    """seats: owned sessions that are RUNNING with no live watcher.
    overflow: OWNED metas past `_SEAT_CAP` that were never consulted.
    blind: None = the census answered; otherwise why it could not, in one clause."""
    seats: List[str]
    overflow: int
    blind: Optional[str]


def run_dir() -> str:
    """The lane's run dir — ONE definition, in `identity`, so a gate and the runtime it
    observes can never read different directories."""
    return identity.run_dir()


def _meta_cwd(path: str) -> Optional[str]:
    """The seat's `cwd=`, or None when the meta cannot be read or carries none. Same `key=value`
    format identity.py:_meta_read consumes; first occurrence wins, exactly as it does there."""
    try:
        with open(path, encoding="utf-8") as fh:
            for line in fh:
                key, sep, value = line.rstrip("\n").partition("=")
                if sep and key.strip() == "cwd":
                    return value.strip() or None
    except (OSError, UnicodeDecodeError):
        return None
    return None


def _same_repo(seat_cwd: str, owner: str, timeout: float) -> bool:
    """Is this seat's cwd in the SAME repository as the payload's? `identity.repo_id` answers
    with the git common dir, which is what makes sibling worktrees of one repo compare EQUAL —
    the whole point of the filter (see the header). None never compares equal: an unattributable
    seat cwd is not ours to judge."""
    seat_repo = identity.repo_id(seat_cwd, timeout=timeout)
    return seat_repo is not None and seat_repo == owner


def _status(agentctl: str, session: str, run: str, timeout: float) -> Optional[str]:
    """`agentctl status <session>` stdout, or None when the question was never answered (missing
    binary, timeout, spawn failure). None must not be read as 'watched': the caller treats it as
    a blind census and degrades."""
    env = dict(os.environ)
    env["AGENT_WATCH_DIR"] = run
    try:
        proc = subprocess.run([agentctl, "status", session], stdout=subprocess.PIPE,
                              stderr=subprocess.DEVNULL, timeout=timeout, env=env)
    except Exception:
        return None
    return proc.stdout.decode("utf-8", "replace")


def _unwatched(out: str) -> bool:
    """The predicate, on `status` output alone: the typed verdict line says RUNNING and the
    advisory note says no watcher is armed. Both halves are required — the note without a
    RUNNING first line would be a stale read of some other classification."""
    lines = [ln for ln in out.splitlines() if ln.strip()]
    return bool(lines) and lines[0].startswith("RUNNING") and "no watcher armed" in out


def census(cwd: Optional[str], run: str) -> Census:
    """The shared enumeration. Bounded four ways so a Stop hook can never hang a turn end: at
    most `_SEAT_CAP` OWNED seats, `_CALL_TIMEOUT` per subprocess, `_CENSUS_BUDGET` for the whole
    path — deadline first, ownership probe INSIDE it (R1 M2: taking the deadline after the git
    call made the real worst case 25s while the file advertised 20s) — and the ownership SCAN
    metered per meta (R2 major: the per-entry cost is trivial, the aggregate over a large or slow
    run dir is not). The FIRST status that does not answer ends the census as blind rather than
    reporting a set it knows is short — a partial census would let a real unwatched seat read as
    'nothing to report'.

    OWNERSHIP IS APPLIED BEFORE THE CAP (R1 B3): capping the raw meta list first meant 20
    alphabetically-earlier FOREIGN seats could evict this repo's own unwatched seat to position
    21, and the gate then reported an answered EMPTY census and let the turn end. Foreign metas
    now cost one file read plus one repo probe each and nothing else — no status call, no cap
    slot. An UNDECIDABLE owner ends the census BLIND (audit §2): reporting the box's seats
    unfiltered made another project's unwatched seat block this session's turn end, and a WARN
    that says "ownership went unanswered" is the honest version of that."""
    agentctl = os.path.join(os.path.dirname(os.path.abspath(__file__)), "agentctl")
    deadline = time.monotonic() + _CENSUS_BUDGET
    try:
        names = sorted(n for n in os.listdir(run) if n.endswith(_META))
    except OSError:
        return Census([], 0, f"run dir {run} could not be listed")
    if not names:
        return Census([], 0, None)
    if not os.access(agentctl, os.X_OK):
        return Census([], 0, f"{agentctl} is not executable")
    owner = (identity.repo_id(cwd, timeout=min(_CALL_TIMEOUT,
                                               max(0.0, deadline - time.monotonic())))
             if cwd else None)
    # The budget is judged BEFORE the owner: an ownership probe that ATE the whole budget must
    # report the budget it spent, not the ownership it therefore could not answer (R1 M2 pins
    # that the git call is inside this deadline, not beside it).
    if time.monotonic() >= deadline:
        return Census([], 0, f"the seat census ran past its {int(_CENSUS_BUDGET)}s budget "
                             "during the ownership probe")
    if owner is None:
        return Census([], 0, "this payload's cwd could not be attributed to a repository, so "
                             "seat ownership is unknown and no seat here is judgeable")
    mine: List[str] = []
    for name in names:
        # The scan itself is metered (R2 major): one `open` + one repo probe per meta is cheap
        # per entry and unbounded in the AGGREGATE — a large or slow (network / contended) run
        # dir could walk the whole census past its budget before the first deadline check ever
        # ran, which is precisely the "the gate becomes the thing that stalls a turn end" failure
        # the budget exists to prevent. Stopping here reports a blind census, which is the same
        # fail-open exit every other unanswerable case takes.
        left = deadline - time.monotonic()
        if left <= 0:
            return Census([], 0,
                          f"the seat census ran past its {int(_CENSUS_BUDGET)}s budget during "
                          "the ownership scan")
        # An empty / unreadable `cwd=` is NOT ours: a cwd-less meta must never inherit ownership
        # from the hook process's own location.
        seat_cwd = _meta_cwd(os.path.join(run, name))
        if not seat_cwd or not _same_repo(seat_cwd, owner, min(_CALL_TIMEOUT, left)):
            continue                       # another repo's session: two cheap reads, nothing more
        mine.append(name[: -len(_META)])
    overflow = max(0, len(mine) - _SEAT_CAP)
    seats: List[str] = []
    for session in mine[:_SEAT_CAP]:
        left = deadline - time.monotonic()
        if left <= 0:
            return Census([], overflow,
                          f"the seat census ran past its {int(_CENSUS_BUDGET)}s budget")
        out = _status(agentctl, session, run, min(_CALL_TIMEOUT, left))
        if out is None:
            return Census([], overflow, f"`agentctl status {session}` never answered")
        if _unwatched(out):
            seats.append(session)
    return Census(seats, overflow, None)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall