@stage5/lumine 0.2.66 → 0.2.68

package/lib/sponsor-duty.js

@@ -1,5 +1,6 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -10,6 +11,10 @@ import { requestJson } from "./http.js";
 import { sleep } from "./util.js";
 import { collectProjectFiles } from "./workspace.js";
 
+const ACTIVE_JOB_STATUSES = new Set(["leased", "working", "waiting_user"]);
+// Colliding duty commands wait this long for the state lock before failing.
+const SPONSOR_LOCK_WAIT_MS = 15_000;
+
 const SPONSOR_PATH = "/cli/sponsor";
 const EXECUTION_MODE = "agent_session_v2";
 const STATE_VERSION = 2;
@@ -61,7 +66,8 @@ export async function sponsorDutyCommand(options, args, commandServices) {
     return;
   }
   if (action !== "start") throw new Error(sponsorDutyUsage());
-  await withSponsorStateLock(options, () => startDuty(options));
+  const startOptions = { ...options, sponsorStateForStart: true };
+  await withSponsorStateLock(startOptions, () => startDuty(startOptions));
 }
 
 export async function sponsorJobCommand(options, args, commandServices) {
@@ -112,6 +118,43 @@ export async function sponsorJobCommand(options, args, commandServices) {
     );
     return;
   }
+  if (action === "sync-main") {
+    assertNoExtraArgs(args, 2);
+    await withSponsorStateLock(options, () =>
+      syncJobFromMain(options, jobId, commandServices),
+    );
+    return;
+  }
+  if (action === "assets") {
+    await withSponsorStateLock(options, () =>
+      jobAssets(options, jobId, args.slice(2), commandServices),
+    );
+    return;
+  }
+  if (action === "hold") {
+    assertNoExtraArgs(args, 2);
+    await holdJobLease(options, jobId);
+    return;
+  }
+  if (action === "rename" || action === "describe") {
+    await withSponsorStateLock(options, () =>
+      jobDetails(options, jobId, action, args.slice(2).join(" "), commandServices),
+    );
+    return;
+  }
+  if (action === "suggest") {
+    assertNoExtraArgs(args, 3);
+    await withSponsorStateLock(options, () =>
+      jobSuggest(options, jobId, String(args[2] || ""), commandServices),
+    );
+    return;
+  }
+  if (action === "thumbnail") {
+    await withSponsorStateLock(options, () =>
+      jobThumbnail(options, jobId, args.slice(2), commandServices),
+    );
+    return;
+  }
   if (action === "complete") {
     assertNoExtraArgs(args, 2);
     await withSponsorStateLock(options, () =>
@@ -215,7 +258,7 @@ async function startDuty(options) {
       `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.",
+      "The CLI keeps a lease keeper for each job you begin in this session; never hand jobs to a newly spawned provider process.",
       "Run `lumine sponsor duty watch` repeatedly to stay present and receive an assignment.",
     ],
   );
@@ -543,12 +586,6 @@ async function changeDutyState(options, action) {
     }
     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);
   const localRecord =
     action === "stop"
       ? await readSponsorStateForStop(options)
@@ -558,6 +595,20 @@ async function changeDutyState(options, action) {
           invalidState: null,
         };
   let localState = localRecord.state;
+  // A sponsor may keep several live sessions on duty (a pool). This session
+  // acts on the duty its own local record names; only without a local
+  // record is more than one open duty ambiguous.
+  const localDutyId = Number(localState?.duty?.id || 0);
+  const ownDuty =
+    localDutyId > 0
+      ? duties.find((duty) => Number(duty.id) === localDutyId)
+      : null;
+  if (!ownDuty && duties.length > 1) {
+    throw new Error(
+      `Multiple duty sessions remain open (${duties.map((duty) => `#${duty.id}`).join(", ")}) and this session owns none of them. Run this from the session that started the duty you want to change.`,
+    );
+  }
+  const dutyId = Number((ownDuty || duties[0]).id || 0);
   if (localState) assertSponsorStateAccount(localState, auth);
   const preservesAnotherAccountState =
     sponsorStateBelongsToAnotherAccount(localRecord.invalidState, auth);
@@ -668,17 +719,20 @@ async function beginJob(options, jobId) {
   }
   const agent = await ensureCoordinator({ options, auth, state, jobState });
   jobState.coordinator = agent;
+  if (!options.sponsorNoLeaseKeeper) startJobLeaseKeeper({ options, state, jobState });
   await writeSponsorState(options, state);
   ({ state } = await heartbeatJob({ options, auth, state, jobId }));
   const canonicalJobState = requireJobState(state, jobId);
   const consultation = isConsultationJob(jobState);
-  printJsonOrLines(options, { job: canonicalJobState.job, coordinator: agent }, [
+  printJsonOrLines(options, { job: canonicalJobState.job, coordinator: agent, leaseKeeperPid: canonicalJobState.keeperPid || null }, [
     `Workshop job #${jobId} is now being handled by this same on-duty agent session.`,
     consultation
       ? `Inspect the approved project in ${jobState.workspaceDir} without editing it, then answer the approved question.`
       : `Apply the approved plan in ${jobState.workspaceDir}.`,
     `Introduce yourself to ${displayPersona(jobState.job.persona)} as Lumine with: lumine sponsor job update ${jobId} --file <message-file> --phase starting`,
-    `Check in with: lumine sponsor job pulse ${jobId}`,
+    canonicalJobState.keeperPid
+      ? `A lease keeper (pid ${canonicalJobState.keeperPid}) checks in for this session while you work; still run lumine sponsor job pulse ${jobId} between steps to read approved follow-ups.`
+      : `No lease keeper runs for this session; run lumine sponsor job pulse ${jobId} at least every few minutes and between steps.`,
   ]);
 }
 
@@ -693,6 +747,10 @@ async function publishDialogueUpdate(options, jobId) {
   if (phase.length > 40) {
     throw new Error("--phase must be at most 40 characters.");
   }
+  const kind = String(options.sponsorUpdateKind || "progress").trim().toLowerCase();
+  if (kind !== "progress" && kind !== "question") {
+    throw new Error("--kind must be progress (default) or question.");
+  }
   const messagePath = path.resolve(messageFile);
   const messageStat = await fs.stat(messagePath);
   if (!messageStat.isFile() || messageStat.size > 8_000) {
@@ -721,6 +779,7 @@ async function publishDialogueUpdate(options, jobId) {
           clientUpdateKey,
           phase: phase || null,
           message,
+          kind,
         },
       }),
     options.signal,
@@ -729,11 +788,44 @@ async function publishDialogueUpdate(options, jobId) {
     throw new Error("Twinkle did not confirm the canonical Lumine update.");
   }
   printJsonOrLines(options, result, [
-    `Lumine → ${displayPersona(jobState.job.persona)}:`,
+    `Lumine → ${displayPersona(jobState.job.persona)}${kind === "question" ? " (question for the user)" : ""}:`,
     result.update.message,
+    ...(kind === "question"
+      ? [`The answer arrives as an approved follow-up relay: keep running lumine sponsor job pulse ${jobId} and read the refreshed assignment.`]
+      : []),
+  ]);
+}
+
+// Title and description of the approved workspace, under the job identity.
+async function jobDetails(options, jobId, field, text, commandServices) {
+  const value = String(text || "").trim();
+  if (!value) throw new Error(`Usage: lumine sponsor job ${field} <job-id> <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 (isConsultationJob(jobState)) {
+    throw new Error("A read-only consultation cannot change project details.");
+  }
+  if (jobState.job?.targetBuild?.kind !== "main") {
+    throw new Error(
+      "Title and description belong to the project's Main; a branch keeps the original details.",
+    );
+  }
+  const fn = field === "rename" ? commandServices?.renameBuild : commandServices?.describeBuild;
+  if (typeof fn !== "function") throw new Error("This Lumine CLI build cannot update job project details.");
+  const jobOptions = jobWorkspaceOptions(options, state, jobState, {
+    json: false,
+    positional: [],
+    ...(field === "rename" ? { title: value } : { description: value, descriptionProvided: true, noDescription: false }),
+  });
+  const output = await runJobScopedCommand(options, jobOptions, (o) => fn(o));
+  printJsonOrLines(options, { job: jobState.job, [field]: value, output }, [
+    field === "rename" ? `Workshop job #${jobId}: project renamed to "${value}".` : `Workshop job #${jobId}: project description updated.`,
   ]);
 }
 
+
 async function startHelper(options, jobId) {
   const auth = await ensureSponsorAuth(options);
   let state = await loadOwnedState({ options, auth });
@@ -840,6 +932,269 @@ async function markRelaysApplied(options, jobId, relayIds) {
   ]);
 }
 
+// Runs the branch's Main sync under the job identity so the server can
+// advance the job's restore point to the merged snapshot. Only editing jobs
+// on a requester-owned branch can sync.
+async function syncJobFromMain(options, jobId, commandServices) {
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const jobState = requireJobState(state, jobId);
+  if (isConsultationJob(jobState)) {
+    throw new Error("A read-only consultation never changes the branch.");
+  }
+  if (jobState.job?.targetBuild?.kind !== "branch") {
+    throw new Error(
+      "Only a requester-owned branch can be updated from Main; this job targets Main itself.",
+    );
+  }
+  if (typeof commandServices?.updateFromMain !== "function") {
+    throw new Error("This Lumine CLI build cannot sync a job branch from Main.");
+  }
+  const jobOptions = jobWorkspaceOptions(options, state, jobState, {
+    json: false,
+    quiet: Boolean(options.quiet),
+  });
+  // The shared update-from-main printer writes plain lines; keep --json
+  // output pure by collecting them into the result instead.
+  const syncLines = [];
+  const originalLog = console.log;
+  if (options.json) console.log = (...parts) => syncLines.push(parts.join(" "));
+  try {
+    await commandServices.updateFromMain(jobOptions);
+  } finally {
+    console.log = originalLog;
+  }
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const refreshed = requireJobState(state, jobId);
+  refreshed.initialFileHashes = hashProjectFiles(
+    await collectProjectFiles(refreshed.workspaceDir),
+  );
+  await writeAssignment(refreshed, state);
+  await writeSponsorState(options, state);
+  printJsonOrLines(options, { job: refreshed.job, sync: syncLines }, [
+    `Workshop job #${jobId}: branch synced from Main under the job identity.`,
+    `Restore point is now ${refreshed.job?.restorePoint ? `artifact version #${refreshed.job.restorePoint.versionNumber || refreshed.job.restorePoint.artifactVersionId}` : "unchanged"}.`,
+  ]);
+}
+
+// Uploads generated media into the approved workspace's asset space under
+// the job identity (the requester's own uploads for that build).
+async function jobAssets(options, jobId, args, commandServices) {
+  const sub = String(args[0] || "").trim().toLowerCase();
+  const files = args.slice(1);
+  if (sub !== "upload" || files.length === 0) {
+    throw new Error(
+      `Usage: lumine sponsor job assets ${jobId} upload <file...>`,
+    );
+  }
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const jobState = requireJobState(state, jobId);
+  if (isConsultationJob(jobState)) {
+    throw new Error("A read-only consultation cannot add assets.");
+  }
+  if (typeof commandServices?.uploadAssets !== "function") {
+    throw new Error("This Lumine CLI build cannot upload job assets.");
+  }
+  const jobOptions = jobWorkspaceOptions(options, state, jobState, {
+    json: Boolean(options.json),
+    quiet: false,
+    positional: ["upload", ...files],
+    skipAssetManifest: false,
+  });
+  await commandServices.uploadAssets(jobOptions);
+}
+
+// Runs a shared CLI command under the job identity with its plain output
+// collected, so a --json caller still gets pure JSON.
+async function runJobScopedCommand(options, jobOptions, fn) {
+  const lines = [];
+  const originalLog = console.log;
+  if (options.json) console.log = (...parts) => lines.push(parts.join(" "));
+  try {
+    await fn(jobOptions);
+  } finally {
+    console.log = originalLog;
+  }
+  return lines;
+}
+
+// Hands the approved branch to the project owner (branch suggestion with a
+// note Lumine wrote) or suggests the branch's thumbnail, under the job
+// identity. Only editing jobs on a requester-owned branch can suggest.
+async function jobSuggest(options, jobId, kind, commandServices) {
+  const suggestionAction = String(kind || "").trim().toLowerCase();
+  if (suggestionAction !== "branch" && suggestionAction !== "thumbnail") {
+    throw new Error(
+      `Usage: lumine sponsor job suggest ${jobId} branch --note <message> | lumine sponsor job suggest ${jobId} thumbnail`,
+    );
+  }
+  const note = String(options.note || "").trim();
+  if (suggestionAction === "branch" && !note) {
+    throw new Error(
+      "Write the note for the project owner with --note <message>; Lumine composes it from the actual work, never from dictation.",
+    );
+  }
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const jobState = requireJobState(state, jobId);
+  if (isConsultationJob(jobState)) {
+    throw new Error("A read-only consultation cannot suggest anything.");
+  }
+  if (jobState.job?.targetBuild?.kind !== "branch") {
+    throw new Error(
+      "Suggestions go from a requester-owned branch to the project owner; this job targets Main itself.",
+    );
+  }
+  const send =
+    suggestionAction === "branch"
+      ? commandServices?.notifyOwner
+      : commandServices?.suggestThumbnail;
+  if (typeof send !== "function") {
+    throw new Error("This Lumine CLI build cannot send job suggestions.");
+  }
+  const jobOptions = jobWorkspaceOptions(options, state, jobState, { json: false });
+  const jobAuth = await resolveAuth(jobOptions);
+  const result = await send({
+    options: jobOptions,
+    auth: jobAuth,
+    rootBuildId: Number(jobState.job.rootBuild.id),
+    contributionBuildId: Number(jobState.job.targetBuild.id),
+    ...(suggestionAction === "branch" ? { note } : {}),
+  });
+  const messageId = Number(result?.message?.id || 0);
+  // The hand-off message is this job's proof of work when no file changed.
+  if (messageId > 0) {
+    jobState.handoffMessageIds = Array.from(
+      new Set([...(jobState.handoffMessageIds || []), messageId]),
+    );
+    await writeSponsorState(options, state);
+  }
+  printJsonOrLines(
+    options,
+    { job: jobState.job, suggestion: suggestionAction, messageId: messageId || null },
+    [
+      suggestionAction === "branch"
+        ? `Workshop job #${jobId}: branch suggested to the project owner with Lumine's note.`
+        : `Workshop job #${jobId}: thumbnail suggested to the project owner.`,
+    ],
+  );
+}
+
+// Sets the approved branch's thumbnail from a local image under the job
+// identity (upload + metadata commit). Pair with `suggest <id> thumbnail`.
+async function jobThumbnail(options, jobId, args, commandServices) {
+  const sub = String(args[0] || "").trim().toLowerCase();
+  const file = String(args[1] || "").trim();
+  if (sub !== "set" || !file || args.length > 2) {
+    throw new Error(`Usage: lumine sponsor job thumbnail ${jobId} set <file>`);
+  }
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const jobState = requireJobState(state, jobId);
+  if (isConsultationJob(jobState)) {
+    throw new Error("A read-only consultation cannot change the thumbnail.");
+  }
+  if (typeof commandServices?.thumbnailCommand !== "function") {
+    throw new Error("This Lumine CLI build cannot set job thumbnails.");
+  }
+  const jobOptions = jobWorkspaceOptions(options, state, jobState, {
+    json: false,
+    yes: true,
+    positional: ["set", file],
+  });
+  const output = await runJobScopedCommand(options, jobOptions, (o) =>
+    commandServices.thumbnailCommand(o),
+  );
+  printJsonOrLines(options, { job: jobState.job, output }, [
+    `Workshop job #${jobId}: thumbnail set on the approved branch.`,
+  ]);
+}
+
+// Foreground lease keeper: pulses the job while the owning session works.
+// `job begin` starts one detached child per job; complete/fail stop it.
+async function holdJobLease(options, jobId) {
+  const every = Math.max(15, Number(options.sponsorHoldEverySeconds || 40));
+  let consecutiveFailures = 0;
+  for (;;) {
+    let keepGoing = true;
+    try {
+      keepGoing = await withSponsorStateLock(options, async () => {
+        const auth = await ensureSponsorAuth(options);
+        const state = await loadOwnedState({ options, auth });
+        if (!state.jobs?.[String(jobId)]) return false;
+        const { state: next } = await heartbeatJob({
+          options,
+          auth,
+          state,
+          jobId,
+        });
+        const jobState = next.jobs?.[String(jobId)];
+        return Boolean(
+          jobState && ACTIVE_JOB_STATUSES.has(String(jobState.job?.status)),
+        );
+      });
+    } catch (error) {
+      const message = String(error?.message || error);
+      // Lease or duty gone: nothing left to hold.
+      if (/no longer active|lease|No local agent-owned duty|does not exist/i.test(message)) {
+        return;
+      }
+      consecutiveFailures += 1;
+      console.error(`lumine: lease keeper check-in failed: ${message}`);
+      // The owning session's own commands re-establish the lease; a keeper
+      // that cannot reach Twinkle three times in a row must not linger.
+      if (consecutiveFailures >= 3) return;
+    }
+    if (!keepGoing) return;
+    consecutiveFailures = 0;
+    await new Promise((resolve) => setTimeout(resolve, every * 1_000));
+  }
+}
+
+function startJobLeaseKeeper({ options, state, jobState }) {
+  if (jobState.keeperPid) return;
+  // A detached child is re-parented once this command exits, so a session
+  // identified only by process ancestry could not prove it is the same live
+  // session. Those sessions keep the lease by pulsing between steps instead.
+  if (state?.operatorSession?.bindingEvidence !== "runtime_session_id") {
+    jobState.keeperSkippedReason = "agent_process_ancestry";
+    return;
+  }
+  const args = [
+    process.argv[1],
+    "sponsor",
+    "job",
+    "hold",
+    String(jobState.job.id),
+    "--auth-file",
+    String(options.authFile),
+    "--api-url",
+    String(options.apiUrl),
+  ];
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: "ignore",
+    env: process.env,
+  });
+  child.unref();
+  jobState.keeperPid = child.pid;
+  jobState.keeperStartedAt = new Date().toISOString();
+}
+
+function stopJobLeaseKeeper(jobState) {
+  const pid = Number(jobState?.keeperPid || 0);
+  if (!pid) return;
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch (_) {}
+  jobState.keeperPid = null;
+}
+
 async function completeJob(options, jobId, commandServices) {
   const summary = String(options.summary || "").trim();
   if (!summary) {
@@ -929,6 +1284,48 @@ async function completeJob(options, jobId, commandServices) {
     ]);
     return;
   }
+  const handoffMessageIds = Array.isArray(jobState.handoffMessageIds)
+    ? jobState.handoffMessageIds.filter((id) => Number(id) > 0).map(Number)
+    : [];
+  if (changedPaths.length === 0 && handoffMessageIds.length > 0) {
+    // Nothing to save: the job's outcome is the hand-off itself (a branch
+    // or thumbnail suggestion sent to the owner under the job identity).
+    const coordinatorResult = await completeAgent({
+      options,
+      auth,
+      state,
+      jobState,
+      agent: jobState.coordinator,
+      outcome: {
+        finalText: summary.slice(0, 2000),
+        changedPathCount: 0,
+        changedPaths: [],
+        agentSessionBound: true,
+        handoffMessageIds,
+      },
+    });
+    jobState.coordinator = { ...jobState.coordinator, ...coordinatorResult };
+    await writeSponsorState(options, state);
+    const result = await retrySponsorTransport(() =>
+      sponsorJobRequest({
+        options,
+        auth,
+        state,
+        jobState,
+        path: "/complete",
+        body: {
+          outcomeSummary: summary,
+          reportedFilesHash: currentDigest,
+          handoffMessageIds,
+        },
+      }),
+    );
+    await removeCompletedJob({ options, state, jobId });
+    printJsonOrLines(options, result, [
+      `Completed Workshop job #${jobId}; the approved branch was handed to the project owner and ${displayPersona(jobState.job.persona)} shared the result.`,
+    ]);
+    return;
+  }
   let savedArtifact = jobState.savedArtifact;
   const canonicalSavedArtifact = jobState.job?.savedArtifact;
   if (
@@ -989,6 +1386,7 @@ async function completeJob(options, jobId, commandServices) {
         artifactVersionId: savedArtifact.artifactVersionId,
         outcomeSummary: summary,
         reportedFilesHash: savedArtifact.filesHash,
+        ...(handoffMessageIds.length > 0 ? { handoffMessageIds } : {}),
       },
     }),
   );
@@ -1463,11 +1861,16 @@ ${jobState.forumContext ? `## Normal-access Build Forum snapshot\n\n${jobState.f
 ## Duty protocol
 
 1. Run \`lumine sponsor job begin ${jobState.job.id}\` before ${consultation ? "inspecting the project" : "editing"}.
-2. Introduce yourself and publish meaningful milestones with \`lumine sponsor job update ${jobState.job.id} --file <message-file> --phase <name>\`. Speak as Lumine, never as the underlying provider.
+2. Introduce yourself and publish meaningful milestones with \`lumine sponsor job update ${jobState.job.id} --file <message-file> --phase <name>\`. Speak as Lumine, never as the underlying provider. To ask the user something you genuinely cannot decide yourself, add \`--kind question\`: ${displayPersona(jobState.job.persona)} puts it to the user and their answer comes back as an approved follow-up relay on your next pulse. Keep working on what does not depend on the answer.
 3. ${consultation ? "Inspect only" : "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.
-4. Run \`lumine sponsor job pulse ${jobState.job.id}\` between substantial work steps to keep the lease alive and receive approved follow-ups.
-5. After applying a relay, record its exact ID with \`lumine sponsor job relay-applied ${jobState.job.id} <relay-id...>\`.
-6. Finish with \`lumine sponsor job complete ${jobState.job.id} --summary "..."\`. ${consultation ? `For this consultation, the summary is the exact substantive answer ${displayPersona(jobState.job.persona)} will share; no artifact or project change is created.` : "The CLI will save a canonical artifact directly to the approved workspace. Publishing remains a separate owner action."}
+4. Run \`lumine sponsor job pulse ${jobState.job.id}\` between substantial work steps to receive approved follow-ups. A CLI lease keeper for this same session checks in while you work, so multi-minute steps are fine; it stops when the job completes or fails.
+5. After applying a relay, record its exact ID with \`lumine sponsor job relay-applied ${jobState.job.id} <relay-id...>\`.${
+    consultation
+      ? ""
+      : `
+6. ${consultation ? "" : `For a new or renamed project, set its title and description with \`lumine sponsor job rename ${jobState.job.id} <title>\` and \`lumine sponsor job describe ${jobState.job.id} <text>\`, and its thumbnail with \`lumine sponsor job thumbnail ${jobState.job.id} set <file>\`. `}If the plan asks for the branch to be updated from Main, run \`lumine sponsor job sync-main ${jobState.job.id}\` FIRST, before editing anything (never your own login); it merges under the job identity and moves the restore point to the merged snapshot, so work done before the sync would be folded into the restore point and no longer count as this job's change. Generated images or audio go in with \`lumine sponsor job assets ${jobState.job.id} upload <file...>\` and are referenced by the printed URLs. When the plan asks you to hand the branch to the project owner, finish with \`lumine sponsor job suggest ${jobState.job.id} branch --note <message>\` using a note you wrote from the actual work (optionally \`lumine sponsor job thumbnail ${jobState.job.id} set <file>\` then \`lumine sponsor job suggest ${jobState.job.id} thumbnail\`); never ask the user for wording.`
+  }
+${consultation ? "6" : "7"}. Finish with \`lumine sponsor job complete ${jobState.job.id} --summary "..."\`. ${consultation ? `For this consultation, the summary is the exact substantive answer ${displayPersona(jobState.job.persona)} will share; no artifact or project change is created.` : "The CLI will save a canonical artifact directly to the approved workspace. Publishing remains a separate owner action."}
 `;
   await fs.writeFile(jobState.assignmentPath, content, {
     encoding: "utf8",
@@ -1537,7 +1940,7 @@ async function loadOwnedState({ options, auth, state = null }) {
   return loaded;
 }
 
-export function sponsorDutyStatePath(options) {
+export function baseSponsorDutyStatePath(options) {
   const authFile = path.resolve(options.authFile);
   const contextHash = createHash("sha256")
     .update(String(options.apiUrl || ""))
@@ -1551,6 +1954,36 @@ export function sponsorDutyStatePath(options) {
   );
 }
 
+// One sponsor login can keep several live agent sessions on duty at once.
+// The first session owns the base state file. When a further session on the
+// same login STARTS duty while the base belongs to another live session, it
+// gets its own file keyed by its session fingerprint; from then on that
+// session always finds its own file. Every other command still sees the base
+// record, so the account and same-session guards keep working.
+export function sponsorDutyStatePath(options) {
+  const base = baseSponsorDutyStatePath(options);
+  let session = null;
+  try {
+    session = detectSponsorAgentSession();
+  } catch {
+    return base;
+  }
+  const scoped = base.replace(
+    /\.json$/,
+    `-${session.fingerprintHash.slice(0, 12)}.json`,
+  );
+  if (existsSync(scoped)) return scoped;
+  if (!options.sponsorStateForStart) return base;
+  try {
+    const state = JSON.parse(readFileSync(base, "utf8"));
+    const owner = String(state?.operatorSession?.fingerprintHash || "");
+    if (owner && owner !== session.fingerprintHash) return scoped;
+  } catch {
+    // No base file (or unreadable): this session takes the base path.
+  }
+  return base;
+}
+
 function assertSponsorStateAccount(state, auth) {
   if (
     auth.userId &&
@@ -1686,18 +2119,27 @@ async function withSponsorStateLock(options, operation) {
   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.",
-      );
+  // Short check-ins (the lease keeper, a pulse) hold the lock for well under
+  // a second, so a colliding command waits briefly instead of failing.
+  const waitUntil = Date.now() + SPONSOR_LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      handle = await fs.open(lockPath, "wx", 0o600);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      const stale = await sponsorLockIsStale(lockPath);
+      if (stale) {
+        await fs.unlink(lockPath).catch(() => undefined);
+        continue;
+      }
+      if (Date.now() >= waitUntil) {
+        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 new Promise((resolve) => setTimeout(resolve, 250));
     }
-    await fs.unlink(lockPath);
-    handle = await fs.open(lockPath, "wx", 0o600);
   }
   try {
     await handle.writeFile(
@@ -1751,6 +2193,7 @@ async function archiveSponsorState(options, state) {
 
 async function removeCompletedJob({ options, state, jobId }) {
   const jobState = requireJobState(state, jobId);
+  stopJobLeaseKeeper(jobState);
   await scrubJobCredentials(jobState);
   const nextJobs = { ...(state.jobs || {}) };
   delete nextJobs[String(jobId)];
@@ -1765,6 +2208,7 @@ async function removeCompletedJob({ options, state, jobId }) {
 
 async function preserveFailedJobWorkspace({ options, state, jobId, reason }) {
   const jobState = requireJobState(state, jobId);
+  stopJobLeaseKeeper(jobState);
   await scrubJobCredentials(jobState);
   const nextJobs = { ...(state.jobs || {}) };
   delete nextJobs[String(jobId)];
@@ -2192,6 +2636,13 @@ function sponsorJobUsage() {
     "  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 sync-main <job-id>",
+    "  lumine sponsor job assets <job-id> upload <file...>",
+    "  lumine sponsor job hold <job-id>",
+    "  lumine sponsor job suggest <job-id> branch --note <message> | thumbnail",
+    "  lumine sponsor job thumbnail <job-id> set <file>",
+    "  lumine sponsor job rename <job-id> <title>",
+    "  lumine sponsor job describe <job-id> <text>",
     "  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");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage5/lumine",
-  "version": "0.2.66",
+  "version": "0.2.68",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {