Add the composition root and a runnable entry point

Nothing had ever assembled the agent. main.py was still the hello-world
placeholder from the scaffold, and no code outside the test suite
constructed an Orchestrator — which is how two fully built, fully
tested components came to be reachable from nothing: the delegation
harness, and the Gitea comment poller. Unit tests that construct a
component directly cannot catch that; only assembly can.

- config.py validates every variable before anything is built and
  names all of them at once, rather than failing at first use twenty
  minutes into a milestone on the call that mattered. Whitespace-only
  counts as missing, since a token of spaces passes a truthiness check
  and fails at the first request instead
- agent.py builds the whole graph and owns startup and shutdown order:
  reconcile before accepting commands, and on stop, stop watching,
  then stop talking, then close the store last
- The Gitea account is read via whoami rather than configured: it names
  the identity every permission is evaluated against, and proves the
  token works before anything depends on it
- Poller lifecycle is now a state-machine concern: watch the plan issue
  while a gate stands, the PR while it is open, and stop on leaving.
  The orchestrator owns when to watch; an injected factory owns how to
  build one
- The executor reports each turn, because it runs synchronously inside
  the transport callback: without it the agent is silent for a whole
  milestone and a working run looks exactly like a hung one
- main.py loads .env, builds, and shuts down cleanly on SIGINT/SIGTERM

The entry-point tests changed shape: nisse-dev no longer greets, it
refuses to start unconfigured and says everything that is missing. Both
tests now run with a deliberately empty environment and a .env path
that does not exist, because the working directory's .env holds live
credentials and a test must never be one cwd away from starting a real
agent.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

nisse-dev/src/nisse_dev/agent.py

@@ -0,0 +1,167 @@
+"""Composition root: the one place that knows how the whole agent fits together.
+
+Every component below has been unit-tested in isolation for some time; nothing
+had ever assembled them. That gap hid two live bugs — the delegation harness
+and the Gitea comment poller were both fully built and reachable from nothing
+but their own tests — which is the argument for having a single root rather
+than constructing pieces ad hoc.
+"""
+
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from nisse_dev.approvals import PlanBoard
+from nisse_dev.config import AgentConfig
+from nisse_dev.control import Orchestrator
+from nisse_dev.delegation import Delegation
+from nisse_dev.executor import LLMExecutor
+from nisse_dev.expert import ExpertDesk
+from nisse_dev.git import GitRepo, authenticated_url
+from nisse_dev.gitea import Comment, GiteaClient
+from nisse_dev.llm import AnthropicPassthroughClient, LiteLLMClient
+from nisse_dev.matrix import MatrixTransport
+from nisse_dev.oplog import OpLog
+from nisse_dev.planner import LLMPlanningAgent
+from nisse_dev.poller import CommentPoller
+from nisse_dev.publish import MilestonePublisher
+from nisse_dev.state import StateStore
+from nisse_dev.tools import Workspace
+
+
+@dataclass
+class Agent:
+    config: AgentConfig
+    store: StateStore
+    transport: MatrixTransport
+    orchestrator: Orchestrator
+    gitea: GiteaClient
+    account: str
+    _stopped: threading.Event
+
+    def start(self) -> None:
+        """Boot in the order A3 requires: reconcile against external truth
+        before accepting a single operator command."""
+        self.orchestrator.start()
+        self.transport.start()
+        state = self.store.get_state()
+        where = state.state if state else "IDLE"
+        self.transport.send_message(
+            f"nisse-dev up as {self.account} — project {self.config.project}, "
+            f"state {where}, planner {self.config.roles.planner}, "
+            f"executor {self.config.roles.executor}"
+        )
+
+    def wait(self) -> None:
+        self._stopped.wait()
+
+    def stop(self) -> None:
+        """Shut down outermost-first: stop accepting work, then stop talking,
+        then close the state store last so nothing writes to a closed file."""
+        self.orchestrator.stop_watching()
+        self.transport.close()
+        self.gitea.close()
+        self.store.close()
+        self._stopped.set()
+
+
+def prepare_workspace(config: AgentConfig, account: str) -> GitRepo:
+    """Ensure the workspace is a clone of the project repo.
+
+    Cloning here rather than on `use <project>` is the single-project
+    shortcut: resolving a project name to a repo is issue #27's work.
+    """
+    repo = GitRepo(config.workspace)
+    remote = authenticated_url(
+        config.gitea_url, config.gitea_repo, account, config.gitea_token
+    )
+    if not (config.workspace / ".git").exists():
+        config.workspace.parent.mkdir(parents=True, exist_ok=True)
+        GitRepo(config.workspace.parent).clone(remote, config.workspace)
+    repo.configure_identity(account, f"{account}@users.noreply.local")
+    return repo
+
+
+def build_agent(
+    config: AgentConfig, *, notify: Callable[[str], None] | None = None
+) -> Agent:
+    oplog = OpLog("nisse-dev")
+    store = StateStore(config.state_db, oplog=oplog)
+
+    gitea = GiteaClient(config.gitea_url, config.gitea_token)
+    # Whoami rather than another config variable: it names the identity every
+    # Gitea permission is evaluated against, and proves the token works before
+    # anything depends on it.
+    account = gitea.whoami()
+
+    git_repo = prepare_workspace(config, account)
+    workspace = Workspace(config.workspace)
+
+    normalized = LiteLLMClient(config.llm_base_url, config.llm_token)
+    # Delegations take the passthrough route; fidelity is cheap elsewhere (A5).
+    passthrough = AnthropicPassthroughClient(config.llm_base_url, config.llm_token)
+
+    transport = MatrixTransport(config.matrix)
+    announce = notify or transport.send_message
+
+    expert = ExpertDesk(normalized, store, config.roles)
+    delegation = Delegation(
+        passthrough,
+        store,
+        workspace,
+        git_repo,
+        model=config.roles.resolve("delegate"),
+    )
+    executor = LLMExecutor(
+        normalized,
+        store,
+        config.roles,
+        workspace,
+        expert=expert,
+        delegate=delegation,
+        notify=announce,
+    )
+    publisher = MilestonePublisher(
+        store,
+        gitea,
+        config.gitea_repo,
+        git_repo,
+        base_url=config.gitea_url,
+        account=account,
+        token=config.gitea_token,
+        base_branch=config.base_branch,
+    )
+
+    def poller_factory(on_comment: Callable[[Comment], None]) -> CommentPoller:
+        return CommentPoller(
+            gitea,
+            config.gitea_repo,
+            on_comment,
+            oplog=oplog,
+            # Its own comments are not new input; without this the agent
+            # answers itself.
+            ignore_authors={account},
+        )
+
+    orchestrator = Orchestrator(
+        store,
+        transport,
+        LLMPlanningAgent(normalized, store, config.roles),
+        operators=config.operators,
+        roles=config.roles,
+        executor=executor,
+        publisher=publisher,
+        gitea_operators=config.gitea_operators,
+        board=PlanBoard(gitea, config.gitea_repo),
+        delegate=delegation,
+        poller_factory=poller_factory,
+    )
+    return Agent(
+        config=config,
+        store=store,
+        transport=transport,
+        orchestrator=orchestrator,
+        gitea=gitea,
+        account=account,
+        _stopped=threading.Event(),
+    )

nisse-dev/src/nisse_dev/config.py

@@ -0,0 +1,99 @@
+"""Agent configuration (spec A5: from env/.env, nothing hardcoded).
+
+Every value is collected and validated **before** anything is built, and a
+single error names every missing variable at once. The alternative — failing
+at first use — surfaces a missing token twenty minutes into a milestone, on
+the call that mattered.
+"""
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+from nisse_dev.llm import RoleMap
+from nisse_dev.matrix import MatrixConfig
+
+REQUIRED = (
+    "NISSE_STATE_DB",
+    "NISSE_WORKSPACE",
+    "NISSE_PROJECT",
+    "NISSE_LLM_BASE_URL",
+    "NISSE_LLM_TOKEN",
+    "NISSE_ROLE_EXECUTOR",
+    "NISSE_ROLE_PLANNER",
+    "NISSE_ROLE_DELEGATE",
+    "NISSE_ROLE_CONSULTANT",
+    "NISSE_MATRIX_HOMESERVER",
+    "NISSE_MATRIX_USER_ID",
+    "NISSE_MATRIX_TOKEN",
+    "NISSE_MATRIX_ROOM_ID",
+    "NISSE_MATRIX_OPERATORS",
+    "NISSE_GITEA_URL",
+    "NISSE_GITEA_TOKEN",
+    "NISSE_GITEA_REPO",
+    "NISSE_GITEA_OPERATORS",
+)
+
+
+class ConfigError(RuntimeError):
+    pass
+
+
+def _people(raw: str) -> frozenset[str]:
+    """Operator allowlists are comma-separated; blanks are dropped so a
+    trailing comma cannot admit an empty identity."""
+    return frozenset(part.strip() for part in raw.split(",") if part.strip())
+
+
+@dataclass(frozen=True)
+class AgentConfig:
+    state_db: Path
+    workspace: Path
+    project: str
+    llm_base_url: str
+    llm_token: str
+    roles: RoleMap
+    matrix: MatrixConfig
+    operators: frozenset[str]
+    gitea_url: str
+    gitea_token: str
+    gitea_repo: str
+    gitea_operators: frozenset[str]
+    base_branch: str = "main"
+
+    @classmethod
+    def from_env(cls, env: Mapping[str, str] = os.environ) -> "AgentConfig":
+        # Whitespace-only counts as missing: a token of spaces would pass a
+        # truthiness check and fail at the first request instead.
+        missing = [name for name in REQUIRED if not (env.get(name) or "").strip()]
+        if missing:
+            raise ConfigError(
+                "cannot start: these are unset or empty — " + ", ".join(missing)
+            )
+        return cls(
+            state_db=Path(env["NISSE_STATE_DB"]).expanduser(),
+            workspace=Path(env["NISSE_WORKSPACE"]).expanduser(),
+            project=env["NISSE_PROJECT"],
+            llm_base_url=env["NISSE_LLM_BASE_URL"],
+            llm_token=env["NISSE_LLM_TOKEN"],
+            roles=RoleMap.from_env(env),
+            matrix=MatrixConfig.from_env(env),
+            operators=_people(env["NISSE_MATRIX_OPERATORS"]),
+            gitea_url=env["NISSE_GITEA_URL"],
+            gitea_token=env["NISSE_GITEA_TOKEN"],
+            gitea_repo=env["NISSE_GITEA_REPO"],
+            gitea_operators=_people(env["NISSE_GITEA_OPERATORS"]),
+            base_branch=env.get("NISSE_BASE_BRANCH", "main"),
+        )
+
+    def redacted(self) -> dict[str, str]:
+        """What the agent may safely announce about how it is configured."""
+        return {
+            "project": self.project,
+            "workspace": str(self.workspace),
+            "repo": self.gitea_repo,
+            "planner": self.roles.planner,
+            "executor": self.roles.executor,
+            "delegate": self.roles.delegate,
+        }

nisse-dev/src/nisse_dev/control.py

@@ -164,6 +164,7 @@ class Orchestrator:
         gitea_operators: Iterable[str] = (),
         board: "PlanBoard | None" = None,
         delegate: Any = None,
+        poller_factory: Any = None,
     ) -> None:
         self._store = store
         self._transport = transport
@@ -178,6 +179,11 @@ class Orchestrator:
         self._gitea_operators = set(gitea_operators)
         self._board = board
         self._delegate = delegate
+        # Builds a poller bound to a comment handler; the orchestrator
+        # owns *when* to watch, which is a state-machine concern, while
+        # the factory owns how to build one.
+        self._poller_factory = poller_factory
+        self._pollers: dict[str, Any] = {}
         # Transport and the comment poller deliver on separate threads;
         # state transitions must not interleave.
         self._lock = threading.RLock()
@@ -465,6 +471,9 @@ class Orchestrator:
             # durability of the record, not the ability to approve.
             return
         board_state["comment_id"] = post.comment_id
+        # Approvals can arrive on the issue as well as over transport (A4),
+        # so watch it for as long as the gate stands.
+        self._watch("plan", board_state["issue"], self.handle_plan_comment)
 
     def handle_plan_comment(self, comment: Any) -> None:
         """A comment on the project issue may satisfy an open plan gate (A4).
@@ -586,6 +595,8 @@ class Orchestrator:
             "url": result.pull_request.url,
             "milestone": milestone,
         }
+        self._unwatch("plan")  # the gate is behind us; the PR is the thread now
+        self._watch("review", result.pull_request.number, self.handle_review_comment)
         self._transition(PR_OPEN, cause=f"milestone {milestone} published")
         self._transport.send_message(
             f"{result.note} — review it, then say 'next milestone' or "
@@ -594,12 +605,14 @@ class Orchestrator:
 
     def _handle_pr_open(self, text: str) -> None:
         if text == "next milestone":
+            self._unwatch("review")
             self._data["milestone"] = int(self._data.get("milestone", 1)) + 1
             self._data["gate"] = None
             self._data["pr"] = None
             self._transition(MILESTONE_PLANNING, cause="operator: next milestone")
             self._run_planning_turn(f"milestone-{self._data['milestone']}")
         elif text == "project complete":
+            self.stop_watching()
             self._data = {**_fresh_data()}
             self._project = None
             self._store.oplog.task_id = None
@@ -614,6 +627,27 @@ class Orchestrator:
                 "'project complete'"
             )
 
+    def _watch(self, kind: str, index: int, handler: Any) -> None:
+        """Start watching one Gitea thread, replacing any previous watch of
+        the same kind. Priming first, so attaching does not replay comments
+        already addressed."""
+        if self._poller_factory is None:
+            return
+        self._unwatch(kind)
+        poller = self._poller_factory(handler)
+        poller.prime(index)
+        poller.start(index)
+        self._pollers[kind] = poller
+
+    def _unwatch(self, kind: str) -> None:
+        poller = self._pollers.pop(kind, None)
+        if poller is not None:
+            poller.stop()
+
+    def stop_watching(self) -> None:
+        for kind in list(self._pollers):
+            self._unwatch(kind)
+
     def _await_input(self, *, cause: str, prompt: str, pending: dict[str, Any]) -> None:
         self._data["pending"] = pending
         self._transition(AWAIT_INPUT, cause=cause)

nisse-dev/src/nisse_dev/executor.py

@@ -10,6 +10,7 @@ or finished-enough. Until delegation exists (step 7), an escalation gates to
 the human with the failures attached rather than engaging a frontier model.
 """
 
+from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Any, Literal
 
@@ -60,6 +61,7 @@ class LLMExecutor:
         failure_limit: int = DEFAULT_FAILURE_LIMIT,
         expert: ExpertDesk | None = None,
         delegate: Delegation | None = None,
+        notify: Callable[[str], None] | None = None,
     ) -> None:
         self._client = client
         self._store = store
@@ -69,6 +71,21 @@ class LLMExecutor:
         self._failure_limit = failure_limit
         self._expert = expert
         self._delegate = delegate
+        # The loop runs synchronously inside the transport callback, so
+        # without this the agent is silent for the whole milestone and a
+        # working run looks exactly like a hung one.
+        self._notify = notify
+
+    def _report(self, turn: int, calls: list[ToolCall]) -> None:
+        if self._notify is None:
+            return
+        summary = ", ".join(
+            f"{c.tool}({c.arguments.get('path') or c.arguments.get('command', '')[:40]})"
+            if c.arguments
+            else c.tool
+            for c in calls
+        )
+        self._notify(f"turn {turn + 1}: {summary}")
 
     def _escalate(
         self, milestone: int, failures: int, last_failure: str
@@ -133,7 +150,7 @@ class LLMExecutor:
         did_work = False
         challenged = False
 
-        for _turn in range(self._max_turns):
+        for turn in range(self._max_turns):
             try:
                 produced = self._client.complete(
                     self._store.read_events(),
@@ -166,6 +183,7 @@ class LLMExecutor:
                     "executor claimed the milestone was done without making any change",
                 )
 
+            self._report(turn, calls)
             for call in calls:
                 if call.tool in MUTATING_TOOLS:
                     did_work = True

nisse-dev/src/nisse_dev/git.py

@@ -59,6 +59,10 @@ class GitRepo:
         self.root.mkdir(parents=True, exist_ok=True)
         self._run("init", "-q", "-b", default_branch)
 
+    def clone(self, remote_url: str, dest: Path, *, token: str | None = None) -> None:
+        self.root.mkdir(parents=True, exist_ok=True)
+        self._run("clone", "-q", remote_url, str(dest), secret=token)
+
     def configure_identity(self, name: str, email: str) -> None:
         self._run("config", "user.name", name)
         self._run("config", "user.email", email)

nisse-dev/src/nisse_dev/main.py

@@ -1,11 +1,46 @@
-"""Placeholder entry point for the dev agent."""
+"""Entry point for the dev agent.
 
-from nisse_core.greeting import greeting
+Loads configuration, builds the agent, and stays up until told to stop.
+Shutdown is deliberate rather than abrupt: A2's durability guarantees assume
+the process may die at any moment, but a clean stop still beats relying on
+them.
+"""
+
+import os
+import signal
+import sys
+from pathlib import Path
+from types import FrameType
+
+from nisse_dev.agent import build_agent
+from nisse_dev.config import AgentConfig, ConfigError
+from nisse_dev.envfile import load_env_file
 
 
-def main() -> None:
-    print(greeting("nisse-dev"))
+def main() -> int:
+    load_env_file(Path(os.environ.get("NISSE_ENV", ".env")).expanduser())
+    try:
+        config = AgentConfig.from_env()
+    except ConfigError as exc:
+        # Fail here rather than twenty minutes into a milestone on the one
+        # call that needed the missing value.
+        print(f"nisse-dev: {exc}", file=sys.stderr)
+        return 2
+
+    agent = build_agent(config)
+
+    def shutdown(_signum: int, _frame: FrameType | None) -> None:
+        print("nisse-dev: stopping", file=sys.stderr)
+        agent.stop()
+
+    signal.signal(signal.SIGINT, shutdown)
+    signal.signal(signal.SIGTERM, shutdown)
+
+    agent.start()
+    print(f"nisse-dev: ready as {agent.account} on {config.project}", file=sys.stderr)
+    agent.wait()
+    return 0
 
 
 if __name__ == "__main__":
-    main()
+    raise SystemExit(main())