@ricsam/r5d-worker 0.0.107 → 0.0.108

package/README.md

@@ -52,7 +52,7 @@ Worker labels are mandatory and unique per user. Choose labels that describe hos
 
 `r5d-worker start` keeps a lightweight supervisor process attached to the launching terminal or service. When both r5d CLIs are updated from User Settings, the connected runtime verifies the installed versions, exits with a reload signal, and the supervisor reconnects using the new worker package. Updates only run while the worker has no active commands or shells.
 
-The supervisor also reconnects automatically after server rollouts and transient network failures. A brief bounded delay prevents a tight retry loop while the server is unavailable. Pressing Ctrl+C still stops the worker, and agent-managed processes retain their existing in-process recovery path while disconnected.
+The supervisor also reconnects automatically after server rollouts and transient network failures. A brief bounded delay prevents a tight retry loop while the server is unavailable. Pressing Ctrl+C still stops the worker, and agent-managed processes retain their existing in-process recovery path while disconnected. In-process reconnects retain initialized project configurations alongside those processes, so an unchanged checkout can reconnect while a dev server is running. Changed layouts and checkouts that need initialization still wait for active commands to finish.
 
 The runtime opens its control connection before recovering interrupted project snapshots. During recovery and initial project configuration it remains connected but non-dispatchable, reports its current phase plus branch/byte progress to the server, and prints the same progress locally. Recovery runs in a credential-sanitized helper process so the control loop can continue answering heartbeats. A durable `restoring` transaction state permits same-filesystem snapshots to be restored with one atomic directory move; cross-filesystem layouts retain the copy-and-fsync fallback.
 

package/dist/cjs/main.cjs

@@ -56,6 +56,9 @@ __export(main_exports, {
   writeWorkerTextFile: () => writeWorkerTextFile
 });
 module.exports = __toCommonJS(main_exports);
+var import_plan_paths = require("./plan-paths.cjs");
+var import_plan_parser = require("./plan-parser.cjs");
+var import_plan_lint = require("./plan-lint.cjs");
 var import_node_fs = __toESM(require("node:fs"), 1);
 var import_node_path = __toESM(require("node:path"), 1);
 var import_node_crypto = require("node:crypto");
@@ -565,7 +568,7 @@ function targetPlanDir(planRoot, target) {
 function planEnv(activePlanId) {
   const env = {};
   if (activePlanId) {
-    validatePlanId(activePlanId);
+    (0, import_plan_paths.validatePlanId)(activePlanId);
     env.R5D_ACTIVE_PLAN_ID = activePlanId;
   }
   return env;
@@ -834,11 +837,6 @@ function validateProjectId(projectId) {
 function validateBranchName(branchName) {
   (0, import_managed_paths.validateManagedBranchName)(branchName);
 }
-function validatePlanId(planId) {
-  if (!/^[a-z0-9][a-z0-9-]*$/.test(planId)) {
-    throw new Error(`Invalid plan id from server: ${planId}`);
-  }
-}
 const NON_RECURSIVE_GIT_CONFIG_ARGS = [
   "-c",
   "submodule.recurse=false",
@@ -1745,6 +1743,7 @@ const workerGitSecurityTestHarness = {
   workspaceSyncFailureHydrationIsSafe,
   assertWorkerChildAdmission,
   executeWriteFileOperation,
+  executeOperation,
   executeEditFileOperation,
   terminateCredentialBearingChildren,
   terminateCredentialBearingChildrenWithRetention,
@@ -2183,6 +2182,55 @@ function editWorkerTextFile(branchPath, filePath, edits, builtInPaths) {
     edits: edits.length
   };
 }
+async function executePlanOperation(input) {
+  const { message, resolvedTarget } = input;
+  const filePath = message.type === "lint_plans" ? (0, import_plan_paths.getWorkerPlansPath)(resolvedTarget.target) : (0, import_plan_paths.getWorkerPlanPath)(resolvedTarget.target, message.planId);
+  const builtInPaths = await prepareBuiltInToolPathsForTarget({
+    target: resolvedTarget.target,
+    filePath,
+    baseUrl: input.baseUrl,
+    token: input.token,
+    rootDir: input.rootDir,
+    sessionId: message.sessionId,
+    access: message.type === "update_task_status" || message.type === "read_plan" && message.createIfMissing ? "write" : "read"
+  });
+  const resolved = resolveWorkerFilePath(resolvedTarget.rootPath, filePath, builtInPaths);
+  if (message.type === "lint_plans") {
+    const result = await (0, import_plan_lint.lintPlans)(resolved.absolutePath, message.glob);
+    return {
+      type: "lint_plans",
+      content: result.lintedPlanCount === 0 ? message.glob ? `No plan files matched glob "${message.glob}".` : "No plan files found." : (0, import_plan_lint.formatPlanLintErrors)(result.errors) || "No plan lint issues found."
+    };
+  }
+  return withFileMutationQueue(mutationQueueKey(resolvedTarget.target, resolved), async () => {
+    input.assertAdmission();
+    if (message.type === "read_plan") {
+      let created = false;
+      if (message.createIfMissing) {
+        try {
+          import_node_fs.default.writeFileSync(resolved.absolutePath, (0, import_plan_parser.createPlanMarkdown)(message.planId), { encoding: "utf8", flag: "wx" });
+          created = true;
+        } catch (error) {
+          if (error.code !== "EEXIST") throw error;
+        }
+      }
+      return {
+        type: "read_plan",
+        created,
+        read: readWorkerTextFile(resolvedTarget.rootPath, filePath, void 0, void 0, builtInPaths)
+      };
+    }
+    const content = import_node_fs.default.readFileSync(resolved.absolutePath, "utf8");
+    writeWorkerTextFile(resolvedTarget.rootPath, filePath, (0, import_plan_parser.updateTaskCheckbox)(content, message.taskId, message.checked), builtInPaths);
+    return {
+      type: "update_task_status",
+      planId: message.planId,
+      taskId: message.taskId,
+      checked: message.checked,
+      message: `Task ${message.taskId} marked ${message.checked ? "complete" : "incomplete"}.`
+    };
+  });
+}
 async function executeReadFileOperation(input) {
   const builtInPaths = await prepareBuiltInToolPathsForTarget({
     target: input.resolvedTarget.target,
@@ -2561,6 +2609,10 @@ async function executeViewFileBytesOperation(input) {
 }
 async function executeOperation(input) {
   switch (input.message.type) {
+    case "read_plan":
+    case "lint_plans":
+    case "update_task_status":
+      return executePlanOperation({ ...input, message: input.message });
     case "read":
       return executeReadFileOperation({ ...input, message: input.message });
     case "write":
@@ -3420,7 +3472,12 @@ function websocketUrl(baseUrl, label) {
   url.searchParams.set("version", getWorkerVersion());
   return url.toString();
 }
-async function startWorker(options) {
+async function startWorker(options, projectRuntime = {
+  projectConfigById: /* @__PURE__ */ new Map(),
+  readyProjectIds: /* @__PURE__ */ new Set(),
+  reconciledProjectConfigFingerprints: /* @__PURE__ */ new Map(),
+  gitIdentity: null
+}) {
   advanceWorkerAdmissionGeneration();
   const config = readConfig(options.configPath);
   const { baseUrl, token } = resolveCredentials(options, config);
@@ -3461,10 +3518,8 @@ async function startWorker(options) {
   });
   const projectWorkspaceStateStore = initializedWorkspaceState.store;
   let projectWorkspaceState = initializedWorkspaceState.state;
-  const projectConfigById = /* @__PURE__ */ new Map();
+  const { projectConfigById, readyProjectIds, reconciledProjectConfigFingerprints } = projectRuntime;
   const pendingCheckouts = /* @__PURE__ */ new Map();
-  const readyProjectIds = /* @__PURE__ */ new Set();
-  const reconciledProjectConfigFingerprints = /* @__PURE__ */ new Map();
   const lastObservedProjectHeads = /* @__PURE__ */ new Map();
   const advertisedProjectMirrorRefsTokens = /* @__PURE__ */ new Map();
   const advertisedProjectMirrorMountTokens = /* @__PURE__ */ new Map();
@@ -3494,7 +3549,7 @@ async function startWorker(options) {
   let workspaceRemoteUrl = null;
   let workspaceCredentialHelper = null;
   let workspaceCredentialUsername = null;
-  let workspaceGitIdentity = null;
+  let workspaceGitIdentity = projectRuntime.gitIdentity;
   let workspaceConfigured = false;
   let activeWorkspaceIncidentId = null;
   let deferredWorkspaceConfiguration = null;
@@ -3855,7 +3910,9 @@ async function startWorker(options) {
   const reportedMissingCheckouts = (inventory) => inventory.missingCheckouts.map(({ projectId, branchName, reason }) => ({ projectId, branchName, reason }));
   const logMissingCheckouts = (inventory) => {
     if (inventory.missingCheckouts.length === 0) return;
-    const described = inventory.missingCheckouts.map(({ checkoutPath, reason }) => `${checkoutPath} (${reason === "missing" ? "directory missing" : "not a linked worktree of the project"})`).join(", ");
+    const described = inventory.missingCheckouts.map(
+      ({ checkoutPath, reason }) => `${checkoutPath} (${reason === "missing" ? "directory missing" : "not a linked worktree of the project"})`
+    ).join(", ");
     process.stderr.write(
       `[r5d-worker] skipping ${inventory.missingCheckouts.length} configured project checkout(s) this cycle: ${described}; delete the branch through the platform or reconnect this worker to recreate the checkout
 `
@@ -4426,7 +4483,9 @@ async function startWorker(options) {
       error: error instanceof Error ? error.message : String(error)
     };
   };
-  const workspaceHydrationTransactionHooks = createWorkspaceHydrationLeaseHooks((message) => sendWorkerMessageFromCurrentSource(ws, message));
+  const workspaceHydrationTransactionHooks = createWorkspaceHydrationLeaseHooks(
+    (message) => sendWorkerMessageFromCurrentSource(ws, message)
+  );
   const performWorkspaceSync = async (input) => {
     if (!workspaceRemoteUrl || !workspaceCredentialHelper || !workspaceCredentialUsername || !workspaceGitIdentity) {
       throw new Error("Worker workspace configuration has not been received");
@@ -4483,7 +4542,11 @@ async function startWorker(options) {
     const outerRemediation = input.trigger.type === "remediation" || input.trigger.type === "remediation_confirm";
     const mounts = outerRemediation ? (0, import_workspace_git_sync.workspaceGitMountsForRemediation)(configuredMounts) : configuredMounts;
     if (outerRemediation) workspaceProjectionLedger.reset();
-    const observedProjectHeads = outerRemediation ? [] : await observeProjectHeadsBeforeOuterWorkspace({ allowNonFastForward: false, failClosed: false, projects: checkoutInventory.projects });
+    const observedProjectHeads = outerRemediation ? [] : await observeProjectHeadsBeforeOuterWorkspace({
+      allowNonFastForward: false,
+      failClosed: false,
+      projects: checkoutInventory.projects
+    });
     const expectedMirrorHeads = /* @__PURE__ */ new Map();
     for (const bundle of observedProjectHeads) {
       for (const observation of bundle.observations) {
@@ -4672,7 +4735,11 @@ async function startWorker(options) {
       };
     }
   };
-  const REMEDIATION_TRIGGER_TYPES = /* @__PURE__ */ new Set(["remediation", "remediation_confirm", "remediation_reset"]);
+  const REMEDIATION_TRIGGER_TYPES = /* @__PURE__ */ new Set([
+    "remediation",
+    "remediation_confirm",
+    "remediation_reset"
+  ]);
   const isOrdinaryWorkspaceSyncRequest = (input) => input.confirmedLargeDiff !== true && input.resetToCanonical !== true && !(input.requiredAncestorHeads && input.requiredAncestorHeads.length > 0) && !REMEDIATION_TRIGGER_TYPES.has(input.trigger.type);
   const LOCAL_ACTIVITY_TRIGGER_TYPES = /* @__PURE__ */ new Set([
     "write",
@@ -4713,7 +4780,14 @@ async function startWorker(options) {
         trigger: leader.trigger,
         assertStillAdmitted: () => assertWorkspaceSyncStillAdmitted(admission, leader.trigger)
       });
-      return { result, ranCycle: true, startedAtMs, finishedAtMs: Date.now(), prepareMs: lastWorkspaceSyncMirrorObservationMs, staleAttemptIds };
+      return {
+        result,
+        ranCycle: true,
+        startedAtMs,
+        finishedAtMs: Date.now(),
+        prepareMs: lastWorkspaceSyncMirrorObservationMs,
+        staleAttemptIds
+      };
     }
   });
   const runWorkspaceSync = async (input) => {
@@ -5145,6 +5219,7 @@ async function startWorker(options) {
         bootstrapCredentialGenerationFingerprintAtProcessStart = null;
         visibleGitIdentity = message.gitIdentity;
         workspaceGitIdentity = message.gitIdentity;
+        projectRuntime.gitIdentity = message.gitIdentity;
         workspaceRemoteUrl = message.workspaceRemoteUrl;
         workspaceCredentialHelper = nextWorkspaceCredentialHelper;
         workspaceCredentialUsername = workerCredentialUsername;
@@ -6285,7 +6360,7 @@ async function startWorker(options) {
         });
         return;
       }
-      if (message.type === "read" || message.type === "write" || message.type === "edit" || message.type === "grep" || message.type === "find" || message.type === "ls" || message.type === "view_file_bytes" || message.type === "code_list" || message.type === "code_read") {
+      if (message.type === "read_plan" || message.type === "lint_plans" || message.type === "update_task_status" || message.type === "read" || message.type === "write" || message.type === "edit" || message.type === "grep" || message.type === "find" || message.type === "ls" || message.type === "view_file_bytes" || message.type === "code_list" || message.type === "code_read") {
         if (workspaceOperationsAreFenced(deferredWorkspaceConfiguration, activeWorkspaceIncidentId)) {
           sendWorkerMessage(ws, {
             type: "operation_result",
@@ -6295,7 +6370,7 @@ async function startWorker(options) {
           return;
         }
         const reservesVisibleWorkspace = targetMayMutateVisibleWorkspace(message.target);
-        const mutatesVisibleWorkspace = (message.type === "write" || message.type === "edit") && targetMayMutateVisibleWorkspace(message.target);
+        const mutatesVisibleWorkspace = (message.type === "write" || message.type === "edit" || message.type === "update_task_status" || message.type === "read_plan" && message.createIfMissing) && targetMayMutateVisibleWorkspace(message.target);
         if (reservesVisibleWorkspace) {
           await (0, import_workspace_command_sync_policy.reserveWorkspaceCommandAfterCurrentSync)(message.target, workspaceSyncSingleFlight, () => {
             workspaceSyncPriorityOperationTargets.set(message.requestId, message.target);
@@ -6322,9 +6397,9 @@ async function startWorker(options) {
               result
             })
           );
-          if (mutatesVisibleWorkspace) {
+          if (mutatesVisibleWorkspace && (result.type !== "read_plan" || result.created)) {
             dirtyTrigger = {
-              type: message.type,
+              type: message.type === "edit" || message.type === "update_task_status" ? "edit" : "write",
               sessionId: message.sessionId,
               toolCallId: message.requestId,
               ...message.target.type === "project" ? { projectId: message.target.projectId, branchName: message.target.branchName } : {}
@@ -6410,7 +6485,7 @@ async function startWorker(options) {
         process.stderr.write(`[r5d-worker] workspace recovery complete; reconnecting in ${reconnectDelayMs}ms
 `);
         setTimeout(() => {
-          void startWorker(options).catch((error) => {
+          void startWorker(options, projectRuntime).catch((error) => {
             process.stderr.write(`[r5d-worker] reconnect failed: ${error instanceof Error ? error.message : String(error)}
 `);
             process.exit(error instanceof WorkerServerUnavailableError ? import_supervisor.WORKER_RECONNECT_EXIT_CODE : 1);
@@ -6429,7 +6504,7 @@ async function startWorker(options) {
         setTimeout(reconnect2, reconnectDelayMs);
       };
       const reconnect = () => {
-        void startWorker(options).catch((error) => {
+        void startWorker(options, projectRuntime).catch((error) => {
           process.stderr.write(`[r5d-worker] reconnect failed: ${error instanceof Error ? error.message : String(error)}
 `);
           if (activeProcesses.size > 0 || credentialBearingProcessGroups.size > 0 || activePtys.size > 0 || pendingProcessTerminals.size > 0) {

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.107",
+  "version": "0.0.108",
   "type": "commonjs"
 }

package/dist/cjs/plan-lint.cjs

@@ -0,0 +1,165 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var plan_lint_exports = {};
+__export(plan_lint_exports, {
+  formatPlanLintErrors: () => formatPlanLintErrors,
+  lintPlanContent: () => lintPlanContent,
+  lintPlans: () => lintPlans
+});
+module.exports = __toCommonJS(plan_lint_exports);
+var import_promises = __toESM(require("node:fs/promises"), 1);
+var import_node_path = __toESM(require("node:path"), 1);
+var import_picomatch = __toESM(require("picomatch"), 1);
+var import_plan_parser = require("./plan-parser.cjs");
+var import_plan_paths = require("./plan-paths.cjs");
+var import_plan_parser2 = require("./plan-parser.cjs");
+const LEGACY_SCHEMA_FIELD_REGEX = /^\s*(type|status|parent|phase|discovered_problem)\s*:/m;
+function lintPlanContent(planId, content) {
+  const errors = [];
+  const lines = content.split(/\r?\n/);
+  if (/^---(?:\r?\n|$)/.test(content)) {
+    errors.push({
+      planId,
+      severity: "error",
+      message: "YAML frontmatter is not supported. Use plain Markdown with a ## Tasks checklist.",
+      line: 1
+    });
+  }
+  if (LEGACY_SCHEMA_FIELD_REGEX.test(content)) {
+    errors.push({
+      planId,
+      severity: "error",
+      message: "Legacy plan schema fields are not supported. Remove type/status/parent/phase/discovered_problem metadata."
+    });
+  }
+  const titleLineIndex = lines.findIndex((line) => /^# .+\S\s*$/.test(line));
+  if (titleLineIndex === -1) {
+    errors.push({
+      planId,
+      severity: "error",
+      message: "Plan must start with or contain an H1 title, for example '# Implementation Plan'."
+    });
+  }
+  const range = (0, import_plan_parser.getTasksSectionRange)(content);
+  if (!range) {
+    errors.push({
+      planId,
+      severity: "error",
+      message: "Plan is missing a ## Tasks section."
+    });
+    return errors;
+  }
+  const taskIds = /* @__PURE__ */ new Set();
+  let taskCount = 0;
+  for (let index = range.startIndex + 1; index < range.endIndex; index += 1) {
+    const line = lines[index] ?? "";
+    if (line.trim() === "") continue;
+    const match = line.match(import_plan_parser.PLAN_TASK_LINE_REGEX);
+    if (!match || !match[3].trim()) {
+      errors.push({
+        planId,
+        severity: "error",
+        line: index + 1,
+        message: 'Malformed task line. Use "- [ ] task-id: Description" or "- [x] task-id: Description".'
+      });
+      continue;
+    }
+    taskCount += 1;
+    const taskId = match[2];
+    if (taskIds.has(taskId)) {
+      errors.push({
+        planId,
+        severity: "error",
+        line: index + 1,
+        message: `Duplicate task id "${taskId}".`
+      });
+    }
+    taskIds.add(taskId);
+  }
+  if (taskCount === 0) {
+    errors.push({
+      planId,
+      severity: "error",
+      message: "Plan must include at least one task in the ## Tasks section.",
+      line: range.startIndex + 1
+    });
+  }
+  return errors;
+}
+async function lintPlans(plansDir, glob) {
+  const errors = [];
+  let entries;
+  try {
+    entries = await import_promises.default.readdir(plansDir, { withFileTypes: true });
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    entries = [];
+  }
+  const matches = glob ? (0, import_picomatch.default)(glob) : null;
+  let lintedPlanCount = 0;
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(import_plan_paths.PLAN_EXTENSION)) continue;
+    const planId = entry.name.slice(0, -import_plan_paths.PLAN_EXTENSION.length);
+    if (!import_plan_parser2.PLAN_TASK_ID_REGEX.test(planId) || matches && !matches(entry.name) && !matches(planId)) continue;
+    const content = await import_promises.default.readFile(import_node_path.default.join(plansDir, entry.name), "utf8");
+    lintedPlanCount += 1;
+    errors.push(...lintPlanContent(planId, content));
+  }
+  return {
+    type: "plan_lint",
+    errors,
+    errorCount: errors.filter((error) => error.severity === "error").length,
+    warningCount: errors.filter((error) => error.severity === "warning").length,
+    lintedPlanCount
+  };
+}
+function formatPlanLintErrors(errors) {
+  if (errors.length === 0) return "";
+  const lines = ["## Plan Lint Errors", ""];
+  const byPlan = /* @__PURE__ */ new Map();
+  for (const error of errors) {
+    byPlan.set(error.planId, [...byPlan.get(error.planId) ?? [], error]);
+  }
+  for (const [planId, planErrors] of byPlan) {
+    lines.push(`### ${planId}.plan.md`);
+    for (const error of planErrors) {
+      const location = error.line ? ` line ${error.line}` : "";
+      lines.push(`- ${error.severity.toUpperCase()}${location}: ${error.message}`);
+    }
+    lines.push("");
+  }
+  lines.push("Fix these issues by editing the Markdown plan file.");
+  return lines.join("\n");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  formatPlanLintErrors,
+  lintPlanContent,
+  lintPlans
+});

package/dist/cjs/plan-parser.cjs

@@ -0,0 +1,127 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var plan_parser_exports = {};
+__export(plan_parser_exports, {
+  PLAN_TASKS_HEADING_REGEX: () => PLAN_TASKS_HEADING_REGEX,
+  PLAN_TASK_ID_REGEX: () => PLAN_TASK_ID_REGEX,
+  PLAN_TASK_LINE_REGEX: () => PLAN_TASK_LINE_REGEX,
+  createPlanMarkdown: () => createPlanMarkdown,
+  formatPlanTitle: () => formatPlanTitle,
+  getPlanMetadata: () => getPlanMetadata,
+  getTasksSectionRange: () => getTasksSectionRange,
+  parseMarkdownPlan: () => parseMarkdownPlan,
+  parsePlan: () => parsePlan,
+  updateTaskCheckbox: () => updateTaskCheckbox
+});
+module.exports = __toCommonJS(plan_parser_exports);
+const PLAN_TASK_ID_REGEX = /^[a-z0-9][a-z0-9-]*$/;
+const PLAN_TASK_LINE_REGEX = /^- \[( |x)\] ([a-z0-9][a-z0-9-]*): (.+)$/;
+const PLAN_TASKS_HEADING_REGEX = /^## Tasks\s*$/;
+function getPlanMetadata(content) {
+  const title = content.split(/\r?\n/).map((line) => line.match(/^# (.+)$/)?.[1]?.trim()).find((value) => Boolean(value));
+  return { title: title || "Untitled Plan" };
+}
+function getTasksSectionRange(content) {
+  const lines = content.split(/\r?\n/);
+  const startIndex = lines.findIndex((line) => PLAN_TASKS_HEADING_REGEX.test(line));
+  if (startIndex === -1) return null;
+  let endIndex = lines.length;
+  for (let index = startIndex + 1; index < lines.length; index += 1) {
+    if (/^##\s+/.test(lines[index] ?? "")) {
+      endIndex = index;
+      break;
+    }
+  }
+  return { startIndex, endIndex };
+}
+function parseMarkdownPlan(content, planId) {
+  const lines = content.split(/\r?\n/);
+  const { title } = getPlanMetadata(content);
+  const range = getTasksSectionRange(content);
+  const tasks = [];
+  if (range) {
+    for (let index = range.startIndex + 1; index < range.endIndex; index += 1) {
+      const line = lines[index] ?? "";
+      const match = line.match(PLAN_TASK_LINE_REGEX);
+      if (!match) continue;
+      const description = match[3].trim();
+      if (!description) continue;
+      tasks.push({
+        id: match[2],
+        description,
+        checked: match[1] === "x",
+        lineNumber: index + 1
+      });
+    }
+  }
+  const currentTask = tasks.find((task) => !task.checked) ?? null;
+  return {
+    id: planId,
+    title,
+    content,
+    tasks,
+    currentTask,
+    complete: tasks.length > 0 && tasks.every((task) => task.checked),
+    tasksStartLine: range ? range.startIndex + 1 : null,
+    tasksEndLine: range ? range.endIndex : null
+  };
+}
+const parsePlan = parseMarkdownPlan;
+function createPlanMarkdown(planId, title = formatPlanTitle(planId)) {
+  return `# ${title}
+
+Brief implementation notes.
+
+## Tasks
+`;
+}
+function updateTaskCheckbox(content, taskId, checked) {
+  if (!PLAN_TASK_ID_REGEX.test(taskId)) {
+    throw new Error(`Invalid task id: ${taskId}`);
+  }
+  const lines = content.split(/\r?\n/);
+  const range = getTasksSectionRange(content);
+  if (!range) {
+    throw new Error("Plan is missing a ## Tasks section.");
+  }
+  for (let index = range.startIndex + 1; index < range.endIndex; index += 1) {
+    const line = lines[index] ?? "";
+    const match = line.match(PLAN_TASK_LINE_REGEX);
+    if (!match || match[2] !== taskId) continue;
+    lines[index] = `- [${checked ? "x" : " "}] ${match[2]}: ${match[3].trim()}`;
+    return lines.join("\n");
+  }
+  throw new Error(`Task not found in plan: ${taskId}`);
+}
+function formatPlanTitle(planId) {
+  return planId.split("-").filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PLAN_TASKS_HEADING_REGEX,
+  PLAN_TASK_ID_REGEX,
+  PLAN_TASK_LINE_REGEX,
+  createPlanMarkdown,
+  formatPlanTitle,
+  getPlanMetadata,
+  getTasksSectionRange,
+  parseMarkdownPlan,
+  parsePlan,
+  updateTaskCheckbox
+});

package/dist/cjs/plan-paths.cjs

@@ -0,0 +1,53 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var plan_paths_exports = {};
+__export(plan_paths_exports, {
+  PLAN_EXTENSION: () => PLAN_EXTENSION,
+  assertPlanTarget: () => assertPlanTarget,
+  getWorkerPlanPath: () => getWorkerPlanPath,
+  getWorkerPlansPath: () => getWorkerPlansPath,
+  validatePlanId: () => validatePlanId
+});
+module.exports = __toCommonJS(plan_paths_exports);
+var import_plan_parser = require("./plan-parser.cjs");
+const PLAN_EXTENSION = ".plan.md";
+function validatePlanId(planId) {
+  if (!import_plan_parser.PLAN_TASK_ID_REGEX.test(planId)) throw new Error(`Invalid plan id: ${planId}`);
+}
+function assertPlanTarget(target) {
+  if (target.type === "workspace" && target.rootProfile !== "visible_projects") {
+    throw new Error("Ordinary plans are unavailable in canonical synchronization sessions");
+  }
+}
+function getWorkerPlansPath(target) {
+  assertPlanTarget(target);
+  return target.type === "project" ? "$R5D_ROOT/plans/$R5D_PROJECT_ID/$R5D_BRANCH_NAME" : "$R5D_ROOT/plans/workspace";
+}
+function getWorkerPlanPath(target, planId) {
+  validatePlanId(planId);
+  return `${getWorkerPlansPath(target)}/${planId}${PLAN_EXTENSION}`;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PLAN_EXTENSION,
+  assertPlanTarget,
+  getWorkerPlanPath,
+  getWorkerPlansPath,
+  validatePlanId
+});

package/dist/mjs/main.mjs

@@ -1,4 +1,7 @@
 #!/usr/bin/env bun
+import { getWorkerPlanPath, getWorkerPlansPath, validatePlanId } from "./plan-paths.mjs";
+import { createPlanMarkdown, updateTaskCheckbox } from "./plan-parser.mjs";
+import { lintPlans, formatPlanLintErrors } from "./plan-lint.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
@@ -845,11 +848,6 @@ function validateProjectId(projectId) {
 function validateBranchName(branchName) {
   validateManagedBranchName(branchName);
 }
-function validatePlanId(planId) {
-  if (!/^[a-z0-9][a-z0-9-]*$/.test(planId)) {
-    throw new Error(`Invalid plan id from server: ${planId}`);
-  }
-}
 const NON_RECURSIVE_GIT_CONFIG_ARGS = [
   "-c",
   "submodule.recurse=false",
@@ -1756,6 +1754,7 @@ const workerGitSecurityTestHarness = {
   workspaceSyncFailureHydrationIsSafe,
   assertWorkerChildAdmission,
   executeWriteFileOperation,
+  executeOperation,
   executeEditFileOperation,
   terminateCredentialBearingChildren,
   terminateCredentialBearingChildrenWithRetention,
@@ -2194,6 +2193,55 @@ function editWorkerTextFile(branchPath, filePath, edits, builtInPaths) {
     edits: edits.length
   };
 }
+async function executePlanOperation(input) {
+  const { message, resolvedTarget } = input;
+  const filePath = message.type === "lint_plans" ? getWorkerPlansPath(resolvedTarget.target) : getWorkerPlanPath(resolvedTarget.target, message.planId);
+  const builtInPaths = await prepareBuiltInToolPathsForTarget({
+    target: resolvedTarget.target,
+    filePath,
+    baseUrl: input.baseUrl,
+    token: input.token,
+    rootDir: input.rootDir,
+    sessionId: message.sessionId,
+    access: message.type === "update_task_status" || message.type === "read_plan" && message.createIfMissing ? "write" : "read"
+  });
+  const resolved = resolveWorkerFilePath(resolvedTarget.rootPath, filePath, builtInPaths);
+  if (message.type === "lint_plans") {
+    const result = await lintPlans(resolved.absolutePath, message.glob);
+    return {
+      type: "lint_plans",
+      content: result.lintedPlanCount === 0 ? message.glob ? `No plan files matched glob "${message.glob}".` : "No plan files found." : formatPlanLintErrors(result.errors) || "No plan lint issues found."
+    };
+  }
+  return withFileMutationQueue(mutationQueueKey(resolvedTarget.target, resolved), async () => {
+    input.assertAdmission();
+    if (message.type === "read_plan") {
+      let created = false;
+      if (message.createIfMissing) {
+        try {
+          fs.writeFileSync(resolved.absolutePath, createPlanMarkdown(message.planId), { encoding: "utf8", flag: "wx" });
+          created = true;
+        } catch (error) {
+          if (error.code !== "EEXIST") throw error;
+        }
+      }
+      return {
+        type: "read_plan",
+        created,
+        read: readWorkerTextFile(resolvedTarget.rootPath, filePath, void 0, void 0, builtInPaths)
+      };
+    }
+    const content = fs.readFileSync(resolved.absolutePath, "utf8");
+    writeWorkerTextFile(resolvedTarget.rootPath, filePath, updateTaskCheckbox(content, message.taskId, message.checked), builtInPaths);
+    return {
+      type: "update_task_status",
+      planId: message.planId,
+      taskId: message.taskId,
+      checked: message.checked,
+      message: `Task ${message.taskId} marked ${message.checked ? "complete" : "incomplete"}.`
+    };
+  });
+}
 async function executeReadFileOperation(input) {
   const builtInPaths = await prepareBuiltInToolPathsForTarget({
     target: input.resolvedTarget.target,
@@ -2572,6 +2620,10 @@ async function executeViewFileBytesOperation(input) {
 }
 async function executeOperation(input) {
   switch (input.message.type) {
+    case "read_plan":
+    case "lint_plans":
+    case "update_task_status":
+      return executePlanOperation({ ...input, message: input.message });
     case "read":
       return executeReadFileOperation({ ...input, message: input.message });
     case "write":
@@ -3431,7 +3483,12 @@ function websocketUrl(baseUrl, label) {
   url.searchParams.set("version", getWorkerVersion());
   return url.toString();
 }
-async function startWorker(options) {
+async function startWorker(options, projectRuntime = {
+  projectConfigById: /* @__PURE__ */ new Map(),
+  readyProjectIds: /* @__PURE__ */ new Set(),
+  reconciledProjectConfigFingerprints: /* @__PURE__ */ new Map(),
+  gitIdentity: null
+}) {
   advanceWorkerAdmissionGeneration();
   const config = readConfig(options.configPath);
   const { baseUrl, token } = resolveCredentials(options, config);
@@ -3472,10 +3529,8 @@ async function startWorker(options) {
   });
   const projectWorkspaceStateStore = initializedWorkspaceState.store;
   let projectWorkspaceState = initializedWorkspaceState.state;
-  const projectConfigById = /* @__PURE__ */ new Map();
+  const { projectConfigById, readyProjectIds, reconciledProjectConfigFingerprints } = projectRuntime;
   const pendingCheckouts = /* @__PURE__ */ new Map();
-  const readyProjectIds = /* @__PURE__ */ new Set();
-  const reconciledProjectConfigFingerprints = /* @__PURE__ */ new Map();
   const lastObservedProjectHeads = /* @__PURE__ */ new Map();
   const advertisedProjectMirrorRefsTokens = /* @__PURE__ */ new Map();
   const advertisedProjectMirrorMountTokens = /* @__PURE__ */ new Map();
@@ -3505,7 +3560,7 @@ async function startWorker(options) {
   let workspaceRemoteUrl = null;
   let workspaceCredentialHelper = null;
   let workspaceCredentialUsername = null;
-  let workspaceGitIdentity = null;
+  let workspaceGitIdentity = projectRuntime.gitIdentity;
   let workspaceConfigured = false;
   let activeWorkspaceIncidentId = null;
   let deferredWorkspaceConfiguration = null;
@@ -3866,7 +3921,9 @@ async function startWorker(options) {
   const reportedMissingCheckouts = (inventory) => inventory.missingCheckouts.map(({ projectId, branchName, reason }) => ({ projectId, branchName, reason }));
   const logMissingCheckouts = (inventory) => {
     if (inventory.missingCheckouts.length === 0) return;
-    const described = inventory.missingCheckouts.map(({ checkoutPath, reason }) => `${checkoutPath} (${reason === "missing" ? "directory missing" : "not a linked worktree of the project"})`).join(", ");
+    const described = inventory.missingCheckouts.map(
+      ({ checkoutPath, reason }) => `${checkoutPath} (${reason === "missing" ? "directory missing" : "not a linked worktree of the project"})`
+    ).join(", ");
     process.stderr.write(
       `[r5d-worker] skipping ${inventory.missingCheckouts.length} configured project checkout(s) this cycle: ${described}; delete the branch through the platform or reconnect this worker to recreate the checkout
 `
@@ -4437,7 +4494,9 @@ async function startWorker(options) {
       error: error instanceof Error ? error.message : String(error)
     };
   };
-  const workspaceHydrationTransactionHooks = createWorkspaceHydrationLeaseHooks((message) => sendWorkerMessageFromCurrentSource(ws, message));
+  const workspaceHydrationTransactionHooks = createWorkspaceHydrationLeaseHooks(
+    (message) => sendWorkerMessageFromCurrentSource(ws, message)
+  );
   const performWorkspaceSync = async (input) => {
     if (!workspaceRemoteUrl || !workspaceCredentialHelper || !workspaceCredentialUsername || !workspaceGitIdentity) {
       throw new Error("Worker workspace configuration has not been received");
@@ -4494,7 +4553,11 @@ async function startWorker(options) {
     const outerRemediation = input.trigger.type === "remediation" || input.trigger.type === "remediation_confirm";
     const mounts = outerRemediation ? workspaceGitMountsForRemediation(configuredMounts) : configuredMounts;
     if (outerRemediation) workspaceProjectionLedger.reset();
-    const observedProjectHeads = outerRemediation ? [] : await observeProjectHeadsBeforeOuterWorkspace({ allowNonFastForward: false, failClosed: false, projects: checkoutInventory.projects });
+    const observedProjectHeads = outerRemediation ? [] : await observeProjectHeadsBeforeOuterWorkspace({
+      allowNonFastForward: false,
+      failClosed: false,
+      projects: checkoutInventory.projects
+    });
     const expectedMirrorHeads = /* @__PURE__ */ new Map();
     for (const bundle of observedProjectHeads) {
       for (const observation of bundle.observations) {
@@ -4683,7 +4746,11 @@ async function startWorker(options) {
       };
     }
   };
-  const REMEDIATION_TRIGGER_TYPES = /* @__PURE__ */ new Set(["remediation", "remediation_confirm", "remediation_reset"]);
+  const REMEDIATION_TRIGGER_TYPES = /* @__PURE__ */ new Set([
+    "remediation",
+    "remediation_confirm",
+    "remediation_reset"
+  ]);
   const isOrdinaryWorkspaceSyncRequest = (input) => input.confirmedLargeDiff !== true && input.resetToCanonical !== true && !(input.requiredAncestorHeads && input.requiredAncestorHeads.length > 0) && !REMEDIATION_TRIGGER_TYPES.has(input.trigger.type);
   const LOCAL_ACTIVITY_TRIGGER_TYPES = /* @__PURE__ */ new Set([
     "write",
@@ -4724,7 +4791,14 @@ async function startWorker(options) {
         trigger: leader.trigger,
         assertStillAdmitted: () => assertWorkspaceSyncStillAdmitted(admission, leader.trigger)
       });
-      return { result, ranCycle: true, startedAtMs, finishedAtMs: Date.now(), prepareMs: lastWorkspaceSyncMirrorObservationMs, staleAttemptIds };
+      return {
+        result,
+        ranCycle: true,
+        startedAtMs,
+        finishedAtMs: Date.now(),
+        prepareMs: lastWorkspaceSyncMirrorObservationMs,
+        staleAttemptIds
+      };
     }
   });
   const runWorkspaceSync = async (input) => {
@@ -5156,6 +5230,7 @@ async function startWorker(options) {
         bootstrapCredentialGenerationFingerprintAtProcessStart = null;
         visibleGitIdentity = message.gitIdentity;
         workspaceGitIdentity = message.gitIdentity;
+        projectRuntime.gitIdentity = message.gitIdentity;
         workspaceRemoteUrl = message.workspaceRemoteUrl;
         workspaceCredentialHelper = nextWorkspaceCredentialHelper;
         workspaceCredentialUsername = workerCredentialUsername;
@@ -6296,7 +6371,7 @@ async function startWorker(options) {
         });
         return;
       }
-      if (message.type === "read" || message.type === "write" || message.type === "edit" || message.type === "grep" || message.type === "find" || message.type === "ls" || message.type === "view_file_bytes" || message.type === "code_list" || message.type === "code_read") {
+      if (message.type === "read_plan" || message.type === "lint_plans" || message.type === "update_task_status" || message.type === "read" || message.type === "write" || message.type === "edit" || message.type === "grep" || message.type === "find" || message.type === "ls" || message.type === "view_file_bytes" || message.type === "code_list" || message.type === "code_read") {
         if (workspaceOperationsAreFenced(deferredWorkspaceConfiguration, activeWorkspaceIncidentId)) {
           sendWorkerMessage(ws, {
             type: "operation_result",
@@ -6306,7 +6381,7 @@ async function startWorker(options) {
           return;
         }
         const reservesVisibleWorkspace = targetMayMutateVisibleWorkspace(message.target);
-        const mutatesVisibleWorkspace = (message.type === "write" || message.type === "edit") && targetMayMutateVisibleWorkspace(message.target);
+        const mutatesVisibleWorkspace = (message.type === "write" || message.type === "edit" || message.type === "update_task_status" || message.type === "read_plan" && message.createIfMissing) && targetMayMutateVisibleWorkspace(message.target);
         if (reservesVisibleWorkspace) {
           await reserveWorkspaceCommandAfterCurrentSync(message.target, workspaceSyncSingleFlight, () => {
             workspaceSyncPriorityOperationTargets.set(message.requestId, message.target);
@@ -6333,9 +6408,9 @@ async function startWorker(options) {
               result
             })
           );
-          if (mutatesVisibleWorkspace) {
+          if (mutatesVisibleWorkspace && (result.type !== "read_plan" || result.created)) {
             dirtyTrigger = {
-              type: message.type,
+              type: message.type === "edit" || message.type === "update_task_status" ? "edit" : "write",
               sessionId: message.sessionId,
               toolCallId: message.requestId,
               ...message.target.type === "project" ? { projectId: message.target.projectId, branchName: message.target.branchName } : {}
@@ -6421,7 +6496,7 @@ async function startWorker(options) {
         process.stderr.write(`[r5d-worker] workspace recovery complete; reconnecting in ${reconnectDelayMs}ms
 `);
         setTimeout(() => {
-          void startWorker(options).catch((error) => {
+          void startWorker(options, projectRuntime).catch((error) => {
             process.stderr.write(`[r5d-worker] reconnect failed: ${error instanceof Error ? error.message : String(error)}
 `);
             process.exit(error instanceof WorkerServerUnavailableError ? WORKER_RECONNECT_EXIT_CODE : 1);
@@ -6440,7 +6515,7 @@ async function startWorker(options) {
         setTimeout(reconnect2, reconnectDelayMs);
       };
       const reconnect = () => {
-        void startWorker(options).catch((error) => {
+        void startWorker(options, projectRuntime).catch((error) => {
           process.stderr.write(`[r5d-worker] reconnect failed: ${error instanceof Error ? error.message : String(error)}
 `);
           if (activeProcesses.size > 0 || credentialBearingProcessGroups.size > 0 || activePtys.size > 0 || pendingProcessTerminals.size > 0) {

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.107",
+  "version": "0.0.108",
   "type": "module"
 }

package/dist/mjs/plan-lint.mjs

@@ -0,0 +1,129 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import picomatch from "picomatch";
+import { getTasksSectionRange, PLAN_TASK_LINE_REGEX } from "./plan-parser.mjs";
+import { PLAN_EXTENSION } from "./plan-paths.mjs";
+import { PLAN_TASK_ID_REGEX } from "./plan-parser.mjs";
+const LEGACY_SCHEMA_FIELD_REGEX = /^\s*(type|status|parent|phase|discovered_problem)\s*:/m;
+function lintPlanContent(planId, content) {
+  const errors = [];
+  const lines = content.split(/\r?\n/);
+  if (/^---(?:\r?\n|$)/.test(content)) {
+    errors.push({
+      planId,
+      severity: "error",
+      message: "YAML frontmatter is not supported. Use plain Markdown with a ## Tasks checklist.",
+      line: 1
+    });
+  }
+  if (LEGACY_SCHEMA_FIELD_REGEX.test(content)) {
+    errors.push({
+      planId,
+      severity: "error",
+      message: "Legacy plan schema fields are not supported. Remove type/status/parent/phase/discovered_problem metadata."
+    });
+  }
+  const titleLineIndex = lines.findIndex((line) => /^# .+\S\s*$/.test(line));
+  if (titleLineIndex === -1) {
+    errors.push({
+      planId,
+      severity: "error",
+      message: "Plan must start with or contain an H1 title, for example '# Implementation Plan'."
+    });
+  }
+  const range = getTasksSectionRange(content);
+  if (!range) {
+    errors.push({
+      planId,
+      severity: "error",
+      message: "Plan is missing a ## Tasks section."
+    });
+    return errors;
+  }
+  const taskIds = /* @__PURE__ */ new Set();
+  let taskCount = 0;
+  for (let index = range.startIndex + 1; index < range.endIndex; index += 1) {
+    const line = lines[index] ?? "";
+    if (line.trim() === "") continue;
+    const match = line.match(PLAN_TASK_LINE_REGEX);
+    if (!match || !match[3].trim()) {
+      errors.push({
+        planId,
+        severity: "error",
+        line: index + 1,
+        message: 'Malformed task line. Use "- [ ] task-id: Description" or "- [x] task-id: Description".'
+      });
+      continue;
+    }
+    taskCount += 1;
+    const taskId = match[2];
+    if (taskIds.has(taskId)) {
+      errors.push({
+        planId,
+        severity: "error",
+        line: index + 1,
+        message: `Duplicate task id "${taskId}".`
+      });
+    }
+    taskIds.add(taskId);
+  }
+  if (taskCount === 0) {
+    errors.push({
+      planId,
+      severity: "error",
+      message: "Plan must include at least one task in the ## Tasks section.",
+      line: range.startIndex + 1
+    });
+  }
+  return errors;
+}
+async function lintPlans(plansDir, glob) {
+  const errors = [];
+  let entries;
+  try {
+    entries = await fs.readdir(plansDir, { withFileTypes: true });
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    entries = [];
+  }
+  const matches = glob ? picomatch(glob) : null;
+  let lintedPlanCount = 0;
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(PLAN_EXTENSION)) continue;
+    const planId = entry.name.slice(0, -PLAN_EXTENSION.length);
+    if (!PLAN_TASK_ID_REGEX.test(planId) || matches && !matches(entry.name) && !matches(planId)) continue;
+    const content = await fs.readFile(path.join(plansDir, entry.name), "utf8");
+    lintedPlanCount += 1;
+    errors.push(...lintPlanContent(planId, content));
+  }
+  return {
+    type: "plan_lint",
+    errors,
+    errorCount: errors.filter((error) => error.severity === "error").length,
+    warningCount: errors.filter((error) => error.severity === "warning").length,
+    lintedPlanCount
+  };
+}
+function formatPlanLintErrors(errors) {
+  if (errors.length === 0) return "";
+  const lines = ["## Plan Lint Errors", ""];
+  const byPlan = /* @__PURE__ */ new Map();
+  for (const error of errors) {
+    byPlan.set(error.planId, [...byPlan.get(error.planId) ?? [], error]);
+  }
+  for (const [planId, planErrors] of byPlan) {
+    lines.push(`### ${planId}.plan.md`);
+    for (const error of planErrors) {
+      const location = error.line ? ` line ${error.line}` : "";
+      lines.push(`- ${error.severity.toUpperCase()}${location}: ${error.message}`);
+    }
+    lines.push("");
+  }
+  lines.push("Fix these issues by editing the Markdown plan file.");
+  return lines.join("\n");
+}
+export {
+  formatPlanLintErrors,
+  lintPlanContent,
+  lintPlans
+};

package/dist/mjs/plan-parser.mjs

@@ -0,0 +1,94 @@
+const PLAN_TASK_ID_REGEX = /^[a-z0-9][a-z0-9-]*$/;
+const PLAN_TASK_LINE_REGEX = /^- \[( |x)\] ([a-z0-9][a-z0-9-]*): (.+)$/;
+const PLAN_TASKS_HEADING_REGEX = /^## Tasks\s*$/;
+function getPlanMetadata(content) {
+  const title = content.split(/\r?\n/).map((line) => line.match(/^# (.+)$/)?.[1]?.trim()).find((value) => Boolean(value));
+  return { title: title || "Untitled Plan" };
+}
+function getTasksSectionRange(content) {
+  const lines = content.split(/\r?\n/);
+  const startIndex = lines.findIndex((line) => PLAN_TASKS_HEADING_REGEX.test(line));
+  if (startIndex === -1) return null;
+  let endIndex = lines.length;
+  for (let index = startIndex + 1; index < lines.length; index += 1) {
+    if (/^##\s+/.test(lines[index] ?? "")) {
+      endIndex = index;
+      break;
+    }
+  }
+  return { startIndex, endIndex };
+}
+function parseMarkdownPlan(content, planId) {
+  const lines = content.split(/\r?\n/);
+  const { title } = getPlanMetadata(content);
+  const range = getTasksSectionRange(content);
+  const tasks = [];
+  if (range) {
+    for (let index = range.startIndex + 1; index < range.endIndex; index += 1) {
+      const line = lines[index] ?? "";
+      const match = line.match(PLAN_TASK_LINE_REGEX);
+      if (!match) continue;
+      const description = match[3].trim();
+      if (!description) continue;
+      tasks.push({
+        id: match[2],
+        description,
+        checked: match[1] === "x",
+        lineNumber: index + 1
+      });
+    }
+  }
+  const currentTask = tasks.find((task) => !task.checked) ?? null;
+  return {
+    id: planId,
+    title,
+    content,
+    tasks,
+    currentTask,
+    complete: tasks.length > 0 && tasks.every((task) => task.checked),
+    tasksStartLine: range ? range.startIndex + 1 : null,
+    tasksEndLine: range ? range.endIndex : null
+  };
+}
+const parsePlan = parseMarkdownPlan;
+function createPlanMarkdown(planId, title = formatPlanTitle(planId)) {
+  return `# ${title}
+
+Brief implementation notes.
+
+## Tasks
+`;
+}
+function updateTaskCheckbox(content, taskId, checked) {
+  if (!PLAN_TASK_ID_REGEX.test(taskId)) {
+    throw new Error(`Invalid task id: ${taskId}`);
+  }
+  const lines = content.split(/\r?\n/);
+  const range = getTasksSectionRange(content);
+  if (!range) {
+    throw new Error("Plan is missing a ## Tasks section.");
+  }
+  for (let index = range.startIndex + 1; index < range.endIndex; index += 1) {
+    const line = lines[index] ?? "";
+    const match = line.match(PLAN_TASK_LINE_REGEX);
+    if (!match || match[2] !== taskId) continue;
+    lines[index] = `- [${checked ? "x" : " "}] ${match[2]}: ${match[3].trim()}`;
+    return lines.join("\n");
+  }
+  throw new Error(`Task not found in plan: ${taskId}`);
+}
+function formatPlanTitle(planId) {
+  return planId.split("-").filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+export {
+  PLAN_TASKS_HEADING_REGEX,
+  PLAN_TASK_ID_REGEX,
+  PLAN_TASK_LINE_REGEX,
+  createPlanMarkdown,
+  formatPlanTitle,
+  getPlanMetadata,
+  getTasksSectionRange,
+  parseMarkdownPlan,
+  parsePlan,
+  updateTaskCheckbox
+};

package/dist/mjs/plan-paths.mjs

@@ -0,0 +1,25 @@
+import { PLAN_TASK_ID_REGEX } from "./plan-parser.mjs";
+const PLAN_EXTENSION = ".plan.md";
+function validatePlanId(planId) {
+  if (!PLAN_TASK_ID_REGEX.test(planId)) throw new Error(`Invalid plan id: ${planId}`);
+}
+function assertPlanTarget(target) {
+  if (target.type === "workspace" && target.rootProfile !== "visible_projects") {
+    throw new Error("Ordinary plans are unavailable in canonical synchronization sessions");
+  }
+}
+function getWorkerPlansPath(target) {
+  assertPlanTarget(target);
+  return target.type === "project" ? "$R5D_ROOT/plans/$R5D_PROJECT_ID/$R5D_BRANCH_NAME" : "$R5D_ROOT/plans/workspace";
+}
+function getWorkerPlanPath(target, planId) {
+  validatePlanId(planId);
+  return `${getWorkerPlansPath(target)}/${planId}${PLAN_EXTENSION}`;
+}
+export {
+  PLAN_EXTENSION,
+  assertPlanTarget,
+  getWorkerPlanPath,
+  getWorkerPlansPath,
+  validatePlanId
+};

package/dist/types/main.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+import type { WorkerLintPlansResult, WorkerUpdatePlanTaskResult } from "./plan-paths";
 import { Database } from "bun:sqlite";
 import type { WorkerGitIdentity } from "./git-identity";
 import { configureGitHubRegistryAuthFiles, type PreparedPrivateAuthFileGeneration } from "./registry-auth";
@@ -424,6 +425,27 @@ type WorkerServerMessage = {
 } | {
     type: "pty_close";
     ptyId: string;
+} | {
+    type: "read_plan";
+    requestId: string;
+    target: WorkerSessionTarget;
+    sessionId?: string;
+    planId: string;
+    createIfMissing: boolean;
+} | {
+    type: "lint_plans";
+    requestId: string;
+    target: WorkerSessionTarget;
+    sessionId?: string;
+    glob?: string;
+} | {
+    type: "update_task_status";
+    requestId: string;
+    target: WorkerSessionTarget;
+    sessionId?: string;
+    planId: string;
+    taskId: string;
+    checked: boolean;
 } | {
     type: "read";
     requestId: string;
@@ -514,6 +536,11 @@ type WorkerGitHubCredential = {
     token: string;
     missingScopes: Array<"repo" | "read:org" | "gist" | "workflow" | "read:packages" | "write:packages">;
 };
+type WorkerReadPlanResult = {
+    type: "read_plan";
+    read: WorkerReadFileResult;
+    created: boolean;
+};
 type WorkerWriteFileResult = {
     type: "write";
     file: string;
@@ -587,7 +614,10 @@ type WorkerCodeReadResult = {
     mtime: string;
     base64: string;
 };
-type WorkerOperationResult = WorkerReadFileResult | WorkerWriteFileResult | WorkerEditFileResult | WorkerGrepResult | WorkerFindResult | WorkerLsResult | WorkerViewFileBytesResult | WorkerExecStdinAck | WorkerCreateProjectBranchResult | WorkerDeleteProjectBranchResult | WorkerCodeListResult | WorkerCodeReadResult;
+type WorkerOperationResult = WorkerReadFileResult | WorkerReadPlanResult | WorkerLintPlansResult | WorkerUpdatePlanTaskResult | WorkerWriteFileResult | WorkerEditFileResult | WorkerGrepResult | WorkerFindResult | WorkerLsResult | WorkerViewFileBytesResult | WorkerExecStdinAck | WorkerCreateProjectBranchResult | WorkerDeleteProjectBranchResult | WorkerCodeListResult | WorkerCodeReadResult;
+type WorkerOperationServerMessage = Extract<WorkerServerMessage, {
+    type: "read_plan" | "lint_plans" | "update_task_status" | "read" | "write" | "edit" | "grep" | "find" | "ls" | "view_file_bytes" | "code_list" | "code_read";
+}>;
 declare class WorkspaceSyncAdmissionChangedError extends Error {
     readonly name = "WorkspaceSyncAdmissionChangedError";
 }
@@ -916,6 +946,7 @@ export declare const workerGitSecurityTestHarness: {
     workspaceSyncFailureHydrationIsSafe: typeof workspaceSyncFailureHydrationIsSafe;
     assertWorkerChildAdmission: typeof assertWorkerChildAdmission;
     executeWriteFileOperation: typeof executeWriteFileOperation;
+    executeOperation: typeof executeOperation;
     executeEditFileOperation: typeof executeEditFileOperation;
     terminateCredentialBearingChildren: typeof terminateCredentialBearingChildren;
     terminateCredentialBearingChildrenWithRetention: typeof terminateCredentialBearingChildrenWithRetention;
@@ -1010,6 +1041,14 @@ export declare function listWorkerDirectory(branchPath: string, inputPath?: stri
 export declare function listWorkerCodeDirectory(branchPath: string, inputPath: string): WorkerCodeListResult;
 export declare function readWorkerCodeFile(branchPath: string, inputPath: string): WorkerCodeReadResult;
 export declare function readWorkerImageFile(branchPath: string, filePath: string, builtInPaths?: WorkerBuiltInToolPaths): WorkerViewFileBytesResult;
+declare function executeOperation(input: {
+    message: WorkerOperationServerMessage;
+    resolvedTarget: ResolvedWorkerSessionTarget;
+    baseUrl: string;
+    token: string;
+    rootDir: string;
+    assertAdmission: () => void;
+}): Promise<WorkerOperationResult>;
 declare function targetProcessEnv(rootDir: string, target: WorkerSessionTarget): Record<string, string>;
 export declare function prepareShellEnvForTarget(input: {
     target: WorkerSessionTarget;

package/dist/types/plan-lint.d.ts

@@ -0,0 +1,16 @@
+export interface PlanLintError {
+    planId: string;
+    message: string;
+    severity: "warning" | "error";
+    line?: number;
+}
+export interface PlanLintResult {
+    type: "plan_lint";
+    errors: PlanLintError[];
+    errorCount: number;
+    warningCount: number;
+    lintedPlanCount: number;
+}
+export declare function lintPlanContent(planId: string, content: string): PlanLintError[];
+export declare function lintPlans(plansDir: string, glob?: string): Promise<PlanLintResult>;
+export declare function formatPlanLintErrors(errors: PlanLintError[]): string;

package/dist/types/plan-parser.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Markdown plan parser.
+ *
+ * Plans are plain Markdown files. The only structured region is the first
+ * "## Tasks" section, which contains checkbox task lines.
+ */
+export declare const PLAN_TASK_ID_REGEX: RegExp;
+export declare const PLAN_TASK_LINE_REGEX: RegExp;
+export declare const PLAN_TASKS_HEADING_REGEX: RegExp;
+export interface PlanTask {
+    id: string;
+    description: string;
+    checked: boolean;
+    lineNumber: number;
+}
+export interface ParsedPlan {
+    id: string;
+    title: string;
+    content: string;
+    tasks: PlanTask[];
+    currentTask: PlanTask | null;
+    complete: boolean;
+    tasksStartLine: number | null;
+    tasksEndLine: number | null;
+}
+export type ParsedMarkdownPlan = ParsedPlan;
+export declare function getPlanMetadata(content: string): {
+    title: string;
+};
+export declare function getTasksSectionRange(content: string): {
+    startIndex: number;
+    endIndex: number;
+} | null;
+export declare function parseMarkdownPlan(content: string, planId: string): ParsedPlan;
+export declare const parsePlan: typeof parseMarkdownPlan;
+export declare function createPlanMarkdown(planId: string, title?: string): string;
+export declare function updateTaskCheckbox(content: string, taskId: string, checked: boolean): string;
+export declare function formatPlanTitle(planId: string): string;

package/dist/types/plan-paths.d.ts

@@ -0,0 +1,36 @@
+type PlanTarget = {
+    type: "project";
+} | {
+    type: "workspace";
+    rootProfile: "visible_projects" | "canonical_sync";
+};
+export declare const PLAN_EXTENSION = ".plan.md";
+export declare function validatePlanId(planId: string): void;
+export declare function assertPlanTarget(target: PlanTarget): void;
+export declare function getWorkerPlansPath(target: PlanTarget): string;
+/** The same worker path is used in prompts, injected reads, and file tools. */
+export declare function getWorkerPlanPath(target: PlanTarget, planId: string): string;
+export type WorkerReadPlanInput = {
+    planId: string;
+    createIfMissing: boolean;
+};
+export type WorkerLintPlansInput = {
+    glob?: string;
+};
+export type WorkerUpdatePlanTaskInput = {
+    planId: string;
+    taskId: string;
+    checked: boolean;
+};
+export type WorkerLintPlansResult = {
+    type: "lint_plans";
+    content: string;
+};
+export type WorkerUpdatePlanTaskResult = {
+    type: "update_task_status";
+    planId: string;
+    taskId: string;
+    checked: boolean;
+    message: string;
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-worker",
-  "version": "0.0.107",
+  "version": "0.0.108",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",
@@ -21,7 +21,8 @@
     "r5d-worker": "dist/cjs/main.cjs"
   },
   "dependencies": {
-    "node-pty": "^1.1.0"
+    "node-pty": "^1.1.0",
+    "picomatch": "^4.0.3"
   },
   "files": [
     "dist",