@stage5/lumine 0.2.59 → 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)
@@ -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",
@@ -1865,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.59",
+  "version": "0.2.60",
   "description": "Command line tools for launching Lumine builds on Twinkle.",
   "type": "module",
   "bin": {