loreli 0.0.0 → 2.0.0

package/packages/action/src/index.js

@@ -0,0 +1,684 @@
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Workflow } from 'loreli/workflow';
+import { pathFor, reset } from 'loreli/workspace';
+import { pick } from 'loreli/identity';
+import { logger } from 'loreli/log';
+import { mark, has, parse } from 'loreli/marker';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const log = logger('action');
+
+/**
+ * Build workspace context used to regenerate MCP scaffolding after branch resets.
+ *
+ * The context mirrors what factory/create uses at spawn time. Reusing the same
+ * shape ensures reset() can restore CLI-facing config files that generic skills
+ * rely on (`loreli tools ...`) without embedding ad-hoc backend assumptions.
+ *
+ * @param {object} orchestrator - Orchestrator instance.
+ * @param {string} repo - Repository in "owner/name" format.
+ * @param {string} agent - Agent identity name.
+ * @returns {object}
+ */
+function workspaceContext(orchestrator, repo, agent) {
+  const context = {
+    session: orchestrator.sessionId,
+    agent,
+    repo,
+    home: orchestrator.storage?.home,
+    denied: orchestrator.cfg?.get?.('agents.disallowedTools') ?? []
+  };
+
+  if (process.env.GITHUB_TOKEN) context.token = process.env.GITHUB_TOKEN;
+
+  return context;
+}
+
+/**
+ * Build reset()/checkout() options that preserve workspace scaffolding.
+ *
+ * @param {object} orchestrator - Orchestrator instance.
+ * @param {string} repo - Repository in "owner/name" format.
+ * @param {string} agent - Agent identity name.
+ * @returns {{context: object, descriptors: object[]}}
+ */
+function workspaceOptions(orchestrator, repo, agent) {
+  const context = workspaceContext(orchestrator, repo, agent);
+  const descriptors = orchestrator.backendRegistry?.scaffoldAll?.(context) ?? [];
+  return { context, descriptors };
+}
+
+/**
+ * Action workflow for Loreli's orchestration pipeline.
+ *
+ * Manages action agents — issue claiming, work dispatch,
+ * and rework from human feedback.
+ * Also owns the claim protocol (claim/claimant) that was previously
+ * in the hub package.
+ *
+ * @extends Workflow
+ */
+export class ActionWorkflow extends Workflow {
+  /** @type {string} Agent role this workflow manages. */
+  static role = 'action';
+
+  /** @type {string} Mustache template path for action prompts. */
+  static template = join(__dirname, '..', 'prompts', 'action.md');
+
+  /**
+   * Guard flag to prevent overlapping dispatch runs.
+   * The dispatch handler is async and may span multiple ticks.
+   *
+   * @type {boolean}
+   */
+  _dispatching = false;
+
+  /**
+   * Determine if a claim is stale — the claimant agent is dead,
+   * dormant, inactive past stall timeout, or unregistered.
+   *
+   * Returns `true` for local dead/dormant/stalled agents (immediate release),
+   * `'foreign'` for agents not in the local map (requires proof-of-life),
+   * or `false` if the agent is alive and working.
+   *
+   * @param {string|null} claimer - Agent name from claim marker.
+   * @returns {boolean|string} true=stale, 'foreign'=needs proof-of-life, false=alive.
+   */
+  _stale(claimer) {
+    if (!claimer) return false;
+    const entry = this.orchestrator.agents.get(claimer);
+    if (!entry) {
+      if (this.orchestrator._removed?.has(claimer)) return true;
+      return 'foreign';
+    }
+    if (entry.state === 'dormant') return true;
+
+    // Claims from agents that exceeded the stall window block the
+    // queue even though they are not making progress; treat them as
+    // stale so dispatch can release and reassign work.
+    const last = this.orchestrator._lastActivity?.get(claimer);
+    if (!last) return false;
+    const elapsed = Date.now() - new Date(last).getTime();
+    if (!Number.isFinite(elapsed)) return false;
+
+    const timeout = this.orchestrator.stallTimeout
+      ?? this.orchestrator.cfg?.get?.('timeouts.stall')
+      ?? 600000;
+
+    return elapsed > timeout;
+  }
+
+  /**
+   * Evaluate a foreign claim through the proof-of-life protocol.
+   *
+   * Delegates to the base Workflow `check()` method which implements
+   * the unified, status-aware PoL gate.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue number.
+   * @param {string} agent - Foreign agent name.
+   * @returns {Promise<string>} 'active'|'requested'|'pending'|'release'.
+   */
+  async _checkForeignClaim(repo, number, agent) {
+    return this.check(repo, number, agent);
+  }
+
+  /**
+   * Report action demand: how many unclaimed issues need an agent vs
+   * how many action agents are currently active. Caches the issue
+   * fetch per tick so _dispatch() doesn't duplicate the API call.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<{workload: number, supply: number, deficit: number}>}
+   */
+  async demand(repo) {
+    const openIssues = await this.hub.issues(repo, { state: 'open', labels: ['loreli'] });
+
+    let workload = 0;
+    for (const issue of openIssues) {
+      if (issue.labels?.includes('loreli:parent')) continue;
+      if (issue.labels?.includes('loreli:blocked')) continue;
+      const claimer = await this.claimant(repo, issue.number);
+      if (!claimer || this._stale(claimer) === true) workload++;
+    }
+
+    const supply = this.agents().filter(function active(a) {
+      return a.state !== 'dormant' && this._stale(a.identity?.name) !== true;
+    }, this).length;
+
+    return { workload, supply, deficit: Math.max(0, workload - supply) };
+  }
+
+  /**
+   * Register event listeners on the orchestrator.
+   * Listens for `removed` events to release claimed issues.
+   *
+   * @returns {Record<string, function>} Event listener map.
+   */
+  events() {
+    const self = this;
+    return {
+      /**
+       * When an agent is removed, release any issues it had claimed.
+       *
+       * @param {object} event - The removed event.
+       * @param {object} event.agent - The removed agent instance.
+       */
+      async removed({ agent }) {
+        if (agent) await self.reassign(agent);
+      }
+    };
+  }
+
+  /**
+   * Register reactor handlers for the orchestrator's tick loop.
+   *
+   * The `dispatch` handler checks for dormant action agents and
+   * unclaimed issues on each tick. When a dormant agent is found,
+   * its workspace is reset to the configured base branch, it is respawned, and
+   * dispatched to the next unclaimed issue.
+   *
+   * @returns {Record<string, function>} Handler map.
+   */
+  reactor() {
+    const self = this;
+    return {
+      async dispatch(repo) { await self._dispatch(repo); }
+    };
+  }
+
+  /**
+   * Dispatch available action agents to unclaimed issues.
+   *
+   * Runs on each reactor tick. Finds dormant or idle spawned agents,
+   * checks for unclaimed issues, and dispatches. Dormant agents need
+   * a workspace reset and respawn; spawned agents that were never
+   * given work are already alive and ready. Only one dispatch cycle
+   * runs at a time via the _dispatching guard.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<void>}
+   */
+  async _dispatch(repo) {
+    if (this._dispatching) return;
+    this._dispatching = true;
+
+    try {
+      const openIssues = await this.hub.issues(repo, { state: 'open', labels: ['loreli'] });
+      const maxClaims = this.orchestrator.cfg?.get?.('watch.maxClaims') ?? 3;
+      const unclaimed = [];
+      for (const issue of openIssues) {
+        if (issue.labels?.includes('loreli:parent')) continue;
+        if (issue.labels?.includes('loreli:blocked')) continue;
+        const claimer = await this.claimant(repo, issue.number);
+        if (!claimer) {
+          unclaimed.push(issue);
+          continue;
+        }
+        const stale = this._stale(claimer);
+
+        if (stale === 'foreign') {
+          // Foreign claim — use proof-of-life protocol instead of
+          // immediate release to prevent duplicate work in multi-
+          // orchestrator setups.
+          try {
+            const verdict = await this._checkForeignClaim(repo, issue.number, claimer);
+            if (verdict === 'release') {
+              log.info(`dispatch: proof-of-life expired for ${claimer} on #${issue.number} — releasing`);
+              const releaseMarker = mark('release', { agent: claimer });
+              await this.hub.as(this.orchestrator.clientIdentity, 'orchestrator')
+                .comment(repo, issue.number, `${releaseMarker}\nClaim released — no proof of life from \`${claimer}\`.`);
+              unclaimed.push(issue);
+            } else {
+              log.debug(`dispatch: foreign claim by ${claimer} on #${issue.number} — ${verdict}`);
+            }
+          } catch (err) { log.warn(`dispatch: foreign claim check failed for #${issue.number}: ${err.message}`); }
+        } else if (stale === true) {
+          log.info(`dispatch: releasing stale claim from ${claimer} on #${issue.number}`);
+          try {
+            const releaseMarker = mark('release', { agent: claimer });
+            await this.hub.as(this.orchestrator.clientIdentity, 'orchestrator')
+              .comment(repo, issue.number, `${releaseMarker}\nClaim released — agent \`${claimer}\` is no longer active or is stalled.`);
+          } catch (err) { log.warn(`dispatch: stale release failed for #${issue.number}: ${err.message}`); }
+          unclaimed.push(issue);
+        }
+      }
+      if (!unclaimed.length) return;
+
+      // scale() is the sole spawn authority — dispatch only assigns
+      // work to agents that already exist (dormant or spawned).
+      const available = this.agents().filter(function ready(a) {
+        return a.state === 'dormant' || a.state === 'spawned';
+      });
+      if (!available.length) return;
+
+      for (let i = 0; i < Math.min(unclaimed.length, available.length); i++) {
+        const issue = unclaimed[i];
+        const agent = available[i];
+
+        // Circuit breaker: count release markers since the last reset point
+        // (circuit-breaker escalation or system restart marker). After
+        // maxClaims releases, the issue is escalated to HITL. The high-
+        // water mark ensures that human label removal and system restarts
+        // reset the counter without needing a separate reset mechanism.
+        const comments = await this.hub.comments(repo, issue.number);
+        let gateIdx = -1;
+        for (let j = comments.length - 1; j >= 0; j--) {
+          if (has(comments[j].body, 'circuit-breaker') || has(comments[j].body, 'restart')) {
+            gateIdx = j;
+            break;
+          }
+        }
+        const releases = comments.slice(gateIdx + 1)
+          .filter(function isRelease(c) { return has(c.body, 'release'); }).length;
+        if (releases >= maxClaims) {
+          log.warn(`circuit-breaker: issue #${issue.number} released ${releases} times — escalating to HITL`);
+          try {
+            await this.hub.ensure(repo, [
+              { name: 'loreli:blocked', color: 'b60205', description: 'Issue blocked — circuit breaker tripped' },
+              { name: 'loreli:needs-attention', color: 'e11d48', description: 'Requires human attention' }
+            ]);
+            await this.hub.label(repo, issue.number, ['loreli:blocked', 'loreli:needs-attention']);
+            const reviewers = this.orchestrator.cfg?.get?.('reviewers') ?? [];
+            const mentions = reviewers.length
+              ? reviewers.map(function mention(r) { return `@${r}`; }).join(' ') + ' '
+              : '';
+            const cbMarker = mark('circuit-breaker', { releases: String(releases) });
+            await this.hub.as(this.orchestrator.clientIdentity, 'orchestrator')
+              .comment(repo, issue.number, `${cbMarker}\n${mentions}### Circuit breaker tripped\n\nThis issue has been claimed and released ${releases} times without a successful PR. Loreli has paused automatic retries to prevent further token waste.\n\n**What happened:**\nLoreli assigned an agent to this issue ${releases} times. Each attempt ended with the agent releasing the issue — either because the work could not be completed, the PR received changes-requested feedback from a reviewer and the action agent was no longer available, or an unrecoverable error occurred.\n\n**To resolve:**\n1. Check the closed PRs linked to this issue for patterns in the agent failures\n2. Review the issue description — it may be ambiguous, underspecified, or infeasible for an AI agent\n3. Update the issue with clearer acceptance criteria or a simpler scope if needed\n4. Remove the \`loreli:blocked\` label from this issue — Loreli will automatically retry with a fresh agent\n5. If this issue should not be automated, close it instead`);
+          } catch (err) { log.warn(`circuit-breaker: HITL escalation failed for #${issue.number}: ${err.message}`); }
+          continue;
+        }
+
+        // Optimistic claim: post first, verify we won, then set up.
+        // This eliminates the TOCTOU race where another participant
+        // claims between our check and our claim.
+        const visible = agent.identity.claim?.() ?? `Claimed by **${agent.identity.name}**`;
+        const won = await this.claimFirst(repo, issue.number, 'claim', agent.identity, agent.role, visible);
+        if (!won) {
+          log.info(`dispatch: lost claim race for #${issue.number} — skipping`);
+          continue;
+        }
+        log.info(`dispatch: ${agent.identity.name} claimed #${issue.number}: ${issue.title}`);
+
+        // Both spawned and dormant agents need the per-issue branch.
+        // reset() switches the workspace to `${name}/issue-${issue}` so
+        // the agent's commits land on the correct remote branch for the PR.
+        const home = this.orchestrator.storage?.home;
+        const wsRoot = home ? `${home}/workspaces` : undefined;
+        const cwd = agent.cwd ?? pathFor(agent.identity.name, wsRoot);
+        const base = this.orchestrator.cfg?.get?.('merge.base') ?? 'main';
+        const options = workspaceOptions(this.orchestrator, repo, agent.identity.name);
+        try {
+          await reset(cwd, agent.identity.name, issue.number, base, options);
+        } catch (err) {
+          log.warn(`dispatch: workspace reset failed for ${agent.identity.name}: ${err.message} — skipping issue`);
+          continue;
+        }
+
+        // Dormant agents need respawning; spawned agents are already alive.
+        if (agent.state === 'dormant') {
+          await agent.spawn();
+        }
+
+        const issueBranch = `${agent.identity.name}/issue-${issue.number}`;
+
+        const prompt = await this.render({
+          name: agent.identity.name,
+          repo,
+          branch: issueBranch,
+          faction: agent.identity.faction,
+          provider: agent.identity.provider,
+          model: agent.identity.model,
+          issue: `#${issue.number}: ${issue.title}\n\n${issue.body}`,
+          labels: agent.identity.labels?.('action')
+        });
+
+        await this.saveTask(agent.identity.name, { type: 'work_issue', issue: issue.number });
+
+        if (agent.identity.labels) {
+          try {
+            await this.hub.label(repo, issue.number, agent.identity.labels(agent.role));
+          } catch (err) { log.warn(`dispatch: labeling failed for issue #${issue.number}: ${err.message}`); }
+        }
+
+        await agent.send(prompt);
+        this.orchestrator.activity(agent.identity.name);
+      }
+    } catch (err) {
+      log.error(`dispatch failed: ${err.message}`);
+    } finally {
+      this._dispatching = false;
+    }
+  }
+
+  // ── Claim Protocol ────────────────────────────────────
+
+  /**
+   * Post a claim comment on an issue.
+   *
+   * First-comment-wins: the agent that posts a claim marker first is
+   * the assignee. Other agents skip already-claimed issues. The marker
+   * is machine-readable; the visible text is themed via identity.claim().
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue number.
+   * @param {object} identity - Agent identity with name.
+   * @param {string} role - Agent role for hub scoping.
+   * @returns {Promise<void>}
+   */
+  async claim(repo, number, identity, role) {
+    const scoped = this.hub.as(identity, role);
+    const marker = mark('claim', { agent: identity.name });
+    const visible = identity.claim?.() ?? `Claimed by **${identity.name}**`;
+    await scoped.comment(repo, number, `${marker}\n${visible}`);
+  }
+
+  /**
+   * Determine who claimed an issue by parsing claim and release comments.
+   *
+   * Walks all comments in chronological order. A `claim` marker sets the
+   * claimant; a subsequent `release` marker clears it. The last lifecycle
+   * marker wins, so claim → release → re-claim works correctly.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue number.
+   * @returns {Promise<string|null>} Claim agent name, or null if unclaimed/released.
+   */
+  async claimant(repo, number) {
+    const allComments = await this.hub.comments(repo, number);
+
+    let agent = null;
+    for (const c of allComments) {
+      if (has(c.body, 'claim')) {
+        const parsed = parse(c.body, 'claim')?.agent;
+        if (parsed) agent = parsed;
+      }
+      if (has(c.body, 'release') || has(c.body, 'restart')) {
+        agent = null;
+      }
+    }
+
+    // Piggyback: record discovered name in the orchestrator's taken
+    // set so identity acquisition avoids collisions. Zero API cost —
+    // this data was already fetched for the claim check.
+    if (agent) this.orchestrator.takenNames?.add(agent);
+
+    return agent;
+  }
+
+  // ── Reassign ─────────────────────────────────────────
+
+  /**
+   * Release all issues claimed by a dead/dying agent so they become
+   * available for re-claim.
+   *
+   * Operates via GitHub: finds issues with this agent's claim,
+   * removes labels, and posts a release comment.
+   *
+   * @param {object} agent - The agent being removed.
+   * @returns {Promise<number>} Number of issues released.
+   */
+  async reassign(agent) {
+    if (!this.hub) return 0;
+
+    const repo = this.orchestrator.repo;
+    if (!repo) return 0;
+
+    let released = 0;
+    try {
+      const open = await this.hub.issues(repo, { state: 'open' });
+      const agentLabels = agent.identity?.labels?.(agent.role) ?? [];
+      const agentName = agent.identity?.name;
+
+      for (const issue of open) {
+        const claimer = await this.claimant(repo, issue.number);
+        if (claimer !== agentName) continue;
+
+        const scoped = this.hub.as(agent.identity, agent.role);
+        try {
+          const releaseMarker = mark('release', { agent: agentName });
+          const visible = agent.identity?.release?.() ?? `**Released** — agent \`${agentName}\` was terminated. This issue is available for re-claim.`;
+          await scoped.comment(repo, issue.number, `${releaseMarker}\n${visible}`);
+        } catch (err) { log.warn(`reassign: release comment failed for issue #${issue.number}: ${err.message}`); }
+
+        if (agentLabels.length) {
+          try {
+            const current = issue.labels ?? [];
+            const remaining = current.filter(function keep(l) { return !agentLabels.includes(l); });
+            if (remaining.length < current.length) {
+              await this.hub.label(repo, issue.number, remaining);
+            }
+          } catch (err) { log.warn(`reassign: label removal failed for issue #${issue.number}: ${err.message}`); }
+        }
+
+        released++;
+        log.info(`released issue #${issue.number} from ${agentName}`);
+      }
+    } catch (err) {
+      log.warn(`reassign failed for ${agent.identity?.name}: ${err.message}`);
+    }
+
+    return released;
+  }
+
+  // ── Work ──────────────────────────────────────────────
+
+  /**
+   * Dispatch the work cycle to action agents.
+   *
+   * Fetches unclaimed issues, assigns them round-robin to action
+   * agents, pairs each with an opposing-provider reviewer for
+   * adversarial cross-model review, claims issues on GitHub, and
+   * renders/sends the action prompt.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<Array<{issue: number, agent: string, reviewer: string|null}>>}
+   * @throws {Error} When no action agents are available.
+   */
+  async work(repo) {
+    if (this._dispatching) return [];
+    this._dispatching = true;
+
+    try {
+      return await this._work(repo);
+    } finally {
+      this._dispatching = false;
+    }
+  }
+
+  /**
+   * Internal work implementation, guarded by _dispatching in work().
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @returns {Promise<Array<{issue: number, agent: string, reviewer: string|null}>>}
+   */
+  async _work(repo) {
+    log.info(`work cycle: ${repo}`);
+    const actions = this.agents().filter(function active(a) {
+      return a.state !== 'dormant' && this._stale(a.identity?.name) !== true;
+    }, this);
+    if (!actions.length) {
+      log.debug('work: no action agents available — scale() will fill demand');
+      return [];
+    }
+
+    const reviewers = [...this.orchestrator.agents.values()]
+      .filter(function isReviewer(a) { return a.role === 'reviewer'; });
+
+    // Fetch unclaimed loreli issues — filtering by label avoids
+    // fetching comments for every open issue in the repository.
+    const openIssues = await this.hub.issues(repo, { state: 'open', labels: ['loreli'] });
+    const unclaimed = [];
+    for (const issue of openIssues) {
+      if (issue.labels?.includes('loreli:parent')) continue;
+      if (issue.labels?.includes('loreli:blocked')) continue;
+      const claimer = await this.claimant(repo, issue.number);
+      if (!claimer) {
+        unclaimed.push(issue);
+        continue;
+      }
+      const stale = this._stale(claimer);
+      if (stale === 'foreign') {
+        try {
+          const verdict = await this._checkForeignClaim(repo, issue.number, claimer);
+          if (verdict === 'release') {
+            log.info(`work: proof-of-life expired for ${claimer} on #${issue.number} — releasing`);
+            const releaseMarker = mark('release', { agent: claimer });
+            await this.hub.as(this.orchestrator.clientIdentity, 'orchestrator')
+              .comment(repo, issue.number, `${releaseMarker}\nClaim released — no proof of life from \`${claimer}\`.`);
+            unclaimed.push(issue);
+          } else {
+            log.debug(`work: foreign claim by ${claimer} on #${issue.number} — ${verdict}`);
+          }
+        } catch (err) { log.warn(`work: foreign claim check failed for #${issue.number}: ${err.message}`); }
+      } else if (stale === true) {
+        log.info(`work: releasing stale claim from ${claimer} on #${issue.number}`);
+        try {
+          const releaseMarker = mark('release', { agent: claimer });
+          await this.hub.as(this.orchestrator.clientIdentity, 'orchestrator')
+            .comment(repo, issue.number, `${releaseMarker}\nClaim released — agent \`${claimer}\` is no longer active or is stalled.`);
+        } catch (err) { log.warn(`work: stale release failed for #${issue.number}: ${err.message}`); }
+        unclaimed.push(issue);
+      }
+    }
+
+    const assignments = [];
+    for (let i = 0; i < Math.min(unclaimed.length, actions.length); i++) {
+      const issue = unclaimed[i];
+      const agent = actions[i];
+
+      // Pair with an opposing-provider reviewer if one exists already.
+      // scale() handles spawning reviewers — we do not enlist inline.
+      const reviewer = this.pair(agent.identity, reviewers);
+
+      // Switch to per-issue branch before the agent starts working.
+      // This ensures each issue gets its own remote branch for its PR.
+      const home = this.orchestrator.storage?.home;
+      const wsRoot = home ? `${home}/workspaces` : undefined;
+      const cwd = agent.cwd ?? pathFor(agent.identity.name, wsRoot);
+      const base = this.orchestrator.cfg?.get?.('merge.base') ?? 'main';
+      const options = workspaceOptions(this.orchestrator, repo, agent.identity.name);
+      try {
+        await reset(cwd, agent.identity.name, issue.number, base, options);
+      } catch (err) {
+        log.warn(`work: branch reset failed for ${agent.identity.name}: ${err.message} — skipping issue`);
+        continue;
+      }
+
+      const issueBranch = `${agent.identity.name}/issue-${issue.number}`;
+
+      const prompt = await this.render({
+        name: agent.identity.name,
+        repo,
+        branch: issueBranch,
+        faction: agent.identity.faction,
+        provider: agent.identity.provider,
+        model: agent.identity.model,
+        issue: `#${issue.number}: ${issue.title}\n\n${issue.body}`,
+        labels: agent.identity.labels?.('action')
+      });
+
+      // Optimistic claim: post first, verify we won.
+      const visible = agent.identity.claim?.() ?? `Claimed by **${agent.identity.name}**`;
+      const won = await this.claimFirst(repo, issue.number, 'claim', agent.identity, agent.role, visible);
+      if (!won) {
+        log.info(`work: lost claim race for #${issue.number} — skipping`);
+        continue;
+      }
+      log.info(`${agent.identity.name} claimed #${issue.number}: ${issue.title}`);
+
+      // Write claimed issue to session so the agent's MCP tools can auto-reference it
+      await this.saveTask(agent.identity.name, { type: 'work_issue', issue: issue.number });
+
+      // Apply agent labels to the claimed issue
+      if (agent.identity.labels) {
+        try {
+          await this.hub.label(repo, issue.number, agent.identity.labels(agent.role));
+        } catch (err) { log.warn(`work: labeling failed for issue #${issue.number}: ${err.message}`); }
+      }
+
+      await agent.send(prompt);
+      this.orchestrator.activity(agent.identity.name);
+
+      assignments.push({
+        issue: issue.number,
+        agent: agent.identity.name,
+        reviewer: reviewer?.identity?.name ?? null
+      });
+    }
+
+    return assignments;
+  }
+
+  // ── Rework ────────────────────────────────────────────
+
+  /**
+   * Handle human feedback on a gated PR by dispatching to an
+   * existing action agent or spawning a fresh one.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} pr - Pull request number.
+   * @param {Array<{author: string, body: string}>} feedback - Human comments.
+   * @returns {Promise<{reworkAgent: string, hitlAt: string}>}
+   */
+  async rework(repo, pr, feedback) {
+    log.info(`rework PR #${pr} on ${repo} with ${feedback.length} feedback items`);
+
+    const cfg = this.orchestrator.cfg;
+    const reviewers = cfg?.get?.('reviewers') ?? [];
+
+    // Try existing action agent first
+    let agent = this.agents()[0];
+
+    // If no agents exist (gate killed them all), spawn a fresh one
+    if (!agent) {
+      log.info('no agents available for rework — spawning fresh action agent');
+
+      await this.orchestrator.backendRegistry.discover();
+      const provider = this.orchestrator.backendRegistry.providers()[0] ?? 'anthropic';
+
+      agent = await this.enlist(provider, 'action', {
+        theme: pick(cfg?.get?.('theme')),
+        config: cfg
+      });
+    }
+
+    // Fetch PR details so the rework prompt includes branch context.
+    // Without this, the agent cannot identify which branch to work on.
+    let prDetails;
+    try {
+      prDetails = await this.hub.pull(repo, pr);
+    } catch (err) {
+      log.warn(`rework: failed to fetch PR #${pr}: ${err.message}`);
+    }
+
+    await this.dispatch(agent, {
+      name: agent.identity.name,
+      repo,
+      branch: prDetails?.head ?? `${agent.identity.name}/work`,
+      faction: agent.identity.faction,
+      provider: agent.identity.provider,
+      model: agent.identity.model,
+      labels: agent.identity.labels?.('action'),
+      hitl: {
+        feedback: feedback.map(function mapFeedback(f) {
+          return { author: f.author, body: f.body };
+        }),
+        reviewer: reviewers[0] ?? 'reviewer'
+      }
+    });
+    this.orchestrator.activity(agent.identity.name);
+
+    // Re-request review after rework
+    const hitlAt = new Date().toISOString();
+    if (reviewers.length) {
+      await this.hub.request(repo, pr, reviewers);
+      await this.hub.assign(repo, pr, reviewers);
+    }
+
+    log.info(`rework agent: ${agent.identity.name}`);
+    return { reworkAgent: agent.identity.name, hitlAt };
+  }
+}