@xn-intenton-z2a/agentic-lib 7.1.57 → 7.1.59

package/.github/workflows/agentic-lib-workflow.yml

@@ -198,23 +198,8 @@ jobs:
                   core.warning(`Could not merge PR #${pr.number}: ${e.message}`);
                 }
               } else if (fullPr.mergeable_state === 'dirty' || fullPr.mergeable === false) {
-                const isStale = new Date(pr.updated_at) < prCutoff;
-                if (isStale) {
-                  // Close stale conflicting PR
-                  core.info(`Closing stale conflicting PR #${pr.number}`);
-                  await github.rest.pulls.update({ owner, repo, pull_number: pr.number, state: 'closed' });
-                  try {
-                    await github.rest.git.deleteRef({ owner, repo, ref: `heads/${pr.head.ref}` });
-                  } catch (e) { /* branch may already be gone */ }
-                  closedPRs.push(pr.number);
-                } else {
-                  // Remove automerge label from conflicting but fresh PR
-                  try {
-                    await github.rest.issues.removeLabel({ owner, repo, issue_number: pr.number, name: 'automerge' });
-                    await github.rest.issues.createComment({ owner, repo, issue_number: pr.number,
-                      body: 'Automerge label removed — PR has conflicts. Resolve and re-add label to retry.' });
-                  } catch (e) { /* label may not exist */ }
-                }
+                // Conflicting PR — leave it for fix-stuck to resolve instead of deleting
+                core.info(`PR #${pr.number} has merge conflicts — fix-stuck job will attempt resolution`);
               }
               // If unstable/unknown: skip, next run handles
             }
@@ -450,7 +435,7 @@ jobs:
               return;
             }
 
-            // Find PRs with failing checks on agentic branches
+            // Find PRs with failing checks or merge conflicts on agentic branches
             const { data: openPRs } = await github.rest.pulls.list({
               owner, repo, state: 'open', per_page: 10,
             });
@@ -460,12 +445,19 @@ jobs:
               if (!hasAutomerge) continue;
               if (!pr.head.ref.startsWith('agentic-lib-') && !pr.head.ref.startsWith('copilot/')) continue;
 
+              // Check for merge conflicts
+              const { data: fullPr } = await github.rest.pulls.get({
+                owner, repo, pull_number: pr.number,
+              });
+              const hasConflicts = fullPr.mergeable_state === 'dirty' || fullPr.mergeable === false;
+
               // Check if checks are failing
               const { data: checkRuns } = await github.rest.checks.listForRef({
                 owner, repo, ref: pr.head.sha,
               });
               const hasFailing = checkRuns.check_runs.some(c => c.conclusion === 'failure');
-              if (!hasFailing) continue;
+
+              if (!hasFailing && !hasConflicts) continue;
 
               // Check fix attempt count
               const { data: fixRuns } = await github.rest.actions.listWorkflowRuns({
@@ -478,24 +470,60 @@ jobs:
                 continue;
               }
 
-              core.info(`Will attempt to fix PR #${pr.number}`);
+              const reason = hasConflicts ? 'merge conflicts' : 'failing checks';
+              core.info(`Will attempt to fix PR #${pr.number} (${reason})`);
               core.exportVariable('FIX_PR_NUMBER', String(pr.number));
+              core.exportVariable('FIX_REASON', reason);
               break;
             }
 
-      - name: Checkout PR branch and fix
+      - name: Checkout PR branch
         if: env.FIX_PR_NUMBER != ''
         run: |
           gh pr checkout ${{ env.FIX_PR_NUMBER }}
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Fix failing code
-        if: env.FIX_PR_NUMBER != ''
+      - name: "Tier 1: Auto-resolve trivial merge conflicts"
+        if: env.FIX_PR_NUMBER != '' && env.FIX_REASON == 'merge conflicts'
+        id: trivial-resolve
+        run: |
+          git fetch origin main
+          if git merge origin/main --no-edit 2>/dev/null; then
+            echo "resolved=clean" >> $GITHUB_OUTPUT
+          else
+            CONFLICTED=$(git diff --name-only --diff-filter=U)
+            TRIVIAL_PATTERN='intentïon\.md|intention\.md|package-lock\.json'
+            NON_TRIVIAL=$(echo "$CONFLICTED" | grep -vE "$TRIVIAL_PATTERN" || true)
+            if [ -z "$NON_TRIVIAL" ]; then
+              echo "All conflicts are trivial — auto-resolving"
+              for f in $CONFLICTED; do
+                git checkout --theirs "$f"
+                git add "$f"
+              done
+              npm install 2>/dev/null || true
+              git add package-lock.json 2>/dev/null || true
+              git commit --no-edit
+              echo "resolved=trivial" >> $GITHUB_OUTPUT
+            else
+              git merge --abort
+              echo "resolved=none" >> $GITHUB_OUTPUT
+              echo "non_trivial<<EOF" >> $GITHUB_OUTPUT
+              echo "$NON_TRIVIAL" >> $GITHUB_OUTPUT
+              echo "EOF" >> $GITHUB_OUTPUT
+            fi
+          fi
+
+      - name: "Tier 2: LLM fix (conflicts or failing checks)"
+        if: |
+          env.FIX_PR_NUMBER != '' &&
+          (env.FIX_REASON != 'merge conflicts' ||
+           steps.trivial-resolve.outputs.resolved == 'none')
         uses: ./.github/agentic-lib/actions/agentic-step
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+          NON_TRIVIAL_FILES: ${{ steps.trivial-resolve.outputs.non_trivial }}
         with:
           task: "fix-code"
           config: ${{ needs.params.outputs.config-path }}
@@ -508,7 +536,7 @@ jobs:
         if: env.FIX_PR_NUMBER != ''
         uses: ./.github/agentic-lib/actions/commit-if-changed
         with:
-          commit-message: "agentic-step: fix failing tests"
+          commit-message: "agentic-step: fix failing tests / resolve conflicts"
 
   # ─── Review: close resolved issues, enhance with criteria ──────────
   review-features:

package/bin/agentic-lib.js

@@ -31,7 +31,7 @@ const flags = args.slice(1);
 let initChanges = 0;
 const TASK_COMMANDS = ["transform", "maintain-features", "maintain-library", "fix-code"];
 const INIT_COMMANDS = ["init", "update", "reset"];
-const ALL_COMMANDS = [...INIT_COMMANDS, ...TASK_COMMANDS, "version"];
+const ALL_COMMANDS = [...INIT_COMMANDS, ...TASK_COMMANDS, "version", "mcp"];
 
 const HELP = `
 @xn-intenton-z2a/agentic-lib — Agentic Coding Systems SDK
@@ -50,6 +50,9 @@ Tasks (run Copilot SDK transformations):
   maintain-library     Update library docs from SOURCES.md
   fix-code             Fix failing tests
 
+MCP Server:
+  mcp                  Start MCP server (for Claude Code, Cursor, etc.)
+
 Options:
   --purge              Full reset — clear features, activity log, source code
   --reseed             Clear features + activity log (keep source code)
@@ -88,6 +91,13 @@ const mission = missionIdx >= 0 ? flags[missionIdx + 1] : "hamming-distance";
 
 // ─── Task Commands ───────────────────────────────────────────────────
 
+if (command === "mcp") {
+  const { startServer } = await import("../src/mcp/server.js");
+  await startServer();
+  // Server runs until stdin closes — don't exit
+  await new Promise(() => {}); // block forever
+}
+
 if (TASK_COMMANDS.includes(command)) {
   process.exit(await runTask(command));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xn-intenton-z2a/agentic-lib",
-  "version": "7.1.57",
+  "version": "7.1.59",
   "description": "Agentic-lib Agentic Coding Systems SDK powering automated GitHub workflows.",
   "type": "module",
   "scripts": {
@@ -81,7 +81,8 @@
     "src/actions/setup-npmrc/",
     "src/agents/",
     "src/seeds/",
-    "src/scripts/"
+    "src/scripts/",
+    "src/mcp/"
   ],
   "overrides": {
     "minimatch": ">=10.2.3"
@@ -99,6 +100,7 @@
     "@actions/core": "^3.0.0",
     "@actions/github": "^9.0.0",
     "@github/copilot-sdk": "^0.1.29",
+    "@modelcontextprotocol/sdk": "^1.27.0",
     "smol-toml": "^1.6.0"
   }
 }

package/src/actions/agentic-step/tasks/fix-code.js

@@ -1,11 +1,13 @@
 // SPDX-License-Identifier: GPL-3.0-only
 // Copyright (C) 2025-2026 Polycode Limited
-// tasks/fix-code.js — Fix failing tests on a PR
+// tasks/fix-code.js — Fix failing tests or resolve merge conflicts on a PR
 //
-// Given a PR number with failing tests, analyzes the test output,
-// generates fixes using the Copilot SDK, and pushes a commit.
+// Given a PR number, detects merge conflicts or failing checks and resolves them.
+// Conflict resolution: reads files with conflict markers, asks the LLM to resolve.
+// Failing checks: analyzes test output, generates code fixes.
 
 import * as core from "@actions/core";
+import { readFileSync } from "fs";
 import { execSync } from "child_process";
 import { runCopilotTask, formatPathsSection } from "../copilot.js";
 
@@ -37,7 +39,90 @@ function fetchRunLog(runId) {
 }
 
 /**
- * Fix failing code on a pull request.
+ * Resolve merge conflicts on a PR using the Copilot SDK.
+ * Called when the workflow has started a `git merge origin/main` that left
+ * conflict markers in non-trivial files (listed in NON_TRIVIAL_FILES env var).
+ *
+ * @param {Object} params
+ * @returns {Promise<Object>} Result with outcome, tokensUsed, model
+ */
+async function resolveConflicts({ config, pr, prNumber, instructions, model, writablePaths, testCommand }) {
+  const nonTrivialEnv = process.env.NON_TRIVIAL_FILES || "";
+  const conflictedPaths = nonTrivialEnv
+    .split("\n")
+    .map((f) => f.trim())
+    .filter(Boolean);
+
+  if (conflictedPaths.length === 0) {
+    core.info(`PR #${prNumber} has conflicts but no non-trivial files listed. Returning nop.`);
+    return { outcome: "nop", details: "No non-trivial conflict files to resolve" };
+  }
+
+  core.info(`Resolving ${conflictedPaths.length} conflicted file(s) on PR #${prNumber}`);
+
+  const conflicts = conflictedPaths.map((f) => {
+    try {
+      return { name: f, content: readFileSync(f, "utf8") };
+    } catch (err) {
+      core.warning(`Could not read conflicted file ${f}: ${err.message}`);
+      return { name: f, content: "(could not read)" };
+    }
+  });
+
+  const agentInstructions = instructions || "Resolve the merge conflicts while preserving the PR's intended changes.";
+  const readOnlyPaths = config.readOnlyPaths;
+
+  const prompt = [
+    "## Instructions",
+    agentInstructions,
+    "",
+    `## Pull Request #${prNumber}: ${pr.title}`,
+    "",
+    pr.body || "(no description)",
+    "",
+    "## Task: Resolve Merge Conflicts",
+    "The PR branch has been merged with main but has conflicts in the files below.",
+    "Each file contains git conflict markers (<<<<<<< / ======= / >>>>>>>).",
+    "Resolve each conflict by keeping the PR's intended changes while incorporating",
+    "any non-conflicting updates from main.",
+    "",
+    `## Conflicted Files (${conflicts.length})`,
+    ...conflicts.map((f) => `### ${f.name}\n\`\`\`\n${f.content}\n\`\`\``),
+    "",
+    formatPathsSection(writablePaths, readOnlyPaths, config),
+    "",
+    "## Constraints",
+    "- Remove ALL conflict markers (<<<<<<, =======, >>>>>>>)",
+    "- Preserve the PR's feature/fix intent",
+    `- Run \`${testCommand}\` to validate your resolution`,
+  ].join("\n");
+
+  const t = config.tuning || {};
+  const { tokensUsed, inputTokens, outputTokens, cost } = await runCopilotTask({
+    model,
+    systemMessage: `You are resolving git merge conflicts on PR #${prNumber}. Write resolved versions of each conflicted file, removing all conflict markers. Preserve the PR's feature intent while incorporating main's updates.`,
+    prompt,
+    writablePaths,
+    tuning: t,
+  });
+
+  core.info(`Conflict resolution completed (${tokensUsed} tokens)`);
+
+  return {
+    outcome: "conflicts-resolved",
+    tokensUsed,
+    inputTokens,
+    outputTokens,
+    cost,
+    model,
+    details: `Resolved ${conflicts.length} conflicted file(s) on PR #${prNumber}`,
+  };
+}
+
+/**
+ * Fix failing code or resolve merge conflicts on a pull request.
+ *
+ * Priority: conflicts first (if NON_TRIVIAL_FILES env is set), then failing checks.
  *
  * @param {Object} context - Task context from index.js
  * @returns {Promise<Object>} Result with outcome, tokensUsed, model
@@ -49,8 +134,15 @@ export async function fixCode(context) {
     throw new Error("fix-code task requires pr-number input");
   }
 
-  // Fetch the PR and check runs
+  // Fetch the PR
   const { data: pr } = await octokit.rest.pulls.get({ ...repo, pull_number: Number(prNumber) });
+
+  // If we have non-trivial conflict files from the workflow's Tier 1 step, resolve them
+  if (process.env.NON_TRIVIAL_FILES) {
+    return resolveConflicts({ config, pr, prNumber, instructions, model, writablePaths, testCommand });
+  }
+
+  // Otherwise, check for failing checks
   const { data: checkRuns } = await octokit.rest.checks.listForRef({ ...repo, ref: pr.head.sha, per_page: 10 });
 
   const failedChecks = checkRuns.check_runs.filter((cr) => cr.conclusion === "failure");

package/src/agents/agent-apply-fix.md

@@ -11,3 +11,15 @@ and maintain the integrity of the codebase's primary purpose.
 You may complete the implementation of a feature and/or bring the code output in line with the README
 or other documentation. Do as much as you can all at once so that the build runs (even with nothing
 to build) and the tests pass and the main at least doesn't output an error.
+
+## Merge Conflict Resolution
+
+When resolving merge conflicts (files containing <<<<<<< / ======= / >>>>>>> markers):
+
+1. **Understand both sides**: The HEAD side (above =======) is the PR's changes. The incoming side
+   (below =======) is from main. Understand what each side intended before choosing.
+2. **Preserve PR intent**: The PR was created for a reason — keep its feature/fix changes.
+3. **Incorporate main's updates**: If main added new code that doesn't conflict with the PR's
+   purpose, include it.
+4. **Remove ALL markers**: Every <<<<<<, =======, and >>>>>>> line must be removed.
+5. **Run tests**: After resolving, run the test command to validate the resolution compiles and passes.

package/src/mcp/server.js

@@ -0,0 +1,915 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: GPL-3.0-only
+// Copyright (C) 2025-2026 Polycode Limited
+// src/mcp/server.js — MCP server for agentic-lib
+//
+// Exposes agentic-lib capabilities as MCP tools for Claude Code and other MCP clients.
+// Usage: npx @xn-intenton-z2a/agentic-lib mcp
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "fs";
+import { execSync } from "child_process";
+import { resolve, dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { tmpdir, homedir } from "os";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = resolve(__dirname, "../..");
+const binPath = resolve(pkgRoot, "bin/agentic-lib.js");
+const seedsDir = resolve(pkgRoot, "src/seeds/missions");
+
+// Workspace base directory
+const workspacesBase =
+  process.env.AGENTIC_LIB_WORKSPACES || join(homedir(), ".agentic-lib", "workspaces");
+
+// ─── Workspace Helpers ──────────────────────────────────────────────
+
+function ensureWorkspacesDir() {
+  if (!existsSync(workspacesBase)) {
+    mkdirSync(workspacesBase, { recursive: true });
+  }
+}
+
+function workspacePath(id) {
+  return join(workspacesBase, id);
+}
+
+function metadataPath(wsPath) {
+  return join(wsPath, ".agentic-lib-workspace.json");
+}
+
+function readMetadata(wsPath) {
+  const mp = metadataPath(wsPath);
+  if (!existsSync(mp)) return null;
+  return JSON.parse(readFileSync(mp, "utf8"));
+}
+
+function writeMetadata(wsPath, metadata) {
+  writeFileSync(metadataPath(wsPath), JSON.stringify(metadata, null, 2));
+}
+
+function listWorkspaces() {
+  ensureWorkspacesDir();
+  const entries = readdirSync(workspacesBase, { withFileTypes: true });
+  return entries
+    .filter((e) => e.isDirectory())
+    .map((e) => {
+      const wsPath = workspacePath(e.name);
+      const meta = readMetadata(wsPath);
+      return meta || { id: e.name, status: "unknown" };
+    })
+    .filter((m) => m.status !== "unknown");
+}
+
+function runCli(args, wsPath, timeoutMs = 300000) {
+  const cmd = `node ${binPath} ${args}`;
+  try {
+    const stdout = execSync(cmd, {
+      cwd: wsPath || pkgRoot,
+      encoding: "utf8",
+      timeout: timeoutMs,
+      env: { ...process.env },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return { success: true, output: stdout };
+  } catch (err) {
+    return {
+      success: false,
+      output: `STDOUT:\n${err.stdout || ""}\nSTDERR:\n${err.stderr || ""}`,
+      exitCode: err.status || 1,
+    };
+  }
+}
+
+function runInWorkspace(command, wsPath, timeoutMs = 120000) {
+  try {
+    const stdout = execSync(command, {
+      cwd: wsPath,
+      encoding: "utf8",
+      timeout: timeoutMs,
+      env: { ...process.env },
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    return { success: true, output: stdout, exitCode: 0 };
+  } catch (err) {
+    return {
+      success: false,
+      output: `STDOUT:\n${err.stdout || ""}\nSTDERR:\n${err.stderr || ""}`,
+      exitCode: err.status || 1,
+    };
+  }
+}
+
+// ─── Tool Definitions ───────────────────────────────────────────────
+
+const TOOLS = [
+  {
+    name: "list_missions",
+    description:
+      "List available mission seeds that can be used to create workspaces. Each mission is a MISSION.md template describing what the autonomous code should build.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "workspace_create",
+    description:
+      "Create a new workspace from a mission seed. Runs init --purge, npm install, and sets up the Copilot SDK. Returns the workspace ID and path.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission: {
+          type: "string",
+          description: "Mission seed name (e.g. 'hamming-distance', 'fizz-buzz')",
+        },
+        profile: {
+          type: "string",
+          enum: ["min", "recommended", "max"],
+          description: "Tuning profile: min (fast/cheap), recommended (balanced), max (thorough). Default: min",
+        },
+        model: {
+          type: "string",
+          description: "LLM model override (e.g. 'gpt-5-mini', 'claude-sonnet-4'). Uses profile default if omitted.",
+        },
+      },
+      required: ["mission"],
+    },
+  },
+  {
+    name: "workspace_list",
+    description: "List all active workspaces with their current status, mission, profile, and iteration count.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "workspace_status",
+    description:
+      "Get detailed status of a workspace: mission content, features, test results, iteration history, and current configuration.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace: { type: "string", description: "Workspace ID" },
+      },
+      required: ["workspace"],
+    },
+  },
+  {
+    name: "workspace_destroy",
+    description: "Delete a workspace and all its contents.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace: { type: "string", description: "Workspace ID" },
+      },
+      required: ["workspace"],
+    },
+  },
+  {
+    name: "iterate",
+    description:
+      "Run N cycles of the autonomous development loop (maintain-features -> transform -> test -> fix-code). Stops early if tests pass for 2 consecutive iterations or if no files change for 2 consecutive iterations. Returns iteration-by-iteration results.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace: { type: "string", description: "Workspace ID" },
+        cycles: {
+          type: "number",
+          description: "Maximum number of iterations to run. Default: 3",
+        },
+        steps: {
+          type: "array",
+          items: { type: "string", enum: ["maintain-features", "transform", "fix-code"] },
+          description:
+            "Which steps to run per cycle. Default: ['maintain-features', 'transform', 'fix-code']. Use ['transform'] for transform-only cycles.",
+        },
+      },
+      required: ["workspace"],
+    },
+  },
+  {
+    name: "run_tests",
+    description: "Run tests in a workspace and return pass/fail status with output.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace: { type: "string", description: "Workspace ID" },
+      },
+      required: ["workspace"],
+    },
+  },
+  {
+    name: "config_get",
+    description: "Read the agentic-lib.toml configuration from a workspace.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace: { type: "string", description: "Workspace ID" },
+      },
+      required: ["workspace"],
+    },
+  },
+  {
+    name: "config_set",
+    description:
+      "Update configuration in a workspace. Can change the tuning profile, model, or individual tuning knobs. Changes take effect on the next iteration.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace: { type: "string", description: "Workspace ID" },
+        profile: {
+          type: "string",
+          enum: ["min", "recommended", "max"],
+          description: "Tuning profile to switch to",
+        },
+        model: {
+          type: "string",
+          description: "LLM model to use (e.g. 'gpt-5-mini', 'claude-sonnet-4', 'gpt-4.1')",
+        },
+        overrides: {
+          type: "object",
+          description:
+            "Individual tuning knob overrides. Keys: reasoning-effort, infinite-sessions, features-scan, source-scan, source-content, issues-scan, document-summary, discussion-comments",
+        },
+      },
+      required: ["workspace"],
+    },
+  },
+  {
+    name: "prepare_iteration",
+    description:
+      "Gather full context for a workspace iteration: mission, features, source code, test results, and transformation instructions. Use this when YOU (Claude/the MCP client) are the LLM — read the returned context, write code via workspace_write_file, then verify with run_tests. No Copilot token needed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace: { type: "string", description: "Workspace ID" },
+        focus: {
+          type: "string",
+          enum: ["transform", "maintain-features", "fix-code"],
+          description: "What kind of iteration to prepare context for. Default: transform",
+        },
+      },
+      required: ["workspace"],
+    },
+  },
+  {
+    name: "workspace_read_file",
+    description: "Read a file from a workspace. Use with prepare_iteration when Claude is the LLM.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace: { type: "string", description: "Workspace ID" },
+        path: { type: "string", description: "Relative path within the workspace (e.g. 'src/lib/main.js')" },
+      },
+      required: ["workspace", "path"],
+    },
+  },
+  {
+    name: "workspace_write_file",
+    description:
+      "Write a file to a workspace. Parent directories are created automatically. Use with prepare_iteration when Claude is the LLM.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace: { type: "string", description: "Workspace ID" },
+        path: { type: "string", description: "Relative path within the workspace (e.g. 'src/lib/main.js')" },
+        content: { type: "string", description: "File content to write" },
+      },
+      required: ["workspace", "path", "content"],
+    },
+  },
+  {
+    name: "workspace_exec",
+    description:
+      "Run a shell command in a workspace. Use for builds, custom test commands, or inspecting workspace state. Git write commands are blocked.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspace: { type: "string", description: "Workspace ID" },
+        command: { type: "string", description: "Shell command to execute" },
+      },
+      required: ["workspace", "command"],
+    },
+  },
+];
+
+// ─── Tool Handlers ──────────────────────────────────────────────────
+
+async function handleListMissions() {
+  if (!existsSync(seedsDir)) {
+    return text("No missions directory found.");
+  }
+  const missions = readdirSync(seedsDir)
+    .filter((f) => f.endsWith(".md"))
+    .map((f) => {
+      const name = f.replace(/\.md$/, "");
+      const content = readFileSync(join(seedsDir, f), "utf8");
+      const firstLine = content.split("\n").find((l) => l.trim()) || "";
+      return `- **${name}**: ${firstLine.replace(/^#\s*/, "")}`;
+    });
+  return text(`Available missions (${missions.length}):\n\n${missions.join("\n")}`);
+}
+
+async function handleWorkspaceCreate({ mission, profile = "min", model }) {
+  // Validate mission exists
+  const missionFile = join(seedsDir, `${mission}.md`);
+  if (!existsSync(missionFile)) {
+    const available = readdirSync(seedsDir)
+      .filter((f) => f.endsWith(".md"))
+      .map((f) => f.replace(/\.md$/, ""));
+    return text(`Unknown mission "${mission}". Available: ${available.join(", ")}`);
+  }
+
+  // Create workspace
+  ensureWorkspacesDir();
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "").substring(0, 15);
+  const id = `${mission}-${timestamp}`;
+  const wsPath = workspacePath(id);
+  mkdirSync(wsPath, { recursive: true });
+
+  // Initialize git repo (required for init)
+  runInWorkspace("git init", wsPath);
+
+  // Run init --purge
+  const initResult = runCli(`init --purge --mission ${mission} --target ${wsPath}`, wsPath);
+  if (!initResult.success) {
+    return text(`Failed to initialize workspace:\n${initResult.output}`);
+  }
+
+  // Update config with profile and model
+  const tomlPath = join(wsPath, "agentic-lib.toml");
+  if (existsSync(tomlPath)) {
+    let toml = readFileSync(tomlPath, "utf8");
+    toml = toml.replace(/^profile\s*=\s*"[^"]*"/m, `profile = "${profile}"`);
+    if (model) {
+      toml = toml.replace(/^model\s*=\s*"[^"]*"/m, `model = "${model}"`);
+    }
+    writeFileSync(tomlPath, toml);
+  }
+
+  // npm install
+  const npmResult = runInWorkspace("npm install --ignore-scripts 2>&1", wsPath, 120000);
+
+  // Install Copilot SDK in action dir
+  const actionDir = join(wsPath, ".github/agentic-lib/actions/agentic-step");
+  let sdkResult = { success: true, output: "skipped" };
+  if (existsSync(join(actionDir, "package.json"))) {
+    sdkResult = runInWorkspace(`cd "${actionDir}" && npm ci 2>&1`, wsPath, 120000);
+  }
+
+  // Write metadata
+  const metadata = {
+    id,
+    mission,
+    created: new Date().toISOString(),
+    profile,
+    model: model || profileDefaultModel(profile),
+    iterations: [],
+    status: "ready",
+    path: wsPath,
+  };
+  writeMetadata(wsPath, metadata);
+
+  const summary = [
+    `Workspace created: **${id}**`,
+    `Path: ${wsPath}`,
+    `Mission: ${mission}`,
+    `Profile: ${profile}`,
+    `Model: ${metadata.model}`,
+    "",
+    `Init: ${initResult.success ? "OK" : "FAILED"}`,
+    `npm install: ${npmResult.success ? "OK" : "FAILED"}`,
+    `Copilot SDK: ${sdkResult.success ? "OK" : "FAILED"}`,
+    "",
+    "Ready for `iterate` or `run_tests`.",
+  ];
+  return text(summary.join("\n"));
+}
+
+async function handleWorkspaceList() {
+  const workspaces = listWorkspaces();
+  if (workspaces.length === 0) {
+    return text("No workspaces found. Use `workspace_create` to create one.");
+  }
+  const lines = workspaces.map((w) => {
+    const iters = w.iterations?.length || 0;
+    return `- **${w.id}** | mission: ${w.mission} | profile: ${w.profile} | model: ${w.model} | iterations: ${iters} | status: ${w.status}`;
+  });
+  return text(`Workspaces (${workspaces.length}):\n\n${lines.join("\n")}`);
+}
+
+async function handleWorkspaceStatus({ workspace }) {
+  const wsPath = workspacePath(workspace);
+  const meta = readMetadata(wsPath);
+  if (!meta) {
+    return text(`Workspace "${workspace}" not found.`);
+  }
+
+  const sections = [`# Workspace: ${meta.id}`, ""];
+
+  // Mission
+  const missionPath = join(wsPath, "MISSION.md");
+  if (existsSync(missionPath)) {
+    const mission = readFileSync(missionPath, "utf8");
+    sections.push("## Mission", mission.substring(0, 1000), "");
+  }
+
+  // Config
+  sections.push("## Configuration");
+  sections.push(`- Profile: ${meta.profile}`);
+  sections.push(`- Model: ${meta.model}`);
+  sections.push(`- Status: ${meta.status}`);
+  sections.push("");
+
+  // Features
+  const featuresDir = join(wsPath, "features");
+  if (existsSync(featuresDir)) {
+    const features = readdirSync(featuresDir).filter((f) => f.endsWith(".md"));
+    sections.push(`## Features (${features.length})`);
+    for (const f of features.slice(0, 10)) {
+      const content = readFileSync(join(featuresDir, f), "utf8");
+      sections.push(`### ${f}`, content.substring(0, 300), "");
+    }
+  }
+
+  // Source files
+  const srcDir = join(wsPath, "src/lib");
+  if (existsSync(srcDir)) {
+    const srcFiles = readdirSync(srcDir, { recursive: true }).filter((f) =>
+      String(f).match(/\.(js|ts)$/),
+    );
+    sections.push(`## Source files (${srcFiles.length})`);
+    for (const f of srcFiles.slice(0, 5)) {
+      const content = readFileSync(join(srcDir, String(f)), "utf8");
+      sections.push(`### ${f}`, "```js", content.substring(0, 2000), "```", "");
+    }
+  }
+
+  // Iteration history
+  if (meta.iterations && meta.iterations.length > 0) {
+    sections.push(`## Iteration History (${meta.iterations.length} cycles)`);
+    for (const iter of meta.iterations) {
+      sections.push(
+        `### Iteration ${iter.number} (${iter.profile}/${iter.model})`,
+        `- Steps: ${iter.steps?.map((s) => `${s.step}: ${s.success ? "OK" : "FAIL"}`).join(", ") || "none"}`,
+        `- Tests: ${iter.testsPassed ? "PASS" : "FAIL"}`,
+        `- Elapsed: ${iter.elapsed || "?"}s`,
+        "",
+      );
+    }
+  }
+
+  // Run tests for current status
+  const testResult = runInWorkspace("npm test 2>&1", wsPath, 60000);
+  sections.push("## Current Test Status");
+  sections.push(testResult.success ? "All tests passing." : "Tests failing.");
+  sections.push("```", testResult.output.substring(0, 2000), "```");
+
+  return text(sections.join("\n"));
+}
+
+async function handleWorkspaceDestroy({ workspace }) {
+  const wsPath = workspacePath(workspace);
+  if (!existsSync(wsPath)) {
+    return text(`Workspace "${workspace}" not found.`);
+  }
+  rmSync(wsPath, { recursive: true, force: true });
+  return text(`Workspace "${workspace}" destroyed.`);
+}
+
+async function handleIterate({ workspace, cycles = 3, steps }) {
+  const wsPath = workspacePath(workspace);
+  const meta = readMetadata(wsPath);
+  if (!meta) {
+    return text(`Workspace "${workspace}" not found.`);
+  }
+
+  const stepsToRun = steps || ["maintain-features", "transform", "fix-code"];
+  const results = [];
+  let consecutivePasses = 0;
+  let consecutiveNoChanges = 0;
+  const startIterNum = (meta.iterations?.length || 0) + 1;
+
+  meta.status = "iterating";
+  writeMetadata(wsPath, meta);
+
+  for (let i = 0; i < cycles; i++) {
+    const iterNum = startIterNum + i;
+    const iterStart = Date.now();
+    const iterSteps = [];
+
+    // Snapshot source files before
+    const srcBefore = snapshotDir(join(wsPath, "src/lib"));
+
+    for (const step of stepsToRun) {
+      const stepStart = Date.now();
+      const result = runCli(
+        `${step} --target ${wsPath} --model ${meta.model}`,
+        wsPath,
+        300000,
+      );
+      const stepElapsed = ((Date.now() - stepStart) / 1000).toFixed(1);
+      iterSteps.push({
+        step,
+        success: result.success,
+        elapsed: stepElapsed,
+        output: result.output.substring(0, 500),
+      });
+    }
+
+    // Run tests
+    const testResult = runInWorkspace("npm test 2>&1", wsPath, 60000);
+    const testsPassed = testResult.success;
+
+    // Snapshot source files after
+    const srcAfter = snapshotDir(join(wsPath, "src/lib"));
+    const filesChanged = countChanges(srcBefore, srcAfter);
+
+    const iterElapsed = ((Date.now() - iterStart) / 1000).toFixed(1);
+
+    const iterRecord = {
+      number: iterNum,
+      profile: meta.profile,
+      model: meta.model,
+      steps: iterSteps,
+      testsPassed,
+      filesChanged,
+      elapsed: iterElapsed,
+    };
+
+    meta.iterations.push(iterRecord);
+    writeMetadata(wsPath, meta);
+
+    results.push(iterRecord);
+
+    // Check stop conditions
+    if (testsPassed) {
+      consecutivePasses++;
+      if (consecutivePasses >= 2) {
+        results.push({ stopped: true, reason: "tests passed for 2 consecutive iterations" });
+        break;
+      }
+    } else {
+      consecutivePasses = 0;
+    }
+
+    if (filesChanged === 0) {
+      consecutiveNoChanges++;
+      if (consecutiveNoChanges >= 2) {
+        results.push({ stopped: true, reason: "no files changed for 2 consecutive iterations (stalled)" });
+        break;
+      }
+    } else {
+      consecutiveNoChanges = 0;
+    }
+  }
+
+  meta.status = "ready";
+  writeMetadata(wsPath, meta);
+
+  // Format results
+  const lines = [`# Iterate Results: ${workspace}`, `Cycles requested: ${cycles}`, ""];
+  for (const r of results) {
+    if (r.stopped) {
+      lines.push(`**Stopped early:** ${r.reason}`);
+      continue;
+    }
+    lines.push(`## Iteration ${r.number} (${r.model}, ${r.profile})`);
+    lines.push(`- Elapsed: ${r.elapsed}s`);
+    lines.push(`- Files changed: ${r.filesChanged}`);
+    lines.push(`- Tests: ${r.testsPassed ? "PASS" : "FAIL"}`);
+    for (const s of r.steps) {
+      lines.push(`  - ${s.step}: ${s.success ? "OK" : "FAIL"} (${s.elapsed}s)`);
+    }
+    lines.push("");
+  }
+
+  const totalIters = results.filter((r) => !r.stopped).length;
+  const lastPassed = results.filter((r) => !r.stopped).slice(-1)[0]?.testsPassed;
+  lines.push("## Summary");
+  lines.push(`- Iterations completed: ${totalIters}`);
+  lines.push(`- Final test status: ${lastPassed ? "PASS" : "FAIL"}`);
+  lines.push(`- Total iterations for this workspace: ${meta.iterations.length}`);
+  lines.push(`- Profile: ${meta.profile} | Model: ${meta.model}`);
+
+  return text(lines.join("\n"));
+}
+
+async function handleRunTests({ workspace }) {
+  const wsPath = workspacePath(workspace);
+  if (!readMetadata(wsPath)) {
+    return text(`Workspace "${workspace}" not found.`);
+  }
+  const result = runInWorkspace("npm test 2>&1", wsPath, 120000);
+  return text(
+    [
+      `## Test Results: ${workspace}`,
+      "",
+      result.success ? "**PASS** — all tests passing." : "**FAIL** — tests are failing.",
+      "",
+      "```",
+      result.output.substring(0, 5000),
+      "```",
+    ].join("\n"),
+  );
+}
+
+async function handleConfigGet({ workspace }) {
+  const wsPath = workspacePath(workspace);
+  if (!readMetadata(wsPath)) {
+    return text(`Workspace "${workspace}" not found.`);
+  }
+  const tomlPath = join(wsPath, "agentic-lib.toml");
+  if (!existsSync(tomlPath)) {
+    return text("No agentic-lib.toml found in workspace.");
+  }
+  const content = readFileSync(tomlPath, "utf8");
+  return text(`## Configuration: ${workspace}\n\n\`\`\`toml\n${content}\n\`\`\``);
+}
+
+async function handleConfigSet({ workspace, profile, model, overrides }) {
+  const wsPath = workspacePath(workspace);
+  const meta = readMetadata(wsPath);
+  if (!meta) {
+    return text(`Workspace "${workspace}" not found.`);
+  }
+
+  const tomlPath = join(wsPath, "agentic-lib.toml");
+  if (!existsSync(tomlPath)) {
+    return text("No agentic-lib.toml found in workspace.");
+  }
+
+  let toml = readFileSync(tomlPath, "utf8");
+  const changes = [];
+
+  if (profile) {
+    toml = toml.replace(/^profile\s*=\s*"[^"]*"/m, `profile = "${profile}"`);
+    meta.profile = profile;
+    if (!model) {
+      meta.model = profileDefaultModel(profile);
+    }
+    changes.push(`profile -> ${profile}`);
+  }
+
+  if (model) {
+    toml = toml.replace(/^model\s*=\s*"[^"]*"/m, `model = "${model}"`);
+    meta.model = model;
+    changes.push(`model -> ${model}`);
+  }
+
+  if (overrides) {
+    for (const [key, value] of Object.entries(overrides)) {
+      const regex = new RegExp(`^${key}\\s*=\\s*.*$`, "m");
+      const line = typeof value === "string" ? `${key} = "${value}"` : `${key} = ${value}`;
+      if (regex.test(toml)) {
+        toml = toml.replace(regex, line);
+      } else {
+        // Add under [tuning] section
+        toml = toml.replace(/^\[tuning\]/m, `[tuning]\n${line}`);
+      }
+      changes.push(`${key} -> ${value}`);
+    }
+  }
+
+  writeFileSync(tomlPath, toml);
+  writeMetadata(wsPath, meta);
+
+  return text(`Configuration updated for ${workspace}:\n${changes.map((c) => `- ${c}`).join("\n")}`);
+}
+
+async function handlePrepareIteration({ workspace, focus = "transform" }) {
+  const wsPath = workspacePath(workspace);
+  const meta = readMetadata(wsPath);
+  if (!meta) {
+    return text(`Workspace "${workspace}" not found.`);
+  }
+
+  const sections = [];
+  const iterNum = (meta.iterations?.length || 0) + 1;
+
+  sections.push(`# Iteration ${iterNum} — ${focus}`);
+  sections.push(`Workspace: ${meta.id} | Profile: ${meta.profile}`);
+  sections.push("");
+
+  // Mission
+  const missionFile = join(wsPath, "MISSION.md");
+  if (existsSync(missionFile)) {
+    sections.push("## Mission", readFileSync(missionFile, "utf8"), "");
+  }
+
+  // Features
+  const featuresDir = join(wsPath, "features");
+  if (existsSync(featuresDir)) {
+    const features = readdirSync(featuresDir).filter((f) => f.endsWith(".md"));
+    if (features.length > 0) {
+      sections.push(`## Features (${features.length})`);
+      for (const f of features.slice(0, 10)) {
+        sections.push(`### ${f}`, readFileSync(join(featuresDir, f), "utf8"), "");
+      }
+    }
+  }
+
+  // Source files
+  const srcDir = join(wsPath, "src/lib");
+  if (existsSync(srcDir)) {
+    const srcFiles = readdirSync(srcDir, { recursive: true })
+      .filter((f) => String(f).match(/\.(js|ts)$/))
+      .slice(0, 20);
+    sections.push(`## Source Files (${srcFiles.length})`);
+    for (const f of srcFiles) {
+      const content = readFileSync(join(srcDir, String(f)), "utf8");
+      sections.push(`### src/lib/${f}`, "```js", content.substring(0, 5000), "```", "");
+    }
+  }
+
+  // Test files
+  const testsDir = join(wsPath, "tests/unit");
+  if (existsSync(testsDir)) {
+    const testFiles = readdirSync(testsDir, { recursive: true })
+      .filter((f) => String(f).match(/\.(js|ts)$/))
+      .slice(0, 10);
+    sections.push(`## Test Files (${testFiles.length})`);
+    for (const f of testFiles) {
+      const content = readFileSync(join(testsDir, String(f)), "utf8");
+      sections.push(`### tests/unit/${f}`, "```js", content.substring(0, 3000), "```", "");
+    }
+  }
+
+  // Current test results
+  const testResult = runInWorkspace("npm test 2>&1", wsPath, 60000);
+  sections.push("## Current Test Results");
+  sections.push(testResult.success ? "**All tests passing.**" : "**Tests failing.**");
+  sections.push("```", testResult.output.substring(0, 3000), "```", "");
+
+  // Instructions based on focus
+  sections.push("## Your Task");
+  if (focus === "transform") {
+    sections.push(
+      "Analyze the mission, features, and source code above.",
+      "Determine the single most impactful next step to advance the code toward the mission.",
+      "Then implement it by calling `workspace_write_file` to modify source files.",
+      "After writing, call `run_tests` to verify your changes.",
+    );
+  } else if (focus === "maintain-features") {
+    sections.push(
+      "Review the mission and current features.",
+      "Create, update, or prune feature files to keep the project focused on its mission.",
+      "Use `workspace_write_file` to write feature files to `features/<name>.md`.",
+      "Each feature should have clear, testable acceptance criteria.",
+    );
+  } else if (focus === "fix-code") {
+    sections.push(
+      "The test output above shows failing tests.",
+      "Analyze the failures and fix the source code.",
+      "Make minimal, targeted changes using `workspace_write_file`.",
+      "Then call `run_tests` to verify the fix.",
+    );
+  }
+  sections.push("");
+  sections.push("## Writable Paths");
+  sections.push("- src/lib/ (source code)");
+  sections.push("- tests/unit/ (test files)");
+  sections.push("- features/ (feature specs)");
+  sections.push("- examples/ (output artifacts)");
+  sections.push("- README.md, package.json");
+
+  return text(sections.join("\n"));
+}
+
+async function handleWorkspaceReadFile({ workspace, path }) {
+  const wsPath = workspacePath(workspace);
+  if (!readMetadata(wsPath)) {
+    return text(`Workspace "${workspace}" not found.`);
+  }
+  const filePath = resolve(wsPath, path);
+  // Prevent path traversal
+  if (!filePath.startsWith(wsPath)) {
+    return text(`Path traversal not allowed: ${path}`);
+  }
+  if (!existsSync(filePath)) {
+    return text(`File not found: ${path}`);
+  }
+  const content = readFileSync(filePath, "utf8");
+  return text(`## ${path}\n\n\`\`\`\n${content}\n\`\`\``);
+}
+
+async function handleWorkspaceWriteFile({ workspace, path, content }) {
+  const wsPath = workspacePath(workspace);
+  if (!readMetadata(wsPath)) {
+    return text(`Workspace "${workspace}" not found.`);
+  }
+  const filePath = resolve(wsPath, path);
+  if (!filePath.startsWith(wsPath)) {
+    return text(`Path traversal not allowed: ${path}`);
+  }
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(filePath, content, "utf8");
+  return text(`Written ${content.length} chars to ${path}`);
+}
+
+async function handleWorkspaceExec({ workspace, command }) {
+  const wsPath = workspacePath(workspace);
+  if (!readMetadata(wsPath)) {
+    return text(`Workspace "${workspace}" not found.`);
+  }
+  // Block git write commands
+  const blocked = /\bgit\s+(commit|push|add|reset|checkout|rebase|merge|stash)\b/;
+  if (blocked.test(command)) {
+    return text(`Git write commands are not allowed: ${command}`);
+  }
+  const result = runInWorkspace(command, wsPath, 120000);
+  return text(
+    [
+      `## exec: ${command}`,
+      `Exit code: ${result.exitCode || 0}`,
+      "```",
+      result.output.substring(0, 5000),
+      "```",
+    ].join("\n"),
+  );
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function text(content) {
+  return { content: [{ type: "text", text: content }] };
+}
+
+function profileDefaultModel(profile) {
+  const models = { min: "gpt-5-mini", recommended: "claude-sonnet-4", max: "gpt-4.1" };
+  return models[profile] || "gpt-5-mini";
+}
+
+function snapshotDir(dirPath) {
+  const snapshot = {};
+  if (!existsSync(dirPath)) return snapshot;
+  try {
+    const files = readdirSync(dirPath, { recursive: true });
+    for (const f of files) {
+      const fp = join(dirPath, String(f));
+      try {
+        snapshot[String(f)] = readFileSync(fp, "utf8");
+      } catch {
+        // skip non-readable files
+      }
+    }
+  } catch {
+    // skip unreadable dirs
+  }
+  return snapshot;
+}
+
+function countChanges(before, after) {
+  let changes = 0;
+  const allKeys = new Set([...Object.keys(before), ...Object.keys(after)]);
+  for (const key of allKeys) {
+    if (before[key] !== after[key]) changes++;
+  }
+  return changes;
+}
+
+// ─── MCP Server ─────────────────────────────────────────────────────
+
+const toolHandlers = {
+  list_missions: handleListMissions,
+  workspace_create: handleWorkspaceCreate,
+  workspace_list: handleWorkspaceList,
+  workspace_status: handleWorkspaceStatus,
+  workspace_destroy: handleWorkspaceDestroy,
+  iterate: handleIterate,
+  run_tests: handleRunTests,
+  config_get: handleConfigGet,
+  config_set: handleConfigSet,
+  prepare_iteration: handlePrepareIteration,
+  workspace_read_file: handleWorkspaceReadFile,
+  workspace_write_file: handleWorkspaceWriteFile,
+  workspace_exec: handleWorkspaceExec,
+};
+
+export async function startServer() {
+  const pkg = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8"));
+
+  const server = new Server(
+    { name: "agentic-lib", version: pkg.version },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const handler = toolHandlers[name];
+    if (!handler) {
+      return text(`Unknown tool: ${name}`);
+    }
+    try {
+      return await handler(args || {});
+    } catch (err) {
+      return text(`Error in ${name}: ${err.message}\n${err.stack || ""}`);
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/src/seeds/zero-package.json

@@ -14,7 +14,7 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@xn-intenton-z2a/agentic-lib": "^7.1.57"
+    "@xn-intenton-z2a/agentic-lib": "^7.1.59"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.18",