@agent-relay/factory 0.1.1 → 0.1.2

package/README.md

@@ -1,248 +1,189 @@
-# @agent-relay/factory
+# Agent Workforce Factory
 
-The autonomous issue factory: a loop that discovers Linear issues, triages them,
-dispatches agents to implement fixes, opens PRs, drives them to completion through
-a merge gate, and closes the issues — all under a hard safety scope.
+**Turn issues into reviewed pull requests, automatically.**
 
-The package publishes the **`factory`** CLI (`bin/factory.mjs`). From a repo
-checkout, build first and invoke the CLI through the package bin:
+Point the factory at your ticketing system (Linear, GitHub, Shortcut, Asana etc) and it does the loop a human
+otherwise babysits: it discovers the issues that are ready, decides how to tackle
+each one, spawns coding agents to implement and review the change, opens a PR,
+drives it through a merge gate, and closes the issue — all inside a safety scope
+you define, so it only ever acts on work you've explicitly opted in.
 
-```bash
-npm ci
-npm run build
+## Why use it
+
+- **Clear the small-but-real backlog.** The well-scoped fixes and chores that pile
+  up get done without a person shepherding each one.
+- **It only touches what you allow.** A safety gate (title prefix + team) means
+  the factory dispatches *exactly* the issues you mark for it and ignores
+  everything else — opt-in by construction.
+- **Real PRs, not blind merges.** Every change goes through an implement → review
+  → merge-gate flow and lands as a normal PR. It defaults to *never* auto-merging
+  until you turn that on.
+- **You stay in the loop.** It posts threaded status to Slack and can ask a human
+  for clarification mid-task when an issue is ambiguous.
+- **Drop in by label.** Hand it new work just by labeling a Linear or GitHub
+  issue — no new tooling in your day-to-day.
+
+A good fit when you have a steady stream of scoped issues and want them turned
+into PRs without standing up your own agent orchestration.
+
+## How it works
 
-node bin/factory.mjs factory <action> --config <cfg>
 ```
+discover ready issues → triage (how to do it) → dispatch agents (implement + review)
+        → open PR → merge gate → close issue
+```
+
+Each step is gated by your config and the safety scope. Issues outside the scope
+are pulled but never dispatched.
 
-Once installed from npm, the ergonomic form is:
+## Install
 
 ```bash
-factory factory <action> [options]
+npm install @agent-relay/factory
 ```
 
-> **Heads-up:** every `factory` action requires `--config <path>` (see
-> [Configuration](#configuration)). Commands fail fast with
-> `factory commands require --config <path>` if it's missing.
+The factory talks to a relay broker through the **`agent-relay`** sidecar; install
+and sign in to that separately (it's a peer of this package). Once installed, the
+CLI is available as `factory`:
 
----
+```bash
+factory factory run-once --config ./factory.config.json --dry-run
+```
+
+> Yes, `factory factory` — the `factory` CLI groups its commands under a `factory`
+> subcommand. From a source checkout instead of an npm install, run
+> `npm ci && npm run build` first, then `node bin/factory.mjs factory <action> …`.
 
 ## Quick start
 
-```bash
-# One-shot batch — discover + triage + dispatch one cycle, then exit.
-# Add --dry-run to plan without writing or spawning anything.
-factory factory run-once --config ./factory.config.json --dry-run
+1. **Write a minimal config** (`factory.config.json`). Only `workspaceId` and a
+   repo route are required:
 
-# Live daemon — subscription-driven; runs until SIGINT/SIGTERM.
-factory factory start --mode live --config ./factory.config.json
-```
+   ```json
+   {
+     "workspaceId": "your-workspace-id",
+     "repos": {
+       "byLabel": { "pear": "AgentWorkforce/pear" },
+       "clonePaths": { "AgentWorkforce/pear": "/path/to/your/pear/checkout" },
+       "default": "AgentWorkforce/pear"
+     }
+   }
+   ```
+
+   `workspaceId` is your relay workspace; `repos.byLabel` maps a Linear label to a
+   repo; `clonePaths` tells the agent where that repo lives locally so it has
+   somewhere to make changes.
+
+2. **Plan a cycle without touching anything** — `--dry-run` discovers and triages
+   but writes nothing and spawns no agents:
+
+   ```bash
+   factory factory run-once --config ./factory.config.json --dry-run
+   ```
+
+3. **Let it work for real:**
+
+   ```bash
+   # One discovery→dispatch cycle, then exit.
+   factory factory run-once --config ./factory.config.json
+
+   # Or run continuously as a daemon (the production form).
+   factory factory start --mode live --config ./factory.config.json
+   ```
+
+> **Pulled some issues but dispatched none?** That's the safety gate doing its
+> job — the issues are real but outside your scope. See
+> [Tell it what to work on](#tell-it-what-to-work-on).
 
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `factory run-once` | One discovery→triage→dispatch cycle, then exit. Honors `--dry-run`. |
-| `factory loop` | Bounded multi-iteration loop (`loop.maxIterations`), then exit. |
-| `factory start --mode live` | Long-lived daemon. Subscription-driven; writes + refreshes a loop heartbeat. The production entrypoint. |
-| `factory status` | Print the in-memory factory status as JSON. |
-| `factory loop-status` | Read the heartbeat file and report liveness (stale vs. alive). |
-| `factory kill-loop` | Send SIGTERM to the daemon PID recorded in the heartbeat. |
-| `factory reap-orphans` | Crash backstop: reap orphaned agent pairs whose heartbeat is stale. Run as a scheduled job. |
-| `factory triage <KEY\|path>` | Triage a single issue and print the decision. |
-| `factory dispatch <KEY\|path>` | Triage + dispatch a single issue. Honors `--dry-run`. |
-| `factory close-probe <PR#> --repo <owner/repo> --issue <KEY>` | Manually close a synthetic E2E probe PR. |
-
-Global options (accepted anywhere in the args): `--config <path>`,
-`--dry-run`, `--backend <internal\|relay>`.
+| `factory run-once` | One discover→triage→dispatch cycle, then exit. Honors `--dry-run`. |
+| `factory loop` | A bounded multi-iteration loop, then exit. |
+| `factory start --mode live` | Long-lived daemon — the production entrypoint. Runs until you stop it. |
+| `factory status` | Print current factory status as JSON. |
+| `factory triage <KEY\|path>` | Triage one issue and print the decision. |
+| `factory dispatch <KEY\|path>` | Triage + dispatch one issue. Honors `--dry-run`. |
+| `factory canary <KEY\|path>` | Assert a known "Ready for Agent" issue is dispatch-ready by the real dry-run triage path. Prints `{ok,issue,status,reason}`; exits non-zero (with the skip reason) if it isn't. |
 
-## The 2-process production model
+Global options work anywhere in the args: `--config <path>`, `--dry-run`,
+`--backend <internal|relay>`. The internal backend reuses a relay broker that's
+already running for your workspace, and starts one if none is.
 
-The factory runs as **two** coordinated processes (see issue #321 §4):
+(There are a few more operational commands — `loop-status`, `kill-loop`,
+`reap-orphans`, `close-probe` — for running the daemon in production.)
 
-1. **Live daemon** — `factory factory start --mode live --config <live>`. Drives the
-   loop and refreshes a heartbeat file.
-2. **External reaper** — a *scheduled* `factory factory reap-orphans --config <live>`
-   that acts as a crash backstop, cleaning up orphaned agent pairs if the daemon dies.
+### Scheduled sync-fidelity canary
 
-> **HARD precondition:** the reaper **must** use the **same `--config`** as the
-> live daemon. A mismatched config reaps nothing *and* leaves the backstop broken
-> (the coupling is load-bearing — see §7 of issue #321).
+`factory canary` is the regression detector for upstream sync drift: if a synced
+issue stops carrying enough state to be dispatchable (e.g. the Linear sync
+regresses to records without `state.id`), a known-good issue flips from
+dispatch-ready to skipped. Run it on a schedule against a standing "Ready for
+Agent" canary issue and alert on failure.
 
-### Other operating preconditions (issue #321 §7)
+`scripts/factory-canary.sh` wraps the command for cron/launchd: it runs from your
+deployment dir (reusing the running relay broker), bounds a hung run, and posts a
+Slack alert via `FACTORY_CANARY_SLACK_WEBHOOK` on failure. See
+`scripts/com.agentrelay.factory-canary.plist.example` for an every-6h launchd
+template.
 
-- **`gh`-authenticated environment.** The gh-resolver is completion-load-bearing
-  while the cloud GitHub→mount PR-sync is degraded; a `gh` auth drop halts completion.
-- Run the real binary path (`factory` / `node bin/factory.mjs`), not a shim.
+## Tell it what to work on
 
-## Configuration
+Two ways to hand the factory an issue — both are just labeling/titling, nothing
+to install:
 
-Pass a JSON file via `--config`. The full schema (with every default) lives in
-[`src/config/schema.ts`](src/config/schema.ts), validated by Zod at load time —
-an invalid config fails fast with a field-level error.
+| Source | What you do | Result |
+|---|---|---|
+| **Linear** | Title it `[factory] <task>`, set the team + a repo label, move it to **Ready for Agent** | dispatched directly |
+| **GitHub** | Add the **`factory`** label to the issue | mirrored into a `[factory]` Linear issue, then dispatched |
 
-The file is either a bare config object, or a `{ "factoryConfig": { … } }`
-wrapper (the wrapper form also allows a sibling `fixtureFiles` map — see
-[Fixture mode](#fixture-mode-offline-testing)).
+The **safety gate** is what keeps this opt-in: by default the factory only
+dispatches an issue whose **title starts with your configured prefix** *and* whose
+**team matches** your configured team. Everything else is ignored. Loosen it
+deliberately — it's the main guardrail.
 
-### Minimal config
+> Tip: `[factory-e2e]` is reserved for the factory's own self-test soak (its PRs
+> auto-close). For real work you want to keep, use the `[factory]` prefix.
 
-Only two fields are required — `workspaceId` and `repos.byLabel`. Everything else
-has a default:
+## Run it as a fleet node (optional)
 
-```json
-{
-  "workspaceId": "your-workspace-id",
-  "repos": {
-    "byLabel": { "pear": "AgentWorkforce/pear" },
-    "default": "AgentWorkforce/pear"
-  }
-}
-```
+The package also ships a fleet **node definition** so a machine can advertise
+`spawn:claude` / `spawn:codex` / `workflow:run` to the cloud and run agents in the
+checkouts it owns:
 
-### Complete annotated config
-
-A realistic live config, showing the fields you'll actually want to set (comments
-are illustrative — strip them; JSON has no comments):
-
-```jsonc
-{
-  // relayfile cloud mount workspace id — the workspace whose /linear and /slack
-  // trees the factory reads. Same id the Pear app uses for this workspace.
-  "workspaceId": "ws_abc123",
-
-  // Which Linear issues to pull. Empty arrays = no filter on that dimension.
-  // Values are Linear team keys / project names / label names / assignee ids.
-  "subscription": {
-    "teams": ["AR"],
-    "labels": ["pear"],
-    "projects": [],
-    "assignees": []
-  },
-
-  // Issue → repo routing. Precedence (first match wins):
-  //   byLabel  →  byProject  →  keywordRules (regex on title/desc)  →  default
-  // No match and no default → the issue is escalated, never dispatched.
-  "repos": {
-    "byLabel":  { "pear": "AgentWorkforce/pear", "cloud": "AgentWorkforce/cloud" },
-    "byProject": { "Pear": "AgentWorkforce/pear" },
-    "keywordRules": [{ "pattern": "relayfile|mount", "repo": "AgentWorkforce/relayfile" }],
-    // Where each repo is checked out locally for the agent to work in.
-    "clonePaths": { "AgentWorkforce/pear": "/Users/you/Projects/pear" },
-    "default": "AgentWorkforce/pear"
-  },
-
-  // SAFETY GATE — an issue is only dispatched if BOTH hold (see below):
-  "safety": {
-    "requireTitlePrefix": "[factory-e2e]",
-    "requireTeamKey": "AR"
-  },
-
-  "batchSize": 5,                       // max issues dispatched per cycle
-  "dispatch": { "maxAttempts": 2, "errorCooldownMs": 60000 },
-  "mergePolicy": "never",               // see mergePolicy note below
-  "models": {                           // optional per-role model overrides
-    "implementer": "claude-opus-4-8",
-    "reviewer": "claude-opus-4-8",
-    "triage": "claude-haiku-4-5-20251001"
-  },
-  "slack": { "channel": "C0B902XR6PN" },   // optional threaded status updates
-  "loop": {
-    "heartbeatPath": "/tmp/factory-run/factory-loop-heartbeat.json",
-    "registryPath":  "/tmp/factory-run/factory-loop-registry.json",
-    "heartbeatStaleMs": 60000
-  }
-}
+```bash
+agent-relay fleet serve @agent-relay/factory/node
 ```
 
-### Where the values come from
-
-- **`workspaceId`** *(required)* — the relayfile cloud mount workspace id for this
-  workspace (the same one the Pear app mounts `/linear` and `/slack` under).
-- **`repos.byLabel`** *(required)* — map a Linear label → `owner/repo`. The other
-  routing maps are optional; **precedence is `byLabel` → `byProject` →
-  `keywordRules` → `default`**, else the issue is escalated (never dispatched).
-- **`repos.clonePaths`** — `owner/repo` → local working-tree path. Without an entry
-  the agent has nowhere to apply changes for that repo, so set it for every repo
-  you actually dispatch to.
-- **`stateIds`** — the Linear workflow-state UUIDs for `readyForAgent`,
-  `agentImplementing`, `done`, `inPlanning`, and optionally `humanReview`.
-  Defaults cover the **AR team's** core states (see
-  [`src/constants/linear.ts`](src/constants/linear.ts)). `humanReview` is
-  intentionally omitted from the schema default so legacy configs fall back to
-  direct-to-Done behavior unless they opt into a review state. If you run against
-  a different Linear team, override the state UUIDs with that team's values (read
-  them from the Linear API / the issue JSON's `state.id`).
-- **`safety`** — the scope gate (below). Defaults `[factory-e2e]` + team `AR`;
-  GitHub issue mirrors created by the factory use `[factory]` and are accepted
-  by the same gate.
-
-### The safety gate (what actually gets dispatched)
-
-`isInFactoryScope` ([`src/safety/factory-scope.ts`](src/safety/factory-scope.ts))
-dispatches an issue only when **both** are true:
-
-1. The issue **title starts with `safety.requireTitlePrefix`** — exactly
-   `[factory-e2e]`, or `[factory-e2e] <rest>` by default. Factory-created
-   GitHub mirrors titled `[factory] <GitHub title>` are also accepted. Anything
-   else is out of scope.
-2. The issue's **team key equals `safety.requireTeamKey`** (`AR`).
-
-This is why `factory run-once` may pull issues but dispatch none — they're real
-issues that fall outside the gate. Loosen the gate deliberately; it's the primary
-guardrail against the factory acting on issues it shouldn't.
-
-> **⚠️ `[factory-e2e]` is the synthetic self-test prefix — its PRs auto-close.**
-> The default `requireTitlePrefix` is `[factory-e2e]`, which is *also* the marker
-> the factory uses to identify synthetic E2E soak issues. A `[factory-e2e]`-titled
-> issue's PR is **auto-closed, never merged** (`#isSyntheticProbeIssue`) — great
-> for self-test soaks, wrong for real work. **For real issues you want to keep,
-> set `requireTitlePrefix` to `[factory]`** and title issues `[factory] <task>`;
-> reserve `[factory-e2e]` for the soak. The synthetic check matches `[factory-e2e]`
-> exactly, so `[factory]` issues are not auto-closed. (Note: `[factory-e2e]` does
-> **not** satisfy a `[factory]` gate — the prefixes differ at the `]`/`-`, so don't
-> mix them.)
-
-### Ingesting GitHub issues (label `factory`)
-
-The factory also picks up **GitHub issues labeled `factory`** (case-insensitive),
-read from the mounted `/github/repos/**` tree (pushed in by the GitHub→relayfile
-sync — no API polling). For each, it creates one Linear mirror titled
-`[factory] <GitHub title>` in **Ready for Agent**, routes it via `repos.byLabel`,
-then dispatches it like any other Linear issue. Mirrors are deduped (one per
-GitHub issue) and set to `done` when the GitHub issue closes.
-
-So to hand the factory a GitHub issue you **just add the `factory` label** — you
-do **not** put `[factory]` in the GitHub title (the factory adds that to the
-Linear mirror). This is the cross-repo path: label, say, a `relay` repo issue
-`factory` and it flows in, routed to `AgentWorkforce/relay`.
+It reads its node config from `./factory.node.json` (or `$FACTORY_NODE_CONFIG`).
+Prefer to build the definition yourself?
 
-| Source | What you do | Result |
-|---|---|---|
-| Linear (direct) | title `[factory] <task>`, team AR, label = repo, Ready for Agent | dispatched directly |
-| GitHub (any configured repo) | add the **`factory` label** | mirrored to a `[factory]` Linear issue, then dispatched |
+```ts
+import { createFactoryNodeDefinition, readFactoryNodeConfigSync } from '@agent-relay/factory'
 
-### Other notable fields (defaults in parentheses)
+export default createFactoryNodeDefinition({ config: readFactoryNodeConfigSync() })
+```
 
-- `mergePolicy` (`never`) — `never` keeps PRs open; `on-green-with-review` enables
-  autonomous merge on green + approved review. **Stays `never` until the flip is
-  thrown** (issue #321 §6).
-- `loop.heartbeatPath` / `loop.registryPath` / `loop.heartbeatStaleMs` (`60000`) —
-  daemon/reaper coupling (the reaper must point at the same paths via the same
-  `--config`).
-- `batchSize` (`5`), `dispatch.maxAttempts` (`2`), `dispatch.errorCooldownMs`
-  (`60000`), `models.{implementer,reviewer,triage}`, `slack.channel`,
-  `subscription.*`, `liveSubscription.*`, `stateIds.*`.
+## Configuration
 
-### Fixture mode (offline testing)
+Pass a JSON file via `--config`. Beyond the two required fields above, useful
+knobs include issue **routing** (`repos.byLabel` / `byProject` / `keywordRules` /
+`default`), the **safety gate** (`safety.requireTitlePrefix`, `safety.requireTeamKey`),
+`mergePolicy` (defaults to `never`), per-role **model** overrides, and an optional
+**Slack** channel for status threads.
 
-If the config (or a `{ "factoryConfig": …, "fixtureFiles": … }` wrapper) includes a
-`fixtureFiles` map, the CLI swaps in fake fleet + mount clients backed by those files —
-no cloud, no real agents. See [`test/fixtures/factory.config.json`](test/fixtures/factory.config.json).
+The full schema — every field and default — is validated by Zod at load time, so
+an invalid config fails fast with a field-level error. See
+[`src/config/schema.ts`](src/config/schema.ts) for the authoritative reference,
+and [`test/fixtures/factory.config.json`](test/fixtures/factory.config.json) for a
+worked example (including offline fixture mode).
 
 ## Notes
 
-- The daemon is headless by design. Pear consumes this package and may expose its
-  own `pear factory ...` passthrough, but this repository's published CLI is
-  `factory`.
-- Build output lives in `dist/`; `npm pack --dry-run` should include only
-  `dist/`, `bin/factory.mjs`, `package.json`, and `README.md`.
+- The daemon is headless by design; tools like Pear can consume this package and
+  wrap it, but the published CLI is `factory`.
+- The published `dist/` is plain ESM, runnable directly by Node (`node bin/factory.mjs`)
+  and importable by ESM consumers.
+- For production operation (the live-daemon + reaper backstop model, heartbeats,
+  and `gh`-auth preconditions), see the operations notes alongside the config schema.

package/dist/cli/fleet.d.ts

@@ -1,9 +1,10 @@
-import { createFactory, createFleet, type Capability, type Factory, type FactoryConfig, type FleetBackend, type FleetClient, type GhRunner, type FactoryStateResolution, type MountClient, type ProbeCloser, type RelayfileCloudMountClientConfig, type ResolvedFactoryWorkspace } from '../index';
+import { createFactory, createFleet, ensureRelayBroker, type Capability, type Factory, type FactoryConfig, type FleetBackend, type FleetClient, type GhRunner, type FactoryStateResolution, type MountClient, type ProbeCloser, type RelayfileCloudMountClientConfig, type ResolvedFactoryWorkspace } from '../index.js';
 interface FleetCliDeps {
     fleet?: FleetClient;
     mount?: MountClient;
     createFactory?: typeof createFactory;
     createFleet?: typeof createFleet;
+    ensureRelayBroker?: typeof ensureRelayBroker;
     cloudMountFromConfig?: (config?: RelayfileCloudMountClientConfig) => Promise<MountClient>;
     resolveWorkspace?: () => Promise<ResolvedFactoryWorkspace>;
     resolveStates?: (mount: MountClient, config: FactoryConfig) => Promise<FactoryStateResolution>;
@@ -49,6 +50,9 @@ type ParsedCommand = {
     kind: 'factory';
     action: 'start';
     mode?: 'live';
+} | {
+    kind: 'factory-canary';
+    issue: string;
 } | {
     kind: 'factory-triage';
     issue: string;

package/dist/cli/fleet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fleet.d.ts","sourceRoot":"","sources":["../../src/cli/fleet.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fleet.d.ts","sourceRoot":"","sources":["../../src/cli/fleet.ts"],"names":[],"mappings":"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"}

package/dist/cli/fleet.js

@@ -1,9 +1,9 @@
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { ensureLocalMount } from '../mount/local-mount-preflight';
-import { FactoryConfigSchema, RelayfileCloudMountClient, checkFactoryLoopLiveness, closeProbePr, createFactory, createFleet, defaultGhRunner, isInFactoryScope, parseLinearIssue, reapFactoryOrphansOnce, readFactoryLoopHeartbeat, resolveFactoryStates, resolveFactoryWorkspace, } from '../index';
-import { FakeFleetClient, FakeMountClient } from '../testing';
+import { ensureLocalMount } from '../mount/local-mount-preflight.js';
+import { FactoryConfigSchema, RelayfileCloudMountClient, checkFactoryLoopLiveness, closeProbePr, createFactory, createFleet, ensureRelayBroker, defaultGhRunner, isInFactoryScope, readLinearIssueWithCanonicalFallback, reapFactoryOrphansOnce, readFactoryLoopHeartbeat, resolveFactoryStates, resolveFactoryWorkspace, } from '../index.js';
+import { FakeFleetClient, FakeMountClient } from '../testing/index.js';
 export async function runFleetCli(argv, deps = {}) {
     const out = deps.stdout ?? process.stdout;
     const err = deps.stderr ?? process.stderr;
@@ -53,6 +53,7 @@ export async function runFleetCli(argv, deps = {}) {
                 writeJson(out, { released: command.name });
                 return 0;
             case 'factory':
+            case 'factory-canary':
             case 'factory-triage':
             case 'factory-dispatch': {
                 if (!loaded)
@@ -112,7 +113,7 @@ export function parseFleetCommand(args) {
     if (verb === 'spawn') {
         const [capability, ...flags] = rest;
         if (!isCapability(capability)) {
-            throw new Error('fleet spawn requires capability spawn:codex or spawn:claude');
+            throw new Error('fleet spawn requires capability spawn:codex, spawn:claude, or workflow:run');
         }
         const parsed = parseFlags(flags);
         return {
@@ -246,6 +247,12 @@ async function runFactoryCommand(command, factory, mount, fleet, config, globals
         }
         return 0;
     }
+    if (command.kind === 'factory-canary') {
+        const report = await factory.runOnce({ dryRun: true });
+        const result = evaluateFactoryCanary(report, command.issue);
+        writeJson(out, result);
+        return result.ok ? 0 : 1;
+    }
     const issue = await readIssueArg(mount, command.issue);
     const decision = await factory.triageIssue(issue);
     if (command.kind === 'factory-triage') {
@@ -263,6 +270,11 @@ function parseFactoryCommand(args) {
     if (action === 'run-once' || action === 'loop' || action === 'status' || action === 'loop-status' || action === 'kill-loop' || action === 'reap-orphans') {
         return { kind: 'factory', action };
     }
+    if (action === 'canary') {
+        if (!issueOrPr)
+            throw new Error('fleet factory canary requires an issue key or path');
+        return { kind: 'factory-canary', issue: issueOrPr };
+    }
     if (action === 'triage') {
         if (!issueOrPr)
             throw new Error('fleet factory triage requires an issue key or path');
@@ -284,6 +296,41 @@ function parseFactoryCommand(args) {
     }
     throw new Error(`Unknown fleet factory action: ${action ?? ''}`);
 }
+// Canary: assert a known "Ready for Agent" issue is classified dispatch-ready
+// by the REAL triage path against the live mount. This is the regression
+// detector for sync-fidelity drift (sparse records / stub primaries) — if it
+// flips to skipped, the adapter/sync contract broke. Exits non-zero with the
+// offending skip reason so CI/cron can alert.
+function evaluateFactoryCanary(report, issueArg) {
+    const wantKey = issueArg.startsWith('/')
+        ? (issueArg.split('/').at(-1) ?? '').replace(/\.json$/u, '').split('__')[0]
+        : issueArg;
+    const matches = (ref) => ref.key === wantKey;
+    if (report.dispatched.some((d) => matches(d.issue))) {
+        return { ok: true, issue: wantKey, status: 'dispatched' };
+    }
+    if (report.triaged.some((t) => matches(t.issue))) {
+        return { ok: true, issue: wantKey, status: 'triaged' };
+    }
+    const skipped = report.skipped.find((s) => matches(s.issue));
+    if (skipped) {
+        return { ok: false, issue: wantKey, status: 'skipped', reason: skipped.reason };
+    }
+    if (!report.pulled.some(matches)) {
+        return {
+            ok: false,
+            issue: wantKey,
+            status: 'not-found',
+            reason: 'issue was not enumerated from the mount (sync may be missing it or it is in-flight)',
+        };
+    }
+    return {
+        ok: false,
+        issue: wantKey,
+        status: 'unknown',
+        reason: 'issue pulled but neither dispatched, triaged, nor skipped',
+    };
+}
 function parseFactoryStartFlags(args) {
     let mode;
     const flags = args.filter((arg) => Boolean(arg));
@@ -315,11 +362,36 @@ async function buildFleet(globals, loaded, deps) {
         return deps.fleet;
     if (globals.backend === 'internal' && hasExplicitFixtureFiles(loaded))
         return new FakeFleetClient();
-    return (deps.createFleet ?? createFleet)({
-        backend: globals.backend,
-        cwd: process.cwd(),
-        connectionPath: resolveBrokerConnectionPath(process.cwd()),
-    });
+    const cwd = process.cwd();
+    const connectionPath = resolveBrokerConnectionPath(cwd);
+    // An injected createFleet owns fleet construction entirely (tests), so skip the
+    // real broker bootstrap.
+    if (deps.createFleet) {
+        return deps.createFleet({ backend: globals.backend, cwd, connectionPath });
+    }
+    // The internal backend talks to a relay broker. Reuse the one already running
+    // for this workspace, or start one if none is up, so `factory <run-once|loop>`
+    // works without a separately-started broker. The relay backend manages its own
+    // connection and needs no local broker.
+    if (globals.backend === 'internal') {
+        const stderr = deps.stderr ?? process.stderr;
+        const logger = {
+            info: (message, ...args) => stderr.write(`${message}${formatLogArgs(args)}\n`),
+        };
+        const { client, started } = await (deps.ensureRelayBroker ?? ensureRelayBroker)({ cwd, connectionPath, logger });
+        return createFleet({ backend: 'internal', cwd, connectionPath }, { harnessClient: client, ownsBroker: started });
+    }
+    return createFleet({ backend: globals.backend, cwd, connectionPath });
+}
+function formatLogArgs(args) {
+    if (args.length === 0)
+        return '';
+    try {
+        return ` ${args.map((arg) => (typeof arg === 'string' ? arg : JSON.stringify(arg))).join(' ')}`;
+    }
+    catch {
+        return '';
+    }
 }
 export function resolveBrokerConnectionPath(startCwd = process.cwd()) {
     let current = resolve(startCwd);
@@ -365,7 +437,7 @@ async function isAllowedFactoryDraft(path, content, opts, mount, config) {
     if (nestedComment) {
         const issuePath = `/linear/issues/${nestedComment[1]}.json`;
         try {
-            const issue = parseLinearIssue(issuePath, (await mount.readFile(issuePath)).content);
+            const issue = await readLinearIssueWithCanonicalFallback(mount, issuePath);
             return isInFactoryScope(issue, config.safety);
         }
         catch {
@@ -376,7 +448,7 @@ async function isAllowedFactoryDraft(path, content, opts, mount, config) {
         if (isInFactoryScope(scopeIssueFromDraftContent(content), config.safety))
             return true;
         try {
-            const issue = parseLinearIssue(path, (await mount.readFile(path)).content);
+            const issue = await readLinearIssueWithCanonicalFallback(mount, path);
             return isInFactoryScope(issue, config.safety);
         }
         catch {
@@ -397,8 +469,7 @@ const scopeIssueFromDraftContent = (content) => ({
 });
 async function readIssueArg(mount, issueArg) {
     const path = issueArg.startsWith('/') ? issueArg : await findIssuePath(mount, issueArg);
-    const { content } = await mount.readFile(path);
-    return parseLinearIssue(path, content);
+    return readLinearIssueWithCanonicalFallback(mount, path);
 }
 async function findIssuePath(mount, key) {
     const matches = (await mount.listTree('/linear/issues/'))
@@ -443,10 +514,10 @@ function flushWritable(stream) {
     });
 }
 function isCapability(value) {
-    return value === 'spawn:codex' || value === 'spawn:claude';
+    return value === 'spawn:codex' || value === 'spawn:claude' || value === 'workflow:run';
 }
 function defaultAgentName(capability, now) {
-    return `fleet-${capability.replace('spawn:', '')}-${now}`;
+    return `fleet-${capability.replace('spawn:', '').replace(':', '-')}-${now}`;
 }
 export function installFactoryStopSignalHandlers(factory, opts = {}) {
     const exit = opts.exit ?? ((code) => process.exit(code));