@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

package/src/resources/extensions/gsd/tools/reassess-roadmap.ts

@@ -16,7 +16,7 @@ import {
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb, renderAssessmentFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -75,12 +75,19 @@ function validateParams(params: ReassessRoadmapParams): ReassessRoadmapParams {
     throw new Error("sliceChanges.removed must be an array");
   }
 
+  const SLICE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]*$/;
+
   // Validate each modified slice
   for (let i = 0; i < params.sliceChanges.modified.length; i++) {
     const s = params.sliceChanges.modified[i];
     if (!s || typeof s !== "object") throw new Error(`sliceChanges.modified[${i}] must be an object`);
     if (!isNonEmptyString(s.sliceId)) throw new Error(`sliceChanges.modified[${i}].sliceId is required`);
     if (!isNonEmptyString(s.title)) throw new Error(`sliceChanges.modified[${i}].title is required`);
+    if (s.depends !== undefined) {
+      if (!Array.isArray(s.depends) || s.depends.some((item: unknown) => !isNonEmptyString(item) || !SLICE_ID_RE.test(item as string))) {
+        throw new Error(`sliceChanges.modified[${i}].depends must be an array of valid slice IDs (e.g. "S01")`);
+      }
+    }
   }
 
   // Validate each added slice
@@ -89,6 +96,11 @@ function validateParams(params: ReassessRoadmapParams): ReassessRoadmapParams {
     if (!s || typeof s !== "object") throw new Error(`sliceChanges.added[${i}] must be an object`);
     if (!isNonEmptyString(s.sliceId)) throw new Error(`sliceChanges.added[${i}].sliceId is required`);
     if (!isNonEmptyString(s.title)) throw new Error(`sliceChanges.added[${i}].title is required`);
+    if (s.depends !== undefined) {
+      if (!Array.isArray(s.depends) || s.depends.some((item: unknown) => !isNonEmptyString(item) || !SLICE_ID_RE.test(item as string))) {
+        throw new Error(`sliceChanges.added[${i}].depends must be an array of valid slice IDs (e.g. "S01")`);
+      }
+    }
   }
 
   return params;
@@ -166,6 +178,37 @@ export async function handleReassessRoadmap(
         }
       }
 
+      // Cross-milestone depends validation — effective slice ID set after this reassessment
+      const removedIds = new Set<string>(params.sliceChanges.removed);
+      const effectiveSliceIds = new Set<string>(
+        existingSlices.map(s => s.id).filter(id => !removedIds.has(id)),
+      );
+      for (const added of params.sliceChanges.added) {
+        effectiveSliceIds.add(added.sliceId);
+      }
+      for (let i = 0; i < params.sliceChanges.modified.length; i++) {
+        const mod = params.sliceChanges.modified[i]!;
+        if (mod.depends !== undefined) {
+          for (const dep of mod.depends) {
+            if (!effectiveSliceIds.has(dep)) {
+              guardError = `sliceChanges.modified[${i}].depends references unknown slice "${dep}" — check that it is defined in this milestone`;
+              return;
+            }
+          }
+        }
+      }
+      for (let i = 0; i < params.sliceChanges.added.length; i++) {
+        const added = params.sliceChanges.added[i]!;
+        if (added.depends !== undefined) {
+          for (const dep of added.depends) {
+            if (!effectiveSliceIds.has(dep)) {
+              guardError = `sliceChanges.added[${i}].depends references unknown slice "${dep}" — check that it is defined in this milestone`;
+              return;
+            }
+          }
+        }
+      }
+
       // Record assessment
       insertAssessment({
         path: assessmentRelPath,
@@ -263,7 +306,7 @@ export async function handleReassessRoadmap(
 
     // ── Post-mutation hook: projections, manifest, event log ─────
     try {
-      await renderAllProjections(basePath, params.milestoneId);
+      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "reassess-roadmap",

package/src/resources/extensions/gsd/tools/reopen-milestone.ts

@@ -10,17 +10,12 @@
  */
 
 import {
-  getMilestone,
   getMilestoneSlices,
   getSliceTasks,
-  reopenMilestoneStatus,
-  updateSliceStatus,
-  updateTaskStatus,
-  transaction,
+  reopenMilestoneCascade,
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
-import { isClosedStatus } from "../status-guards.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -53,40 +48,18 @@ export async function handleReopenMilestone(
     return { error: "milestoneId is required and must be a non-empty string" };
   }
 
-  // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
-  let guardError: string | null = null;
-  let slicesResetCount = 0;
-  let tasksResetCount = 0;
-
-  transaction(() => {
-    const milestone = getMilestone(params.milestoneId);
-    if (!milestone) {
-      guardError = `milestone not found: ${params.milestoneId}`;
-      return;
-    }
-    if (!isClosedStatus(milestone.status)) {
-      guardError = `milestone ${params.milestoneId} is not closed (status: ${milestone.status}) — nothing to reopen`;
-      return;
-    }
-
-    reopenMilestoneStatus(params.milestoneId);
-
-    const slices = getMilestoneSlices(params.milestoneId);
-    slicesResetCount = slices.length;
-
-    for (const slice of slices) {
-      updateSliceStatus(params.milestoneId, slice.id, "in_progress");
-      const tasks = getSliceTasks(params.milestoneId, slice.id);
-      tasksResetCount += tasks.length;
-      for (const task of tasks) {
-        updateTaskStatus(params.milestoneId, slice.id, task.id, "pending");
-      }
+  // ── Atomic reopen cascade (guards + writes in one transaction) ───────────
+  const outcome = reopenMilestoneCascade(params.milestoneId);
+  if (!outcome.ok) {
+    switch (outcome.reason) {
+      case "milestone-not-found":
+        return { error: `milestone not found: ${params.milestoneId}` };
+      case "milestone-not-closed":
+        return { error: `milestone ${params.milestoneId} is not closed (status: ${outcome.status}) — nothing to reopen` };
     }
-  });
-
-  if (guardError) {
-    return { error: guardError };
   }
+  const slicesResetCount = outcome.slicesReset;
+  const tasksResetCount = outcome.tasksReset;
 
   // ── Invalidate caches ────────────────────────────────────────────────────
   invalidateStateCache();
@@ -125,7 +98,7 @@ export async function handleReopenMilestone(
 
   // ── Post-mutation hook ───────────────────────────────────────────────────
   try {
-    await renderAllProjections(basePath, params.milestoneId);
+    await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
     writeManifest(basePath);
     appendEvent(basePath, {
       cmd: "reopen-milestone",

package/src/resources/extensions/gsd/tools/reopen-slice.ts

@@ -12,16 +12,11 @@
 // Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
 
 import {
-  getMilestone,
-  getSlice,
   getSliceTasks,
-  updateSliceStatus,
-  updateTaskStatus,
-  transaction,
+  reopenSliceCascade,
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
-import { isClosedStatus } from "../status-guards.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -57,44 +52,21 @@ export async function handleReopenSlice(
     return { error: "milestoneId is required and must be a non-empty string" };
   }
 
-  // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
-  let guardError: string | null = null;
-  let tasksResetCount = 0;
-
-  transaction(() => {
-    const milestone = getMilestone(params.milestoneId);
-    if (!milestone) {
-      guardError = `milestone not found: ${params.milestoneId}`;
-      return;
-    }
-    if (isClosedStatus(milestone.status)) {
-      guardError = `cannot reopen slice in a closed milestone: ${params.milestoneId} (status: ${milestone.status})`;
-      return;
-    }
-
-    const slice = getSlice(params.milestoneId, params.sliceId);
-    if (!slice) {
-      guardError = `slice not found: ${params.milestoneId}/${params.sliceId}`;
-      return;
-    }
-    if (!isClosedStatus(slice.status)) {
-      guardError = `slice ${params.sliceId} is not complete (status: ${slice.status}) — nothing to reopen`;
-      return;
+  // ── Atomic reopen cascade (guards + writes in one transaction) ───────────
+  const outcome = reopenSliceCascade(params.milestoneId, params.sliceId);
+  if (!outcome.ok) {
+    switch (outcome.reason) {
+      case "milestone-not-found":
+        return { error: `milestone not found: ${params.milestoneId}` };
+      case "milestone-closed":
+        return { error: `cannot reopen slice in a closed milestone: ${params.milestoneId} (status: ${outcome.status})` };
+      case "slice-not-found":
+        return { error: `slice not found: ${params.milestoneId}/${params.sliceId}` };
+      case "slice-not-complete":
+        return { error: `slice ${params.sliceId} is not complete (status: ${outcome.status}) — nothing to reopen` };
     }
-
-    // Fetch tasks inside txn so the list is consistent with the slice status check
-    const tasks = getSliceTasks(params.milestoneId, params.sliceId);
-    tasksResetCount = tasks.length;
-
-    updateSliceStatus(params.milestoneId, params.sliceId, "in_progress");
-    for (const task of tasks) {
-      updateTaskStatus(params.milestoneId, params.sliceId, task.id, "pending");
-    }
-  });
-
-  if (guardError) {
-    return { error: guardError };
   }
+  const tasksResetCount = outcome.tasksReset;
 
   // ── Invalidate caches ────────────────────────────────────────────────────
   invalidateStateCache();
@@ -125,7 +97,7 @@ export async function handleReopenSlice(
 
   // ── Post-mutation hook ───────────────────────────────────────────────────
   try {
-    await renderAllProjections(basePath, params.milestoneId);
+    await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
     writeManifest(basePath);
     appendEvent(basePath, {
       cmd: "reopen-slice",

package/src/resources/extensions/gsd/tools/reopen-task.ts

@@ -19,7 +19,7 @@ import {
 } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { isClosedStatus } from "../status-guards.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -119,7 +119,7 @@ export async function handleReopenTask(
 
   // ── Post-mutation hook ───────────────────────────────────────────────────
   try {
-    await renderAllProjections(basePath, params.milestoneId);
+    await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
     writeManifest(basePath);
     appendEvent(basePath, {
       cmd: "reopen-task",

package/src/resources/extensions/gsd/tools/replan-slice.ts

@@ -13,7 +13,7 @@ import { invalidateStateCache } from "../state.js";
 import { isClosedStatus } from "../status-guards.js";
 import { isNonEmptyString } from "../validation.js";
 import { renderPlanFromDb, renderReplanFromDb } from "../markdown-renderer.js";
-import { renderAllProjections } from "../workflow-projections.js";
+import { flushWorkflowProjections } from "../projection-flush.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning } from "../workflow-logger.js";
@@ -216,7 +216,7 @@ export async function handleReplanSlice(
 
     // ── Post-mutation hook: projections, manifest, event log ─────
     try {
-      await renderAllProjections(basePath, params.milestoneId);
+      await flushWorkflowProjections(basePath, { milestoneId: params.milestoneId });
       writeManifest(basePath);
       appendEvent(basePath, {
         cmd: "replan-slice",

package/src/resources/extensions/gsd/tools/skip-slice.ts

@@ -11,14 +11,9 @@
  */
 
 import {
-  getSlice,
-  getSliceTasks,
   isDbAvailable,
-  transaction,
-  updateSliceStatus,
-  updateTaskStatus,
+  skipSliceCascade,
 } from "../gsd-db.js";
-import { isClosedStatus } from "../status-guards.js";
 
 /**
  * Input parameters for {@link handleSkipSlice}.
@@ -90,44 +85,23 @@ export function handleSkipSlice(params: SkipSliceParams): SkipSliceResult {
     throw new Error("handleSkipSlice: GSD database is not available");
   }
 
-  // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ────
-  let guardError: string | null = null;
-  let guardCode: SkipSliceErrorCode | null = null;
-  let wasAlreadySkipped = false;
-  let tasksSkipped = 0;
-
-  transaction(() => {
-    const slice = getSlice(params.milestoneId, params.sliceId);
-    if (!slice) {
-      guardError = `Slice ${params.sliceId} not found in milestone ${params.milestoneId}`;
-      guardCode = "slice_not_found";
-      return;
-    }
-    if (slice.status === "complete" || slice.status === "done") {
-      guardError = `Slice ${params.sliceId} is already complete — cannot skip.`;
-      guardCode = "already_complete";
-      return;
-    }
-
-    wasAlreadySkipped = slice.status === "skipped";
-    if (!wasAlreadySkipped) {
-      updateSliceStatus(params.milestoneId, params.sliceId, "skipped");
+  // ── Atomic skip cascade (guards + writes in one transaction) ────────────
+  const outcome = skipSliceCascade(params.milestoneId, params.sliceId);
+  if (!outcome.ok) {
+    switch (outcome.reason) {
+      case "slice-not-found":
+        return {
+          ...base,
+          error: `Slice ${params.sliceId} not found in milestone ${params.milestoneId}`,
+          errorCode: "slice_not_found" as SkipSliceErrorCode,
+        };
+      case "slice-already-complete":
+        return {
+          ...base,
+          error: `Slice ${params.sliceId} is already complete — cannot skip.`,
+          errorCode: "already_complete" as SkipSliceErrorCode,
+        };
     }
-
-    // Cascade: mark every non-closed task as skipped so milestone completion
-    // doesn't trip the deep-task guard (#4375). Closed tasks (complete/done/
-    // skipped) are left untouched — we never downgrade.
-    const tasks = getSliceTasks(params.milestoneId, params.sliceId);
-    for (const task of tasks) {
-      if (!isClosedStatus(task.status)) {
-        updateTaskStatus(params.milestoneId, params.sliceId, task.id, "skipped");
-        tasksSkipped++;
-      }
-    }
-  });
-
-  if (guardError) {
-    return { ...base, error: guardError, errorCode: guardCode ?? undefined };
   }
-  return { ...base, tasksSkipped, wasAlreadySkipped };
+  return { ...base, tasksSkipped: outcome.tasksSkipped, wasAlreadySkipped: outcome.wasAlreadySkipped };
 }

package/src/resources/extensions/gsd/tools/validate-milestone.ts

@@ -19,11 +19,11 @@ import {
   insertAssessment,
   getMilestoneSlices,
   getMilestone,
-  getArtifact,
 } from "../gsd-db.js";
-import { gsdProjectionRoot, clearPathCache, resolveSliceFile } from "../paths.js";
+import { gsdProjectionRoot, clearPathCache } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
-import { saveFile, clearParseCache, loadFile } from "../files.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
+import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { VALIDATION_VERDICTS, isValidMilestoneVerdict } from "../verdict-parser.js";
 import { insertMilestoneValidationGates } from "../milestone-validation-gates.js";
@@ -31,7 +31,10 @@ import { logWarning } from "../workflow-logger.js";
 import { UokGateRunner } from "../uok/gate-runner.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { resolveUokFlags } from "../uok/flags.js";
-import { compactTextParts, hasBrowserEvidenceText, hasBrowserRequiredText } from "../browser-evidence.js";
+import {
+  applyBrowserEvidenceGate,
+  browserEvidenceGateRequiresAttention,
+} from "../milestone-validation-evidence.js";
 
 export interface ValidateMilestoneParams {
   milestoneId: string;
@@ -78,86 +81,6 @@ function getRequiredVerificationClasses(milestoneId: string): string[] {
   return required;
 }
 
-function hasRuntimeExecutableUatEvidenceText(text: string): boolean {
-  if (!/\buatType:\s*runtime-executable\b/i.test(text)) return false;
-  if (!/\bverdict:\s*PASS\b/i.test(text)) return false;
-  return /^\|\s*[^|\n]+\s*\|\s*runtime\s*\|\s*PASS\s*\|[^|\n]*\bgsd_uat_exec\b/mi.test(text);
-}
-
-async function browserEvidenceGateRequiresAttention(
-  params: ValidateMilestoneParams,
-  basePath: string,
-): Promise<boolean> {
-  if (params.verdict !== "pass") return false;
-
-  const milestone = getMilestone(params.milestoneId);
-  const slices = getMilestoneSlices(params.milestoneId);
-  const requirementText = compactTextParts([
-    milestone?.vision,
-    milestone?.success_criteria,
-    milestone?.verification_uat,
-    params.successCriteriaChecklist,
-    params.verificationClasses,
-    ...slices.flatMap((slice) => [
-      slice.demo,
-      slice.goal,
-      slice.success_criteria,
-    ]),
-  ]);
-  if (!hasBrowserRequiredText(requirementText)) return false;
-
-  // Collect per-slice evidence so the runtime bypass is checked independently
-  // for each slice. Concatenating all slices before checking would allow runtime
-  // evidence from one slice to cover another slice's browser requirements.
-  const sliceEvidencePairs: Array<{ sliceRequirementText: string; evidenceText: string }> = [];
-  for (const slice of slices) {
-    const chunks: string[] = [];
-    const artifactPath = `milestones/${params.milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
-    const artifact = getArtifact(artifactPath);
-    if (artifact?.full_content) chunks.push(artifact.full_content);
-    const assessmentPath = resolveSliceFile(basePath, params.milestoneId, slice.id, "ASSESSMENT");
-    const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
-    if (assessmentContent) chunks.push(assessmentContent);
-    sliceEvidencePairs.push({
-      sliceRequirementText: compactTextParts([slice.demo, slice.goal, slice.success_criteria]),
-      evidenceText: chunks.join("\n\n"),
-    });
-  }
-  const persistedEvidence = sliceEvidencePairs.map((s) => s.evidenceText).join("\n\n");
-
-  // Runtime bypass: each slice whose own requirement text has browser-observable
-  // criteria must have its own runtime-executable UAT evidence. When no individual
-  // slice has slice-level browser requirements (e.g., they come from milestone-level
-  // fields only), fall back to checking whether any slice has runtime evidence.
-  const browserRequiringSlices = sliceEvidencePairs.filter((s) =>
-    hasBrowserRequiredText(s.sliceRequirementText),
-  );
-  const runtimeBypasses =
-    browserRequiringSlices.length > 0
-      ? browserRequiringSlices.every((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText))
-      : sliceEvidencePairs.some((s) => hasRuntimeExecutableUatEvidenceText(s.evidenceText));
-  if (runtimeBypasses) return false;
-
-  const validationEvidence = compactTextParts([
-    params.successCriteriaChecklist,
-    params.verificationClasses,
-    params.verdictRationale,
-    params.remediationPlan,
-  ]);
-  return !hasBrowserEvidenceText(`${persistedEvidence}\n\n${validationEvidence}`);
-}
-
-function applyBrowserEvidenceGate(params: ValidateMilestoneParams): ValidateMilestoneParams {
-  const note = "Browser evidence gate: Browser-observable acceptance criteria were detected, but no persisted ASSESSMENT or validation evidence recorded browser actions with assertions. Downgraded from pass to needs-attention.";
-  return {
-    ...params,
-    verdict: "needs-attention",
-    verdictRationale: params.verdictRationale.trim()
-      ? `${params.verdictRationale.trim()}\n\n${note}`
-      : note,
-  };
-}
-
 function renderValidationMarkdown(params: ValidateMilestoneParams): string {
   let md = `---
 verdict: ${params.verdict}
@@ -279,6 +202,24 @@ export async function handleValidateMilestone(
   let projectionStale = false;
   try {
     await saveFile(validationPath, validationMd);
+    const projectRoot = resolveWorktreeProjectRoot(basePath);
+    if (projectRoot !== artifactBasePath) {
+      const projectValidationPath = join(
+        gsdProjectionRoot(projectRoot),
+        "milestones",
+        effectiveParams.milestoneId,
+        `${effectiveParams.milestoneId}-VALIDATION.md`,
+      );
+      try {
+        await saveFile(projectValidationPath, validationMd);
+      } catch (mirrorErr) {
+        logWarning(
+          "projection",
+          `validate_milestone project-root VALIDATION mirror failed for ${effectiveParams.milestoneId}`,
+          { error: (mirrorErr as Error).message },
+        );
+      }
+    }
   } catch (renderErr) {
     projectionStale = true;
     logWarning("projection", `validate_milestone projection write failed for ${effectiveParams.milestoneId}; DB validation remains committed`, {

package/src/resources/extensions/gsd/tools/workflow-tool-executors.ts

@@ -19,9 +19,10 @@ import {
 } from "../gsd-db.js";
 import { GATE_REGISTRY } from "../gate-registry.js";
 import { generateRequirementsMd, saveArtifactToDb } from "../db-writer.js";
-import { clearPathCache, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
+import { clearPathCache, normalizeRealPath, relSliceFile, resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "../paths.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { unlinkSync } from "node:fs";
+import { hostname } from "node:os";
 import { join } from "node:path";
 import type { CompleteMilestoneParams } from "./complete-milestone.js";
 import { handleCompleteMilestone } from "./complete-milestone.js";
@@ -48,13 +49,21 @@ import { logError, logWarning } from "../workflow-logger.js";
 import { invalidateStateCache } from "../state.js";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { parseProject } from "../schemas/parsers.js";
-import { getAutoRuntimeSnapshot } from "../auto-runtime-state.js";
+import { autoSession, getAutoRuntimeSnapshot, isAutoActive } from "../auto-runtime-state.js";
 import { renderPlanFromDb } from "../markdown-renderer.js";
 import {
   prepareUatRun,
   saveUatAttemptArtifact,
   type UatResultSaveParams,
 } from "../uat-run.js";
+import { registerAutoWorker, markWorkerStopping, getAutoWorker } from "../db/auto-workers.js";
+import {
+  claimMilestoneLease,
+  releaseMilestoneLease,
+  getMilestoneLease,
+  refreshMilestoneLease,
+  milestoneLeaseTtlSeconds,
+} from "../db/milestone-leases.js";
 export type {
   UatCheckResultInput,
   UatEvidenceRef,
@@ -105,6 +114,24 @@ function blockIfWrongAutoUnit(requiredUnitType: string, operation: string): Tool
   };
 }
 
+function milestoneLeaseConflictResult(
+  milestoneId: string,
+  byWorker: string,
+  expiresAt: string,
+): ToolExecutionResult {
+  return {
+    content: [{ type: "text", text: `Milestone ${milestoneId} is currently leased by ${byWorker}. Retry after ${expiresAt}.` }],
+    details: {
+      operation: "plan_milestone",
+      error: "milestone_lease_conflict",
+      milestoneId,
+      byWorker,
+      expiresAt,
+    },
+    isError: true,
+  };
+}
+
 export interface SummarySaveParams {
   milestone_id?: string;
   slice_id?: string;
@@ -1244,7 +1271,48 @@ export async function executePlanMilestone(
     isError: true,
       };
   }
+  let workerId: string | null = null;
+  let acquiredToken: number | null = null;
+  let leaseRefreshTimer: ReturnType<typeof setInterval> | undefined;
   try {
+    // Re-read at the gate so a peer-created milestone is not treated as fresh.
+    const milestoneExists = getMilestone(params.milestoneId) !== null;
+    if (milestoneExists) {
+      const heldLease = getMilestoneLease(params.milestoneId);
+      if (heldLease?.status === "held" && Date.parse(heldLease.expires_at) > Date.now()) {
+        const holder = getAutoWorker(heldLease.worker_id);
+        // Let the one-shot claim path recover stale same-process worker rows.
+        const projectRoot = normalizeRealPath(basePath);
+        const isOurAutoLease = isAutoActive() && heldLease.worker_id === autoSession.workerId;
+        const holderIsOneShotReentrantPeer = !isAutoActive()
+          && !!holder
+          && holder.host === hostname()
+          && holder.pid === process.pid
+          && holder.project_root_realpath === projectRoot;
+        if (holder?.status === "active" && !isOurAutoLease && !holderIsOneShotReentrantPeer) {
+          return milestoneLeaseConflictResult(params.milestoneId, heldLease.worker_id, heldLease.expires_at);
+        }
+      }
+    }
+
+    // Fresh creation cannot claim a lease because the FK row does not exist.
+    // In-process auto already owns its lease; re-claiming would bump its token.
+    if (!isAutoActive() && milestoneExists) {
+      workerId = registerAutoWorker({ projectRootRealpath: normalizeRealPath(basePath) });
+      const lease = claimMilestoneLease(workerId, params.milestoneId);
+      if (!lease.ok) {
+        return milestoneLeaseConflictResult(params.milestoneId, lease.byWorker, lease.expiresAt);
+      }
+      acquiredToken = lease.token;
+
+      const leaseRefreshMs = (milestoneLeaseTtlSeconds() / 2) * 1000;
+      leaseRefreshTimer = setInterval(() => {
+        if (acquiredToken !== null && workerId !== null) {
+          refreshMilestoneLease(workerId, params.milestoneId, acquiredToken);
+        }
+      }, leaseRefreshMs);
+    }
+
     const result = await handlePlanMilestone(params, basePath);
     if ("error" in result) {
       return {
@@ -1270,6 +1338,17 @@ export async function executePlanMilestone(
     isError: true,
       };
   }
+  finally {
+    if (leaseRefreshTimer !== undefined) {
+      clearInterval(leaseRefreshTimer);
+    }
+    if (workerId !== null && acquiredToken !== null) {
+      releaseMilestoneLease(workerId, params.milestoneId, acquiredToken);
+    }
+    if (workerId !== null) {
+      markWorkerStopping(workerId);
+    }
+  }
 }
 
 export async function executePlanSlice(