@linzumi/cli 0.0.88-beta → 0.0.89-beta

package/README.md

@@ -58,7 +58,7 @@ Install the CLI or run it with `npx`:
 ```bash
 npm install -g @linzumi/cli@latest
 npx -y @linzumi/cli@latest signup
-npx -y @linzumi/cli@0.0.88-beta --version
+npx -y @linzumi/cli@0.0.89-beta --version
 linzumi --version
 ```
 

package/dist/index.js

@@ -1936,6 +1936,228 @@ var init_codexRuntimeOptions = __esm({
   }
 });
 
+// src/linzumiContext.ts
+function parseLinzumiConversationContext(value, warn = console.warn) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const context = objectValue(value);
+  if (context === void 0) {
+    return invalidLinzumiContext("linzumiContext must be an object", warn);
+  }
+  const threadId = stringValue(context.threadId);
+  const creatorUserId = stringValue(context.creatorUserId) ?? integerValue(context.creatorUserId)?.toString();
+  const creatorUsername = stringValue(context.creatorUsername);
+  const conversationUrl = stringValue(context.conversationUrl);
+  if (threadId === void 0 || creatorUserId === void 0 || creatorUsername === void 0 || conversationUrl === void 0) {
+    return invalidLinzumiContext(
+      "linzumiContext must include threadId, creatorUserId, creatorUsername, and conversationUrl",
+      warn
+    );
+  }
+  return { threadId, creatorUserId, creatorUsername, conversationUrl };
+}
+function formatLinzumiConversationContextForPrompt(context) {
+  return `<linzumi_context>
+<linzumi_thread_id>${escapeXmlText(context.threadId)}</linzumi_thread_id>
+<linzumi_creator_user_id>${escapeXmlText(context.creatorUserId)}</linzumi_creator_user_id>
+<linzumi_creator_username>${escapeXmlText(context.creatorUsername)}</linzumi_creator_username>
+<linzumi_conversation_url>${escapeXmlText(context.conversationUrl)}</linzumi_conversation_url>
+</linzumi_context>
+
+<linzumi_pr_footer_instruction>
+For any GitHub pull request you open from this session, include this Markdown footer link in the PR description: [Continue this on Linzumi](${context.conversationUrl})
+</linzumi_pr_footer_instruction>`;
+}
+function invalidLinzumiContext(reason, warn) {
+  warn(`Ignoring invalid linzumiContext: ${reason}`);
+  return void 0;
+}
+function escapeXmlText(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+var init_linzumiContext = __esm({
+  "src/linzumiContext.ts"() {
+    "use strict";
+    init_json();
+  }
+});
+
+// src/commanderDeveloperInstructions.ts
+function commanderDeveloperInstructions(args) {
+  const agentLabel = args.agentLabel ?? "Codex";
+  const planOpener = `Before you begin ANY work - and again whenever the job
+changes - call linzumi_upsert_coding_job_plan to set or refresh the current
+goal and the high-level plan. Always record the plan up front, before starting
+work, so the user can see a high-level view of what you are doing at all times
+and trust your work. Keep it accurate as you go: whenever you discover steps to
+add, steps that are no longer needed, or the nature of the job changes, update
+it with linzumi_upsert_coding_job_plan.`;
+  const planStepsInstruction = args.planTool === "todo-write" ? `${planOpener}
+Record and maintain the plan STEPS with the TodoWrite tool. Linzumi mirrors
+your TodoWrite list into the coding-job plan steps automatically, one TodoWrite
+item per plan step.` : `${planOpener}
+Replace the plan STEPS with linzumi_replace_coding_job_plan_steps.`;
+  const planUpdateInstruction = args.planTool === "todo-write" ? `As work proceeds, update each step's status with TodoWrite. Do not call
+linzumi_replace_coding_job_plan_steps or linzumi_update_coding_job_plan_step
+directly; TodoWrite is the source of truth for the plan steps.` : `As work proceeds, update each step with linzumi_update_coding_job_plan_step.`;
+  const customPrompt = args.developerPrompt === void 0 ? "" : `
+<invoker_developer_prompt>
+${args.developerPrompt}
+</invoker_developer_prompt>
+`;
+  const linzumiContext = args.linzumiContext === void 0 ? "" : `
+${formatLinzumiConversationContextForPrompt(args.linzumiContext)}
+`;
+  return `<context>
+You are a Linzumi ${agentLabel} session launched by the Linzumi Commander.
+The Commander is the local bridge process that connects this computer to the
+user's Linzumi workspace, secure preview tunnel, browser VS Code editor, and
+thread transcript. Your work and progress are relayed into that Linzumi thread.
+</context>
+
+<term_definitions>
+Bootstrapper ${agentLabel}: The outer setup agent that claimed/signup, generated the
+demo folder when applicable, and asked Linzumi to start this session. It does
+not own implementation work.
+Linzumi Commander: The local long-running process that launched this ${agentLabel}
+session, enforces the trusted folder, and forwards descendant preview ports to
+Linzumi.
+Linzumi ${agentLabel} session: You, the inner ${agentLabel} process that performs the actual
+work in the approved project folder.
+Approved project folder: ${args.cwd}
+Coding-job metadata: User-visible goal, plan steps, step statuses, completion
+notes, primary pull request link, and worktree state shown in Linzumi's coding
+job overview.
+Plan step: A discrete chunk of work with a short title, one-line description,
+status, and completion note. It should describe an actual goal, not just a
+process verb.
+Primary pull request: The GitHub PR the job is currently driving or reviewing;
+Linzumi uses this link to hydrate PR comments, files, commits, checks, and
+deployments in the metadata overview.
+</term_definitions>
+
+<linzumi_mcp>
+The Codex process is preconfigured with a Linzumi MCP server named "linzumi".
+Use it when you need authenticated context from the current Linzumi workspace:
+read a message by ID/URL, read a thread by ID, read the scoped channel, or send
+a concise DM to the Commander owner when the task genuinely requires it.
+</linzumi_mcp>
+
+<task_instructions>
+Work only in the approved project folder unless the human explicitly asks for
+something else in the Linzumi thread. Start, inspect, and modify the local app
+from that folder. Report concise progress and exact blockers in the thread.
+Use the Linzumi MCP server named "linzumi" when you need authenticated
+workspace context or coding-job metadata tools.
+${planStepsInstruction}
+When the coding-job scope changes materially, call linzumi_rename_coding_job
+with a concise title so the Linzumi thread title and workflow-facing title
+match the work.
+${planUpdateInstruction}
+When you open, discover, or choose the primary pull request, link it with
+linzumi_link_coding_job_pull_request.
+Before stopping, confirm the metadata overview tells the truth for a user who
+only sees that overview: completed work is completed, active work is really
+active, blocked work says why, and no stale in-progress step is left behind.
+For frontend or other user-visible changes, ask whether the user wants
+screenshot or screen-recording proof, ideally before/after when that helps
+review the change. Screen recordings should be WebM or MP4.
+When the user asks you to open or update a PR, attach or link feasible proof in
+the PR and state the exact blocker when proof is not feasible.
+</task_instructions>
+
+<rules>
+You MUST treat the Linzumi thread as the source of truth for user-facing
+progress.
+For coding-job threads, you MUST keep coding-job metadata current throughout
+the job.
+Plan steps MUST be fairly granular, discrete chunks of real work that a human
+can track.
+Plan step descriptions MUST stay short, usually one line and less than one full
+sentence.
+Plan steps MUST NOT be vague process-only labels such as "sync PR",
+"update PR", "verify PR", or "commit and merge" when those labels hide the
+concrete goal.
+You MUST update steps in sequence as work is completed. Do not mark a later
+step active while earlier applicable steps are still pending.
+Before you stop work, you MUST reconcile the plan so the job is not left with a
+stale active step. You may delegate metadata upkeep to a sub-agent when useful,
+but the visible job state must remain truthful.
+If the coding-job thread title is missing, undefined, or "Untitled", you MUST
+choose a concise, specific title for the job.
+User-visible UI, status, error, and PR-review copy MUST keep it short, direct,
+and focused on the user's outcome unless the user explicitly asks for
+implementation detail.
+You MUST keep user-visible preview servers bound to 0.0.0.0, not 127.0.0.1 or
+localhost, so the Linzumi secure tunnel can reach them.
+You MUST keep any preview or dev server as your descendant process so the
+Commander can discover and forward it.
+You MUST NOT ask the Bootstrapper ${agentLabel} to do implementation work.
+You MUST NOT inspect unrelated repositories or folders.
+You MUST report the exact blocker if a command, preview, editor, or tunnel step
+fails.
+When several Linzumi Codex sessions work in the same repository, create or use
+a separate checkout or git worktree for this task before making changes, unless
+the human explicitly asks you to share the current checkout. Do not overwrite or
+revert another session's work.
+</rules>
+
+<examples>
+GOOD preview command: npm run dev -- --host 0.0.0.0 --port 8787
+Why good: The preview is reachable through the Linzumi secure tunnel.
+
+BAD preview command: npm run dev -- --host 127.0.0.1
+Why bad: Binding to localhost prevents the Linzumi secure tunnel from reaching
+the preview.
+
+GOOD coding-job plan:
+- Inspect prompt sources: Locate the prompt builder, prompt guide, and tests.
+- Add metadata guidance: Patch the prompt with plan, title, and stop-state rules.
+- Verify compiled prompt: Run focused tests and inspect the generated text.
+- Push PR update: Commit owned files, push the branch, and refresh PR metadata.
+Why good: Each step is a concrete chunk of work, the list is short enough to
+scan, and the titles explain what is actually happening.
+
+BAD coding-job plan:
+- Sync PR
+- Update PR
+- Verify PR
+- Commit and merge
+Why bad: These labels describe process mechanics, not the concrete work or
+product goal. A user cannot tell what the agent has learned, changed, or still
+needs to do.
+
+BAD coding-job metadata state:
+- Step 1 complete, Step 2 complete, Step 3 active, Step 4 pending.
+- The agent has stopped working and sent its final response.
+Why bad: The overview still says work is active even though the agent is idle.
+Before stopping, the agent should mark Step 3 completed, blocked, or canceled
+with a truthful note.
+</examples>
+${linzumiContext}
+${customPrompt}
+<task_reminder>
+You are the Commander-launched Linzumi ${agentLabel} session. Do the implementation
+work in the approved project folder, keep preview servers reachable through the
+secure tunnel, and keep the Linzumi thread and coding-job metadata truthful.
+</task_reminder>
+
+<output_format>
+Use normal concise Linzumi thread messages for user-facing progress and final
+answers. When the task requires files, code, commits, pull requests, previews,
+or verification output, report the concrete artifact, command, result, and any
+exact blocker. Do not emit machine-only JSON unless the user or tool explicitly
+requests it.
+</output_format>`;
+}
+var init_commanderDeveloperInstructions = __esm({
+  "src/commanderDeveloperInstructions.ts"() {
+    "use strict";
+    init_linzumiContext();
+  }
+});
+
 // src/codexOutput.ts
 import { Buffer as Buffer2 } from "node:buffer";
 import { fileURLToPath } from "node:url";
@@ -6552,53 +6774,6 @@ var init_kandanQueue = __esm({
   }
 });
 
-// src/linzumiContext.ts
-function parseLinzumiConversationContext(value, warn = console.warn) {
-  if (value === void 0) {
-    return void 0;
-  }
-  const context = objectValue(value);
-  if (context === void 0) {
-    return invalidLinzumiContext("linzumiContext must be an object", warn);
-  }
-  const threadId = stringValue(context.threadId);
-  const creatorUserId = stringValue(context.creatorUserId) ?? integerValue(context.creatorUserId)?.toString();
-  const creatorUsername = stringValue(context.creatorUsername);
-  const conversationUrl = stringValue(context.conversationUrl);
-  if (threadId === void 0 || creatorUserId === void 0 || creatorUsername === void 0 || conversationUrl === void 0) {
-    return invalidLinzumiContext(
-      "linzumiContext must include threadId, creatorUserId, creatorUsername, and conversationUrl",
-      warn
-    );
-  }
-  return { threadId, creatorUserId, creatorUsername, conversationUrl };
-}
-function formatLinzumiConversationContextForPrompt(context) {
-  return `<linzumi_context>
-<linzumi_thread_id>${escapeXmlText(context.threadId)}</linzumi_thread_id>
-<linzumi_creator_user_id>${escapeXmlText(context.creatorUserId)}</linzumi_creator_user_id>
-<linzumi_creator_username>${escapeXmlText(context.creatorUsername)}</linzumi_creator_username>
-<linzumi_conversation_url>${escapeXmlText(context.conversationUrl)}</linzumi_conversation_url>
-</linzumi_context>
-
-<linzumi_pr_footer_instruction>
-For any GitHub pull request you open from this session, include this Markdown footer link in the PR description: [Continue this on Linzumi](${context.conversationUrl})
-</linzumi_pr_footer_instruction>`;
-}
-function invalidLinzumiContext(reason, warn) {
-  warn(`Ignoring invalid linzumiContext: ${reason}`);
-  return void 0;
-}
-function escapeXmlText(value) {
-  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
-}
-var init_linzumiContext = __esm({
-  "src/linzumiContext.ts"() {
-    "use strict";
-    init_json();
-  }
-});
-
 // src/reconnectContext.ts
 function parseReconnectContextMessages(value) {
   if (!Array.isArray(value)) {
@@ -11336,10 +11511,27 @@ async function startCodexThread(codex, options) {
     cwd: options.cwd,
     serviceName: "kandan-local-runner",
     personality: "pragmatic",
+    ...developerInstructionsForThreadStart(options),
     ...codexThreadRuntimeOverrides(options)
   });
   return extractThreadIdFromResponse(start);
 }
+function developerInstructionsForThreadStart(options) {
+  const developerPrompt = options.channelSession.developerPrompt;
+  if (developerPrompt === void 0) {
+    return {};
+  }
+  return {
+    developerInstructions: commanderDeveloperInstructions({
+      cwd: options.cwd,
+      planTool: "linzumi-mcp",
+      developerPrompt,
+      linzumiContext: parseLinzumiConversationContext(
+        options.channelSession.linzumiContext
+      )
+    })
+  };
+}
 async function pushOk2(kandan, topic, event, payload) {
   const reply = await kandan.push(topic, event, payload);
   if (isJsonObject(reply) && reply.status === "ok" && isJsonObject(reply.response)) {
@@ -11366,6 +11558,7 @@ var init_channelSession = __esm({
     init_channelSessionSupport();
     init_commanderAttachments();
     init_codexRuntimeOptions();
+    init_commanderDeveloperInstructions();
     init_codexOutput();
     init_codexSessionLog();
     init_integration();
@@ -14961,11 +15154,34 @@ var init_defaultUrls = __esm({
 import { spawn as spawn3 } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { createServer as createServer2 } from "node:http";
+function oauthCallbackTimeoutMs(override, env = process.env) {
+  if (typeof override === "number" && Number.isFinite(override) && override > 0) {
+    return override;
+  }
+  const raw = env.LINZUMI_OAUTH_CALLBACK_TIMEOUT_MS?.trim();
+  if (raw !== void 0 && raw !== "") {
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isFinite(parsed) && parsed > 0) {
+      return parsed;
+    }
+  }
+  return DEFAULT_OAUTH_CALLBACK_TIMEOUT_MS;
+}
 async function acquireLocalRunnerTokenDetails(options) {
   const httpBaseUrl = kandanHttpBaseUrl(options.kandanUrl);
   const state = randomBytes(18).toString("base64url");
   const callback = await startCallbackServer({
-    host: oauthCallbackHost(options.kandanUrl, options.callbackHost)
+    host: oauthCallbackHost(options.kandanUrl, options.callbackHost),
+    exchange: async (result) => {
+      if (result.state !== state) {
+        throw new Error("local runner OAuth state mismatch");
+      }
+      return await exchangeCodeForToken({
+        httpBaseUrl,
+        code: result.code,
+        redirectUri: result.redirectUri
+      });
+    }
   });
   const authorizeUrl = authorizationUrl({
     httpBaseUrl,
@@ -14981,15 +15197,9 @@ ${authorizeUrl}
 `);
   try {
     await (options.openAuthorizationUrl ?? openBrowser)(authorizeUrl);
-    const result = await callback.waitForCallback();
-    if (result.state !== state) {
-      throw new Error("local runner OAuth state mismatch");
-    }
-    return await exchangeCodeForToken({
-      httpBaseUrl,
-      code: result.code,
-      redirectUri: callback.redirectUri
-    });
+    return await callback.waitForToken(
+      oauthCallbackTimeoutMs(options.waitForTokenTimeoutMs)
+    );
   } finally {
     callback.close();
   }
@@ -15169,49 +15379,83 @@ function stringBodyField(body, key) {
 }
 function startCallbackServer(args) {
   return new Promise((resolve12, reject) => {
-    let resolveCallback;
-    let rejectCallback;
-    const callbackPromise = new Promise((callbackResolve, callbackReject) => {
-      resolveCallback = callbackResolve;
-      rejectCallback = callbackReject;
+    let resolveToken;
+    let rejectToken;
+    let settled = false;
+    const tokenPromise = new Promise(
+      (tokenResolve, tokenReject) => {
+        resolveToken = tokenResolve;
+        rejectToken = tokenReject;
+      }
+    );
+    tokenPromise.catch(() => {
     });
+    const settle = (apply) => {
+      if (settled) {
+        return false;
+      }
+      settled = true;
+      apply();
+      return true;
+    };
+    let boundRedirectUri = `http://${args.host}/callback`;
     const server = createServer2((request, response) => {
-      try {
-        const url = new URL(request.url ?? "/", `http://${args.host}`);
-        const code = url.searchParams.get("code");
-        const state = url.searchParams.get("state");
-        const error = url.searchParams.get("error");
-        if (error !== null && error.trim() !== "") {
-          rejectCallback?.(new Error(`local runner OAuth failed: ${error}`));
+      void (async () => {
+        try {
+          const url = new URL(request.url ?? "/", `http://${args.host}`);
+          const code = url.searchParams.get("code");
+          const state = url.searchParams.get("state");
+          const error = url.searchParams.get("error");
+          if (error !== null && error.trim() !== "") {
+            settle(
+              () => rejectToken?.(new Error(`local runner OAuth failed: ${error}`))
+            );
+            writeOauthResult(response, {
+              title: "Not authorized",
+              body: "You denied the request. Close this tab and rerun the bootstrap command when you're ready.",
+              status: 403
+            });
+            return;
+          }
+          if (code === null || state === null || code.trim() === "" || state.trim() === "") {
+            writeOauthResult(response, {
+              title: "Authorization callback was incomplete",
+              body: "We didn't receive the authorization code. Return to your terminal and try again.",
+              status: 400
+            });
+            return;
+          }
+          let token;
+          try {
+            token = await args.exchange({
+              code,
+              state,
+              redirectUri: boundRedirectUri
+            });
+          } catch (exchangeError) {
+            settle(() => rejectToken?.(exchangeError));
+            writeOauthResult(response, {
+              title: "Authorization could not be completed",
+              body: "We received the authorization but could not finish setup. Return to your terminal for details and rerun the bootstrap command.",
+              status: 400
+            });
+            return;
+          }
+          const accepted = settle(() => resolveToken?.(token));
           writeOauthResult(response, {
-            title: "Not authorized",
-            body: "You denied the request. Close this tab and rerun the bootstrap command when you're ready.",
-            status: 403
+            title: accepted ? "Computer authorized" : "Already authorized",
+            body: "This computer has been authorized for agentic use in Linzumi. Feel free to close this tab and let the terminal finish setup.",
+            status: 200
           });
-          return;
-        }
-        if (code === null || state === null || code.trim() === "" || state.trim() === "") {
+        } catch (handlerError) {
+          settle(() => rejectToken?.(handlerError));
           writeOauthResult(response, {
-            title: "Authorization callback was incomplete",
-            body: "We didn't receive the authorization code. Return to your terminal and try again.",
-            status: 400
+            title: "Authorization callback failed",
+            body: "Return to your terminal and rerun the bootstrap command.",
+            status: 500
           });
-          return;
         }
-        resolveCallback?.({ code, state });
-        writeOauthResult(response, {
-          title: "Computer authorized",
-          body: "This computer has been authorized for agentic use in Linzumi. Feel free to close this tab and let the terminal finish setup.",
-          status: 200
-        });
-      } catch (error) {
-        rejectCallback?.(error);
-        writeOauthResult(response, {
-          title: "Authorization callback failed",
-          body: "Return to your terminal and rerun the bootstrap command.",
-          status: 500
-        });
-      }
+      })();
     });
     server.once("error", reject);
     server.listen(0, args.host, () => {
@@ -15224,9 +15468,34 @@ function startCallbackServer(args) {
         );
         return;
       }
+      boundRedirectUri = `http://${args.host}:${address.port}/callback`;
       resolve12({
-        redirectUri: `http://${args.host}:${address.port}/callback`,
-        waitForCallback: () => callbackPromise,
+        redirectUri: boundRedirectUri,
+        // Bound the wait so that "only spurious/incomplete requests, no real
+        // callback" can't hang forever. Incomplete requests deliberately never
+        // settle the token promise (they only render the incomplete page), so
+        // the overall timeout is what guarantees forward progress. The timer is
+        // unref'd so it can't keep the process alive on its own, and it's
+        // cleared once the token promise settles for any reason.
+        waitForToken: (timeoutMs) => {
+          const effectiveTimeoutMs = oauthCallbackTimeoutMs(timeoutMs);
+          const timer = setTimeout(() => {
+            settle(
+              () => rejectToken?.(
+                new Error(
+                  "Authorization timed out before the browser callback completed. Rerun the connect command and finish authorizing in the browser."
+                )
+              )
+            );
+            server.close();
+          }, effectiveTimeoutMs);
+          timer.unref?.();
+          tokenPromise.finally(() => {
+            clearTimeout(timer);
+          }).catch(() => {
+          });
+          return tokenPromise;
+        },
         close: () => {
           server.close();
         }
@@ -15291,7 +15560,7 @@ function oauthResultHtml(args) {
         place-items: center;
         padding: 24px;
         background:
-          radial-gradient(1200px 600px at 50% -10%, var(--notice-soft), transparent 60%),
+          radial-gradient(1200px 600px at 50% -10%, var(${success ? "--success-soft" : "--notice-soft"}), transparent 60%),
           var(--page-bg);
         color: var(--foreground);
         font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
@@ -15376,11 +15645,12 @@ function openBrowser(url) {
     });
   });
 }
-var LINZUMI_LOGO_SVG;
+var DEFAULT_OAUTH_CALLBACK_TIMEOUT_MS, LINZUMI_LOGO_SVG;
 var init_oauth = __esm({
   "src/oauth.ts"() {
     "use strict";
     init_runnerLogger();
+    DEFAULT_OAUTH_CALLBACK_TIMEOUT_MS = 5 * 60 * 1e3;
     LINZUMI_LOGO_SVG = '<svg viewBox="0 0 512 512" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false"><path fill="currentColor" d="M206.7,82.37l2.55-6.45,2.01-3.63c.67-1.21,1.07-1.88,2.55-3.63,1.34-1.61,3.36-4.43,5.64-6.58,2.42-2.24,5.06-4.3,7.93-6.18,3.92-2.53,8.17-4.52,12.63-5.91,1.79-.63,4.03-1.16,6.72-1.61,6.1-.88,12.29-.92,18.4-.13,2.69.45,5.06,1.03,7.12,1.75,2.15.67,3.49,1.07,5.64,2.15,4.55,2.16,8.87,4.77,12.9,7.79,1.61,1.34,2.42,2.15,4.16,4.16l5.91,7.66c1.34,2.01,1.34,2.28,2.15,4.03l2.55,6.58c.67,1.34-.13,1.34,1.07.94,1.21-.27,4.3-2.01,6.45-2.82,4.7-1.83,9.62-3,14.64-3.49,2.42-.27,3.76-.54,7.12-.27s9.27,1.21,12.76,2.15c3.63.94,6.58,2.55,8.73,3.49,2.15,1.07,2.55,1.48,4.16,2.55,3.49,2.51,6.77,5.29,9.81,8.33,1.52,1.7,3.04,3.58,4.57,5.64,2.74,4.49,4.86,9.32,6.31,14.37.67,2.28,1.07,3.49,1.34,6.72.27,3.22,0,10.48.4,12.76.27,2.28.27.67,1.61.94,1.48.27,4.3,0,6.72.4,2.42.27,4.97.85,7.66,1.75,6.76,2.32,13.01,5.92,18.4,10.61,2.28,1.75,2.96,2.69,4.3,4.3,3.51,3.93,6.32,8.43,8.33,13.3,1.07,2.15,1.21,2.28,1.88,5.1.54,2.96,1.61,8.19,1.61,12.36s-.81,9.67-1.34,12.76c-.67,3.22-1.07,4.03-2.15,6.18-2.16,4.54-4.81,8.82-7.93,12.76-1.25,1.61-2.6,3-4.03,4.16-1.48,1.34-2.69,2.42-4.7,3.76-3.79,2.34-7.74,4.4-11.82,6.18l-6.58,2.15c-2.06.45-4.12.72-6.18.81l-7.25.13c-2.28,0-2.82.27-6.58-.4-3.76-.81-11.69-2.82-15.99-4.3-4.16-1.34-6.31-2.69-9.67-4.43-3.49-1.75-10.48-6.18-12.9-7.39-8.26-4.54-16.78-8.58-25.52-12.09-4.3-1.75-9.27-3.22-11.82-4.03-2.55-.81-5.24-1.61-7.66-2.15-8.39-2.25-16.99-3.6-25.66-4.03-3.9-.27-4.84-.27-8.19-.13-3.67-.09-7.79.04-12.36.4-7.9.79-15.75,2.04-23.51,3.76-8.37,2.26-16.62,4.95-24.72,8.06-3.22,1.34-2.82.81-9.13,4.16-6.31,3.36-22.03,12.22-28.75,15.58-6.72,3.36-8.73,3.49-11.82,4.43-3.09,1.07-4.3,1.21-6.58,1.61-7.3,1.09-14.71,1.18-22.03.27-2.55-.54-5.78-1.61-7.79-2.28-2.01-.54-2.15-.67-4.03-1.75-2.02-1.07-5.64-3.22-7.79-4.7-3.24-2.15-6.14-4.77-8.6-7.79-1.34-1.52-2.69-3.36-4.03-5.51-1.52-2.51-2.96-5.24-4.3-8.19-2.03-5.46-3.03-11.24-2.96-17.06,0-2.96.13-6.72.67-9.67.54-2.87,1.34-5.6,2.42-8.19,4.24-10.52,12.04-19.22,22.03-24.58,5.19-2.98,10.88-4.98,16.79-5.91,2.55-.4,5.37-.13,6.72-.4,1.34-.27,1.34,1.34,1.61-.94.4-2.28,0-9.4.4-12.76.27-3.36.81-4.97,1.48-7.25,1.87-6.19,4.88-11.97,8.87-17.06,3.47-3.98,7.39-7.54,11.69-10.61,4.43-2.61,9.11-4.77,13.97-6.45,2.55-.67,6.99-1.34,9.13-1.75,2.15-.27,1.88-.13,3.63-.13,1.79-.09,4.03,0,6.72.27,2.69.18,5.73.72,9.13,1.61,3.49,1.07,9.27,4.03,11.28,4.7s.4.27,1.07-.94ZM512.27,255.7c0,141.39-114.62,256-256,256S.27,397.09.27,255.7,114.89-.3,256.27-.3s256,114.62,256,256ZM449.33,352.66c14.67-29.16,22.94-62.09,22.94-96.95,0-119.29-96.71-216-216-216S40.27,136.41,40.27,255.7c0,41.89,11.94,80.98,32.57,114.09,1.7,1.79,2.94.65,3.05-.57.27-1.61,2.75-20.85,4.43-27.27,1.87-7.6,4.52-14.98,7.93-22.03,1.75-3.49,3.76-7.93,6.18-11.82,8.77-13.95,19.75-26.38,32.51-36.81,7.24-5.32,14.87-10.08,22.84-14.24,9.74-4.78,20.09-8.22,30.76-10.21,4.03-.99,7.61-1.66,10.75-2.02,3.36-.54,5.78-.54,9.27-.94,3.49-.54,9.32-1.16,11.82-2.01,6.65-2.27,5.64-6.72,3.09-7.52-2.55-.81-9.67-1.88-13.84-2.96-4.16-1.21-8.73-2.82-11.28-3.76-2.55-.94-2.28-.94-3.9-2.02l-5.91-4.03c-.94-.94-1.34-.94.54-2.02l10.21-5.51c2.01-1.07,1.75-.67,3.09-.13,1.34.67,4.3,2.42,6.72,3.36,7.2,2.69,14.96,3.52,22.57,2.42,1.34-.27,1.34-.54,1.61-1.21.27-.67.81-.94-.13-2.69-.94-1.88-4.43-6.58-5.64-8.46l-1.21-2.28c-.27-.45-1.07-1.07,1.21-1.75,2.42-.54,10.48-2.58,12.9-2.82.86-.09.67,0,1.75,1.07,1.07,1.07,3.09,3.63,4.84,5.24,1.88,1.61,4.43,3.22,6.18,4.3,2.8,1.71,5.99,2.68,9.27,2.82,1.88,0,4.97-.13,7.12-.67,2.15-.4,3.63-.94,5.64-2.02,2.01-1.07,4.7-2.69,6.72-4.43,2.01-1.75,3.49-5.1,5.64-6.04,2.15-.81,4.97.54,7.12.94,2.28.4,4.97,1.21,6.18,1.61,1.21.4,2.01.4.67,2.28l-8.06,10.34c-1.34,1.88.13,5.51,1.21,5.64l5.64.27c2.28-.13,4.43.13,7.66-.67,3.36-.81,9.27-2.96,11.82-3.9,2.69-.94,3.22-1.34,4.16-2.01.81-.54,1.39-1.03,1.75-1.48.45-.27.67-1.07,2.82,0s9.4,4.97,11.28,6.18c2.01,1.21,1.07.94,0,1.75l-5.51,3.9c-1.48.94-1.07.94-3.22,1.88-2.15,1.07-6.58,2.96-9.67,4.03s-4.03,1.75-8.73,2.69c-4.7.81-14.51,1.75-19.48,2.55-4.97.81-7.93,1.34-10.34,2.01-2.28.67-2.15.94-3.49,1.88-1.48,1.07-2.69,1.61-4.97,3.9-2.28,2.28-5.91,6.85-8.73,9.81-2.82,2.96-6.45,6.04-8.33,7.79-2.02,1.61-1.61,1.34-3.36,2.42l-6.99,4.03-4.03,2.02-6.72,2.15c-2.42.67-3.9,1.21-7.66,2.01l-14.91,2.82c-3.63.81-4.3,1.07-7.12,2.01-2.96,1.07-6.22,2.46-9.81,4.16-3.22,1.43-6.81,3.45-10.75,6.04-13.6,9.14-24.61,21.63-31.97,36.27-2.01,3.76-2.96,6.58-3.9,9.27-1.07,2.69-1.61,4.03-2.28,6.58-.67,2.69-1.48,5.24-2.15,9.27-.54,4.16-1.48,11.15-1.75,15.45-.27,4.16-.27,6.04,0,10.21l1.88,14.91c.67,3.76,1.48,5.91,2.15,8.19l1.88,5.64c.99,2.6,2.42,5.78,4.3,9.54,2.15,3.76,5.37,9.13,8.06,13.03,10.08,14.51,23.81,26.36,40.17,33.05,22.55,9.22,43.32,10.46,61.89,10.46,3.25,0,6.49-.09,9.71-.23,3.07-.42,2.74-6.09,10.48-9.42,5.26-2.26,13.7-2.42,14.91-2.55,1.07-.13-5.24-4.57-7.79-6.45-2.55-1.88-4.97-4.3-6.72-5.91-1.75-1.75-2.42-2.28-3.9-4.16-1.61-1.88-3.9-5.51-5.24-7.12-1.34-1.61-1.48-2.28-2.55-2.55-.98-.27-2.37-.09-4.16.54-1.88.4-5.37,1.21-7.12,1.88-1.75.67-2.02.81-3.09,2.01-1.07,1.07-2.69,3.76-3.63,4.7-.81.94-.67.67-1.48.94-.81.27-2.42.67-3.63.54-1.34-.18-2.55-.58-3.63-1.21-.81-.81-1.48-2.42-1.88-3.22-.4-.94-.54-1.21-.54-2.15l.4-3.49c.18-1.52.72-3.27,1.61-5.24.94-1.75,1.88-3.49,4.16-5.64,2.15-2.02,7.52-5.51,9.13-6.85,1.61-1.34,1.21-2.15.54-3.63-2.69-5.16-6.33-9.77-10.75-13.57-2.42-1.88-5.51-3.22-7.79-4.3-2.15-1.21-2.01-1.21-5.78-2.42-3.76-1.07-13.16-3.63-16.79-4.84-3.63-1.07-2.82-.94-5.1-2.01l-8.19-4.3c-1.75-.94-1.34-.54-2.69-1.61l-5.51-4.57c-2.18-1.93-3.77-4.45-4.57-7.25-.45-1.52-.45-2.87,0-4.03.4-1.34,0-1.21,2.01-3.63,2.15-2.42,7.25-7.93,10.21-10.75,3.09-2.82,4.97-4.03,7.79-6.04,5.43-3.82,11.09-7.32,16.93-10.48,2.42-1.21,5.37-2.02,7.12-2.69,1.61-.81,2.64-1.43,3.09-1.88.54-.4.67.54.4-.94-.4-1.48-1.88-4.97-2.28-7.66-.4-2.82-.4-6.18,0-8.73.36-2.42,1.03-4.66,2.01-6.72,1.16-2.24,2.46-4.3,3.9-6.18,1.34-1.7,2.91-3.04,4.7-4.03,1.75-1.07,4.3-2.01,6.18-2.42,1.61-.45,3.13-.58,4.57-.4l4.57.27c1.34.18,2.55.49,3.63.94,1.07.54,2.55,1.48,3.09,2.01.4.67.67.13-.27,1.61-1.07,1.48-4.16,4.57-5.78,7.12-1.61,2.69-2.96,5.6-4.03,8.73-.94,3.22-1.88,8.73-2.01,10.75-.27,2.15,4.7,1.75,5.1.54.54-1.07.27-2.55,1.07-5.1.81-2.42,2.42-7.25,3.9-9.81,1.34-2.55,2.82-3.76,4.57-5.51,1.79-1.88,3.67-3.45,5.64-4.7,1.88-1.21,3.22-1.75,5.64-2.28,2.42-.4,6.18-.67,8.73-.67,2.42,0,3.9.13,6.18.94,2.15.81,5.24,2.69,7.12,4.03,1.79,1.52,3.22,3.09,4.3,4.7,1.21,1.61,1.88,2.96,2.55,5.1.67,2.15,1.34,5.1,1.34,7.66,0,2.69-.54,6.04-1.21,8.19-.63,2.24-1.43,4.03-2.42,5.37-.67,1.34-.94,1.61-2.15,2.82-1.21,1.34-3.22,3.22-4.97,4.57-1.75,1.21-4.43,2.28-5.51,3.22-.94.81-.4,2.51.4,2.42.94.13,1.75.4,4.57-.13,2.82-.4,8.33-2.15,12.22-2.82,11.99-2.63,24.41-2.63,36.4,0,3.22.54,4.16,1.07,6.31,1.75l6.04,2.28c2.42,1.07,5.51,2.42,8.19,4.16,8.15,5.36,15.14,12.3,20.55,20.42,1.61,2.42,2.87,4.66,3.76,6.72,1.85,4.51,3.42,9.13,4.7,13.84.67,2.82,1.21,4.43,1.61,8.19.4,3.76.4,11.82.54,14.37.27,2.55-.13,2.28,1.75,1.34,1.75-.94,20.09-7.74,30.63-31.57,9.16-20.71,1.9-47.26-2.28-55.34-1.75-3.22-4.16-6.99-6.31-9.81-4.44-5.14-9.6-9.62-15.31-13.3-2.96-1.7-5.55-3.09-7.79-4.16-4.33-1.6-8.77-2.86-13.3-3.76l-6.18-.4h-14.37c-2.69-.27-3.1-3.18-.54-4.3,3.64-1.58,9.88-2.63,18.54-2.42,8.78.21,14.91,1.88,17.33,2.55,13.98,3.94,30.19,16.65,38.55,30.76,6.61,11.16,9.81,29.96,9.81,29.96.37,1.75,2.18,1.66,3.08.35ZM232.78,345.3c-3.91,0-7.08,3.17-7.08,7.08s3.17,7.08,7.08,7.08,7.08-3.17,7.08-7.08-3.17-7.08-7.08-7.08Z"/></svg>';
   }
 });
@@ -18719,7 +18989,7 @@ var linzumiCliVersion, linzumiCliVersionText;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    linzumiCliVersion = "0.0.88-beta";
+    linzumiCliVersion = "0.0.89-beta";
     linzumiCliVersionText = `linzumi ${linzumiCliVersion}`;
   }
 });
@@ -26082,173 +26352,6 @@ function truncateFailureDetail(message) {
   }
   return `${trimmed.slice(0, 237)}...`;
 }
-function commanderDeveloperInstructions(args) {
-  const agentLabel = args.agentLabel ?? "Codex";
-  const planOpener = `Before you begin ANY work - and again whenever the job
-changes - call linzumi_upsert_coding_job_plan to set or refresh the current
-goal and the high-level plan. Always record the plan up front, before starting
-work, so the user can see a high-level view of what you are doing at all times
-and trust your work. Keep it accurate as you go: whenever you discover steps to
-add, steps that are no longer needed, or the nature of the job changes, update
-it with linzumi_upsert_coding_job_plan.`;
-  const planStepsInstruction = args.planTool === "todo-write" ? `${planOpener}
-Record and maintain the plan STEPS with the TodoWrite tool. Linzumi mirrors
-your TodoWrite list into the coding-job plan steps automatically, one TodoWrite
-item per plan step.` : `${planOpener}
-Replace the plan STEPS with linzumi_replace_coding_job_plan_steps.`;
-  const planUpdateInstruction = args.planTool === "todo-write" ? `As work proceeds, update each step's status with TodoWrite. Do not call
-linzumi_replace_coding_job_plan_steps or linzumi_update_coding_job_plan_step
-directly; TodoWrite is the source of truth for the plan steps.` : `As work proceeds, update each step with linzumi_update_coding_job_plan_step.`;
-  const customPrompt = args.developerPrompt === void 0 ? "" : `
-<invoker_developer_prompt>
-${args.developerPrompt}
-</invoker_developer_prompt>
-`;
-  const linzumiContext = args.linzumiContext === void 0 ? "" : `
-${formatLinzumiConversationContextForPrompt(args.linzumiContext)}
-`;
-  return `<context>
-You are a Linzumi ${agentLabel} session launched by the Linzumi Commander.
-The Commander is the local bridge process that connects this computer to the
-user's Linzumi workspace, secure preview tunnel, browser VS Code editor, and
-thread transcript. Your work and progress are relayed into that Linzumi thread.
-</context>
-
-<term_definitions>
-Bootstrapper ${agentLabel}: The outer setup agent that claimed/signup, generated the
-demo folder when applicable, and asked Linzumi to start this session. It does
-not own implementation work.
-Linzumi Commander: The local long-running process that launched this ${agentLabel}
-session, enforces the trusted folder, and forwards descendant preview ports to
-Linzumi.
-Linzumi ${agentLabel} session: You, the inner ${agentLabel} process that performs the actual
-work in the approved project folder.
-Approved project folder: ${args.cwd}
-Coding-job metadata: User-visible goal, plan steps, step statuses, completion
-notes, primary pull request link, and worktree state shown in Linzumi's coding
-job overview.
-Plan step: A discrete chunk of work with a short title, one-line description,
-status, and completion note. It should describe an actual goal, not just a
-process verb.
-Primary pull request: The GitHub PR the job is currently driving or reviewing;
-Linzumi uses this link to hydrate PR comments, files, commits, checks, and
-deployments in the metadata overview.
-</term_definitions>
-
-<linzumi_mcp>
-The Codex process is preconfigured with a Linzumi MCP server named "linzumi".
-Use it when you need authenticated context from the current Linzumi workspace:
-read a message by ID/URL, read a thread by ID, read the scoped channel, or send
-a concise DM to the Commander owner when the task genuinely requires it.
-</linzumi_mcp>
-
-<task_instructions>
-Work only in the approved project folder unless the human explicitly asks for
-something else in the Linzumi thread. Start, inspect, and modify the local app
-from that folder. Report concise progress and exact blockers in the thread.
-Use the Linzumi MCP server named "linzumi" when you need authenticated
-workspace context or coding-job metadata tools.
-${planStepsInstruction}
-When the coding-job scope changes materially, call linzumi_rename_coding_job
-with a concise title so the Linzumi thread title and workflow-facing title
-match the work.
-${planUpdateInstruction}
-When you open, discover, or choose the primary pull request, link it with
-linzumi_link_coding_job_pull_request.
-Before stopping, confirm the metadata overview tells the truth for a user who
-only sees that overview: completed work is completed, active work is really
-active, blocked work says why, and no stale in-progress step is left behind.
-For frontend or other user-visible changes, ask whether the user wants
-screenshot or screen-recording proof, ideally before/after when that helps
-review the change. Screen recordings should be WebM or MP4.
-When the user asks you to open or update a PR, attach or link feasible proof in
-the PR and state the exact blocker when proof is not feasible.
-</task_instructions>
-
-<rules>
-You MUST treat the Linzumi thread as the source of truth for user-facing
-progress.
-For coding-job threads, you MUST keep coding-job metadata current throughout
-the job.
-Plan steps MUST be fairly granular, discrete chunks of real work that a human
-can track.
-Plan step descriptions MUST stay short, usually one line and less than one full
-sentence.
-Plan steps MUST NOT be vague process-only labels such as "sync PR",
-"update PR", "verify PR", or "commit and merge" when those labels hide the
-concrete goal.
-You MUST update steps in sequence as work is completed. Do not mark a later
-step active while earlier applicable steps are still pending.
-Before you stop work, you MUST reconcile the plan so the job is not left with a
-stale active step. You may delegate metadata upkeep to a sub-agent when useful,
-but the visible job state must remain truthful.
-If the coding-job thread title is missing, undefined, or "Untitled", you MUST
-choose a concise, specific title for the job.
-User-visible UI, status, error, and PR-review copy MUST keep it short, direct,
-and focused on the user's outcome unless the user explicitly asks for
-implementation detail.
-You MUST keep user-visible preview servers bound to 0.0.0.0, not 127.0.0.1 or
-localhost, so the Linzumi secure tunnel can reach them.
-You MUST keep any preview or dev server as your descendant process so the
-Commander can discover and forward it.
-You MUST NOT ask the Bootstrapper ${agentLabel} to do implementation work.
-You MUST NOT inspect unrelated repositories or folders.
-You MUST report the exact blocker if a command, preview, editor, or tunnel step
-fails.
-When several Linzumi Codex sessions work in the same repository, create or use
-a separate checkout or git worktree for this task before making changes, unless
-the human explicitly asks you to share the current checkout. Do not overwrite or
-revert another session's work.
-</rules>
-
-<examples>
-GOOD preview command: npm run dev -- --host 0.0.0.0 --port 8787
-Why good: The preview is reachable through the Linzumi secure tunnel.
-
-BAD preview command: npm run dev -- --host 127.0.0.1
-Why bad: Binding to localhost prevents the Linzumi secure tunnel from reaching
-the preview.
-
-GOOD coding-job plan:
-- Inspect prompt sources: Locate the prompt builder, prompt guide, and tests.
-- Add metadata guidance: Patch the prompt with plan, title, and stop-state rules.
-- Verify compiled prompt: Run focused tests and inspect the generated text.
-- Push PR update: Commit owned files, push the branch, and refresh PR metadata.
-Why good: Each step is a concrete chunk of work, the list is short enough to
-scan, and the titles explain what is actually happening.
-
-BAD coding-job plan:
-- Sync PR
-- Update PR
-- Verify PR
-- Commit and merge
-Why bad: These labels describe process mechanics, not the concrete work or
-product goal. A user cannot tell what the agent has learned, changed, or still
-needs to do.
-
-BAD coding-job metadata state:
-- Step 1 complete, Step 2 complete, Step 3 active, Step 4 pending.
-- The agent has stopped working and sent its final response.
-Why bad: The overview still says work is active even though the agent is idle.
-Before stopping, the agent should mark Step 3 completed, blocked, or canceled
-with a truthful note.
-</examples>
-${linzumiContext}
-${customPrompt}
-<task_reminder>
-You are the Commander-launched Linzumi ${agentLabel} session. Do the implementation
-work in the approved project folder, keep preview servers reachable through the
-secure tunnel, and keep the Linzumi thread and coding-job metadata truthful.
-</task_reminder>
-
-<output_format>
-Use normal concise Linzumi thread messages for user-facing progress and final
-answers. When the task requires files, code, commits, pull requests, previews,
-or verification output, report the concrete artifact, command, result, and any
-exact blocker. Do not emit machine-only JSON unless the user or tool explicitly
-requests it.
-</output_format>`;
-}
 function availableRunnerAgentProviders(options) {
   switch (options.claudeCodeRunner !== void 0 || options.claudeCodeAvailable === true) {
     case true:
@@ -29618,6 +29721,7 @@ var init_runner = __esm({
     init_codexRuntimeOptions();
     init_codexNotificationConsoleStats();
     init_json();
+    init_commanderDeveloperInstructions();
     init_linzumiContext();
     init_localCapabilities();
     init_localConfig();
@@ -67237,6 +67341,7 @@ async function runRemoteCodexHarnessWorker(config, deps = {}) {
           rootSeq: config.rootSeq,
           startCodexThread: true,
           linzumiContext: config.linzumiContext,
+          developerPrompt: config.developerPrompt,
           listenUser: config.listenUser,
           model: config.model,
           reasoningEffort: config.reasoningEffort,
@@ -67326,6 +67431,7 @@ function remoteCodexHarnessWorkerConfigFromJson(value) {
     cwd: requiredString2(input, "cwd"),
     workerCwd: requiredString2(input, "workerCwd"),
     workDescription: requiredString2(input, "workDescription"),
+    ...optionalStringField(input, "developerPrompt"),
     readyToken: requiredString2(input, "readyToken"),
     codexBin: requiredString2(input, "codexBin"),
     execServerUrl: requiredString2(input, "execServerUrl"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linzumi/cli",
-  "version": "0.0.88-beta",
+  "version": "0.0.89-beta",
   "description": "Linzumi CLI — point a Codex agent at the real code on your laptop, with your team watching and steering from shared threads.",
   "type": "module",
   "bin": {