@stage5/lumine 0.2.58 → 0.2.60

package/README.md

@@ -283,13 +283,18 @@ works:
 
 ```bash
 lumine sponsor job begin 42
+lumine sponsor job update 42 --file /path/to/lumine-update.txt --phase building
 lumine sponsor job pulse 42
 lumine sponsor job relay-applied 42 101
 lumine sponsor job complete 42 --summary "Implemented and tested the approved change"
 ```
 
 `pulse` renews the duty/job leases and returns any newly approved follow-up.
-Run it between substantial work steps. `relay-applied` is an explicit receipt;
+`update` sends the exact file text back to Zero or Ciel as a user-visible
+message from Lumine, their added brain. Use it for concise, deliberate
+milestones only; never send hidden reasoning, raw terminal output, credentials,
+tokens, private paths, or unrelated data. Run `pulse` between substantial work
+steps. `relay-applied` is an explicit receipt;
 completion is rejected until every delivered relay has actually been applied
 and acknowledged. Use `helper-start` and `helper-complete` to record native
 same-session subagents within the configured helper limit—the CLI records them

package/lib/commands.js

@@ -2409,6 +2409,8 @@ export function parseArgs(args) {
     sponsorAgentOrdinal: raw.ordinal,
     sponsorOutcome: raw.outcome ? String(raw.outcome) : "",
     sponsorFailureReason: raw.reason ? String(raw.reason) : "",
+    sponsorUpdateFile: raw.file ? String(raw.file) : "",
+    sponsorUpdatePhase: raw.phase ? String(raw.phase) : "",
     sponsorResolvedModel: raw.resolvedModel
       ? String(raw.resolvedModel)
       : "",
@@ -2749,6 +2751,7 @@ export function printHelp() {
   lumine sponsor duty watch [--wait-ms <ms>] [--json]
   lumine sponsor duty pause|resume|stop
   lumine sponsor job status|pulse|begin <job-id>
+  lumine sponsor job update <job-id> --file <path> [--phase <name>]
   lumine sponsor job relay-applied <job-id> <relay-id...>
   lumine sponsor job helper-start|helper-complete <job-id> [options]
   lumine sponsor job complete <job-id> --summary <text>

package/lib/sponsor-duty.js

@@ -66,6 +66,13 @@ export async function sponsorJobCommand(options, args, commandServices) {
     await withSponsorStateLock(options, () => beginJob(options, jobId));
     return;
   }
+  if (action === "update") {
+    assertNoExtraArgs(args, 2);
+    await withSponsorStateLock(options, () =>
+      publishDialogueUpdate(options, jobId),
+    );
+    return;
+  }
   if (action === "relay-applied") {
     const relayIds = args
       .slice(2)
@@ -234,7 +241,7 @@ async function reconcileExistingStateBeforeStart({
   }
   const preservedWorkspaces = dutyWorkspacePaths(existingState);
   if (preservedWorkspaces.length > 0) {
-    const archivePath = await archiveSponsorState(options);
+    const archivePath = await archiveSponsorState(options, existingState);
     console.error(
       `lumine: preserved the expired duty record at ${archivePath}.`,
     );
@@ -408,7 +415,7 @@ async function changeDutyState(options, action) {
       const preservedWorkspaces = dutyWorkspacePaths(localState);
       const localArchive =
         preservedWorkspaces.length > 0
-          ? await archiveSponsorState(options)
+          ? await archiveSponsorState(options, localState)
           : null;
       if (!localArchive) await removeSponsorState(options);
       printJsonOrLines(
@@ -472,7 +479,7 @@ async function changeDutyState(options, action) {
     if (nextState === "stopped") {
       preservedWorkspaces = dutyWorkspacePaths(localState);
       if (preservedWorkspaces.length > 0) {
-        localArchive = await archiveSponsorState(options);
+        localArchive = await archiveSponsorState(options, localState);
       } else {
         await removeSponsorState(options);
       }
@@ -539,10 +546,61 @@ async function beginJob(options, 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}.`,
+    `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}`,
   ]);
 }
 
+async function publishDialogueUpdate(options, jobId) {
+  const messageFile = String(options.sponsorUpdateFile || "").trim();
+  if (!messageFile) {
+    throw new Error(
+      "Write the deliberate user-facing Lumine update to a file and pass --file <path>.",
+    );
+  }
+  const phase = String(options.sponsorUpdatePhase || "").trim();
+  if (phase.length > 40) {
+    throw new Error("--phase must be at most 40 characters.");
+  }
+  const messagePath = path.resolve(messageFile);
+  const messageStat = await fs.stat(messagePath);
+  if (!messageStat.isFile() || messageStat.size > 8_000) {
+    throw new Error("The Lumine update file must be a text file under 8 KB.");
+  }
+  const message = String(await fs.readFile(messagePath, "utf8")).trim();
+  if (!message) throw new Error("The Lumine update file is empty.");
+  if (message.length > 2_000) {
+    throw new Error("The Lumine update must be at most 2,000 characters.");
+  }
+
+  const auth = await ensureSponsorAuth(options);
+  let state = await loadOwnedState({ options, auth });
+  ({ state } = await heartbeatJob({ options, auth, state, jobId }));
+  const jobState = requireJobState(state, jobId);
+  const clientUpdateKey = randomBytes(18).toString("base64url");
+  const result = await retrySponsorCheckIn(() =>
+    sponsorJobRequest({
+      options,
+      auth,
+      state,
+      jobState,
+      path: "/dialogue",
+      body: {
+        clientUpdateKey,
+        phase: phase || null,
+        message,
+      },
+    }),
+  );
+  if (!result?.update?.message) {
+    throw new Error("Twinkle did not confirm the canonical Lumine update.");
+  }
+  printJsonOrLines(options, result, [
+    `Lumine → ${displayPersona(jobState.job.persona)}:`,
+    result.update.message,
+  ]);
+}
+
 async function startHelper(options, jobId) {
   const auth = await ensureSponsorAuth(options);
   let state = await loadOwnedState({ options, auth });
@@ -1177,25 +1235,36 @@ 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")}`;
+      const dialogueText =
+        String(relay.dialogueText || "").trim() ||
+        [
+          relay.summary,
+          relay.projectTitleHint
+            ? `Project: ${relay.projectTitleHint}`
+            : "",
+          relay.requestedOutcome
+            ? `What to build: ${relay.requestedOutcome}`
+            : "",
+          relay.constraints?.length
+            ? `Keeping in mind:\n${relay.constraints.map((item) => `• ${item}`).join("\n")}`
+            : "",
+          relay.acceptanceCriteria?.length
+            ? `Done means:\n${relay.acceptanceCriteria.map((item) => `• ${item}`).join("\n")}`
+            : "",
+        ]
+          .filter(Boolean)
+          .join("\n\n");
+      return `## Relay #${relay.id}${unapplied.has(Number(relay.id)) ? " (not yet acknowledged as applied)" : " (applied receipt confirmed)"}\n\n${dialogueText}`;
     })
     .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.
+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. In every user-facing Workshop update, you are Lumine: the added brain talking with that teammate. 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.
 
+Lumine updates are a deliberate public channel. Write concise messages about what you are checking, what you found, or what happens next. Never publish hidden chain-of-thought, raw terminal output, credentials, tokens, private paths, or unrelated data. The exact file text you submit is shown in Twinkle and echoed back by the CLI.
+
 - User: @${jobState.job.requester.username}
 - Visible teammate: ${displayPersona(jobState.job.persona)}
 - Main project: ${jobState.job.rootBuild.title} (#${jobState.job.rootBuild.id})
@@ -1208,10 +1277,11 @@ ${jobState.forumContext ? `## Scoped Build Forum snapshot\n\n${jobState.forumCon
 ## 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 "..."\`.
+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.
+3. 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 "..."\`.
 `;
   await fs.writeFile(jobState.assignmentPath, content, {
     encoding: "utf8",
@@ -1412,7 +1482,17 @@ async function sponsorLockIsStale(lockPath) {
   }
 }
 
-async function archiveSponsorState(options) {
+async function archiveSponsorState(options, state) {
+  for (const jobState of Object.values(state.jobs || {})) {
+    await scrubJobCredentials(jobState);
+  }
+  for (const preserved of Array.isArray(state.preservedWorkspaces)
+    ? state.preservedWorkspaces
+    : []) {
+    await scrubPreservedWorkspaceCredential(preserved);
+  }
+  state.duty = { ...state.duty, leaseToken: null };
+  await writeSponsorState(options, state);
   const filePath = sponsorDutyStatePath(options);
   const archivePath = `${filePath}.stopped-${Date.now()}`;
   await fs.rename(filePath, archivePath);
@@ -1422,6 +1502,7 @@ async function archiveSponsorState(options) {
 
 async function removeCompletedJob({ options, state, jobId }) {
   const jobState = requireJobState(state, jobId);
+  await scrubJobCredentials(jobState);
   const nextJobs = { ...(state.jobs || {}) };
   delete nextJobs[String(jobId)];
   state.jobs = nextJobs;
@@ -1435,6 +1516,7 @@ async function removeCompletedJob({ options, state, jobId }) {
 
 async function preserveFailedJobWorkspace({ options, state, jobId, reason }) {
   const jobState = requireJobState(state, jobId);
+  await scrubJobCredentials(jobState);
   const nextJobs = { ...(state.jobs || {}) };
   delete nextJobs[String(jobId)];
   state.jobs = nextJobs;
@@ -1449,6 +1531,7 @@ async function preserveFailedJobWorkspace({ options, state, jobId, reason }) {
       workspaceDir: jobState.workspaceDir,
       reason: reason.slice(0, 1000),
       preservedAt: new Date().toISOString(),
+      credentialsRemovedAt: jobState.credentialsRemovedAt,
     },
   ];
   await writeSponsorState(options, state);
@@ -1473,6 +1556,50 @@ function dutyWorkspacePaths(state) {
 }
 
 async function cleanupJobFiles(jobState) {
+  const tempDir = resolveJobTempDir(jobState);
+  await fs.rm(tempDir, { recursive: true, force: true });
+}
+
+async function scrubJobCredentials(jobState) {
+  const tempDir = resolveJobTempDir(jobState);
+  const expectedAuthFile = path.join(tempDir, "job-auth.json");
+  const authFile = path.resolve(
+    String(jobState?.authFile || expectedAuthFile),
+  );
+  if (authFile !== expectedAuthFile) {
+    throw new Error(
+      "Refused to remove an unrecognized Workshop credential file.",
+    );
+  }
+  await fs.unlink(authFile).catch((error) => {
+    if (error.code !== "ENOENT") throw error;
+  });
+  jobState.authFile = null;
+  jobState.workspaceToken = null;
+  if (jobState.attempt) {
+    jobState.attempt = { ...jobState.attempt, token: null };
+  }
+  jobState.credentialsRemovedAt = new Date().toISOString();
+}
+
+async function scrubPreservedWorkspaceCredential(preserved) {
+  const workspaceDir = path.resolve(String(preserved?.workspaceDir || ""));
+  if (path.basename(workspaceDir) !== "workspace") return;
+  const tempDir = path.dirname(workspaceDir);
+  try {
+    resolveJobTempDir({ tempDir });
+  } catch {
+    return;
+  }
+  const credentialState = {
+    tempDir,
+    authFile: path.join(tempDir, "job-auth.json"),
+  };
+  await scrubJobCredentials(credentialState);
+  preserved.credentialsRemovedAt = credentialState.credentialsRemovedAt;
+}
+
+function resolveJobTempDir(jobState) {
   const tempRoot = path.resolve(os.tmpdir());
   const tempDir = path.resolve(String(jobState?.tempDir || ""));
   if (
@@ -1482,7 +1609,7 @@ async function cleanupJobFiles(jobState) {
   ) {
     throw new Error("Refused to remove an unrecognized Workshop directory.");
   }
-  await fs.rm(tempDir, { recursive: true, force: true });
+  return tempDir;
 }
 
 export function detectSponsorAgentSession({
@@ -1808,6 +1935,7 @@ function sponsorJobUsage() {
     "Usage:",
     "  lumine sponsor job status|pulse <job-id>",
     "  lumine sponsor job begin <job-id>",
+    "  lumine sponsor job update <job-id> --file <path> [--phase <name>]",
     "  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>]",

package/lib/sponsor.js

@@ -391,6 +391,7 @@ function sponsorUsage() {
     "  lumine sponsor duty watch [--wait-ms <ms>] [--json]",
     "  lumine sponsor duty status|pause|resume|stop",
     "  lumine sponsor job status|pulse|begin <job-id>",
+    "  lumine sponsor job update <job-id> --file <path> [--phase <name>]",
     "  lumine sponsor job relay-applied <job-id> <relay-id...>",
     "  lumine sponsor job helper-start|helper-complete <job-id> [options]",
     "  lumine sponsor job complete <job-id> --summary <text>",

package/package.json

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