poe-code 3.0.101 → 3.0.102

package/dist/index.js

@@ -714,16 +714,16 @@ function getConfigFormat(pathOrFormat) {
   }
   return formatRegistry[formatName];
 }
-function detectFormat(path24) {
-  const ext = getExtension(path24);
+function detectFormat(path27) {
+  const ext = getExtension(path27);
   return extensionMap[ext];
 }
-function getExtension(path24) {
-  const lastDot = path24.lastIndexOf(".");
+function getExtension(path27) {
+  const lastDot = path27.lastIndexOf(".");
   if (lastDot === -1) {
     return "";
   }
-  return path24.slice(lastDot).toLowerCase();
+  return path27.slice(lastDot).toLowerCase();
 }
 var formatRegistry, extensionMap;
 var init_formats = __esm({
@@ -1054,8 +1054,8 @@ async function applyChmod(mutation, context, options) {
     };
   }
   try {
-    const stat6 = await context.fs.stat(targetPath);
-    const currentMode = typeof stat6.mode === "number" ? stat6.mode & 511 : null;
+    const stat8 = await context.fs.stat(targetPath);
+    const currentMode = typeof stat8.mode === "number" ? stat8.mode & 511 : null;
     if (currentMode === mutation.mode) {
       return {
         outcome: { changed: false, effect: "none", detail: "noop" },
@@ -1450,38 +1450,38 @@ import { createTwoFilesPatch } from "diff";
 import chalk from "chalk";
 function createDryRunFileSystem(base, recorder) {
   const proxy = {
-    async readFile(path24, encoding) {
+    async readFile(path27, encoding) {
       if (encoding) {
-        return base.readFile(path24, encoding);
+        return base.readFile(path27, encoding);
       }
-      return base.readFile(path24);
+      return base.readFile(path27);
     },
-    async writeFile(path24, data, options) {
-      const previousContent = await tryReadText(base, path24);
+    async writeFile(path27, data, options) {
+      const previousContent = await tryReadText(base, path27);
       const nextContent = formatData(data, options?.encoding);
       recorder.record({
         type: "writeFile",
-        path: path24,
+        path: path27,
         nextContent,
         previousContent
       });
     },
-    async mkdir(path24, options) {
-      recorder.record({ type: "mkdir", path: path24, options });
+    async mkdir(path27, options) {
+      recorder.record({ type: "mkdir", path: path27, options });
     },
-    async stat(path24) {
-      return base.stat(path24);
+    async stat(path27) {
+      return base.stat(path27);
     },
-    async unlink(path24) {
-      recorder.record({ type: "unlink", path: path24 });
+    async unlink(path27) {
+      recorder.record({ type: "unlink", path: path27 });
     },
-    async readdir(path24) {
-      return base.readdir(path24);
+    async readdir(path27) {
+      return base.readdir(path27);
     }
   };
   if (typeof base.rm === "function") {
-    proxy.rm = async (path24, options) => {
-      recorder.record({ type: "rm", path: path24, options });
+    proxy.rm = async (path27, options) => {
+      recorder.record({ type: "rm", path: path27, options });
     };
   }
   if (typeof base.copyFile === "function") {
@@ -1571,8 +1571,8 @@ function describeWriteChange(previous, next) {
   }
   return "update";
 }
-function renderWriteCommand(path24, change) {
-  const command = `cat > ${path24}`;
+function renderWriteCommand(path27, change) {
+  const command = `cat > ${path27}`;
   if (change === "create") {
     return renderOperationCommand(command, chalk.green, "# create");
   }
@@ -1734,9 +1734,9 @@ function redactTomlLine(line) {
   }
   return line;
 }
-async function tryReadText(base, path24) {
+async function tryReadText(base, path27) {
   try {
-    return await base.readFile(path24, "utf8");
+    return await base.readFile(path27, "utf8");
   } catch (error2) {
     if (isNotFound(error2)) {
       return null;
@@ -3730,21 +3730,21 @@ async function* adaptClaude(lines) {
         if (blockType !== "tool_result") continue;
         const kind = toolKindsById.get(item.tool_use_id);
         toolKindsById.delete(item.tool_use_id);
-        let path24;
+        let path27;
         if (typeof item.content === "string") {
-          path24 = item.content;
+          path27 = item.content;
         } else {
           try {
-            path24 = JSON.stringify(item.content);
+            path27 = JSON.stringify(item.content);
           } catch {
-            path24 = String(item.content);
+            path27 = String(item.content);
           }
         }
         yield {
           event: "tool_complete",
           id: item.tool_use_id,
           kind,
-          path: path24
+          path: path27
         };
       }
     }
@@ -3866,10 +3866,10 @@ async function* adaptCodex(lines) {
         const kindFromStart = toolKindById.get(item.id);
         const kind = kindFromStart ?? (itemType === "command_execution" ? "exec" : itemType === "file_edit" ? "edit" : "other");
         const titleFromEvent = isNonEmptyString(item.path) ? item.path : itemType === "mcp_tool_call" ? `${isNonEmptyString(item.server) ? item.server : "unknown"}.${isNonEmptyString(item.tool) ? item.tool : "unknown"}` : void 0;
-        const path24 = titleFromEvent ?? toolTitleById.get(item.id) ?? "";
+        const path27 = titleFromEvent ?? toolTitleById.get(item.id) ?? "";
         toolTitleById.delete(item.id);
         toolKindById.delete(item.id);
-        yield { event: "tool_complete", id: item.id, kind, path: path24 };
+        yield { event: "tool_complete", id: item.id, kind, path: path27 };
       }
     }
   }
@@ -4311,7 +4311,7 @@ function updateSessionFromEvent(ctx, event, toolCallsById) {
   }
   const id = readString(event.id);
   const kind = readString(event.kind);
-  const path24 = readString(event.path);
+  const path27 = readString(event.path);
   let toolCall = id ? toolCallsById.get(id) : void 0;
   if (!toolCall) {
     toolCall = {};
@@ -4326,8 +4326,8 @@ function updateSessionFromEvent(ctx, event, toolCallsById) {
   if (kind) {
     toolCall.kind = kind;
   }
-  if (path24) {
-    toolCall.path = path24;
+  if (path27) {
+    toolCall.path = path27;
   }
 }
 var sessionCapture;
@@ -4835,15 +4835,142 @@ var init_spawn_core = __esm({
   }
 });
 
-// src/cli/environment.ts
+// packages/poe-code-config/src/schema.ts
+var init_schema = __esm({
+  "packages/poe-code-config/src/schema.ts"() {
+    "use strict";
+  }
+});
+
+// packages/poe-code-config/src/store.ts
 import path7 from "node:path";
+async function readDocument(fs3, filePath) {
+  try {
+    const raw = await fs3.readFile(filePath, "utf8");
+    return await parseDocument(fs3, filePath, raw);
+  } catch (error2) {
+    if (isNotFound(error2)) {
+      return {};
+    }
+    throw error2;
+  }
+}
+async function writeScope(fs3, filePath, scope, values) {
+  const document = await readDocument(fs3, filePath);
+  const normalizedValues = normalizeScopeValues(values);
+  if (Object.keys(normalizedValues).length === 0) {
+    delete document[scope];
+  } else {
+    document[scope] = normalizedValues;
+  }
+  await writeDocument(fs3, filePath, document);
+}
+async function parseDocument(fs3, filePath, raw) {
+  try {
+    return normalizeDocument(JSON.parse(raw));
+  } catch (error2) {
+    if (error2 instanceof SyntaxError) {
+      await recoverInvalidDocument(fs3, filePath, raw);
+      return {};
+    }
+    throw error2;
+  }
+}
+function normalizeDocument(value) {
+  if (!isRecord2(value)) {
+    return {};
+  }
+  const document = {};
+  for (const [scope, scopeValues] of Object.entries(value)) {
+    const normalizedValues = normalizeScopeValues(scopeValues);
+    if (Object.keys(normalizedValues).length > 0) {
+      document[scope] = normalizedValues;
+    }
+  }
+  return document;
+}
+function normalizeScopeValues(value) {
+  if (!isRecord2(value)) {
+    return {};
+  }
+  const normalized = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry !== void 0) {
+      normalized[key] = entry;
+    }
+  }
+  return normalized;
+}
+async function writeDocument(fs3, filePath, document) {
+  await fs3.mkdir(path7.dirname(filePath), { recursive: true });
+  await fs3.writeFile(filePath, `${JSON.stringify(document, null, 2)}
+`, {
+    encoding: "utf8"
+  });
+}
+async function recoverInvalidDocument(fs3, filePath, content) {
+  await fs3.mkdir(path7.dirname(filePath), { recursive: true });
+  const backupPath = createInvalidBackupPath(filePath);
+  await fs3.writeFile(backupPath, content, { encoding: "utf8" });
+  await fs3.writeFile(filePath, EMPTY_DOCUMENT, { encoding: "utf8" });
+}
+function createInvalidBackupPath(filePath) {
+  const directory = path7.dirname(filePath);
+  const baseName = path7.basename(filePath);
+  return path7.join(directory, `${baseName}.invalid-${createTimestamp()}.json`);
+}
+function isRecord2(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function resolveConfigPath(homeDir) {
+  return path7.join(homeDir, ".poe-code", "config.json");
+}
+var EMPTY_DOCUMENT;
+var init_store = __esm({
+  "packages/poe-code-config/src/store.ts"() {
+    "use strict";
+    init_src2();
+    EMPTY_DOCUMENT = `${JSON.stringify({}, null, 2)}
+`;
+  }
+});
+
+// packages/poe-code-config/src/resolve.ts
+var init_resolve = __esm({
+  "packages/poe-code-config/src/resolve.ts"() {
+    "use strict";
+  }
+});
+
+// packages/poe-code-config/src/config.ts
+var init_config = __esm({
+  "packages/poe-code-config/src/config.ts"() {
+    "use strict";
+    init_store();
+    init_resolve();
+  }
+});
+
+// packages/poe-code-config/src/index.ts
+var init_src6 = __esm({
+  "packages/poe-code-config/src/index.ts"() {
+    "use strict";
+    init_schema();
+    init_config();
+    init_resolve();
+    init_store();
+  }
+});
+
+// src/cli/environment.ts
+import path8 from "node:path";
 function createCliEnvironment(init) {
   const platform = init.platform ?? process.platform;
   const variables = init.variables ?? process.env;
   const configPath = resolveConfigPath(init.homeDir);
   const logDir = resolveLogDir(init.homeDir);
   const { poeApiBaseUrl, poeBaseUrl } = resolvePoeBaseUrls(variables);
-  const resolveHomePath = (...segments) => path7.join(init.homeDir, ...segments);
+  const resolveHomePath = (...segments) => path8.join(init.homeDir, ...segments);
   const getVariable = (name) => variables[name];
   return {
     cwd: init.cwd,
@@ -4858,11 +4985,8 @@ function createCliEnvironment(init) {
     getVariable
   };
 }
-function resolveConfigPath(homeDir) {
-  return path7.join(homeDir, ".poe-code", "config.json");
-}
 function resolveLogDir(homeDir) {
-  return path7.join(homeDir, ".poe-code", "logs");
+  return path8.join(homeDir, ".poe-code", "logs");
 }
 function resolvePoeBaseUrls(variables) {
   const raw = variables.POE_BASE_URL;
@@ -4941,6 +5065,7 @@ var DEFAULT_POE_API_BASE_URL;
 var init_environment = __esm({
   "src/cli/environment.ts"() {
     "use strict";
+    init_src6();
     DEFAULT_POE_API_BASE_URL = "https://api.poe.com/v1";
   }
 });
@@ -5555,7 +5680,7 @@ var init_logger2 = __esm({
 });
 
 // src/cli/error-logger.ts
-import path8 from "node:path";
+import path9 from "node:path";
 var DEFAULT_MAX_SIZE, DEFAULT_MAX_BACKUPS, ErrorLogger;
 var init_error_logger = __esm({
   "src/cli/error-logger.ts"() {
@@ -5572,7 +5697,7 @@ var init_error_logger = __esm({
       fileLoggingAvailable;
       constructor(options) {
         this.fs = options.fs;
-        this.logFilePath = path8.join(options.logDir, "errors.log");
+        this.logFilePath = path9.join(options.logDir, "errors.log");
         this.logToStderr = options.logToStderr ?? true;
         this.maxSize = options.maxSize ?? DEFAULT_MAX_SIZE;
         this.maxBackups = options.maxBackups ?? DEFAULT_MAX_BACKUPS;
@@ -5691,7 +5816,7 @@ ${entry.stack}`);
         return `${this.logFilePath}.${index}`;
       }
       ensureLogDirectory() {
-        const directory = path8.dirname(this.logFilePath);
+        const directory = path9.dirname(this.logFilePath);
         try {
           if (!this.fs.existsSync(directory)) {
             this.fs.mkdirSync(directory, { recursive: true });
@@ -5709,7 +5834,7 @@ ${entry.stack}`);
 });
 
 // src/providers/index.ts
-import path9 from "node:path";
+import path10 from "node:path";
 import { readdir } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
 function isProviderModule(filename) {
@@ -5736,7 +5861,7 @@ async function loadProviders() {
   for (const entry of entries) {
     if (!entry.isFile()) continue;
     if (!isProviderModule(entry.name)) continue;
-    const moduleUrl = pathToFileURL(path9.join(currentDir, entry.name)).href;
+    const moduleUrl = pathToFileURL(path10.join(currentDir, entry.name)).href;
     const moduleExports = await import(moduleUrl);
     if (!moduleExports.provider) {
       throw new Error(`Provider module "${entry.name}" must export "provider".`);
@@ -5752,8 +5877,8 @@ var moduleDir, currentDir, defaultProviders;
 var init_providers = __esm({
   async "src/providers/index.ts"() {
     "use strict";
-    moduleDir = path9.dirname(fileURLToPath(import.meta.url));
-    currentDir = path9.basename(moduleDir) === "providers" ? moduleDir : path9.join(moduleDir, "providers");
+    moduleDir = path10.dirname(fileURLToPath(import.meta.url));
+    currentDir = path10.basename(moduleDir) === "providers" ? moduleDir : path10.join(moduleDir, "providers");
     defaultProviders = await loadProviders();
   }
 });
@@ -6095,21 +6220,21 @@ function createSdkContainer(options) {
   });
   loggerFactory.setErrorLogger(errorLogger);
   const asyncFs = {
-    readFile: ((path24, encoding) => {
+    readFile: ((path27, encoding) => {
       if (encoding) {
-        return fs2.readFile(path24, encoding);
+        return fs2.readFile(path27, encoding);
       }
-      return fs2.readFile(path24);
+      return fs2.readFile(path27);
     }),
-    writeFile: (path24, data, opts) => fs2.writeFile(path24, data, opts),
-    mkdir: (path24, opts) => fs2.mkdir(path24, opts).then(() => {
+    writeFile: (path27, data, opts) => fs2.writeFile(path27, data, opts),
+    mkdir: (path27, opts) => fs2.mkdir(path27, opts).then(() => {
     }),
-    stat: (path24) => fs2.stat(path24),
-    rm: (path24, opts) => fs2.rm(path24, opts),
-    unlink: (path24) => fs2.unlink(path24),
-    readdir: (path24) => fs2.readdir(path24),
+    stat: (path27) => fs2.stat(path27),
+    rm: (path27, opts) => fs2.rm(path27, opts),
+    unlink: (path27) => fs2.unlink(path27),
+    readdir: (path27) => fs2.readdir(path27),
     copyFile: (src, dest) => fs2.copyFile(src, dest),
-    chmod: (path24, mode) => fs2.chmod(path24, mode)
+    chmod: (path27, mode) => fs2.chmod(path27, mode)
   };
   const contextFactory = createCommandContextFactory({ fs: asyncFs });
   const authFs = {
@@ -6811,8 +6936,8 @@ function resourceNotFound(resource) {
     `Resource not found: ${resource}`
   );
 }
-function assertAbsolutePath(path24) {
-  if (!isAbsolute(path24)) {
+function assertAbsolutePath(path27) {
+  if (!isAbsolute(path27)) {
     throw invalidParams('"path" must be an absolute path');
   }
 }
@@ -7546,7 +7671,7 @@ var init_run_report = __esm({
 });
 
 // packages/poe-acp-client/src/index.ts
-var init_src6 = __esm({
+var init_src7 = __esm({
   "packages/poe-acp-client/src/index.ts"() {
     "use strict";
     init_acp_client();
@@ -8573,7 +8698,7 @@ var init_acp_core = __esm({
 });
 
 // packages/poe-agent/src/plugins/plugin-args.ts
-import path10 from "node:path";
+import path11 from "node:path";
 function isObjectRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -8604,13 +8729,13 @@ function getOptionalString(args, key) {
   return value;
 }
 function resolveAllowedPath(cwd, allowedPaths, inputPath) {
-  const resolvedPath = path10.resolve(cwd, inputPath);
+  const resolvedPath = path11.resolve(cwd, inputPath);
   const isAllowed = allowedPaths.some((allowedPath) => {
     if (allowedPath === resolvedPath) {
       return true;
     }
-    const rel = path10.relative(allowedPath, resolvedPath);
-    return rel.length > 0 && !rel.startsWith("..") && !path10.isAbsolute(rel);
+    const rel = path11.relative(allowedPath, resolvedPath);
+    return rel.length > 0 && !rel.startsWith("..") && !path11.isAbsolute(rel);
   });
   if (!isAllowed) {
     throw new Error(`Path is outside allowed paths: ${inputPath}`);
@@ -8625,7 +8750,7 @@ var init_plugin_args = __esm({
 
 // packages/poe-agent/src/plugins/poe-agent-plugin-files.ts
 import fsPromises2 from "node:fs/promises";
-import path11 from "node:path";
+import path12 from "node:path";
 async function fileExists(fs3, filePath) {
   try {
     await fs3.readFile(filePath, "utf8");
@@ -8649,9 +8774,9 @@ var init_poe_agent_plugin_files = __esm({
     "use strict";
     init_plugin_args();
     filesPlugin = (options = {}) => {
-      const cwd = path11.resolve(options.cwd ?? process.cwd());
+      const cwd = path12.resolve(options.cwd ?? process.cwd());
       const allowedPaths = (options.allowedPaths ?? [cwd]).map(
-        (allowedPath) => path11.resolve(cwd, allowedPath)
+        (allowedPath) => path12.resolve(cwd, allowedPath)
       );
       const fs3 = options.fs ?? fsPromises2;
       const readFileTool = {
@@ -8705,7 +8830,7 @@ var init_poe_agent_plugin_files = __esm({
         async call(args) {
           const command = getRequiredString(args, "command");
           const filePath = resolveAllowedPath(cwd, allowedPaths, getRequiredString(args, "path"));
-          const displayedPath = path11.relative(cwd, filePath) || path11.basename(filePath);
+          const displayedPath = path12.relative(cwd, filePath) || path12.basename(filePath);
           if (command === "str_replace") {
             const oldStr = getRequiredString(args, "old_str", true);
             const newStr = getRequiredString(args, "new_str", true);
@@ -8725,7 +8850,7 @@ var init_poe_agent_plugin_files = __esm({
             if (await fileExists(fs3, filePath)) {
               throw new Error("File already exists \u2014 use str_replace to edit");
             }
-            await fs3.mkdir(path11.dirname(filePath), { recursive: true });
+            await fs3.mkdir(path12.dirname(filePath), { recursive: true });
             await fs3.writeFile(filePath, fileText, "utf8");
             return `Created file: ${displayedPath}`;
           }
@@ -8766,7 +8891,7 @@ var init_poe_agent_plugin_files = __esm({
 
 // packages/poe-agent/src/plugins/poe-agent-plugin-shell.ts
 import { exec as execCallback } from "node:child_process";
-import path12 from "node:path";
+import path13 from "node:path";
 import { promisify } from "node:util";
 async function defaultRunCommand(command, cwd) {
   try {
@@ -8799,9 +8924,9 @@ var init_poe_agent_plugin_shell = __esm({
     init_plugin_args();
     exec = promisify(execCallback);
     shellPlugin = (options = {}) => {
-      const cwd = path12.resolve(options.cwd ?? process.cwd());
+      const cwd = path13.resolve(options.cwd ?? process.cwd());
       const allowedPaths = (options.allowedPaths ?? [cwd]).map(
-        (allowedPath) => path12.resolve(cwd, allowedPath)
+        (allowedPath) => path13.resolve(cwd, allowedPath)
       );
       const runCommand2 = options.runCommand ?? defaultRunCommand;
       const runCommandTool = {
@@ -9585,7 +9710,7 @@ var AgentHost;
 var init_agent_host = __esm({
   "packages/poe-agent/src/runtime/agent-host.ts"() {
     "use strict";
-    init_src6();
+    init_src7();
     init_agent_session();
     init_acp_core();
     init_run_context();
@@ -9945,7 +10070,7 @@ function readDependencies(plugin) {
   }
   return normalized;
 }
-var init_config = __esm({
+var init_config2 = __esm({
   "packages/poe-agent/src/runtime/config.ts"() {
     "use strict";
   }
@@ -10872,7 +10997,7 @@ var init_internal = __esm({
 });
 
 // packages/tiny-mcp-client/src/index.ts
-var init_src7 = __esm({
+var init_src8 = __esm({
   "packages/tiny-mcp-client/src/index.ts"() {
     "use strict";
     init_internal();
@@ -10921,7 +11046,7 @@ var DEFAULT_MCP_CLIENT_INFO, PluginApiImpl;
 var init_plugin_api_impl = __esm({
   "packages/poe-agent/src/runtime/plugin-api-impl.ts"() {
     "use strict";
-    init_src7();
+    init_src8();
     init_hooks();
     DEFAULT_MCP_CLIENT_INFO = {
       name: "poe-agent",
@@ -11252,7 +11377,7 @@ var init_agent = __esm({
     init_acp_core();
     init_agent_host();
     init_hooks();
-    init_config();
+    init_config2();
     init_plugin_setup();
     init_run_context();
     ImmutableAgentBuilder = class _ImmutableAgentBuilder {
@@ -11488,7 +11613,7 @@ __export(src_exports, {
   agent: () => agent,
   createAgentSession: () => createAgentSession
 });
-var init_src8 = __esm({
+var init_src9 = __esm({
   "packages/poe-agent/src/index.ts"() {
     "use strict";
     init_agent();
@@ -11826,7 +11951,7 @@ function createInMemoryAcpTransport2(options) {
       }
       if (method === "session/new") {
         const request = params;
-        const { createAgentSession: createAgentSession2 } = await Promise.resolve().then(() => (init_src8(), src_exports));
+        const { createAgentSession: createAgentSession2 } = await Promise.resolve().then(() => (init_src9(), src_exports));
         const session = await createAgentSession2({
           model: options.model,
           cwd: request.cwd || options.cwd,
@@ -11976,7 +12101,7 @@ var init_poe_agent = __esm({
   "src/providers/poe-agent.ts"() {
     "use strict";
     init_constants();
-    init_src6();
+    init_src7();
     init_create_provider();
     poeAgentService = createProvider({
       id: "poe-agent",
@@ -12145,7 +12270,7 @@ var init_spawn3 = __esm({
 });
 
 // packages/pipeline/src/utils.ts
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isNotFound2(error2) {
@@ -12179,7 +12304,7 @@ var init_utils2 = __esm({
 });
 
 // packages/pipeline/src/config/loader.ts
-import path13 from "node:path";
+import path14 from "node:path";
 import { parse as parse4 } from "yaml";
 function asStepMode(value) {
   if (value === void 0 || value === null) {
@@ -12203,19 +12328,19 @@ function parseStepConfigDocument(filePath, content) {
   if (document === null || document === void 0) {
     return {};
   }
-  if (!isRecord2(document)) {
+  if (!isRecord3(document)) {
     throw new Error(`Invalid pipeline step config in "${filePath}": expected a top-level object.`);
   }
   const stepsValue = document.steps;
   if (stepsValue === void 0 || stepsValue === null) {
     return {};
   }
-  if (!isRecord2(stepsValue)) {
+  if (!isRecord3(stepsValue)) {
     throw new Error(`Invalid pipeline step config in "${filePath}": "steps" must be an object.`);
   }
   const steps = {};
   for (const [stepName, value] of Object.entries(stepsValue)) {
-    if (!isRecord2(value)) {
+    if (!isRecord3(value)) {
       throw new Error(`Invalid step "${stepName}" in "${filePath}": expected an object.`);
     }
     const instruction = value.instruction;
@@ -12237,7 +12362,7 @@ function parseConfigDocument(filePath, content) {
   if (document === null || document === void 0) {
     return {};
   }
-  if (!isRecord2(document)) {
+  if (!isRecord3(document)) {
     throw new Error(`Invalid pipeline config in "${filePath}": expected a top-level object.`);
   }
   const planPath = document.planPath;
@@ -12263,8 +12388,8 @@ async function loadStepsFile(fs3, filePath) {
   return parseStepConfigDocument(filePath, content);
 }
 async function loadPipelineConfig(options) {
-  const globalPath = path13.join(options.homeDir, ".poe-code", "pipeline", "config.yaml");
-  const projectPath = path13.join(options.cwd, ".poe-code", "pipeline", "config.yaml");
+  const globalPath = path14.join(options.homeDir, ".poe-code", "pipeline", "config.yaml");
+  const projectPath = path14.join(options.cwd, ".poe-code", "pipeline", "config.yaml");
   const [globalConfig2, projectConfig] = await Promise.all([
     loadConfigFile(options.fs, globalPath),
     loadConfigFile(options.fs, projectPath)
@@ -12275,8 +12400,8 @@ async function loadPipelineConfig(options) {
   };
 }
 async function loadResolvedSteps(options) {
-  const globalPath = path13.join(options.homeDir, ".poe-code", "pipeline", "steps.yaml");
-  const projectPath = path13.join(options.cwd, ".poe-code", "pipeline", "steps.yaml");
+  const globalPath = path14.join(options.homeDir, ".poe-code", "pipeline", "steps.yaml");
+  const projectPath = path14.join(options.cwd, ".poe-code", "pipeline", "steps.yaml");
   const [globalSteps, projectSteps] = await Promise.all([
     loadStepsFile(options.fs, globalPath),
     loadStepsFile(options.fs, projectPath)
@@ -12315,7 +12440,7 @@ function parseTaskStatus(value, availableSteps, taskId) {
   if (typeof value === "string") {
     return normalizeStatus(value, "task status");
   }
-  if (!isRecord2(value)) {
+  if (!isRecord3(value)) {
     throw new Error(`Invalid status for task "${taskId}": expected a string or step-status map.`);
   }
   const statusMap = {};
@@ -12335,7 +12460,7 @@ function parsePlan(yamlContent, options = {}) {
     const message = error2 instanceof Error ? error2.message : String(error2);
     throw new Error(`Invalid plan YAML: ${message}`);
   }
-  if (!isRecord2(document)) {
+  if (!isRecord3(document)) {
     throw new Error("Invalid plan YAML: expected a top-level object.");
   }
   const tasksValue = document.tasks;
@@ -12344,7 +12469,7 @@ function parsePlan(yamlContent, options = {}) {
   }
   const ids = /* @__PURE__ */ new Set();
   const tasks = tasksValue.map((value, index) => {
-    if (!isRecord2(value)) {
+    if (!isRecord3(value)) {
       throw new Error(`Invalid tasks[${index}]: expected an object.`);
     }
     const id = asRequiredString(value.id, `tasks[${index}].id`);
@@ -12369,18 +12494,18 @@ var init_parser = __esm({
 });
 
 // packages/pipeline/src/plan/discovery.ts
-import path14 from "node:path";
+import path15 from "node:path";
 import * as fsPromises3 from "node:fs/promises";
 function createDefaultFs() {
   return {
     readFile: fsPromises3.readFile,
     readdir: fsPromises3.readdir,
     stat: async (filePath) => {
-      const stat6 = await fsPromises3.stat(filePath);
+      const stat8 = await fsPromises3.stat(filePath);
       return {
-        isFile: () => stat6.isFile(),
-        isDirectory: () => stat6.isDirectory(),
-        mtimeMs: stat6.mtimeMs
+        isFile: () => stat8.isFile(),
+        isDirectory: () => stat8.isDirectory(),
+        mtimeMs: stat8.mtimeMs
       };
     }
   };
@@ -12405,10 +12530,10 @@ function countCompletedTasks(planPath, content) {
   };
 }
 async function ensurePlanExists(fs3, cwd, planPath) {
-  const absolutePath = path14.isAbsolute(planPath) ? planPath : path14.resolve(cwd, planPath);
+  const absolutePath = path15.isAbsolute(planPath) ? planPath : path15.resolve(cwd, planPath);
   try {
-    const stat6 = await fs3.stat(absolutePath);
-    if (!stat6.isFile()) {
+    const stat8 = await fs3.stat(absolutePath);
+    if (!stat8.isFile()) {
       throw new Error(`Plan not found at "${planPath}".`);
     }
   } catch (error2) {
@@ -12433,20 +12558,20 @@ async function scanPlansDir(fs3, plansDir, displayPrefix) {
     if (!isPlanCandidateFile(entry)) {
       continue;
     }
-    const absolutePath = path14.join(plansDir, entry);
-    const stat6 = await fs3.stat(absolutePath);
-    if (!stat6.isFile()) {
+    const absolutePath = path15.join(plansDir, entry);
+    const stat8 = await fs3.stat(absolutePath);
+    if (!stat8.isFile()) {
       continue;
     }
-    const displayPath = path14.join(displayPrefix, entry);
+    const displayPath = path15.join(displayPrefix, entry);
     const content = await fs3.readFile(absolutePath, "utf8");
     candidates.push(countCompletedTasks(displayPath, content));
   }
   return candidates;
 }
 async function listPlanCandidates(fs3, cwd, homeDir) {
-  const projectDir = path14.join(cwd, ".poe-code", "pipeline", "plans");
-  const globalDir = path14.join(homeDir, ".poe-code", "pipeline", "plans");
+  const projectDir = path15.join(cwd, ".poe-code", "pipeline", "plans");
+  const globalDir = path15.join(homeDir, ".poe-code", "pipeline", "plans");
   const [projectCandidates, globalCandidates] = await Promise.all([
     scanPlansDir(fs3, projectDir, ".poe-code/pipeline/plans"),
     scanPlansDir(fs3, globalDir, "~/.poe-code/pipeline/plans")
@@ -12457,9 +12582,9 @@ async function listPlanCandidates(fs3, cwd, homeDir) {
 }
 function resolveAbsolutePlanPath(planPath, cwd, homeDir) {
   if (planPath.startsWith("~/")) {
-    return path14.join(homeDir, planPath.slice(2));
+    return path15.join(homeDir, planPath.slice(2));
   }
-  return path14.isAbsolute(planPath) ? planPath : path14.resolve(cwd, planPath);
+  return path15.isAbsolute(planPath) ? planPath : path15.resolve(cwd, planPath);
 }
 async function resolvePlanPath(options) {
   const fs3 = options.fs ?? createDefaultFs();
@@ -12516,7 +12641,7 @@ var init_discovery = __esm({
 });
 
 // packages/pipeline/src/plan/writer.ts
-import { parseDocument, isMap, isSeq } from "yaml";
+import { parseDocument as parseDocument2, isMap, isSeq } from "yaml";
 function getTasksNode(document) {
   const tasksNode = document.get("tasks", true);
   if (!tasksNode || !isSeq(tasksNode)) {
@@ -12540,7 +12665,7 @@ async function readPlanFile(fs3, planPath) {
 }
 async function writeTaskStatus(options) {
   const content = await readPlanFile(options.fs, options.planPath);
-  const document = parseDocument(content);
+  const document = parseDocument2(content);
   const tasksNode = getTasksNode(document);
   const taskNode = getTaskNode(tasksNode, options.taskId);
   if (options.stepName) {
@@ -12646,11 +12771,11 @@ function createDefaultFs2() {
     },
     rmdir: fsPromises4.rmdir,
     stat: async (filePath) => {
-      const stat6 = await fsPromises4.stat(filePath);
+      const stat8 = await fsPromises4.stat(filePath);
       return {
-        isFile: () => stat6.isFile(),
-        isDirectory: () => stat6.isDirectory(),
-        mtimeMs: stat6.mtimeMs
+        isFile: () => stat8.isFile(),
+        isDirectory: () => stat8.isDirectory(),
+        mtimeMs: stat8.mtimeMs
       };
     }
   };
@@ -12683,8 +12808,8 @@ async function lockFile(filePath, options = {}) {
       if (!error2 || typeof error2 !== "object" || !("code" in error2) || error2.code !== "EEXIST") {
         throw error2;
       }
-      const stat6 = await fs3.stat(lockPath);
-      if (Date.now() - stat6.mtimeMs > staleMs) {
+      const stat8 = await fs3.stat(lockPath);
+      if (Date.now() - stat8.mtimeMs > staleMs) {
         await fs3.rmdir(lockPath);
         continue;
       }
@@ -12702,7 +12827,7 @@ var init_lock = __esm({
 });
 
 // packages/pipeline/src/run/pipeline.ts
-import path15 from "node:path";
+import path16 from "node:path";
 import * as fsPromises5 from "node:fs/promises";
 function createDefaultFs3() {
   return {
@@ -12710,11 +12835,11 @@ function createDefaultFs3() {
     writeFile: fsPromises5.writeFile,
     readdir: fsPromises5.readdir,
     stat: async (filePath) => {
-      const stat6 = await fsPromises5.stat(filePath);
+      const stat8 = await fsPromises5.stat(filePath);
       return {
-        isFile: () => stat6.isFile(),
-        isDirectory: () => stat6.isDirectory(),
-        mtimeMs: stat6.mtimeMs
+        isFile: () => stat8.isFile(),
+        isDirectory: () => stat8.isDirectory(),
+        mtimeMs: stat8.mtimeMs
       };
     },
     mkdir: async (filePath, options) => {
@@ -12738,9 +12863,9 @@ function resolveMode(stepName, steps) {
   return step.mode;
 }
 async function archivePlan(fs3, absolutePlanPath) {
-  const dir = path15.dirname(absolutePlanPath);
-  const archiveDir = path15.join(dir, "archive");
-  const archivePath = path15.join(archiveDir, path15.basename(absolutePlanPath));
+  const dir = path16.dirname(absolutePlanPath);
+  const archiveDir = path16.join(dir, "archive");
+  const archivePath = path16.join(archiveDir, path16.basename(absolutePlanPath));
   await fs3.mkdir(archiveDir, { recursive: true });
   await fs3.rename(absolutePlanPath, archivePath);
 }
@@ -12975,7 +13100,7 @@ var init_pipeline = __esm({
 });
 
 // packages/pipeline/src/index.ts
-var init_src9 = __esm({
+var init_src10 = __esm({
   "packages/pipeline/src/index.ts"() {
     "use strict";
     init_loader();
@@ -13007,7 +13132,286 @@ async function runPipeline2(options) {
 var init_pipeline2 = __esm({
   async "src/sdk/pipeline.ts"() {
     "use strict";
-    init_src9();
+    init_src10();
+    init_src5();
+    await init_spawn3();
+  }
+});
+
+// packages/ralph/src/discovery/discovery.ts
+import path17 from "node:path";
+import * as fsPromises6 from "node:fs/promises";
+function createDefaultFs4() {
+  return {
+    readFile: fsPromises6.readFile,
+    readdir: fsPromises6.readdir,
+    stat: async (filePath) => {
+      const stat8 = await fsPromises6.stat(filePath);
+      return {
+        isFile: () => stat8.isFile(),
+        mtimeMs: stat8.mtimeMs
+      };
+    }
+  };
+}
+function isNotFound3(error2) {
+  return !!error2 && typeof error2 === "object" && "code" in error2 && error2.code === "ENOENT";
+}
+function isMarkdownFile(entry) {
+  return entry.toLowerCase().endsWith(".md");
+}
+async function scanDir(fs3, absoluteDir, displayDir) {
+  let entries;
+  try {
+    entries = await fs3.readdir(absoluteDir);
+  } catch (error2) {
+    if (isNotFound3(error2)) {
+      return [];
+    }
+    throw error2;
+  }
+  const docs = [];
+  for (const entry of entries) {
+    if (!isMarkdownFile(entry)) {
+      continue;
+    }
+    const absolutePath = path17.join(absoluteDir, entry);
+    const stat8 = await fs3.stat(absolutePath);
+    if (!stat8.isFile()) {
+      continue;
+    }
+    const displayPath = path17.join(displayDir, entry);
+    docs.push({
+      path: displayPath,
+      displayPath
+    });
+  }
+  return docs;
+}
+async function discoverDocs(options) {
+  const fs3 = options.fs ?? createDefaultFs4();
+  const [localDocs, globalDocs] = await Promise.all([
+    scanDir(
+      fs3,
+      path17.join(options.cwd, ".poe-code", "ralph", "plans"),
+      ".poe-code/ralph/plans"
+    ),
+    scanDir(
+      fs3,
+      path17.join(options.homeDir, ".poe-code", "ralph", "plans"),
+      "~/.poe-code/ralph/plans"
+    )
+  ]);
+  return [...localDocs, ...globalDocs].sort((left, right) => {
+    const leftName = path17.basename(left.displayPath).toLowerCase();
+    const rightName = path17.basename(right.displayPath).toLowerCase();
+    return leftName === rightName ? left.displayPath.localeCompare(right.displayPath) : leftName.localeCompare(rightName);
+  });
+}
+var init_discovery2 = __esm({
+  "packages/ralph/src/discovery/discovery.ts"() {
+    "use strict";
+  }
+});
+
+// packages/ralph/src/overbaking/detector.ts
+var OverbakingDetector;
+var init_detector = __esm({
+  "packages/ralph/src/overbaking/detector.ts"() {
+    "use strict";
+    OverbakingDetector = class {
+      threshold;
+      consecutiveFailures = 0;
+      constructor(threshold) {
+        this.threshold = threshold;
+      }
+      record(_success) {
+        if (_success) {
+          this.consecutiveFailures = 0;
+          return {
+            consecutiveFailures: 0,
+            overbaked: false,
+            shouldWarn: false
+          };
+        }
+        this.consecutiveFailures += 1;
+        return {
+          consecutiveFailures: this.consecutiveFailures,
+          overbaked: this.consecutiveFailures >= this.threshold,
+          shouldWarn: this.consecutiveFailures === this.threshold
+        };
+      }
+    };
+  }
+});
+
+// packages/ralph/src/run/ralph.ts
+import path18 from "node:path";
+import * as fsPromises7 from "node:fs/promises";
+async function runRalph(options) {
+  const fs3 = options.fs ?? createDefaultFs5();
+  const runAgent = options.runAgent;
+  if (!runAgent) {
+    throw new Error("runRalph requires a runAgent implementation.");
+  }
+  if (!Number.isInteger(options.maxIterations) || options.maxIterations < 1) {
+    throw new Error("maxIterations must be a positive integer.");
+  }
+  const threshold = options.maxFailures ?? 3;
+  if (!Number.isInteger(threshold) || threshold < 1) {
+    throw new Error("maxFailures must be a positive integer.");
+  }
+  const absoluteDocPath = resolveAbsoluteDocPath(
+    options.docPath,
+    options.cwd,
+    options.homeDir
+  );
+  const prompt = await fs3.readFile(absoluteDocPath, "utf8");
+  const detector = new OverbakingDetector(threshold);
+  const startTime = Date.now();
+  let iterationsCompleted = 0;
+  try {
+    for (let iteration = 1; iteration <= options.maxIterations; iteration += 1) {
+      assertNotAborted5(options.signal);
+      options.onIterationStart?.(iteration, options.maxIterations);
+      const iterationStart = Date.now();
+      let result;
+      try {
+        result = await runAgent({
+          agent: options.agent,
+          prompt,
+          cwd: options.cwd,
+          ...options.model ? { model: options.model } : {},
+          ...options.signal ? { signal: options.signal } : {}
+        });
+      } catch (error2) {
+        if (isAbortError2(error2)) {
+          return {
+            stopReason: "cancelled",
+            docPath: options.docPath,
+            iterationsCompleted,
+            totalDurationMs: Date.now() - startTime
+          };
+        }
+        throw error2;
+      }
+      const success2 = result.exitCode === 0;
+      iterationsCompleted += 1;
+      options.onIterationComplete?.(
+        iteration,
+        Date.now() - iterationStart,
+        success2
+      );
+      const overbake = detector.record(success2);
+      if (!overbake.shouldWarn) {
+        continue;
+      }
+      options.onOverbakeWarning?.(
+        overbake.consecutiveFailures,
+        threshold
+      );
+      const action = options.promptOverbake ? await options.promptOverbake({
+        consecutiveFailures: overbake.consecutiveFailures,
+        threshold
+      }) : "abort";
+      if (action === "abort") {
+        return {
+          stopReason: "overbake_abort",
+          docPath: options.docPath,
+          iterationsCompleted,
+          totalDurationMs: Date.now() - startTime
+        };
+      }
+    }
+  } catch (error2) {
+    if (isAbortError2(error2)) {
+      return {
+        stopReason: "cancelled",
+        docPath: options.docPath,
+        iterationsCompleted,
+        totalDurationMs: Date.now() - startTime
+      };
+    }
+    throw error2;
+  }
+  return {
+    stopReason: "max_iterations",
+    docPath: options.docPath,
+    iterationsCompleted,
+    totalDurationMs: Date.now() - startTime
+  };
+}
+function createDefaultFs5() {
+  return {
+    readFile: fsPromises7.readFile,
+    readdir: fsPromises7.readdir,
+    stat: async (filePath) => {
+      const stat8 = await fsPromises7.stat(filePath);
+      return {
+        isFile: () => stat8.isFile(),
+        mtimeMs: stat8.mtimeMs
+      };
+    }
+  };
+}
+function resolveAbsoluteDocPath(docPath, cwd, homeDir) {
+  if (docPath.startsWith("~/")) {
+    return path18.join(homeDir, docPath.slice(2));
+  }
+  return path18.isAbsolute(docPath) ? docPath : path18.resolve(cwd, docPath);
+}
+function assertNotAborted5(signal) {
+  if (!signal?.aborted) {
+    return;
+  }
+  throw createAbortError4();
+}
+function createAbortError4() {
+  const error2 = new Error("Ralph run cancelled");
+  error2.name = "AbortError";
+  return error2;
+}
+function isAbortError2(error2) {
+  return error2 instanceof Error && error2.name === "AbortError";
+}
+var init_ralph = __esm({
+  "packages/ralph/src/run/ralph.ts"() {
+    "use strict";
+    init_detector();
+  }
+});
+
+// packages/ralph/src/index.ts
+var init_src11 = __esm({
+  "packages/ralph/src/index.ts"() {
+    "use strict";
+    init_discovery2();
+    init_detector();
+    init_ralph();
+  }
+});
+
+// src/sdk/ralph.ts
+async function runRalph2(options) {
+  return runRalph({
+    ...options,
+    runAgent: async (input) => {
+      const { events, result } = spawn5(input.agent, {
+        prompt: input.prompt,
+        cwd: input.cwd,
+        model: input.model,
+        mode: "yolo",
+        ...input.signal ? { signal: input.signal } : {}
+      });
+      await renderAcpStream(events);
+      return result;
+    }
+  });
+}
+var init_ralph2 = __esm({
+  async "src/sdk/ralph.ts"() {
+    "use strict";
+    init_src11();
     init_src5();
     await init_spawn3();
   }
@@ -13077,13 +13481,13 @@ async function readErrorBody(response) {
   }
 }
 function extractTextContent(data) {
-  if (!isRecord3(data)) return void 0;
+  if (!isRecord4(data)) return void 0;
   const choices = data.choices;
   if (!Array.isArray(choices) || choices.length === 0) return void 0;
   const first = choices[0];
-  if (!isRecord3(first)) return void 0;
+  if (!isRecord4(first)) return void 0;
   const message = first.message;
-  if (!isRecord3(message)) return void 0;
+  if (!isRecord4(message)) return void 0;
   return typeof message.content === "string" ? message.content : void 0;
 }
 function extractMediaFromCompletion(data) {
@@ -13091,14 +13495,14 @@ function extractMediaFromCompletion(data) {
   if (!content) return {};
   try {
     const parsed = JSON.parse(content);
-    if (isRecord3(parsed) && typeof parsed.url === "string") {
+    if (isRecord4(parsed) && typeof parsed.url === "string") {
       return {
         url: parsed.url,
         mimeType: typeof parsed.mimeType === "string" ? parsed.mimeType : void 0,
         data: typeof parsed.data === "string" ? parsed.data : void 0
       };
     }
-    if (isRecord3(parsed) && typeof parsed.data === "string") {
+    if (isRecord4(parsed) && typeof parsed.data === "string") {
       return {
         data: parsed.data,
         mimeType: typeof parsed.mimeType === "string" ? parsed.mimeType : void 0
@@ -13132,7 +13536,7 @@ function isValidUrl(value) {
     return false;
   }
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 var init_llm_client = __esm({
@@ -13375,7 +13779,7 @@ var init_oauth_client = __esm({
 });
 
 // packages/poe-oauth/src/index.ts
-var init_src10 = __esm({
+var init_src12 = __esm({
   "packages/poe-oauth/src/index.ts"() {
     "use strict";
     init_check_auth();
@@ -13426,7 +13830,7 @@ function openInBrowser(url2) {
 var init_oauth_login = __esm({
   "src/cli/oauth-login.ts"() {
     "use strict";
-    init_src10();
+    init_src12();
     init_src4();
   }
 });
@@ -13557,7 +13961,7 @@ var init_container2 = __esm({
 });
 
 // src/services/config.ts
-import path17 from "node:path";
+import path20 from "node:path";
 async function deleteConfig(options) {
   const { fs: fs3, filePath } = options;
   try {
@@ -13572,31 +13976,32 @@ async function deleteConfig(options) {
 }
 async function loadConfiguredServices(options) {
   const { fs: fs3, filePath } = options;
-  const document = await readConfigDocument(fs3, filePath);
-  return { ...document.configured_services ?? {} };
+  await migrateLegacyCredentialsIfNeeded(fs3, filePath);
+  const document = await readDocument(fs3, filePath);
+  return normalizeConfiguredServices(document[configuredServicesScope]);
 }
 async function saveConfiguredService(options) {
   const { fs: fs3, filePath, service, metadata } = options;
-  const document = await readConfigDocument(fs3, filePath);
-  const normalized = normalizeConfiguredServiceMetadata(metadata);
-  document.configured_services = {
-    ...document.configured_services ?? {},
-    [service]: normalized
-  };
-  await writeConfigDocument(fs3, filePath, document);
+  await migrateLegacyConfigIfNeeded(fs3, filePath);
+  const document = await readDocument(fs3, filePath);
+  const services = normalizeConfiguredServices(
+    document[configuredServicesScope]
+  );
+  services[service] = normalizeConfiguredServiceMetadata(metadata);
+  await writeScope(fs3, filePath, configuredServicesScope, services);
 }
 async function unconfigureService(options) {
   const { fs: fs3, filePath, service } = options;
-  const document = await readConfigDocument(fs3, filePath);
-  const services = document.configured_services;
-  if (!services || !(service in services)) {
+  await migrateLegacyConfigIfNeeded(fs3, filePath);
+  const document = await readDocument(fs3, filePath);
+  const services = normalizeConfiguredServices(
+    document[configuredServicesScope]
+  );
+  if (!(service in services)) {
     return false;
   }
   delete services[service];
-  if (Object.keys(services).length === 0) {
-    delete document.configured_services;
-  }
-  await writeConfigDocument(fs3, filePath, document);
+  await writeScope(fs3, filePath, configuredServicesScope, services);
   return true;
 }
 function normalizeConfiguredServiceMetadata(metadata) {
@@ -13611,47 +14016,78 @@ function normalizeConfiguredServiceMetadata(metadata) {
       seen.add(entry);
     }
   }
-  return {
-    files
-  };
+  return { files };
 }
-async function readConfigDocument(fs3, filePath) {
-  try {
-    const raw = await fs3.readFile(filePath, "utf8");
-    return await parseConfigDocument2(fs3, filePath, raw);
-  } catch (error2) {
-    if (isNotFound(error2)) {
-      return migrateLegacyCredentialsFile(fs3, filePath);
-    }
-    throw error2;
+async function migrateLegacyConfigIfNeeded(fs3, filePath) {
+  await migrateLegacyCredentialsIfNeeded(fs3, filePath);
+  const currentRaw = await readFileIfExists(fs3, filePath);
+  if (currentRaw === null) {
+    return;
+  }
+  const legacyDocument = normalizeLegacyConfigDocument(
+    parseLegacyConfigDocument(currentRaw)
+  );
+  if (!legacyDocument.apiKey) {
+    return;
   }
+  const document = await readDocument(fs3, filePath);
+  const existingCore = document[CORE_SCOPE] ?? {};
+  if (typeof existingCore.apiKey === "string" && existingCore.apiKey.length > 0) {
+    return;
+  }
+  await writeScope(fs3, filePath, CORE_SCOPE, {
+    ...existingCore,
+    apiKey: legacyDocument.apiKey
+  });
 }
-async function migrateLegacyCredentialsFile(fs3, configPath) {
-  const legacyPath = path17.join(path17.dirname(configPath), "credentials.json");
-  try {
-    const raw = await fs3.readFile(legacyPath, "utf8");
-    const document = await parseConfigDocument2(fs3, legacyPath, raw);
-    await writeConfigDocument(fs3, configPath, document);
-    await fs3.unlink(legacyPath);
-    return document;
-  } catch {
-    return {};
+async function migrateLegacyCredentialsIfNeeded(fs3, filePath) {
+  const currentRaw = await readFileIfExists(fs3, filePath);
+  if (currentRaw !== null) {
+    return;
   }
+  await migrateLegacyCredentialsFile(fs3, filePath);
 }
-async function parseConfigDocument2(fs3, filePath, raw) {
+async function migrateLegacyCredentialsFile(fs3, configPath) {
+  const legacyPath = path20.join(path20.dirname(configPath), "credentials.json");
+  const raw = await readFileIfExists(fs3, legacyPath);
+  if (raw === null) {
+    return;
+  }
+  let legacyDocument;
   try {
-    const parsed = JSON.parse(raw);
-    return normalizeConfigDocument(parsed);
+    legacyDocument = normalizeLegacyConfigDocument(JSON.parse(raw));
   } catch (error2) {
     if (error2 instanceof SyntaxError) {
-      await recoverInvalidConfig(fs3, filePath, raw);
-      return {};
+      await recoverInvalidConfig(fs3, legacyPath, raw);
+      await fs3.unlink(legacyPath);
+      return;
     }
     throw error2;
   }
+  if (legacyDocument.configured_services) {
+    await writeScope(
+      fs3,
+      configPath,
+      configuredServicesScope,
+      legacyDocument.configured_services
+    );
+  }
+  if (legacyDocument.apiKey) {
+    await writeScope(fs3, configPath, CORE_SCOPE, {
+      apiKey: legacyDocument.apiKey
+    });
+  }
+  await fs3.unlink(legacyPath);
+}
+function parseLegacyConfigDocument(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
 }
-function normalizeConfigDocument(value) {
-  if (!isRecord4(value)) {
+function normalizeLegacyConfigDocument(value) {
+  if (!isRecord5(value)) {
     return {};
   }
   const document = {};
@@ -13665,55 +14101,42 @@ function normalizeConfigDocument(value) {
   return document;
 }
 function normalizeConfiguredServices(value) {
-  if (!isRecord4(value)) {
+  if (!isRecord5(value)) {
     return {};
   }
   const entries = {};
   for (const [key, entry] of Object.entries(value)) {
-    if (!isRecord4(entry)) {
+    if (!isRecord5(entry)) {
       continue;
     }
-    const normalized = normalizeConfiguredServiceMetadata({
+    entries[key] = normalizeConfiguredServiceMetadata({
       files: Array.isArray(entry.files) ? entry.files : []
     });
-    entries[key] = normalized;
   }
   return entries;
 }
-async function writeConfigDocument(fs3, filePath, document) {
-  await fs3.mkdir(path17.dirname(filePath), { recursive: true });
-  const payload = {};
-  if (document.apiKey) {
-    payload.apiKey = document.apiKey;
-  }
-  if (document.configured_services) {
-    payload.configured_services = document.configured_services;
-  }
-  await fs3.writeFile(filePath, `${JSON.stringify(payload, null, 2)}
-`, {
-    encoding: "utf8"
-  });
-}
 async function recoverInvalidConfig(fs3, filePath, content) {
-  const backupPath = createInvalidBackupPath(filePath);
+  const backupPath = createInvalidBackupPath2(filePath);
   await fs3.writeFile(backupPath, content, { encoding: "utf8" });
-  await fs3.writeFile(filePath, EMPTY_DOCUMENT, { encoding: "utf8" });
+  await fs3.writeFile(filePath, EMPTY_DOCUMENT2, { encoding: "utf8" });
 }
-function createInvalidBackupPath(filePath) {
-  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const dir = path17.dirname(filePath);
-  const base = path17.basename(filePath);
-  return path17.join(dir, `${base}.invalid-${timestamp}.json`);
+function createInvalidBackupPath2(filePath) {
+  const directory = path20.dirname(filePath);
+  const baseName = path20.basename(filePath);
+  return path20.join(directory, `${baseName}.invalid-${createTimestamp()}.json`);
 }
-function isRecord4(value) {
+function isRecord5(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
-var EMPTY_DOCUMENT;
-var init_config2 = __esm({
+var CORE_SCOPE, configuredServicesScope, EMPTY_DOCUMENT2;
+var init_config3 = __esm({
   "src/services/config.ts"() {
     "use strict";
     init_src2();
-    EMPTY_DOCUMENT = `${JSON.stringify({}, null, 2)}
+    init_src6();
+    CORE_SCOPE = "core";
+    configuredServicesScope = "configured_services";
+    EMPTY_DOCUMENT2 = `${JSON.stringify({}, null, 2)}
 `;
   }
 });
@@ -13882,7 +14305,7 @@ var init_configure = __esm({
     "use strict";
     init_shared();
     init_errors();
-    init_config2();
+    init_config3();
     init_mutation_events();
     init_configure_payload();
     serviceSelectionPrompt = (action) => `Pick an agent to ${action}:`;
@@ -13906,7 +14329,7 @@ function registerAgentCommand(program, container) {
     }
     let session;
     try {
-      const { createAgentSession: createAgentSession2 } = await Promise.resolve().then(() => (init_src8(), src_exports));
+      const { createAgentSession: createAgentSession2 } = await Promise.resolve().then(() => (init_src9(), src_exports));
       session = await createAgentSession2({
         model: options.model,
         apiKey: options.apiKey,
@@ -13965,7 +14388,7 @@ var init_agent2 = __esm({
 });
 
 // src/cli/commands/spawn.ts
-import path18 from "node:path";
+import path21 from "node:path";
 function registerSpawnCommand(program, container, options = {}) {
   const spawnServices = container.registry.list().filter((service) => typeof service.spawn === "function" || getSpawnConfig(service.name)).map((service) => service.name);
   const extraServices = options.extraServices ?? [];
@@ -14176,10 +14599,10 @@ function resolveSpawnWorkingDirectory2(baseDir, candidate) {
   if (!candidate || candidate.trim().length === 0) {
     return void 0;
   }
-  if (path18.isAbsolute(candidate)) {
+  if (path21.isAbsolute(candidate)) {
     return candidate;
   }
-  return path18.resolve(baseDir, candidate);
+  return path21.resolve(baseDir, candidate);
 }
 function parseMcpSpawnConfig2(input) {
   if (!input) {
@@ -14290,7 +14713,7 @@ var init_spawn4 = __esm({
     init_src5();
     init_src3();
     init_src4();
-    init_config2();
+    init_config3();
     init_shared();
     init_spawn_core();
     await init_spawn3();
@@ -14299,7 +14722,7 @@ var init_spawn4 = __esm({
 });
 
 // src/sdk/research.ts
-import path19 from "node:path";
+import path22 from "node:path";
 async function research(container, options) {
   const logger2 = options.logger;
   const source = await resolveSource({
@@ -14334,7 +14757,7 @@ async function research(container, options) {
         markdown: markdownOutput
       });
       outputPath = buildOutputPath(container.env.homeDir, options.prompt);
-      await ensureDirectory2(container.fs, path19.dirname(outputPath));
+      await ensureDirectory2(container.fs, path22.dirname(outputPath));
       await container.fs.writeFile(outputPath, document, {
         encoding: "utf8"
       });
@@ -14409,7 +14832,7 @@ function buildResearchDocument(input) {
 }
 function buildClonePath(homeDir, github) {
   const slug = extractRepoSlug(github);
-  return path19.join(homeDir, ".poe-code", "repos", slug);
+  return path22.join(homeDir, ".poe-code", "repos", slug);
 }
 function extractRepoSlug(value) {
   const trimmed = value.trim();
@@ -14447,7 +14870,7 @@ function extractRepoSlug(value) {
 function buildOutputPath(homeDir, prompt, now = /* @__PURE__ */ new Date()) {
   const timestamp = formatTimestamp2(now);
   const slug = buildSlug(prompt);
-  return path19.join(
+  return path22.join(
     homeDir,
     ".poe-code",
     "research",
@@ -14468,7 +14891,7 @@ async function resolveSource(input) {
   if (options.github) {
     const cloneUrl = resolveGithubCloneUrl(options.github);
     const clonePath = buildClonePath(container.env.homeDir, options.github);
-    await ensureDirectory2(container.fs, path19.dirname(clonePath));
+    await ensureDirectory2(container.fs, path22.dirname(clonePath));
     const exists = await pathExists2(container.fs, clonePath);
     if (!exists) {
       const cloneResult = await container.commandRunner(
@@ -14566,10 +14989,10 @@ function formatYamlString(value) {
   return JSON.stringify(value);
 }
 function resolvePath2(baseDir, candidate) {
-  if (path19.isAbsolute(candidate)) {
+  if (path22.isAbsolute(candidate)) {
     return candidate;
   }
-  return path19.resolve(baseDir, candidate);
+  return path22.resolve(baseDir, candidate);
 }
 function teeAcpStream(events) {
   const chunks = [];
@@ -14629,7 +15052,7 @@ async function removePathFallback(fs3, target) {
   if (stats && typeof stats.isDirectory === "function" && stats.isDirectory()) {
     const entries = await fs3.readdir(target);
     for (const entry of entries) {
-      await removePathFallback(fs3, path19.join(target, entry));
+      await removePathFallback(fs3, path22.join(target, entry));
     }
   }
   try {
@@ -14796,7 +15219,7 @@ var init_research2 = __esm({
   async "src/cli/commands/research.ts"() {
     "use strict";
     init_src5();
-    init_config2();
+    init_config3();
     await init_research();
     init_errors();
     init_shared();
@@ -15026,7 +15449,7 @@ var init_login = __esm({
     "use strict";
     init_shared();
     init_errors();
-    init_config2();
+    init_config3();
     init_mutation_events();
   }
 });
@@ -15151,7 +15574,7 @@ function formatUnconfigureMessages(service, label, unconfigured, _payload) {
 var init_unconfigure = __esm({
   "src/cli/commands/unconfigure.ts"() {
     "use strict";
-    init_config2();
+    init_config3();
     init_mutation_events();
     init_isolated_env();
     init_shared();
@@ -15205,7 +15628,7 @@ async function executeLogout(program, container) {
 var init_logout = __esm({
   "src/cli/commands/logout.ts"() {
     "use strict";
-    init_config2();
+    init_config3();
     init_shared();
     init_unconfigure();
   }
@@ -15305,7 +15728,7 @@ var init_auth = __esm({
   "src/cli/commands/auth.ts"() {
     "use strict";
     init_errors();
-    init_config2();
+    init_config3();
     init_shared();
     init_login();
     init_logout();
@@ -15508,7 +15931,7 @@ var init_media_download = __esm({
 });
 
 // src/cli/commands/generate.ts
-import path20 from "node:path";
+import path23 from "node:path";
 function registerGenerateCommand(program, container) {
   const generate2 = program.command("generate").description("Generate content via Poe API").option("--model <model>", `Model identifier (default: ${DEFAULT_TEXT_MODEL})`).option(
     "--param <key=value>",
@@ -15774,11 +16197,11 @@ function getDefaultMimeType(type) {
   return defaults[type];
 }
 function resolveOutputPath(filename, cwd) {
-  if (path20.isAbsolute(filename)) {
+  if (path23.isAbsolute(filename)) {
     return { path: filename, label: filename };
   }
   return {
-    path: path20.join(cwd, filename),
+    path: path23.join(cwd, filename),
     label: `./${filename}`
   };
 }
@@ -16471,7 +16894,7 @@ function defineSchema(definition) {
     required: required2
   };
 }
-var init_schema = __esm({
+var init_schema2 = __esm({
   "packages/tiny-stdio-mcp-server/src/schema.ts"() {
     "use strict";
   }
@@ -16882,8 +17305,8 @@ var init_parseUtil = __esm({
     init_errors3();
     init_en();
     makeIssue = (params) => {
-      const { data, path: path24, errorMaps, issueData } = params;
-      const fullPath = [...path24, ...issueData.path || []];
+      const { data, path: path27, errorMaps, issueData } = params;
+      const fullPath = [...path27, ...issueData.path || []];
       const fullIssue = {
         ...issueData,
         path: fullPath
@@ -17163,11 +17586,11 @@ var init_types4 = __esm({
     init_parseUtil();
     init_util();
     ParseInputLazyPath = class {
-      constructor(parent, value, path24, key) {
+      constructor(parent, value, path27, key) {
         this._cachedPath = [];
         this.parent = parent;
         this.data = value;
-        this._path = path24;
+        this._path = path27;
         this._key = key;
       }
       get path() {
@@ -20671,10 +21094,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path24) {
-  if (!path24)
+function getElementAtPath(obj, path27) {
+  if (!path27)
     return obj;
-  return path24.reduce((acc, key) => acc?.[key], obj);
+  return path27.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -20986,11 +21409,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path24, issues) {
+function prefixIssues(path27, issues) {
   return issues.map((iss) => {
     var _a2;
     (_a2 = iss).path ?? (_a2.path = []);
-    iss.path.unshift(path24);
+    iss.path.unshift(path27);
     return iss;
   });
 }
@@ -33151,8 +33574,8 @@ var require_utils = __commonJS({
       }
       return ind;
     }
-    function removeDotSegments(path24) {
-      let input = path24;
+    function removeDotSegments(path27) {
+      let input = path27;
       const output = [];
       let nextSlash = -1;
       let len = 0;
@@ -33351,8 +33774,8 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path24, query] = wsComponent.resourceName.split("?");
-        wsComponent.path = path24 && path24 !== "/" ? path24 : void 0;
+        const [path27, query] = wsComponent.resourceName.split("?");
+        wsComponent.path = path27 && path27 !== "/" ? path27 : void 0;
         wsComponent.query = query;
         wsComponent.resourceName = void 0;
       }
@@ -36585,11 +37008,11 @@ var init_content = __esm({
 });
 
 // packages/tiny-stdio-mcp-server/src/index.ts
-var init_src11 = __esm({
+var init_src13 = __esm({
   "packages/tiny-stdio-mcp-server/src/index.ts"() {
     "use strict";
     init_server();
-    init_schema();
+    init_schema2();
     init_testing();
     init_content();
     init_types3();
@@ -36889,7 +37312,7 @@ var generateTextSchema, generateImageSchema, generateVideoSchema, generateAudioS
 var init_mcp_server = __esm({
   "src/cli/mcp-server.ts"() {
     "use strict";
-    init_src11();
+    init_src13();
     init_client_instance();
     init_constants();
     generateTextSchema = defineSchema({
@@ -37295,9 +37718,9 @@ var init_shapes = __esm({
 });
 
 // packages/agent-mcp-config/src/apply.ts
-import path21 from "node:path";
+import path24 from "node:path";
 function getConfigDirectory(configPath) {
-  return path21.dirname(configPath);
+  return path24.dirname(configPath);
 }
 function isConfigObject5(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -37399,7 +37822,7 @@ var init_apply = __esm({
 });
 
 // packages/agent-mcp-config/src/index.ts
-var init_src12 = __esm({
+var init_src14 = __esm({
   "packages/agent-mcp-config/src/index.ts"() {
     "use strict";
     init_configs2();
@@ -37579,7 +38002,7 @@ var init_mcp2 = __esm({
     init_shared();
     init_mcp_output_format();
     init_command_not_found();
-    init_src12();
+    init_src14();
     init_execution_context();
     DEFAULT_MCP_AGENT = "claude-code";
   }
@@ -37587,7 +38010,7 @@ var init_mcp2 = __esm({
 
 // packages/agent-skill-config/src/configs.ts
 import os2 from "node:os";
-import path22 from "node:path";
+import path25 from "node:path";
 function resolveAgentSupport2(input, registry2 = agentSkillConfigs) {
   const resolvedId = resolveAgentId(input);
   if (!resolvedId) {
@@ -37623,7 +38046,7 @@ var init_configs3 = __esm({
 });
 
 // packages/agent-skill-config/src/templates.ts
-import { readFile as readFile5 } from "node:fs/promises";
+import { readFile as readFile7 } from "node:fs/promises";
 async function getTemplates() {
   if (templatesCache) {
     return templatesCache;
@@ -37632,7 +38055,7 @@ async function getTemplates() {
     "./templates/poe-generate.md",
     import.meta.url
   );
-  const poeGenerateTemplate = await readFile5(poeGenerateTemplateUrl, "utf8");
+  const poeGenerateTemplate = await readFile7(poeGenerateTemplateUrl, "utf8");
   templatesCache = {
     "poe-generate.md": poeGenerateTemplate
   };
@@ -37779,7 +38202,7 @@ var init_apply2 = __esm({
 });
 
 // packages/agent-skill-config/src/index.ts
-var init_src13 = __esm({
+var init_src15 = __esm({
   "packages/agent-skill-config/src/index.ts"() {
     "use strict";
     init_configs3();
@@ -38004,7 +38427,7 @@ var init_skill = __esm({
   "src/cli/commands/skill.ts"() {
     "use strict";
     init_src4();
-    init_src13();
+    init_src15();
     init_shared();
     init_command_not_found();
     DEFAULT_SKILL_AGENT = "claude-code";
@@ -38598,8 +39021,8 @@ var init_models = __esm({
 });
 
 // src/cli/commands/pipeline.ts
-import path23 from "node:path";
-import { readFile as readFile6, stat as stat5 } from "node:fs/promises";
+import path26 from "node:path";
+import { readFile as readFile8, stat as stat7 } from "node:fs/promises";
 import { fileURLToPath as fileURLToPath4 } from "node:url";
 function formatDuration(ms) {
   const totalSeconds = Math.round(ms / 1e3);
@@ -38630,11 +39053,11 @@ function resolveMaxRuns(value) {
   return parsed;
 }
 function resolvePipelinePaths(scope, cwd, homeDir) {
-  const rootPath = scope === "global" ? path23.join(homeDir, ".poe-code", "pipeline") : path23.join(cwd, ".poe-code", "pipeline");
+  const rootPath = scope === "global" ? path26.join(homeDir, ".poe-code", "pipeline") : path26.join(cwd, ".poe-code", "pipeline");
   const displayRoot = scope === "global" ? "~/.poe-code/pipeline" : ".poe-code/pipeline";
   return {
-    plansPath: path23.join(rootPath, "plans"),
-    stepsPath: path23.join(rootPath, "steps.yaml"),
+    plansPath: path26.join(rootPath, "plans"),
+    stepsPath: path26.join(rootPath, "steps.yaml"),
     displayPlansPath: `${displayRoot}/plans`,
     displayStepsPath: `${displayRoot}/steps.yaml`
   };
@@ -38645,16 +39068,16 @@ async function loadPipelineTemplates() {
   }
   const packageRoot = await findPackageRoot(fileURLToPath4(import.meta.url));
   const templateRoots = [
-    path23.join(packageRoot, "src", "templates", "pipeline"),
-    path23.join(packageRoot, "dist", "templates", "pipeline")
+    path26.join(packageRoot, "src", "templates", "pipeline"),
+    path26.join(packageRoot, "dist", "templates", "pipeline")
   ];
   for (const templateRoot of templateRoots) {
     if (!await pathExistsOnDisk(templateRoot)) {
       continue;
     }
     const [skillPlan, steps] = await Promise.all([
-      readFile6(path23.join(templateRoot, "SKILL_plan.md"), "utf8"),
-      readFile6(path23.join(templateRoot, "steps.yaml.hbs"), "utf8")
+      readFile8(path26.join(templateRoot, "SKILL_plan.md"), "utf8"),
+      readFile8(path26.join(templateRoot, "steps.yaml.hbs"), "utf8")
     ]);
     pipelineTemplatesCache = { skillPlan, steps };
     return pipelineTemplatesCache;
@@ -38663,7 +39086,7 @@ async function loadPipelineTemplates() {
 }
 async function pathExistsOnDisk(targetPath) {
   try {
-    await stat5(targetPath);
+    await stat7(targetPath);
     return true;
   } catch (error2) {
     if (error2 && typeof error2 === "object" && "code" in error2 && error2.code === "ENOENT") {
@@ -38673,12 +39096,12 @@ async function pathExistsOnDisk(targetPath) {
   }
 }
 async function findPackageRoot(entryFilePath) {
-  let currentPath = path23.dirname(entryFilePath);
+  let currentPath = path26.dirname(entryFilePath);
   while (true) {
-    if (await pathExistsOnDisk(path23.join(currentPath, "package.json"))) {
+    if (await pathExistsOnDisk(path26.join(currentPath, "package.json"))) {
       return currentPath;
     }
-    const parentPath = path23.dirname(currentPath);
+    const parentPath = path26.dirname(currentPath);
     if (parentPath === currentPath) {
       throw new Error("Unable to locate package root for Pipeline templates.");
     }
@@ -38956,7 +39379,7 @@ function registerPipelineCommand(program, container) {
           `Would ${stepsExists ? "overwrite" : "create"}: ${pipelinePaths.displayStepsPath}`
         );
       } else {
-        await container.fs.mkdir(path23.dirname(pipelinePaths.stepsPath), {
+        await container.fs.mkdir(path26.dirname(pipelinePaths.stepsPath), {
           recursive: true
         });
         await container.fs.writeFile(pipelinePaths.stepsPath, templates.steps, {
@@ -38981,24 +39404,244 @@ var init_pipeline4 = __esm({
     "use strict";
     init_src4();
     init_src3();
-    init_src13();
+    init_src15();
     init_errors();
     init_shared();
     await init_pipeline2();
-    init_src9();
+    init_src10();
     DEFAULT_PIPELINE_AGENT = "claude-code";
     DEFAULT_PIPELINE_SCOPE = "local";
     pipelineTemplatesCache = null;
   }
 });
 
+// src/cli/commands/ralph.ts
+function formatDuration2(ms) {
+  const totalSeconds = Math.round(ms / 1e3);
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
+}
+function resolveRalphAgent(value) {
+  if (!value || value.trim().length === 0) {
+    return DEFAULT_RALPH_AGENT;
+  }
+  const resolved = resolveAgentId(value.trim());
+  if (!resolved) {
+    throw new ValidationError(`Unsupported agent: ${value}`);
+  }
+  return resolved;
+}
+function parsePositiveInt(value, fieldName) {
+  if (value == null) {
+    return void 0;
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed < 1) {
+    throw new ValidationError(
+      `Invalid ${fieldName} "${value}". Expected a positive integer.`
+    );
+  }
+  return parsed;
+}
+async function resolveAgent(options) {
+  if (options.providedAgent) {
+    return resolveRalphAgent(options.providedAgent);
+  }
+  const flags = resolveCommandFlags(options.program);
+  if (flags.assumeYes) {
+    return DEFAULT_RALPH_AGENT;
+  }
+  const selected = await select2({
+    message: "Select agent to run Ralph with:",
+    options: allSpawnConfigs.map((config2) => ({
+      label: config2.agentId,
+      value: config2.agentId
+    }))
+  });
+  if (isCancel2(selected)) {
+    cancel2("Ralph run cancelled.");
+    return null;
+  }
+  return resolveRalphAgent(typeof selected === "string" ? selected : void 0);
+}
+async function resolveDocPath(options) {
+  if (options.providedDoc && options.providedDoc.trim().length > 0) {
+    return options.providedDoc.trim();
+  }
+  const docs = await discoverDocs({
+    cwd: options.container.env.cwd,
+    homeDir: options.container.env.homeDir,
+    fs: options.container.fs
+  });
+  if (docs.length === 0) {
+    throw new ValidationError(
+      "No markdown doc found under .poe-code/ralph/plans/ or ~/.poe-code/ralph/plans/. Provide a doc path."
+    );
+  }
+  const flags = resolveCommandFlags(options.program);
+  if (flags.assumeYes) {
+    return docs[0].path;
+  }
+  const selected = await select2({
+    message: "Select the Ralph markdown doc to run:",
+    options: docs.map((doc) => ({
+      label: doc.displayPath,
+      value: doc.path
+    }))
+  });
+  if (isCancel2(selected)) {
+    cancel2("Ralph run cancelled.");
+    return null;
+  }
+  return typeof selected === "string" ? selected : null;
+}
+async function resolveIterations(options) {
+  const explicitIterations = parsePositiveInt(
+    options.providedIterations,
+    "iterations"
+  );
+  if (explicitIterations != null) {
+    return explicitIterations;
+  }
+  const flags = resolveCommandFlags(options.program);
+  if (flags.assumeYes) {
+    throw new ValidationError(
+      "Iterations are required when using --yes. Provide poe-code ralph run <iterations> [doc]."
+    );
+  }
+  const entered = await text3({
+    message: "How many Ralph iterations should run?"
+  });
+  if (isCancel2(entered)) {
+    cancel2("Ralph run cancelled.");
+    return null;
+  }
+  return parsePositiveInt(
+    typeof entered === "string" ? entered.trim() : void 0,
+    "iterations"
+  ) ?? null;
+}
+function registerRalphCommand(program, container) {
+  const ralph = program.command("ralph").description("Run a simple iterative markdown loop.");
+  ralph.command("run").description("Run the selected markdown doc through repeated agent iterations.").argument("[iterations]", "Number of Ralph iterations to run").argument("[doc]", "Markdown doc path").option("--agent <name>", "Agent to run each iteration with").option("--model <model>", "Model override passed to the agent").option(
+    "--max-failures <n>",
+    "Consecutive failure threshold before overbake protection prompts"
+  ).action(async function(iterationsArg, docArg) {
+    const flags = resolveCommandFlags(program);
+    const resources = createExecutionResources(container, flags, "ralph:run");
+    const options = this.opts();
+    resources.logger.intro("ralph run");
+    try {
+      const docPath = await resolveDocPath({
+        container,
+        program,
+        providedDoc: docArg
+      });
+      if (!docPath) {
+        return;
+      }
+      const agent2 = await resolveAgent({
+        program,
+        providedAgent: options.agent
+      });
+      if (!agent2) {
+        return;
+      }
+      const maxIterations = await resolveIterations({
+        program,
+        providedIterations: iterationsArg
+      });
+      if (maxIterations == null) {
+        return;
+      }
+      const maxFailures = parsePositiveInt(
+        options.maxFailures,
+        "max-failures"
+      );
+      const result = await runRalph2({
+        agent: agent2,
+        cwd: container.env.cwd,
+        homeDir: container.env.homeDir,
+        docPath,
+        maxIterations,
+        ...options.model ? { model: options.model } : {},
+        ...maxFailures != null ? { maxFailures } : {},
+        promptOverbake: async (input) => {
+          const selected = await select2({
+            message: `Ralph hit ${input.consecutiveFailures} consecutive failures (threshold ${input.threshold}). What should happen next?`,
+            options: [
+              { label: "Continue", value: "continue" },
+              { label: "Abort", value: "abort" }
+            ]
+          });
+          if (isCancel2(selected)) {
+            cancel2("Ralph run cancelled.");
+            return "abort";
+          }
+          return selected === "continue" ? "continue" : "abort";
+        },
+        onIterationStart(iteration, total) {
+          resources.logger.info(`Iteration ${iteration}/${total}`);
+        },
+        onIterationComplete(iteration, durationMs, success2) {
+          const status = success2 ? "done" : "failed";
+          resources.logger.info(
+            `Iteration ${iteration} ${status} in ${formatDuration2(durationMs)}`
+          );
+        },
+        onOverbakeWarning(consecutiveFailures, threshold) {
+          resources.logger.warn(
+            `Overbake protection triggered at ${consecutiveFailures} consecutive failures (threshold ${threshold}).`
+          );
+        }
+      });
+      const summary = [
+        `Iterations: ${result.iterationsCompleted}/${maxIterations}`,
+        `Doc: ${result.docPath}`,
+        `Duration: ${formatDuration2(result.totalDurationMs)}`
+      ].join("\n   ");
+      if (result.stopReason === "cancelled") {
+        process.exitCode = 130;
+        resources.logger.warn("Ralph run cancelled.");
+        resources.logger.resolved("Run summary", summary);
+        return;
+      }
+      if (result.stopReason === "overbake_abort") {
+        process.exitCode = 1;
+        resources.logger.warn("Ralph stopped after repeated failures.");
+        resources.logger.resolved("Run summary", summary);
+        return;
+      }
+      resources.logger.resolved("Run summary", summary);
+      resources.logger.success("Ralph run finished.");
+    } finally {
+      resources.context.finalize();
+    }
+  });
+}
+var DEFAULT_RALPH_AGENT;
+var init_ralph3 = __esm({
+  async "src/cli/commands/ralph.ts"() {
+    "use strict";
+    init_src4();
+    init_src3();
+    init_src5();
+    init_src11();
+    init_errors();
+    init_shared();
+    await init_ralph2();
+    DEFAULT_RALPH_AGENT = "claude-code";
+  }
+});
+
 // package.json
 var package_default;
 var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "poe-code",
-      version: "3.0.101",
+      version: "3.0.102",
       description: "CLI tool to configure Poe API for developer workflows.",
       type: "module",
       main: "./dist/index.js",
@@ -39091,6 +39734,8 @@ var init_package = __esm({
         "@poe-code/freeze-cli": "*",
         "@poe-code/pipeline": "*",
         "@poe-code/poe-acp-client": "*",
+        "@poe-code/poe-code-config": "*",
+        "@poe-code/ralph": "*",
         "@types/mustache": "^4.2.6",
         "@types/node": "^25.2.2",
         "@types/semver": "^7.7.1",
@@ -39214,6 +39859,11 @@ function formatHelpText(input) {
       args: "",
       description: "Run a fixed-step task pipeline plan"
     },
+    {
+      name: "ralph run",
+      args: "[iterations] [doc]",
+      description: "Run a markdown doc through repeated agent iterations"
+    },
     {
       name: "usage",
       args: "",
@@ -39223,11 +39873,6 @@ function formatHelpText(input) {
       name: "usage list",
       args: "",
       description: "Display usage history"
-    },
-    {
-      name: "pipeline run",
-      args: "",
-      description: "Run a fixed-step task pipeline plan"
     }
   ];
   const nameWidth = Math.max(0, ...commandRows.map((row) => row.name.length));
@@ -39377,6 +40022,7 @@ function bootstrapProgram(container) {
   registerMcpCommand(program, container);
   registerSkillCommand(program, container);
   registerPipelineCommand(program, container);
+  registerRalphCommand(program, container);
   registerUsageCommand(program, container);
   registerModelsCommand(program, container);
   program.allowExcessArguments().action(function() {
@@ -39434,6 +40080,7 @@ var init_program = __esm({
     init_usage();
     init_models();
     await init_pipeline4();
+    await init_ralph3();
     init_package();
     init_command_not_found();
     init_execution_context();
@@ -39607,6 +40254,7 @@ var init_bootstrap = __esm({
 // src/index.ts
 await init_spawn3();
 await init_pipeline2();
+await init_ralph2();
 import { realpathSync as realpathSync2 } from "node:fs";
 import { pathToFileURL as pathToFileURL3 } from "node:url";
 
@@ -39715,7 +40363,7 @@ init_src5();
 init_src4();
 init_constants();
 init_errors();
-import path16 from "node:path";
+import path19 from "node:path";
 import { Command } from "commander";
 function parseMcpSpawnConfig(input) {
   if (!input) {
@@ -39786,10 +40434,10 @@ function resolveWorkingDirectory(baseDir, candidate) {
   if (!candidate || candidate.trim().length === 0) {
     return void 0;
   }
-  if (path16.isAbsolute(candidate)) {
+  if (path19.isAbsolute(candidate)) {
     return candidate;
   }
-  return path16.resolve(baseDir, candidate);
+  return path19.resolve(baseDir, candidate);
 }
 function createPoeAgentProgram() {
   const program = new Command();
@@ -39892,6 +40540,7 @@ export {
   main,
   poeAgentMain,
   runPipeline2 as runPipeline,
+  runRalph2 as runRalph,
   spawn5 as spawn
 };
 //# sourceMappingURL=index.js.map