@jskit-ai/jskit-cli 0.2.82 → 0.2.84

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.82",
+  "version": "0.2.84",
   "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.81",
-    "@jskit-ai/kernel": "0.1.73",
-    "@jskit-ai/shell-web": "0.1.72",
+    "@jskit-ai/jskit-catalog": "0.1.83",
+    "@jskit-ai/kernel": "0.1.75",
+    "@jskit-ai/shell-web": "0.1.74",
     "@vue/compiler-sfc": "^3.5.29",
     "ts-morph": "^28.0.0"
   },

package/src/server/commandHandlers/session.js

@@ -280,9 +280,25 @@ async function resolveStepInputs({
     return closeReason;
   }
 
+  const codexResult = await resolveTextInput({
+    codePrefix: "codex_result",
+    fileOption: "codex-result-file",
+    inlineOptions,
+    io,
+    repairCommand: `jskit session ${sessionId} step --codex-result -`,
+    cwd,
+    sessionId,
+    stdinOption: "-",
+    textOption: "codex-result"
+  });
+  if (codexResult.ok === false) {
+    return codexResult;
+  }
+
   return {
     agentDecisions: agentDecisions.value,
     closeReason: closeReason.value,
+    codexResult: codexResult.value,
     issue: issue.value,
     issueTitle: issueTitle.value,
     ok: true,
@@ -365,7 +381,8 @@ function createSessionCommands() {
                 reworkNotes: stepInputs.reworkNotes,
                 skipReason: stepInputs.skipReason,
                 agentDecisions: stepInputs.agentDecisions,
-                closeReason: stepInputs.closeReason
+                closeReason: stepInputs.closeReason,
+                codexResult: stepInputs.codexResult
               }
             });
       } else if (second === "abandon") {

package/src/server/core/commandCatalog.js

@@ -226,6 +226,7 @@ const COMMAND_DESCRIPTORS = Object.freeze({
       "Use --issue-title when the approved issue title is separate from the body.",
       "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 --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.",
@@ -245,6 +246,7 @@ const COMMAND_DESCRIPTORS = Object.freeze({
           "jskit session 2026-05-11_21-42-08 step --issue-title \"Fix customer filters\" --issue -",
           "jskit session 2026-05-11_21-42-08 step --issue-details -",
           "jskit session 2026-05-11_21-42-08 step --plan -",
+          "jskit session 2026-05-11_21-42-08 step --codex-result -",
           "jskit session 2026-05-11_21-42-08 step --agent-decisions -",
           "jskit session 2026-05-11_21-42-08 step --review-findings-remaining true --review-findings \"A helper duplication fix needs another pass\"",
           "jskit session 2026-05-11_21-42-08 step --review-findings-remaining false",
@@ -258,7 +260,7 @@ const COMMAND_DESCRIPTORS = Object.freeze({
       })
     ]),
     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>] [--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|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]",
     showHelpOnBareInvocation: false,
     handlerName: "commandSession",
     allowedFlagKeys: Object.freeze(["json", "abandoned", "completed", "all"]),

package/src/server/sessionRuntime/constants.js

@@ -138,24 +138,100 @@ const USER_CHECK_INPUT = Object.freeze({
   required: true,
   type: "choice"
 });
-function codexHandoff(expectedOutput, {
+
+const JSKIT_STEP_RESULT_CONTRACT = Object.freeze({
+  completionBehavior: "auto_advance",
+  kind: "completion_marker",
+  marker: "jskit_step_result",
+  missingMarkerBehavior: "resend",
+  required: true,
+  stepField: "step"
+});
+const DESLOP_RESULT_CONTRACT = Object.freeze({
+  autoResolvePriorities: Object.freeze(["high", "medium"]),
+  completionBehavior: "deslop_loop",
+  kind: "deslop_result",
+  marker: "deslop_result",
+  missingMarkerBehavior: "resend",
+  required: true,
+  resolvePrompt: Object.freeze({
+    findingsPlaceholder: "{{findings}}",
+    marker: "resolve_deslop_findings",
+    templateFile: "resolve_deslop_findings.md"
+  })
+});
+
+function fieldResponseContract(outputDefinitions) {
+  const fields = outputDefinitions
+    .filter((output) => output?.field && output?.extract)
+    .map((output) => Object.freeze({
+      extract: output.extract,
+      field: output.field,
+      formatHint: output.formatHint || "",
+      label: output.label || output.field,
+      manualEntry: true,
+      ...(output.multiline === true ? { multiline: true } : {}),
+      ...(Array.isArray(output.options) ? { options: Object.freeze(output.options.map((option) => Object.freeze({ ...option }))) } : {}),
+      required: output.required !== false
+    }));
+  return Object.freeze({
+    fields: Object.freeze(fields),
+    kind: "fields",
+    missingMarkerBehavior: "manual_or_resend",
+    required: fields.some((field) => field.required)
+  });
+}
+
+function codexHandoff(outputDefinition, {
   autoInject = false,
-  promptActionLabel = ""
+  promptActionLabel = "",
+  promptIntroText = "",
+  promptWaitingText = "",
+  responseContract = undefined
 } = {}) {
-  const expectedOutputs = Object.freeze(Array.isArray(expectedOutput) ? [...expectedOutput] : [expectedOutput]);
+  const outputDefinitions = Object.freeze(Array.isArray(outputDefinition) ? [...outputDefinition] : [outputDefinition]);
+  const resolvedResponseContract = responseContract === undefined
+    ? fieldResponseContract(outputDefinitions)
+    : responseContract;
   return Object.freeze({
     ...(autoInject ? { autoInject: true } : {}),
-    expectedOutput: expectedOutputs[expectedOutputs.length - 1] || null,
-    expectedOutputs,
     mode: "inject_prompt",
     promptField: "prompt",
-    ...(promptActionLabel ? { promptActionLabel } : {})
+    ...(promptActionLabel ? { promptActionLabel } : {}),
+    ...(promptIntroText ? { promptIntroText } : {}),
+    ...(promptWaitingText ? { promptWaitingText } : {}),
+    ...(resolvedResponseContract ? { responseContract: resolvedResponseContract } : {})
   });
 }
 
+function stepAutomationFor({
+  codex = undefined,
+  id,
+  kind,
+  requiresExplicitRun = false
+}) {
+  if (requiresExplicitRun) {
+    return Object.freeze({ mode: "manual" });
+  }
+  if (id === "dependencies_installed") {
+    return Object.freeze({ mode: "terminal" });
+  }
+  if (kind === "automatic") {
+    return Object.freeze({ mode: "immediate" });
+  }
+  if (kind === "codex_prompt" && codex?.autoInject === true) {
+    return Object.freeze({ mode: "codex_prompt" });
+  }
+  if (kind === "codex_output" && codex?.autoInject === true) {
+    return Object.freeze({ mode: "codex_output_prompt" });
+  }
+  return Object.freeze({ mode: "manual" });
+}
+
 const PLAN_EXECUTION_CODEX_HANDOFF = codexHandoff([], {
   autoInject: true,
-  promptActionLabel: "Get Codex to execute plan"
+  promptActionLabel: "Get Codex to execute plan",
+  responseContract: JSKIT_STEP_RESULT_CONTRACT
 });
 const ISSUE_DETAILS_CODEX_HANDOFF = codexHandoff([
   ISSUE_CATEGORY_OUTPUT,
@@ -163,23 +239,29 @@ const ISSUE_DETAILS_CODEX_HANDOFF = codexHandoff([
   ISSUE_DETAILS_OUTPUT
 ], {
   autoInject: true,
-  promptActionLabel: "Start details conversation"
+  promptActionLabel: "Start details conversation",
+  promptIntroText: "Codex will gather issue details and classify the issue.",
+  promptWaitingText: "Please respond and finalise things with Codex"
 });
 const REVIEW_EXECUTION_CODEX_HANDOFF = codexHandoff([], {
   autoInject: true,
-  promptActionLabel: "Run deslop"
+  promptActionLabel: "Run deslop",
+  responseContract: DESLOP_RESULT_CONTRACT
 });
 const DEEP_UI_CHECK_CODEX_HANDOFF = codexHandoff([], {
   autoInject: true,
-  promptActionLabel: "Run Deep UI check"
+  promptActionLabel: "Run Deep UI check",
+  responseContract: JSKIT_STEP_RESULT_CONTRACT
 });
 const AUTOMATED_CHECK_REPAIR_CODEX_HANDOFF = codexHandoff([], {
   autoInject: true,
-  promptActionLabel: "Run automated checks"
+  promptActionLabel: "Run automated checks",
+  responseContract: JSKIT_STEP_RESULT_CONTRACT
 });
 const BLUEPRINT_CODEX_HANDOFF = codexHandoff([], {
   autoInject: true,
-  promptActionLabel: "Update blueprint"
+  promptActionLabel: "Update blueprint",
+  responseContract: JSKIT_STEP_RESULT_CONTRACT
 });
 
 function defineStep({
@@ -193,11 +275,20 @@ function defineStep({
   nextCommandTemplate = DEFAULT_NEXT_COMMAND_TEMPLATE,
   preconditions = [],
   requiresExplicitRun = false,
+  submitOptions = {},
+  automation = undefined,
   utilityActions = [],
   displayGroupId = "",
   displayGroupLabel = ""
 }) {
+  const resolvedAutomation = automation || stepAutomationFor({
+    codex,
+    id,
+    kind,
+    requiresExplicitRun
+  });
   return Object.freeze({
+    automation: Object.freeze({ ...resolvedAutomation }),
     buttonLabel,
     codex,
     description,
@@ -210,6 +301,7 @@ function defineStep({
     nextCommandTemplate,
     preconditions: Object.freeze([...preconditions]),
     requiresExplicitRun,
+    submitOptions: Object.freeze({ ...submitOptions }),
     utilityActions: Object.freeze([...utilityActions])
   });
 }
@@ -259,7 +351,8 @@ const STEP_DEFINITIONS = Object.freeze([
       ISSUE_TEXT_OUTPUT
     ], {
       autoInject: true,
-      promptActionLabel: "Get Codex to create issue text"
+      promptActionLabel: "Get Codex to create issue text",
+      promptIntroText: "Codex will create a comprehensive issue."
     }),
     description: "Codex drafts the issue title and body; user reviews or edits them; JSKIT saves the approved draft.",
     id: "issue_drafted",
@@ -294,7 +387,8 @@ const STEP_DEFINITIONS = Object.freeze([
     buttonLabel: "Save plan",
     codex: codexHandoff(PLAN_OUTPUT, {
       autoInject: true,
-      promptActionLabel: "Get Codex to create plan"
+      promptActionLabel: "Get Codex to create plan",
+      promptIntroText: "Codex will create an implementation plan based on the issue."
     }),
     description: "Codex writes an implementation plan for the active cycle; cycle 001 plans from the issue, later cycles plan from user rework notes.",
     id: "plan_made",
@@ -342,12 +436,15 @@ const STEP_DEFINITIONS = Object.freeze([
     kind: "user_check",
     label: "Review/deslop",
     nextCommandTemplate: `${JSKIT_CLI_SHELL_COMMAND} session {{session_id}} step --review-findings-remaining false`,
-    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "deep_ui_check_satisfied"]
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "deep_ui_check_satisfied"],
+    submitOptions: Object.freeze({
+      reviewFindingsRemaining: false
+    })
   }),
   defineStep({
     buttonLabel: "Run automated checks",
     codex: AUTOMATED_CHECK_REPAIR_CODEX_HANDOFF,
-    description: "JSKIT asks Codex to run automated checks in the worktree, fix failures, and report the final result.",
+    description: "JSKIT asks Codex to run the official verification command in the worktree, fix failures, and report the final passing result.",
     id: "automated_checks_run",
     kind: "codex_prompt",
     label: "Automated checks",
@@ -361,7 +458,14 @@ const STEP_DEFINITIONS = Object.freeze([
     kind: "user_check",
     label: "User check",
     nextCommandTemplate: `${JSKIT_CLI_SHELL_COMMAND} session {{session_id}} step --user-check passed`,
-    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied"]
+    preconditions: ["session_exists", "worktree_exists", "dependencies_installed", "ready_jskit_app", "issue_metadata_exists", "active_cycle_exists", "automated_checks_passed", "deep_ui_check_satisfied"],
+    utilityActions: Object.freeze([
+      Object.freeze({
+        id: "session_app_test",
+        kind: "app_test",
+        label: "Test app"
+      })
+    ])
   }),
   defineStep({
     buttonLabel: "Commit accepted changes",
@@ -379,13 +483,6 @@ const STEP_DEFINITIONS = Object.freeze([
     label: "Blueprint updated",
     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"]
   }),
-  defineStep({
-    buttonLabel: "Run verification",
-    description: "JSKIT runs the final project verification command in the session worktree and records the result.",
-    id: "doctor_run",
-    label: "Verification run",
-    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"]
-  }),
   defineStep({
     buttonLabel: "Create final report",
     description: "JSKIT creates the deterministic final session report and comments it on the GitHub issue.",
@@ -406,7 +503,10 @@ const STEP_DEFINITIONS = Object.freeze([
     id: "pr_finalized",
     label: "PR finalized, worktree removed",
     preconditions: ["session_exists", "pr_url_exists", "worktree_exists"],
-    requiresExplicitRun: true
+    requiresExplicitRun: true,
+    submitOptions: Object.freeze({
+      mergePr: true
+    })
   }),
   defineStep({
     buttonLabel: "Finish session",

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

@@ -32,7 +32,7 @@ Implementation rules:
 - Keep direct knex exceptional and minimal. Prefer internal json-rest-api seams outside generated CRUD packages and explicit weird-custom feature lanes.
 - Keep runtime, UI, and data concerns separated.
 - Avoid accidental scope expansion.
-- Do not create old workflow files such as `.jskit/WORKBOARD.md`; the session files and receipts are the workflow record.
+- Do not create `.jskit/WORKBOARD.md`; the session files and receipts are the workflow record.
 - If user-facing UI changes, bring the screen to Material Design and Vuetify quality before calling it done. Include coherent responsive layout, loading, empty, error, disabled, and success states where relevant.
 - If verification needs login, use the app's local development auth bootstrap path rather than a live external auth login.
 

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

@@ -15,15 +15,9 @@ No stones unturned:
 - Read `.jskit/APP_BLUEPRINT.md` and `.jskit/helper-map.md` when present.
 - Read package.json, `.jskit/lock.json`, `config/public.js`, relevant `src/`, relevant `packages/`, and relevant package docs or `npx --no-install jskit show ... --details`.
 - Ask follow-up questions until all important issue details are known.
+- Ask the user for whatever is still needed.
 - Ask for final confirmation before emitting final details.
-
-When you are ready to discuss details with the user, output this marker exactly once:
-
-[issue_details_conversation_ready]
-ready
-[/issue_details_conversation_ready]
-
-Then ask the user for whatever is still needed. Do not output the final markers below until the user has confirmed the details.
+- Do not output the final markers below until the user has confirmed the details.
 
 For CRUD or persisted data, confirm entity/table name, fields, field types, nullability, defaults, uniqueness, indexes, relationships, ownership, allowed operations, list/view/form shape, validation, permissions, migration/generator lane, and exact CRUD generator command or exact reason no CRUD generator applies.
 

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

@@ -15,7 +15,7 @@ Do not run workflow, repair, or mutation commands during issue drafting:
 
 - Do not run `npx --no-install jskit session`, `npx --no-install jskit session step`, or any command that advances a JSKIT session.
 - Do not run `gh`, `git add`, `git commit`, `git push`, `npm install`, generators, tests, verification, devlinks, or doctor commands.
-- Do not try to fix missing PATH entries or missing command shims. If a tool is unavailable, continue with read-only file inspection.
+- Do not try to fix missing PATH entries or missing helper binaries. If a tool is unavailable, continue with read-only file inspection.
 - Do not edit files.
 
 Draft an implementation-ready issue, not a broad product essay.

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

@@ -0,0 +1,16 @@
+Resolve the listed deslop findings in the current worktree.
+
+Fix only the listed findings. Keep scope tight. Do not create commits, branches, issues, pull requests, merges, or worktree cleanup.
+
+Use existing JSKIT helpers, generators, package seams, and app-local helpers where they fit. Do not introduce helper churn or unrelated refactors while resolving these findings.
+
+[resolve_deslop_findings]
+{{findings}}
+[/resolve_deslop_findings]
+
+When finished:
+
+- Summarize the exact findings fixed.
+- List changed files.
+- List checks run, or say why checks were not run.
+- Wait for the next review prompt.

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

@@ -32,5 +32,7 @@ Rules:
 When finished, summarize the blueprint result normally, then end with this exact marker:
 
 [jskit_step_result]
-Blueprint updated.
+status: complete
+step: blueprint_updated
+summary: Short summary of blueprint changes, or why no blueprint update was needed.
 [/jskit_step_result]

package/src/server/sessionRuntime/responses.js

@@ -3,6 +3,8 @@ import path from "node:path";
 import {
   CYCLE_STEP_IDS,
   JSKIT_CLI_SHELL_COMMAND,
+  PROMPT_DIRECTORY,
+  REVIEW_EXECUTION_CODEX_HANDOFF,
   REVIEW_PASS_LIMIT,
   SESSION_WORKFLOW_VERSION,
   SESSION_STATUS,
@@ -73,8 +75,14 @@ function normalizeKnownStepIds(stepIds = []) {
 }
 
 function stepCanExposeStoredPrompt(stepId) {
-  const step = STEP_DEFINITION_BY_ID[normalizeStepId(stepId)];
-  return Boolean(step?.codex || step?.kind === "codex_prompt" || step?.kind === "human_input");
+  const normalizedStepId = normalizeStepId(stepId);
+  const step = STEP_DEFINITION_BY_ID[normalizedStepId];
+  return Boolean(
+    normalizedStepId === "review_changes_accepted" ||
+    step?.codex ||
+    step?.kind === "codex_prompt" ||
+    step?.kind === "human_input"
+  );
 }
 
 const DEFAULT_ACTIVE_CYCLE = "001";
@@ -198,6 +206,35 @@ async function readReviewPasses(paths) {
   return Promise.all(passes.map((pass) => readReviewPassInfo(paths, pass)));
 }
 
+const REVIEW_STEP_IDS = Object.freeze([
+  "review_prompt_rendered",
+  "review_changes_accepted"
+]);
+
+function latestReviewPass(artifacts = {}) {
+  const passes = Array.isArray(artifacts.reviewPasses) ? artifacts.reviewPasses : [];
+  return passes.at(-1) || null;
+}
+
+function latestReviewPassIsPrompted(artifacts = {}) {
+  return latestReviewPass(artifacts)?.status === "prompted";
+}
+
+async function readPromptFromAbsolutePath(filePath = "") {
+  return filePath ? readTextIfExists(filePath) : "";
+}
+
+async function readReviewPromptForStep(paths, artifacts = {}) {
+  const latestPass = latestReviewPass(artifacts);
+  if (latestPass?.status === "prompted") {
+    const prompt = await readPromptFromAbsolutePath(latestPass.promptPath);
+    if (prompt) {
+      return prompt;
+    }
+  }
+  return "";
+}
+
 const PROMPT_ARTIFACT_BY_STEP_ID = Object.freeze({
   issue_drafted: "issue_draft.md",
   issue_details_gathered: "issue_details.md",
@@ -218,10 +255,13 @@ async function promptArtifactForStep(paths, stepId) {
   return PROMPT_ARTIFACT_BY_STEP_ID[normalizedStepId] || "";
 }
 
-async function readPromptForStep(paths, stepId) {
+async function readPromptForStep(paths, stepId, artifacts = {}) {
   if (!stepCanExposeStoredPrompt(stepId)) {
     return "";
   }
+  if (REVIEW_STEP_IDS.includes(normalizeStepId(stepId))) {
+    return readReviewPromptForStep(paths, artifacts);
+  }
   const promptArtifact = await promptArtifactForStep(paths, stepId);
   if (promptArtifact) {
     const prompt = await readTextIfExists(path.join(paths.sessionRoot, "prompts", promptArtifact));
@@ -229,7 +269,7 @@ async function readPromptForStep(paths, stepId) {
       return prompt;
     }
   }
-  return readTextIfExists(path.join(paths.sessionRoot, "prompt.md"));
+  return "";
 }
 
 async function readStepFileNames(stepsRoot) {
@@ -253,11 +293,6 @@ async function readCompletedSteps(paths) {
   return applyReviewPassCompletionOverlay(paths, normalizeKnownStepIds([...globalStepIds, ...cycleStepIds]));
 }
 
-const REVIEW_STEP_IDS = Object.freeze([
-  "review_prompt_rendered",
-  "review_changes_accepted"
-]);
-
 async function applyReviewPassCompletionOverlay(paths, completedSteps = []) {
   const completed = new Set(completedSteps);
   if (!REVIEW_STEP_IDS.some((stepId) => completed.has(stepId))) {
@@ -315,7 +350,7 @@ async function readCycles(paths, activeCycle) {
         }
       }
     } catch {
-      // Missing cycle directories are normal for older sessions.
+      // No cycle directory exists until a session enters a repeatable work cycle.
     }
   }
   return Promise.all([...cycles]
@@ -494,6 +529,23 @@ function cloneContractValue(value) {
   );
 }
 
+async function publicCodexContract(codex = null) {
+  if (!codex || typeof codex !== "object" || Array.isArray(codex)) {
+    return null;
+  }
+  const clonedCodex = cloneContractValue(codex);
+  const resolvePrompt = clonedCodex.responseContract?.resolvePrompt;
+  const templateFile = normalizeText(resolvePrompt?.templateFile || "");
+  if (templateFile) {
+    const template = await readTextIfExists(path.join(PROMPT_DIRECTORY, templateFile));
+    clonedCodex.responseContract.resolvePrompt = {
+      ...resolvePrompt,
+      template
+    };
+  }
+  return clonedCodex;
+}
+
 function stepRepeatabilityContract(stepId) {
   if (!CYCLE_STEP_IDS.includes(normalizeStepId(stepId))) {
     return {
@@ -513,6 +565,8 @@ function stepRepeatabilityContract(stepId) {
 
 function publicStepDefinition(step, index) {
   return {
+    automation: cloneContractValue(step.automation || { mode: "manual" }),
+    ...(step.codex ? { codex: cloneContractValue(step.codex) } : {}),
     description: step.description,
     displayGroupId: step.displayGroupId || "",
     displayGroupLabel: step.displayGroupLabel || "",
@@ -523,6 +577,7 @@ function publicStepDefinition(step, index) {
     label: step.label,
     ...stepRepeatabilityContract(step.id),
     requiresExplicitRun: step.requiresExplicitRun === true,
+    submitOptions: cloneContractValue(step.submitOptions || {}),
     utilityActions: cloneContractValue(step.utilityActions || [])
   };
 }
@@ -534,8 +589,7 @@ function buildStepDefinitions() {
 function stepIsRetryableWhenBlocked(stepId) {
   return [
     "automated_checks_run",
-    "deep_ui_check_run",
-    "doctor_run"
+    "deep_ui_check_run"
   ].includes(normalizeStepId(stepId));
 }
 
@@ -607,11 +661,13 @@ function buildCurrentStepAction(stepId, artifacts = {}) {
   if (step.id === "review_changes_accepted") {
     alternateActions.push({
       id: "request_another_review_pass",
+      helpText: "Use this only when important review findings remain. Studio will record these notes and loop back to Codex review.",
       input: {
         formatHint: "markdown",
         label: "What important findings remain?",
         multiline: true,
         name: "reviewFindings",
+        placeholder: "List the specific findings Codex still needs to address.",
         required: true,
         type: "text"
       },
@@ -626,6 +682,7 @@ 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.",
       input: {
         formatHint: "markdown",
         label: "Why is this session finishing without merge?",
@@ -679,10 +736,13 @@ function buildCurrentStepAction(stepId, artifacts = {}) {
     alternateActions,
     buttonLabel: dynamicButtonLabel,
     description: dynamicDescription,
+    displayGroupId: step.displayGroupId,
+    displayGroupLabel: step.displayGroupLabel,
     index: STEP_IDS.indexOf(step.id),
     input: cloneContractValue(step.input),
     kind: step.kind,
     label: dynamicButtonLabel,
+    automation: cloneContractValue(step.automation || { mode: "manual" }),
     ...stepRepeatabilityContract(step.id),
     requiredInput: cloneContractValue(step.input),
     requiresExplicitRun: step.requiresExplicitRun === true,
@@ -690,13 +750,29 @@ function buildCurrentStepAction(stepId, artifacts = {}) {
     retryable: artifacts.status === SESSION_STATUS.BLOCKED && stepIsRetryableWhenBlocked(step.id),
     skipReason: skipReasonForStep(step.id, artifacts),
     stepId: step.id,
+    submitOptions: cloneContractValue(step.submitOptions || {}),
     utilityActions: cloneContractValue(dynamicUtilityActions)
   };
 }
 
-function buildCodexHandoff(stepId, _artifacts = {}) {
+function rawCodexHandoff(stepId, artifacts = {}) {
+  if (normalizeStepId(stepId) === "review_changes_accepted" && latestReviewPassIsPrompted(artifacts)) {
+    return cloneContractValue(REVIEW_EXECUTION_CODEX_HANDOFF);
+  }
   const step = STEP_DEFINITION_BY_ID[stepId];
-  return step?.codex ? cloneContractValue(step.codex) : null;
+  const codex = step?.codex ? cloneContractValue(step.codex) : null;
+  if (
+    codex &&
+    normalizeStepId(stepId) === "plan_made" &&
+    normalizeCycleNumber(artifacts.activeCycle || "") !== "001"
+  ) {
+    codex.promptIntroText = "Codex will create a revised implementation plan based on the rework notes.";
+  }
+  return codex;
+}
+
+async function buildCodexHandoff(stepId, artifacts = {}) {
+  return publicCodexContract(rawCodexHandoff(stepId, artifacts));
 }
 
 async function readSessionArtifacts(paths) {
@@ -798,7 +874,7 @@ async function readSessionArtifacts(paths) {
     (completedSteps.includes(currentStep) || currentStepIndex < 0 || currentStepIndex > nextStepIndex)
     ? nextStep
     : currentStep || nextStep;
-  const prompt = await readPromptForStep(paths, effectiveCurrentStep);
+  const prompt = await readPromptForStep(paths, effectiveCurrentStep, { reviewPasses });
 
   return {
     codexThreadId,
@@ -969,7 +1045,7 @@ async function buildSessionResponse(paths, {
     commandLogPath: artifacts.commandLogPath || "",
     stepDefinitions: buildStepDefinitions(),
     currentStepAction: buildCurrentStepAction(currentStep, artifacts),
-    codex: codex === undefined ? buildCodexHandoff(currentStep, artifacts) : cloneContractValue(codex),
+    codex: codex === undefined ? await buildCodexHandoff(currentStep, artifacts) : await publicCodexContract(codex),
     prompt: responsePrompt,
     nextCommand: buildNextCommand(paths.sessionId || "", currentStep),
     issueUrl: artifacts.issueUrl || "",
@@ -1120,7 +1196,8 @@ async function failSession(paths, {
   repairCommand = "",
   preconditions = [],
   status = SESSION_STATUS.BLOCKED,
-  prompt = ""
+  prompt = "",
+  codex = undefined
 }) {
   if (paths.sessionRoot && await fileExists(paths.sessionRoot)) {
     await markStatus(paths, status);
@@ -1129,6 +1206,7 @@ async function failSession(paths, {
     ok: false,
     status,
     prompt,
+    codex,
     preconditions,
     errors: [
       createError({

package/src/server/sessionRuntime.js

@@ -9,6 +9,7 @@ import path from "node:path";
 import {
   BLUEPRINT_CODEX_HANDOFF,
   AUTOMATED_CHECK_REPAIR_CODEX_HANDOFF,
+  CYCLE_STEP_IDS,
   DEEP_UI_CHECK_CODEX_HANDOFF,
   ISSUE_DETAILS_CODEX_HANDOFF,
   PLAN_EXECUTION_CODEX_HANDOFF,
@@ -16,6 +17,7 @@ import {
   REVIEW_EXECUTION_CODEX_HANDOFF,
   SESSION_STATUS,
   SESSION_WORKFLOW_VERSION,
+  STEP_DEFINITION_BY_ID,
   STEP_DEFINITIONS,
   STEP_IDS,
   STEP_PRECONDITION_NAMES
@@ -165,6 +167,15 @@ function extractMarkedText(value = "", marker = "") {
   return normalizeText(matches.length > 0 ? matches[matches.length - 1][1] : "");
 }
 
+function extractMarkedField(value = "", fieldName = "") {
+  const normalizedFieldName = normalizeText(fieldName);
+  if (!normalizedFieldName) {
+    return "";
+  }
+  const pattern = new RegExp(`^\\s*${normalizedFieldName.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}\\s*:\\s*(.+)$`, "imu");
+  return normalizeText(pattern.exec(normalizeText(value))?.[1] || "");
+}
+
 function extractIssueTitle(value = "") {
   return extractMarkedText(value, "issue_title");
 }
@@ -211,6 +222,62 @@ async function writePromptArtifact(paths, fileName, prompt) {
   await writeTextFile(path.join(paths.sessionRoot, "prompts", fileName), prompt);
 }
 
+async function codexResultPath(paths, stepId) {
+  if (CYCLE_STEP_IDS.includes(stepId)) {
+    const activeCycle = await readActiveCycle(paths);
+    return path.join(cycleRootPath(paths, activeCycle), "codex_results", `${stepId}.md`);
+  }
+  return path.join(paths.sessionRoot, "codex_results", `${stepId}.md`);
+}
+
+function codexResponseContractForStep(stepId) {
+  const contract = STEP_DEFINITION_BY_ID[stepId]?.codex?.responseContract;
+  return contract && typeof contract === "object" && !Array.isArray(contract) ? contract : null;
+}
+
+async function requireCodexStepResult(paths, stepId, result, preconditions = [], contractOverride = null) {
+  const contract = contractOverride || codexResponseContractForStep(stepId);
+  if (contract?.required !== true || !contract.marker) {
+    return null;
+  }
+
+  const source = String(result || "");
+  if (!source.trim()) {
+    return failSession(paths, {
+      code: "codex_result_required",
+      message: `The ${STEP_DEFINITION_BY_ID[stepId]?.label || stepId} step has already produced a Codex prompt. Paste Codex's final marked result with --codex-result - before JSKIT records the receipt.`,
+      repairCommand: `jskit session ${paths.sessionId} step --codex-result -`,
+      preconditions
+    });
+  }
+
+  const markedResult = extractMarkedText(source, contract.marker);
+  if (!markedResult) {
+    return failSession(paths, {
+      code: "codex_result_marker_missing",
+      message: `Codex output for ${STEP_DEFINITION_BY_ID[stepId]?.label || stepId} must include [${contract.marker}]... [/${contract.marker}] before JSKIT can advance.`,
+      repairCommand: `jskit session ${paths.sessionId} step --codex-result -`,
+      preconditions
+    });
+  }
+  const stepField = normalizeText(contract.stepField);
+  if (stepField) {
+    const resultStep = extractMarkedField(markedResult, stepField);
+    if (resultStep !== stepId) {
+      return failSession(paths, {
+        code: "codex_result_step_mismatch",
+        message: `Codex output for ${STEP_DEFINITION_BY_ID[stepId]?.label || stepId} must include ${stepField}: ${stepId} inside [${contract.marker}] before JSKIT can advance.`,
+        repairCommand: `jskit session ${paths.sessionId} step --codex-result -`,
+        preconditions
+      });
+    }
+  }
+
+  await writeTextFile(await codexResultPath(paths, stepId), source);
+  await appendAgentDecisions(paths, extractAgentDecisions(source));
+  return null;
+}
+
 function commandText(command, args = []) {
   return [command, ...args].map((part) => {
     const value = String(part || "");
@@ -1050,11 +1117,15 @@ async function makePlan(paths, options = {}, context = {}) {
   });
 }
 
-async function renderPlanExecutionPrompt(paths, _options = {}, context = {}) {
+async function renderPlanExecutionPrompt(paths, options = {}, context = {}) {
   const preconditions = context.preconditions || [];
   const activeCycle = await readActiveCycle(paths);
   const executionPromptPath = path.join(paths.sessionRoot, "prompts", cyclePlanExecutionPromptFileName(activeCycle));
   if (await fileExists(executionPromptPath)) {
+    const codexResultFailure = await requireCodexStepResult(paths, "plan_executed", options.codexResult, preconditions);
+    if (codexResultFailure) {
+      return codexResultFailure;
+    }
     await writeReceipt(paths, "plan_executed", `Cycle ${activeCycle} plan execution completed by Codex.`);
     await markStatus(paths, SESSION_STATUS.RUNNING);
     return buildSessionResponse(paths, {
@@ -1402,7 +1473,8 @@ async function acceptReviewChanges(paths, options = {}) {
 async function runAutomatedChecks(paths, {
   stepId,
   label
-}) {
+}, options = {}, context = {}) {
+  const preconditions = context.preconditions || [];
   const [command, args] = await doctorCommandForWorktree(paths.worktree);
   const promptFileName = `${stepId}.md`;
   const promptPath = path.join(paths.sessionRoot, "prompts", promptFileName);
@@ -1411,6 +1483,10 @@ async function runAutomatedChecks(paths, {
   const checkCommand = [command, ...args].join(" ");
 
   if (await fileExists(promptPath)) {
+    const codexResultFailure = await requireCodexStepResult(paths, stepId, options.codexResult, preconditions);
+    if (codexResultFailure) {
+      return codexResultFailure;
+    }
     await writeTextFile(
       path.join(checksRoot, `${stepId}.json`),
       `${JSON.stringify({
@@ -1423,7 +1499,9 @@ async function runAutomatedChecks(paths, {
     );
     await writeReceipt(paths, stepId, `${label} completed by Codex: ${checkCommand}.`);
     await markStatus(paths, SESSION_STATUS.RUNNING);
-    return buildSessionResponse(paths);
+    return buildSessionResponse(paths, {
+      preconditions
+    });
   }
 
   const prompt = await renderPrompt(paths, "automated_checks.md", {
@@ -1443,6 +1521,7 @@ async function runAutomatedChecks(paths, {
   await markStatus(paths, SESSION_STATUS.WAITING_FOR_USER);
   return buildSessionResponse(paths, {
     codex: AUTOMATED_CHECK_REPAIR_CODEX_HANDOFF,
+    preconditions,
     prompt,
     status: SESSION_STATUS.WAITING_FOR_USER
   });
@@ -1501,6 +1580,10 @@ async function runDeepUiCheck(paths, {
   const promptFileName = `${stepId}.md`;
   const promptPath = path.join(paths.sessionRoot, "prompts", promptFileName);
   if (await fileExists(promptPath)) {
+    const codexResultFailure = await requireCodexStepResult(paths, stepId, options.codexResult, preconditions);
+    if (codexResultFailure) {
+      return codexResultFailure;
+    }
     await writeReceipt(paths, stepId, `${label} completed by Codex.`);
     await markStatus(paths, SESSION_STATUS.RUNNING);
     return buildSessionResponse(paths, {
@@ -1644,7 +1727,7 @@ async function commitAcceptedChanges(paths, _options = {}, context = {}) {
   });
 }
 
-async function updateBlueprint(paths, _options = {}, context = {}) {
+async function updateBlueprint(paths, options = {}, context = {}) {
   const preconditions = context.preconditions || [];
   const issueText = await readTrimmedFile(path.join(paths.sessionRoot, "issue.md"));
   const issueTitle = await readTrimmedFile(path.join(paths.sessionRoot, "issue_title")) || titleFromIssue(issueText);
@@ -1657,6 +1740,10 @@ async function updateBlueprint(paths, _options = {}, context = {}) {
   const blueprintPromptPath = path.join(paths.sessionRoot, "prompts", "update_blueprint.md");
 
   if (await fileExists(blueprintPromptPath)) {
+    const codexResultFailure = await requireCodexStepResult(paths, "blueprint_updated", options.codexResult, preconditions);
+    if (codexResultFailure) {
+      return codexResultFailure;
+    }
     const changedFiles = await changedFilesInWorktree(paths);
     const unexpectedChanges = changedFiles.filter((file) => file !== ".jskit/APP_BLUEPRINT.md");
     if (unexpectedChanges.length > 0) {
@@ -1755,68 +1842,6 @@ async function doctorCommandForWorktree(worktree) {
   return ["npx", ["--no-install", "jskit", "app", "verify"]];
 }
 
-async function runDoctor(paths) {
-  const repairCommitFailure = await maybeCommitDoctorRepair(paths);
-  if (repairCommitFailure) {
-    return repairCommitFailure;
-  }
-  const [command, args] = await doctorCommandForWorktree(paths.worktree);
-  const result = await runLoggedCommand(paths, "doctor_run", command, args, {
-    cwd: paths.worktree,
-    timeout: 1000 * 60 * 15
-  });
-  await writeTextFile(path.join(paths.sessionRoot, "doctor.log"), result.output);
-  if (!result.ok) {
-    const prompt = await renderPrompt(paths, "doctor_failure.md", {
-      doctor_output: result.output
-    });
-    await writePromptArtifact(paths, "doctor_failure.md", prompt);
-    return failSession(paths, {
-      code: "doctor_failed",
-      message: "Doctor/verification command failed. Paste the failure prompt into Codex, then rerun this step.",
-      repairCommand: `${command} ${args.join(" ")}`,
-      prompt
-    });
-  }
-  await writeReceipt(paths, "doctor_run", `Doctor command passed: ${command} ${args.join(" ")}.`);
-  await markStatus(paths, SESSION_STATUS.RUNNING);
-  return buildSessionResponse(paths);
-}
-
-async function maybeCommitDoctorRepair(paths) {
-  if (!await fileExists(path.join(paths.sessionRoot, "doctor.log")) || await fileExists(path.join(paths.sessionRoot, "steps", "doctor_run"))) {
-    return null;
-  }
-  const status = await worktreeStatus(paths.worktree);
-  if (!status.ok) {
-    return failSession(paths, {
-      code: "git_status_failed",
-      message: status.output || "Failed to inspect verification repair changes.",
-      repairCommand: `git -C ${paths.worktree} status --short`
-    });
-  }
-  if (status.changedFiles.length < 1) {
-    return null;
-  }
-  const result = await commitWorktree(paths, {
-    message: `Verification repairs for ${paths.sessionId}`
-  });
-  if (!result.ok) {
-    return failSession(paths, {
-      code: "doctor_repair_commit_failed",
-      message: result.output || "Failed to commit verification repair changes.",
-      repairCommand: `git -C ${paths.worktree} status --short`
-    });
-  }
-  await writeTextFile(path.join(paths.sessionRoot, "doctor_repair_commit.json"), `${JSON.stringify({
-    changedFiles: result.changedFiles || [],
-    commit: await currentHead(paths),
-    committedAt: timestampForReceipt(),
-    ok: true
-  }, null, 2)}\n`);
-  return null;
-}
-
 async function commitLinesSinceBase(paths) {
   const baseCommit = await readTrimmedFile(path.join(paths.sessionRoot, "base_commit"));
   const args = baseCommit
@@ -2536,10 +2561,10 @@ const STEP_RUNNERS = Object.freeze({
   issue_details_gathered: saveIssueDetails,
   plan_made: makePlan,
   plan_executed: renderPlanExecutionPrompt,
-  automated_checks_run: (paths) => runAutomatedChecks(paths, {
+  automated_checks_run: (paths, options, context) => runAutomatedChecks(paths, {
     label: "Automated checks",
     stepId: "automated_checks_run"
-  }),
+  }, options, context),
   deep_ui_check_run: (paths, options, context) => runDeepUiCheck(paths, {
     label: "Deep UI check",
     phase: "pre_review",
@@ -2550,7 +2575,6 @@ const STEP_RUNNERS = Object.freeze({
   user_check_completed: userCheck,
   changes_committed: commitAcceptedChanges,
   blueprint_updated: updateBlueprint,
-  doctor_run: runDoctor,
   final_report_created: createFinalReport,
   pr_created: createPr,
   pr_finalized: finalizePr,

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

@@ -1,35 +0,0 @@
-The JSKIT session doctor or verification step failed.
-
-Session:
-
-{{session_id}}
-
-Worktree:
-
-{{worktree}}
-
-Failure output:
-
-{{doctor_output}}
-
-Fix the root cause in this worktree. Do not silence the failure or remove checks to make the step pass.
-
-Diagnosis rules:
-
-- Re-read the issue, `issue_details.md`, the active cycle plan file, `agent_decisions.md`, `.jskit/APP_BLUEPRINT.md`, `.jskit/helper-map.md`, check receipts, and UI check receipts before repairing.
-- Identify whether the failure is dependency/setup, JSKIT metadata, generated contract drift, routing/surface wiring, CRUD ownership, UI verification receipt, test-auth, or ordinary application code.
-- Prefer repairing the JSKIT-owned contract or generated metadata over adding local-path hacks.
-- Do not run `npm install` only because optional agent docs are missing. Run installs only when the failure or a JSKIT setup/session step requires dependency repair.
-- If a generator/package command is the correct repair, use the `npx --no-install jskit` command rather than hand-recreating generated structure.
-- For UI receipt failures, run the relevant Playwright check and record it with `npx --no-install jskit app verify-ui --command "<playwright command>" --feature "<label>" --auth-mode <mode>` when possible.
-- If login is required, use the app's development auth bootstrap path rather than a live external auth flow.
-
-Do not push, open a PR, merge, or remove the worktree. When the fix is ready, report the root cause, files changed, verification, and anything still unverified. The user or Studio will rerun the JSKIT session step.
-
-If the repair records a meaningful verification decision, tradeoff, missing coverage, or root-cause explanation future steps should know, include concise entries with reasons in this exact marker block:
-
-```text
-[agent_decisions]
-<verification or repair decisions, or "No new decisions.">
-[/agent_decisions]
-```