@stage5/lumine 0.2.56 → 0.2.58

package/lib/sponsor.js

@@ -1,22 +1,15 @@
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 
-import { agentCommand } from "./agent.js";
-import { notifyBuildOwnerOfContribution } from "./api.js";
-import { ensureAuth, resolveAuth, writeAuthFile } from "./auth.js";
-import { readCompleteBuildForumSnapshot } from "./forum.js";
+import { ensureAuth } from "./auth.js";
+import {
+  sponsorDutyCommand,
+  sponsorJobCommand,
+} from "./sponsor-duty.js";
 import { requestJson } from "./http.js";
-import { sleep } from "./util.js";
 
 const SPONSOR_PATH = "/cli/sponsor";
 const PROVIDERS = new Set(["codex", "claude-code"]);
-const PERSONAS = new Set(["zero", "ciel"]);
-const DEFAULT_DUTY_POLL_MS = 3_000;
-const MAX_FORUM_CONTEXT_CHARS = 8_000;
-const MAX_FOLLOW_UP_PASSES = 4;
 
 export async function sponsorCommand(options, commandServices) {
   const args = options.sponsorArgs || [];
@@ -24,6 +17,12 @@ export async function sponsorCommand(options, commandServices) {
     .trim()
     .toLowerCase();
   if (area === "agreement") {
+    if (String(args[1] || "").trim().toLowerCase() === "accept") {
+      if (args.length > 2) throw new Error(sponsorUsage());
+      await acceptSponsorAgreement(options);
+      return;
+    }
+    if (args.length > 1) throw new Error(sponsorUsage());
     const auth = await ensureAuth(options);
     const agreement = await sponsorRequest({
       options,
@@ -49,6 +48,10 @@ export async function sponsorCommand(options, commandServices) {
     await sponsorDutyCommand(options, args.slice(1), commandServices);
     return;
   }
+  if (area === "job") {
+    await sponsorJobCommand(options, args.slice(1), commandServices);
+    return;
+  }
   if (area === "jobs") {
     const auth = await ensureAuth(options);
     const result = await sponsorRequest({
@@ -66,6 +69,42 @@ export async function sponsorCommand(options, commandServices) {
   throw new Error(sponsorUsage());
 }
 
+async function acceptSponsorAgreement(options) {
+  const auth = await ensureAuth(options);
+  const agreement = await sponsorRequest({ options, auth, path: "/agreement" });
+  if (!options.json) {
+    printSponsorAgreement(agreement, { ...options, json: false });
+  }
+  const interactive = Boolean(input.isTTY && output.isTTY);
+  let accepted = options.sponsorAcceptAgreement;
+  if (!accepted && interactive) {
+    const rl = readline.createInterface({ input, output });
+    try {
+      accepted = await confirmExactAgreement(rl);
+    } finally {
+      rl.close();
+    }
+  }
+  if (!accepted) {
+    throw new Error(
+      "Explicit acceptance is required. Re-run with --accept-agreement after reading the current agreement.",
+    );
+  }
+  const result = await sponsorRequest({
+    options,
+    auth,
+    method: "POST",
+    path: "/agreement/accept",
+    body: {
+      agreementVersion: agreement.version,
+      agreementAccepted: true,
+    },
+  });
+  printJsonOrLines(options, result, [
+    `Sponsor agreement ${result.agreementVersion} accepted.`,
+  ]);
+}
+
 async function applyToSponsor(options) {
   const auth = await ensureAuth(options);
   const agreement = await sponsorRequest({ options, auth, path: "/agreement" });
@@ -207,932 +246,6 @@ async function updateSponsorCapacity(options) {
   ]);
 }
 
-async function sponsorDutyCommand(options, args, commandServices) {
-  const action = String(args[0] || "status")
-    .trim()
-    .toLowerCase();
-  if (action === "status") {
-    if (args.length > 1) throw new Error(sponsorUsage());
-    await printSponsorStatus(options);
-    return;
-  }
-  if (args.length > 1 || options.sponsorPersona) {
-    throw new Error(
-      "Sponsor duty is shared by Zero and Ciel. Remove the persona argument.",
-    );
-  }
-  if (["pause", "resume", "stop"].includes(action)) {
-    const auth = await ensureAuth(options);
-    const status = await sponsorRequest({ options, auth, path: "/status" });
-    const currentDuties = (status.duties || []).filter((duty) =>
-      ["active", "paused"].includes(String(duty.state || "")),
-    );
-    if (currentDuties.length === 0) {
-      throw new Error("No active sponsor duty session was found.");
-    }
-    if (currentDuties.length > 1) {
-      throw new Error(
-        `Multiple legacy duty sessions are still open (${currentDuties.map((duty) => `#${duty.id}`).join(", ")}). Stop them with the CLI version that started them before using shared duty.`,
-      );
-    }
-    const dutyId = Number(currentDuties[0].id || 0);
-    if (!dutyId) throw new Error("Twinkle returned an invalid duty session.");
-    const state =
-      action === "resume" ? "active" : action === "stop" ? "stopped" : "paused";
-    const result = await sponsorRequest({
-      options,
-      auth,
-      method: "POST",
-      path: "/duty/state",
-      body: { dutySessionId: dutyId, state },
-    });
-    printJsonOrLines(options, result, [`Sponsor duty is now ${state}.`]);
-    return;
-  }
-  if (action !== "start") throw new Error(sponsorUsage());
-  if (options.json) {
-    throw new Error("A foreground sponsor duty cannot run with --json.");
-  }
-  const provider = normalizeProvider(options.provider);
-  if (provider !== "codex" && options.sponsorServiceTier) {
-    throw new Error(
-      "--service-tier is currently supported only by the Codex duty adapter.",
-    );
-  }
-  const auth = await ensureAuth(options);
-  const started = await sponsorRequest({
-    options,
-    auth,
-    method: "POST",
-    path: "/duty/start",
-    body: {
-      scope: "shared",
-      provider,
-      requestedModel: options.model || null,
-      requestedEffort: options.sponsorEffort || null,
-      requestedServiceTier: options.sponsorServiceTier || null,
-      cliVersion: options.lumineCli?.version || null,
-    },
-  });
-  await runSponsorDuty({
-    options,
-    auth,
-    provider,
-    started,
-    commandServices,
-  });
-}
-
-async function runSponsorDuty({
-  options,
-  auth,
-  provider,
-  started,
-  commandServices,
-}) {
-  const dutyId = Number(started.duty?.id || 0);
-  const leaseToken = String(started.leaseToken || "");
-  if (!dutyId || !leaseToken) {
-    throw new Error("Twinkle did not return a valid sponsor duty lease.");
-  }
-  if (started.duty?.scope !== "shared") {
-    throw new Error("Twinkle did not return a shared sponsor duty lease.");
-  }
-  let canonicalDuty = started.duty;
-  let stopRequested = false;
-  let dutyLeaseError = null;
-  let dutyHeartbeatRunning = false;
-  const activeJobs = new Set();
-  const signalHandler = () => {
-    if (!stopRequested) {
-      stopRequested = true;
-      console.log("\nStopping after active Workshop jobs finish...");
-    }
-  };
-  process.on("SIGINT", signalHandler);
-  process.on("SIGTERM", signalHandler);
-
-  const heartbeatDuty = async () => {
-    if (dutyHeartbeatRunning) return;
-    dutyHeartbeatRunning = true;
-    try {
-      canonicalDuty = await sponsorRequest({
-        options,
-        auth,
-        method: "POST",
-        path: `/duty/${dutyId}/heartbeat`,
-        body: { leaseToken },
-      });
-      dutyLeaseError = null;
-      if (canonicalDuty.state === "stopped") stopRequested = true;
-    } catch (error) {
-      const status = await sponsorRequest({
-        options,
-        auth,
-        path: "/status",
-      }).catch(() => null);
-      const confirmedDuty = (status?.duties || []).find(
-        (duty) => Number(duty.id) === dutyId,
-      );
-      if (confirmedDuty?.state === "stopped") {
-        canonicalDuty = confirmedDuty;
-        dutyLeaseError = null;
-        stopRequested = true;
-        return;
-      }
-      dutyLeaseError = error;
-      stopRequested = true;
-    } finally {
-      dutyHeartbeatRunning = false;
-    }
-  };
-  const dutyHeartbeat = setInterval(
-    () => void heartbeatDuty(),
-    Math.max(10, Number(started.heartbeatEverySeconds || 30)) * 1_000,
-  );
-
-  console.log(`Shared Zero/Ciel sponsor duty started with ${provider}.`);
-  printDutyRuntime(canonicalDuty);
-  console.log(
-    "The Workshop is now discoverable to users. Press Ctrl-C for a graceful stop.",
-  );
-
-  try {
-    while (!stopRequested) {
-      if (canonicalDuty.state !== "active") {
-        await sleep(options.sponsorPollMs || DEFAULT_DUTY_POLL_MS);
-        continue;
-      }
-      const concurrency = Math.max(
-        1,
-        Number(canonicalDuty.capacity?.maxConcurrentTasks || 1),
-      );
-      while (!stopRequested && activeJobs.size < concurrency) {
-        const claim = await sponsorRequest({
-          options,
-          auth,
-          method: "POST",
-          path: "/jobs/claim",
-          body: { dutySessionId: dutyId, leaseToken },
-        });
-        if (!claim.job) break;
-        const work = processSponsorJob({
-          options,
-          sponsorAuth: auth,
-          dutyId,
-          dutyLeaseToken: leaseToken,
-          provider,
-          claim,
-          commandServices,
-        })
-          .catch((error) => {
-            console.error(
-              `Workshop job #${claim.job.id} ended: ${error?.message || error}`,
-            );
-          })
-          .finally(() => activeJobs.delete(work));
-        activeJobs.add(work);
-      }
-      await sleep(options.sponsorPollMs || DEFAULT_DUTY_POLL_MS);
-    }
-    if (!dutyLeaseError && canonicalDuty.state === "active") {
-      const paused = await sponsorRequest({
-        options,
-        auth,
-        method: "POST",
-        path: "/duty/state",
-        body: { dutySessionId: dutyId, state: "paused" },
-      });
-      canonicalDuty = paused.duty || canonicalDuty;
-    }
-    await Promise.allSettled(Array.from(activeJobs));
-    if (dutyLeaseError) throw dutyLeaseError;
-  } finally {
-    clearInterval(dutyHeartbeat);
-    process.off("SIGINT", signalHandler);
-    process.off("SIGTERM", signalHandler);
-    if (canonicalDuty.state !== "stopped") {
-      await sponsorRequest({
-        options,
-        auth,
-        method: "POST",
-        path: "/duty/state",
-        body: { dutySessionId: dutyId, state: "stopped" },
-      }).catch((error) => {
-        if (!dutyLeaseError) {
-          console.error(
-            `Could not mark duty stopped: ${error?.message || error}`,
-          );
-        }
-      });
-    }
-  }
-  console.log("Shared Zero/Ciel sponsor duty stopped.");
-}
-
-async function processSponsorJob({
-  options,
-  sponsorAuth,
-  dutyId,
-  dutyLeaseToken,
-  provider,
-  claim,
-  commandServices,
-}) {
-  const job = claim.job;
-  const persona = normalizeJobPersona(job?.persona);
-  const jobId = Number(job.id);
-  const attemptToken = String(claim.attempt?.token || "");
-  const workspaceToken = String(claim.workspaceToken?.accessToken || "");
-  if (!jobId || !attemptToken || !workspaceToken) {
-    throw new Error("Twinkle returned an incomplete Workshop job lease.");
-  }
-  const runtime = {
-    provider: String(claim.runtime?.provider || ""),
-    requestedModel: String(claim.runtime?.requestedModel || "").trim() || null,
-    requestedEffort:
-      String(claim.runtime?.requestedEffort || "").trim() || null,
-    requestedServiceTier:
-      String(claim.runtime?.requestedServiceTier || "").trim() || null,
-  };
-  if (!PROVIDERS.has(runtime.provider) || runtime.provider !== provider) {
-    throw new Error(
-      "Twinkle returned a Workshop runtime that does not match this duty.",
-    );
-  }
-  const relayById = new Map(
-    (claim.relays || []).map((relay) => [relay.id, relay]),
-  );
-  let heartbeatError = null;
-  let heartbeatRunning = false;
-  const jobAbortController = new AbortController();
-  const heartbeatEveryMs =
-    Math.max(10, Number(claim.heartbeatEverySeconds || 30)) * 1_000;
-  let lastHeartbeatSuccessAt = Date.now();
-  const abortWorkerIfLeaseIsGone = (error) => {
-    const status = Number(error?.status || 0);
-    const serverRejectedLease = [401, 403, 409].includes(status);
-    const leaseWindowElapsed =
-      Date.now() - lastHeartbeatSuccessAt >=
-      Math.max(120_000, heartbeatEveryMs * 3);
-    if (
-      !jobAbortController.signal.aborted &&
-      (serverRejectedLease || leaseWindowElapsed)
-    ) {
-      jobAbortController.abort(
-        error instanceof Error
-          ? error
-          : new Error("The sponsored Workshop lease ended."),
-      );
-    }
-  };
-  const heartbeatJob = async () => {
-    if (heartbeatRunning) return null;
-    heartbeatRunning = true;
-    try {
-      const result = await sponsorJobRequest({
-        options,
-        sponsorAuth,
-        dutyId,
-        dutyLeaseToken,
-        jobId,
-        attemptToken,
-        path: "/heartbeat",
-      });
-      heartbeatError = null;
-      lastHeartbeatSuccessAt = Date.now();
-      for (const relay of result.relays || []) relayById.set(relay.id, relay);
-      return result;
-    } catch (error) {
-      heartbeatError = error;
-      abortWorkerIfLeaseIsGone(error);
-      return null;
-    } finally {
-      heartbeatRunning = false;
-    }
-  };
-  const tempDir = await fs.mkdtemp(
-    path.join(os.tmpdir(), `lumine-${persona}-job-${jobId}-`),
-  );
-  const workspaceDir = path.join(tempDir, "workspace");
-  const authFile = path.join(tempDir, "job-auth.json");
-  const jobOptions = {
-    ...options,
-    authToken: null,
-    authFile,
-    dir: workspaceDir,
-    target: String(job.contributionBuild.id),
-    buildIdFlag: String(job.contributionBuild.id),
-    provider: runtime.provider,
-    model: runtime.requestedModel || "",
-    agentEffort: runtime.requestedEffort || "",
-    serviceTier: runtime.requestedServiceTier || "",
-    agentAbortSignal: jobAbortController.signal,
-    reviewLoop: false,
-    openBrowser: false,
-    skipAssetManifest: true,
-  };
-  // Do not start a long-lived lease timer until the owned temporary workspace
-  // exists. If temp creation fails there is then no interval keeping the duty
-  // process alive after this job promise rejects.
-  const heartbeatTimer = setInterval(
-    () => void heartbeatJob(),
-    heartbeatEveryMs,
-  );
-  const logicalAgents = [];
-  let lastSave = null;
-
-  console.log(
-    `Claimed Workshop job #${jobId} for ${job.requester.username || `user ${job.requester.userId}`} (${job.contributionBuild.title}).`,
-  );
-  try {
-    await writeAuthFile(jobOptions, {
-      token: workspaceToken,
-      username: claim.workspaceToken?.user?.username || displayPersona(persona),
-      userId: claim.workspaceToken?.user?.id || job.personaUserId,
-      expiresAt: Number(claim.workspaceToken?.expiresAt || 0) * 1_000,
-      apiUrl: options.apiUrl,
-      createdAt: new Date().toISOString(),
-    });
-    const jobAuth = await resolveAuth(jobOptions);
-    await commandServices.pullWorkspace({
-      options: jobOptions,
-      auth: jobAuth,
-      buildId: Number(job.contributionBuild.id),
-    });
-    const forumContext = await loadForumContext({
-      options: jobOptions,
-      auth: jobAuth,
-      buildId: Number(job.contributionBuild.id),
-    });
-    const coordinator = await startLogicalAgent({
-      options,
-      sponsorAuth,
-      dutyId,
-      jobId,
-      attemptToken,
-      runtime,
-      role: "coordinator",
-      ordinal: 0,
-      parentAgentId: null,
-    });
-    logicalAgents.push(coordinator);
-    const appliedRelayIds = new Set();
-    const coordinatorResults = [];
-    const initialRelays = Array.from(relayById.values());
-    const initialResult = await runWorkshopAgentPass({
-      jobOptions,
-      saveWorkspace: commandServices.saveWorkspace,
-      job,
-      persona,
-      relays: initialRelays,
-      forumContext,
-      helperOrdinal: 0,
-    });
-    coordinatorResults.push(initialResult);
-    await acknowledgeRelaysApplied({
-      options,
-      sponsorAuth,
-      dutyId,
-      jobId,
-      attemptToken,
-      relays: initialRelays,
-      appliedRelayIds,
-    });
-    lastSave = initialResult.saveResult || lastSave;
-
-    const helperCount = Math.max(0, Number(job.requestedSubagents || 0));
-    for (let ordinal = 1; ordinal <= helperCount; ordinal += 1) {
-      await heartbeatJob();
-      if (heartbeatError) throw heartbeatError;
-      const helper = await startLogicalAgent({
-        options,
-        sponsorAuth,
-        dutyId,
-        jobId,
-        attemptToken,
-        runtime,
-        role: "helper",
-        ordinal,
-        parentAgentId: coordinator.agentId,
-      });
-      logicalAgents.push(helper);
-      try {
-        const helperRelays = Array.from(relayById.values());
-        const helperResult = await runWorkshopAgentPass({
-          jobOptions,
-          saveWorkspace: commandServices.saveWorkspace,
-          job,
-          persona,
-          relays: helperRelays,
-          forumContext,
-          helperOrdinal: ordinal,
-        });
-        await acknowledgeRelaysApplied({
-          options,
-          sponsorAuth,
-          dutyId,
-          jobId,
-          attemptToken,
-          relays: helperRelays,
-          appliedRelayIds,
-        });
-        lastSave = helperResult.saveResult || lastSave;
-        await completeLogicalAgent({
-          options,
-          sponsorAuth,
-          dutyId,
-          jobId,
-          attemptToken,
-          agent: helper,
-          status: "completed",
-          results: [helperResult],
-        });
-        helper.completed = true;
-      } catch (error) {
-        await completeLogicalAgent({
-          options,
-          sponsorAuth,
-          dutyId,
-          jobId,
-          attemptToken,
-          agent: helper,
-          status: "failed",
-          results: [],
-          error,
-        }).catch(() => undefined);
-        helper.completed = true;
-        throw error;
-      }
-    }
-
-    let relayStreamClosed = false;
-    for (let pass = 0; pass < MAX_FOLLOW_UP_PASSES; pass += 1) {
-      await heartbeatJob();
-      if (heartbeatError) throw heartbeatError;
-      const pendingRelays = Array.from(relayById.values()).filter(
-        (relay) => !appliedRelayIds.has(relay.id),
-      );
-      if (pendingRelays.length > 0) {
-        const followUpResult = await runWorkshopAgentPass({
-          jobOptions,
-          saveWorkspace: commandServices.saveWorkspace,
-          job,
-          persona,
-          relays: pendingRelays,
-          forumContext: "",
-          helperOrdinal: 0,
-          isFollowUp: true,
-        });
-        coordinatorResults.push(followUpResult);
-        await acknowledgeRelaysApplied({
-          options,
-          sponsorAuth,
-          dutyId,
-          jobId,
-          attemptToken,
-          relays: pendingRelays,
-          appliedRelayIds,
-        });
-        lastSave = followUpResult.saveResult || lastSave;
-      }
-      const closure = await retrySponsorTransport(() =>
-        sponsorJobRequest({
-          options,
-          sponsorAuth,
-          dutyId,
-          jobId,
-          attemptToken,
-          path: "/relays/close",
-        }),
-      );
-      for (const relay of closure.relays || []) relayById.set(relay.id, relay);
-      if (closure.closed) {
-        relayStreamClosed = true;
-        break;
-      }
-    }
-    if (!relayStreamClosed) {
-      throw new Error(
-        "The Workshop kept receiving follow-ups and could not close a fully applied relay stream safely.",
-      );
-    }
-
-    await completeLogicalAgent({
-      options,
-      sponsorAuth,
-      dutyId,
-      jobId,
-      attemptToken,
-      agent: coordinator,
-      status: "completed",
-      results: coordinatorResults,
-    });
-    coordinator.completed = true;
-    if (!lastSave?.artifactVersion?.versionId || !lastSave?.filesHash) {
-      throw new Error(
-        "The agent did not produce a new canonical saved artifact for this Workshop job.",
-      );
-    }
-    const outcomeSummary = summarizeWorkshopOutcome(
-      coordinatorResults.at(-1)?.finalText,
-      job,
-    );
-    const branchNoticeMessageId = await ensureCanonicalBranchNotice({
-      options,
-      sponsorAuth,
-      dutyId,
-      jobId,
-      attemptToken,
-      jobOptions,
-      jobAuth,
-      job,
-      outcomeSummary,
-    });
-    await retrySponsorTransport(() =>
-      sponsorJobRequest({
-        options,
-        sponsorAuth,
-        dutyId,
-        jobId,
-        attemptToken,
-        path: "/complete",
-        body: {
-          artifactVersionId: Number(lastSave.artifactVersion.versionId),
-          branchNoticeMessageId,
-          outcomeSummary,
-          reportedFilesHash: lastSave.filesHash,
-        },
-      }),
-    );
-    console.log(
-      `Completed Workshop job #${jobId}; ${displayPersona(persona)} sent the branch update.`,
-    );
-  } catch (error) {
-    for (const agent of logicalAgents.filter((item) => !item.completed)) {
-      await completeLogicalAgent({
-        options,
-        sponsorAuth,
-        dutyId,
-        jobId,
-        attemptToken,
-        agent,
-        status: "failed",
-        results: [],
-        error,
-      }).catch(() => undefined);
-      agent.completed = true;
-    }
-    await retrySponsorTransport(() =>
-      sponsorJobRequest({
-        options,
-        sponsorAuth,
-        dutyId,
-        jobId,
-        attemptToken,
-        path: "/fail",
-        body: {
-          failureCode: "worker_failed",
-          failureReason: String(error?.message || error).slice(0, 1000),
-        },
-      }),
-    ).catch(() => undefined);
-    throw error;
-  } finally {
-    clearInterval(heartbeatTimer);
-    try {
-      await fs.rm(tempDir, { recursive: true, force: true });
-    } catch (error) {
-      console.error(
-        `lumine: could not remove temporary Workshop directory ${tempDir} (${error?.message || error})`,
-      );
-    }
-  }
-}
-
-async function runWorkshopAgentPass({
-  jobOptions,
-  saveWorkspace,
-  job,
-  persona,
-  relays,
-  forumContext,
-  helperOrdinal,
-  isFollowUp = false,
-}) {
-  const prompt = workshopAgentPrompt({
-    job,
-    persona,
-    relays,
-    forumContext,
-    helperOrdinal,
-    isFollowUp,
-  });
-  return await agentCommand(
-    { ...jobOptions, agentPrompt: prompt },
-    { saveWorkspace },
-  );
-}
-
-async function startLogicalAgent({
-  options,
-  sponsorAuth,
-  dutyId,
-  jobId,
-  attemptToken,
-  runtime,
-  role,
-  ordinal,
-  parentAgentId,
-}) {
-  return await retrySponsorTransport(() =>
-    sponsorJobRequest({
-      options,
-      sponsorAuth,
-      dutyId,
-      jobId,
-      attemptToken,
-      path: "/agents",
-      body: {
-        role,
-        ordinal,
-        parentAgentId,
-        provider: runtime.provider,
-        requestedModel: runtime.requestedModel,
-        requestedEffort: runtime.requestedEffort,
-        requestedServiceTier: runtime.requestedServiceTier,
-      },
-    }),
-  );
-}
-
-async function completeLogicalAgent({
-  options,
-  sponsorAuth,
-  dutyId,
-  jobId,
-  attemptToken,
-  agent,
-  status,
-  results,
-  error = null,
-}) {
-  const provenance = summarizeProviderRuns(results);
-  const allChangedPaths = Array.from(
-    new Set(results.flatMap((result) => result.changedPaths || [])),
-  );
-  return await retrySponsorTransport(() =>
-    sponsorJobRequest({
-      options,
-      sponsorAuth,
-      dutyId,
-      jobId,
-      attemptToken,
-      path: `/agents/${agent.agentId}/complete`,
-      body: {
-        status,
-        resolvedModel: provenance.resolvedModel,
-        resolvedEffort: provenance.resolvedEffort,
-        resolvedServiceTier: provenance.resolvedServiceTier,
-        runtimeVersion: provenance.runtimeVersion,
-        evidenceTier: provenance.evidenceTier,
-        usage: provenance.usage,
-        outcome: {
-          providerPassCount: provenance.providerPassCount,
-          changedPathCount: allChangedPaths.length,
-          changedPaths: allChangedPaths
-            .map((changedPath) => String(changedPath || "").slice(0, 300))
-            .filter(Boolean)
-            .slice(0, 50),
-          finalText: String(results.at(-1)?.finalText || "").slice(0, 2000),
-          ...(error
-            ? { error: String(error?.message || error).slice(0, 1000) }
-            : {}),
-        },
-      },
-    }),
-  );
-}
-
-async function acknowledgeRelaysApplied({
-  options,
-  sponsorAuth,
-  dutyId,
-  jobId,
-  attemptToken,
-  relays,
-  appliedRelayIds,
-}) {
-  const relayIds = Array.from(
-    new Set(relays.map((relay) => Number(relay.id)).filter((id) => id > 0)),
-  );
-  if (relayIds.length === 0) return;
-  for (let index = 0; index < relayIds.length; index += 50) {
-    const relayIdBatch = relayIds.slice(index, index + 50);
-    const receipt = await retrySponsorTransport(() =>
-      sponsorJobRequest({
-        options,
-        sponsorAuth,
-        dutyId,
-        jobId,
-        attemptToken,
-        path: "/relays/applied",
-        body: { relayIds: relayIdBatch },
-      }),
-    );
-    const canonicalIds = new Set(
-      (receipt.appliedRelayIds || []).map((relayId) => Number(relayId)),
-    );
-    if (relayIdBatch.some((relayId) => !canonicalIds.has(relayId))) {
-      throw new Error("Twinkle did not confirm every applied Workshop relay.");
-    }
-    for (const relayId of canonicalIds) appliedRelayIds.add(relayId);
-  }
-}
-
-async function ensureCanonicalBranchNotice({
-  options,
-  sponsorAuth,
-  dutyId,
-  jobId,
-  attemptToken,
-  jobOptions,
-  jobAuth,
-  job,
-  outcomeSummary,
-}) {
-  const lookup = () =>
-    sponsorJobRequest({
-      options,
-      sponsorAuth,
-      dutyId,
-      jobId,
-      attemptToken,
-      path: "/branch-notice",
-    });
-  const existing = await lookup();
-  const existingMessageId = Number(existing.branchNotice?.id || 0);
-  if (existingMessageId) return existingMessageId;
-
-  try {
-    const notice = await notifyBuildOwnerOfContribution({
-      options: jobOptions,
-      auth: jobAuth,
-      rootBuildId: Number(job.rootBuild.id),
-      contributionBuildId: Number(job.contributionBuild.id),
-      note: outcomeSummary,
-    });
-    const messageId = Number(notice?.message?.id || 0);
-    if (!messageId) {
-      throw new Error("Twinkle did not confirm the branch update message.");
-    }
-    return messageId;
-  } catch (error) {
-    for (const delayMs of [250, 750, 1_500]) {
-      await sleep(delayMs);
-      const recovered = await lookup().catch(() => null);
-      const recoveredMessageId = Number(recovered?.branchNotice?.id || 0);
-      if (recoveredMessageId) return recoveredMessageId;
-    }
-    throw error;
-  }
-}
-
-function summarizeProviderRuns(results) {
-  const runs = results.flatMap((result) => result.providerRuns || []);
-  const lastRun = runs.at(-1) || {};
-  const valueFromLastRun = (key, maximum) =>
-    String(lastRun?.[key] || "")
-      .trim()
-      .slice(0, maximum) || null;
-  const evidenceTiers = runs.map((run) => run?.evidenceTier);
-  const evidenceTier =
-    evidenceTiers.length > 0 &&
-    evidenceTiers.every((tier) => tier === "runtime_observed")
-      ? "runtime_observed"
-      : evidenceTiers.length > 0 &&
-          evidenceTiers.every((tier) =>
-            ["runtime_observed", "provider_reported"].includes(tier),
-          )
-        ? "provider_reported"
-        : "requested_only";
-  return {
-    resolvedModel: valueFromLastRun("resolvedModel", 160),
-    resolvedEffort: valueFromLastRun("resolvedEffort", 40),
-    resolvedServiceTier: valueFromLastRun("resolvedServiceTier", 40),
-    runtimeVersion: valueFromLastRun("runtimeVersion", 64),
-    evidenceTier,
-    providerPassCount: runs.length,
-    usage: {
-      passes: runs.slice(0, 20).map((run) => ({
-        phase: run.phase || null,
-        resolvedModel: run.resolvedModel || null,
-        resolvedEffort: run.resolvedEffort || null,
-        resolvedServiceTier: run.resolvedServiceTier || null,
-        runtimeVersion: run.runtimeVersion || null,
-        evidenceTier: run.evidenceTier || "requested_only",
-        usage: run.usage || {},
-      })),
-    },
-  };
-}
-
-async function loadForumContext({ options, auth, buildId }) {
-  try {
-    const snapshot = await readCompleteBuildForumSnapshot({
-      options: { ...options, limit: 100 },
-      auth,
-      buildId,
-      maxPages: 100,
-    });
-    const events = (snapshot.events || []).slice(-50);
-    if (events.length === 0) return "";
-    return JSON.stringify(events).slice(0, MAX_FORUM_CONTEXT_CHARS);
-  } catch (error) {
-    console.error(
-      `lumine: scoped Forum context unavailable (${error?.message || error})`,
-    );
-    return "";
-  }
-}
-
-function workshopAgentPrompt({
-  job,
-  persona,
-  relays,
-  forumContext,
-  helperOrdinal,
-  isFollowUp,
-}) {
-  const relayText = relays
-    .map((relay, index) => {
-      const details = [
-        relay.summary,
-        relay.requestedOutcome ? `Outcome: ${relay.requestedOutcome}` : "",
-        relay.constraints?.length
-          ? `Constraints: ${relay.constraints.join("; ")}`
-          : "",
-        relay.acceptanceCriteria?.length
-          ? `Acceptance: ${relay.acceptanceCriteria.join("; ")}`
-          : "",
-      ].filter(Boolean);
-      return `${index + 1}. ${details.join("\n   ")}`;
-    })
-    .join("\n");
-  const role =
-    helperOrdinal > 0
-      ? `You are helper ${helperOrdinal}. Review the current implementation and fix concrete gaps.`
-      : isFollowUp
-        ? "Apply these newly relayed follow-up requirements to the current implementation."
-        : `Implement this hands-on Lumine Build request on ${displayPersona(persona)}'s assigned contribution branch.`;
-  return `${role}
-
-The user owns Build #${job.rootBuild.id}; you may edit only contribution Build #${job.contributionBuild.id}. Do not merge, replace Main, publish, contact the user directly, or infer anything from private chat. The text below is the structured relay explicitly approved for this named sponsor. Preserve existing sound UX and leave a complete, validated project.
-
-Approved relay:
-${relayText || "No additional relay text was supplied."}
-${forumContext ? `\nScoped Build Forum snapshot (project-visible context only):\n${forumContext}\n` : ""}
-Return a short factual outcome summary after saving the canonical branch.`;
-}
-
-async function sponsorJobRequest({
-  options,
-  sponsorAuth,
-  dutyId,
-  dutyLeaseToken,
-  jobId,
-  attemptToken,
-  path: suffix,
-  body = {},
-}) {
-  return await sponsorRequest({
-    options,
-    auth: sponsorAuth,
-    method: "POST",
-    path: `/jobs/${jobId}${suffix}`,
-    body: {
-      dutySessionId: dutyId,
-      attemptToken,
-      ...(dutyLeaseToken ? { dutyLeaseToken } : {}),
-      ...body,
-    },
-  });
-}
-
-async function retrySponsorTransport(operation) {
-  let lastError;
-  for (const delayMs of [0, 250, 750, 1_500]) {
-    if (delayMs) await sleep(delayMs);
-    try {
-      return await operation();
-    } catch (error) {
-      if (Number(error?.status || 0) > 0) throw error;
-      lastError = error;
-    }
-  }
-  throw lastError;
-}
-
 async function sponsorRequest({
   options,
   auth,
@@ -1158,6 +271,14 @@ async function printSponsorStatus(options) {
   }
   console.log(`Application: ${status.application?.status || "not submitted"}`);
   console.log(`Sponsor access: ${status.sponsor?.status || "not approved"}`);
+  if (
+    status.sponsor &&
+    status.application?.agreementVersion !== status.agreementVersion
+  ) {
+    console.log(
+      `Agreement update required: read version ${status.agreementVersion} with \`lumine sponsor agreement\`, then accept it before starting duty.`,
+    );
+  }
   if (status.sponsor?.capacity) {
     const capacity = status.sponsor.capacity;
     console.log(
@@ -1173,7 +294,7 @@ async function printSponsorStatus(options) {
         ? "shared Zero/Ciel"
         : `legacy assistant user ${duty.personaUserId}`;
     console.log(
-      `Duty #${duty.id}: ${scope} · ${duty.state} · ${duty.provider} · model=${duty.requestedModel || "provider default"} · effort=${duty.requestedEffort || "provider default"}`,
+      `Duty #${duty.id}: ${scope} · ${duty.state} · ${duty.provider} · model=${duty.requestedModel || "missing"} · effort=${duty.requestedEffort || "missing"}`,
     );
   }
 }
@@ -1203,15 +324,6 @@ function printSponsorJobs(jobs, options) {
   }
 }
 
-function printDutyRuntime(duty) {
-  console.log(
-    `Runtime: model=${duty.requestedModel || "provider default"}, effort=${duty.requestedEffort || "provider default"}, service-tier=${duty.requestedServiceTier || "provider default"}`,
-  );
-  console.log(
-    `Limits: ${duty.capacity?.maxConcurrentTasks || 1} concurrent, ${duty.capacity?.maxSubagentsPerTask || 0} helpers, ${duty.capacity?.dailyTaskLimit || 0}/day, ${duty.capacity?.weeklyTaskLimit || 0}/week`,
-  );
-}
-
 function printJsonOrLines(options, value, lines) {
   if (options.json) console.log(JSON.stringify(value, null, 2));
   else for (const line of lines) console.log(line);
@@ -1232,7 +344,7 @@ async function requiredApplicationText({ supplied, label, interactive, rl }) {
 
 async function confirmExactAgreement(rl) {
   const answer = await rl.question(
-    "Type I ACCEPT to confirm this agreement and submit the application: ",
+    "Type I ACCEPT to confirm this sponsor agreement: ",
   );
   return answer.trim() === "I ACCEPT";
 }
@@ -1262,50 +374,27 @@ function normalizeProviderList(value) {
   return Array.from(new Set(submitted));
 }
 
-function normalizeProvider(value) {
-  const provider = String(value || "")
-    .trim()
-    .toLowerCase();
-  if (!PROVIDERS.has(provider)) {
-    throw new Error("Pass --provider codex or --provider claude-code.");
-  }
-  return provider;
-}
-
-function normalizeJobPersona(value) {
-  const persona = String(value || "")
-    .trim()
-    .toLowerCase();
-  if (!PERSONAS.has(persona)) {
-    throw new Error("Twinkle returned an invalid Workshop job assistant.");
-  }
-  return persona;
-}
-
 function displayPersona(persona) {
   return String(persona || "").toLowerCase() === "ciel" ? "Ciel" : "Zero";
 }
 
-function summarizeWorkshopOutcome(finalText, job) {
-  const summary = String(finalText || "")
-    .trim()
-    .slice(0, 1000);
-  return (
-    summary ||
-    `Updated ${job.rootBuild.title} on the assigned contribution branch.`
-  );
-}
-
 function sponsorUsage() {
   return [
     "Usage:",
     "  lumine sponsor agreement",
+    "  lumine sponsor agreement accept [--accept-agreement]",
     "  lumine sponsor apply --providers codex[,claude-code] [--motivation <text>] [--availability <text>] [--accept-agreement]",
     "  lumine sponsor status",
     "  lumine sponsor withdraw [--yes]",
     "  lumine sponsor capacity [--concurrency <n>] [--helpers <n>] [--daily-limit <n>] [--weekly-limit <n>]",
-    "  lumine sponsor duty start --provider <codex|claude-code> [--model <name>] [--effort <level>] [--service-tier <tier>]",
-    "  lumine sponsor duty pause|resume|stop",
+    "  lumine sponsor duty start [--provider <codex|claude-code>] --model <name> --effort <level> [--service-tier <tier>]",
+    "  lumine sponsor duty watch [--wait-ms <ms>] [--json]",
+    "  lumine sponsor duty status|pause|resume|stop",
+    "  lumine sponsor job status|pulse|begin <job-id>",
+    "  lumine sponsor job relay-applied <job-id> <relay-id...>",
+    "  lumine sponsor job helper-start|helper-complete <job-id> [options]",
+    "  lumine sponsor job complete <job-id> --summary <text>",
+    "  lumine sponsor job fail <job-id> --reason <text>",
     "  lumine sponsor jobs [--limit <n>]",
   ].join("\n");
 }