@ryanfw/prompt-orchestration-pipeline 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryanfw/prompt-orchestration-pipeline",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A Prompt-orchestration pipeline (POP) is a framework for building, running, and experimenting with complex chains of LLM tasks.",
   "type": "module",
   "main": "src/ui/server.js",

package/src/config/log-events.js

@@ -0,0 +1,77 @@
+/**
+ * Canonical log event constants and file extensions for the prompt orchestration pipeline.
+ * This module serves as the single source of truth for all log-related naming conventions.
+ */
+
+// Log event types for different stages and events in the pipeline
+export const LogEvent = Object.freeze({
+  START: "start",
+  COMPLETE: "complete",
+  ERROR: "error",
+  CONTEXT: "context",
+  DEBUG: "debug",
+  METRICS: "metrics",
+  PIPELINE_START: "pipeline-start",
+  PIPELINE_COMPLETE: "pipeline-complete",
+  PIPELINE_ERROR: "pipeline-error",
+  EXECUTION_LOGS: "execution-logs",
+  FAILURE_DETAILS: "failure-details",
+});
+
+// File extensions for different log types
+export const LogFileExtension = Object.freeze({
+  TEXT: "log",
+  JSON: "json",
+});
+
+// Validation sets for ensuring consistency
+export const VALID_LOG_EVENTS = new Set(Object.values(LogEvent));
+export const VALID_LOG_FILE_EXTENSIONS = new Set(
+  Object.values(LogFileExtension)
+);
+
+/**
+ * Validates a log event string.
+ * @param {string} event - Log event to validate
+ * @returns {boolean} True if valid, false otherwise
+ */
+export function isValidLogEvent(event) {
+  return VALID_LOG_EVENTS.has(event);
+}
+
+/**
+ * Validates a log file extension string.
+ * @param {string} ext - File extension to validate
+ * @returns {boolean} True if valid, false otherwise
+ */
+export function isValidLogFileExtension(ext) {
+  return VALID_LOG_FILE_EXTENSIONS.has(ext);
+}
+
+/**
+ * Normalizes a log event string to canonical form.
+ * @param {string} event - Raw log event
+ * @returns {string|null} Canonical log event or null if invalid
+ */
+export function normalizeLogEvent(event) {
+  if (typeof event !== "string") {
+    return null;
+  }
+
+  const normalized = event.toLowerCase().trim();
+  return isValidLogEvent(normalized) ? normalized : null;
+}
+
+/**
+ * Normalizes a log file extension string to canonical form.
+ * @param {string} ext - Raw file extension
+ * @returns {string|null} Canonical file extension or null if invalid
+ */
+export function normalizeLogFileExtension(ext) {
+  if (typeof ext !== "string") {
+    return null;
+  }
+
+  const normalized = ext.toLowerCase().trim().replace(/^\./, "");
+  return isValidLogFileExtension(normalized) ? normalized : null;
+}

package/src/core/file-io.js

@@ -1,6 +1,13 @@
 import fs from "node:fs/promises";
+import fsSync from "node:fs";
 import path from "node:path";
 import { writeJobStatus } from "./status-writer.js";
+import {
+  LogEvent,
+  LogFileExtension,
+  isValidLogEvent,
+  isValidLogFileExtension,
+} from "../config/log-events.js";
 
 /**
  * Creates a task-scoped file I/O interface that manages file operations
@@ -18,7 +25,17 @@ async function ensureDir(dir) {
   await fs.mkdir(dir, { recursive: true });
 }
 
-export function createTaskFileIO({ workDir, taskName, getStage, statusPath }) {
+function ensureDirSync(dir) {
+  fsSync.mkdir(dir, { recursive: true });
+}
+
+export function createTaskFileIO({
+  workDir,
+  taskName,
+  getStage,
+  statusPath,
+  trackTaskFiles = true,
+}) {
   const taskDir = path.join(workDir, "tasks", taskName);
 
   // New directory structure: {workDir}/files/{type}
@@ -34,18 +51,21 @@ export function createTaskFileIO({ workDir, taskName, getStage, statusPath }) {
     const jobDir = path.dirname(statusPath);
     await writeJobStatus(jobDir, (snapshot) => {
       snapshot.files ||= { artifacts: [], logs: [], tmp: [] };
-      snapshot.tasks ||= {};
-      snapshot.tasks[taskName] ||= {};
-      snapshot.tasks[taskName].files ||= { artifacts: [], logs: [], tmp: [] };
 
       const jobArray = snapshot.files[fileType];
       if (!jobArray.includes(fileName)) {
         jobArray.push(fileName);
       }
 
-      const taskArray = snapshot.tasks[taskName].files[fileType];
-      if (!taskArray.includes(fileName)) {
-        taskArray.push(fileName);
+      if (trackTaskFiles) {
+        snapshot.tasks ||= {};
+        snapshot.tasks[taskName] ||= {};
+        snapshot.tasks[taskName].files ||= { artifacts: [], logs: [], tmp: [] };
+
+        const taskArray = snapshot.tasks[taskName].files[fileType];
+        if (!taskArray.includes(fileName)) {
+          taskArray.push(fileName);
+        }
       }
 
       return snapshot;
@@ -61,6 +81,15 @@ export function createTaskFileIO({ workDir, taskName, getStage, statusPath }) {
     await fs.rename(tmpPath, filePath);
   }
 
+  /**
+   * Synchronous atomic write helper
+   */
+  function atomicWriteSync(filePath, data) {
+    const tmpPath = filePath + ".tmp";
+    fsSync.writeFileSync(tmpPath, data);
+    fsSync.renameSync(tmpPath, filePath);
+  }
+
   /**
    * Generic write function that handles different modes
    */
@@ -85,6 +114,54 @@ export function createTaskFileIO({ workDir, taskName, getStage, statusPath }) {
     return await fs.readFile(filePath, "utf8");
   }
 
+  /**
+   * Synchronous status writer for critical paths
+   * @param {string} jobDir - Directory containing tasks-status.json
+   * @param {Function} updater - Function that mutates and returns the snapshot
+   */
+  function writeJobStatusSync(jobDir, updater) {
+    const statusPath = path.join(jobDir, "tasks-status.json");
+    let snapshot;
+    try {
+      const raw = fsSync.readFileSync(statusPath, "utf8");
+      snapshot = JSON.parse(raw);
+    } catch {
+      snapshot = { files: { artifacts: [], logs: [], tmp: [] }, tasks: {} };
+    }
+    const updated = updater(snapshot);
+    fsSync.writeFileSync(statusPath, JSON.stringify(updated, null, 2));
+  }
+
+  /**
+   * Synchronous status update with file tracking and metadata
+   * @param {string} fileType - "logs", "artifacts", or "tmp"
+   * @param {string} fileName - Name of the file
+   */
+  function updateStatusWithFilesSync(fileType, fileName) {
+    const jobDir = path.dirname(statusPath);
+    writeJobStatusSync(jobDir, (snapshot) => {
+      snapshot.files ||= { artifacts: [], logs: [], tmp: [] };
+
+      const jobArray = snapshot.files[fileType];
+      if (!jobArray.includes(fileName)) {
+        jobArray.push(fileName);
+      }
+
+      if (trackTaskFiles) {
+        snapshot.tasks ||= {};
+        snapshot.tasks[taskName] ||= {};
+        snapshot.tasks[taskName].files ||= { artifacts: [], logs: [], tmp: [] };
+
+        const taskArray = snapshot.tasks[taskName].files[fileType];
+        if (!taskArray.includes(fileName)) {
+          taskArray.push(fileName);
+        }
+      }
+
+      return snapshot;
+    });
+  }
+
   // Return curried functions for each file type
   return {
     /**
@@ -113,6 +190,12 @@ export function createTaskFileIO({ workDir, taskName, getStage, statusPath }) {
      * @param {string} options.mode - "append" (default) or "replace"
      */
     async writeLog(name, content, options = {}) {
+      if (!validateLogName(name)) {
+        throw new Error(
+          `Invalid log filename "${name}". Must follow format {taskName}-{stage}-{event}.{ext}`
+        );
+      }
+
       const filePath = await writeFile(
         logsDir,
         name,
@@ -176,6 +259,33 @@ export function createTaskFileIO({ workDir, taskName, getStage, statusPath }) {
       return taskDir;
     },
 
+    /**
+     * Write a log file synchronously (critical path only)
+     * @param {string} name - File name
+     * @param {string} content - Log content
+     * @param {Object} options - Options object
+     * @param {string} options.mode - "replace" (default) or "append"
+     */
+    writeLogSync(name, content, options = {}) {
+      if (!validateLogName(name)) {
+        throw new Error(
+          `Invalid log filename "${name}". Must follow format {taskName}-{stage}-{event}.{ext}`
+        );
+      }
+
+      ensureDirSync(logsDir);
+      const filePath = path.join(logsDir, name);
+
+      if (options.mode === "append") {
+        fsSync.appendFileSync(filePath, content);
+      } else {
+        atomicWriteSync(filePath, content);
+      }
+
+      updateStatusWithFilesSync("logs", name);
+      return filePath;
+    },
+
     /**
      * Get the current stage name
      * @returns {string} Current stage name
@@ -185,3 +295,88 @@ export function createTaskFileIO({ workDir, taskName, getStage, statusPath }) {
     },
   };
 }
+
+/**
+ * Generates a standardized log filename following the convention {taskName}-{stage}-{event}.{ext}
+ * @param {string} taskName - Name of the task
+ * @param {string} stage - Stage name or identifier
+ * @param {string} event - Event type from LogEvent constants
+ * @param {string} ext - File extension from LogFileExtension constants
+ * @returns {string} Formatted log filename
+ */
+export function generateLogName(
+  taskName,
+  stage,
+  event,
+  ext = LogFileExtension.TEXT
+) {
+  if (!taskName || !stage || !event || !ext) {
+    throw new Error(
+      "All parameters (taskName, stage, event, ext) are required for generateLogName"
+    );
+  }
+  if (!isValidLogEvent(event)) {
+    throw new Error(
+      `Invalid log event "${event}". Use a value from LogEvent: ${Object.values(
+        LogEvent
+      ).join(", ")}`
+    );
+  }
+  if (!isValidLogFileExtension(ext)) {
+    throw new Error(
+      `Invalid log file extension "${ext}". Use a value from LogFileExtension: ${Object.values(
+        LogFileExtension
+      ).join(", ")}`
+    );
+  }
+  return `${taskName}-${stage}-${event}.${ext}`;
+}
+
+/**
+ * Parses a log filename to extract taskName, stage, event, and extension
+ * @param {string} fileName - Log filename to parse
+ * @returns {Object|null} Parsed components or null if invalid format
+ */
+export function parseLogName(fileName) {
+  if (typeof fileName !== "string") {
+    return null;
+  }
+
+  // Match pattern: taskName-stage-event.ext
+  // Split on first two hyphens: taskName-stage-event.ext
+  const match = fileName.match(
+    /^(?<taskName>[^-]+)-(?<stage>[^-]+)-(?<event>[^.]+)\.(?<ext>.+)$/
+  );
+  if (!match) {
+    return null;
+  }
+
+  const { taskName, stage, event, ext } = match.groups;
+  return { taskName, stage, event, ext };
+}
+
+/**
+ * Generates a glob pattern for matching log files with specific components
+ * @param {string} taskName - Task name (optional, use "*" for wildcard)
+ * @param {string} stage - Stage name (optional, use "*" for wildcard)
+ * @param {string} event - Event type (optional, use "*" for wildcard)
+ * @param {string} ext - File extension (optional, use "*" for wildcard)
+ * @returns {string} Glob pattern for file matching
+ */
+export function getLogPattern(
+  taskName = "*",
+  stage = "*",
+  event = "*",
+  ext = "*"
+) {
+  return `${taskName}-${stage}-${event}.${ext}`;
+}
+
+/**
+ * Validates that a log filename follows the standardized naming convention
+ * @param {string} fileName - Log filename to validate
+ * @returns {boolean} True if valid, false otherwise
+ */
+export function validateLogName(fileName) {
+  return parseLogName(fileName) !== null;
+}

package/src/core/orchestrator.js

@@ -5,6 +5,8 @@ import chokidar from "chokidar";
 import { spawn as defaultSpawn } from "node:child_process";
 import { getConfig, getPipelineConfig } from "./config.js";
 import { createLogger } from "./logger.js";
+import { createTaskFileIO, generateLogName } from "./file-io.js";
+import { LogEvent } from "../config/log-events.js";
 
 /**
  * Resolve canonical pipeline directories for the given data root.
@@ -153,6 +155,35 @@ export async function startOrchestrator(opts) {
       };
       await fs.writeFile(statusPath, JSON.stringify(status, null, 2));
     }
+    // Create fileIO for orchestrator-level logging
+    const fileIO = createTaskFileIO({
+      workDir,
+      taskName: jobId,
+      getStage: () => "orchestrator",
+      statusPath,
+      trackTaskFiles: false,
+    });
+
+    // Write job start log
+    await fileIO.writeLog(
+      generateLogName(jobId, "orchestrator", LogEvent.START),
+      JSON.stringify(
+        {
+          jobId,
+          pipeline: seed?.pipeline,
+          timestamp: new Date().toISOString(),
+          seedSummary: {
+            name: seed?.name,
+            pipeline: seed?.pipeline,
+            keys: Object.keys(seed || {}),
+          },
+        },
+        null,
+        2
+      ),
+      { mode: "replace" }
+    );
+
     // Spawn runner for this job
     const child = spawnRunner(
       logger,
@@ -161,7 +192,8 @@ export async function startOrchestrator(opts) {
       running,
       spawn,
       testMode,
-      seed
+      seed,
+      fileIO
     );
     // child registered inside spawnRunner
     return child;
@@ -223,6 +255,12 @@ export async function startOrchestrator(opts) {
   return { stop };
 }
 
+/**
+ * @typedef {Object} TaskFileIO
+ * @property {(name: string, content: string, options?: { mode?: 'append'|'replace' }) => Promise<string>} writeLog
+ * @property {(name: string, content: string, options?: { mode?: 'append'|'replace' }) => string} writeLogSync
+ */
+
 /**
  * Spawn a pipeline runner. In testMode we still call spawn() so tests can assert,
  * but we resolve immediately and let tests drive the lifecycle (emit 'exit', etc.).
@@ -234,8 +272,18 @@ export async function startOrchestrator(opts) {
  * @param {typeof defaultSpawn} spawn
  * @param {boolean} testMode
  * @param {Object} seed - Seed data containing pipeline information
+ * @param {TaskFileIO} fileIO - Task-scoped file I/O interface for writing logs
  */
-function spawnRunner(logger, jobId, dirs, running, spawn, testMode, seed) {
+function spawnRunner(
+  logger,
+  jobId,
+  dirs,
+  running,
+  spawn,
+  testMode,
+  seed,
+  fileIO
+) {
   // Use path relative to this file to avoid process.cwd() issues
   const orchestratorDir = path.dirname(new URL(import.meta.url).pathname);
   const runnerPath = path.join(orchestratorDir, "pipeline-runner.js");
@@ -316,11 +364,67 @@ function spawnRunner(logger, jobId, dirs, running, spawn, testMode, seed) {
 
     running.set(jobId, child);
 
-    child.on("exit", () => {
+    child.on("exit", (code, signal) => {
       running.delete(jobId);
+
+      // Write job completion log synchronously
+      if (fileIO) {
+        try {
+          fileIO.writeLogSync(
+            generateLogName(jobId, "orchestrator", LogEvent.COMPLETE),
+            JSON.stringify(
+              {
+                jobId,
+                exitCode: code,
+                signal: signal,
+                timestamp: new Date().toISOString(),
+                completionType: code === 0 ? "success" : "failure",
+              },
+              null,
+              2
+            ),
+            { mode: "replace" }
+          );
+        } catch (error) {
+          logger.error("Failed to write job completion log", {
+            jobId,
+            error: error.message,
+          });
+        }
+      }
     });
-    child.on("error", () => {
+
+    child.on("error", (error) => {
       running.delete(jobId);
+
+      // Write job error log synchronously
+      if (fileIO) {
+        try {
+          fileIO.writeLogSync(
+            generateLogName(jobId, "orchestrator", LogEvent.ERROR),
+            JSON.stringify(
+              {
+                jobId,
+                error: {
+                  message: error.message,
+                  name: error.name,
+                  code: error.code,
+                },
+                timestamp: new Date().toISOString(),
+                completionType: "error",
+              },
+              null,
+              2
+            ),
+            { mode: "replace" }
+          );
+        } catch (logError) {
+          logger.error("Failed to write job error log", {
+            jobId,
+            error: logError.message,
+          });
+        }
+      }
     });
 
     // In test mode: return immediately; in real mode you might await readiness

package/src/core/pipeline-runner.js

@@ -7,9 +7,14 @@ import { getPipelineConfig } from "./config.js";
 import { writeJobStatus } from "./status-writer.js";
 import { TaskState } from "../config/statuses.js";
 import { ensureTaskSymlinkBridge } from "./symlink-bridge.js";
-import { cleanupTaskSymlinks } from "./symlink-utils.js";
-import { createTaskFileIO } from "./file-io.js";
+import {
+  cleanupTaskSymlinks,
+  validateTaskSymlinks,
+  repairTaskSymlinks,
+} from "./symlink-utils.js";
+import { createTaskFileIO, generateLogName } from "./file-io.js";
 import { createJobLogger } from "./logger.js";
+import { LogEvent, LogFileExtension } from "../config/log-events.js";
 
 const ROOT = process.env.PO_ROOT || process.cwd();
 const DATA_DIR = path.join(ROOT, process.env.PO_DATA_DIR || "pipeline-data");
@@ -132,8 +137,66 @@ for (const taskName of pipeline.tasks) {
       ? modulePath
       : path.resolve(path.dirname(TASK_REGISTRY), modulePath);
 
-    // Create symlink bridge for deterministic module resolution
+    // Validate symlinks before task execution to ensure restart reliability
     const poRoot = process.env.PO_ROOT || process.cwd();
+    const expectedTargets = {
+      nodeModules: path.join(path.resolve(poRoot, ".."), "node_modules"),
+      taskRoot: path.dirname(absoluteModulePath),
+    };
+
+    const validationResult = await validateTaskSymlinks(
+      taskDir,
+      expectedTargets
+    );
+
+    if (!validationResult.isValid) {
+      logger.warn("Task symlinks validation failed, attempting repair", {
+        taskName,
+        taskDir,
+        errors: validationResult.errors,
+        validationDuration: validationResult.duration,
+      });
+
+      const repairResult = await repairTaskSymlinks(
+        taskDir,
+        poRoot,
+        absoluteModulePath
+      );
+
+      if (!repairResult.success) {
+        const errorMessage = `Failed to repair task symlinks for ${taskName}: ${repairResult.errors.join(", ")}`;
+        logger.error("Task symlink repair failed, aborting execution", {
+          taskName,
+          taskDir,
+          errors: repairResult.errors,
+          repairDuration: repairResult.duration,
+        });
+
+        await updateStatus(taskName, {
+          state: TaskState.FAILED,
+          endedAt: now(),
+          error: { message: errorMessage, type: "SymlinkRepairFailed" },
+        });
+
+        process.exitCode = 1;
+        process.exit(1);
+      }
+
+      logger.log("Task symlinks repaired successfully", {
+        taskName,
+        taskDir,
+        repairDuration: repairResult.duration,
+        relocatedEntry: repairResult.relocatedEntry,
+      });
+    } else {
+      logger.debug("Task symlinks validation passed", {
+        taskName,
+        taskDir,
+        validationDuration: validationResult.duration,
+      });
+    }
+
+    // Create symlink bridge for deterministic module resolution
     const relocatedEntry = await ensureTaskSymlinkBridge({
       taskDir,
       poRoot,
@@ -162,7 +225,12 @@ for (const taskName of pipeline.tasks) {
       // Persist execution-logs.json and failure-details.json on task failure via IO
       if (result.logs) {
         await fileIO.writeLog(
-          "execution-logs.json",
+          generateLogName(
+            taskName,
+            "pipeline",
+            LogEvent.EXECUTION_LOGS,
+            LogFileExtension.JSON
+          ),
           JSON.stringify(result.logs, null, 2),
           { mode: "replace" }
         );
@@ -175,7 +243,12 @@ for (const taskName of pipeline.tasks) {
         refinementAttempts: result.refinementAttempts || 0,
       };
       await fileIO.writeLog(
-        "failure-details.json",
+        generateLogName(
+          taskName,
+          "pipeline",
+          LogEvent.FAILURE_DETAILS,
+          LogFileExtension.JSON
+        ),
         JSON.stringify(failureDetails, null, 2),
         { mode: "replace" }
       );
@@ -218,7 +291,12 @@ for (const taskName of pipeline.tasks) {
 
     if (result.logs) {
       await fileIO.writeLog(
-        "execution-logs.json",
+        generateLogName(
+          taskName,
+          "pipeline",
+          LogEvent.EXECUTION_LOGS,
+          LogFileExtension.JSON
+        ),
         JSON.stringify(result.logs, null, 2),
         { mode: "replace" }
       );

package/src/core/symlink-utils.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { createLogger } from "./logger.js";
+import { ensureTaskSymlinkBridge } from "./symlink-bridge.js";
 
 const logger = createLogger("SymlinkUtils");
 
@@ -49,6 +50,201 @@ export async function ensureSymlink(linkPath, targetPath, type) {
   }
 }
 
+/**
+ * Validates that required task symlinks exist and point to accessible targets.
+ *
+ * @param {string} taskDir - The task directory containing symlinks
+ * @param {Object} expectedTargets - Expected symlink targets
+ * @param {string} expectedTargets.nodeModules - Expected target for node_modules symlink
+ * @param {string} expectedTargets.taskRoot - Expected target for _task_root symlink
+ * @returns {Object} Validation result with isValid flag and details
+ */
+export async function validateTaskSymlinks(taskDir, expectedTargets) {
+  const startTime = Date.now();
+  const validationErrors = [];
+  const validationDetails = {};
+
+  const symlinksToValidate = [
+    { name: "node_modules", expectedTarget: expectedTargets.nodeModules },
+    { name: "_task_root", expectedTarget: expectedTargets.taskRoot },
+  ];
+
+  for (const { name, expectedTarget } of symlinksToValidate) {
+    const linkPath = path.join(taskDir, name);
+
+    try {
+      // Check if symlink exists
+      const stats = await fs.lstat(linkPath);
+
+      if (!stats.isSymbolicLink()) {
+        validationErrors.push(
+          `${name} exists but is not a symlink (type: ${stats.isFile() ? "file" : "directory"})`
+        );
+        validationDetails[name] = {
+          exists: true,
+          isSymlink: false,
+          targetAccessible: false,
+        };
+        continue;
+      }
+
+      // Read the symlink target
+      const actualTarget = await fs.readlink(linkPath);
+
+      // Check if target matches expected (normalize paths for comparison)
+      const normalizedActual = path.resolve(taskDir, actualTarget);
+      const normalizedExpected = path.resolve(expectedTarget);
+
+      if (normalizedActual !== normalizedExpected) {
+        validationErrors.push(
+          `${name} points to wrong target: expected ${expectedTarget}, got ${actualTarget}`
+        );
+        validationDetails[name] = {
+          exists: true,
+          isSymlink: true,
+          targetAccessible: false,
+          actualTarget,
+          expectedTarget,
+        };
+        continue;
+      }
+
+      // Check if target is accessible
+      const targetStats = await fs.stat(normalizedActual).catch(() => null);
+      if (!targetStats) {
+        validationErrors.push(
+          `${name} target is not accessible: ${actualTarget}`
+        );
+        validationDetails[name] = {
+          exists: true,
+          isSymlink: true,
+          targetAccessible: false,
+          actualTarget,
+        };
+        continue;
+      }
+
+      if (!targetStats.isDirectory()) {
+        validationErrors.push(
+          `${name} target is not a directory: ${actualTarget}`
+        );
+        validationDetails[name] = {
+          exists: true,
+          isSymlink: true,
+          targetAccessible: false,
+          actualTarget,
+          targetType: "file",
+        };
+        continue;
+      }
+
+      // Symlink is valid
+      validationDetails[name] = {
+        exists: true,
+        isSymlink: true,
+        targetAccessible: true,
+        actualTarget,
+      };
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        validationErrors.push(`${name} symlink does not exist`);
+        validationDetails[name] = {
+          exists: false,
+          isSymlink: false,
+          targetAccessible: false,
+        };
+      } else {
+        validationErrors.push(`${name} validation failed: ${error.message}`);
+        validationDetails[name] = {
+          exists: false,
+          isSymlink: false,
+          targetAccessible: false,
+          error: error.message,
+        };
+      }
+    }
+  }
+
+  const isValid = validationErrors.length === 0;
+  const duration = Date.now() - startTime;
+
+  logger.debug("Symlink validation completed", {
+    taskDir,
+    isValid,
+    errorsCount: validationErrors.length,
+    duration,
+    details: validationDetails,
+  });
+
+  return {
+    isValid,
+    errors: validationErrors,
+    details: validationDetails,
+    duration,
+  };
+}
+
+/**
+ * Repairs task symlinks by recreating them using the existing symlink bridge.
+ *
+ * @param {string} taskDir - The task directory where symlinks should be created
+ * @param {string} poRoot - The repository root directory
+ * @param {string} taskModulePath - Absolute path to the original task module
+ * @returns {Object} Repair result with success flag and details
+ */
+export async function repairTaskSymlinks(taskDir, poRoot, taskModulePath) {
+  const startTime = Date.now();
+
+  try {
+    logger.log("Repairing task symlinks", {
+      taskDir,
+      poRoot,
+      taskModulePath,
+    });
+
+    // Use existing ensureTaskSymlinkBridge for repairs
+    const relocatedEntry = await ensureTaskSymlinkBridge({
+      taskDir,
+      poRoot,
+      taskModulePath,
+    });
+
+    const duration = Date.now() - startTime;
+
+    logger.log("Task symlinks repaired successfully", {
+      taskDir,
+      duration,
+      relocatedEntry,
+    });
+
+    return {
+      success: true,
+      relocatedEntry,
+      duration,
+      errors: [],
+    };
+  } catch (error) {
+    const duration = Date.now() - startTime;
+    const errorMessage = `Failed to repair task symlinks: ${error.message}`;
+
+    logger.error("Task symlink repair failed", {
+      taskDir,
+      poRoot,
+      taskModulePath,
+      duration,
+      error: error.message,
+      stack: error.stack,
+    });
+
+    return {
+      success: false,
+      relocatedEntry: null,
+      duration,
+      errors: [errorMessage],
+    };
+  }
+}
+
 /**
  * Removes task symlinks from a completed job directory to avoid dangling links.
  *

package/src/core/task-runner.js

@@ -4,12 +4,13 @@ import fs from "fs";
 import { createLLM, getLLMEvents } from "../llm/index.js";
 import { loadFreshModule } from "./module-loader.js";
 import { loadEnvironment } from "./environment.js";
-import { createTaskFileIO } from "./file-io.js";
+import { createTaskFileIO, generateLogName } from "./file-io.js";
 import { writeJobStatus } from "./status-writer.js";
 import { computeDeterministicProgress } from "./progress.js";
 import { TaskState } from "../config/statuses.js";
 import { validateWithSchema } from "../api/validators/json.js";
 import { createJobLogger } from "./logger.js";
+import { LogEvent, LogFileExtension } from "../config/log-events.js";
 
 /**
  * Derives model key and token counts from LLM metric event.
@@ -67,13 +68,13 @@ function assertStageResult(stageName, result) {
     );
   }
 
-  if (!result.hasOwnProperty("output")) {
+  if (!Object.prototype.hasOwnProperty.call(result, "output")) {
     throw new Error(
       `Stage "${stageName}" result missing required property: output`
     );
   }
 
-  if (!result.hasOwnProperty("flags")) {
+  if (!Object.prototype.hasOwnProperty.call(result, "flags")) {
     throw new Error(
       `Stage "${stageName}" result missing required property: flags`
     );
@@ -507,7 +508,11 @@ export async function runPipeline(modulePath, initialContext = {}) {
     }
 
     // Add console output capture before stage execution using IO
-    const logName = `stage-${stageName}.log`;
+    const logName = generateLogName(
+      context.meta.taskName,
+      stageName,
+      LogEvent.START
+    );
     const logPath = path.join(context.meta.workDir, "files", "logs", logName);
     console.debug("[task-runner] stage log path resolution via IO", {
       stage: stageName,
@@ -593,7 +598,12 @@ export async function runPipeline(modulePath, initialContext = {}) {
       },
     };
     await context.io.writeLog(
-      `stage-${stageName}-context.json`,
+      generateLogName(
+        context.meta.taskName,
+        stageName,
+        LogEvent.CONTEXT,
+        LogFileExtension.JSON
+      ),
       JSON.stringify(snapshot, null, 2),
       { mode: "replace" }
     );
@@ -696,6 +706,18 @@ export async function runPipeline(modulePath, initialContext = {}) {
         }
       }
 
+      // Add explicit completion log after stage completion
+      const completeLogName = generateLogName(
+        context.meta.taskName,
+        stageName,
+        LogEvent.COMPLETE
+      );
+      await context.io.writeLog(
+        completeLogName,
+        `Stage ${stageName} completed at ${new Date().toISOString()}\n`,
+        { mode: "replace" }
+      );
+
       const ms = +(performance.now() - start).toFixed(2);
       logger.log("Stage completed successfully", {
         stage: stageName,
@@ -729,9 +751,17 @@ export async function runPipeline(modulePath, initialContext = {}) {
           context.meta.workDir,
           "files",
           "logs",
-          `stage-${stageName}.log`
+          generateLogName(context.meta.taskName, stageName, LogEvent.START)
+        ),
+        snapshotPath: path.join(
+          logsDir,
+          generateLogName(
+            context.meta.taskName,
+            stageName,
+            LogEvent.CONTEXT,
+            LogFileExtension.JSON
+          )
         ),
-        snapshotPath: path.join(logsDir, `stage-${stageName}-context.json`),
         dataHasSeed: !!context.data?.seed,
         seedHasData: context.data?.seed?.data !== undefined,
         flagsKeys: Object.keys(context.flags || {}),
@@ -855,8 +885,41 @@ function toAbsFileURL(p) {
 }
 
 function normalizeError(err) {
-  if (err instanceof Error)
+  if (err instanceof Error) {
     return { name: err.name, message: err.message, stack: err.stack };
+  }
+
+  // Handle plain object errors (like those from HTTP responses)
+  if (typeof err === "object" && err !== null) {
+    let message = "Unknown error";
+    if (typeof err?.message === "string") {
+      message = err.message;
+    } else if (typeof err?.error?.message === "string") {
+      message = err.error.message;
+    } else if (typeof err?.error === "string") {
+      message = err.error;
+    }
+    const result = { message };
+
+    // Include additional context if available
+    if (err.status) result.status = err.status;
+    if (err.code) result.code = err.code;
+    if (err.error) {
+      if (typeof err.error === "string") {
+        result.error = err.error;
+      } else if (typeof err.error === "object" && err.error !== null) {
+        // Try to extract a message property, else serialize the object
+        result.error = err.error.message
+          ? err.error.message
+          : JSON.stringify(err.error);
+      } else {
+        result.error = String(err.error);
+      }
+    }
+
+    return result;
+  }
+
   return { message: String(err) };
 }
 

package/src/providers/zhipu.js

@@ -65,20 +65,39 @@ export async function zhipuChat({
       };
 
       console.log("[Zhipu] Calling Zhipu API...");
-      const response = await fetch("https://api.z.ai/api/coding/paas/v4", {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${process.env.ZHIPU_API_KEY}`,
-        },
-        body: JSON.stringify(requestBody),
-      });
+      const response = await fetch(
+        "https://api.z.ai/api/paas/v4/chat/completions",
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${process.env.ZHIPU_API_KEY}`,
+          },
+          body: JSON.stringify(requestBody),
+        }
+      );
 
       if (!response.ok) {
-        const error = await response
-          .json()
-          .catch(() => ({ error: response.statusText }));
-        throw { status: response.status, ...error };
+        let errorMessage;
+        try {
+          const errorData = await response.json();
+          errorMessage =
+            errorData?.error?.message ||
+            errorData?.message ||
+            response.statusText ||
+            "Unknown error";
+        } catch {
+          // If JSON parsing fails, try to get text response
+          try {
+            errorMessage = await response.text();
+          } catch {
+            errorMessage = response.statusText || "Unknown error";
+          }
+        }
+
+        const error = new Error(errorMessage);
+        error.status = response.status;
+        throw error;
       }
 
       const data = await response.json();
@@ -117,7 +136,7 @@ export async function zhipuChat({
       };
     } catch (error) {
       lastError = error;
-      const msg = error?.error?.message || error?.message || "";
+      const msg = error?.message || error?.toString() || "Unknown error";
       console.error("[Zhipu] Error occurred:", msg);
       console.error("[Zhipu] Error status:", error?.status);