@h-rig/supervisor-plugin 0.0.6-alpha.133

package/README.md

@@ -0,0 +1 @@
+# @h-rig/supervisor-plugin

package/dist/src/awaiter.d.ts

@@ -0,0 +1,15 @@
+import type { RunId, RunStatus } from "@rig/contracts";
+import type { SupervisorRunOutcome } from "./supervisor";
+export interface RunStatusSnapshot {
+    readonly runId: RunId;
+    readonly status: RunStatus;
+    readonly diagnostic?: string;
+}
+export interface SupervisorAwaitTerminalOptions {
+    readonly runId: RunId;
+    readonly readStatus: (runId: RunId) => Promise<RunStatusSnapshot | null> | RunStatusSnapshot | null;
+    readonly waitForChange: (timeoutMs: number) => Promise<void>;
+    readonly pollMs?: number;
+    readonly timeoutMs?: number;
+}
+export declare function awaitTerminalRun(options: SupervisorAwaitTerminalOptions): Promise<SupervisorRunOutcome>;

package/dist/src/awaiter.js

@@ -0,0 +1,39 @@
+// @bun
+// packages/supervisor-plugin/src/awaiter.ts
+var TERMINAL_RUN_STATUSES = {
+  created: false,
+  queued: false,
+  preparing: false,
+  running: false,
+  "waiting-approval": false,
+  "waiting-user-input": false,
+  paused: false,
+  validating: false,
+  reviewing: false,
+  "closing-out": false,
+  "needs-attention": true,
+  completed: true,
+  failed: true,
+  stopped: true
+};
+async function awaitTerminalRun(options) {
+  const startedAt = Date.now();
+  const pollMs = Math.max(0, Math.floor(options.pollMs ?? 5000));
+  while (true) {
+    const snapshot = await options.readStatus(options.runId);
+    if (snapshot && TERMINAL_RUN_STATUSES[snapshot.status]) {
+      return {
+        runId: options.runId,
+        status: snapshot.status,
+        failed: snapshot.status !== "completed"
+      };
+    }
+    if (options.timeoutMs !== undefined && Date.now() - startedAt >= options.timeoutMs) {
+      return { runId: options.runId, status: "needs-attention", failed: true };
+    }
+    await options.waitForChange(pollMs);
+  }
+}
+export {
+  awaitTerminalRun
+};

package/dist/src/closureStage.d.ts

@@ -0,0 +1,8 @@
+import type { StageContext, StageMutation, StageResult, TaskClosureSummary } from "@rig/contracts";
+export declare const SUPERVISOR_CLOSURE_STAGE_ID = "supervisor-closure-observer";
+export interface ClosureSummaryPort {
+    summarize(ctx: StageContext): Promise<TaskClosureSummary | null> | TaskClosureSummary | null;
+    record?(summary: TaskClosureSummary): Promise<void> | void;
+}
+export declare function createClosureStage(port: ClosureSummaryPort): (ctx: StageContext) => Promise<StageResult>;
+export declare const supervisorClosureStageMutation: StageMutation;

package/dist/src/closureStage.js

@@ -0,0 +1,30 @@
+// @bun
+// packages/supervisor-plugin/src/closureStage.ts
+var SUPERVISOR_CLOSURE_STAGE_ID = "supervisor-closure-observer";
+function createClosureStage(port) {
+  return async (ctx) => {
+    const summary = await port.summarize(ctx);
+    if (!summary)
+      return { kind: "continue", ctx };
+    await port.record?.(summary);
+    const metadata = { ...ctx.metadata ?? {}, supervisorClosure: summary };
+    return { kind: "continue", ctx: { ...ctx, metadata } };
+  };
+}
+var supervisorClosureStageMutation = {
+  op: "insert",
+  contributedBy: "@rig/supervisor-plugin",
+  stage: {
+    id: SUPERVISOR_CLOSURE_STAGE_ID,
+    kind: "observe",
+    after: ["source-closeout"],
+    before: ["journal-append"],
+    priority: 0,
+    protected: false
+  }
+};
+export {
+  supervisorClosureStageMutation,
+  createClosureStage,
+  SUPERVISOR_CLOSURE_STAGE_ID
+};

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./awaiter";
+export * from "./closureStage";
+export * from "./journal";
+export * from "./plugin";
+export * from "./supervisor";

package/dist/src/index.js

@@ -0,0 +1,310 @@
+// @bun
+// packages/supervisor-plugin/src/awaiter.ts
+var TERMINAL_RUN_STATUSES = {
+  created: false,
+  queued: false,
+  preparing: false,
+  running: false,
+  "waiting-approval": false,
+  "waiting-user-input": false,
+  paused: false,
+  validating: false,
+  reviewing: false,
+  "closing-out": false,
+  "needs-attention": true,
+  completed: true,
+  failed: true,
+  stopped: true
+};
+async function awaitTerminalRun(options) {
+  const startedAt = Date.now();
+  const pollMs = Math.max(0, Math.floor(options.pollMs ?? 5000));
+  while (true) {
+    const snapshot = await options.readStatus(options.runId);
+    if (snapshot && TERMINAL_RUN_STATUSES[snapshot.status]) {
+      return {
+        runId: options.runId,
+        status: snapshot.status,
+        failed: snapshot.status !== "completed"
+      };
+    }
+    if (options.timeoutMs !== undefined && Date.now() - startedAt >= options.timeoutMs) {
+      return { runId: options.runId, status: "needs-attention", failed: true };
+    }
+    await options.waitForChange(pollMs);
+  }
+}
+// packages/supervisor-plugin/src/closureStage.ts
+var SUPERVISOR_CLOSURE_STAGE_ID = "supervisor-closure-observer";
+function createClosureStage(port) {
+  return async (ctx) => {
+    const summary = await port.summarize(ctx);
+    if (!summary)
+      return { kind: "continue", ctx };
+    await port.record?.(summary);
+    const metadata = { ...ctx.metadata ?? {}, supervisorClosure: summary };
+    return { kind: "continue", ctx: { ...ctx, metadata } };
+  };
+}
+var supervisorClosureStageMutation = {
+  op: "insert",
+  contributedBy: "@rig/supervisor-plugin",
+  stage: {
+    id: SUPERVISOR_CLOSURE_STAGE_ID,
+    kind: "observe",
+    after: ["source-closeout"],
+    before: ["journal-append"],
+    priority: 0,
+    protected: false
+  }
+};
+// packages/supervisor-plugin/src/journal.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname } from "path";
+import { Schema } from "effect";
+import {
+  SupervisorEvent,
+  reduceSupervisorJournal
+} from "@rig/contracts";
+var NEWLINE = `
+`;
+function createFileSupervisorJournal(path) {
+  return {
+    async append(line) {
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, `${line}${NEWLINE}`, { flag: "a" });
+    },
+    async read() {
+      try {
+        return await readFile(path, "utf8");
+      } catch (error) {
+        const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+        if (code === "ENOENT")
+          return "";
+        throw error;
+      }
+    }
+  };
+}
+function createInMemorySupervisorJournalStore(seed = []) {
+  const lines = seed.map((event) => JSON.stringify(event));
+  return {
+    async append(line) {
+      lines.push(line);
+    },
+    async read() {
+      return lines.join(NEWLINE);
+    }
+  };
+}
+function parseSupervisorJournal(text) {
+  return text.split(/\r?\n/u).map((line) => line.trim()).filter((line) => line.length > 0).map((line, index) => {
+    try {
+      return Schema.decodeUnknownSync(SupervisorEvent)(JSON.parse(line));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Invalid supervisor journal line ${index + 1}: ${message}`);
+    }
+  });
+}
+function createSupervisorJournal(store) {
+  const append = async (event) => {
+    await store.append(JSON.stringify(Schema.decodeUnknownSync(SupervisorEvent)(event)));
+  };
+  const readEvents = async () => parseSupervisorJournal(await store.read());
+  const readProjection = async () => reduceSupervisorJournal(await readEvents());
+  return { append, readEvents, readProjection };
+}
+// packages/supervisor-plugin/src/plugin.ts
+import { definePlugin } from "@rig/core";
+var SUPERVISOR_PLUGIN_NAME = "@rig/supervisor-plugin";
+var supervisorPlugin = definePlugin({
+  name: SUPERVISOR_PLUGIN_NAME,
+  version: "0.0.0-alpha.1",
+  provides: [],
+  requires: ["journal", "transport"],
+  contributes: {
+    stageMutations: [supervisorClosureStageMutation]
+  }
+});
+// packages/supervisor-plugin/src/supervisor.ts
+import {
+  computeTaskDependencyBadges,
+  disjointScope,
+  isTaskTerminalStatus,
+  rankReadyTasks,
+  readTaskScope
+} from "@rig/core/task-graph";
+var DEFAULT_STOP_WHEN = new Set(["all-done", "all-human-blocked", "source-error"]);
+var HUMAN_BLOCKER_CLASS = {
+  "not-blocked": false,
+  "task-blocked": false,
+  "human-decision": true,
+  "human-approval": true,
+  "external-input": true,
+  unknown: true
+};
+function normalizeOptions(options = {}) {
+  return {
+    concurrency: Math.max(1, Math.floor(options.concurrency ?? 1)),
+    selectionPolicy: options.selectionPolicy ?? "rank",
+    maxTasks: options.maxTasks === undefined ? null : Math.max(0, Math.floor(options.maxTasks)),
+    ...options.filter ? { filter: options.filter } : {},
+    stopWhen: options.stopWhen ?? DEFAULT_STOP_WHEN,
+    pauseOnAttention: options.pauseOnAttention ?? true,
+    failFast: options.failFast ?? false,
+    pollMs: Math.max(0, Math.floor(options.pollMs ?? 5000))
+  };
+}
+function selectionMode(policy) {
+  if (policy === "blocking-only")
+    return "blocking-only";
+  if (policy === "max-unblock")
+    return "max-unblock";
+  return "all-ready";
+}
+function dispatchHandle(result) {
+  return typeof result === "string" ? { runId: result } : result;
+}
+function filterTask(task, filter) {
+  if (!filter)
+    return true;
+  if (filter.statuses && !filter.statuses.includes(task.status))
+    return false;
+  if (filter.workspaceIds && !filter.workspaceIds.includes(task.workspaceId))
+    return false;
+  if (filter.assignees) {
+    const raw = task.metadata;
+    const assignee = typeof raw === "object" && raw !== null && "assignee" in raw && typeof raw.assignee === "string" ? raw.assignee : null;
+    if (!assignee || !filter.assignees.includes(assignee))
+      return false;
+  }
+  return true;
+}
+function classifyEmptyReadySet(snapshot, badges, classifyBlocker) {
+  if ((snapshot.diagnostics ?? []).length > 0)
+    return "source-error";
+  const openTasks = snapshot.tasks.filter((task) => !isTaskTerminalStatus(task.status));
+  if (openTasks.length === 0)
+    return "all-done";
+  if (classifyBlocker) {
+    const allHumanBlocked = openTasks.every((task) => HUMAN_BLOCKER_CLASS[classifyBlocker(task, badges).blockerClass]);
+    if (allHumanBlocked)
+      return "all-human-blocked";
+  }
+  return "all-done";
+}
+function terminalFailed(outcome) {
+  return outcome.failed ?? ["failed", "stopped", "needs-attention"].includes(outcome.status);
+}
+async function runSupervisor(ctx, options = {}) {
+  const normalized = normalizeOptions(options);
+  const now = () => (ctx.now?.() ?? new Date).toISOString();
+  const emit = async (event) => {
+    await ctx.emitEvent?.(event);
+  };
+  let processed = 0;
+  let succeeded = 0;
+  let failed = 0;
+  let skipped = 0;
+  let idleReason = null;
+  const completedTaskIds = new Set;
+  await emit({ kind: "supervisor.started", at: now(), options: normalized });
+  while (!ctx.shouldStop?.()) {
+    if (normalized.maxTasks !== null && processed >= normalized.maxTasks) {
+      idleReason = "max-tasks";
+      await emit({ kind: "supervisor.idle", at: now(), reason: idleReason });
+      break;
+    }
+    const snapshot = await ctx.readTasks();
+    const badges = computeTaskDependencyBadges(snapshot.tasks);
+    const activeRuns = snapshot.activeRuns ?? [];
+    const activeTaskIds = activeRuns.map((run) => run.taskId);
+    const remainingSlots = normalized.maxTasks === null ? normalized.concurrency : Math.min(normalized.concurrency, normalized.maxTasks - processed);
+    const ranked = rankReadyTasks(snapshot.tasks, {
+      excludeTaskIds: completedTaskIds,
+      activeTaskIds,
+      filter: (task) => filterTask(task, normalized.filter),
+      selection: selectionMode(normalized.selectionPolicy)
+    });
+    const selected = [];
+    const occupiedScopes = activeRuns.flatMap((run) => {
+      const task = snapshot.tasks.find((candidate) => candidate.id === run.taskId);
+      return task ? readTaskScope(task) : [];
+    });
+    for (const entry of ranked) {
+      if (selected.length >= remainingSlots)
+        break;
+      if (!disjointScope(entry.scope, occupiedScopes))
+        continue;
+      selected.push(entry);
+      occupiedScopes.push(...entry.scope);
+    }
+    await emit({ kind: "supervisor.selection-planned", at: now(), taskIds: selected.map((entry) => entry.task.id), policy: normalized.selectionPolicy });
+    if (selected.length === 0) {
+      idleReason = classifyEmptyReadySet(snapshot, badges, ctx.classifyBlocker);
+      await emit({ kind: "supervisor.idle", at: now(), reason: idleReason });
+      if (normalized.stopWhen.has(idleReason))
+        break;
+      await ctx.waitForChange(normalized.pollMs);
+      continue;
+    }
+    const outcomes = await Promise.all(selected.map(async (entry) => {
+      await emit({ kind: "supervisor.dispatch-started", at: now(), taskId: entry.task.id, score: Math.max(0, Math.floor(entry.score)) });
+      const handle = dispatchHandle(await ctx.dispatch(entry.task));
+      await emit({
+        kind: "supervisor.dispatch-confirmed",
+        at: now(),
+        taskId: entry.task.id,
+        runId: handle.runId,
+        ...handle.dispatchHandle === undefined ? {} : { dispatchHandle: handle.dispatchHandle }
+      });
+      const outcome = await ctx.awaitTerminal(handle.runId, entry.task);
+      const failedOutcome = terminalFailed(outcome);
+      await emit({
+        kind: "supervisor.outcome",
+        at: now(),
+        taskId: entry.task.id,
+        runId: outcome.runId,
+        status: outcome.status,
+        failed: failedOutcome,
+        unblockedTaskIds: outcome.closure?.unblockedTaskIds ?? [],
+        ...outcome.closure ? { closure: outcome.closure } : {}
+      });
+      return { taskId: entry.task.id, status: outcome.status, failed: failedOutcome };
+    }));
+    for (const outcome of outcomes) {
+      completedTaskIds.add(outcome.taskId);
+      processed += 1;
+      if (outcome.failed)
+        failed += 1;
+      else
+        succeeded += 1;
+    }
+    if (normalized.pauseOnAttention && outcomes.some((outcome) => outcome.status === "needs-attention")) {
+      idleReason = "operator-stop";
+      break;
+    }
+    if (normalized.failFast && outcomes.some((outcome) => outcome.failed))
+      break;
+  }
+  if (ctx.shouldStop?.()) {
+    idleReason = "operator-stop";
+    await emit({ kind: "supervisor.stopped", at: now(), reason: idleReason });
+  }
+  await emit({ kind: "supervisor.finished", at: now(), processed, succeeded, failed, skipped, idleReason });
+  return { processed, succeeded, failed, skipped, idleReason };
+}
+export {
+  supervisorPlugin,
+  supervisorClosureStageMutation,
+  runSupervisor,
+  parseSupervisorJournal,
+  createSupervisorJournal,
+  createInMemorySupervisorJournalStore,
+  createFileSupervisorJournal,
+  createClosureStage,
+  awaitTerminalRun,
+  SUPERVISOR_PLUGIN_NAME,
+  SUPERVISOR_CLOSURE_STAGE_ID
+};

package/dist/src/journal.d.ts

@@ -0,0 +1,14 @@
+import { SupervisorEvent, type SupervisorProjection } from "@rig/contracts";
+export interface SupervisorJournalStore {
+    append(line: string): Promise<void>;
+    read(): Promise<string>;
+}
+export interface SupervisorJournal {
+    append(event: SupervisorEvent): Promise<void>;
+    readEvents(): Promise<readonly SupervisorEvent[]>;
+    readProjection(): Promise<SupervisorProjection>;
+}
+export declare function createFileSupervisorJournal(path: string): SupervisorJournalStore;
+export declare function createInMemorySupervisorJournalStore(seed?: readonly SupervisorEvent[]): SupervisorJournalStore;
+export declare function parseSupervisorJournal(text: string): readonly SupervisorEvent[];
+export declare function createSupervisorJournal(store: SupervisorJournalStore): SupervisorJournal;

package/dist/src/journal.js

@@ -0,0 +1,64 @@
+// @bun
+// packages/supervisor-plugin/src/journal.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname } from "path";
+import { Schema } from "effect";
+import {
+  SupervisorEvent,
+  reduceSupervisorJournal
+} from "@rig/contracts";
+var NEWLINE = `
+`;
+function createFileSupervisorJournal(path) {
+  return {
+    async append(line) {
+      await mkdir(dirname(path), { recursive: true });
+      await writeFile(path, `${line}${NEWLINE}`, { flag: "a" });
+    },
+    async read() {
+      try {
+        return await readFile(path, "utf8");
+      } catch (error) {
+        const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+        if (code === "ENOENT")
+          return "";
+        throw error;
+      }
+    }
+  };
+}
+function createInMemorySupervisorJournalStore(seed = []) {
+  const lines = seed.map((event) => JSON.stringify(event));
+  return {
+    async append(line) {
+      lines.push(line);
+    },
+    async read() {
+      return lines.join(NEWLINE);
+    }
+  };
+}
+function parseSupervisorJournal(text) {
+  return text.split(/\r?\n/u).map((line) => line.trim()).filter((line) => line.length > 0).map((line, index) => {
+    try {
+      return Schema.decodeUnknownSync(SupervisorEvent)(JSON.parse(line));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`Invalid supervisor journal line ${index + 1}: ${message}`);
+    }
+  });
+}
+function createSupervisorJournal(store) {
+  const append = async (event) => {
+    await store.append(JSON.stringify(Schema.decodeUnknownSync(SupervisorEvent)(event)));
+  };
+  const readEvents = async () => parseSupervisorJournal(await store.read());
+  const readProjection = async () => reduceSupervisorJournal(await readEvents());
+  return { append, readEvents, readProjection };
+}
+export {
+  parseSupervisorJournal,
+  createSupervisorJournal,
+  createInMemorySupervisorJournalStore,
+  createFileSupervisorJournal
+};

package/dist/src/plugin.d.ts

@@ -0,0 +1,3 @@
+export declare const SUPERVISOR_PLUGIN_NAME = "@rig/supervisor-plugin";
+export declare const supervisorPlugin: import("@rig/core").RigPluginWithRuntime;
+export default supervisorPlugin;

package/dist/src/plugin.js

@@ -0,0 +1,36 @@
+// @bun
+// packages/supervisor-plugin/src/plugin.ts
+import { definePlugin } from "@rig/core";
+
+// packages/supervisor-plugin/src/closureStage.ts
+var SUPERVISOR_CLOSURE_STAGE_ID = "supervisor-closure-observer";
+var supervisorClosureStageMutation = {
+  op: "insert",
+  contributedBy: "@rig/supervisor-plugin",
+  stage: {
+    id: SUPERVISOR_CLOSURE_STAGE_ID,
+    kind: "observe",
+    after: ["source-closeout"],
+    before: ["journal-append"],
+    priority: 0,
+    protected: false
+  }
+};
+
+// packages/supervisor-plugin/src/plugin.ts
+var SUPERVISOR_PLUGIN_NAME = "@rig/supervisor-plugin";
+var supervisorPlugin = definePlugin({
+  name: SUPERVISOR_PLUGIN_NAME,
+  version: "0.0.0-alpha.1",
+  provides: [],
+  requires: ["journal", "transport"],
+  contributes: {
+    stageMutations: [supervisorClosureStageMutation]
+  }
+});
+var plugin_default = supervisorPlugin;
+export {
+  supervisorPlugin,
+  plugin_default as default,
+  SUPERVISOR_PLUGIN_NAME
+};

package/dist/src/supervisor.d.ts

@@ -0,0 +1,57 @@
+import type { BlockerClassification, RunId, RunStatus, SupervisorEvent, SupervisorSelectionPolicy, SupervisorStopReason, TaskClosureSummary, TaskSummary } from "@rig/contracts";
+import { type TaskDependencyBadgeSummary } from "@rig/core/task-graph";
+export interface SupervisorActiveRun {
+    readonly taskId: TaskSummary["id"];
+    readonly runId: RunId;
+    readonly status?: RunStatus;
+}
+export interface TaskSnapshot {
+    readonly tasks: readonly TaskSummary[];
+    readonly activeRuns?: readonly SupervisorActiveRun[];
+    readonly diagnostics?: readonly string[];
+}
+export interface SupervisorDispatchHandle {
+    readonly runId: RunId;
+    readonly dispatchHandle?: string | null;
+}
+export type SupervisorDispatchResult = RunId | SupervisorDispatchHandle;
+export interface SupervisorRunOutcome {
+    readonly runId: RunId;
+    readonly status: RunStatus;
+    readonly failed?: boolean;
+    readonly closure?: TaskClosureSummary;
+}
+export interface SupervisorContext {
+    readonly projectRoot: string;
+    readTasks(): Promise<TaskSnapshot>;
+    dispatch(task: TaskSummary): Promise<SupervisorDispatchResult>;
+    awaitTerminal(runId: RunId, task: TaskSummary): Promise<SupervisorRunOutcome>;
+    waitForChange(timeoutMs: number): Promise<void>;
+    emitEvent?(event: SupervisorEvent): Promise<void>;
+    classifyBlocker?(task: TaskSummary, badges: ReadonlyMap<string, TaskDependencyBadgeSummary>): BlockerClassification;
+    now?(): Date;
+    shouldStop?(): boolean;
+}
+export interface TaskFilter {
+    readonly statuses?: readonly TaskSummary["status"][];
+    readonly workspaceIds?: readonly TaskSummary["workspaceId"][];
+    readonly assignees?: readonly string[];
+}
+export interface SupervisorOptions {
+    readonly concurrency?: number;
+    readonly selectionPolicy?: SupervisorSelectionPolicy;
+    readonly maxTasks?: number;
+    readonly filter?: TaskFilter;
+    readonly stopWhen?: ReadonlySet<SupervisorStopReason>;
+    readonly pauseOnAttention?: boolean;
+    readonly failFast?: boolean;
+    readonly pollMs?: number;
+}
+export interface SupervisorSummary {
+    readonly processed: number;
+    readonly succeeded: number;
+    readonly failed: number;
+    readonly skipped: number;
+    readonly idleReason: SupervisorStopReason | null;
+}
+export declare function runSupervisor(ctx: SupervisorContext, options?: SupervisorOptions): Promise<SupervisorSummary>;

package/dist/src/supervisor.js

@@ -0,0 +1,172 @@
+// @bun
+// packages/supervisor-plugin/src/supervisor.ts
+import {
+  computeTaskDependencyBadges,
+  disjointScope,
+  isTaskTerminalStatus,
+  rankReadyTasks,
+  readTaskScope
+} from "@rig/core/task-graph";
+var DEFAULT_STOP_WHEN = new Set(["all-done", "all-human-blocked", "source-error"]);
+var HUMAN_BLOCKER_CLASS = {
+  "not-blocked": false,
+  "task-blocked": false,
+  "human-decision": true,
+  "human-approval": true,
+  "external-input": true,
+  unknown: true
+};
+function normalizeOptions(options = {}) {
+  return {
+    concurrency: Math.max(1, Math.floor(options.concurrency ?? 1)),
+    selectionPolicy: options.selectionPolicy ?? "rank",
+    maxTasks: options.maxTasks === undefined ? null : Math.max(0, Math.floor(options.maxTasks)),
+    ...options.filter ? { filter: options.filter } : {},
+    stopWhen: options.stopWhen ?? DEFAULT_STOP_WHEN,
+    pauseOnAttention: options.pauseOnAttention ?? true,
+    failFast: options.failFast ?? false,
+    pollMs: Math.max(0, Math.floor(options.pollMs ?? 5000))
+  };
+}
+function selectionMode(policy) {
+  if (policy === "blocking-only")
+    return "blocking-only";
+  if (policy === "max-unblock")
+    return "max-unblock";
+  return "all-ready";
+}
+function dispatchHandle(result) {
+  return typeof result === "string" ? { runId: result } : result;
+}
+function filterTask(task, filter) {
+  if (!filter)
+    return true;
+  if (filter.statuses && !filter.statuses.includes(task.status))
+    return false;
+  if (filter.workspaceIds && !filter.workspaceIds.includes(task.workspaceId))
+    return false;
+  if (filter.assignees) {
+    const raw = task.metadata;
+    const assignee = typeof raw === "object" && raw !== null && "assignee" in raw && typeof raw.assignee === "string" ? raw.assignee : null;
+    if (!assignee || !filter.assignees.includes(assignee))
+      return false;
+  }
+  return true;
+}
+function classifyEmptyReadySet(snapshot, badges, classifyBlocker) {
+  if ((snapshot.diagnostics ?? []).length > 0)
+    return "source-error";
+  const openTasks = snapshot.tasks.filter((task) => !isTaskTerminalStatus(task.status));
+  if (openTasks.length === 0)
+    return "all-done";
+  if (classifyBlocker) {
+    const allHumanBlocked = openTasks.every((task) => HUMAN_BLOCKER_CLASS[classifyBlocker(task, badges).blockerClass]);
+    if (allHumanBlocked)
+      return "all-human-blocked";
+  }
+  return "all-done";
+}
+function terminalFailed(outcome) {
+  return outcome.failed ?? ["failed", "stopped", "needs-attention"].includes(outcome.status);
+}
+async function runSupervisor(ctx, options = {}) {
+  const normalized = normalizeOptions(options);
+  const now = () => (ctx.now?.() ?? new Date).toISOString();
+  const emit = async (event) => {
+    await ctx.emitEvent?.(event);
+  };
+  let processed = 0;
+  let succeeded = 0;
+  let failed = 0;
+  let skipped = 0;
+  let idleReason = null;
+  const completedTaskIds = new Set;
+  await emit({ kind: "supervisor.started", at: now(), options: normalized });
+  while (!ctx.shouldStop?.()) {
+    if (normalized.maxTasks !== null && processed >= normalized.maxTasks) {
+      idleReason = "max-tasks";
+      await emit({ kind: "supervisor.idle", at: now(), reason: idleReason });
+      break;
+    }
+    const snapshot = await ctx.readTasks();
+    const badges = computeTaskDependencyBadges(snapshot.tasks);
+    const activeRuns = snapshot.activeRuns ?? [];
+    const activeTaskIds = activeRuns.map((run) => run.taskId);
+    const remainingSlots = normalized.maxTasks === null ? normalized.concurrency : Math.min(normalized.concurrency, normalized.maxTasks - processed);
+    const ranked = rankReadyTasks(snapshot.tasks, {
+      excludeTaskIds: completedTaskIds,
+      activeTaskIds,
+      filter: (task) => filterTask(task, normalized.filter),
+      selection: selectionMode(normalized.selectionPolicy)
+    });
+    const selected = [];
+    const occupiedScopes = activeRuns.flatMap((run) => {
+      const task = snapshot.tasks.find((candidate) => candidate.id === run.taskId);
+      return task ? readTaskScope(task) : [];
+    });
+    for (const entry of ranked) {
+      if (selected.length >= remainingSlots)
+        break;
+      if (!disjointScope(entry.scope, occupiedScopes))
+        continue;
+      selected.push(entry);
+      occupiedScopes.push(...entry.scope);
+    }
+    await emit({ kind: "supervisor.selection-planned", at: now(), taskIds: selected.map((entry) => entry.task.id), policy: normalized.selectionPolicy });
+    if (selected.length === 0) {
+      idleReason = classifyEmptyReadySet(snapshot, badges, ctx.classifyBlocker);
+      await emit({ kind: "supervisor.idle", at: now(), reason: idleReason });
+      if (normalized.stopWhen.has(idleReason))
+        break;
+      await ctx.waitForChange(normalized.pollMs);
+      continue;
+    }
+    const outcomes = await Promise.all(selected.map(async (entry) => {
+      await emit({ kind: "supervisor.dispatch-started", at: now(), taskId: entry.task.id, score: Math.max(0, Math.floor(entry.score)) });
+      const handle = dispatchHandle(await ctx.dispatch(entry.task));
+      await emit({
+        kind: "supervisor.dispatch-confirmed",
+        at: now(),
+        taskId: entry.task.id,
+        runId: handle.runId,
+        ...handle.dispatchHandle === undefined ? {} : { dispatchHandle: handle.dispatchHandle }
+      });
+      const outcome = await ctx.awaitTerminal(handle.runId, entry.task);
+      const failedOutcome = terminalFailed(outcome);
+      await emit({
+        kind: "supervisor.outcome",
+        at: now(),
+        taskId: entry.task.id,
+        runId: outcome.runId,
+        status: outcome.status,
+        failed: failedOutcome,
+        unblockedTaskIds: outcome.closure?.unblockedTaskIds ?? [],
+        ...outcome.closure ? { closure: outcome.closure } : {}
+      });
+      return { taskId: entry.task.id, status: outcome.status, failed: failedOutcome };
+    }));
+    for (const outcome of outcomes) {
+      completedTaskIds.add(outcome.taskId);
+      processed += 1;
+      if (outcome.failed)
+        failed += 1;
+      else
+        succeeded += 1;
+    }
+    if (normalized.pauseOnAttention && outcomes.some((outcome) => outcome.status === "needs-attention")) {
+      idleReason = "operator-stop";
+      break;
+    }
+    if (normalized.failFast && outcomes.some((outcome) => outcome.failed))
+      break;
+  }
+  if (ctx.shouldStop?.()) {
+    idleReason = "operator-stop";
+    await emit({ kind: "supervisor.stopped", at: now(), reason: idleReason });
+  }
+  await emit({ kind: "supervisor.finished", at: now(), processed, succeeded, failed, skipped, idleReason });
+  return { processed, succeeded, failed, skipped, idleReason };
+}
+export {
+  runSupervisor
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@h-rig/supervisor-plugin",
+  "version": "0.0.6-alpha.133",
+  "type": "module",
+  "description": "First-party autonomous supervisor loop plugin for Rig.",
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    },
+    "./supervisor": {
+      "types": "./dist/src/supervisor.d.ts",
+      "import": "./dist/src/supervisor.js"
+    },
+    "./journal": {
+      "types": "./dist/src/journal.d.ts",
+      "import": "./dist/src/journal.js"
+    },
+    "./closure-stage": {
+      "types": "./dist/src/closureStage.d.ts",
+      "import": "./dist/src/closureStage.js"
+    },
+    "./awaiter": {
+      "types": "./dist/src/awaiter.d.ts",
+      "import": "./dist/src/awaiter.js"
+    },
+    "./plugin": {
+      "types": "./dist/src/plugin.d.ts",
+      "import": "./dist/src/plugin.js"
+    }
+  },
+  "engines": {
+    "bun": ">=1.3.11"
+  },
+  "main": "./dist/src/index.js",
+  "module": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "dependencies": {
+    "@rig/contracts": "npm:@h-rig/contracts@0.0.6-alpha.133",
+    "@rig/core": "npm:@h-rig/core@0.0.6-alpha.133",
+    "effect": "4.0.0-beta.78"
+  }
+}