@stage5/lumine 0.2.56 → 0.2.58

package/lib/sponsor-duty.js

@@ -0,0 +1,1817 @@
+import { execFileSync } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { notifyBuildOwnerOfContribution } from "./api.js";
+import { ensureAuth, resolveAuth, writeAuthFile } from "./auth.js";
+import { readCompleteBuildForumSnapshot } from "./forum.js";
+import { requestJson } from "./http.js";
+import { sleep } from "./util.js";
+import { collectProjectFiles } from "./workspace.js";
+
+const SPONSOR_PATH = "/cli/sponsor";
+const EXECUTION_MODE = "agent_session_v1";
+const STATE_VERSION = 1;
+const PROVIDERS = new Set(["codex", "claude-code"]);
+const PERSONAS = new Set(["zero", "ciel"]);
+const DEFAULT_DUTY_POLL_MS = 3_000;
+const DEFAULT_DUTY_WATCH_MS = 20_000;
+const MAX_DUTY_WATCH_MS = 60_000;
+const MAX_FORUM_CONTEXT_CHARS = 8_000;
+
+export async function sponsorDutyCommand(options, args, commandServices) {
+  const action = String(args[0] || "status")
+    .trim()
+    .toLowerCase();
+  if (action === "status") {
+    if (args.length > 1) throw new Error(sponsorDutyUsage());
+    await printDutyStatus(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)) {
+    await withSponsorStateLock(options, () =>
+      changeDutyState(options, action),
+    );
+    return;
+  }
+  if (action === "watch") {
+    await withSponsorStateLock(options, () =>
+      watchDuty(options, commandServices),
+    );
+    return;
+  }
+  if (action !== "start") throw new Error(sponsorDutyUsage());
+  await withSponsorStateLock(options, () => startDuty(options));
+}
+
+export async function sponsorJobCommand(options, args, commandServices) {
+  const action = String(args[0] || "status")
+    .trim()
+    .toLowerCase();
+  const jobId = positiveInteger(args[1], "Workshop job ID");
+  if (action === "status" || action === "pulse") {
+    assertNoExtraArgs(args, 2);
+    await withSponsorStateLock(options, () => showJob(options, jobId));
+    return;
+  }
+  if (action === "begin") {
+    assertNoExtraArgs(args, 2);
+    await withSponsorStateLock(options, () => beginJob(options, jobId));
+    return;
+  }
+  if (action === "relay-applied") {
+    const relayIds = args
+      .slice(2)
+      .map((value) => positiveInteger(value, "Workshop relay ID"));
+    if (relayIds.length === 0) {
+      throw new Error(
+        "List the approved relay IDs you actually applied to the workspace.",
+      );
+    }
+    await withSponsorStateLock(options, () =>
+      markRelaysApplied(options, jobId, relayIds),
+    );
+    return;
+  }
+  if (action === "helper-start") {
+    assertNoExtraArgs(args, 2);
+    await withSponsorStateLock(options, () => startHelper(options, jobId));
+    return;
+  }
+  if (action === "helper-complete") {
+    assertNoExtraArgs(args, 2);
+    await withSponsorStateLock(options, () =>
+      completeHelper(options, jobId),
+    );
+    return;
+  }
+  if (action === "complete") {
+    assertNoExtraArgs(args, 2);
+    await withSponsorStateLock(options, () =>
+      completeJob(options, jobId, commandServices),
+    );
+    return;
+  }
+  if (action === "fail") {
+    const positionalReason = args.slice(2).join(" ").trim();
+    await withSponsorStateLock(options, () =>
+      failJob(
+        options,
+        jobId,
+        options.sponsorFailureReason || positionalReason,
+      ),
+    );
+    return;
+  }
+  throw new Error(sponsorJobUsage());
+}
+
+async function startDuty(options) {
+  const operatorSession = detectSponsorAgentSession();
+  if (!operatorSession.runtimeVersion) {
+    throw new Error(
+      `Lumine could not verify the active ${displayProvider(operatorSession.provider)} runtime version. Confirm that its CLI is available in this agent session before starting duty.`,
+    );
+  }
+  const provider = normalizeDutyProvider(options.provider, operatorSession);
+  const requestedModel = requiredRuntimeSetting(options.model, "--model", 160);
+  const requestedEffort = requiredRuntimeSetting(
+    options.sponsorEffort,
+    "--effort",
+    40,
+  );
+  if (provider !== "codex" && options.sponsorServiceTier) {
+    throw new Error(
+      "--service-tier is currently supported only for a Codex duty session.",
+    );
+  }
+  const auth = await ensureSponsorAuth(options);
+  const existingState = await readSponsorState(options, { required: false });
+  if (existingState) {
+    await reconcileExistingStateBeforeStart({ options, auth, existingState });
+  }
+  const started = await sponsorRequest({
+    options,
+    auth,
+    method: "POST",
+    path: "/duty/start",
+    body: {
+      scope: "shared",
+      provider,
+      requestedModel,
+      requestedEffort,
+      requestedServiceTier: options.sponsorServiceTier || null,
+      cliVersion: options.lumineCli?.version || null,
+      operatorSession,
+    },
+  });
+  const dutyId = Number(started.duty?.id || 0);
+  const leaseToken = String(started.leaseToken || "");
+  if (!dutyId || !leaseToken || started.duty?.scope !== "shared") {
+    throw new Error("Twinkle did not return a valid shared sponsor duty lease.");
+  }
+  const state = {
+    version: STATE_VERSION,
+    apiUrl: options.apiUrl,
+    sponsorUserId: Number(started.duty.sponsorUserId || auth.userId || 0),
+    operatorSession,
+    duty: {
+      ...started.duty,
+      leaseToken,
+      heartbeatEverySeconds: Number(started.heartbeatEverySeconds || 20),
+    },
+    jobs: {},
+    preservedWorkspaces: [],
+    updatedAt: new Date().toISOString(),
+  };
+  try {
+    await writeSponsorState(options, state);
+  } catch (error) {
+    await sponsorRequest({
+      options,
+      auth,
+      method: "POST",
+      path: "/duty/state",
+      body: { dutySessionId: dutyId, state: "stopped" },
+    }).catch(() => undefined);
+    throw error;
+  }
+  printJsonOrLines(
+    options,
+    {
+      duty: started.duty,
+      executionMode: EXECUTION_MODE,
+      operatorSession: publicOperatorSession(operatorSession),
+      nextCommand: "lumine sponsor duty watch --json",
+    },
+    [
+      `Shared Zero/Ciel sponsor duty #${dutyId} is open under this ${displayProvider(provider)} session.`,
+      `Declared runtime: model=${requestedModel}, effort=${requestedEffort}, service-tier=${options.sponsorServiceTier || "provider default"}.`,
+      "This same live agent session must keep checking in, receive approved plans, and perform the work itself.",
+      "Do not leave an unattended heartbeat running and do not hand jobs to a newly spawned provider process.",
+      "Run `lumine sponsor duty watch` repeatedly to stay present and receive an assignment.",
+    ],
+  );
+}
+
+async function reconcileExistingStateBeforeStart({
+  options,
+  auth,
+  existingState,
+}) {
+  assertSponsorStateAccount(existingState, auth);
+  const status = await sponsorRequest({ options, auth, path: "/status" });
+  const canonicalDuty = (status.duties || []).find(
+    (duty) => Number(duty.id) === Number(existingState.duty.id),
+  );
+  const now = Math.floor(Date.now() / 1_000);
+  const canonicallyOpen =
+    canonicalDuty &&
+    ["active", "paused"].includes(String(canonicalDuty.state || ""));
+  if (canonicallyOpen && Number(canonicalDuty.expiresAt || 0) > now) {
+    throw new Error(
+      `Sponsor duty #${canonicalDuty.id} is still live. Resume it with \`lumine sponsor duty watch\`, or stop it before starting another.`,
+    );
+  }
+  if (canonicallyOpen) {
+    await sponsorRequest({
+      options,
+      auth,
+      method: "POST",
+      path: "/duty/state",
+      body: {
+        dutySessionId: Number(canonicalDuty.id),
+        state: "stopped",
+      },
+    });
+  }
+  const preservedWorkspaces = dutyWorkspacePaths(existingState);
+  if (preservedWorkspaces.length > 0) {
+    const archivePath = await archiveSponsorState(options);
+    console.error(
+      `lumine: preserved the expired duty record at ${archivePath}.`,
+    );
+    for (const workspace of preservedWorkspaces) {
+      console.error(`lumine: preserved expired workspace ${workspace}`);
+    }
+  } else {
+    await removeSponsorState(options);
+  }
+}
+
+async function watchDuty(options, commandServices) {
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  const waitMs = normalizeWatchMs(options.sponsorWaitMs);
+  const deadline = Date.now() + waitMs;
+  let lastDutyHeartbeatAt = 0;
+  let lastJobHeartbeatAt = 0;
+
+  while (true) {
+    const now = Date.now();
+    const dutyEveryMs = Math.max(
+      5_000,
+      Number(state.duty.heartbeatEverySeconds || 15) * 1_000,
+    );
+    if (!lastDutyHeartbeatAt || now - lastDutyHeartbeatAt >= dutyEveryMs) {
+      state = await heartbeatDuty({ options, auth, state });
+      lastDutyHeartbeatAt = Date.now();
+    }
+    if (state.duty.state !== "active") {
+      printJsonOrLines(
+        options,
+        { duty: publicDuty(state.duty), assignment: null },
+        [
+          `Sponsor duty #${state.duty.id} is ${state.duty.state}. Resume it before watching for work.`,
+        ],
+      );
+      return;
+    }
+
+    const jobEveryMs = Math.max(
+      10_000,
+      minimumJobHeartbeatSeconds(state) * 1_000,
+    );
+    if (!lastJobHeartbeatAt || now - lastJobHeartbeatAt >= jobEveryMs) {
+      const relays = await heartbeatAllJobs({ options, auth, state });
+      state = relays.state;
+      lastJobHeartbeatAt = Date.now();
+      if (relays.newRelayCount > 0) {
+        const assignments = activeJobSummaries(state);
+        printJsonOrLines(options, { assignments }, [
+          `Received ${relays.newRelayCount} new approved Workshop follow-up${relays.newRelayCount === 1 ? "" : "s"}.`,
+          ...assignments.map(formatAssignmentLine),
+        ]);
+        return;
+      }
+    }
+
+    const unpreparedJob = Object.values(state.jobs || {}).find(
+      (jobState) => !jobState.preparedAt,
+    );
+    if (unpreparedJob) {
+      const prepared = await prepareClaimedJob({
+        options,
+        auth,
+        state,
+        jobId: Number(unpreparedJob.job.id),
+        commandServices,
+      });
+      state = prepared.state;
+      const assignment = jobSummary(prepared.jobState);
+      printJsonOrLines(options, { assignment }, [
+        `Recovered Workshop job #${assignment.job.id} for this live agent session.`,
+        `Workspace: ${assignment.workspaceDir}`,
+        `Approved assignment: ${assignment.assignmentPath}`,
+        `Begin it with: lumine sponsor job begin ${assignment.job.id}`,
+      ]);
+      return;
+    }
+
+    let claim;
+    try {
+      claim = await sponsorRequest({
+        options,
+        auth,
+        method: "POST",
+        path: "/jobs/claim",
+        body: {
+          dutySessionId: Number(state.duty.id),
+          leaseToken: state.duty.leaseToken,
+          operatorSession: state.operatorSession,
+        },
+      });
+    } catch (error) {
+      if (!isRetryableSponsorRequestError(error)) throw error;
+      if (Date.now() >= deadline) throw error;
+      console.error(
+        `Workshop check-in failed; retrying while this watch is active: ${error?.message || error}`,
+      );
+      await sleep(
+        Math.min(
+          options.sponsorPollMs || DEFAULT_DUTY_POLL_MS,
+          3_000,
+          Math.max(0, deadline - Date.now()),
+        ),
+      );
+      continue;
+    }
+    if (claim.job) {
+      state = await recordClaim({ options, state, claim });
+      const prepared = await prepareClaimedJob({
+        options,
+        auth,
+        state,
+        jobId: Number(claim.job.id),
+        commandServices,
+      });
+      state = prepared.state;
+      const assignment = jobSummary(prepared.jobState);
+      printJsonOrLines(options, { assignment }, [
+        `Workshop job #${assignment.job.id} is assigned to this live ${displayProvider(state.operatorSession.provider)} session.`,
+        `Workspace: ${assignment.workspaceDir}`,
+        `Approved assignment: ${assignment.assignmentPath}`,
+        `Begin it with: lumine sponsor job begin ${assignment.job.id}`,
+      ]);
+      return;
+    }
+    if (Date.now() >= deadline) {
+      printJsonOrLines(
+        options,
+        {
+          duty: publicDuty(state.duty),
+          assignment: null,
+          activeJobs: activeJobSummaries(state),
+          nextCommand: "lumine sponsor duty watch --json",
+        },
+        [
+          `No new Workshop assignment during this ${Math.ceil(waitMs / 1000)}-second watch.`,
+          "Run `lumine sponsor duty watch` again now to remain visibly on duty.",
+        ],
+      );
+      return;
+    }
+    await sleep(
+      Math.min(
+        options.sponsorPollMs || DEFAULT_DUTY_POLL_MS,
+        Math.max(0, deadline - Date.now()),
+      ),
+    );
+  }
+}
+
+async function changeDutyState(options, action) {
+  const auth = await ensureSponsorAuth(options);
+  const status = await sponsorRequest({ options, auth, path: "/status" });
+  const duties = (status.duties || []).filter((duty) =>
+    ["active", "paused"].includes(String(duty.state || "")),
+  );
+  if (duties.length === 0) {
+    if (action === "stop") {
+      const localState = await readSponsorState(options, { required: false });
+      if (!localState) {
+        printJsonOrLines(
+          options,
+          { changed: false, duty: null },
+          ["No active sponsor duty session."],
+        );
+        return;
+      }
+      assertSponsorStateAccount(localState, auth);
+      const preservedWorkspaces = dutyWorkspacePaths(localState);
+      const localArchive =
+        preservedWorkspaces.length > 0
+          ? await archiveSponsorState(options)
+          : null;
+      if (!localArchive) await removeSponsorState(options);
+      printJsonOrLines(
+        options,
+        {
+          changed: false,
+          duty: null,
+          ...(localArchive ? { localArchive, preservedWorkspaces } : {}),
+        },
+        [
+          "No active sponsor duty session.",
+          ...(localArchive
+            ? [
+                `Preserved the expired job record at ${localArchive}.`,
+                ...preservedWorkspaces.map(
+                  (workspace) => `Preserved workspace: ${workspace}`,
+                ),
+              ]
+            : ["Removed the stale local duty record."]),
+        ],
+      );
+      return;
+    }
+    throw new Error("No active sponsor duty session was found.");
+  }
+  if (duties.length > 1) {
+    throw new Error(
+      `Multiple legacy duty sessions remain open (${duties.map((duty) => `#${duty.id}`).join(", ")}). Stop them before using shared duty.`,
+    );
+  }
+  const dutyId = Number(duties[0].id || 0);
+  let localState = await readSponsorState(options, { required: false });
+  if (localState) assertSponsorStateAccount(localState, auth);
+  if (action === "resume") {
+    localState = await loadOwnedState({ options, auth, state: localState });
+    if (Number(localState.duty.id) !== dutyId) {
+      throw new Error("The local agent-session lease does not own this duty.");
+    }
+  }
+  const nextState =
+    action === "resume" ? "active" : action === "stop" ? "stopped" : "paused";
+  const result = await sponsorRequest({
+    options,
+    auth,
+    method: "POST",
+    path: "/duty/state",
+    body: {
+      dutySessionId: dutyId,
+      state: nextState,
+      ...(nextState === "active"
+        ? {
+            dutyLeaseToken: localState.duty.leaseToken,
+            operatorSession: localState.operatorSession,
+          }
+        : {}),
+    },
+  });
+  let localArchive = null;
+  let preservedWorkspaces = [];
+  if (localState && Number(localState.duty?.id) === dutyId) {
+    if (nextState === "stopped") {
+      preservedWorkspaces = dutyWorkspacePaths(localState);
+      if (preservedWorkspaces.length > 0) {
+        localArchive = await archiveSponsorState(options);
+      } else {
+        await removeSponsorState(options);
+      }
+    } else {
+      localState.duty = {
+        ...result.duty,
+        leaseToken: localState.duty.leaseToken,
+        heartbeatEverySeconds: localState.duty.heartbeatEverySeconds,
+      };
+      await writeSponsorState(options, localState);
+    }
+  }
+  printJsonOrLines(
+    options,
+    {
+      ...result,
+      ...(localArchive
+        ? { localArchive, preservedWorkspaces }
+        : {}),
+    },
+    [
+      `Sponsor duty is now ${nextState}.`,
+      ...(localArchive
+        ? [
+            `Preserved the expired job record at ${localArchive}.`,
+            ...preservedWorkspaces.map(
+              (workspace) => `Preserved workspace: ${workspace}`,
+            ),
+          ]
+        : []),
+    ],
+  );
+}
+
+async function showJob(options, jobId) {
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  const refreshed = await heartbeatJob({ options, auth, state, jobId });
+  state = refreshed.state;
+  const jobState = requireJobState(state, jobId);
+  printJsonOrLines(options, jobSummary(jobState), [
+    `Workshop job #${jobId}: ${jobState.job.status}`,
+    `Workspace: ${jobState.workspaceDir}`,
+    `Approved assignment: ${jobState.assignmentPath}`,
+    `${unappliedRelayIds(jobState).length} approved relay(s) still need an explicit applied receipt.`,
+  ]);
+}
+
+async function beginJob(options, jobId) {
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const jobState = requireJobState(state, jobId);
+  if (!jobState.preparedAt) {
+    throw new Error(
+      `Job #${jobId} is not prepared. Run \`lumine sponsor duty watch\` again.`,
+    );
+  }
+  const agent = await ensureCoordinator({ options, auth, state, jobState });
+  jobState.coordinator = agent;
+  await writeSponsorState(options, state);
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const canonicalJobState = requireJobState(state, jobId);
+  printJsonOrLines(options, { job: canonicalJobState.job, coordinator: agent }, [
+    `Workshop job #${jobId} is now being handled by this same on-duty agent session.`,
+    `Apply the approved plan in ${jobState.workspaceDir}.`,
+    `Check in with: lumine sponsor job pulse ${jobId}`,
+  ]);
+}
+
+async function startHelper(options, jobId) {
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const jobState = requireJobState(state, jobId);
+  const coordinator = await ensureCoordinator({
+    options,
+    auth,
+    state,
+    jobState,
+  });
+  jobState.coordinator = coordinator;
+  const ordinal = normalizeHelperOrdinal(options.sponsorAgentOrdinal, jobState);
+  const existing = jobState.helpers?.[String(ordinal)];
+  if (existing) {
+    throw new Error(`Helper ${ordinal} is already registered for job #${jobId}.`);
+  }
+  const helper = await sponsorJobRequest({
+    options,
+    auth,
+    state,
+    jobState,
+    path: "/agents",
+    body: {
+      role: "helper",
+      ordinal,
+      parentAgentId: coordinator.agentId,
+      provider: state.operatorSession.provider,
+      requestedModel: jobState.runtime.requestedModel,
+      requestedEffort: jobState.runtime.requestedEffort,
+      requestedServiceTier: jobState.runtime.requestedServiceTier,
+    },
+  });
+  jobState.helpers = { ...(jobState.helpers || {}), [String(ordinal)]: helper };
+  await writeSponsorState(options, state);
+  printJsonOrLines(options, { helper, jobId }, [
+    `Registered helper ${ordinal} for Workshop job #${jobId}.`,
+    "Spawn and supervise that helper from this agent session; the CLI does not launch a replacement provider.",
+  ]);
+}
+
+async function completeHelper(options, jobId) {
+  const outcome = String(options.sponsorOutcome || "").trim();
+  if (!outcome) {
+    throw new Error("Describe the helper's actual result with --outcome <text>.");
+  }
+  const ordinal = positiveInteger(options.sponsorAgentOrdinal, "--ordinal");
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const jobState = requireJobState(state, jobId);
+  const helper = jobState.helpers?.[String(ordinal)];
+  if (!helper?.agentId) {
+    throw new Error(`Helper ${ordinal} is not registered for job #${jobId}.`);
+  }
+  const result = await completeAgent({
+    options,
+    auth,
+    state,
+    jobState,
+    agent: helper,
+    outcome: {
+      finalText: outcome.slice(0, 2000),
+      changedPaths: [],
+      agentSessionBound: true,
+    },
+  });
+  jobState.helpers[String(ordinal)] = { ...helper, ...result };
+  await writeSponsorState(options, state);
+  printJsonOrLines(options, result, [
+    `Helper ${ordinal} provenance is complete for Workshop job #${jobId}.`,
+  ]);
+}
+
+async function markRelaysApplied(options, jobId, relayIds) {
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const jobState = requireJobState(state, jobId);
+  const availableIds = new Set((jobState.relays || []).map((relay) => Number(relay.id)));
+  if (relayIds.some((relayId) => !availableIds.has(relayId))) {
+    throw new Error(
+      "Every applied relay ID must come from this job's approved assignment.",
+    );
+  }
+  const result = await sponsorJobRequest({
+    options,
+    auth,
+    state,
+    jobState,
+    path: "/relays/applied",
+    body: { relayIds: Array.from(new Set(relayIds)) },
+  });
+  jobState.appliedRelayIds = Array.from(
+    new Set([
+      ...(jobState.appliedRelayIds || []),
+      ...(result.appliedRelayIds || []).map(Number),
+    ]),
+  );
+  await writeAssignment(jobState, state);
+  await writeSponsorState(options, state);
+  printJsonOrLines(options, result, [
+    `Twinkle confirmed ${result.appliedRelayIds?.length || 0} applied relay receipt(s) for job #${jobId}.`,
+  ]);
+}
+
+async function completeJob(options, jobId, commandServices) {
+  const summary = String(options.summary || "").trim();
+  if (!summary) {
+    throw new Error("Summarize the actual completed work with --summary <text>.");
+  }
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const jobState = requireJobState(state, jobId);
+  if (!jobState.coordinator?.agentId) {
+    throw new Error(
+      `Run \`lumine sponsor job begin ${jobId}\` before completing this job.`,
+    );
+  }
+  const unapplied = unappliedRelayIds(jobState);
+  if (unapplied.length > 0) {
+    throw new Error(
+      `Approved relay${unapplied.length === 1 ? "" : "s"} ${unapplied.join(", ")} still need to be applied and acknowledged with \`lumine sponsor job relay-applied ${jobId} <relay-id...>\`.`,
+    );
+  }
+  const closure = await sponsorJobRequest({
+    options,
+    auth,
+    state,
+    jobState,
+    path: "/relays/close",
+  });
+  const newRelayCount = mergeCanonicalRelays(jobState, closure.relays || []);
+  if (!closure.closed) {
+    await writeAssignment(jobState, state);
+    await writeSponsorState(options, state);
+    throw new Error(
+      `${newRelayCount || closure.relays?.length || 1} approved follow-up relay(s) arrived. Read the refreshed assignment, apply them, and acknowledge their IDs before completing.`,
+    );
+  }
+  jobState.relaysClosedAt = Number(closure.closedAt || 0) || true;
+  await writeSponsorState(options, state);
+
+  const jobOptions = jobWorkspaceOptions(options, state, jobState, { summary });
+  const currentFiles = await collectProjectFiles(jobState.workspaceDir);
+  const currentDigest = digestProjectFiles(currentFiles);
+  let savedArtifact = jobState.savedArtifact;
+  if (!savedArtifact || savedArtifact.localFilesDigest !== currentDigest) {
+    const saveResult = await commandServices.saveWorkspace(jobOptions);
+    if (!saveResult?.artifactVersion?.versionId || !saveResult?.filesHash) {
+      throw new Error(
+        "The same-session agent did not produce a new canonical saved artifact for this Workshop job.",
+      );
+    }
+    savedArtifact = {
+      artifactVersionId: Number(saveResult.artifactVersion.versionId),
+      filesHash: String(saveResult.filesHash),
+      localFilesDigest: currentDigest,
+    };
+    jobState.savedArtifact = savedArtifact;
+    await writeSponsorState(options, state);
+  }
+  const changedPaths = listChangedPaths(
+    jobState.initialFileHashes || {},
+    hashProjectFiles(currentFiles),
+  );
+  const coordinatorResult = await completeAgent({
+    options,
+    auth,
+    state,
+    jobState,
+    agent: jobState.coordinator,
+    outcome: {
+      finalText: summary.slice(0, 2000),
+      changedPathCount: changedPaths.length,
+      changedPaths: changedPaths.slice(0, 50),
+      agentSessionBound: true,
+    },
+  });
+  jobState.coordinator = {
+    ...jobState.coordinator,
+    ...coordinatorResult,
+  };
+  await writeSponsorState(options, state);
+
+  const jobAuth = await resolveAuth(jobOptions);
+  const branchNoticeMessageId = await ensureCanonicalBranchNotice({
+    options,
+    auth,
+    state,
+    jobState,
+    jobOptions,
+    jobAuth,
+    outcomeSummary: summary,
+  });
+  const result = await retrySponsorTransport(() =>
+    sponsorJobRequest({
+      options,
+      auth,
+      state,
+      jobState,
+      path: "/complete",
+      body: {
+        artifactVersionId: savedArtifact.artifactVersionId,
+        branchNoticeMessageId,
+        outcomeSummary: summary,
+        reportedFilesHash: savedArtifact.filesHash,
+      },
+    }),
+  );
+  await removeCompletedJob({ options, state, jobId });
+  printJsonOrLines(options, result, [
+    `Completed Workshop job #${jobId}; ${displayPersona(jobState.job.persona)} sent the canonical branch update.`,
+  ]);
+}
+
+async function failJob(options, jobId, rawReason) {
+  const reason = String(rawReason || "").trim();
+  if (!reason) {
+    throw new Error("Explain the concrete failure with --reason <text>.");
+  }
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const jobState = requireJobState(state, jobId);
+  const result = await retrySponsorTransport(() =>
+    sponsorJobRequest({
+      options,
+      auth,
+      state,
+      jobState,
+      path: "/fail",
+      body: {
+        failureCode: "agent_session_failed",
+        failureReason: reason.slice(0, 1000),
+      },
+    }),
+  );
+  const preservedWorkspace = await preserveFailedJobWorkspace({
+    options,
+    state,
+    jobId,
+    reason,
+  });
+  printJsonOrLines(options, { ...result, preservedWorkspace }, [
+    `Workshop job #${jobId} was ended safely.`,
+    `Preserved the unfinished workspace at ${preservedWorkspace}.`,
+  ]);
+}
+
+async function heartbeatDuty({ options, auth, state }) {
+  const duty = await retrySponsorCheckIn(() =>
+    sponsorRequest({
+      options,
+      auth,
+      method: "POST",
+      path: `/duty/${Number(state.duty.id)}/heartbeat`,
+      body: {
+        leaseToken: state.duty.leaseToken,
+        operatorSession: state.operatorSession,
+      },
+    }),
+  );
+  state.duty = {
+    ...duty,
+    leaseToken: state.duty.leaseToken,
+    heartbeatEverySeconds: state.duty.heartbeatEverySeconds,
+  };
+  await writeSponsorState(options, state);
+  return state;
+}
+
+async function heartbeatAllJobs({ options, auth, state }) {
+  let newRelayCount = 0;
+  for (const key of Object.keys(state.jobs || {})) {
+    const jobId = Number(key);
+    const refreshed = await heartbeatJob({ options, auth, state, jobId });
+    state = refreshed.state;
+    newRelayCount += refreshed.newRelayCount;
+  }
+  return { state, newRelayCount };
+}
+
+async function heartbeatJob({ options, auth, state, jobId }) {
+  const jobState = requireJobState(state, jobId);
+  const result = await retrySponsorCheckIn(() =>
+    sponsorJobRequest({
+      options,
+      auth,
+      state,
+      jobState,
+      path: "/heartbeat",
+    }),
+  );
+  jobState.job = result.job;
+  jobState.leaseExpiresAt = Number(result.leaseExpiresAt || 0) || null;
+  const newRelayCount = mergeCanonicalRelays(jobState, result.relays || []);
+  if (newRelayCount > 0 && jobState.preparedAt) {
+    await writeAssignment(jobState, state);
+  }
+  await writeSponsorState(options, state);
+  return { state, newRelayCount };
+}
+
+async function recordClaim({ options, state, claim }) {
+  const jobId = Number(claim.job?.id || 0);
+  const persona = normalizeJobPersona(claim.job?.persona);
+  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.");
+  }
+  if (state.jobs?.[String(jobId)]) {
+    throw new Error(`Workshop job #${jobId} is already recorded locally.`);
+  }
+  const runtime = {
+    provider: String(claim.runtime?.provider || ""),
+    requestedModel: String(claim.runtime?.requestedModel || "").trim(),
+    requestedEffort: String(claim.runtime?.requestedEffort || "").trim(),
+    requestedServiceTier:
+      String(claim.runtime?.requestedServiceTier || "").trim() || null,
+  };
+  if (
+    runtime.provider !== state.operatorSession.provider ||
+    runtime.requestedModel !== String(state.duty.requestedModel || "") ||
+    runtime.requestedEffort !== String(state.duty.requestedEffort || "")
+  ) {
+    throw new Error(
+      "Twinkle returned a Workshop runtime that does not match this live agent session.",
+    );
+  }
+  const tempDir = await fs.mkdtemp(
+    path.join(os.tmpdir(), `lumine-${persona}-job-${jobId}-`),
+  );
+  await fs.chmod(tempDir, 0o700);
+  const jobState = {
+    job: claim.job,
+    attempt: {
+      id: Number(claim.attempt?.id || 0),
+      number: Number(claim.attempt?.number || 0),
+      token: attemptToken,
+    },
+    runtime,
+    relays: Array.isArray(claim.relays) ? claim.relays : [],
+    appliedRelayIds: [],
+    heartbeatEverySeconds: Number(claim.heartbeatEverySeconds || 40),
+    leaseExpiresAt: Number(claim.job?.leaseExpiresAt || 0) || null,
+    workspaceToken: {
+      accessToken: workspaceToken,
+      expiresAt: Number(claim.workspaceToken?.expiresAt || 0),
+      user: claim.workspaceToken?.user || null,
+    },
+    tempDir,
+    workspaceDir: path.join(tempDir, "workspace"),
+    authFile: path.join(tempDir, "job-auth.json"),
+    assignmentPath: path.join(tempDir, "WORKSHOP_ASSIGNMENT.md"),
+    preparedAt: null,
+    initialFileHashes: null,
+    forumContext: "",
+    coordinator: null,
+    helpers: {},
+    savedArtifact: null,
+  };
+  state.jobs = { ...(state.jobs || {}), [String(jobId)]: jobState };
+  await writeSponsorState(options, state);
+  return state;
+}
+
+async function prepareClaimedJob({
+  options,
+  auth,
+  state,
+  jobId,
+  commandServices,
+}) {
+  const jobState = requireJobState(state, jobId);
+  if (jobState.preparedAt) return { state, jobState };
+  if (jobState.workspaceToken?.accessToken) {
+    await writeAuthFile(jobWorkspaceOptions(options, state, jobState), {
+      token: jobState.workspaceToken.accessToken,
+      username:
+        jobState.workspaceToken.user?.username ||
+        displayPersona(jobState.job.persona),
+      userId:
+        jobState.workspaceToken.user?.id || Number(jobState.job.personaUserId),
+      expiresAt: Number(jobState.workspaceToken.expiresAt || 0) * 1_000,
+      apiUrl: options.apiUrl,
+      createdAt: new Date().toISOString(),
+    });
+    jobState.workspaceToken = null;
+    await writeSponsorState(options, state);
+  }
+  const jobOptions = jobWorkspaceOptions(options, state, jobState);
+  const jobAuth = await resolveAuth(jobOptions);
+  await commandServices.pullWorkspace({
+    options: jobOptions,
+    auth: jobAuth,
+    buildId: Number(jobState.job.contributionBuild.id),
+  });
+  jobState.forumContext = await loadForumContext({
+    options: jobOptions,
+    auth: jobAuth,
+    buildId: Number(jobState.job.contributionBuild.id),
+  });
+  jobState.initialFileHashes = hashProjectFiles(
+    await collectProjectFiles(jobState.workspaceDir),
+  );
+  jobState.preparedAt = new Date().toISOString();
+  await writeAssignment(jobState, state);
+  await writeSponsorState(options, state);
+  return { state, jobState };
+}
+
+async function ensureCoordinator({ options, auth, state, jobState }) {
+  if (jobState.coordinator?.agentId) return jobState.coordinator;
+  return await sponsorJobRequest({
+    options,
+    auth,
+    state,
+    jobState,
+    path: "/agents",
+    body: {
+      role: "coordinator",
+      ordinal: 0,
+      parentAgentId: null,
+      provider: state.operatorSession.provider,
+      requestedModel: jobState.runtime.requestedModel,
+      requestedEffort: jobState.runtime.requestedEffort,
+      requestedServiceTier: jobState.runtime.requestedServiceTier,
+    },
+  });
+}
+
+async function completeAgent({
+  options,
+  auth,
+  state,
+  jobState,
+  agent,
+  outcome,
+}) {
+  return await retrySponsorTransport(() =>
+    sponsorJobRequest({
+      options,
+      auth,
+      state,
+      jobState,
+      path: `/agents/${Number(agent.agentId)}/complete`,
+      body: {
+        status: "completed",
+        resolvedModel:
+          options.sponsorResolvedModel || jobState.runtime.requestedModel,
+        resolvedEffort:
+          options.sponsorResolvedEffort || jobState.runtime.requestedEffort,
+        resolvedServiceTier:
+          options.sponsorResolvedServiceTier ||
+          jobState.runtime.requestedServiceTier,
+        runtimeVersion: state.operatorSession.runtimeVersion || null,
+        evidenceTier: "provider_reported",
+        usage: {
+          executionMode: EXECUTION_MODE,
+          agentSessionFingerprintHash:
+            state.operatorSession.fingerprintHash,
+          bindingEvidence: state.operatorSession.bindingEvidence,
+        },
+        outcome,
+      },
+    }),
+  );
+}
+
+async function ensureCanonicalBranchNotice({
+  options,
+  auth,
+  state,
+  jobState,
+  jobOptions,
+  jobAuth,
+  outcomeSummary,
+}) {
+  const lookup = () =>
+    sponsorJobRequest({
+      options,
+      auth,
+      state,
+      jobState,
+      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(jobState.job.rootBuild.id),
+      contributionBuildId: Number(jobState.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;
+  }
+}
+
+async function sponsorJobRequest({
+  options,
+  auth,
+  state,
+  jobState,
+  path: suffix,
+  body = {},
+}) {
+  return await sponsorRequest({
+    options,
+    auth,
+    method: "POST",
+    path: `/jobs/${Number(jobState.job.id)}${suffix}`,
+    body: {
+      dutySessionId: Number(state.duty.id),
+      attemptToken: jobState.attempt.token,
+      operatorSession: state.operatorSession,
+      dutyLeaseToken: state.duty.leaseToken,
+      ...body,
+    },
+  });
+}
+
+async function sponsorRequest({
+  options,
+  auth,
+  method = "GET",
+  path: suffix,
+  body,
+}) {
+  return await requestJson({
+    method,
+    url: `${options.apiUrl}${SPONSOR_PATH}${suffix}`,
+    authToken: auth.token,
+    body,
+    timeoutMs: options.timeoutMs,
+  });
+}
+
+async function ensureSponsorAuth(options) {
+  const auth = await ensureAuth(options);
+  if (Number(auth.userId || 0) > 0) return auth;
+  const session = await requestJson({
+    url: `${options.apiUrl}/cli/session`,
+    authToken: auth.token,
+    timeoutMs: options.timeoutMs,
+  });
+  const userId = Number(session?.userId || 0);
+  if (!Number.isSafeInteger(userId) || userId <= 0) {
+    throw new Error(
+      "Twinkle could not verify which account owns this sponsor duty login.",
+    );
+  }
+  return {
+    ...auth,
+    userId,
+    username: String(session?.username || ""),
+  };
+}
+
+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 retrySponsorCheckIn(operation) {
+  let lastError;
+  for (const delayMs of [0, 250, 750, 1_500]) {
+    if (delayMs) await sleep(delayMs);
+    try {
+      return await operation();
+    } catch (error) {
+      if (!isRetryableSponsorRequestError(error)) throw error;
+      lastError = error;
+    }
+  }
+  throw lastError;
+}
+
+function isRetryableSponsorRequestError(error) {
+  const status = Number(error?.status || 0);
+  if (!status) return true;
+  return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+
+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);
+    return events.length > 0
+      ? JSON.stringify(events).slice(0, MAX_FORUM_CONTEXT_CHARS)
+      : "";
+  } catch (error) {
+    console.error(
+      `lumine: scoped Forum context unavailable (${error?.message || error})`,
+    );
+    return "";
+  }
+}
+
+async function writeAssignment(jobState, state) {
+  const unapplied = new Set(unappliedRelayIds(jobState));
+  const relays = (jobState.relays || [])
+    .map((relay) => {
+      const details = [
+        relay.summary,
+        relay.requestedOutcome ? `What to deliver: ${relay.requestedOutcome}` : "",
+        relay.constraints?.length
+          ? `Constraints: ${relay.constraints.join("; ")}`
+          : "",
+        relay.acceptanceCriteria?.length
+          ? `Done means: ${relay.acceptanceCriteria.join("; ")}`
+          : "",
+      ].filter(Boolean);
+      return `## Relay #${relay.id}${unapplied.has(Number(relay.id)) ? " (not yet acknowledged as applied)" : " (applied receipt confirmed)"}\n\n${details.join("\n\n")}`;
+    })
+    .join("\n\n");
+  const content = `# Lumine Build Workshop assignment #${jobState.job.id}
+
+You are the same live ${displayProvider(state.operatorSession.provider)} agent session that opened sponsor duty. Zero or Ciel is the user's visible teammate; you are lending that teammate an added brain. Perform this work in this session. Do not launch a replacement coding provider or leave an unattended heartbeat process standing in for you.
+
+The user approved sharing only this structured plan, active-job follow-ups, the assigned Build project, and its scoped Forum. Never inspect or infer from their private Zero/Ciel chat. Edit only contribution Build #${jobState.job.contributionBuild.id}; never merge Main, publish, or contact the user directly.
+
+- User: @${jobState.job.requester.username}
+- Visible teammate: ${displayPersona(jobState.job.persona)}
+- Main project: ${jobState.job.rootBuild.title} (#${jobState.job.rootBuild.id})
+- Assigned contribution branch: ${jobState.job.contributionBuild.title} (#${jobState.job.contributionBuild.id})
+- Workspace: ${jobState.workspaceDir}
+
+${relays || "No approved relay text was supplied."}
+
+${jobState.forumContext ? `## Scoped Build Forum snapshot\n\n${jobState.forumContext}\n` : ""}
+## Duty protocol
+
+1. Run \`lumine sponsor job begin ${jobState.job.id}\` before editing.
+2. Work only in the workspace above. Use your native same-session subagents only after registering each with \`helper-start\`. The coordinator alone runs sponsor CLI commands; helpers report their results back to it.
+3. Run \`lumine sponsor job pulse ${jobState.job.id}\` between substantial work steps to keep the lease alive and receive approved follow-ups.
+4. After applying a relay, record its exact ID with \`lumine sponsor job relay-applied ${jobState.job.id} <relay-id...>\`.
+5. Finish with \`lumine sponsor job complete ${jobState.job.id} --summary "..."\`.
+`;
+  await fs.writeFile(jobState.assignmentPath, content, {
+    encoding: "utf8",
+    mode: 0o600,
+  });
+  await fs.chmod(jobState.assignmentPath, 0o600);
+}
+
+function mergeCanonicalRelays(jobState, relays) {
+  const byId = new Map(
+    (jobState.relays || []).map((relay) => [Number(relay.id), relay]),
+  );
+  let newRelayCount = 0;
+  for (const relay of relays) {
+    const relayId = Number(relay?.id || 0);
+    if (!relayId) continue;
+    if (!byId.has(relayId)) newRelayCount += 1;
+    byId.set(relayId, relay);
+  }
+  jobState.relays = Array.from(byId.values()).sort(
+    (a, b) => Number(a.id) - Number(b.id),
+  );
+  return newRelayCount;
+}
+
+function unappliedRelayIds(jobState) {
+  const applied = new Set((jobState.appliedRelayIds || []).map(Number));
+  return (jobState.relays || [])
+    .map((relay) => Number(relay.id))
+    .filter((relayId) => relayId > 0 && !applied.has(relayId));
+}
+
+function jobWorkspaceOptions(options, state, jobState, overrides = {}) {
+  return {
+    ...options,
+    ...overrides,
+    authToken: null,
+    authFile: jobState.authFile,
+    dir: jobState.workspaceDir,
+    target: String(jobState.job.contributionBuild.id),
+    buildIdFlag: String(jobState.job.contributionBuild.id),
+    externalAgentProvider: state.operatorSession.provider,
+    openBrowser: false,
+    quiet: true,
+    publish: false,
+    force: false,
+    skipAssetManifest: true,
+  };
+}
+
+async function loadOwnedState({ options, auth, state = null }) {
+  const loaded = state || (await readSponsorState(options));
+  if (loaded.apiUrl !== options.apiUrl) {
+    throw new Error("The saved sponsor duty belongs to a different Twinkle API.");
+  }
+  assertSponsorStateAccount(loaded, auth);
+  const currentSession = detectSponsorAgentSession();
+  if (
+    currentSession.provider !== loaded.operatorSession?.provider ||
+    currentSession.fingerprintHash !==
+      loaded.operatorSession?.fingerprintHash
+  ) {
+    throw new Error(
+      `Sponsor duty #${loaded.duty?.id || "unknown"} belongs to a different live agent session. Stop it from the sponsor account or return to the session that started it.`,
+    );
+  }
+  return loaded;
+}
+
+export function sponsorDutyStatePath(options) {
+  const authFile = path.resolve(options.authFile);
+  const contextHash = createHash("sha256")
+    .update(String(options.apiUrl || ""))
+    .update("\0")
+    .update(authFile)
+    .digest("hex")
+    .slice(0, 12);
+  return path.join(
+    path.dirname(authFile),
+    `lumine-sponsor-duty-${contextHash}.json`,
+  );
+}
+
+function assertSponsorStateAccount(state, auth) {
+  if (
+    auth.userId &&
+    state?.sponsorUserId &&
+    Number(auth.userId) !== Number(state.sponsorUserId)
+  ) {
+    throw new Error(
+      `The saved sponsor duty belongs to account user ${state.sponsorUserId}. Use a separate --auth-file or return to that account; this login will not alter its lease record.`,
+    );
+  }
+}
+
+async function readSponsorState(options, { required = true } = {}) {
+  const filePath = sponsorDutyStatePath(options);
+  try {
+    const state = JSON.parse(await fs.readFile(filePath, "utf8"));
+    if (
+      Number(state?.version) !== STATE_VERSION ||
+      !state?.duty?.id ||
+      !state?.duty?.leaseToken
+    ) {
+      throw new Error(
+        `The saved sponsor duty state at ${filePath} is invalid. Stop the canonical duty before replacing it.`,
+      );
+    }
+    return state;
+  } catch (error) {
+    if (error.code === "ENOENT" && !required) return null;
+    if (error.code === "ENOENT") {
+      throw new Error(
+        "No local agent-owned duty exists. Start one from the Codex or Claude Code session that will do the work.",
+      );
+    }
+    throw error;
+  }
+}
+
+async function writeSponsorState(options, state) {
+  const filePath = sponsorDutyStatePath(options);
+  const directory = path.dirname(filePath);
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  const nextState = {
+    ...state,
+    updatedAt: new Date().toISOString(),
+  };
+  const temporaryPath = `${filePath}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    await fs.writeFile(temporaryPath, JSON.stringify(nextState, null, 2), {
+      encoding: "utf8",
+      mode: 0o600,
+    });
+    await fs.chmod(temporaryPath, 0o600);
+    await fs.rename(temporaryPath, filePath);
+    await fs.chmod(filePath, 0o600);
+  } finally {
+    await fs.unlink(temporaryPath).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+  }
+}
+
+async function removeSponsorState(options) {
+  await fs.unlink(sponsorDutyStatePath(options)).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
+}
+
+async function withSponsorStateLock(options, operation) {
+  const lockPath = `${sponsorDutyStatePath(options)}.lock`;
+  const lockDirectory = path.dirname(lockPath);
+  await fs.mkdir(lockDirectory, { recursive: true, mode: 0o700 });
+  let handle;
+  try {
+    handle = await fs.open(lockPath, "wx", 0o600);
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    const stale = await sponsorLockIsStale(lockPath);
+    if (!stale) {
+      throw new Error(
+        "Another sponsor duty command is still running for this login. Wait for it to finish instead of starting overlapping watchers or job mutations.",
+      );
+    }
+    await fs.unlink(lockPath);
+    handle = await fs.open(lockPath, "wx", 0o600);
+  }
+  try {
+    await handle.writeFile(
+      JSON.stringify({ pid: process.pid, createdAt: Date.now() }),
+      "utf8",
+    );
+    await handle.chmod(0o600);
+    return await operation();
+  } finally {
+    await handle.close().catch(() => undefined);
+    await fs.unlink(lockPath).catch((error) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+  }
+}
+
+async function sponsorLockIsStale(lockPath) {
+  try {
+    const lock = JSON.parse(await fs.readFile(lockPath, "utf8"));
+    const pid = Number(lock?.pid || 0);
+    if (!Number.isSafeInteger(pid) || pid <= 0) return true;
+    try {
+      process.kill(pid, 0);
+      return false;
+    } catch (error) {
+      return error.code === "ESRCH";
+    }
+  } catch (error) {
+    if (error.code === "ENOENT") return true;
+    return false;
+  }
+}
+
+async function archiveSponsorState(options) {
+  const filePath = sponsorDutyStatePath(options);
+  const archivePath = `${filePath}.stopped-${Date.now()}`;
+  await fs.rename(filePath, archivePath);
+  await fs.chmod(archivePath, 0o600);
+  return archivePath;
+}
+
+async function removeCompletedJob({ options, state, jobId }) {
+  const jobState = requireJobState(state, jobId);
+  const nextJobs = { ...(state.jobs || {}) };
+  delete nextJobs[String(jobId)];
+  state.jobs = nextJobs;
+  await writeSponsorState(options, state);
+  await cleanupJobFiles(jobState).catch((error) => {
+    console.error(
+      `lumine: could not remove completed Workshop directory ${jobState.tempDir} (${error?.message || error})`,
+    );
+  });
+}
+
+async function preserveFailedJobWorkspace({ options, state, jobId, reason }) {
+  const jobState = requireJobState(state, jobId);
+  const nextJobs = { ...(state.jobs || {}) };
+  delete nextJobs[String(jobId)];
+  state.jobs = nextJobs;
+  state.preservedWorkspaces = [
+    ...(Array.isArray(state.preservedWorkspaces)
+      ? state.preservedWorkspaces.filter(
+          (item) => String(item?.workspaceDir || "") !== jobState.workspaceDir,
+        )
+      : []),
+    {
+      jobId,
+      workspaceDir: jobState.workspaceDir,
+      reason: reason.slice(0, 1000),
+      preservedAt: new Date().toISOString(),
+    },
+  ];
+  await writeSponsorState(options, state);
+  return jobState.workspaceDir;
+}
+
+function dutyWorkspacePaths(state) {
+  return Array.from(
+    new Set(
+      [
+        ...Object.values(state.jobs || {}).map((jobState) =>
+          String(jobState.workspaceDir || ""),
+        ),
+        ...(Array.isArray(state.preservedWorkspaces)
+          ? state.preservedWorkspaces.map((item) =>
+              String(item?.workspaceDir || ""),
+            )
+          : []),
+      ].filter(Boolean),
+    ),
+  );
+}
+
+async function cleanupJobFiles(jobState) {
+  const tempRoot = path.resolve(os.tmpdir());
+  const tempDir = path.resolve(String(jobState?.tempDir || ""));
+  if (
+    !tempDir.startsWith(`${tempRoot}${path.sep}`) ||
+    !path.basename(tempDir).startsWith("lumine-") ||
+    !path.basename(tempDir).includes("-job-")
+  ) {
+    throw new Error("Refused to remove an unrecognized Workshop directory.");
+  }
+  await fs.rm(tempDir, { recursive: true, force: true });
+}
+
+export function detectSponsorAgentSession({
+  environment = process.env,
+  ancestry = null,
+} = {}) {
+  const codexSessionId = firstNonEmpty(
+    environment.CODEX_SESSION_ID,
+    environment.CODEX_THREAD_ID,
+  );
+  const claudeSessionId = firstNonEmpty(
+    environment.CLAUDE_CODE_SESSION_ID,
+    environment.CLAUDE_SESSION_ID,
+    environment.CLAUDE_RUNNER_SESSION_ID,
+    environment.CLAUDE_CODE_REMOTE_SESSION_ID,
+  );
+  const detectedAncestry = ancestry || readAgentProcessAncestry();
+  if (codexSessionId && claudeSessionId) {
+    throw new Error(
+      "Lumine found both Codex and Claude Code session IDs. Start duty from a single, directly owning agent session.",
+    );
+  }
+  const codexIdentity = claudeSessionId
+    ? null
+    : codexSessionId || detectedAncestry.codex || null;
+  const claudeIdentity = codexSessionId
+    ? null
+    : claudeSessionId ||
+      (String(environment.CLAUDECODE || "").trim() === "1"
+        ? detectedAncestry.claude
+        : null) ||
+      detectedAncestry.claude ||
+      null;
+  if (codexIdentity && claudeIdentity) {
+    throw new Error(
+      "Lumine found both Codex and Claude Code session signals. Start duty from a single, directly owning agent session.",
+    );
+  }
+  const provider = codexIdentity
+    ? "codex"
+    : claudeIdentity
+      ? "claude-code"
+      : null;
+  const identity = codexIdentity || claudeIdentity;
+  if (!provider || !identity) {
+    throw new Error(
+      "Sponsor duty must be started from an active Codex or Claude Code agent session; a standalone terminal or background supervisor cannot advertise Workshop availability.",
+    );
+  }
+  const bindingEvidence =
+    (provider === "codex" && codexSessionId) ||
+    (provider === "claude-code" && claudeSessionId)
+      ? "runtime_session_id"
+      : "agent_process_ancestry";
+  return {
+    mode: EXECUTION_MODE,
+    provider,
+    fingerprintHash: createHash("sha256")
+      .update(`lumine-sponsor-agent-session\0${provider}\0${identity}`)
+      .digest("hex"),
+    bindingEvidence,
+    runtimeVersion: detectAgentRuntimeVersion(provider),
+  };
+}
+
+function readAgentProcessAncestry() {
+  const found = { codex: null, claude: null };
+  let currentPid = process.ppid;
+  const visited = new Set();
+  for (let depth = 0; depth < 12 && currentPid > 1; depth += 1) {
+    if (visited.has(currentPid)) break;
+    visited.add(currentPid);
+    try {
+      const line = execFileSync(
+        "ps",
+        ["-o", "pid=,ppid=,comm=", "-p", String(currentPid)],
+        { encoding: "utf8", timeout: 2_000 },
+      ).trim();
+      const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.+)$/);
+      if (!match) break;
+      const pid = Number(match[1]);
+      const parentPid = Number(match[2]);
+      const command = path.basename(String(match[3] || "").trim()).toLowerCase();
+      if (!found.claude && (command === "claude" || command.startsWith("claude-"))) {
+        found.claude = `process:${pid}`;
+      }
+      if (!found.codex && (command === "codex" || command.startsWith("codex-"))) {
+        found.codex = `process:${pid}`;
+      }
+      currentPid = parentPid;
+    } catch {
+      break;
+    }
+  }
+  return found;
+}
+
+function detectAgentRuntimeVersion(provider) {
+  const binary = provider === "claude-code" ? "claude" : "codex";
+  try {
+    return String(
+      execFileSync(binary, ["--version"], {
+        encoding: "utf8",
+        timeout: 5_000,
+        stdio: ["ignore", "pipe", "ignore"],
+      }),
+    )
+      .trim()
+      .slice(0, 64) || null;
+  } catch {
+    return null;
+  }
+}
+
+function normalizeDutyProvider(value, operatorSession) {
+  const supplied = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (supplied && !PROVIDERS.has(supplied)) {
+    throw new Error("Pass --provider codex or --provider claude-code.");
+  }
+  if (supplied && supplied !== operatorSession.provider) {
+    throw new Error(
+      `This is a ${displayProvider(operatorSession.provider)} session, so it cannot advertise ${displayProvider(supplied)} duty.`,
+    );
+  }
+  return operatorSession.provider;
+}
+
+function requiredRuntimeSetting(value, flag, maximum) {
+  const setting = String(value || "").trim();
+  if (!setting) {
+    throw new Error(
+      `${flag} is required so the actual on-duty agent runtime is recorded.`,
+    );
+  }
+  if (setting.length > maximum) {
+    throw new Error(`${flag} is too long.`);
+  }
+  return setting;
+}
+
+function normalizeHelperOrdinal(value, jobState) {
+  const limit = Math.max(0, Number(jobState.job.requestedSubagents || 0));
+  if (limit === 0) {
+    throw new Error("This duty capacity does not allow helpers for this job.");
+  }
+  if (value !== undefined && value !== null && value !== "") {
+    const ordinal = positiveInteger(value, "--ordinal");
+    if (ordinal > limit) {
+      throw new Error(`--ordinal cannot exceed this job's helper limit (${limit}).`);
+    }
+    return ordinal;
+  }
+  for (let ordinal = 1; ordinal <= limit; ordinal += 1) {
+    if (!jobState.helpers?.[String(ordinal)]) return ordinal;
+  }
+  throw new Error(`All ${limit} helper slot(s) are already registered.`);
+}
+
+function normalizeWatchMs(value) {
+  const selected = Number(value || DEFAULT_DUTY_WATCH_MS);
+  if (!Number.isSafeInteger(selected) || selected < 1_000) {
+    throw new Error("--wait-ms must be an integer of at least 1000.");
+  }
+  return Math.min(selected, MAX_DUTY_WATCH_MS);
+}
+
+function positiveInteger(value, label) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number <= 0) {
+    throw new Error(`${label} must be a positive integer.`);
+  }
+  return number;
+}
+
+function assertNoExtraArgs(args, maximum) {
+  if (args.length > maximum) throw new Error(sponsorJobUsage());
+}
+
+function requireJobState(state, jobId) {
+  const jobState = state.jobs?.[String(jobId)];
+  if (!jobState) {
+    throw new Error(
+      `Workshop job #${jobId} is not assigned to this local agent session.`,
+    );
+  }
+  return jobState;
+}
+
+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 minimumJobHeartbeatSeconds(state) {
+  const values = Object.values(state.jobs || {})
+    .map((jobState) => Number(jobState.heartbeatEverySeconds || 40))
+    .filter((value) => Number.isFinite(value) && value > 0);
+  return values.length > 0 ? Math.min(...values) : 40;
+}
+
+function hashProjectFiles(files) {
+  return Object.fromEntries(
+    files.map((file) => [
+      String(file.path),
+      createHash("sha256").update(String(file.content || "")).digest("hex"),
+    ]),
+  );
+}
+
+function digestProjectFiles(files) {
+  const hash = createHash("sha256");
+  for (const file of files) {
+    hash.update(String(file.path));
+    hash.update("\0");
+    hash.update(String(file.content || ""));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function listChangedPaths(before, after) {
+  return Array.from(new Set([...Object.keys(before), ...Object.keys(after)]))
+    .filter((filePath) => before[filePath] !== after[filePath])
+    .sort();
+}
+
+function publicOperatorSession(session) {
+  return {
+    mode: session.mode,
+    provider: session.provider,
+    bindingEvidence: session.bindingEvidence,
+    runtimeVersion: session.runtimeVersion || null,
+    fingerprint: session.fingerprintHash.slice(0, 12),
+  };
+}
+
+function publicDuty(duty) {
+  const { leaseToken: _leaseToken, ...visibleDuty } = duty || {};
+  return visibleDuty;
+}
+
+function jobSummary(jobState) {
+  return {
+    job: jobState.job,
+    workspaceDir: jobState.workspaceDir,
+    assignmentPath: jobState.assignmentPath,
+    relays: jobState.relays || [],
+    appliedRelayIds: jobState.appliedRelayIds || [],
+    unappliedRelayIds: unappliedRelayIds(jobState),
+    coordinator: jobState.coordinator || null,
+    helpers: Object.values(jobState.helpers || {}),
+  };
+}
+
+function activeJobSummaries(state) {
+  return Object.values(state.jobs || {}).map(jobSummary);
+}
+
+function formatAssignmentLine(assignment) {
+  return `Job #${assignment.job.id}: ${assignment.assignmentPath}`;
+}
+
+function displayPersona(persona) {
+  return String(persona || "").toLowerCase() === "ciel" ? "Ciel" : "Zero";
+}
+
+function displayProvider(provider) {
+  return provider === "claude-code" ? "Claude Code" : "Codex";
+}
+
+function firstNonEmpty(...values) {
+  for (const value of values) {
+    const normalized = String(value || "").trim();
+    if (normalized) return normalized;
+  }
+  return null;
+}
+
+async function printDutyStatus(options) {
+  const auth = await ensureSponsorAuth(options);
+  const status = await sponsorRequest({ options, auth, path: "/status" });
+  if (options.json) {
+    console.log(JSON.stringify(status, null, 2));
+    return;
+  }
+  const active = (status.duties || []).filter((duty) =>
+    ["active", "paused"].includes(String(duty.state || "")),
+  );
+  if (active.length === 0) {
+    console.log("No active sponsor duty session.");
+    return;
+  }
+  for (const duty of active) {
+    console.log(
+      `Duty #${duty.id}: ${duty.state} · ${duty.provider} · model=${duty.requestedModel || "missing"} · effort=${duty.requestedEffort || "missing"}`,
+    );
+  }
+}
+
+function printJsonOrLines(options, value, lines) {
+  if (options.json) console.log(JSON.stringify(value, null, 2));
+  else for (const line of lines) console.log(line);
+}
+
+function sponsorDutyUsage() {
+  return [
+    "Usage:",
+    "  lumine sponsor duty start [--provider <codex|claude-code>] --model <name> --effort <level> [--service-tier <tier>]",
+    "  lumine sponsor duty watch [--wait-ms <1000-60000>] [--json]",
+    "  lumine sponsor duty status|pause|resume|stop",
+  ].join("\n");
+}
+
+function sponsorJobUsage() {
+  return [
+    "Usage:",
+    "  lumine sponsor job status|pulse <job-id>",
+    "  lumine sponsor job begin <job-id>",
+    "  lumine sponsor job relay-applied <job-id> <relay-id...>",
+    "  lumine sponsor job helper-start <job-id> [--ordinal <n>]",
+    "  lumine sponsor job helper-complete <job-id> --ordinal <n> --outcome <text> [--resolved-model <name>] [--resolved-effort <level>]",
+    "  lumine sponsor job complete <job-id> --summary <text> [--resolved-model <name>] [--resolved-effort <level>] [--resolved-service-tier <tier>]",
+    "  lumine sponsor job fail <job-id> --reason <text>",
+  ].join("\n");
+}