vibe64 0.1.21 → 0.1.22

package/node_modules/@local/studio-terminal-core/src/server/index.js

@@ -1,5 +1,6 @@
 export * from "./containerRuntime.js";
 export * from "./dockerRuntime.js";
+export * from "./gitGithubTransport.js";
 export * from "./gitToolchainMounts.js";
 export * from "./launchTargetTerminal.js";
 export * from "./managedDatabases.js";

package/node_modules/@local/studio-terminal-core/src/server/terminalSessions.js

@@ -1,3 +1,4 @@
+import { Buffer } from "node:buffer";
 import crypto from "node:crypto";
 import { spawn as spawnPty } from "node-pty";
 
@@ -47,8 +48,14 @@ function terminalSessionResponse(session) {
     id: session.id,
     commandPreview: session.commandPreview,
     exitCode: session.exitCode,
+    inputVersion: session.inputVersion || 0,
+    lastInputAt: session.lastInputAt || "",
+    lastInputBytes: session.lastInputBytes || 0,
+    lastOutputAt: session.lastOutputAt || "",
+    lastOutputBytes: session.lastOutputBytes || 0,
     metadata: session.metadata || {},
     output: session.output,
+    outputVersion: session.outputVersion || 0,
     rows: session.rows || DEFAULT_TERMINAL_ROWS,
     status: session.status
   };
@@ -101,6 +108,36 @@ function applySessionMetadata(session, metadata = {}) {
   return terminalSessionResponse(session);
 }
 
+function byteLength(value = "") {
+  return Buffer.byteLength(String(value || ""), "utf8");
+}
+
+function recordTerminalInput(session, data = "") {
+  const bytes = byteLength(data);
+  if (bytes < 1) {
+    return;
+  }
+  session.inputVersion = Number(session.inputVersion || 0) + 1;
+  session.lastInputAt = new Date().toISOString();
+  session.lastInputBytes = bytes;
+  sendToSubscribers(session, {
+    bytes,
+    inputVersion: session.inputVersion,
+    lastInputAt: session.lastInputAt,
+    type: "input"
+  });
+}
+
+function recordTerminalOutput(session, data = "") {
+  const bytes = byteLength(data);
+  if (bytes < 1) {
+    return;
+  }
+  session.outputVersion = Number(session.outputVersion || 0) + 1;
+  session.lastOutputAt = new Date().toISOString();
+  session.lastOutputBytes = bytes;
+}
+
 function sendToSubscribers(session, message) {
   if (!session?.subscribers?.size) {
     return;
@@ -300,7 +337,13 @@ function startTerminalSession({
       : {},
     onClose,
     onStop,
+    inputVersion: 0,
+    lastInputAt: "",
+    lastInputBytes: 0,
+    lastOutputAt: "",
+    lastOutputBytes: 0,
     output: "",
+    outputVersion: 0,
     rows: DEFAULT_TERMINAL_ROWS,
     status: "running",
     subscribers: new Set(),
@@ -308,9 +351,12 @@ function startTerminalSession({
   };
 
   terminal.onData((data) => {
+    recordTerminalOutput(session, data);
     session.output = trimBuffer(session.output + data);
     sendToSubscribers(session, {
       chunk: data,
+      lastOutputAt: session.lastOutputAt,
+      outputVersion: session.outputVersion,
       type: "output"
     });
     if (typeof onOutput === "function") {
@@ -420,7 +466,11 @@ function writeTerminalSession(id, data, { namespace = "default" } = {}) {
     return readTerminalSession(id, { namespace });
   }
 
-  session.terminal.write(String(data || ""));
+  const input = String(data || "");
+  if (input) {
+    recordTerminalInput(session, input);
+    session.terminal.write(input);
+  }
   return readTerminalSession(id, { namespace });
 }
 

package/node_modules/@local/vibe64-adapters/src/server/adapter.js

@@ -233,6 +233,10 @@ class TargetAdapter {
     return [];
   }
 
+  async listProjectTools() {
+    return [];
+  }
+
   async createCommandTerminalSpec(commandId) {
     return {
       ok: false,

package/node_modules/@local/vibe64-adapters/src/server/adapters/laravel/adapter.js

@@ -62,6 +62,7 @@ import {
 } from "./currentApp.js";
 import {
   createLaravelRuntimeContainers,
+  listLaravelDatabaseProjectTools,
   selectedLaravelDatabaseRuntime
 } from "./databaseRuntime.js";
 import {
@@ -428,6 +429,10 @@ class LaravelTargetAdapter extends Vibe64DescribedWorkflowTargetAdapter {
       }
     });
   }
+
+  async listProjectTools(context = {}) {
+    return listLaravelDatabaseProjectTools(context);
+  }
 }
 
 export {

package/node_modules/@local/vibe64-adapters/src/server/adapters/laravel/databaseRuntime.js

@@ -141,6 +141,54 @@ function createLaravelRuntimeContainers({
   return [];
 }
 
+function mysqlCompatibleLaravelRuntime(config = {}) {
+  return ["mysql", "mariadb"].includes(selectedLaravelDatabaseRuntime(config));
+}
+
+function mysqlClientScript() {
+  return [
+    "set -e",
+    "if command -v mysql >/dev/null 2>&1; then",
+    "  exec mysql",
+    "fi",
+    "if command -v mariadb >/dev/null 2>&1; then",
+    "  exec mariadb",
+    "fi",
+    "printf '[studio] No MySQL-compatible client was found in this toolchain.\\n' >&2",
+    "exit 127"
+  ].join("\n");
+}
+
+function listLaravelDatabaseProjectTools({
+  config = {},
+  targetRoot = ""
+} = {}) {
+  if (!mysqlCompatibleLaravelRuntime(config)) {
+    return [];
+  }
+  return [
+    {
+      id: "connect_mysql",
+      label: "Connect to MySQL",
+      description: "Open an interactive client for the configured Vibe64-managed MySQL or MariaDB service.",
+      type: "command",
+      parameters: [],
+      async command() {
+        return {
+          args: [
+            "-lc",
+            mysqlClientScript()
+          ],
+          command: "bash",
+          commandPreview: "mysql",
+          cwd: targetRoot,
+          ok: true
+        };
+      }
+    }
+  ];
+}
+
 function laravelRuntimeContainerName({
   config = {},
   targetRoot = ""
@@ -232,6 +280,8 @@ export {
   laravelDatabaseEnvWriteScript,
   laravelDatabaseNameFromTargetRoot,
   laravelRuntimeContainerName,
+  listLaravelDatabaseProjectTools,
+  mysqlCompatibleLaravelRuntime,
   selectedLaravelDatabaseRuntime,
   startLaravelRuntimeRepair
 };

package/node_modules/@local/vibe64-adapters/src/server/configStore.js

@@ -18,6 +18,8 @@ import {
 const VIBE64_CONFIG_DIR = "config";
 const VIBE64_RUNTIME_DIR = "runtime";
 const VIBE64_CONFIG_HELPER_FILE = "vibe64-config.sh";
+const VIBE64_DEPLOY_PRODUCTION_COMMAND_CONFIG = "deploy_production_command";
+const VIBE64_DEPLOY_STAGING_COMMAND_CONFIG = "deploy_staging_command";
 const CONFIG_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/u;
 const CONFIG_FIELD_TYPES = new Set(["boolean", "path", "select", "string"]);
 
@@ -45,6 +47,22 @@ const VIBE64_GENERAL_CONFIG_FIELDS = deepFreeze([
       }
     ],
     type: "select"
+  },
+  {
+    defaultValue: "",
+    description: "Command Studio should run from the main checkout when you choose Tools > Push to production.",
+    id: VIBE64_DEPLOY_PRODUCTION_COMMAND_CONFIG,
+    label: "Production deploy command",
+    required: false,
+    type: "string"
+  },
+  {
+    defaultValue: "",
+    description: "Command Studio should run from the main checkout when you choose Tools > Push to staging.",
+    id: VIBE64_DEPLOY_STAGING_COMMAND_CONFIG,
+    label: "Staging deploy command",
+    required: false,
+    type: "string"
   }
 ]);
 
@@ -444,8 +462,9 @@ function createVibe64ProjectConfigStore({
     }));
     const fieldValues = Object.fromEntries(entries);
     const values = Object.fromEntries(entries.map(([fieldId, state]) => [fieldId, state.value]));
+    const fieldById = new Map(normalizedDefinition.fields.map((field) => [field.id, field]));
     const missing = entries
-      .filter(([, state]) => !state.saved)
+      .filter(([fieldId, state]) => fieldById.get(fieldId)?.required !== false && !state.saved)
       .map(([fieldId]) => fieldId)
       .sort((left, right) => left.localeCompare(right));
     const invalid = entries
@@ -524,6 +543,8 @@ function createVibe64ProjectConfigStore({
 export {
   VIBE64_CONFIG_DIR,
   VIBE64_CONFIG_HELPER_FILE,
+  VIBE64_DEPLOY_PRODUCTION_COMMAND_CONFIG,
+  VIBE64_DEPLOY_STAGING_COMMAND_CONFIG,
   VIBE64_GENERAL_CONFIG_FIELDS,
   VIBE64_RUNTIME_DIR,
   createVibe64ProjectConfigStore,

package/node_modules/@local/vibe64-adapters/src/server/systemPrompts/agent_conversation.txt

@@ -32,11 +32,9 @@ General rules:
 - Do not modify Vibe64 session internals or artifact files.
 
 Workflow-specific behavior:
-- If `session.currentStep` is `agent_conversation`, this is the General coding change-making step. Make the requested code or project changes directly, following the adapter and framework guidance. When you are done, report what changed, what you checked, and what remains unresolved. The user decides when to continue to validation.
 - If `session.currentStep` is `implementation_reviewed`, the user is reviewing the implemented work before slower checks. Make only the focused tweak requested by `conversationRequest`, run the focused checks that prove it when practical, and submit the response through the current-step input helper.
 - If `session.currentStep` is `changes_accepted`, the user is doing final review after validation. Make only the requested final tweak. Vibe64 will send the workflow back through review and validation after this prompt completes.
 - If this step needs to show a response in Vibe64, submit that response through the current-step input helper.
-- If `metadata.workflow_definition` is `non_code_maintenance`, make the requested documentation or non-code project changes in the session worktree. Do not modify application code unless the user explicitly asks for it or it is strictly required for the non-code task.
 - For other workflow definitions, answer, inspect, or edit according to the user's request and the current step contract.
 
 Response artifact contract:

package/node_modules/@local/vibe64-adapters/src/server/systemPrompts/draft_issue.txt

@@ -0,0 +1,18 @@
+You are defining the work for this Vibe64 session.
+
+Use the user's request or feedback to propose:
+- a concise work title
+- a Markdown work description with the requested change, useful context, and acceptance criteria
+- a short Vibe64 session label/word derived from the work title
+
+If session metadata `github_issue_mode` is `create`, the saved title and description will be used to create a GitHub issue later in this same workflow step.
+If `github_issue_mode` is `skip`, no GitHub issue will be created; the saved title and description are the work anchor for planning.
+
+If Action input contains feedback about an existing draft, read the current draft artifacts from the session artifacts root before revising it:
+- issue_title
+- issue.md
+- issue_word
+
+If the request is too vague to define useful work, ask for the missing information through the current-step helper instead of guessing.
+
+When you have enough information, call the current-step helper with the proposed title, body, and word. Do not write Vibe64 workflow artifacts directly.

package/node_modules/@local/vibe64-adapters/src/server/systemPrompts/make_plan.txt

@@ -1,4 +1,4 @@
-Make plan
+Make a plan
 
 Vibe64 standard planning instructions.
 
@@ -7,6 +7,7 @@ Session:
 - current step: {{session.currentStep}}
 - target root: {{session.targetRoot}}
 - worktree path: {{session.worktreePath}}
+- artifacts root: {{session.artifactsRoot}}
 
 Known session metadata:
 {{session.metadata.json}}
@@ -19,4 +20,15 @@ Action input:
 Missing information policy:
 {{prompt.missingInformationPolicy}}
 
-Create a clear, ordered implementation plan as your normal Codex response. Use the current Codex conversation, Action input, adapter facts, and project files as context. Do not modify files while creating the plan. Do not run shell commands just to display the plan.
+Work anchor source of truth:
+- If the saved work artifacts exist, read them before planning:
+  - `{{session.artifactsRoot}}/issue_title`
+  - `{{session.artifactsRoot}}/issue.md`
+  - `{{session.artifactsRoot}}/issue_word`
+- Treat those artifacts as the work title, work description, and Vibe64 session word for this plan.
+- When `github_issue_mode` is `create` or `reuse`, the work artifacts describe the GitHub issue context. Use `issue_url` and `issue_number` metadata only as references. Do not call GitHub to rediscover the issue content unless the artifacts are missing or empty.
+- When `github_issue_mode` is `skip`, do not require or create a GitHub issue before planning. Plan from the saved work artifacts, the current Codex conversation, Action input, adapter facts, and project files.
+- If `work_source` is `existing_pr` and issue artifacts are absent, use the source PR metadata as the work anchor instead: `source_pr_url`, `source_pr_title`, `source_pr_head_ref`, and `source_pr_head_sha`.
+- For an existing PR work anchor, do not require or create an issue before planning. Plan from the PR context, the current Codex conversation, Action input, adapter facts, and project files.
+
+Create a clear, ordered implementation plan as your normal Codex response. Use the work anchor, current Codex conversation, Action input, adapter facts, and project files as context. Do not modify files while creating the plan. Do not run shell commands just to display the plan.

package/node_modules/@local/vibe64-adapters/src/server/systemPrompts/prepare_for_merge.txt

@@ -29,4 +29,6 @@ Check the PR state, identify merge blockers, resolve blockers that can be fixed
 
 Also inspect the main checkout at the target root. Confirm the base branch can be fetched, checked out, and fast-forwarded after the PR merge. If the main checkout has dirty user changes, untracked files that would be overwritten, a detached or unexpected branch state, or another local condition that makes syncing unsafe, fix only the safe mechanical blockers. Do not discard or overwrite user work. If user-owned changes block the sync, report the blocker clearly.
 
+When you complete this step, include `fields.mergePreparationSummary` in the current-step input helper result. If no extra merge-preparation work was needed after pull request creation, set it to an empty string. If you changed files, created commits, adjusted repository state, fixed merge blockers, or performed any other extra work after pull request creation, set it to a concise Markdown summary of that work.
+
 Report whether the PR is ready to merge, whether the main checkout is ready to sync, and what remains blocked.

package/node_modules/@local/vibe64-adapters/src/server/systemPrompts/resolve_pull_request.txt

@@ -23,6 +23,7 @@ Body guidance:
 - Summarize the user-visible change.
 - List important files or areas changed.
 - List verification already run, or clearly say when verification is still pending.
+- If this session stacks on `source_pr_url`, mention that relationship in the pull request body.
 - Mention blockers or risks only when they matter to the reviewer.
 
 After the helper reports success, stop.

package/node_modules/@local/vibe64-adapters/src/server/systemPrompts/run_deep_ui_check.txt

@@ -1,6 +1,6 @@
-Run deep UI check
+Check user interface
 
-Vibe64 standard deep UI check instructions.
+Vibe64 standard user interface check instructions.
 
 Session:
 - id: {{session.id}}
@@ -19,4 +19,8 @@ Action input:
 Missing information policy:
 {{prompt.missingInformationPolicy}}
 
-Inspect the user-facing application behavior carefully. Focus on real UI defects, broken flows, layout issues, state mistakes, and mismatches with the requested work. Fix clear defects directly when the project supports it. Report what you changed, which checks ran, and why no edit was needed if the UI is already sound.
+Changed-files scope:
+Before inspecting the application, identify the session worktree diff and changed files. Only check user-facing behavior that could plausibly be affected by those changed files and the requested work. Do not run a broad whole-application UI audit. If the changed files do not affect UI behavior, say that directly and complete the step without spending time on unrelated screens.
+Hard stop: if the diff only contains non-UI files, documentation, generated helper-map output, or inert root files such as an empty `.txt` file, do not launch the app, browse unrelated screens, or run a whole UI check. Report that no user-interface check is needed for the changed files and complete the step.
+
+Inspect the affected user-facing application behavior carefully. Focus on real UI defects, broken flows, layout issues, state mistakes, and mismatches with the requested work. Fix clear defects directly when the project supports it. Report what you changed, which checks ran, and why no edit was needed if the affected UI is already sound.

package/node_modules/@local/vibe64-adapters/src/server/workflowCommandTerminal/commitPush.js

@@ -17,13 +17,10 @@ import {
 
 function commitChangesScript(session = {}) {
   const issueTitlePath = metadataFilePath(session, "issue_title");
-  const directExistingPr = normalizeText(session.metadata?.work_source) === "existing_pr" &&
-    normalizeText(session.metadata?.source_pr_update_mode) === "direct";
   const baseBranch = normalizeText(session.metadata?.base_branch) ||
+    normalizeText(session.metadata?.source_pr_head_ref) ||
     normalizeText(session.metadata?.source_pr_base_ref) ||
     "main";
-  const sourcePrHeadRef = normalizeText(session.metadata?.source_pr_head_ref);
-  const sourcePrHeadRepo = normalizeText(session.metadata?.source_pr_head_repo);
   return [
     "set -e",
     `COMMIT_TITLE="$(cat ${shellQuote(issueTitlePath)} 2>/dev/null | head -n 1 | sed 's/[[:space:]]*$//')"`,
@@ -51,24 +48,9 @@ function commitChangesScript(session = {}) {
     "  exit 1",
     "fi",
     "ACCEPTED_COMMIT=\"$(git rev-parse --verify HEAD)\"",
-    ...(directExistingPr ? [
-      `SOURCE_PR_HEAD_REF=${shellQuote(sourcePrHeadRef)}`,
-      `SOURCE_PR_HEAD_REPO=${shellQuote(sourcePrHeadRepo)}`,
-      "if [ -z \"$SOURCE_PR_HEAD_REF\" ] || [ -z \"$SOURCE_PR_HEAD_REPO\" ]; then",
-      "  printf '[studio] Existing PR push target is missing.\\n' >&2",
-      "  exit 1",
-      "fi",
-      "PR_HEAD_REMOTE=\"vibe64-pr-head\"",
-      "git remote remove \"$PR_HEAD_REMOTE\" >/dev/null 2>&1 || true",
-      "git remote add \"$PR_HEAD_REMOTE\" \"https://github.com/$SOURCE_PR_HEAD_REPO.git\"",
-      "printf '[studio] Pushing changes to existing PR branch %s/%s\\n' \"$SOURCE_PR_HEAD_REPO\" \"$SOURCE_PR_HEAD_REF\"",
-      "git push \"$PR_HEAD_REMOTE\" \"HEAD:refs/heads/$SOURCE_PR_HEAD_REF\"",
-      recordCommandFactScript("branch_pushed", "\"$SOURCE_PR_HEAD_REF\"")
-    ] : [
-      "printf '[studio] Pushing branch %s\\n' \"$CURRENT_BRANCH\"",
-      "git push -u origin \"$CURRENT_BRANCH\"",
-      recordCommandFactScript("branch_pushed", "\"$CURRENT_BRANCH\"")
-    ]),
+    "printf '[studio] Pushing branch %s\\n' \"$CURRENT_BRANCH\"",
+    "git push -u origin \"$CURRENT_BRANCH\"",
+    recordCommandFactScript("branch_pushed", "\"$CURRENT_BRANCH\""),
     recordCommandFactScript("accepted_commit", "\"$ACCEPTED_COMMIT\""),
     "printf '[studio] Committed %s\\n' \"$ACCEPTED_COMMIT\""
   ].join("\n");

package/node_modules/@local/vibe64-adapters/src/server/workflowCommandTerminal/factMetadata.js

@@ -37,27 +37,23 @@ function createWorktreeSuccessMetadataFromFacts({ facts = {}, session = {} } = {
     return commandMetadataResult();
   }
 
-  const updateMode = normalizeText(facts.source_pr_update_mode);
-  if (updateMode === "direct") {
-    return commandMetadataResult({
-      metadata: {
-        pr_source: "existing",
-        pr_url: normalizeText(facts.pr_url) || normalizeText(session.metadata?.source_pr_url),
-        source_pr_update_mode: "direct"
-      }
-    });
-  }
-
-  if (updateMode === "replacement") {
-    return commandMetadataResult({
-      deleteMetadata: ["pr_url"],
-      metadata: {
-        source_pr_update_mode: "replacement"
-      }
-    });
+  const updateMode = normalizeText(facts.source_pr_update_mode) ||
+    normalizeText(session.metadata?.source_pr_update_mode);
+  if (updateMode !== "stacked" && !normalizeText(session.metadata?.source_pr_url)) {
+    return commandMetadataResult();
   }
 
-  return commandMetadataResult();
+  const sessionPrUrl = normalizeText(session.metadata?.pr_url);
+  const sourcePrUrl = normalizeText(session.metadata?.source_pr_url);
+  const deletePrMetadata = sessionPrUrl && sessionPrUrl === sourcePrUrl
+    ? ["pr_url", "pr_source", "pr_number", "pr_title"]
+    : [];
+  return commandMetadataResult({
+    deleteMetadata: deletePrMetadata,
+    metadata: {
+      source_pr_update_mode: "stacked"
+    }
+  });
 }
 
 function commitChangesSuccessMetadataFromFacts({ facts = {} } = {}) {
@@ -80,7 +76,12 @@ function createIssueSuccessMetadataFromFacts({ facts = {} } = {}) {
   }
   return commandMetadataResult({
     metadata: {
+      github_issue_mode: "create",
       issue_source: "created",
+      work_anchor_number: normalizeText(metadata.issue_number),
+      work_anchor_title: normalizeText(metadata.issue_title),
+      work_anchor_type: "issue",
+      work_anchor_url: normalizeText(metadata.issue_url),
       ...metadata
     }
   });
@@ -99,7 +100,7 @@ function createPrSuccessMetadataFromFacts({ facts = {}, session = {} } = {}) {
   return commandMetadataResult({
     metadata: {
       ...metadata,
-      pr_source: normalizeText(metadata.pr_source) || (normalizeText(session.metadata?.source_pr_url) ? "replacement" : "created")
+      pr_source: normalizeText(metadata.pr_source) || (normalizeText(session.metadata?.source_pr_url) ? "stacked" : "created")
     }
   });
 }

package/node_modules/@local/vibe64-adapters/src/server/workflowCommandTerminal/issuePr.js

@@ -46,12 +46,16 @@ function createIssueOnGhScript(session = {}) {
 }
 
 function createPrOnGhScript(session = {}) {
-  const stepId = "create_pull_request";
+  const stepId = "create_and_merge_pull_request";
   const prBodyPath = artifactFilePath(session, `tmp/${stepId}.body.md`);
   const prTitlePath = artifactFilePath(session, `tmp/${stepId}.title.txt`);
+  const sourcePrHeadSha = normalizeText(session.metadata?.source_pr_head_sha);
+  const sourcePrNumber = normalizeText(session.metadata?.source_pr_number);
   const sourcePrUrl = normalizeText(session.metadata?.source_pr_url);
   const branch = normalizeText(session.metadata?.branch);
-  const baseBranch = normalizeText(session.metadata?.base_branch) || "main";
+  const baseBranch = normalizeText(session.metadata?.base_branch) ||
+    normalizeText(session.metadata?.source_pr_head_ref) ||
+    "main";
   const quotedBaseBranch = shellQuote(baseBranch);
   const quotedBranch = shellQuote(branch);
   return [
@@ -71,6 +75,25 @@ function createPrOnGhScript(session = {}) {
     "  printf '[studio] Worktree is on branch %s, expected %s.\\n' \"$CURRENT_BRANCH\" \"$EXPECTED_BRANCH\" >&2",
     "  exit 1",
     "fi",
+    `SOURCE_PR_NUMBER=${shellQuote(sourcePrNumber)}`,
+    `SOURCE_PR_HEAD_SHA=${shellQuote(sourcePrHeadSha)}`,
+    "if [ -n \"$SOURCE_PR_NUMBER\" ]; then",
+    "  printf '[studio] Validating stacked PR base #%s\\n' \"$SOURCE_PR_NUMBER\"",
+    "  SOURCE_PR_STATE=\"$(gh pr view \"$SOURCE_PR_NUMBER\" --json state --jq '.state' 2>/dev/null | head -n 1 | sed 's/[[:space:]]*$//')\"",
+    "  SOURCE_PR_CURRENT_SHA=\"$(gh pr view \"$SOURCE_PR_NUMBER\" --json headRefOid --jq '.headRefOid' 2>/dev/null | head -n 1 | sed 's/[[:space:]]*$//')\"",
+    "  if [ -z \"$SOURCE_PR_STATE\" ] || [ -z \"$SOURCE_PR_CURRENT_SHA\" ]; then",
+    "    printf '[studio] Could not validate existing PR #%s. Check GitHub access, then retry.\\n' \"$SOURCE_PR_NUMBER\" >&2",
+    "    exit 1",
+    "  fi",
+    "  if [ \"$SOURCE_PR_STATE\" != \"OPEN\" ]; then",
+    "    printf '[studio] Existing PR #%s is %s. Start a new session from the current work anchor.\\n' \"$SOURCE_PR_NUMBER\" \"$SOURCE_PR_STATE\" >&2",
+    "    exit 1",
+    "  fi",
+    "  if [ -n \"$SOURCE_PR_HEAD_SHA\" ] && [ \"$SOURCE_PR_CURRENT_SHA\" != \"$SOURCE_PR_HEAD_SHA\" ]; then",
+    "    printf '[studio] Existing PR #%s moved from %s to %s. Start a new session from the updated PR.\\n' \"$SOURCE_PR_NUMBER\" \"$SOURCE_PR_HEAD_SHA\" \"$SOURCE_PR_CURRENT_SHA\" >&2",
+    "    exit 1",
+    "  fi",
+    "fi",
     "git fetch origin \"$BASE_BRANCH\"",
     "BASE_REF=\"origin/$BASE_BRANCH\"",
     "if ! git rev-parse --verify \"$BASE_REF\" >/dev/null 2>&1; then",
@@ -88,7 +111,7 @@ function createPrOnGhScript(session = {}) {
     "fi",
     `SOURCE_PR_URL=${shellQuote(sourcePrUrl)}`,
     "if [ -n \"$SOURCE_PR_URL\" ]; then",
-    "  PR_SOURCE=replacement",
+    "  PR_SOURCE=stacked",
     "else",
     "  PR_SOURCE=created",
     "fi",
@@ -96,7 +119,7 @@ function createPrOnGhScript(session = {}) {
     "if [ -n \"$SOURCE_PR_URL\" ]; then",
     "  PR_BODY_FILE=\"$(mktemp)\"",
     `  cat ${shellQuote(prBodyPath)} > "$PR_BODY_FILE"`,
-    "  printf '\\n\\nContinues existing pull request: %s\\n' \"$SOURCE_PR_URL\" >> \"$PR_BODY_FILE\"",
+    "  printf '\\n\\nStacks on existing pull request: %s\\n' \"$SOURCE_PR_URL\" >> \"$PR_BODY_FILE\"",
     "fi",
     "find_existing_pull_request_url() {",
     "  gh pr list --head \"$EXPECTED_BRANCH\" --base \"$BASE_BRANCH\" --state open --json url --jq '.[0].url' 2>/dev/null | head -n 1 | sed 's/[[:space:]]*$//'",

package/node_modules/@local/vibe64-adapters/src/server/workflowCommandTerminal/mergeSync.js

@@ -21,6 +21,7 @@ function mergePrScript({
   session = {}
 } = {}) {
   const prUrl = normalizeText(session.metadata?.pr_url);
+  const mergePreparationSummary = normalizeText(session.metadata?.merge_preparation_summary);
   const mergeFlag = {
     merge: "--merge",
     rebase: "--rebase",
@@ -30,18 +31,50 @@ function mergePrScript({
     "set -e",
     beforeMergeScript,
     `printf '[studio] Merging pull request %s\\n' ${shellQuote(prUrl)}`,
-    `gh pr merge ${shellQuote(prUrl)} ${mergeFlag}`
+    `gh pr merge ${shellQuote(prUrl)} ${mergeFlag}`,
+    mergePreparationCommentScript({
+      prUrl,
+      summary: mergePreparationSummary
+    })
   ].filter(Boolean).join("\n");
 }
 
-function syncMainCheckoutScript(session = {}, targetRoot = "") {
-  const baseBranch = normalizeText(session.metadata?.base_branch) || "main";
+function mergePreparationCommentScript({
+  prUrl = "",
+  summary = ""
+} = {}) {
+  const normalizedSummary = normalizeText(summary);
+  if (!normalizedSummary) {
+    return "";
+  }
+  const comment = [
+    "## Vibe64 merge preparation",
+    "",
+    "Additional merge-preparation work was performed after this pull request was created and before it was merged.",
+    "",
+    normalizedSummary
+  ].join("\n");
+  return [
+    `MERGE_PREPARATION_COMMENT_FILE="$(mktemp)"`,
+    `printf '%s\\n' ${shellQuote(comment)} > "$MERGE_PREPARATION_COMMENT_FILE"`,
+    `if ! gh pr comment ${shellQuote(prUrl)} --body-file "$MERGE_PREPARATION_COMMENT_FILE"; then`,
+    `  printf '[studio] Merge-preparation comment failed; pull request was already merged.\\n' >&2`,
+    "fi",
+    `rm -f "$MERGE_PREPARATION_COMMENT_FILE"`
+  ].join("\n");
+}
+
+function syncMainCheckoutScript({
+  baseBranch = "main",
+  targetRoot = ""
+} = {}) {
+  const normalizedBaseBranch = normalizeText(baseBranch) || "main";
   return [
     "set -e",
-    `printf '[studio] Syncing main checkout %s to %s\\n' ${shellQuote(targetRoot)} ${shellQuote(baseBranch)}`,
-    `git -C ${shellQuote(targetRoot)} fetch origin ${shellQuote(baseBranch)}`,
-    `git -C ${shellQuote(targetRoot)} checkout ${shellQuote(baseBranch)}`,
-    `git -C ${shellQuote(targetRoot)} pull --ff-only origin ${shellQuote(baseBranch)}`
+    `printf '[studio] Syncing main checkout %s to %s\\n' ${shellQuote(targetRoot)} ${shellQuote(normalizedBaseBranch)}`,
+    `git -C ${shellQuote(targetRoot)} fetch origin ${shellQuote(normalizedBaseBranch)}`,
+    `git -C ${shellQuote(targetRoot)} checkout ${shellQuote(normalizedBaseBranch)}`,
+    `git -C ${shellQuote(targetRoot)} pull --ff-only origin ${shellQuote(normalizedBaseBranch)}`
   ].join("\n");
 }
 
@@ -102,11 +135,35 @@ async function syncMainCheckoutTerminalSpec({
     metadata: {
       main_checkout_synced: "yes"
     },
-    script: syncMainCheckoutScript(session, syncRoot)
+    script: syncMainCheckoutScript({
+      baseBranch: session.metadata?.base_branch,
+      targetRoot: syncRoot
+    })
+  });
+}
+
+async function projectSyncMainCheckoutTerminalSpec({
+  baseBranch = "main",
+  targetRoot = ""
+} = {}) {
+  const syncRoot = targetRoot || process.cwd();
+  return completedMetadataSpec({
+    commandPreview: "git fetch && git pull --ff-only",
+    cwd: syncRoot,
+    label: "Sync main checkout",
+    metadata: {
+      main_checkout_synced: "yes"
+    },
+    script: syncMainCheckoutScript({
+      baseBranch,
+      targetRoot: syncRoot
+    })
   });
 }
 
 export {
   mergePrTerminalSpec,
+  projectSyncMainCheckoutTerminalSpec,
+  syncMainCheckoutScript,
   syncMainCheckoutTerminalSpec
 };