@jskit-ai/jskit-cli 0.2.84 → 0.2.86

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.84",
+  "version": "0.2.86",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,9 +20,9 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.83",
-    "@jskit-ai/kernel": "0.1.75",
-    "@jskit-ai/shell-web": "0.1.74",
+    "@jskit-ai/jskit-catalog": "0.1.85",
+    "@jskit-ai/kernel": "0.1.77",
+    "@jskit-ai/shell-web": "0.1.76",
     "@vue/compiler-sfc": "^3.5.29",
     "ts-morph": "^28.0.0"
   },

package/src/server/commandHandlers/appCommandCatalog.js

@@ -51,7 +51,7 @@ const APP_COMMAND_DEFINITIONS = Object.freeze({
     options: Object.freeze([
       Object.freeze({
         label: "--command <shell-command>",
-        description: "Targeted Playwright command to run, for example: npx playwright test tests/e2e/contacts.spec.ts -g filters."
+        description: "Targeted UI verification command to run. If it uses Playwright against a local app, the command/environment must start or reuse a reachable app server first."
       }),
       Object.freeze({
         label: "--feature <label>",
@@ -68,6 +68,7 @@ const APP_COMMAND_DEFINITIONS = Object.freeze({
     ]),
     defaults: Object.freeze([
       "Requires a git working tree so the receipt can record the currently changed UI files.",
+      "Does not start the app server; make --command self-contained for UI tests that need one.",
       "Writes .jskit/verification/ui.json after the command succeeds.",
       "Doctor expects the receipt to match the current dirty UI file set, or the same --against <base-ref> delta when used."
     ])

package/src/server/commandHandlers/session.js

@@ -7,6 +7,7 @@ import {
   inspectSessionDiff,
   inspectSessionDetails,
   listSessions,
+  rewindSession,
   runSessionStep
 } from "../sessionRuntime.js";
 
@@ -270,7 +271,7 @@ async function resolveStepInputs({
     fileOption: "close-reason-file",
     inlineOptions,
     io,
-    repairCommand: `jskit session ${sessionId} step --close-without-merge --close-reason "<reason>"`,
+    repairCommand: `jskit session ${sessionId} step --skip-merge --close-reason "<reason>"`,
     cwd,
     sessionId,
     stdinOption: "-",
@@ -312,10 +313,14 @@ async function resolveStepInputs({
 function normalizeStepOptions(inlineOptions = {}) {
   const options = {
     ...inlineOptions,
-    closeWithoutMerge: inlineOptions["close-without-merge"] === "true" || inlineOptions.closeWithoutMerge === true,
+    closeWithoutMerge: inlineOptions["close-without-merge"] === "true" ||
+      inlineOptions.closeWithoutMerge === true ||
+      inlineOptions["skip-merge"] === "true" ||
+      inlineOptions.skipMerge === true,
     mergePr: inlineOptions["merge-pr"] === "true" || inlineOptions.mergePr === true,
     prompt: inlineOptions.prompt,
     reviewFindings: inlineOptions["review-findings"] || inlineOptions.reviewFindings,
+    skipMainSync: inlineOptions["skip-main-sync"] === "true" || inlineOptions.skipMainSync === true,
     skipUiCheck: inlineOptions["skip-ui-check"] === "true" || inlineOptions.skipUiCheck === true,
     userCheck: inlineOptions["user-check"] || inlineOptions.userCheck
   };
@@ -395,6 +400,12 @@ function createSessionCommands() {
           targetRoot: cwd,
           sessionId: first
         });
+      } else if (second === "rewind") {
+        payload = await rewindSession({
+          targetRoot: cwd,
+          sessionId: first,
+          stepId: inlineOptions.step
+        });
       } else if (second === "adopt-codex-thread") {
         payload = await adoptCodexThreadId({
           targetRoot: cwd,

package/src/server/core/argParser.js

@@ -145,6 +145,14 @@ function parseArgs(argv, { createCliError } = {}) {
       options.inlineOptions["close-without-merge"] = "true";
       continue;
     }
+    if (token === "--skip-merge") {
+      options.inlineOptions["skip-merge"] = "true";
+      continue;
+    }
+    if (token === "--skip-main-sync") {
+      options.inlineOptions["skip-main-sync"] = "true";
+      continue;
+    }
 
     if (token.startsWith("--")) {
       const withoutPrefix = token.slice(2);

package/src/server/core/commandCatalog.js

@@ -212,8 +212,8 @@ const COMMAND_DESCRIPTORS = Object.freeze({
         description: "Create a session, inspect a session, or run a session subcommand."
       }),
       Object.freeze({
-        name: "[step|abandon|adopt-codex-thread]",
-        description: "Run the next step, inspect a diff, abandon a session, or attach a Codex thread id."
+        name: "[step|diff|rewind|abandon|adopt-codex-thread]",
+        description: "Run the next step, inspect a diff, rewind a session, abandon a session, or attach a Codex thread id."
       })
     ]),
     defaults: Object.freeze([
@@ -227,13 +227,17 @@ const COMMAND_DESCRIPTORS = Object.freeze({
       "Use --issue-details - to read confirmed issue details from stdin.",
       "Use --plan - to read the approved implementation plan from stdin.",
       "Use --codex-result - after Codex prompt steps to read the final marked Codex result from stdin.",
+      "Use rewind --step <step_id> to delete a completed step and later JSKIT-owned session artifacts; only plan_made is allowed inside the repeatable cycle.",
       "Use --rework-notes - with --user-check failed to start the next plan cycle.",
       "Use --agent-decisions - to append session-local decision log entries from implementation, UI review, verification, or repair phases.",
       "Use --review-findings-remaining true --review-findings \"<findings>\" when an accepted review pass needs another pass.",
       "Use --review-findings-remaining false only when the review/deslop loop is done.",
       "Use --skip-ui-check --skip-reason \"<reason>\" only when uiImpact is possible and the Deep UI Check is intentionally skipped.",
+      "Use --prepare-merge true at PR merge preparation to render the Codex prep prompt.",
+      "Use --continue-to-merge true when the user decides to advance from preparation to merge decision.",
       "Use --merge-pr true at PR finalization to merge the pull request.",
-      "Use --close-without-merge --close-reason \"<reason>\" at PR finalization to complete the session without merging.",
+      "Use --skip-merge at PR finalization to complete the session without merging.",
+      "Use --skip-main-sync at Main checkout synced to explicitly leave the main checkout untouched.",
       "Run the blueprint step once to render its Codex prompt, then again after Codex updates .jskit/APP_BLUEPRINT.md."
     ]),
     examples: Object.freeze([
@@ -252,15 +256,19 @@ const COMMAND_DESCRIPTORS = Object.freeze({
           "jskit session 2026-05-11_21-42-08 step --review-findings-remaining false",
           "jskit session 2026-05-11_21-42-08 step --skip-ui-check --skip-reason \"No user-facing UI changes\"",
           "jskit session 2026-05-11_21-42-08 step",
+          "jskit session 2026-05-11_21-42-08 step --prepare-merge true",
+          "jskit session 2026-05-11_21-42-08 step --continue-to-merge true",
           "jskit session 2026-05-11_21-42-08 step --merge-pr true",
-          "jskit session 2026-05-11_21-42-08 step --close-without-merge --close-reason \"Prototype kept for reference\"",
+          "jskit session 2026-05-11_21-42-08 step --skip-merge",
+          "jskit session 2026-05-11_21-42-08 step --skip-main-sync",
           "jskit session 2026-05-11_21-42-08 step --user-check failed --rework-notes -",
+          "jskit session 2026-05-11_21-42-08 rewind --step plan_made --json",
           "jskit session 2026-05-11_21-42-08 diff --json"
         ])
       })
     ]),
     fullUse:
-      "jskit session [create|<sessionId>] [step|diff|abandon|adopt-codex-thread] [--prompt <text>] [--issue-title <text>|--issue-title-file <path>] [--issue <text>|--issue-file <path>] [--issue-details <text>|--issue-details-file <path>] [--plan <text>|--plan-file <path>] [--codex-result <text>|--codex-result-file <path>] [--agent-decisions <text>|--agent-decisions-file <path>] [--review-findings-remaining true --review-findings <text>|--review-findings-remaining false] [--skip-ui-check --skip-reason <text>] [--merge-pr true|--close-without-merge --close-reason <text>] [--user-check <passed|failed>] [--rework-notes <text>|--rework-notes-file <path>] [--codex-thread-id <id>] [--abandoned|--completed|--all] [--json]",
+      "jskit session [create|<sessionId>] [step|diff|rewind|abandon|adopt-codex-thread] [--step <step_id>] [--prompt <text>] [--issue-title <text>|--issue-title-file <path>] [--issue <text>|--issue-file <path>] [--issue-details <text>|--issue-details-file <path>] [--plan <text>|--plan-file <path>] [--codex-result <text>|--codex-result-file <path>] [--agent-decisions <text>|--agent-decisions-file <path>] [--review-findings-remaining true --review-findings <text>|--review-findings-remaining false] [--skip-ui-check --skip-reason <text>] [--prepare-merge true|--continue-to-merge true|--merge-pr true|--skip-merge|--skip-main-sync] [--user-check <passed|failed>] [--rework-notes <text>|--rework-notes-file <path>] [--codex-thread-id <id>] [--abandoned|--completed|--all] [--json]",
     showHelpOnBareInvocation: false,
     handlerName: "commandSession",
     allowedFlagKeys: Object.freeze(["json", "abandoned", "completed", "all"]),

package/src/server/sessionRuntime/constants.js

@@ -263,6 +263,12 @@ const BLUEPRINT_CODEX_HANDOFF = codexHandoff([], {
   promptActionLabel: "Update blueprint",
   responseContract: JSKIT_STEP_RESULT_CONTRACT
 });
+const PR_MERGE_PREP_CODEX_HANDOFF = codexHandoff([], {
+  autoInject: true,
+  promptActionLabel: "Get Codex ready to merge PR",
+  promptWaitingText: "Codex is preparing the PR for merge. Continue only when you decide the PR is ready.",
+  responseContract: null
+});
 
 function defineStep({
   buttonLabel,
@@ -497,23 +503,53 @@ const STEP_DEFINITIONS = Object.freeze([
     label: "Branch pushed, PR created",
     preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied", "active_cycle_user_check_passed", "accepted_changes_committed", "blueprint_update_satisfied", "final_report_exists"]
   }),
+  defineStep({
+    buttonLabel: "Continue to merge",
+    codex: PR_MERGE_PREP_CODEX_HANDOFF,
+    description: "User can ask Codex to prepare the pull request for merge, then explicitly continue to the merge decision.",
+    id: "pr_merge_prepared",
+    label: "PR merge prepared",
+    preconditions: ["session_exists", "pr_url_exists", "worktree_exists"],
+    requiresExplicitRun: true,
+    submitOptions: Object.freeze({
+      continueToMerge: true
+    }),
+    utilityActions: Object.freeze([
+      Object.freeze({
+        id: "prepare_pr_merge",
+        kind: "codex_prompt",
+        label: "Get Codex ready to merge PR",
+        submitOptions: Object.freeze({
+          prepareMerge: true
+        })
+      })
+    ])
+  }),
   defineStep({
     buttonLabel: "Merge PR",
-    description: "User chooses whether JSKIT merges the pull request or finishes without merge; JSKIT then removes the session worktree.",
+    description: "User chooses whether JSKIT merges the pull request or skips merge; JSKIT records the PR outcome.",
     id: "pr_finalized",
-    label: "PR finalized, worktree removed",
+    label: "PR finalized",
     preconditions: ["session_exists", "pr_url_exists", "worktree_exists"],
     requiresExplicitRun: true,
     submitOptions: Object.freeze({
       mergePr: true
     })
   }),
+  defineStep({
+    buttonLabel: "Sync main checkout",
+    description: "JSKIT fast-forwards the main checkout after a merged PR, or records an explicit skip before cleanup.",
+    id: "main_checkout_synced",
+    label: "Main checkout synced",
+    preconditions: ["session_exists", "worktree_exists"],
+    requiresExplicitRun: true
+  }),
   defineStep({
     buttonLabel: "Finish session",
-    description: "JSKIT writes the final receipt and archives the completed session.",
+    description: "JSKIT removes the session worktree, writes the final receipt, and archives the completed session.",
     id: "session_finished",
-    label: "Session finished",
-    preconditions: ["session_exists"]
+    label: "Worktree removed, session finished",
+    preconditions: ["session_exists", "main_checkout_sync_satisfied"]
   })
 ]);
 
@@ -553,6 +589,7 @@ export {
   DEEP_UI_CHECK_CODEX_HANDOFF,
   AUTOMATED_CHECK_REPAIR_CODEX_HANDOFF,
   BLUEPRINT_CODEX_HANDOFF,
+  PR_MERGE_PREP_CODEX_HANDOFF,
   JSKIT_CLI_SHELL_COMMAND,
   JSKIT_CLI_SHELL_RULE,
   SESSION_STATE_RELATIVE_PATH

package/src/server/sessionRuntime/preconditions.js

@@ -710,6 +710,33 @@ async function assertPrUrlExists(paths) {
   };
 }
 
+async function assertMainCheckoutSyncSatisfied(paths) {
+  const receiptPath = path.join(paths.sessionRoot, "steps", "main_checkout_synced");
+  if (await pathExists(receiptPath)) {
+    return {
+      ok: true,
+      precondition: createPrecondition({
+        id: "main_checkout_sync_satisfied",
+        ok: true,
+        message: "Main checkout sync has been completed or skipped."
+      })
+    };
+  }
+  return {
+    ok: false,
+    error: createError({
+      code: "main_checkout_sync_required",
+      message: "Main checkout sync must be completed or explicitly skipped before session cleanup.",
+      repairCommand: jskitCommand(`session ${paths.sessionId} step`)
+    }),
+    precondition: createPrecondition({
+      id: "main_checkout_sync_satisfied",
+      ok: false,
+      message: "Main checkout sync has been completed or skipped."
+    })
+  };
+}
+
 export {
   applyPreconditions,
   assertAcceptedChangesCommitted,
@@ -728,6 +755,7 @@ export {
   assertIssueUrlExists,
   assertAutomatedChecksPassed,
   assertIssueDetailsExists,
+  assertMainCheckoutSyncSatisfied,
   assertPlanTextExists,
   assertPrUrlExists,
   assertReadyJskitApp,

package/src/server/sessionRuntime/prompts/deep_ui_check.md

@@ -34,6 +34,8 @@ Use Playwright for a meaningful route check when possible. If login is required,
 
 `npx --no-install jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>`
 
+Important: `npx --no-install jskit app verify-ui` does not start the app server. Before running it, make sure the app is reachable by Playwright. If a local server is needed, inspect `.jskit/config/testrun_command` when present and use the app's documented server command, or start the server explicitly and wait for it before invoking `verify-ui`. Do not first run a bare Playwright command against a stopped server.
+
 Do not create commits, branches, issues, pull requests, merges, or worktree cleanup. JSKIT session owns those steps.
 
 If this pass makes UI fixes, intentionally skips UI work after inspection, changes a design direction, or leaves a meaningful UI verification gap, include concise decision entries with reasons in this exact marker block:

package/src/server/sessionRuntime/prompts/execute_plan.md

@@ -41,6 +41,7 @@ After making changes:
 - Review for repeated code, unnecessary helpers, fragmented functions, placeholder work, missing states, broken route wiring, ownership mistakes, and weak JSKIT reuse.
 - Run the smallest relevant checks you can run safely in the worktree.
 - For changed user-facing UI, run or clearly identify the Playwright verification path. When possible, record UI verification with `npx --no-install jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>`.
+- `npx --no-install jskit app verify-ui` does not start the app server. Before using it for Playwright, make sure the app is reachable. If a local server is needed, inspect `.jskit/config/testrun_command` when present and use the app's documented server command, or start the server explicitly and wait for it before invoking `verify-ui`. Do not first run a bare Playwright command against a stopped server.
 - Summarize changed files and checks run.
 - If implementation deviated from the approved plan, generator choices, package ownership, helper reuse, UI verification path, or data ownership, include concise decision entries with reasons in this exact marker block:
 

package/src/server/sessionRuntime/prompts/prepare_pr_merge.md

@@ -0,0 +1,22 @@
+Prepare the JSKIT session pull request for merge.
+
+Session: {{session_id}}
+Worktree: {{worktree}}
+Target root: {{target_root}}
+Branch: {{branch}}
+Base branch: {{base_branch}}
+Pull request: {{pr_url}}
+Issue: {{issue_url}}
+Final report: {{final_report_file}}
+
+Your job is to get the pull request into a state where the user can decide whether to press the JSKIT Merge PR button.
+
+Required boundaries:
+
+- Inspect the pull request state, checks, and branch status.
+- Resolve merge conflicts or failing checks if the fix is clear and in scope.
+- Commit and push any preparation changes to the session branch.
+- Do not merge the pull request.
+- Do not remove the worktree, archive the session, update the local base branch, or write JSKIT receipts. JSKIT owns deterministic cleanup after the user decides.
+
+When you are done, summarize what you checked, what changed, and whether you believe the PR is ready for the user to merge.

package/src/server/sessionRuntime/prompts/review_changes.md

@@ -51,6 +51,7 @@ Use four passes:
    - run the smallest relevant verification commands for the changed scope
    - any changed user-facing UI should be exercised with Playwright when possible
    - UI verification should normally be recorded through `npx --no-install jskit app verify-ui`
+   - `npx --no-install jskit app verify-ui` does not start the app server; if Playwright needs a local server, inspect `.jskit/config/testrun_command` when present and start or wrap the documented server command before invoking `verify-ui`
    - if login is required, use the chosen local test-auth path instead of live external auth
    - if there is no usable local auth bootstrap path, record it as a blocking testability gap
 

package/src/server/sessionRuntime/responses.js

@@ -241,6 +241,7 @@ const PROMPT_ARTIFACT_BY_STEP_ID = Object.freeze({
   deep_ui_check_run: "deep_ui_check_run.md",
   automated_checks_run: "automated_checks_run.md",
   blueprint_updated: "update_blueprint.md",
+  pr_merge_prepared: "prepare_pr_merge.md",
   user_check_completed: "user_check.md"
 });
 
@@ -589,7 +590,8 @@ function buildStepDefinitions() {
 function stepIsRetryableWhenBlocked(stepId) {
   return [
     "automated_checks_run",
-    "deep_ui_check_run"
+    "deep_ui_check_run",
+    "main_checkout_synced"
   ].includes(normalizeStepId(stepId));
 }
 
@@ -681,17 +683,12 @@ function buildCurrentStepAction(stepId, artifacts = {}) {
   }
   if (step.id === "pr_finalized") {
     alternateActions.push({
-      id: "close_without_merge",
-      helpText: "Leave the PR open, record the reason, and remove the session worktree without merging.",
+      id: "skip_merge",
+      helpText: "Leave the PR open and record the skipped-merge outcome; final cleanup removes the session worktree.",
       input: {
-        formatHint: "markdown",
-        label: "Why is this session finishing without merge?",
-        multiline: true,
-        name: "closeReason",
-        required: true,
-        type: "text"
+        type: "none"
       },
-      label: "Finish without merge",
+      label: "Skip merge",
       presentation: "secondary",
       submitOptions: {
         closeWithoutMerge: true
@@ -699,6 +696,21 @@ function buildCurrentStepAction(stepId, artifacts = {}) {
       targetStep: "pr_finalized"
     });
   }
+  if (step.id === "main_checkout_synced") {
+    alternateActions.push({
+      id: "skip_main_checkout_sync",
+      helpText: "Leave the main checkout untouched and continue with session cleanup.",
+      input: {
+        type: "none"
+      },
+      label: "Skip sync",
+      presentation: "secondary",
+      submitOptions: {
+        skipMainSync: true
+      },
+      targetStep: "main_checkout_synced"
+    });
+  }
   const dynamicButtonLabel = (() => {
     if (step.id === "plan_executed" && planExecutionPrompted && !planExecutionSubmitted) {
       return "Go to next step";
@@ -712,6 +724,9 @@ function buildCurrentStepAction(stepId, artifacts = {}) {
     if (step.id === "plan_made" && planReworkMode && !artifacts.prompt && hasActiveReworkRequest) {
       return "Get Codex to create revised plan";
     }
+    if (step.id === "main_checkout_synced" && artifacts.prOutcome?.outcome && artifacts.prOutcome.outcome !== "merged") {
+      return "Record no sync needed";
+    }
     return buttonLabel;
   })();
   const dynamicDescription = (() => {
@@ -727,6 +742,9 @@ function buildCurrentStepAction(stepId, artifacts = {}) {
     if (step.id === "plan_made" && planReworkMode && hasActiveReworkRequest) {
       return "Codex writes a revised implementation plan from the user's rework notes for this cycle.";
     }
+    if (step.id === "main_checkout_synced" && artifacts.prOutcome?.outcome && artifacts.prOutcome.outcome !== "merged") {
+      return "The PR was not merged, so JSKIT will record main checkout sync as skipped before cleanup.";
+    }
     return step.description;
   })();
   const dynamicUtilityActions = (() => {
@@ -795,7 +813,8 @@ async function readSessionArtifacts(paths) {
     baseCommit,
     issueMetadataText,
     planExecutionReceipt,
-    prOutcomeText
+    prOutcomeText,
+    mainCheckoutSyncText
   ] = await Promise.all([
     readTrimmedFile(path.join(paths.sessionRoot, "status")),
     readTrimmedFile(path.join(paths.sessionRoot, "current_step")),
@@ -814,7 +833,8 @@ async function readSessionArtifacts(paths) {
     readTrimmedFile(path.join(paths.sessionRoot, "base_commit")),
     readTextIfExists(path.join(paths.sessionRoot, "issue_metadata.json")),
     readTextIfExists(path.join(cycleStepsRoot(paths, activeCycle), "plan_executed")),
-    readTextIfExists(path.join(paths.sessionRoot, "pr_outcome.json"))
+    readTextIfExists(path.join(paths.sessionRoot, "pr_outcome.json")),
+    readTextIfExists(path.join(paths.sessionRoot, "main_checkout_sync.json"))
   ]);
   let issueMetadata = null;
   if (issueMetadataText) {
@@ -842,6 +862,15 @@ async function readSessionArtifacts(paths) {
       prOutcome = null;
     }
   }
+  let mainCheckoutSync = null;
+  if (mainCheckoutSyncText) {
+    try {
+      const parsed = JSON.parse(mainCheckoutSyncText);
+      mainCheckoutSync = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    } catch {
+      mainCheckoutSync = null;
+    }
+  }
   const cycles = await readCycles(paths, activeCycle);
   const checks = await readStructuredChecks(paths);
   const uiChecks = await readStructuredUiChecks(paths);
@@ -858,7 +887,7 @@ async function readSessionArtifacts(paths) {
   const helperMapPath = path.join(appRootForArtifacts, ".jskit", "helper-map.md");
   const currentStep = normalizeStepId(rawCurrentStep);
   let completedSteps = await readCompletedSteps(paths);
-  const worktreeRemovalCompleted = completedSteps.includes("pr_finalized");
+  const worktreeRemovalCompleted = completedSteps.includes("session_finished");
   const worktreeReceiptInvalid = !worktreeReady &&
     completedSteps.includes("worktree_created") &&
     !worktreeRemovalCompleted &&
@@ -919,6 +948,7 @@ async function readSessionArtifacts(paths) {
     nextStep,
     prUrl,
     prOutcome,
+    mainCheckoutSync,
     planExecution: {
       prompted: planExecutionPromptExists,
       promptPath: planExecutionPromptExists ? planExecutionPromptPath : "",
@@ -1001,6 +1031,7 @@ async function buildSessionResponse(paths, {
       helperMapExists: artifacts.helperMapExists === true,
       prUrl: artifacts.prUrl || "",
       prOutcome: cloneContractValue(artifacts.prOutcome || null),
+      mainCheckoutSync: cloneContractValue(artifacts.mainCheckoutSync || null),
       preconditions,
       errors: [
         createError({
@@ -1067,6 +1098,7 @@ async function buildSessionResponse(paths, {
     helperMapExists: artifacts.helperMapExists === true,
     prUrl: artifacts.prUrl || "",
     prOutcome: cloneContractValue(artifacts.prOutcome || null),
+    mainCheckoutSync: cloneContractValue(artifacts.mainCheckoutSync || null),
     preconditions,
     errors,
     archive: responsePaths.archive || (resolvedStatus === SESSION_STATUS.FINISHED ? "completed" : resolvedStatus === SESSION_STATUS.ABANDONED ? "abandoned" : "active"),

package/src/server/sessionRuntime.js

@@ -3,6 +3,7 @@ import {
   mkdir,
   readFile,
   readdir,
+  rm,
   rmdir
 } from "node:fs/promises";
 import path from "node:path";
@@ -13,6 +14,7 @@ import {
   DEEP_UI_CHECK_CODEX_HANDOFF,
   ISSUE_DETAILS_CODEX_HANDOFF,
   PLAN_EXECUTION_CODEX_HANDOFF,
+  PR_MERGE_PREP_CODEX_HANDOFF,
   REVIEW_PASS_LIMIT,
   REVIEW_EXECUTION_CODEX_HANDOFF,
   SESSION_STATUS,
@@ -78,6 +80,7 @@ import {
   assertIssueUrlExists,
   assertAutomatedChecksPassed,
   assertIssueDetailsExists,
+  assertMainCheckoutSyncSatisfied,
   assertPlanTextExists,
   assertPrUrlExists,
   assertReadyJskitApp,
@@ -96,6 +99,9 @@ import {
   HELPER_MAP_MARKDOWN_RELATIVE_PATH
 } from "./helperMapPaths.js";
 
+const SESSION_PROVISION_PACKAGE_SCRIPT = "jskit:provision-session";
+const SESSION_FINALIZATION_GUARD_PACKAGE_SCRIPT = "jskit:finalization-guard";
+
 function invalidSessionIdError(sessionId = "") {
   return createError({
     code: "invalid_session_id",
@@ -355,6 +361,139 @@ async function runLoggedCommand(paths, kind, command, args = [], options = {}) {
   return result;
 }
 
+async function readWorktreePackageJson(worktree) {
+  const source = await readTextIfExists(path.join(worktree, "package.json"));
+  if (!source) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(source);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function packageScriptRunArgs(packageManager, scriptName) {
+  if (packageManager === "pnpm") {
+    return ["pnpm", ["run", scriptName]];
+  }
+  if (packageManager === "yarn") {
+    return ["yarn", ["run", scriptName]];
+  }
+  if (packageManager === "bun") {
+    return ["bun", ["run", scriptName]];
+  }
+  return ["npm", ["run", "--silent", scriptName]];
+}
+
+async function packageScriptCommandForWorktree(worktree, scriptName, {
+  preferredPackageManager = ""
+} = {}) {
+  const packageJson = await readWorktreePackageJson(worktree);
+  const script = packageJson?.scripts?.[scriptName];
+  if (typeof script !== "string" || !normalizeText(script)) {
+    return null;
+  }
+  const packageManager = preferredPackageManager || (await dependencyInstallCommandForWorktree(worktree))[0];
+  const [command, args] = packageScriptRunArgs(packageManager, scriptName);
+  return {
+    args,
+    command
+  };
+}
+
+function sessionPackageScriptEnv(paths, scriptName) {
+  return {
+    JSKIT_SESSION_ID: paths.sessionId,
+    JSKIT_SESSION_PACKAGE_SCRIPT: scriptName,
+    JSKIT_SESSION_ROOT: paths.sessionRoot,
+    JSKIT_TARGET_ROOT: paths.targetRoot,
+    JSKIT_WORKTREE_ROOT: paths.worktree
+  };
+}
+
+function packageScriptRepairCommand(paths, command, args) {
+  return `cd ${paths.worktree} && ${command} ${args.join(" ")}`;
+}
+
+function packageScriptReceiptName(scriptName) {
+  return normalizeText(scriptName).replace(/[^a-zA-Z0-9._-]+/gu, "_");
+}
+
+async function writeSessionHookReceipt(paths, scriptName, message) {
+  await writeTextFile(
+    path.join(paths.sessionRoot, "hooks", packageScriptReceiptName(scriptName)),
+    `${timestampForReceipt()}\n${normalizeText(message) || `${scriptName} completed.`}`
+  );
+}
+
+async function runOptionalSessionPackageScript(paths, {
+  failureCode,
+  failureMessage,
+  kind,
+  preferredPackageManager = "",
+  preconditions = [],
+  scriptName,
+  timeout = 1000 * 60 * 10
+} = {}) {
+  const scriptCommand = await packageScriptCommandForWorktree(paths.worktree, scriptName, {
+    preferredPackageManager
+  });
+  if (!scriptCommand) {
+    return {
+      ok: true,
+      ran: false
+    };
+  }
+  const result = await runLoggedCommand(paths, kind, scriptCommand.command, scriptCommand.args, {
+    cwd: paths.worktree,
+    env: sessionPackageScriptEnv(paths, scriptName),
+    timeout
+  });
+  if (!result.ok) {
+    return {
+      ok: false,
+      response: await failSession(paths, {
+        code: failureCode,
+        message: result.output || failureMessage,
+        preconditions,
+        repairCommand: packageScriptRepairCommand(paths, scriptCommand.command, scriptCommand.args)
+      })
+    };
+  }
+  await writeSessionHookReceipt(paths, scriptName, result.output || `${scriptName} completed.`);
+  return {
+    ok: true,
+    ran: true,
+    result
+  };
+}
+
+async function runSessionFinalizationGuard(paths, preconditions = []) {
+  return runOptionalSessionPackageScript(paths, {
+    failureCode: "session_finalization_guard_failed",
+    failureMessage: `${SESSION_FINALIZATION_GUARD_PACKAGE_SCRIPT} failed in the session worktree.`,
+    kind: "session_finalization_guard",
+    preconditions,
+    scriptName: SESSION_FINALIZATION_GUARD_PACKAGE_SCRIPT
+  });
+}
+
+async function runSessionProvisioningHook(paths, {
+  preferredPackageManager = "",
+  preconditions = []
+} = {}) {
+  return runOptionalSessionPackageScript(paths, {
+    failureCode: "session_provision_failed",
+    failureMessage: `${SESSION_PROVISION_PACKAGE_SCRIPT} failed in the session worktree.`,
+    kind: "session_provision",
+    preferredPackageManager,
+    preconditions,
+    scriptName: SESSION_PROVISION_PACKAGE_SCRIPT
+  });
+}
+
 async function readIssueMetadata(paths) {
   const source = await readTextIfExists(path.join(paths.sessionRoot, "issue_metadata.json"));
   if (!source) {
@@ -820,8 +959,16 @@ async function installDependencies(paths, _options = {}, context = {}) {
       preconditions
     });
   }
+  const provisionResult = await runSessionProvisioningHook(paths, {
+    preferredPackageManager: command,
+    preconditions
+  });
+  if (!provisionResult.ok) {
+    return provisionResult.response;
+  }
+  const installMessage = result.output || `Installed Node dependencies in the session worktree with ${command} ${args.join(" ")}.`;
   return recordDependenciesInstalled(paths, {
-    message: result.output || `Installed Node dependencies in the session worktree with ${command} ${args.join(" ")}.`,
+    message: provisionResult.ran ? `${installMessage}\n${SESSION_PROVISION_PACKAGE_SCRIPT} completed.` : installMessage,
     preconditions
   });
 }
@@ -832,6 +979,7 @@ async function adoptDependenciesInstalled({
   message = ""
 } = {}) {
   return withExistingSession({ targetRoot, sessionId }, async (paths, context = {}) => {
+    const preconditions = context.preconditions || [];
     const artifacts = await readSessionArtifacts(paths);
     if (artifacts.nextStep !== "dependencies_installed") {
       return buildSessionResponse(paths, {
@@ -842,12 +990,21 @@ async function adoptDependenciesInstalled({
             message: `Cannot record dependencies for ${paths.sessionId}; current step is ${artifacts.nextStep || "complete"}.`
           })
         ],
-        preconditions: context.preconditions || []
+        preconditions
       });
     }
+    const provisionResult = await runSessionProvisioningHook(paths, {
+      preconditions
+    });
+    if (!provisionResult.ok) {
+      return provisionResult.response;
+    }
+    const receiptMessage = provisionResult.ran
+      ? `${normalizeText(message) || "Installed Node dependencies in the session worktree."}\n${SESSION_PROVISION_PACKAGE_SCRIPT} completed.`
+      : message;
     return recordDependenciesInstalled(paths, {
-      message,
-      preconditions: context.preconditions || []
+      message: receiptMessage,
+      preconditions
     });
   });
 }
@@ -1282,6 +1439,333 @@ async function inspectSessionDiff({
   });
 }
 
+const FIRST_REWINDABLE_STEP_ID = "dependencies_installed";
+const CYCLE_REWIND_TARGET_STEP_ID = "plan_made";
+const REWIND_CLOSED_STATUSES = Object.freeze([
+  SESSION_STATUS.ABANDONED,
+  SESSION_STATUS.FINISHED
+]);
+
+async function removeSessionPath(paths, ...parts) {
+  await rm(path.join(paths.sessionRoot, ...parts), {
+    force: true,
+    recursive: true
+  });
+}
+
+async function removeSessionRootFile(paths, fileName) {
+  await removeSessionPath(paths, fileName);
+}
+
+async function removePromptArtifact(paths, fileName) {
+  await removeSessionPath(paths, "prompts", fileName);
+}
+
+async function removeGlobalCodexResult(paths, stepId) {
+  await removeSessionPath(paths, "codex_results", `${stepId}.md`);
+}
+
+async function removeGithubCommentPurpose(paths, purpose) {
+  const comments = await readGithubComments(paths);
+  if (!Object.hasOwn(comments, purpose)) {
+    return;
+  }
+  delete comments[purpose];
+  if (Object.keys(comments).length === 0) {
+    await removeSessionRootFile(paths, "github_comments.json");
+    return;
+  }
+  await writeGithubComments(paths, comments);
+}
+
+async function removeIssueDetailsMetadata(paths) {
+  const metadata = await readIssueMetadata(paths);
+  if (Object.keys(metadata).length === 0) {
+    return;
+  }
+  delete metadata.issueCategory;
+  delete metadata.issueDetailsPath;
+  delete metadata.uiImpact;
+  if (Object.keys(metadata).length === 0) {
+    await removeSessionRootFile(paths, "issue_metadata.json");
+    return;
+  }
+  await writeTextFile(path.join(paths.sessionRoot, "issue_metadata.json"), `${JSON.stringify(metadata, null, 2)}\n`);
+}
+
+async function removeCycleDirectories(paths) {
+  for (const rootName of ["steps", "cycles"]) {
+    const root = path.join(paths.sessionRoot, rootName);
+    let entries = [];
+    try {
+      entries = await readdir(root, { withFileTypes: true });
+    } catch {
+      entries = [];
+    }
+    await Promise.all(entries
+      .filter((entry) => entry.isDirectory() && /^cycle_\d+$/u.test(entry.name))
+      .map((entry) => rm(path.join(root, entry.name), {
+        force: true,
+        recursive: true
+      })));
+  }
+}
+
+async function removeCyclePromptArtifacts(paths) {
+  const promptsRoot = path.join(paths.sessionRoot, "prompts");
+  let entries = [];
+  try {
+    entries = await readdir(promptsRoot, { withFileTypes: true });
+  } catch {
+    entries = [];
+  }
+  const cyclePromptPattern = /^cycle_\d+_(?:plan_request|plan_execution)\.md$/u;
+  const cyclePromptFiles = entries
+    .filter((entry) => entry.isFile() && cyclePromptPattern.test(entry.name))
+    .map((entry) => entry.name);
+  await Promise.all([
+    ...cyclePromptFiles.map((fileName) => removePromptArtifact(paths, fileName)),
+    removePromptArtifact(paths, "automated_checks_run.md"),
+    removePromptArtifact(paths, "deep_ui_check_run.md"),
+    removePromptArtifact(paths, "review.md"),
+    removePromptArtifact(paths, "user_check.md")
+  ]);
+}
+
+async function cancelAllCycleState(paths) {
+  await Promise.all([
+    removeCycleDirectories(paths),
+    removeCyclePromptArtifacts(paths),
+    removeSessionPath(paths, "checks"),
+    removeSessionPath(paths, "ui_checks"),
+    removeSessionPath(paths, "review_passes")
+  ]);
+  await writeActiveCycle(paths, "001");
+}
+
+const STEP_CANCELERS = Object.freeze({
+  dependencies_installed: async () => {},
+  issue_prompt_rendered: async (paths) => {
+    await removePromptArtifact(paths, "issue_draft.md");
+  },
+  issue_drafted: async (paths) => {
+    await Promise.all([
+      removeSessionRootFile(paths, "issue.md"),
+      removeSessionRootFile(paths, "issue_title")
+    ]);
+  },
+  issue_created: async (paths) => {
+    await Promise.all([
+      removeSessionRootFile(paths, "issue_url"),
+      removeSessionRootFile(paths, "issue_metadata.json")
+    ]);
+  },
+  issue_details_gathered: async (paths) => {
+    await Promise.all([
+      removePromptArtifact(paths, "issue_details.md"),
+      removeSessionRootFile(paths, "issue_details.md"),
+      removeGithubCommentPurpose(paths, "issue_details"),
+      removeIssueDetailsMetadata(paths)
+    ]);
+  },
+  plan_made: cancelAllCycleState,
+  plan_executed: cancelAllCycleState,
+  deep_ui_check_run: cancelAllCycleState,
+  review_prompt_rendered: cancelAllCycleState,
+  review_changes_accepted: cancelAllCycleState,
+  automated_checks_run: cancelAllCycleState,
+  user_check_completed: cancelAllCycleState,
+  changes_committed: async (paths) => {
+    await removeSessionRootFile(paths, "changes_committed.json");
+  },
+  blueprint_updated: async (paths) => {
+    await Promise.all([
+      removePromptArtifact(paths, "update_blueprint.md"),
+      removeGlobalCodexResult(paths, "blueprint_updated")
+    ]);
+  },
+  final_report_created: async (paths) => {
+    await Promise.all([
+      removeSessionRootFile(paths, "final_report.md"),
+      removeGithubCommentPurpose(paths, "final_report")
+    ]);
+  },
+  pr_created: async (paths) => {
+    await Promise.all([
+      removePromptArtifact(paths, "pr_create_failure.md"),
+      removeSessionRootFile(paths, "pr_body.md"),
+      removeSessionRootFile(paths, "pr_url")
+    ]);
+  },
+  pr_merge_prepared: async (paths) => {
+    await removePromptArtifact(paths, "prepare_pr_merge.md");
+  },
+  pr_finalized: async (paths) => {
+    await Promise.all([
+      removePromptArtifact(paths, "pr_merge_failure.md"),
+      removeSessionRootFile(paths, "pr_base_branch"),
+      removeSessionRootFile(paths, "pr_merge_completed"),
+      removeSessionRootFile(paths, "pr_outcome.json")
+    ]);
+  },
+  main_checkout_synced: async (paths) => {
+    await Promise.all([
+      removeSessionRootFile(paths, "local_base_updated"),
+      removeSessionRootFile(paths, "main_checkout_sync.json")
+    ]);
+  },
+  session_finished: async (paths) => {
+    await Promise.all([
+      removeSessionRootFile(paths, "final_comment.md")
+    ]);
+  }
+});
+
+function targetRequiresCycleReset(stepId) {
+  const targetIndex = STEP_IDS.indexOf(stepId);
+  const planIndex = STEP_IDS.indexOf(CYCLE_REWIND_TARGET_STEP_ID);
+  return targetIndex >= 0 && targetIndex <= planIndex;
+}
+
+function targetIsAllowedRewindStep(stepId) {
+  if (!STEP_IDS.includes(stepId)) {
+    return false;
+  }
+  if (stepId === "session_created" || stepId === "worktree_created") {
+    return false;
+  }
+  if (CYCLE_STEP_IDS.includes(stepId)) {
+    return stepId === CYCLE_REWIND_TARGET_STEP_ID;
+  }
+  return STEP_IDS.indexOf(stepId) >= STEP_IDS.indexOf(FIRST_REWINDABLE_STEP_ID);
+}
+
+function deletedStepIdsForRewindTarget(stepId) {
+  const targetIndex = STEP_IDS.indexOf(stepId);
+  return targetIndex < 0 ? [] : STEP_IDS.slice(targetIndex);
+}
+
+async function removeReceiptsForDeletedSteps(paths, deletedStepIds) {
+  await Promise.all(deletedStepIds
+    .filter((stepId) => !CYCLE_STEP_IDS.includes(stepId))
+    .map((stepId) => removeSessionPath(paths, "steps", stepId)));
+}
+
+async function cancelDeletedStepArtifacts(paths, deletedStepIds, {
+  cycleReset = false
+} = {}) {
+  const cancelerIds = cycleReset
+    ? deletedStepIds.filter((stepId) => !CYCLE_STEP_IDS.includes(stepId)).concat(CYCLE_REWIND_TARGET_STEP_ID)
+    : deletedStepIds;
+  const calledCycleCancel = new Set();
+  for (const stepId of cancelerIds) {
+    const canceler = STEP_CANCELERS[stepId];
+    if (typeof canceler !== "function") {
+      continue;
+    }
+    if (CYCLE_STEP_IDS.includes(stepId)) {
+      if (calledCycleCancel.has(CYCLE_REWIND_TARGET_STEP_ID)) {
+        continue;
+      }
+      calledCycleCancel.add(CYCLE_REWIND_TARGET_STEP_ID);
+    }
+    await canceler(paths);
+  }
+}
+
+async function rewindSession({
+  targetRoot = process.cwd(),
+  sessionId,
+  stepId
+} = {}) {
+  return withExistingSession({ targetRoot, sessionId }, async (paths) => {
+    const artifacts = await readSessionArtifacts(paths);
+    const normalizedStepId = normalizeText(stepId);
+    const currentStatus = artifacts.status || SESSION_STATUS.PENDING;
+
+    if (paths.archive && paths.archive !== "active") {
+      return buildSessionResponse(paths, {
+        ok: false,
+        errors: [
+          createError({
+            code: "session_archived_read_only",
+            message: `Session ${paths.sessionId} is archived and cannot be rewound.`
+          })
+        ],
+        status: currentStatus
+      });
+    }
+
+    if (REWIND_CLOSED_STATUSES.includes(currentStatus)) {
+      return buildSessionResponse(paths, {
+        ok: false,
+        errors: [
+          createError({
+            code: "session_closed_read_only",
+            message: `Session ${paths.sessionId} is ${currentStatus} and cannot be rewound.`
+          })
+        ],
+        status: currentStatus
+      });
+    }
+
+    if (artifacts.workflowVersion !== SESSION_WORKFLOW_VERSION) {
+      return buildSessionResponse(paths, {
+        ok: false,
+        errors: [
+          createError({
+            code: "unsupported_workflow_version",
+            message: `Session ${paths.sessionId} uses workflow version ${artifacts.workflowVersion || "unknown"}, but this JSKIT runtime expects ${SESSION_WORKFLOW_VERSION}.`
+          })
+        ],
+        status: SESSION_STATUS.BLOCKED
+      });
+    }
+
+    if (!targetIsAllowedRewindStep(normalizedStepId)) {
+      const cycleHint = CYCLE_STEP_IDS.includes(normalizedStepId)
+        ? " Only Plan made can be used as a cycle rewind target; it resets all cycle/rework state."
+        : "";
+      return buildSessionResponse(paths, {
+        ok: false,
+        errors: [
+          createError({
+            code: "rewind_step_not_allowed",
+            message: `Cannot rewind session ${paths.sessionId} to ${normalizedStepId || "(missing)"}.${cycleHint}`
+          })
+        ],
+        status: currentStatus
+      });
+    }
+
+    if (!artifacts.completedSteps.includes(normalizedStepId)) {
+      return buildSessionResponse(paths, {
+        ok: false,
+        errors: [
+          createError({
+            code: "rewind_step_not_completed",
+            message: `Cannot rewind session ${paths.sessionId} to ${normalizedStepId} because that step is not completed.`
+          })
+        ],
+        status: currentStatus
+      });
+    }
+
+    const deletedStepIds = deletedStepIdsForRewindTarget(normalizedStepId);
+    const cycleReset = targetRequiresCycleReset(normalizedStepId);
+    await removeReceiptsForDeletedSteps(paths, deletedStepIds);
+    await cancelDeletedStepArtifacts(paths, deletedStepIds, { cycleReset });
+    if (cycleReset) {
+      await writeActiveCycle(paths, "001");
+    }
+    await markCurrentStep(paths, normalizedStepId);
+    await markStatus(paths, SESSION_STATUS.PENDING);
+    return buildSessionResponse(paths, {
+      status: SESSION_STATUS.PENDING
+    });
+  });
+}
+
 async function commitWorktree(paths, {
   message,
   allowNoChanges = false
@@ -2118,6 +2602,17 @@ async function writePrOutcome(paths, outcome) {
   }, null, 2)}\n`);
 }
 
+function mainCheckoutSyncPath(paths) {
+  return path.join(paths.sessionRoot, "main_checkout_sync.json");
+}
+
+async function writeMainCheckoutSync(paths, payload = {}) {
+  await writeTextFile(mainCheckoutSyncPath(paths), `${JSON.stringify({
+    recordedAt: timestampForReceipt(),
+    ...payload
+  }, null, 2)}\n`);
+}
+
 async function assertTargetRootCanUpdateBase(paths, branch) {
   const cleanFailure = await assertTargetRootCleanForBaseUpdate(paths);
   if (cleanFailure) {
@@ -2136,50 +2631,6 @@ async function assertTargetRootCanUpdateBase(paths, branch) {
   return null;
 }
 
-async function assertTargetBaseCanFastForward(paths, branch) {
-  const branchFailure = await assertTargetRootCanUpdateBase(paths, branch);
-  if (branchFailure) {
-    return branchFailure;
-  }
-
-  const fetchResult = await runLoggedCommand(paths, "git_fetch_origin", "git", ["fetch", "origin"], {
-    cwd: paths.targetRoot,
-    timeout: 1000 * 60 * 5
-  });
-  if (!fetchResult.ok) {
-    return failSession(paths, {
-      code: "target_fetch_failed",
-      message: fetchResult.output || `Failed to fetch origin before checking local ${branch}.`,
-      repairCommand: `git -C ${paths.targetRoot} fetch origin`
-    });
-  }
-
-  const remoteBranch = `origin/${branch}`;
-  const remoteExists = await runGit(paths.targetRoot, ["rev-parse", "--verify", remoteBranch], {
-    timeout: 15000
-  });
-  if (!remoteExists.ok) {
-    return failSession(paths, {
-      code: "target_remote_branch_missing",
-      message: `Remote base branch ${remoteBranch} does not exist; JSKIT cannot safely update local ${branch} after merge.`,
-      repairCommand: `git -C ${paths.targetRoot} fetch origin`
-    });
-  }
-
-  const ancestor = await runGit(paths.targetRoot, ["merge-base", "--is-ancestor", branch, remoteBranch], {
-    timeout: 15000
-  });
-  if (!ancestor.ok) {
-    return failSession(paths, {
-      code: "target_branch_not_fast_forwardable",
-      message: `Local ${branch} is not an ancestor of ${remoteBranch}; JSKIT will not merge the PR while the local base branch has diverged.`,
-      repairCommand: `git -C ${paths.targetRoot} pull --ff-only origin ${branch}`
-    });
-  }
-
-  return null;
-}
-
 async function updateLocalBaseBranch(paths, baseBranch = "") {
   const branch = normalizeText(baseBranch) || await currentTargetBranch(paths.targetRoot);
   if (!branch) {
@@ -2222,6 +2673,54 @@ async function updateLocalBaseBranch(paths, baseBranch = "") {
   return null;
 }
 
+async function syncMainCheckout(paths, options = {}, context = {}) {
+  const prOutcome = parseJsonObject(await readTextIfExists(path.join(paths.sessionRoot, "pr_outcome.json")));
+  const preconditions = context.preconditions || [];
+  if (!prOutcome?.outcome) {
+    return failSession(paths, {
+      code: "pr_outcome_missing",
+      message: "Cannot sync the main checkout before PR finalization records an outcome.",
+      preconditions,
+      repairCommand: `jskit session ${paths.sessionId} step`
+    });
+  }
+
+  const skipRequested = options.skipMainSync === true ||
+    normalizeText(options["skip-main-sync"]).toLowerCase() === "true";
+  const skipReason = normalizeText(options.skipReason || options["skip-reason"]) ||
+    "User skipped main checkout sync.";
+  if (skipRequested || prOutcome.outcome !== "merged") {
+    const reason = prOutcome.outcome === "merged"
+      ? skipReason
+      : `PR outcome is ${prOutcome.outcome}; no main checkout sync is required.`;
+    await writeMainCheckoutSync(paths, {
+      branch: prOutcome.baseBranch || "",
+      outcome: prOutcome.outcome,
+      reason,
+      status: "skipped"
+    });
+    await writeReceipt(paths, "main_checkout_synced", `Main checkout sync skipped: ${reason}`);
+    await markStatus(paths, SESSION_STATUS.RUNNING);
+    return buildSessionResponse(paths);
+  }
+
+  const baseBranch = prOutcome.baseBranch || await readTrimmedFile(path.join(paths.sessionRoot, "pr_base_branch"));
+  const syncFailure = await updateLocalBaseBranch(paths, baseBranch);
+  if (syncFailure) {
+    return syncFailure;
+  }
+
+  const branch = normalizeText(baseBranch) || await currentTargetBranch(paths.targetRoot);
+  await writeMainCheckoutSync(paths, {
+    branch,
+    outcome: prOutcome.outcome,
+    status: "synced"
+  });
+  await writeReceipt(paths, "main_checkout_synced", `Fast-forwarded target checkout branch ${branch}.`);
+  await markStatus(paths, SESSION_STATUS.RUNNING);
+  return buildSessionResponse(paths);
+}
+
 async function updateHelperMapBeforePr(paths) {
   let helperMapPayload;
   try {
@@ -2380,14 +2879,7 @@ async function createPr(paths) {
 }
 
 async function closePrWithoutMerge(paths, prUrl, options = {}) {
-  const reason = normalizeText(options.closeReason || options["close-reason"]);
-  if (!reason) {
-    return failSession(paths, {
-      code: "close_without_merge_reason_required",
-      message: "Finishing without merging requires --close-reason.",
-      repairCommand: `jskit session ${paths.sessionId} step --close-without-merge --close-reason "<reason>"`
-    });
-  }
+  const reason = normalizeText(options.closeReason || options["close-reason"]) || "User skipped merge in JSKIT Studio.";
   const prState = await readPrState(paths, prUrl);
   if (!prState.ok) {
     return failSession(paths, {
@@ -2423,10 +2915,6 @@ async function closePrWithoutMerge(paths, prUrl, options = {}) {
       timeout: 1000 * 60
     });
   }
-  const removeFailure = await removeSessionWorktree(paths);
-  if (removeFailure) {
-    return removeFailure;
-  }
   await writePrOutcome(paths, {
     issueUrl,
     outcome: "closed_without_merge",
@@ -2434,16 +2922,69 @@ async function closePrWithoutMerge(paths, prUrl, options = {}) {
     prState: prState.state,
     reason
   });
-  await writeReceipt(paths, "pr_finalized", `Finished without merging PR ${prUrl}; PR left open and worktree removed ${paths.worktree}. Reason: ${reason}`);
+  await writeReceipt(paths, "pr_finalized", `Finished without merging PR ${prUrl}; PR left open. Reason: ${reason}`);
   await markStatus(paths, SESSION_STATUS.RUNNING);
   return buildSessionResponse(paths);
 }
 
-async function finalizePr(paths, options = {}) {
+async function preparePrMerge(paths, options = {}, context = {}) {
+  const preconditions = context.preconditions || [];
+  const prepareMerge = options.prepareMerge === true ||
+    normalizeText(options["prepare-merge"]).toLowerCase() === "true";
+  const continueToMerge = options.continueToMerge === true ||
+    normalizeText(options["continue-to-merge"]).toLowerCase() === "true";
+
+  if (prepareMerge) {
+    const prUrl = await readTrimmedFile(path.join(paths.sessionRoot, "pr_url"));
+    const baseBranch = await readTrimmedFile(path.join(paths.sessionRoot, "pr_base_branch")) ||
+      await readTrimmedFile(path.join(paths.sessionRoot, "base_branch")) ||
+      await currentTargetBranch(paths.targetRoot);
+    const prompt = await renderPrompt(paths, "prepare_pr_merge.md", {
+      base_branch: baseBranch,
+      final_report_file: path.join(paths.sessionRoot, "final_report.md"),
+      issue_url: await readTrimmedFile(path.join(paths.sessionRoot, "issue_url")),
+      pr_url: prUrl,
+      target_root: paths.targetRoot
+    });
+    await writePromptArtifact(paths, "prepare_pr_merge.md", prompt);
+    await markStatus(paths, SESSION_STATUS.WAITING_FOR_USER);
+    return buildSessionResponse(paths, {
+      codex: PR_MERGE_PREP_CODEX_HANDOFF,
+      ok: true,
+      preconditions,
+      prompt,
+      status: SESSION_STATUS.WAITING_FOR_USER
+    });
+  }
+
+  if (!continueToMerge) {
+    return failSession(paths, {
+      code: "pr_merge_prepare_decision_required",
+      message: "Choose whether to ask Codex to prepare the PR for merge or continue to the merge decision.",
+      repairCommand: `jskit session ${paths.sessionId} step --continue-to-merge true`,
+      preconditions
+    });
+  }
+
+  await writeReceipt(paths, "pr_merge_prepared", "User continued from PR merge preparation to the merge decision.");
+  await markStatus(paths, SESSION_STATUS.RUNNING);
+  return buildSessionResponse(paths, {
+    preconditions
+  });
+}
+
+async function finalizePr(paths, options = {}, context = {}) {
+  const preconditions = context.preconditions || [];
   const prUrl = await readTrimmedFile(path.join(paths.sessionRoot, "pr_url"));
   const closeWithoutMerge = options.closeWithoutMerge === true ||
-    normalizeText(options["close-without-merge"]).toLowerCase() === "true";
+    normalizeText(options["close-without-merge"]).toLowerCase() === "true" ||
+    options.skipMerge === true ||
+    normalizeText(options["skip-merge"]).toLowerCase() === "true";
   if (closeWithoutMerge) {
+    const guardResult = await runSessionFinalizationGuard(paths, preconditions);
+    if (!guardResult.ok) {
+      return guardResult.response;
+    }
     return closePrWithoutMerge(paths, prUrl, options);
   }
   const mergePr = options.mergePr === true ||
@@ -2451,10 +2992,15 @@ async function finalizePr(paths, options = {}) {
   if (!mergePr) {
     return failSession(paths, {
       code: "pr_finalize_decision_required",
-      message: "Choose whether to merge the PR or finish without merging.",
-      repairCommand: `jskit session ${paths.sessionId} step --merge-pr true`
+      message: "Choose whether to merge the PR or skip merge.",
+      repairCommand: `jskit session ${paths.sessionId} step --merge-pr true`,
+      preconditions
     });
   }
+  const guardResult = await runSessionFinalizationGuard(paths, preconditions);
+  if (!guardResult.ok) {
+    return guardResult.response;
+  }
   const mergeMarkerPath = path.join(paths.sessionRoot, "pr_merge_completed");
   const baseBranchPath = path.join(paths.sessionRoot, "pr_base_branch");
   const mergeAlreadyCompleted = await readTrimmedFile(mergeMarkerPath);
@@ -2465,10 +3011,6 @@ async function finalizePr(paths, options = {}) {
     if (baseBranch) {
       await writeTextFile(baseBranchPath, `${baseBranch}\n`);
     }
-    const baseFailure = await assertTargetBaseCanFastForward(paths, baseBranch);
-    if (baseFailure) {
-      return baseFailure;
-    }
     let prMerged = prStateIsMerged(existingPrState);
     let mergeResult = null;
     if (!prMerged) {
@@ -2491,6 +3033,7 @@ async function finalizePr(paths, options = {}) {
         code: "pr_merge_failed",
         message: mergeResult?.output || existingPrState.output || "Failed to merge PR.",
         repairCommand: `gh pr merge ${prUrl} --merge --delete-branch`,
+        preconditions,
         prompt
       });
     }
@@ -2509,15 +3052,7 @@ async function finalizePr(paths, options = {}) {
     });
     await writeTextFile(mergeMarkerPath, `${prUrl}\n`);
   }
-  const updateFailure = await updateLocalBaseBranch(paths, baseBranch);
-  if (updateFailure) {
-    return updateFailure;
-  }
-  const removeFailure = await removeSessionWorktree(paths);
-  if (removeFailure) {
-    return removeFailure;
-  }
-  await writeReceipt(paths, "pr_finalized", `Merged PR ${prUrl}, updated local ${baseBranch || "base branch"}, and removed worktree ${paths.worktree}.`);
+  await writeReceipt(paths, "pr_finalized", `Merged PR ${prUrl}.`);
   await markStatus(paths, SESSION_STATUS.RUNNING);
   return buildSessionResponse(paths);
 }
@@ -2527,6 +3062,10 @@ async function finishSession(paths) {
   const issueUrl = await readTrimmedFile(path.join(paths.sessionRoot, "issue_url"));
   const codexThreadId = await readTrimmedFile(path.join(paths.sessionRoot, "codex_thread_id"));
   const prOutcome = parseJsonObject(await readTextIfExists(path.join(paths.sessionRoot, "pr_outcome.json")));
+  const removeFailure = await removeSessionWorktree(paths);
+  if (removeFailure) {
+    return removeFailure;
+  }
   const prompt = await renderPrompt(paths, "final_comment.md", {
     codex_thread_id: codexThreadId,
     issue_url: issueUrl,
@@ -2543,7 +3082,7 @@ async function finishSession(paths) {
       timeout: 1000 * 60
     });
   }
-  await writeReceipt(paths, "session_finished", `Finished session ${paths.sessionId} with PR outcome ${prOutcome?.outcome || "unknown"}.`);
+  await writeReceipt(paths, "session_finished", `Removed worktree ${paths.worktree} and finished session ${paths.sessionId} with PR outcome ${prOutcome?.outcome || "unknown"}.`);
   await markStatus(paths, SESSION_STATUS.FINISHED);
   await markCurrentStep(paths, "");
   const archivedPaths = await archiveSession(paths, "completed");
@@ -2577,7 +3116,9 @@ const STEP_RUNNERS = Object.freeze({
   blueprint_updated: updateBlueprint,
   final_report_created: createFinalReport,
   pr_created: createPr,
+  pr_merge_prepared: preparePrMerge,
   pr_finalized: finalizePr,
+  main_checkout_synced: syncMainCheckout,
   session_finished: finishSession
 });
 
@@ -2598,6 +3139,7 @@ const PRECONDITION_RUNNERS = Object.freeze({
   issue_url_exists: assertIssueUrlExists,
   automated_checks_passed: assertAutomatedChecksPassed,
   issue_details_exists: assertIssueDetailsExists,
+  main_checkout_sync_satisfied: assertMainCheckoutSyncSatisfied,
   plan_text_exists: assertPlanTextExists,
   pr_url_exists: assertPrUrlExists,
   ready_jskit_app: assertReadyJskitApp,
@@ -2772,6 +3314,7 @@ export {
   listSessions,
   renderTemplate,
   recordDependenciesInstalled,
+  rewindSession,
   resolveSessionPaths,
   runSessionStep
 };