@pi-unipi/unipi 2.4.2 → 2.6.0

package/packages/milestone/hooks.ts

@@ -1,22 +1,33 @@
 /**
  * @pi-unipi/milestone — Lifecycle hooks
  *
- * Session start: inject milestone progress as system context.
+ * Agent start: append milestone progress as a hidden, persistent context snapshot.
  * Session end: auto-sync completed items from workflow docs.
  */
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  buildSessionContext,
+  type ExtensionAPI,
+  type SessionEntry,
+} from "@earendil-works/pi-coding-agent";
 import { MILESTONE_DIRS, UNIPI_EVENTS, safeMtimeMs, tryRead } from "@pi-unipi/core";
-import { parseMilestones, getProgressSummary, updateItemStatus } from "./milestone.js";
+import { getProgressSummary, updateItemStatus } from "./milestone.js";
 
-/** Track when the session started for diffing modified files */
-let sessionStartMs = 0;
+export const MILESTONE_SNAPSHOT_TYPE = "unipi-milestone-snapshot";
 
-/**
- * Format a progress summary as a context string for the system prompt.
- */
+interface MilestoneSnapshotDetails {
+  active: boolean;
+  workspace: string;
+}
+
+interface EffectiveSnapshot {
+  content: unknown;
+  details?: MilestoneSnapshotDetails;
+}
+
+/** Format the active milestone progress included in a snapshot. */
 function formatMilestoneContext(filePath: string): string | null {
   const summary = getProgressSummary(filePath);
   if (summary.totalItems === 0) return null;
@@ -39,23 +50,84 @@ function formatMilestoneContext(filePath: string): string | null {
     .join("\n");
 }
 
+/** Build an append-only snapshot that explicitly invalidates earlier snapshots. */
+export function formatMilestoneSnapshot(workspace: string, context: string | null): string {
+  return [
+    "# UniPi Milestone Snapshot",
+    "This snapshot supersedes all prior UniPi milestone snapshots; use only this snapshot for milestone status.",
+    `Workspace: ${workspace}`,
+    `Status: ${context ? "active" : "inactive"}`,
+    context ?? "No milestones are active for this workspace.",
+  ].join("\n\n");
+}
+
+function latestEffectiveSnapshot(branch: SessionEntry[]): EffectiveSnapshot | undefined {
+  const messages = buildSessionContext(branch).messages;
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const message = messages[index];
+    if (message.role === "custom" && message.customType === MILESTONE_SNAPSHOT_TYPE) {
+      return {
+        content: message.content,
+        details: message.details as MilestoneSnapshotDetails | undefined,
+      };
+    }
+  }
+  return undefined;
+}
+
+/** Find state that may have been folded into a compaction summary. */
+function latestHistoricalSnapshot(branch: SessionEntry[]): EffectiveSnapshot | undefined {
+  for (let index = branch.length - 1; index >= 0; index--) {
+    const entry = branch[index];
+    if (entry.type === "custom_message" && entry.customType === MILESTONE_SNAPSHOT_TYPE) {
+      return {
+        content: entry.content,
+        details: entry.details as MilestoneSnapshotDetails | undefined,
+      };
+    }
+  }
+  return undefined;
+}
+
+function isActiveSnapshot(snapshot: EffectiveSnapshot): boolean {
+  if (typeof snapshot.details?.active === "boolean") return snapshot.details.active;
+  return typeof snapshot.content === "string" && snapshot.content.includes("Status: active");
+}
+
 /**
- * Register session start hook — injects milestone progress into system context.
+ * Register the agent-start hook. Snapshots are hidden from the transcript but
+ * persist in the append-only session and therefore keep the system prefix stable.
  */
 export function registerSessionStartHook(pi: ExtensionAPI): void {
-  pi.on("before_agent_start", (event) => {
-    sessionStartMs = Date.now();
+  pi.on("before_agent_start", (_event, ctx) => {
+    const workspace = ctx.cwd;
+    const milestonesPath = path.join(workspace, MILESTONE_DIRS.MILESTONES);
+    const context = formatMilestoneContext(milestonesPath);
+    const branch = ctx.sessionManager.getBranch();
+    const latest = latestEffectiveSnapshot(branch);
+    const historical = latestHistoricalSnapshot(branch);
 
-    const cwd = process.cwd();
-    const milestonesPath = path.join(cwd, MILESTONE_DIRS.MILESTONES);
+    // A genuinely clean workspace/session needs no synthetic context. Raw
+    // history is checked because compaction may have folded an old active
+    // snapshot into summary prose while removing its custom-message identity.
+    if (!context && !latest && !historical) return undefined;
 
-    const context = formatMilestoneContext(milestonesPath);
-    if (!context) return undefined;
+    const prior = latest ?? historical;
+    if (!context && prior && !isActiveSnapshot(prior)) return undefined;
+
+    const content = formatMilestoneSnapshot(workspace, context);
+    if (latest?.content === content) return undefined;
 
-    // Append milestone context to the system prompt
-    const currentPrompt = (event as any).systemPrompt ?? "";
     return {
-      systemPrompt: currentPrompt + "\n\n" + context,
+      message: {
+        customType: MILESTONE_SNAPSHOT_TYPE,
+        content,
+        display: false,
+        details: {
+          active: context !== null,
+          workspace,
+        } satisfies MilestoneSnapshotDetails,
+      },
     };
   });
 }
@@ -140,19 +212,21 @@ function scanModifiedDocs(dirs: string[], since: number): string[] {
  * scans modified docs, and auto-updates MILESTONES.md.
  */
 export function registerSessionEndHook(pi: ExtensionAPI): void {
-  // Store baseline snapshots at session start
+  // Capture the session workspace because process.cwd() can change before shutdown.
   const baselineSnapshots = new Map<string, string>();
+  let sessionStartMs = 0;
+  let sessionWorkspace: string | null = null;
 
   // Capture baselines on session start
-  pi.on("session_start", () => {
+  pi.on("session_start", (_event, ctx) => {
     sessionStartMs = Date.now();
+    sessionWorkspace = ctx.cwd;
     baselineSnapshots.clear();
 
-    const cwd = process.cwd();
     const scanDirs = [
-      path.join(cwd, ".unipi/docs/specs"),
-      path.join(cwd, ".unipi/docs/plans"),
-      path.join(cwd, ".unipi/docs/quick-work"),
+      path.join(sessionWorkspace, ".unipi/docs/specs"),
+      path.join(sessionWorkspace, ".unipi/docs/plans"),
+      path.join(sessionWorkspace, ".unipi/docs/quick-work"),
     ];
 
     for (const dir of scanDirs) {
@@ -168,15 +242,15 @@ export function registerSessionEndHook(pi: ExtensionAPI): void {
   });
 
   const syncModifiedDocs = () => {
-    const cwd = process.cwd();
-    const milestonesPath = path.join(cwd, MILESTONE_DIRS.MILESTONES);
+    if (!sessionWorkspace) return;
 
+    const milestonesPath = path.join(sessionWorkspace, MILESTONE_DIRS.MILESTONES);
     if (!fs.existsSync(milestonesPath)) return;
 
     const scanDirs = [
-      path.join(cwd, ".unipi/docs/specs"),
-      path.join(cwd, ".unipi/docs/plans"),
-      path.join(cwd, ".unipi/docs/quick-work"),
+      path.join(sessionWorkspace, ".unipi/docs/specs"),
+      path.join(sessionWorkspace, ".unipi/docs/plans"),
+      path.join(sessionWorkspace, ".unipi/docs/quick-work"),
     ];
 
     const modifiedFiles = scanModifiedDocs(scanDirs, sessionStartMs);

package/packages/milestone/index.ts

@@ -2,7 +2,7 @@
  * @pi-unipi/milestone — Extension entry point
  *
  * Lifecycle layer for project-level goals. Tracks progress via MILESTONES.md,
- * injects context on session start, auto-syncs on session end.
+ * appends hidden context snapshots before agent turns, and auto-syncs on session end.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

package/packages/milestone/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@pi-unipi/milestone",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "Lifecycle layer for project-level goals — MILESTONES.md tracking, session hooks, auto-sync",
   "type": "module",
   "main": "index.ts",
+  "scripts": {
+    "test": "npx tsx --test tests/hooks.test.ts"
+  },
   "license": "MIT",
   "author": "Neuron Mr White",
   "repository": {
@@ -29,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.4.1"
+    "@pi-unipi/core": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/packages/notify/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/notify",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "Cross-platform notification extension for Pi — native OS, Gotify, and Telegram notifications for agent lifecycle events",
   "type": "module",
   "main": "index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.4.1",
+    "@pi-unipi/core": "2.6.0",
     "node-notifier": "^10.0.1"
   },
   "peerDependencies": {

package/packages/ralph/index.ts

@@ -30,6 +30,7 @@ const VERSION = getPackageVersion(dirname(fileURLToPath(import.meta.url)));
 /** Current loop manager instance (recreated on session reload) */
 let manager: RalphLoopManager | null = null;
 
+
 /**
  * Get or create the loop manager for the current context.
  */
@@ -42,9 +43,14 @@ function getManager(ctx: ExtensionContext, pi: ExtensionAPI): RalphLoopManager {
   return manager;
 }
 
+export { buildRalphLoopReminder } from "./reminder.js";
+import { buildRalphLoopReminder, latestRalphReminder, RALPH_REMINDER_TYPE } from "./reminder.js";
+
 export default function (pi: ExtensionAPI) {
-  // Register tools
-  // (Manager will be created lazily on first use)
+  // Register static tool definitions at extension load. Their executors resolve
+  // the session-scoped manager lazily, so schemas never arrive late or reorder
+  // the provider tool array during session_start.
+  registerRalphTools(pi, (ctx) => getManager(ctx, pi));
 
   // Register commands
   registerCommands(pi);
@@ -157,20 +163,13 @@ export default function (pi: ExtensionAPI) {
     const state = mgr.loadState(currentLoop);
     if (!state || state.status !== "active") return;
 
-    const iterStr = `${state.iteration}${state.maxIterations > 0 ? `/${state.maxIterations}` : ""}`;
-
-    let instructions = `You are in a Ralph loop working on: ${state.taskFile}\n`;
-    if (state.itemsPerIteration > 0) {
-      instructions += `- Work on ~${state.itemsPerIteration} items this iteration\n`;
-    }
-    instructions += `- Update the task file as you progress\n`;
-    instructions += `- When FULLY COMPLETE: ${RALPH_COMPLETE_MARKER}\n`;
-    instructions += `- Otherwise, call ralph_done tool to proceed to next iteration`;
+    const content = buildRalphLoopReminder(state);
+    if (latestRalphReminder(ctx) === content) return;
 
     return {
       message: {
-        customType: "unipi-ralph-loop-reminder",
-        content: `[RALPH LOOP - ${state.name} - Iteration ${iterStr}]\n\n${instructions}`,
+        customType: RALPH_REMINDER_TYPE,
+        content,
         display: false,
       },
     };
@@ -187,11 +186,6 @@ export default function (pi: ExtensionAPI) {
     manager = null;
   });
 
-  // Register tools after manager setup
-  pi.on("session_start", async (_event, ctx) => {
-    const mgr = getManager(ctx, pi);
-    registerRalphTools(pi, mgr);
-  });
 }
 
 /**

package/packages/ralph/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ralph",
-  "version": "2.4.2",
+  "version": "2.6.0",
   "description": "Long-running iterative development loops for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -26,9 +26,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "test": "npx tsx --test reminder.test.ts"
+  },
   "dependencies": {
-    "@pi-unipi/core": "2.4.1",
-    "@pi-unipi/info-screen": "2.4.1"
+    "@pi-unipi/core": "2.6.0",
+    "@pi-unipi/info-screen": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.80.0",

package/packages/ralph/reminder.ts

@@ -0,0 +1,40 @@
+import type { ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { RALPH_COMPLETE_MARKER } from "@pi-unipi/core";
+
+export const RALPH_REMINDER_TYPE = "unipi-ralph-loop-reminder";
+
+export interface RalphReminderInput {
+  name: string;
+  iteration: number;
+  maxIterations: number;
+  taskFile: string;
+  itemsPerIteration: number;
+}
+
+/** Build the exact deterministic hidden reminder used by the live hook. */
+export function buildRalphLoopReminder(state: RalphReminderInput): string {
+  const iterStr = `${state.iteration}${state.maxIterations > 0 ? `/${state.maxIterations}` : ""}`;
+  let instructions = "This snapshot supersedes all earlier Ralph loop reminders.\n";
+  instructions += `You are in a Ralph loop working on: ${state.taskFile}\n`;
+  if (state.itemsPerIteration > 0) {
+    instructions += `- Work on ~${state.itemsPerIteration} items this iteration\n`;
+  }
+  instructions += "- Update the task file as you progress\n";
+  instructions += `- When FULLY COMPLETE: ${RALPH_COMPLETE_MARKER}\n`;
+  instructions += "- Otherwise, call ralph_done tool to proceed to next iteration";
+  return `[RALPH LOOP - ${state.name} - Iteration ${iterStr}]\n\n${instructions}`;
+}
+
+export function latestRalphReminder(ctx: Pick<ExtensionContext, "sessionManager">): string | null {
+  const branch = ctx.sessionManager.getBranch() as SessionEntry[];
+  for (let index = branch.length - 1; index >= 0; index--) {
+    const entry = branch[index];
+    if (entry.type === "custom_message" && entry.customType === RALPH_REMINDER_TYPE) {
+      return typeof entry.content === "string" ? entry.content : null;
+    }
+    // A compacted summary may contain the old reminder but no longer retains a
+    // dedicated custom entry. Inject the current snapshot once in the new epoch.
+    if (entry.type === "compaction") break;
+  }
+  return null;
+}

package/packages/ralph/tools.ts

@@ -9,10 +9,12 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { RALPH_COMPLETE_MARKER, RALPH_DEFAULTS, RALPH_TOOLS } from "@pi-unipi/core";
 import { RalphLoopManager, DEFAULT_REFLECT_INSTRUCTIONS } from "./ralph-loop.js";
 
+type ManagerProvider = (ctx: ExtensionContext) => RalphLoopManager;
+
 /**
  * Register ralph_start and ralph_done tools.
  */
-export function registerRalphTools(pi: ExtensionAPI, manager: RalphLoopManager): void {
+export function registerRalphTools(pi: ExtensionAPI, getManager: ManagerProvider): void {
   // --- ralph_start tool ---
   pi.registerTool({
     name: RALPH_TOOLS.START,
@@ -44,6 +46,7 @@ export function registerRalphTools(pi: ExtensionAPI, manager: RalphLoopManager):
       ),
     }),
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const manager = getManager(ctx);
       const taskFile = `.unipi/ralph/${params.name.replace(/[^a-zA-Z0-9_-]/g, "_")}.md`;
 
       if (manager.loadState(params.name)?.status === "active") {
@@ -92,6 +95,7 @@ export function registerRalphTools(pi: ExtensionAPI, manager: RalphLoopManager):
     ],
     parameters: Type.Object({}),
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const manager = getManager(ctx);
       if (!manager.getCurrentLoop()) {
         return {
           content: [{ type: "text", text: "No active Ralph loop." }],

package/packages/subagents/README.md

@@ -69,6 +69,8 @@ spawn_helper(
 get_helper_result(agent_id: "helper_abc123")
 ```
 
+Foreground and retrieved background results have a hard 64 KiB model-visible ceiling. For raw results up to 16 MiB, larger output includes a bounded head/tail preview and a path to the complete private mode-0600 artifact under a mode-0700 `~/.unipi/tool-results/` directory. Use `read` with offset/limit to inspect only the needed region. Repeated retrieval reuses the same artifact. Results above the safety cap or artifact-write failures still return a preview with an explicit non-retention warning.
+
 ## Custom Agent Types
 
 Create markdown files defining agent behavior:

package/packages/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/subagents",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "Subagents for UniPi — parallel execution, file locking, workflow integration",
   "type": "module",
   "main": "dist/index.js",

package/packages/subagents/src/agent-manager.ts

@@ -13,6 +13,10 @@ import { resolveModel, type ModelRegistry } from "./model-resolver.js";
 import type { AgentRecord, AgentConfig, AgentType, ThinkingLevel, SubagentsConfig } from "./types.js";
 import { BUILTIN_CONFIGS } from "./types.js";
 import { loadCustomAgents } from "./custom-agents.js";
+
+function compareCodeUnits(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
 import { FileLock } from "./file-lock.js";
 
 export type OnAgentComplete = (record: AgentRecord) => void;
@@ -88,7 +92,7 @@ export class AgentManager {
       ...Object.keys(BUILTIN_CONFIGS).filter((type) => type !== "name-gen"),
       ...this.customAgents.keys(),
       ...Object.keys(this.typeSettings),
-    ])];
+    ])].sort(compareCodeUnits);
   }
 
   /** A type is enabled only when both JSON config and agent frontmatter allow it. */

package/packages/subagents/src/agent-runner.ts

@@ -19,8 +19,8 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { BUILTIN_CONFIGS, type AgentConfig, type AgentType, type ThinkingLevel } from "./types.js";
 
-/** Tools excluded from subagents to prevent nesting. */
-const EXCLUDED_TOOL_NAMES = ["Agent", "get_result"];
+/** Tools excluded from subagents to prevent nesting. Legacy names remain for older hosts. */
+const EXCLUDED_TOOL_NAMES = ["spawn_helper", "get_helper_result", "Agent", "get_result"];
 
 /** All known built-in tool names. */
 const BUILTIN_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls"];

package/packages/subagents/src/core-compat.ts

@@ -1,4 +1,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { chmodSync, lstatSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
 
 export const MODULES = { SUBAGENTS: "subagents" } as const;
 
@@ -24,6 +28,75 @@ export function emitEvent(
   }
 }
 
+export interface BoundedHelperOutput {
+  text: string;
+  truncated: boolean;
+  originalBytes: number;
+  artifactPath?: string;
+}
+
+/** Standalone-package twin of core's bounded-output policy. */
+const MAX_RAW_HELPER_ARTIFACT_BYTES = 16 * 1024 * 1024;
+
+export function boundHelperOutput(
+  text: string,
+  maxBytes = 64 * 1024,
+  existingArtifactPath?: string,
+): BoundedHelperOutput {
+  const originalBytes = Buffer.byteLength(text, "utf8");
+  if (originalBytes <= maxBytes) return { text, truncated: false, originalBytes };
+
+  let artifactPath = existingArtifactPath;
+  let artifactWarning: string | undefined;
+  if (!artifactPath && originalBytes <= MAX_RAW_HELPER_ARTIFACT_BYTES) {
+    try {
+      const dir = join(homedir(), ".unipi", "tool-results");
+      mkdirSync(dir, { recursive: true, mode: 0o700 });
+      let stat = lstatSync(dir);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`Refusing unsafe tool-result directory: ${dir}`);
+      }
+      if ((stat.mode & 0o077) !== 0) {
+        chmodSync(dir, 0o700);
+        stat = lstatSync(dir);
+        if ((stat.mode & 0o077) !== 0) throw new Error(`Refusing non-private tool-result directory: ${dir}`);
+      }
+      artifactPath = join(dir, `helper-${randomUUID()}.txt`);
+      writeFileSync(artifactPath, text, { encoding: "utf8", mode: 0o600, flag: "wx" });
+    } catch (error) {
+      artifactWarning = `Full-output artifact unavailable: ${error instanceof Error ? error.message : String(error)}`;
+      artifactPath = undefined;
+    }
+  } else if (!artifactPath) {
+    artifactWarning = `Full output exceeded the ${MAX_RAW_HELPER_ARTIFACT_BYTES}-byte local artifact safety cap and was not retained.`;
+  }
+
+  const marker = [
+    "",
+    "--- output bounded by UniPi ---",
+    artifactPath ? `Full output: ${artifactPath}` : artifactWarning!,
+    `Original size: ${originalBytes} bytes; model-visible ceiling: ${maxBytes} bytes.`,
+    ...(artifactPath ? ["Use the read tool with offset/limit to inspect only the needed region."] : []),
+  ].join("\n");
+  const markerBytes = Buffer.byteLength(marker, "utf8");
+  const contentBudget = Math.max(1, maxBytes - markerBytes - 80);
+  const bytes = Buffer.from(text, "utf8");
+  const headBytes = Math.ceil(contentBudget * 0.75);
+  const tailBytes = Math.max(0, contentBudget - headBytes);
+  const head = bytes.subarray(0, headBytes).toString("utf8").replace(/\uFFFD+$/u, "");
+  const tail = bytes.subarray(originalBytes - tailBytes).toString("utf8").replace(/^\uFFFD+/u, "");
+  let bounded = `${head}\n… ${Math.max(0, originalBytes - contentBudget)} bytes omitted …\n${tail}${marker}`;
+  if (Buffer.byteLength(bounded, "utf8") > maxBytes) {
+    bounded = Buffer.from(bounded, "utf8").subarray(0, maxBytes).toString("utf8").replace(/\uFFFD+$/u, "");
+  }
+  return {
+    text: bounded,
+    truncated: true,
+    originalBytes,
+    artifactPath,
+  };
+}
+
 export async function withHerdrBlocked<T>(
   pi: Pick<ExtensionAPI, "events">,
   label: string,

package/packages/subagents/src/custom-agents.ts

@@ -12,6 +12,10 @@ import { homedir } from "node:os";
 import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "./types.js";
 
+function compareCodeUnits(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
 /** Backup a corrupted file by renaming to .bak */
 function backupCorrupted(filePath: string): void {
   const backupPath = filePath + ".bak";
@@ -93,7 +97,9 @@ export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
   // Load global agents first
   const globalDir = getGlobalAgentsDir();
   if (existsSync(globalDir)) {
-    const files = readdirSync(globalDir).filter((f) => f.endsWith(".md"));
+    const files = readdirSync(globalDir)
+      .filter((f) => f.endsWith(".md"))
+      .sort(compareCodeUnits);
     for (const file of files) {
       const agent = loadAgentFromFile(join(globalDir, file), "global");
       if (agent) {
@@ -105,7 +111,9 @@ export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
   // Load project agents (overrides global)
   const projectDir = getProjectAgentsDir(cwd);
   if (existsSync(projectDir)) {
-    const files = readdirSync(projectDir).filter((f) => f.endsWith(".md"));
+    const files = readdirSync(projectDir)
+      .filter((f) => f.endsWith(".md"))
+      .sort(compareCodeUnits);
     for (const file of files) {
       const agent = loadAgentFromFile(join(projectDir, file), "project");
       if (agent) {

package/packages/subagents/src/index.ts

@@ -12,7 +12,7 @@ import { Type } from "typebox";
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
-import { emitEvent, MODULES, UNIPI_EVENTS, withHerdrBlocked, type UnipiBadgeGenerateRequestEvent } from "./core-compat.js";
+import { boundHelperOutput, emitEvent, MODULES, UNIPI_EVENTS, withHerdrBlocked, type UnipiBadgeGenerateRequestEvent } from "./core-compat.js";
 import { AgentManager } from "./agent-manager.js";
 import { initConfig } from "./config.js";
 import { type AgentActivity, type NotificationDetails, BUILTIN_TYPES } from "./types.js";
@@ -756,9 +756,11 @@ Guidelines:
           });
         }
 
+        const output = boundHelperOutput(record.result?.trim() || "No output.");
+        record.resultArtifactPath = output.artifactPath;
         return textResult(
           `Agent completed in ${(durationMs / 1000).toFixed(1)}s (${record.toolUses} tool uses${tokenText ? `, ${tokenText} tokens` : ""}).\n\n` +
-            (record.result?.trim() || "No output."),
+            output.text,
           {
             status: "completed",
             toolUses: record.toolUses,
@@ -766,6 +768,9 @@ Guidelines:
             durationMs,
             turnCount: fgState.turnCount,
             maxTurns: fgState.maxTurns,
+            truncated: output.truncated,
+            originalBytes: output.originalBytes,
+            artifactPath: output.artifactPath,
           },
         );
       },
@@ -851,7 +856,13 @@ Guidelines:
         } else if (record.status === "error") {
           output += `Error: ${record.error}`;
         } else {
-          output += record.result?.trim() || "No output.";
+          const bounded = boundHelperOutput(
+            record.result?.trim() || "No output.",
+            64 * 1024,
+            record.resultArtifactPath,
+          );
+          record.resultArtifactPath = bounded.artifactPath;
+          output += bounded.text;
         }
 
         if (record.status !== "running" && record.status !== "queued") {

package/packages/subagents/src/types.ts

@@ -90,6 +90,8 @@ export interface AgentRecord {
   description: string;
   status: "queued" | "running" | "completed" | "aborted" | "stopped" | "error";
   result?: string;
+  /** Private artifact holding the complete result when model-visible output is bounded. */
+  resultArtifactPath?: string;
   error?: string;
   toolUses: number;
   startedAt: number;