omp-conductor 0.5.2 → 0.5.3

package/README.md

@@ -8,7 +8,7 @@ tiers: first to an orchestrator session that can re-brief the worker, then to yo
 
 You label an issue. Within one tick the conductor claims it on the tracker, cuts a
 worktree, hands one omp worker a self-contained brief, and watches it to a green
-PR. The worker then stops: it never merges, tags, publishes or deploys.
+PR. The worker then stops: it does not merge, tag, publish or deploy.
 
 ### Scope
 
@@ -2028,7 +2028,7 @@ dispatcher. The brief is explicit about the boundary:
 | Add or update tests for behaviour it introduced. | Suppress a warning, delete an assertion, or special-case an input to make a check pass. |
 | Run the repo's configured cheap gates, each from its listed `cwd`, over the whole tree. | Run docker or image builds, production builds, browser/e2e suites, or the full test suite on the shared host — CI owns the heavy gates. |
 | Review its whole diff, then commit and publish once with `conductor_push`. One corrective push if CI is red. | Force-push, `git add -f`, or add AI/co-author attribution. There is no force path to reach: `conductor_push` publishes that run's branch fast-forward only and takes no other ref. Red twice means stop and report, not push a third time. |
-| Open a PR with `conductor_pr_create`, and poll CI to a verdict with `conductor_pr_status`. | Run `gh pr merge` — or reach `conductor_pr_merge`, which refuses a worker session mechanically. **A worker never merges** — absolute, whoever else holds the authority — so PRs land one at a time with a freshness re-check; two workers merging concurrently is how agent PRs clobber each other. Who *may* merge is the [`authority`](#configuration) answer, and it is never the worker. |
+| Open a PR with `conductor_pr_create`, and poll CI to a verdict with `conductor_pr_status`. | Run `gh pr merge` — or reach `conductor_pr_merge`, which refuses a worker session mechanically. **A worker is never authorised to merge**, whoever else holds the authority, so PRs land one at a time with a freshness re-check; two workers merging concurrently is how agent PRs clobber each other. Who *may* merge is the [`authority`](#configuration) answer, and it is never the worker. The verb refusal is mechanical; reaching for `gh` instead is a prohibition, and one that shows up as a merge absent from the [ledger](#the-ledger). |
 | Escalate: ambiguity, a cross-repo contract, a needed credential, a product or data-migration decision, a blocking existing test, CI red twice, or most of the wall-clock budget burned. | Cut a release, push a tag, publish to npm, edit a deployment pin, deploy, or touch infrastructure or secrets. `conductor_release` and `conductor_label` refuse a worker whatever `releasePolicy` says, because the check compares the caller against the configured holder rather than ruling one value out. The in-session tripwire still blocks recognised release/deploy tool calls early and audits the attempt, but it is [defence in depth](#the-mediated-verbs-126), not the gate. |
 
 The worker ends with a seven-line evidence report (issue, PR, observed head SHA,
@@ -2150,8 +2150,9 @@ every release shape under the most permissive config there is.
 
 Identity is never an argument. `project`, `run`, `issue` and the caller's role
 come from **which socket the call arrived on** plus the verified peer uid, and a
-request carrying any of those field names is refused outright, named. A worker
-on run X asking to merge run Y's PR is not merely wrong, it is unexpressible.
+request carrying any of those field names is refused outright, named. So a worker
+on run X cannot *ask* to merge run Y's PR: on its own channel that request is
+unexpressible, and a merge is refused for a worker session on any channel.
 
 ```
 <state dir>/verbs/                 daemon-owned, mode 0711
@@ -2294,9 +2295,12 @@ Known and deliberate in this version:
   than a silently dropped page. `delivered` means Telegram accepted an attempt,
   not that exactly one message exists. See
   [Report delivery](#report-delivery-the-outbox).
-- **Workers stop at green PRs.** They never merge, release or deploy. Those
-  actions default to a human, but setup may grant either to the orchestrator;
-  `authority` never grants them to a worker or the dispatch daemon.
+- **Workers stop at green PRs.** They are never authorised to merge, release or
+  deploy: those actions default to a human, and while setup may grant either to
+  the orchestrator, `authority` never grants them to a worker or the dispatch
+  daemon. The verbs refuse a worker mechanically. A session that shells out
+  instead is violating its brief rather than defeating a gate — sessions inherit
+  the daemon's credentials — and the missing ledger entry is the evidence.
 - **The worker gate is partial, and the orchestrator has none.** A worker's
   structured `write` / `edit` / `read` / `grep` / `glob` calls are gated to its
   worktree by an inline harness extension; `bash` is not, so a shell one-liner

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

package/src/config.ts

@@ -816,7 +816,7 @@ function normalizeRepos(parsed: unknown, label: string, problems: string[]): Rec
     const credentialInUrl = cloneUrlCredentialProblem(cloneUrl);
     if (credentialInUrl !== undefined) {
       problems.push(
-        `${label}: routing.repos.${key}.cloneUrl ${credentialInUrl} (#125). Use an SSH URL, or an https URL ` +
+        `${label}: routing.repos.${key}.cloneUrl ${credentialInUrl}. Use an SSH URL, or an https URL ` +
           `backed by the daemon's own credential helper.`,
       );
       continue;

package/src/daemon.ts

@@ -140,7 +140,9 @@ interface Deps {
    * Reads the connecting uid off a verb socket (#126). Resolved once at startup
    * so the mechanism is logged before the first socket exists; absent on a host
    * exposing no peer-credential call, where the `0600` socket under the
-   * daemon-owned `0711` parent is the whole boundary and `status` says so.
+   * daemon-owned `0711` parent is all that keeps other local accounts out, and
+   * `status` says so. It never told two sessions apart — they share the daemon's
+   * uid.
    */
   verbPeerReader?: PeerReader;
   /**
@@ -564,7 +566,7 @@ export async function settleWorktree(
     branch: string;
     /**
      * Publishes the run branch on the privileged side. Required rather than
-     * optional: since #125 the run's commits live in a repository of its own,
+     * optional: the run's commits live in a repository of its own,
      * so a removal that did not publish first would delete the only copy —
      * which is #121's data loss with one extra step. `undefined` is a visible
      * decision at the call site, never an omission.

package/src/gitops.ts

@@ -1,17 +1,20 @@
 /**
  * The daemon's own git and `gh` operations.
  *
- * Everything here runs as the daemon, with the operator's credentials, and it
- * is the only place in this package that spawns a credentialed process. That is
- * the whole organising idea: "what can reach the operator's `gh` credential" is
- * answered by this file's call sites rather than by auditing every `Bun.spawn`
- * in the tree.
+ * Everything here runs as the daemon, with the operator's credentials, and it is
+ * the only place this package **constructs** credential material for a git or
+ * `gh` call of its own. That is the organising idea: "what does the conductor
+ * itself do with the operator's credential" is answered by this file's call sites
+ * rather than by auditing every `Bun.spawn` in the tree.
  *
- * Sessions are not gated at the OS level — a worker is a child process of the
- * daemon and inherits its environment. What keeps a run's publication honest is
- * that the dispatcher performs it: a push or a pull request the daemon did not
- * make is a run it cannot account for. The mediated verbs route a worker's
- * intent through here so the settlement record and the branch cannot disagree.
+ * It is emphatically **not** a claim that nothing else can reach that credential.
+ * Sessions are child processes of the daemon and inherit its environment, so a
+ * session can reach whatever the daemon can — `omp.ts` spawns them and does not
+ * scrub anything. What keeps a run's publication accountable is that the
+ * dispatcher performs it: a push or a pull request the daemon did not make is a
+ * run it cannot account for, and is absent from the verb ledger. The mediated
+ * verbs route a worker's intent through here so the settlement record and the
+ * branch cannot disagree.
  */
 
 import { join } from "node:path";

package/src/omp.ts

@@ -111,12 +111,13 @@ const disposers = new WeakMap<AgentSessionLike, () => Promise<void>>();
  * Start one omp coding session **in this process**, rooted at `cwd`, with a
  * private agent registry and a file-backed transcript of its own.
  *
- * This is the far side of the boundary, not the dispatcher's entry point.
  * Production callers want {@link createSession}, which runs this same function
- * inside a child process under the run's own OS principal (#125); the only
- * caller of this one is `session-host.ts`, plus the tests that pin what it
- * builds. Calling it directly from the daemon puts the session back in the
- * credential-holding process, which is the thing #125 exists to stop.
+ * inside a **child process**; the only caller of this one is `session-host.ts`,
+ * plus the tests that pin what it builds. Calling it directly from the daemon
+ * puts the harness back inside the dispatcher, where a crash, a hang or an
+ * exhausted heap takes the whole fleet down with it and no `MemoryMax` bounds
+ * it — that is what the child process buys. It is not a security boundary: the
+ * child runs as the daemon's own user.
  *
  * `sessionDir` chooses the directory the harness writes that transcript into;
  * omitted, the harness picks its default location for `cwd`. Either way the

package/src/orchestrator.ts

@@ -84,13 +84,7 @@ export interface OrchestratorOpts {
   model?: string;
   releaseGrants?: ResolvedGrants;
   onReleaseBlocked?: (shape: ReleaseShape) => void;
-  /**
-   * The OS principal this session runs as (#125). Its own, distinct from every
-   * worker slot: the orchestrator reads the state directory and its briefs, and
-   * must have no read or write access to any run checkout — a property the
-   * adversarial probe asserts rather than assumes.
-   */
-  /** Control socket for the session child. See {@link OrchestratorOpts.boundary}. */
+  /** Control socket for the session child, beside its own working directory. */
   socketPath?: string;
   /**
    * The orchestrator's own verb socket (#126) — a third, distinct one, never

package/src/release-policy.ts

@@ -8,11 +8,12 @@
  * It was the only mechanism there was, and it was never the one anybody should
  * have had to rely on.
  *
- * What actually stops a release now is that the session cannot perform one. It
- * holds no credential (#125) and its only route to a mutation is the mediated
- * verbs, whose checks run in the daemon against the configured holder
- * (`verbs/server.ts`). A worker that talks its way past every regex below still
- * has nothing to push with.
+ * What actually stops a release now is that the daemon performs every one, and
+ * checks it first: the mediated verbs run their checks against the configured
+ * holder (`verbs/server.ts`), on the daemon's side of the socket. A worker that
+ * talks its way past every regex below has still not cut a release — and if it
+ * reaches for `gh` directly instead, the release is not in the ledger, which is
+ * the discrepancy an operator reads.
  *
  * It stays installed anyway, for the two things a tripwire is good at and a
  * boundary is not: it refuses *early*, in the session, with an explanation the

package/src/tracker/github.ts

@@ -5,13 +5,13 @@
  * daemon never handles a token itself: credentials stay in the user's keychain
  * or `gh` config and are never passed as argv, written to a file, or logged.
  *
- * That reachability is exactly what #125 confines. The environment this adapter
- * hands `gh` comes from `credentialedEnv()` — the one named construction site
- * of credential material in the daemon — so "which processes can reach the
- * operator's GitHub write credential" is answered by that function's call
- * sites, not by auditing every spawn in the tree. Sessions get the opposite
- * environment, and on a `per-run` host they are a different OS principal
- * entirely and could not use this credential even if they found it.
+ * The environment this adapter hands `gh` comes from `credentialedEnv()` — the
+ * one named construction site of credential material in the daemon — so "what in
+ * this package reaches the operator's GitHub credential" is answered by that
+ * function's call sites rather than by auditing every spawn in the tree. It is a
+ * legibility property, not a boundary: sessions run as the daemon's own user and
+ * can reach the same credential. What keeps a run's mutations accountable is
+ * that the daemon performs them, and records them.
  *
  * ponytail: shelling out to `gh` is the deliberate simplification. The ceiling
  * is per-call cost (one process spawn plus one TLS handshake per operation,
@@ -151,10 +151,9 @@ async function gh(argv: string[], stdin?: string): Promise<string> {
     stdin: new Blob([stdin ?? ""]),
     stdout: "pipe",
     stderr: "pipe",
-    // The privileged side of the boundary (#125). Explicit rather than
-    // inherited so that adding a credential-scrubbing default to this process
-    // could never silently break the tracker, and so that the grep for
-    // `credentialedEnv` finds this call.
+    // Explicit rather than inherited, so that a future change to this process's
+    // own environment could never silently break the tracker, and so that the
+    // grep for `credentialedEnv` finds this call.
     env: credentialedEnv(),
   });
 

package/src/types.ts

@@ -1324,9 +1324,9 @@ export const VERB_NAMES = [
   "conductor_pr_merge",
   "conductor_label",
   "conductor_release",
-  /** The one read verb. A session with no credential cannot otherwise observe
-   *  the pull request it just pushed, and "pushed-green" would go back to being
-   *  a claim a worker makes about itself. */
+  /** The one read verb. It answers with the merge gate's own verdict, so
+   *  "pushed-green" is the dispatcher's reading of the PR rather than a claim the
+   *  worker makes about itself from whatever it happened to run. */
   "conductor_pr_status",
 ] as const;
 

package/src/verbs/actions.ts

@@ -1,12 +1,12 @@
 /**
  * The privileged half of the verbs, wired to real commands (#126).
  *
- * This is the *only* module in the verb path that touches a credential, and it
- * runs in the daemon. Push and pull-request creation are delegated to the
- * credential boundary (#125) rather than re-shelled here, so there is one
- * implementation of "how does a run's work reach the remote" and it is the one
- * that scrubs the environment. The remaining verbs shell `gh` through
- * {@link credentialedEnv} for the same reason.
+ * This is the only module in the verb path that performs a mutation, and it runs
+ * in the daemon. Push and pull-request creation are delegated to `gitops.ts`
+ * rather than re-shelled here, so there is one implementation of "how does a
+ * run's work reach the remote" — fast-forward only, no force path. The remaining
+ * verbs shell `gh` through {@link credentialedEnv} for the same reason: one
+ * named construction site, so its call sites are the audit.
  *
  * Kept apart from `server.ts` deliberately: every policy check above it is
  * testable against the {@link VerbActions} interface with no repository, no
@@ -23,8 +23,8 @@ import type { ActionOutcome, ReleaseExecution, VerbActions } from "./server.ts";
  *
  * The three GitHub-shaped ones, and deliberately not `package-publish` or
  * `deploy`: the daemon holds a GitHub credential and nothing else — no npm
- * token, no registry login, no deploy key — and #125 exists to keep it that
- * way. A shape outside this list is refused by name in `server.ts` rather than
+ * token, no registry login, no deploy key — and that is deliberate. A shape
+ * outside this list is refused by name in `server.ts` rather than
  * attempted and reported as a command failure, because "we tried and it did not
  * work" and "we were never able to do this" are different answers and only one
  * of them tells an operator to go and do it themselves.
@@ -87,10 +87,10 @@ export function githubVerbActions(project: ProjectConfig, run: CommandRunner = s
   return {
     releasableShapes: GITHUB_RELEASABLE_SHAPES,
 
-    // Both of these are #125's, not this module's: they know the run's own
-    // repository layout and they are the two paths that must never see an
-    // ambient credential. Re-shelling `git push` here would be a second
-    // implementation of the one thing the credential boundary exists to own.
+    // Both live in `gitops.ts`, not here: they know the run's own repository
+    // layout, and they are the two paths whose fast-forward-only rule must have
+    // exactly one implementation. Re-shelling `git push` here would be a second
+    // one, and the second one is where a `--force` eventually appears.
     push: (target) => pushRunBranch(project, target),
 
     createPr: (target, opts) => openRunPr(project, target, opts),

package/src/verbs/client.ts

@@ -2,10 +2,9 @@
  * The child-side half of the mutation verbs (#126): a thin client, and nothing
  * else.
  *
- * This module runs **inside the untrusted per-run process**. Under #125 that is
- * a different OS principal with no access to the daemon's `gh` config, keychain
- * or SSH keys; before #125 it is the same user. Either way it is code the model
- * can read, and on a bad day rewrite — so it decides nothing:
+ * This module runs **inside the session process**, as the daemon's own user, so
+ * it is code the model can read and on a bad day rewrite — and it can reach the
+ * same credentials the daemon can. That is exactly why it decides nothing:
  *
  *  - **No policy branch.** It does not know what `authority.merge` says, which
  *    release shapes are granted, or whether the fleet is paused. Every answer
@@ -15,8 +14,8 @@
  *    There is nothing here to steal.
  *  - **No local fallback.** No socket means the verb fails, loudly, with an
  *    explanation. A client that fell back to `git push` when the daemon was
- *    unreachable would make the boundary optional, and an optional boundary is
- *    one that is missing precisely when something has gone wrong.
+ *    unreachable would leave the settlement record silently incomplete, and it
+ *    would do so precisely when something had already gone wrong.
  *
  * The identity fields are absent by construction rather than stripped: this
  * client has no project, run or role to send, because it was never told one.

package/src/verbs/server.ts

@@ -2,10 +2,10 @@
  * The privileged half of the mutation verbs (#126): every check, in the daemon.
  *
  * The child-side tool handler forwards arguments and renders an answer. It
- * holds no credential, evaluates no policy and writes no ledger entry, because
- * under #125 it runs inside the untrusted per-run process — anything it decided
- * would be decided by code the model can rewrite. Everything below runs on the
- * other side of the socket.
+ * evaluates no policy and writes no ledger entry, because it runs inside the
+ * session process — anything it decided would be decided by code the model can
+ * rewrite, and a session runs as the daemon's own user. Everything below runs on
+ * the other side of the socket, which is what makes the checks real.
  *
  * Four rules shape the order of the checks, and each is here because prose
  * alone did not hold it on `main`:
@@ -819,7 +819,7 @@ async function releaseVerb(
     return refuse(
       "release-shape-not-executable",
       `refused: this daemon cannot cut a ${shape}. It holds a GitHub credential and nothing else — no npm token, ` +
-        "no deploy key — and #125 exists to keep it that way. It can do " +
+        "no deploy key — and that is deliberate. It can do " +
         `${deps.actions.releasableShapes.join(", ")}. Escalate this one to your operator.`,
     );
   }
@@ -843,8 +843,8 @@ async function releaseVerb(
 
 
 /**
- * The one read verb, and the reason a credential-less worker can still report
- * honestly (#125 took `gh pr view` away from it).
+ * The one read verb, and the reason a worker reports a PR's real state rather
+ * than its own recollection.
  *
  * Reuses `Tracker.verifyPr`, so the answer is literally the merge gate's own
  * verdict rather than a second opinion assembled here — including the

package/src/verbs/socket.ts

@@ -361,14 +361,14 @@ export function peerVerdict(
     return {
       ok: true,
       basis: "socket-ownership",
-      why: "no uid was named for this socket, so the 0600 mode under the daemon-owned 0711 parent is the whole boundary",
+      why: "no uid was named for this socket, so the 0600 mode under the daemon-owned 0711 parent is all that keeps other local accounts out",
     };
   }
   if (peer === undefined) {
     return {
       ok: true,
       basis: "socket-ownership",
-      why: "this host exposes no peer credentials, so the 0600 socket under the daemon-owned 0711 parent is the whole boundary",
+      why: "this host exposes no peer-credential call, so the 0600 socket under the daemon-owned 0711 parent is all that keeps other local accounts out",
     };
   }
   if (peer.uid !== expected.uid) {

package/src/worktree.ts

@@ -6,11 +6,12 @@
  * once and refreshed, rather than a fresh full clone per issue: a module repo's
  * history is fetched one time and every later run pays only for the delta.
  *
- * **A run gets its own repository, not a linked worktree of the mirror, and
- * that is a security property rather than a preference (#125 1b).** A linked
- * worktree shares the mirror's common dir — refs, objects, index locks — so it
- * needs *write* access to it, which hands every run write access to every other
- * run's refs. Here the objects arrive read-only through git's alternates
+ * **A run gets its own repository, not a linked worktree of the mirror, and that
+ * is load-bearing rather than a preference.** A linked worktree shares the
+ * mirror's common dir — refs, objects, index locks — so every run would be
+ * writing into one store: concurrent runs contend on the same index lock, a
+ * `git gc` in one can pull objects from under another, and a run's refs are one
+ * `git update-ref` away from a sibling's. Here the objects arrive read-only through git's alternates
  * mechanism and the run's refs, index and commits live in its own git dir. The
  * documented residual is that a run can still *read* another run's objects out
  * of the shared store: bounded, same source, no write path, no credential, and
@@ -61,9 +62,9 @@ async function runGit(
     stdin: "ignore",
     stdout: "pipe",
     stderr: "pipe",
-    // Every git call in this module runs on the *privileged* side — the daemon
-    // provisioning, salvaging or publishing — so it goes through the one named
-    // construction site of credential material (#125). It also carries
+    // Every git call in this module is the daemon's own — provisioning,
+    // salvaging or publishing — so it goes through the one named construction
+    // site of credential material. It also carries
     // GIT_TERMINAL_PROMPT=0, because an unattended dispatcher must fail loudly
     // rather than block forever on a prompt nobody is there to answer.
     env: credentialedEnv(),
@@ -287,8 +288,8 @@ export async function ensureMirror(
  * git's own read-only borrowing mechanism — so provisioning still costs one
  * fetch of the delta rather than a full clone, exactly as the linked worktree
  * it replaces did. What changed is who can write what: the run's refs, index
- * and commits are its own, and nothing it does can reach a sibling run's refs
- * or the mirror (#125 1b).
+ * and commits are its own, and no ordinary git operation in the checkout reaches
+ * a sibling run's refs or the mirror.
  *
  * `origin` is deliberately the real clone URL and not the mirror path. Pointing
  * it at the mirror would make a worker's ordinary `git push origin HEAD`
@@ -553,9 +554,9 @@ function parseCachedNameStatus(raw: string): { files: string[]; newPaths: string
  * commit and re-runs its checks. That is the price of work outliving its host.
  *
  * `publish` is a **required** parameter rather than an optional one with a
- * no-op default, and that is the whole design. The salvage commit no longer
- * pushes for itself: the run's repository holds no credential (#125), so the
- * network hop is the daemon's, through `pushRunBranch`. A defaulted parameter
+ * no-op default, and that is the whole design. The salvage commit does not push
+ * for itself: the network hop is the daemon's, through `pushRunBranch`, so the
+ * sha that reaches the remote is the sha the dispatcher recorded. A defaulted parameter
  * is how a future call site silently stops publishing salvaged work and nobody
  * finds out until the host that held it is gone — which is #121's failure with
  * one extra step. Passing `undefined` is allowed, and is a visible decision at
@@ -676,7 +677,8 @@ export async function removeWorktree(
   if (existsSync(worktreePath)) {
     // A run repo is a plain directory now, so removal is a plain removal — but
     // the `worktree remove` is still attempted first, because a fleet upgrading
-    // into #125 has live trees that ARE linked worktrees of this mirror, and
+    // from a release that used linked worktrees has live trees that ARE linked
+    // worktrees of this mirror, and
     // deleting one of those without deregistering it leaves the mirror
     // believing the branch is still checked out. It refuses `worktree add` and,
     // worse, refuses to delete the branch at cleanup. The failure is expected