@poncho-ai/harness 0.60.0 → 0.61.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.60.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.61.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
 > node scripts/embed-docs.js && tsup src/index.ts --format esm --dts
 
 [embed-docs] Generated poncho-docs.ts with 4 topics
@@ -9,8 +9,8 @@
 CLI Target: es2022
 ESM Build start
 ESM dist/isolate-F2PPSUL6.js 53.82 KB
-ESM dist/index.js            574.06 KB
-ESM ⚡️ Build success in 251ms
+ESM dist/index.js            579.17 KB
+ESM ⚡️ Build success in 267ms
 DTS Build start
-DTS ⚡️ Build success in 7890ms
-DTS dist/index.d.ts 105.18 KB
+DTS ⚡️ Build success in 8217ms
+DTS dist/index.d.ts 108.62 KB

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @poncho-ai/harness
 
+## 0.61.0
+
+### Minor Changes
+
+- [#192](https://github.com/cesr/poncho-ai/pull/192) [`bfd8012`](https://github.com/cesr/poncho-ai/commit/bfd80125ad71cd4401221c598faebf71afda2078) Thanks [@cesr](https://github.com/cesr)! - Fix context-compaction correctness so the agent stops losing context and
+  mislabeling failed work after a compaction:
+  - **Turn-based retention.** Compaction now preserves the last N whole _turns_
+    verbatim (new `compaction.keepRecentTurns`, default 4) instead of N messages,
+    which in tool-heavy turns collapsed to just the summary. The preserved side is
+    bounded by a token budget (≤ 50% of the context window) so keeping recent turns
+    can't leave the post-compaction context above the trigger (re-compaction
+    thrash / overflow). Adds exported `findSafeSplitPointByTurns`.
+  - **Faithful summaries.** The summarization output cap is raised 768 → 8192
+    tokens (768 physically truncated summaries mid-content); per-message truncation
+    1200 → 4000 chars, with a total summarizer-input budget that drops the oldest
+    non-error messages first. The prompt now requires a non-omittable "Unresolved
+    errors & failures" section, a "Pending promises" section, forbids claiming
+    unconfirmed completion, and preserves identifiers verbatim.
+  - **Structured subagent task outcome.** New `PendingSubagentResult.taskOutcome`
+    (`succeeded | failed | partial | unknown`) distinct from run status: a subagent
+    that ran but failed its task is no longer recorded as "completed". Subagents
+    self-report a machine-readable verdict; it is parsed deterministically
+    (defaulting to "unknown", never success) and rendered in the callback header
+    and compaction ledger. The subagent digest is enlarged (2000 chars, ungated on
+    status) so the failure reason survives compaction.
+  - **Per-run `maxSteps` override.** New `RunInput.maxSteps` lets a caller raise the
+    step ceiling for foreground turns without raising it for background/job turns
+    that share the same agent definition.
+
+### Patch Changes
+
+- Updated dependencies [[`bfd8012`](https://github.com/cesr/poncho-ai/commit/bfd80125ad71cd4401221c598faebf71afda2078)]:
+  - @poncho-ai/sdk@1.17.0
+
+## 0.60.1
+
+### Patch Changes
+
+- [`47d92ba`](https://github.com/cesr/poncho-ai/commit/47d92ba6e0001147423ffda39f9dbeb29b5ca359) Thanks [@cesr](https://github.com/cesr)! - Forward `volatileContext` and `telemetryAttributes` through `continueFromToolResult`. The per-conversation capture already covers same-process continuations, but a checkpoint resumed after a process restart would silently lose the embedder's volatile blocks; resume callers can now pass them explicitly.
+
 ## 0.60.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -43,6 +43,16 @@ interface AgentFrontmatter {
 interface CompactionConfig {
     enabled: boolean;
     trigger: number;
+    /**
+     * Primary retention unit: number of whole recent *turns* (a user message plus
+     * the assistant/tool messages that follow it) preserved verbatim after the
+     * summary. See `findSafeSplitPointByTurns`.
+     */
+    keepRecentTurns: number;
+    /**
+     * Fallback retention floor, in messages, used only for the single-giant-turn
+     * case where no turn boundary yields a safe split.
+     */
     keepRecentMessages: number;
     instructions?: string;
 }
@@ -105,8 +115,37 @@ declare const estimateTotalTokens: (systemPrompt: string, messages: Message[], t
  * Returns -1 if no valid split point is found.
  */
 declare const findSafeSplitPoint: (messages: Message[], keepRecentMessages: number) => number;
+/**
+ * Find the split index that preserves the last `keepRecentTurns` whole *turns*
+ * verbatim. A turn begins at a `role:"user"` message and runs until the next
+ * `user` message. Everything before the split is folded into the summary;
+ * everything from the split onward is kept as-is.
+ *
+ * Two guards make a candidate split acceptable:
+ *  1. The compacted side has at least `MIN_COMPACTABLE_MESSAGES` messages.
+ *  2. The preserved side estimates at most `maxPreservedTokens` — so keeping N
+ *     large turns can never leave the post-compaction context above the
+ *     compaction trigger (which caused re-compaction thrash / window overflow).
+ * The tool-call-orphan guard (`splitOrphansToolCalls`) is preserved: a split
+ * that would strand an assistant tool-call on the compacted side steps to an
+ * earlier user boundary (which only preserves more, always safe).
+ *
+ * We try the largest N (up to `keepRecentTurns`) first and decrement, so we
+ * keep as many turns as fit. If no turn boundary yields a safe split (e.g. a
+ * single giant turn near the window), fall back to the message-based
+ * `findSafeSplitPoint` so the middle of that turn still compacts.
+ *
+ * Returns -1 when nothing safe can be compacted.
+ */
+declare const findSafeSplitPointByTurns: (messages: Message[], keepRecentTurns: number, keepRecentMessagesFallback: number, maxPreservedTokens: number) => number;
 interface CompactMessagesOptions {
     instructions?: string;
+    /**
+     * The model's context window (tokens). Used to bound the preserved side of a
+     * turn-based split so keeping N recent turns can't leave the post-compaction
+     * context above the compaction trigger. Defaults to 200k when omitted.
+     */
+    contextWindow?: number;
 }
 interface CompactResult {
     compacted: boolean;
@@ -207,10 +246,22 @@ interface StateStore {
     set(state: ConversationState): Promise<void>;
     delete(runId: string): Promise<void>;
 }
+/**
+ * Whether a subagent actually accomplished its task — distinct from the *run*
+ * status (`status` below), which is "completed" whenever the run merely
+ * finished. A subagent that ran to completion but could not do the task (e.g.
+ * lacked the required tools) is `runStatus:"completed"` but `taskOutcome:
+ * "failed"`. Derived at subagent finalize; "unknown" when it can't be
+ * determined. Consumed by the compaction subagent ledger so a failed task can
+ * never be summarized as "completed".
+ */
+type SubagentTaskOutcome = "succeeded" | "failed" | "partial" | "unknown";
 interface PendingSubagentResult {
     subagentId: string;
     task: string;
     status: "completed" | "error" | "stopped";
+    /** Did the subagent accomplish its task? See {@link SubagentTaskOutcome}. */
+    taskOutcome: SubagentTaskOutcome;
     result?: _poncho_ai_sdk.RunResult;
     error?: _poncho_ai_sdk.AgentFailure;
     timestamp: number;
@@ -1635,6 +1686,13 @@ declare class AgentHarness {
          *  otherwise the continuation falls back to the agent definition's
          *  (possibly concurrently-mutated) frontmatter model. */
         model?: string;
+        /** Same as `RunInput.volatileContext`. Pass it explicitly on resume —
+         *  the per-conversation capture covers same-process continuations, but
+         *  a checkpoint resumed after a restart would otherwise lose the
+         *  embedder's volatile blocks. */
+        volatileContext?: string;
+        /** Same as `RunInput.telemetryAttributes`, for the continuation run. */
+        telemetryAttributes?: Record<string, string>;
     }): AsyncGenerator<AgentEvent>;
     runToCompletion(input: RunInput): Promise<HarnessRunOutput>;
 }
@@ -2397,6 +2455,12 @@ interface RunConversationTurnOpts {
      * built with an OTLP exporter attached.
      */
     suppressTelemetry?: boolean;
+    /**
+     * Forwarded to `RunInput.maxSteps`: per-run step-ceiling override. Lets the
+     * foreground chat turn run a higher ceiling than background/job turns that
+     * share the same agent definition.
+     */
+    maxSteps?: number;
     /**
      * Forwarded to `RunInput.telemetryAttributes` — extra attributes for the
      * `invoke_agent` root span (e.g. run kind / job name for segmentation).
@@ -2439,4 +2503,4 @@ type NewEntryNoId = NewConversationEntry extends infer T ? T extends NewConversa
  */
 declare const appendEntriesSafe: (store: ConversationStore, conversation: Pick<Conversation, "conversationId" | "ownerId" | "tenantId">, entries: NewEntryNoId[], log: Logger) => Promise<ConversationEntry[]>;
 
-export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CallbackStartedEntry, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationEntry, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TAGLINE, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type MountProvider, type NetworkConfig, type NewConversationEntry, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentResultEntry, type SubagentSpawnResult, type SubagentSummary, type SubagentTranscript, type SubagentTranscriptMode, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, abnormalEndResponse, appendEntriesSafe, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, decodeFileInputData, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPendingSubagentResults, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, lastAssistantText, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadSkillMetadataFromDirs, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, normalizeToolAccess, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, realResponseText, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, stripPillMetaTokens, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };
+export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CallbackStartedEntry, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationEntry, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TAGLINE, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type MountProvider, type NetworkConfig, type NewConversationEntry, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentResultEntry, type SubagentSpawnResult, type SubagentSummary, type SubagentTaskOutcome, type SubagentTranscript, type SubagentTranscriptMode, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, abnormalEndResponse, appendEntriesSafe, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, decodeFileInputData, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, findSafeSplitPointByTurns, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPendingSubagentResults, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, lastAssistantText, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadSkillMetadataFromDirs, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, normalizeToolAccess, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, realResponseText, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, stripPillMetaTokens, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };

package/dist/index.js

@@ -232,9 +232,10 @@ var parseAgentMarkdown = (content) => {
           "Invalid AGENT.md frontmatter compaction.trigger: must be between 0.1 and 1."
         );
       }
+      const keepRecentTurns = typeof raw.keepRecentTurns === "number" ? Math.max(1, Math.floor(raw.keepRecentTurns)) : 4;
       const keepRecentMessages = typeof raw.keepRecentMessages === "number" ? Math.max(2, Math.floor(raw.keepRecentMessages)) : 6;
       const instructions = typeof raw.instructions === "string" && raw.instructions.trim() ? raw.instructions.trim() : void 0;
-      return { enabled, trigger, keepRecentMessages, instructions };
+      return { enabled, trigger, keepRecentTurns, keepRecentMessages, instructions };
     })(),
     cron: parseCronJobs(parsed.cron)
   };
@@ -359,29 +360,37 @@ var MIN_COMPACTABLE_MESSAGES = 4;
 var DEFAULT_COMPACTION_CONFIG = {
   enabled: true,
   trigger: 0.75,
-  keepRecentMessages: 4
+  keepRecentTurns: 4,
+  keepRecentMessages: 6
 };
-var SUMMARIZATION_MESSAGE_TRUNCATION_CHARS = 1200;
-var SUMMARIZATION_MAX_OUTPUT_TOKENS = 768;
+var SUMMARIZATION_MESSAGE_TRUNCATION_CHARS = 4e3;
+var SUMMARIZATION_MAX_OUTPUT_TOKENS = 8192;
+var SUMMARIZATION_MAX_INPUT_TOKENS = 12e4;
 var SUMMARIZATION_PROMPT = `Summarize the following conversation into a structured working state that allows continuation without re-asking questions. Include:
 
 1. **User intent**: What the user originally asked for and any refinements
-2. **Completed work**: What has been accomplished so far
+2. **Completed work**: What has been accomplished AND CONFIRMED so far
 3. **Key decisions**: Technical decisions made and their rationale
-4. **Errors & fixes**: Errors encountered and how they were resolved
-5. **Referenced resources**: Files, URLs, tools, or data referenced
-6. **Pending next steps**: What remains to be done
+4. **Unresolved errors & failures**: Every error, failed or uncertain tool call, and failed or incomplete subagent \u2014 recorded verbatim enough to act on. NEVER drop a failure because it is old. This section is REQUIRED whenever any failure occurred; do not omit it.
+5. **Pending promises**: Anything the assistant said it WOULD do but has not confirmed done.
+6. **Referenced resources**: Files, URLs, tools, or data referenced
+7. **Pending next steps**: What remains to be done
+
+Rules:
+- NEVER describe work as "completed", "done", or "fixed" unless the conversation contains explicit confirmation (a successful tool result or the user acknowledging it). If completion is unverified, record it under "Pending next steps" as unconfirmed.
+- Preserve identifiers verbatim \u2014 file paths, URLs, IDs, command names, tool names. Do not paraphrase or truncate them.
 
 Be concise but preserve all information needed to continue the task.
-Omit any section that has no relevant content.`;
+Omit any section that has no relevant content, EXCEPT "Unresolved errors & failures" when a failure occurred.`;
 var CUMULATIVE_SUMMARY_PROMPT = `The FIRST message below (tagged [prior-summary]) is an existing working-state summary produced by an earlier compaction. Treat it as the authoritative prior working state: MERGE AND UPDATE it with the newer messages that follow it, carrying forward all still-relevant detail. Do NOT discard or re-compress information from the prior summary just because it is older \u2014 only drop it if the newer messages explicitly supersede it.`;
-var SUBAGENT_DIGEST_CHARS = 500;
+var SUBAGENT_DIGEST_CHARS = 2e3;
 var SUBAGENT_LEDGER_HEADING = "## Subagents";
 var resolveCompactionConfig = (explicit) => {
   if (!explicit) return { ...DEFAULT_COMPACTION_CONFIG };
   return {
     enabled: explicit.enabled ?? DEFAULT_COMPACTION_CONFIG.enabled,
     trigger: explicit.trigger ?? DEFAULT_COMPACTION_CONFIG.trigger,
+    keepRecentTurns: explicit.keepRecentTurns ?? DEFAULT_COMPACTION_CONFIG.keepRecentTurns,
     keepRecentMessages: explicit.keepRecentMessages ?? DEFAULT_COMPACTION_CONFIG.keepRecentMessages,
     instructions: explicit.instructions
   };
@@ -433,18 +442,57 @@ var findSafeSplitPoint = (messages, keepRecentMessages) => {
   }
   return -1;
 };
+var findSafeSplitPointByTurns = (messages, keepRecentTurns, keepRecentMessagesFallback, maxPreservedTokens) => {
+  const userIdx = [];
+  for (let i = 0; i < messages.length; i++) {
+    if (messages[i].role === "user") userIdx.push(i);
+  }
+  const maxN = Math.min(keepRecentTurns, userIdx.length);
+  for (let n = maxN; n >= 1; n--) {
+    let guardN = n;
+    let split = userIdx[userIdx.length - guardN];
+    while (splitOrphansToolCalls(messages, split) && guardN < userIdx.length) {
+      guardN++;
+      split = userIdx[userIdx.length - guardN];
+    }
+    if (split < MIN_COMPACTABLE_MESSAGES) continue;
+    const preservedTokens = estimateTokens(
+      messages.slice(split).map((m) => getTextContent(m)).join("\n")
+    );
+    if (preservedTokens <= maxPreservedTokens) return split;
+  }
+  return findSafeSplitPoint(messages, keepRecentMessagesFallback);
+};
 var isCompactionSummary = (msg) => msg.metadata?.isCompactionSummary === true;
+var FAILURE_SIGNAL_RE = /\berror\b|\bfailed\b|\bfailure\b|\bexception\b|could ?n[’']?t|cannot\b|unable to|\[subagent result\]/i;
 var buildSummarizationMessages = (messagesToCompact, instructions) => {
   const hasPriorSummary = messagesToCompact.length > 0 && isCompactionSummary(messagesToCompact[0]);
-  const conversationLines = [];
+  const lines = [];
   for (let i = 0; i < messagesToCompact.length; i++) {
     const msg = messagesToCompact[i];
     const text = getTextContent(msg);
     const isPrior = i === 0 && hasPriorSummary;
     const rendered = isPrior || text.length <= SUMMARIZATION_MESSAGE_TRUNCATION_CHARS ? text : text.slice(0, SUMMARIZATION_MESSAGE_TRUNCATION_CHARS) + "\n...[truncated]";
     const tag = isPrior ? "prior-summary" : msg.role;
-    conversationLines.push(`[${tag}]: ${rendered}`);
+    const line = `[${tag}]: ${rendered}`;
+    lines.push({
+      text: line,
+      tokens: estimateTokens(line),
+      important: isPrior || FAILURE_SIGNAL_RE.test(text)
+    });
   }
+  let total = lines.reduce((sum, l) => sum + l.tokens, 0);
+  if (total > SUMMARIZATION_MAX_INPUT_TOKENS) {
+    for (let i = 0; i < lines.length && total > SUMMARIZATION_MAX_INPUT_TOKENS; ) {
+      if (lines[i].important) {
+        i++;
+        continue;
+      }
+      total -= lines[i].tokens;
+      lines.splice(i, 1);
+    }
+  }
+  const conversationLines = lines.map((l) => l.text);
   let prompt = SUMMARIZATION_PROMPT;
   if (hasPriorSummary) prompt = `${prompt}
 
@@ -475,7 +523,7 @@ var parseSubagentCallback = (msg) => {
   const subagentId = typeof meta.subagentId === "string" && meta.subagentId ? meta.subagentId : headerMatch?.[2] ?? "";
   if (!subagentId) return null;
   const task = typeof meta.task === "string" && meta.task ? meta.task : headerMatch?.[1] ?? "";
-  const status = headerMatch?.[3] ?? "completed";
+  const status = typeof meta.taskOutcome === "string" && meta.taskOutcome || headerMatch?.[3] || "unknown";
   const bodyStart = text.indexOf("\n\n");
   const body = bodyStart >= 0 ? text.slice(bodyStart + 2) : text;
   const digest = body.length > SUBAGENT_DIGEST_CHARS ? body.slice(0, SUBAGENT_DIGEST_CHARS) + "\u2026" : body;
@@ -535,8 +583,18 @@ ${summary}
 Continue from where the conversation left off without re-asking questions.`,
   metadata: { isCompactionSummary: true, timestamp: Date.now() }
 });
+var MAX_PRESERVED_CONTEXT_FRACTION = 0.5;
 var compactMessages = async (model, messages, config, options) => {
-  const splitIdx = findSafeSplitPoint(messages, config.keepRecentMessages);
+  const contextWindow = options?.contextWindow && options.contextWindow > 0 ? options.contextWindow : 2e5;
+  const maxPreservedTokens = Math.floor(
+    contextWindow * MAX_PRESERVED_CONTEXT_FRACTION
+  );
+  const splitIdx = findSafeSplitPointByTurns(
+    messages,
+    config.keepRecentTurns,
+    config.keepRecentMessages,
+    maxPreservedTokens
+  );
   if (splitIdx === -1) {
     return {
       compacted: false,
@@ -10790,7 +10848,11 @@ var AgentHarness = class _AgentHarness {
     const modelName = agent.frontmatter.model?.name ?? "claude-opus-4-5";
     const modelInstance = this.modelProvider(modelName);
     const config = resolveCompactionConfig(agent.frontmatter.compaction);
-    return compactMessages(modelInstance, messages, config, options);
+    const contextWindow = agent.frontmatter.model?.contextWindow ?? getModelContextWindow(modelName);
+    return compactMessages(modelInstance, messages, config, {
+      ...options,
+      contextWindow: options?.contextWindow ?? contextWindow
+    });
   }
   async *run(input) {
     if (!this.parsedAgent) {
@@ -10811,7 +10873,7 @@ var AgentHarness = class _AgentHarness {
     let agent = this.parsedAgent;
     const runId = `run_${randomUUID5()}`;
     const start = now();
-    const maxSteps = agent.frontmatter.limits?.maxSteps ?? 20;
+    const maxSteps = input.maxSteps ?? agent.frontmatter.limits?.maxSteps ?? 20;
     const configuredTimeout = this.runTimeoutSecOverride ?? agent.frontmatter.limits?.timeout;
     const timeoutMs = this.environment === "development" && configuredTimeout == null ? 0 : (configuredTimeout ?? 300) * 1e3;
     const platformMaxDurationSec = Number(process.env.PONCHO_MAX_DURATION) || 0;
@@ -11383,7 +11445,8 @@ ${textContent}` };
               const compactResult = await compactMessages(
                 modelInstance,
                 messages,
-                compactionConfig
+                compactionConfig,
+                { contextWindow }
               );
               if (compactResult.compacted) {
                 messages.length = 0;
@@ -12229,7 +12292,9 @@ ${this.skillFingerprint}`;
       parameters: input.parameters,
       abortSignal: input.abortSignal,
       suppressTelemetry: input.suppressTelemetry,
-      model: input.model
+      model: input.model,
+      volatileContext: input.volatileContext,
+      telemetryAttributes: input.telemetryAttributes
     });
   }
   async runToCompletion(input) {
@@ -13035,6 +13100,17 @@ var abnormalEndResponse = (opts) => {
 
 ${opts.gathered}` : `${head} ${recover}`;
 };
+var SUBAGENT_OUTCOME_RE = /\[\[\s*OUTCOME\s*:\s*(succeeded|failed|partial)\s*\]\]/i;
+var SUBAGENT_OUTCOME_INSTRUCTION = "\n\nAt the very end of your final message, on its own line, append a machine-readable outcome verdict for the task you were given: `[[OUTCOME: succeeded]]`, `[[OUTCOME: partial]]`, or `[[OUTCOME: failed]]`, followed by a one-line reason. Judge honestly by whether YOU actually accomplished the task (produced the real result / wrote the files), not by whether the run finished. If a tool or capability you needed was missing, that is `failed`.";
+var deriveTaskOutcome = (gathered, abnormal) => {
+  if (abnormal) return "failed";
+  if (!gathered.trim()) return "failed";
+  const m = gathered.match(SUBAGENT_OUTCOME_RE);
+  if (!m) return "unknown";
+  const v = m[1].toLowerCase();
+  return v === "succeeded" ? "succeeded" : v === "partial" ? "partial" : "failed";
+};
+var stripOutcomeVerdict = (text) => text.replace(/\n*\[\[\s*OUTCOME\s*:\s*(?:succeeded|failed|partial)\s*\]\].*$/is, "").trimEnd();
 var AgentOrchestrator = class {
   harness;
   conversationStore;
@@ -13478,6 +13554,7 @@ var AgentOrchestrator = class {
       subagentId,
       task: conv.subagentMeta?.task ?? conv.title,
       status: "completed",
+      taskOutcome: deriveTaskOutcome(responseText, false),
       result: { status: "completed", response: responseText, steps: 0, tokens: { input: 0, output: 0, cached: 0 }, duration: 0 },
       timestamp: Date.now()
     };
@@ -13579,7 +13656,11 @@ var AgentOrchestrator = class {
       const harnessMessages = [...runOutcome.messages];
       const recallParams = this.hooks?.buildRecallParams?.({ ownerId, tenantId: conversation.tenantId, excludeConversationId: childConversationId }) ?? {};
       for await (const event of childHarness.runWithTelemetry({
-        task,
+        // Ask the subagent to self-report a machine-readable task outcome at the
+        // end of its final message; `deriveTaskOutcome` parses it so a failed
+        // task can never be recorded as "completed". Appended only to the model
+        // input, not the stored/displayed task name.
+        task: `${task}${SUBAGENT_OUTCOME_INSTRUCTION}`,
         conversationId: childConversationId,
         tenantId: conversation.tenantId ?? void 0,
         parameters: withToolResultArchiveParam({
@@ -13766,11 +13847,14 @@ var AgentOrchestrator = class {
         if (freshSubConv) gathered = realResponseText(lastAssistantText(freshSubConv.messages));
       }
       const abnormal = !runResult;
-      const subagentResponse = abnormal ? abnormalEndResponse({ subagentId: childConversationId, gathered, runError }) : gathered;
+      const taskOutcome = deriveTaskOutcome(gathered, abnormal);
+      const cleanedGathered = stripOutcomeVerdict(gathered);
+      const subagentResponse = abnormal ? abnormalEndResponse({ subagentId: childConversationId, gathered: cleanedGathered, runError }) : cleanedGathered;
       const pendingResult = {
         subagentId: childConversationId,
         task,
         status: abnormal ? "error" : "completed",
+        taskOutcome,
         result: {
           status: runResult?.status ?? "error",
           response: subagentResponse,
@@ -13811,6 +13895,7 @@ var AgentOrchestrator = class {
         subagentId: childConversationId,
         task,
         status: "error",
+        taskOutcome: "failed",
         error: { code: "SUBAGENT_ERROR", message: errMsg },
         timestamp: Date.now()
       };
@@ -13878,10 +13963,10 @@ Response: ${responseLine}
 Steps: ${pr.result.steps}, Duration: ${pr.result.duration}ms` : pr.error ? `Error: ${pr.error.message}` : "(no result)";
       const injected = {
         role: "user",
-        content: `[Subagent Result] Subagent "${pr.task}" (${pr.subagentId}) ${pr.status}:
+        content: `[Subagent Result] Subagent "${pr.task}" (${pr.subagentId}) ${pr.taskOutcome}:
 
 ${resultBody}`,
-        metadata: { _subagentCallback: true, subagentId: pr.subagentId, task: pr.task, timestamp: pr.timestamp }
+        metadata: { _subagentCallback: true, subagentId: pr.subagentId, task: pr.task, taskOutcome: pr.taskOutcome, timestamp: pr.timestamp }
       };
       injectedCallbackMessages.push(injected);
       conversation.messages.push(injected);
@@ -14164,13 +14249,16 @@ ${resultBody}`,
         if (freshSubConv) gathered = realResponseText(lastAssistantText(freshSubConv.messages));
       }
       const abnormal = !runResult;
-      const subagentResponse = abnormal ? abnormalEndResponse({ subagentId: conversationId, gathered, runError }) : gathered;
+      const taskOutcome = deriveTaskOutcome(gathered, abnormal);
+      const cleanedGathered = stripOutcomeVerdict(gathered);
+      const subagentResponse = abnormal ? abnormalEndResponse({ subagentId: conversationId, gathered: cleanedGathered, runError }) : cleanedGathered;
       const parentConv = await this.conversationStore.get(parentConversationId);
       if (parentConv) {
         const result = {
           subagentId: conversationId,
           task,
           status: abnormal ? "error" : "completed",
+          taskOutcome,
           result: { status: runResult?.status ?? "error", response: subagentResponse, steps: runResult?.steps ?? 0, tokens: { input: 0, output: 0, cached: 0 }, duration: runResult?.duration ?? 0 },
           ...abnormal ? { error: { code: runError?.code ?? "SUBAGENT_INCOMPLETE", message: runError?.message ?? "subagent ended without a result" } } : {},
           timestamp: Date.now()
@@ -14219,6 +14307,7 @@ ${resultBody}`,
           subagentId: conversationId,
           task,
           status: "error",
+          taskOutcome: "failed",
           error: { code: "CONTINUATION_ERROR", message: err instanceof Error ? err.message : String(err) },
           timestamp: Date.now()
         };
@@ -14462,6 +14551,7 @@ ${resultBody}`,
       subagentId: childConversationId,
       task,
       status: "error",
+      taskOutcome: "failed",
       error: { code: "SUBAGENT_SPAWN_FAILED", message },
       timestamp: Date.now()
     });
@@ -14493,6 +14583,7 @@ ${resultBody}`,
             subagentId: conv.conversationId,
             task: conv.subagentMeta.task,
             status: "error",
+            taskOutcome: "failed",
             error: conv.subagentMeta.error,
             timestamp: Date.now()
           };
@@ -14635,6 +14726,7 @@ var runConversationTurn = async (opts) => {
         disablePromptCache: opts.disablePromptCache,
         suppressTelemetry: opts.suppressTelemetry,
         model: opts.model,
+        maxSteps: opts.maxSteps,
         volatileContext: opts.volatileContext,
         telemetryAttributes: opts.telemetryAttributes
       },
@@ -14979,6 +15071,7 @@ export {
   estimateTotalTokens,
   executeConversationTurn,
   findSafeSplitPoint,
+  findSafeSplitPointByTurns,
   flushTurnDraft,
   generateAgentId,
   getAgentStoreDirectory,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "mustache": "^4.2.0",
     "yaml": "^2.4.0",
     "zod": "^3.22.0",
-    "@poncho-ai/sdk": "1.16.0"
+    "@poncho-ai/sdk": "1.17.0"
   },
   "peerDependencies": {
     "esbuild": ">=0.17.0",

package/src/agent-parser.ts

@@ -52,6 +52,16 @@ export interface AgentFrontmatter {
 export interface CompactionConfig {
   enabled: boolean;
   trigger: number;
+  /**
+   * Primary retention unit: number of whole recent *turns* (a user message plus
+   * the assistant/tool messages that follow it) preserved verbatim after the
+   * summary. See `findSafeSplitPointByTurns`.
+   */
+  keepRecentTurns: number;
+  /**
+   * Fallback retention floor, in messages, used only for the single-giant-turn
+   * case where no turn boundary yields a safe split.
+   */
   keepRecentMessages: number;
   instructions?: string;
 }
@@ -306,6 +316,10 @@ export const parseAgentMarkdown = (content: string): ParsedAgent => {
           "Invalid AGENT.md frontmatter compaction.trigger: must be between 0.1 and 1.",
         );
       }
+      const keepRecentTurns =
+        typeof raw.keepRecentTurns === "number"
+          ? Math.max(1, Math.floor(raw.keepRecentTurns))
+          : 4;
       const keepRecentMessages =
         typeof raw.keepRecentMessages === "number"
           ? Math.max(2, Math.floor(raw.keepRecentMessages))
@@ -314,7 +328,7 @@ export const parseAgentMarkdown = (content: string): ParsedAgent => {
         typeof raw.instructions === "string" && raw.instructions.trim()
           ? raw.instructions.trim()
           : undefined;
-      return { enabled, trigger, keepRecentMessages, instructions };
+      return { enabled, trigger, keepRecentTurns, keepRecentMessages, instructions };
     })(),
     cron: parseCronJobs(parsed.cron),
   };

package/src/compaction.ts

@@ -9,22 +9,36 @@ const MIN_COMPACTABLE_MESSAGES = 4;
 const DEFAULT_COMPACTION_CONFIG: CompactionConfig = {
   enabled: true,
   trigger: 0.75,
-  keepRecentMessages: 4,
+  keepRecentTurns: 4,
+  keepRecentMessages: 6,
 };
-const SUMMARIZATION_MESSAGE_TRUNCATION_CHARS = 1200;
-const SUMMARIZATION_MAX_OUTPUT_TOKENS = 768;
+const SUMMARIZATION_MESSAGE_TRUNCATION_CHARS = 4000;
+const SUMMARIZATION_MAX_OUTPUT_TOKENS = 8192;
+/**
+ * Upper bound on the tokens fed INTO the summarization model call. With hundreds
+ * of compacted messages at 4000 chars each the joined transcript can exceed the
+ * summarizer's own window; we drop the oldest non-error, non-prior-summary
+ * messages first so recent context and every failure survive. Held well under a
+ * 200k window to leave room for the prompt + output.
+ */
+const SUMMARIZATION_MAX_INPUT_TOKENS = 120_000;
 
 const SUMMARIZATION_PROMPT = `Summarize the following conversation into a structured working state that allows continuation without re-asking questions. Include:
 
 1. **User intent**: What the user originally asked for and any refinements
-2. **Completed work**: What has been accomplished so far
+2. **Completed work**: What has been accomplished AND CONFIRMED so far
 3. **Key decisions**: Technical decisions made and their rationale
-4. **Errors & fixes**: Errors encountered and how they were resolved
-5. **Referenced resources**: Files, URLs, tools, or data referenced
-6. **Pending next steps**: What remains to be done
+4. **Unresolved errors & failures**: Every error, failed or uncertain tool call, and failed or incomplete subagent — recorded verbatim enough to act on. NEVER drop a failure because it is old. This section is REQUIRED whenever any failure occurred; do not omit it.
+5. **Pending promises**: Anything the assistant said it WOULD do but has not confirmed done.
+6. **Referenced resources**: Files, URLs, tools, or data referenced
+7. **Pending next steps**: What remains to be done
+
+Rules:
+- NEVER describe work as "completed", "done", or "fixed" unless the conversation contains explicit confirmation (a successful tool result or the user acknowledging it). If completion is unverified, record it under "Pending next steps" as unconfirmed.
+- Preserve identifiers verbatim — file paths, URLs, IDs, command names, tool names. Do not paraphrase or truncate them.
 
 Be concise but preserve all information needed to continue the task.
-Omit any section that has no relevant content.`;
+Omit any section that has no relevant content, EXCEPT "Unresolved errors & failures" when a failure occurred.`;
 
 /**
  * Extra instruction appended when the first compacted message is itself a
@@ -34,8 +48,13 @@ Omit any section that has no relevant content.`;
  */
 const CUMULATIVE_SUMMARY_PROMPT = `The FIRST message below (tagged [prior-summary]) is an existing working-state summary produced by an earlier compaction. Treat it as the authoritative prior working state: MERGE AND UPDATE it with the newer messages that follow it, carrying forward all still-relevant detail. Do NOT discard or re-compress information from the prior summary just because it is older — only drop it if the newer messages explicitly supersede it.`;
 
-/** Max chars of a subagent result text kept verbatim in the ledger digest. */
-const SUBAGENT_DIGEST_CHARS = 500;
+/**
+ * Max chars of a subagent result text kept verbatim in the ledger digest. Kept
+ * large (and NOT gated on outcome) so a failed subagent's own explanation
+ * survives compaction — the failing case is exactly the one that must not be
+ * clipped, and it can be mislabeled, so gating on status would be self-defeating.
+ */
+const SUBAGENT_DIGEST_CHARS = 2000;
 
 /** Heading used for the verbatim, model-proof subagent ledger block. */
 const SUBAGENT_LEDGER_HEADING = "## Subagents";
@@ -47,6 +66,8 @@ export const resolveCompactionConfig = (
   return {
     enabled: explicit.enabled ?? DEFAULT_COMPACTION_CONFIG.enabled,
     trigger: explicit.trigger ?? DEFAULT_COMPACTION_CONFIG.trigger,
+    keepRecentTurns:
+      explicit.keepRecentTurns ?? DEFAULT_COMPACTION_CONFIG.keepRecentTurns,
     keepRecentMessages:
       explicit.keepRecentMessages ??
       DEFAULT_COMPACTION_CONFIG.keepRecentMessages,
@@ -162,6 +183,71 @@ export const findSafeSplitPoint = (
   return -1;
 };
 
+/**
+ * Find the split index that preserves the last `keepRecentTurns` whole *turns*
+ * verbatim. A turn begins at a `role:"user"` message and runs until the next
+ * `user` message. Everything before the split is folded into the summary;
+ * everything from the split onward is kept as-is.
+ *
+ * Two guards make a candidate split acceptable:
+ *  1. The compacted side has at least `MIN_COMPACTABLE_MESSAGES` messages.
+ *  2. The preserved side estimates at most `maxPreservedTokens` — so keeping N
+ *     large turns can never leave the post-compaction context above the
+ *     compaction trigger (which caused re-compaction thrash / window overflow).
+ * The tool-call-orphan guard (`splitOrphansToolCalls`) is preserved: a split
+ * that would strand an assistant tool-call on the compacted side steps to an
+ * earlier user boundary (which only preserves more, always safe).
+ *
+ * We try the largest N (up to `keepRecentTurns`) first and decrement, so we
+ * keep as many turns as fit. If no turn boundary yields a safe split (e.g. a
+ * single giant turn near the window), fall back to the message-based
+ * `findSafeSplitPoint` so the middle of that turn still compacts.
+ *
+ * Returns -1 when nothing safe can be compacted.
+ */
+export const findSafeSplitPointByTurns = (
+  messages: Message[],
+  keepRecentTurns: number,
+  keepRecentMessagesFallback: number,
+  maxPreservedTokens: number,
+): number => {
+  // Indices of every user message, in order.
+  const userIdx: number[] = [];
+  for (let i = 0; i < messages.length; i++) {
+    if (messages[i]!.role === "user") userIdx.push(i);
+  }
+
+  const maxN = Math.min(keepRecentTurns, userIdx.length);
+  for (let n = maxN; n >= 1; n--) {
+    // The Nth-from-last user message starts the preserved region.
+    let guardN = n;
+    let split = userIdx[userIdx.length - guardN]!;
+    // Orphan guard: step to an earlier user boundary if the compacted side
+    // would end on an assistant tool-call whose result moved to the preserved
+    // side. Walking earlier only preserves more, so it stays within budget
+    // checks below.
+    while (
+      splitOrphansToolCalls(messages, split) &&
+      guardN < userIdx.length
+    ) {
+      guardN++;
+      split = userIdx[userIdx.length - guardN]!;
+    }
+    if (split < MIN_COMPACTABLE_MESSAGES) continue;
+    const preservedTokens = estimateTokens(
+      messages
+        .slice(split)
+        .map((m) => getTextContent(m))
+        .join("\n"),
+    );
+    if (preservedTokens <= maxPreservedTokens) return split;
+  }
+
+  // No turn boundary fits: fall back to the legacy message-based split so a
+  // single giant turn still gets its middle compacted.
+  return findSafeSplitPoint(messages, keepRecentMessagesFallback);
+};
+
 /**
  * Whether a message is itself a prior compaction summary.
  */
@@ -175,8 +261,17 @@ const isCompactionSummary = (msg: Message): boolean =>
  * compaction summary, it is passed in FULL (not truncated to
  * SUMMARIZATION_MESSAGE_TRUNCATION_CHARS) and tagged `[prior-summary]`, and
  * the prompt instructs the model to merge-and-update rather than
- * re-summarize. All other messages keep the 1200-char truncation.
+ * re-summarize. All other messages keep the per-message truncation.
+ *
+ * Total-input budget: with many messages the joined transcript can exceed the
+ * summarizer's own window, so we cap it at SUMMARIZATION_MAX_INPUT_TOKENS and
+ * drop the OLDEST non-important lines first. A line is "important" (never
+ * dropped) if it is the prior summary or carries a failure/error signal — so
+ * every failure and the most recent context always reach the summarizer.
  */
+const FAILURE_SIGNAL_RE =
+  /\berror\b|\bfailed\b|\bfailure\b|\bexception\b|could ?n[’']?t|cannot\b|unable to|\[subagent result\]/i;
+
 const buildSummarizationMessages = (
   messagesToCompact: Message[],
   instructions?: string,
@@ -184,7 +279,12 @@ const buildSummarizationMessages = (
   const hasPriorSummary =
     messagesToCompact.length > 0 && isCompactionSummary(messagesToCompact[0]!);
 
-  const conversationLines: string[] = [];
+  interface Line {
+    text: string;
+    tokens: number;
+    important: boolean;
+  }
+  const lines: Line[] = [];
   for (let i = 0; i < messagesToCompact.length; i++) {
     const msg = messagesToCompact[i]!;
     const text = getTextContent(msg);
@@ -196,9 +296,29 @@ const buildSummarizationMessages = (
         : text.slice(0, SUMMARIZATION_MESSAGE_TRUNCATION_CHARS) +
           "\n...[truncated]";
     const tag = isPrior ? "prior-summary" : msg.role;
-    conversationLines.push(`[${tag}]: ${rendered}`);
+    const line = `[${tag}]: ${rendered}`;
+    lines.push({
+      text: line,
+      tokens: estimateTokens(line),
+      important: isPrior || FAILURE_SIGNAL_RE.test(text),
+    });
   }
 
+  // Enforce the input budget: while over, drop the oldest non-important line.
+  let total = lines.reduce((sum, l) => sum + l.tokens, 0);
+  if (total > SUMMARIZATION_MAX_INPUT_TOKENS) {
+    for (let i = 0; i < lines.length && total > SUMMARIZATION_MAX_INPUT_TOKENS; ) {
+      if (lines[i]!.important) {
+        i++;
+        continue;
+      }
+      total -= lines[i]!.tokens;
+      lines.splice(i, 1);
+    }
+  }
+
+  const conversationLines = lines.map((l) => l.text);
+
   let prompt = SUMMARIZATION_PROMPT;
   if (hasPriorSummary) prompt = `${prompt}\n\n${CUMULATIVE_SUMMARY_PROMPT}`;
   if (instructions) prompt = `${prompt}\n\nAdditional focus: ${instructions}`;
@@ -246,7 +366,15 @@ const parseSubagentCallback = (msg: Message): SubagentLedgerEntry | null => {
     typeof meta.task === "string" && meta.task
       ? meta.task
       : headerMatch?.[1] ?? "";
-  const status = headerMatch?.[3] ?? "completed";
+  // The ledger "status" is the subagent's TASK OUTCOME (succeeded/failed/
+  // partial/unknown), not its run status. Prefer the structured metadata; fall
+  // back to the header token. NEVER default to "completed" — an unparseable
+  // header must not silently assert success. `status` remains the field name
+  // for backward compat with parsePriorLedger's rendered shape.
+  const status =
+    (typeof meta.taskOutcome === "string" && meta.taskOutcome) ||
+    headerMatch?.[3] ||
+    "unknown";
 
   // Digest = the body after the header line (the result text), capped.
   const bodyStart = text.indexOf("\n\n");
@@ -338,8 +466,17 @@ const buildContinuationMessage = (summary: string): Message => ({
 
 export interface CompactMessagesOptions {
   instructions?: string;
+  /**
+   * The model's context window (tokens). Used to bound the preserved side of a
+   * turn-based split so keeping N recent turns can't leave the post-compaction
+   * context above the compaction trigger. Defaults to 200k when omitted.
+   */
+  contextWindow?: number;
 }
 
+/** Fraction of the context window the preserved (verbatim) side may occupy. */
+const MAX_PRESERVED_CONTEXT_FRACTION = 0.5;
+
 export interface CompactResult {
   compacted: boolean;
   messages: Message[];
@@ -363,7 +500,18 @@ export const compactMessages = async (
   config: CompactionConfig,
   options?: CompactMessagesOptions,
 ): Promise<CompactResult> => {
-  const splitIdx = findSafeSplitPoint(messages, config.keepRecentMessages);
+  const contextWindow = options?.contextWindow && options.contextWindow > 0
+    ? options.contextWindow
+    : 200_000;
+  const maxPreservedTokens = Math.floor(
+    contextWindow * MAX_PRESERVED_CONTEXT_FRACTION,
+  );
+  const splitIdx = findSafeSplitPointByTurns(
+    messages,
+    config.keepRecentTurns,
+    config.keepRecentMessages,
+    maxPreservedTokens,
+  );
   if (splitIdx === -1) {
     return {
       compacted: false,

package/src/harness.ts

@@ -2286,7 +2286,12 @@ export class AgentHarness {
     const modelName = agent.frontmatter.model?.name ?? "claude-opus-4-5";
     const modelInstance = this.modelProvider(modelName);
     const config = resolveCompactionConfig(agent.frontmatter.compaction);
-    return compactMessages(modelInstance, messages, config, options);
+    const contextWindow =
+      agent.frontmatter.model?.contextWindow ?? getModelContextWindow(modelName);
+    return compactMessages(modelInstance, messages, config, {
+      ...options,
+      contextWindow: options?.contextWindow ?? contextWindow,
+    });
   }
 
   async *run(input: RunInput): AsyncGenerator<AgentEvent> {
@@ -2317,7 +2322,7 @@ export class AgentHarness {
     let agent = this.parsedAgent as ParsedAgent;
     const runId = `run_${randomUUID()}`;
     const start = now();
-    const maxSteps = agent.frontmatter.limits?.maxSteps ?? 20;
+    const maxSteps = input.maxSteps ?? agent.frontmatter.limits?.maxSteps ?? 20;
     // A constructor-level override (e.g. a longer budget for background
     // subagents) takes precedence over the agent definition's limits.timeout.
     const configuredTimeout = this.runTimeoutSecOverride ?? agent.frontmatter.limits?.timeout;
@@ -3082,6 +3087,7 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
               modelInstance,
               messages,
               compactionConfig,
+              { contextWindow },
             );
             if (compactResult.compacted) {
               messages.length = 0;
@@ -3096,6 +3102,16 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
                   emittedMessages.pop();
                 }
               }
+              // MID-RUN COMPACTION (step > 1) intentionally emits
+              // `compactedMessages: undefined`. The live `messages` array is
+              // already rewritten in place above (so the rest of the run and
+              // the end-of-run `continuationMessages` reflect the compaction),
+              // but we do NOT drive the runner's persisted `compactedHistory`
+              // archive mid-turn: that would require a get→mutate→update on the
+              // conversation row while the turn is still in flight, which is the
+              // clobber pattern PonchOS forbids for non-terminal writers. The
+              // compacted content is preserved in the summary; only the raw
+              // pre-compaction transcript archive skips these mid-run events.
               const tokensAfterCompaction = estimateTotalTokens(systemPrompt, messages, toolDefsJsonForEstimate);
               latestContextTokens = tokensAfterCompaction;
               toolOutputEstimateSinceModel = 0;
@@ -4109,6 +4125,13 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
      *  otherwise the continuation falls back to the agent definition's
      *  (possibly concurrently-mutated) frontmatter model. */
     model?: string;
+    /** Same as `RunInput.volatileContext`. Pass it explicitly on resume —
+     *  the per-conversation capture covers same-process continuations, but
+     *  a checkpoint resumed after a restart would otherwise lose the
+     *  embedder's volatile blocks. */
+    volatileContext?: string;
+    /** Same as `RunInput.telemetryAttributes`, for the continuation run. */
+    telemetryAttributes?: Record<string, string>;
   }): AsyncGenerator<AgentEvent> {
     const messages = [...input.messages];
     const lastMsg = messages[messages.length - 1];
@@ -4169,6 +4192,8 @@ Code is wrapped in an async IIFE — use \`return\` to return a value to the too
       abortSignal: input.abortSignal,
       suppressTelemetry: input.suppressTelemetry,
       model: input.model,
+      volatileContext: input.volatileContext,
+      telemetryAttributes: input.telemetryAttributes,
     });
   }
 

package/src/orchestrator/orchestrator.ts

@@ -107,6 +107,48 @@ export const abnormalEndResponse = (opts: {
   return opts.gathered ? `${head} ${recover}\n\n${opts.gathered}` : `${head} ${recover}`;
 };
 
+/**
+ * Machine-readable verdict a subagent is asked to append to its final message,
+ * e.g. `[[OUTCOME: failed]] reason`. Parsed deterministically — see
+ * SUBAGENT_OUTCOME_INSTRUCTION and `deriveTaskOutcome`.
+ */
+const SUBAGENT_OUTCOME_RE = /\[\[\s*OUTCOME\s*:\s*(succeeded|failed|partial)\s*\]\]/i;
+
+/** Appended to a subagent's task so it self-reports whether it succeeded. */
+export const SUBAGENT_OUTCOME_INSTRUCTION =
+  "\n\nAt the very end of your final message, on its own line, append a " +
+  "machine-readable outcome verdict for the task you were given: " +
+  "`[[OUTCOME: succeeded]]`, `[[OUTCOME: partial]]`, or `[[OUTCOME: failed]]`, " +
+  "followed by a one-line reason. Judge honestly by whether YOU actually " +
+  "accomplished the task (produced the real result / wrote the files), not by " +
+  "whether the run finished. If a tool or capability you needed was missing, " +
+  "that is `failed`.";
+
+/**
+ * Derive a subagent's task outcome (distinct from run status). Abnormal ends and
+ * empty output are `failed`; otherwise we parse the self-declared verdict and
+ * default to `unknown` when absent (never assume success).
+ */
+export const deriveTaskOutcome = (
+  gathered: string,
+  abnormal: boolean,
+): import("../state.js").SubagentTaskOutcome => {
+  if (abnormal) return "failed";
+  if (!gathered.trim()) return "failed";
+  const m = gathered.match(SUBAGENT_OUTCOME_RE);
+  if (!m) return "unknown";
+  const v = m[1]!.toLowerCase();
+  return v === "succeeded" ? "succeeded" : v === "partial" ? "partial" : "failed";
+};
+
+/**
+ * Remove the machine-readable `[[OUTCOME: …]]` verdict (and its one-line reason)
+ * from the text delivered to the parent — the outcome is carried structurally in
+ * the callback header/metadata, so the marker shouldn't leak into chat UI.
+ */
+export const stripOutcomeVerdict = (text: string): string =>
+  text.replace(/\n*\[\[\s*OUTCOME\s*:\s*(?:succeeded|failed|partial)\s*\]\].*$/is, "").trimEnd();
+
 // ── Types ──
 
 export type ActiveConversationRun = {
@@ -697,6 +739,7 @@ export class AgentOrchestrator {
       subagentId,
       task: conv.subagentMeta?.task ?? conv.title,
       status: "completed",
+      taskOutcome: deriveTaskOutcome(responseText, false),
       result: { status: "completed", response: responseText, steps: 0, tokens: { input: 0, output: 0, cached: 0 }, duration: 0 },
       timestamp: Date.now(),
     };
@@ -829,7 +872,11 @@ export class AgentOrchestrator {
       const recallParams = this.hooks?.buildRecallParams?.({ ownerId, tenantId: conversation.tenantId, excludeConversationId: childConversationId }) ?? {};
 
       for await (const event of childHarness.runWithTelemetry({
-        task,
+        // Ask the subagent to self-report a machine-readable task outcome at the
+        // end of its final message; `deriveTaskOutcome` parses it so a failed
+        // task can never be recorded as "completed". Appended only to the model
+        // input, not the stored/displayed task name.
+        task: `${task}${SUBAGENT_OUTCOME_INSTRUCTION}`,
         conversationId: childConversationId,
         tenantId: conversation.tenantId ?? undefined,
         parameters: withToolResultArchiveParam({
@@ -1040,13 +1087,16 @@ export class AgentOrchestrator {
       // the work — deliver what it gathered, tagged so the parent knows it
       // didn't finish, and build a result so it never renders as "(no result)".
       const abnormal = !runResult;
+      const taskOutcome = deriveTaskOutcome(gathered, abnormal);
+      const cleanedGathered = stripOutcomeVerdict(gathered);
       const subagentResponse = abnormal
-        ? abnormalEndResponse({ subagentId: childConversationId, gathered, runError })
-        : gathered;
+        ? abnormalEndResponse({ subagentId: childConversationId, gathered: cleanedGathered, runError })
+        : cleanedGathered;
       const pendingResult: PendingSubagentResult = {
         subagentId: childConversationId,
         task,
         status: abnormal ? "error" : "completed",
+        taskOutcome,
         result: {
           status: runResult?.status ?? "error",
           response: subagentResponse,
@@ -1096,6 +1146,7 @@ export class AgentOrchestrator {
         subagentId: childConversationId,
         task,
         status: "error",
+        taskOutcome: "failed",
         error: { code: "SUBAGENT_ERROR", message: errMsg },
         timestamp: Date.now(),
       };
@@ -1185,8 +1236,8 @@ export class AgentOrchestrator {
           : "(no result)";
       const injected: Message = {
         role: "user",
-        content: `[Subagent Result] Subagent "${pr.task}" (${pr.subagentId}) ${pr.status}:\n\n${resultBody}`,
-        metadata: { _subagentCallback: true, subagentId: pr.subagentId, task: pr.task, timestamp: pr.timestamp } as Message["metadata"],
+        content: `[Subagent Result] Subagent "${pr.task}" (${pr.subagentId}) ${pr.taskOutcome}:\n\n${resultBody}`,
+        metadata: { _subagentCallback: true, subagentId: pr.subagentId, task: pr.task, taskOutcome: pr.taskOutcome, timestamp: pr.timestamp } as Message["metadata"],
       };
       injectedCallbackMessages.push(injected);
       conversation.messages.push(injected);
@@ -1516,9 +1567,11 @@ export class AgentOrchestrator {
         if (freshSubConv) gathered = realResponseText(lastAssistantText(freshSubConv.messages));
       }
       const abnormal = !runResult;
+      const taskOutcome = deriveTaskOutcome(gathered, abnormal);
+      const cleanedGathered = stripOutcomeVerdict(gathered);
       const subagentResponse = abnormal
-        ? abnormalEndResponse({ subagentId: conversationId, gathered, runError })
-        : gathered;
+        ? abnormalEndResponse({ subagentId: conversationId, gathered: cleanedGathered, runError })
+        : cleanedGathered;
 
       const parentConv = await this.conversationStore.get(parentConversationId);
       if (parentConv) {
@@ -1526,6 +1579,7 @@ export class AgentOrchestrator {
           subagentId: conversationId,
           task,
           status: abnormal ? "error" : "completed",
+          taskOutcome,
           result: { status: runResult?.status ?? "error", response: subagentResponse, steps: runResult?.steps ?? 0, tokens: { input: 0, output: 0, cached: 0 }, duration: runResult?.duration ?? 0 },
           ...(abnormal
             ? { error: { code: runError?.code ?? "SUBAGENT_INCOMPLETE", message: runError?.message ?? "subagent ended without a result" } }
@@ -1576,6 +1630,7 @@ export class AgentOrchestrator {
           subagentId: conversationId,
           task,
           status: "error",
+          taskOutcome: "failed",
           error: { code: "CONTINUATION_ERROR", message: err instanceof Error ? err.message : String(err) },
           timestamp: Date.now(),
         };
@@ -1858,6 +1913,7 @@ export class AgentOrchestrator {
       subagentId: childConversationId,
       task,
       status: "error",
+      taskOutcome: "failed",
       error: { code: "SUBAGENT_SPAWN_FAILED", message },
       timestamp: Date.now(),
     });
@@ -1892,6 +1948,7 @@ export class AgentOrchestrator {
             subagentId: conv.conversationId,
             task: conv.subagentMeta.task,
             status: "error",
+            taskOutcome: "failed",
             error: conv.subagentMeta.error,
             timestamp: Date.now(),
           };

package/src/orchestrator/run-conversation-turn.ts

@@ -84,6 +84,12 @@ export interface RunConversationTurnOpts {
    * built with an OTLP exporter attached.
    */
   suppressTelemetry?: boolean;
+  /**
+   * Forwarded to `RunInput.maxSteps`: per-run step-ceiling override. Lets the
+   * foreground chat turn run a higher ceiling than background/job turns that
+   * share the same agent definition.
+   */
+  maxSteps?: number;
   /**
    * Forwarded to `RunInput.telemetryAttributes` — extra attributes for the
    * `invoke_agent` root span (e.g. run kind / job name for segmentation).
@@ -252,6 +258,7 @@ export const runConversationTurn = async (
         disablePromptCache: opts.disablePromptCache,
         suppressTelemetry: opts.suppressTelemetry,
         model: opts.model,
+        maxSteps: opts.maxSteps,
         volatileContext: opts.volatileContext,
         telemetryAttributes: opts.telemetryAttributes,
       },

package/src/state.ts

@@ -17,10 +17,23 @@ export interface StateStore {
   delete(runId: string): Promise<void>;
 }
 
+/**
+ * Whether a subagent actually accomplished its task — distinct from the *run*
+ * status (`status` below), which is "completed" whenever the run merely
+ * finished. A subagent that ran to completion but could not do the task (e.g.
+ * lacked the required tools) is `runStatus:"completed"` but `taskOutcome:
+ * "failed"`. Derived at subagent finalize; "unknown" when it can't be
+ * determined. Consumed by the compaction subagent ledger so a failed task can
+ * never be summarized as "completed".
+ */
+export type SubagentTaskOutcome = "succeeded" | "failed" | "partial" | "unknown";
+
 export interface PendingSubagentResult {
   subagentId: string;
   task: string;
   status: "completed" | "error" | "stopped";
+  /** Did the subagent accomplish its task? See {@link SubagentTaskOutcome}. */
+  taskOutcome: SubagentTaskOutcome;
   result?: import("@poncho-ai/sdk").RunResult;
   error?: import("@poncho-ai/sdk").AgentFailure;
   timestamp: number;

package/test/compaction.test.ts

@@ -5,8 +5,10 @@ import type { Message } from "@poncho-ai/sdk";
 import {
   compactMessages,
   findSafeSplitPoint,
+  findSafeSplitPointByTurns,
   resolveCompactionConfig,
 } from "../src/compaction.js";
+import { deriveTaskOutcome, stripOutcomeVerdict } from "../src/orchestrator/orchestrator.js";
 
 // ── Fake model ──────────────────────────────────────────────────────────
 // A MockLanguageModelV3 whose doGenerate returns a fixed text and records the
@@ -254,9 +256,9 @@ describe("compactMessages", () => {
     expect(sentPrompt).toContain("MERGE AND UPDATE");
   });
 
-  it("still truncates non-prior-summary long messages to 1200 chars", async () => {
+  it("still truncates non-prior-summary long messages to the per-message cap", async () => {
     const { model, prompts } = fakeModel("S");
-    const longUser = "X".repeat(3000);
+    const longUser = "X".repeat(6000); // > SUMMARIZATION_MESSAGE_TRUNCATION_CHARS (4000)
     const messages: Message[] = [
       userMsg(longUser),
       assistantText("a0"),
@@ -272,3 +274,123 @@ describe("compactMessages", () => {
     expect(sentPrompt).not.toContain("MERGE AND UPDATE");
   });
 });
+
+describe("findSafeSplitPointByTurns", () => {
+  const turns = (n: number, assistantText = "a"): Message[] => {
+    const msgs: Message[] = [];
+    for (let i = 0; i < n; i++) {
+      msgs.push(userMsg(`u${i}`));
+      msgs.push({ role: "assistant", content: `${assistantText}${i}` });
+    }
+    return msgs;
+  };
+
+  it("preserves the last N whole turns verbatim", () => {
+    const messages = turns(6); // userIdx = [0,2,4,6,8,10]
+    // keepRecentTurns=4, generous token budget → split before the 4th-from-last
+    // user message (index 4), preserving turns u2..u5.
+    const idx = findSafeSplitPointByTurns(messages, 4, 6, 1_000_000);
+    expect(idx).toBe(4);
+    const preserved = messages.slice(idx);
+    const userCount = preserved.filter((m) => m.role === "user").length;
+    expect(userCount).toBe(4);
+  });
+
+  it("reduces N when N turns exceed the preserved-token budget", () => {
+    // Each assistant turn is large (~460 tokens); 4 turns preserved would blow a
+    // small budget, so it must fall back to fewer turns.
+    const big = "Z".repeat(1600);
+    const messages = turns(6, big); // userIdx=[0,2,4,6,8,10]
+    const idx = findSafeSplitPointByTurns(messages, 4, 6, 1200);
+    // n=4 (~1840 tok) and n=3 (~1380 tok) exceed 1200; n=2 (~920 tok) fits →
+    // split at userIdx[len-2] = index 8, preserving 2 turns.
+    expect(idx).toBe(8);
+    expect(messages.slice(idx).filter((m) => m.role === "user").length).toBe(2);
+  });
+
+  it("returns -1 for a single giant turn with no earlier user boundary", () => {
+    // One user message followed by many tool rounds — no safe boundary to
+    // compact against. (The message-based fallback also finds none.)
+    const messages: Message[] = [userMsg("do a big thing")];
+    for (let i = 0; i < 8; i++) {
+      messages.push(assistantToolCall(`step ${i}`, "run_code"));
+      messages.push(toolResult(`out ${i}`));
+    }
+    expect(findSafeSplitPointByTurns(messages, 4, 6, 1_000_000)).toBe(-1);
+  });
+});
+
+describe("deriveTaskOutcome / stripOutcomeVerdict", () => {
+  it("parses the self-declared verdict", () => {
+    expect(deriveTaskOutcome("did it [[OUTCOME: succeeded]] all good", false)).toBe("succeeded");
+    expect(deriveTaskOutcome("partial [[OUTCOME: partial]] some left", false)).toBe("partial");
+    expect(deriveTaskOutcome("couldn't [[OUTCOME: failed]] no tools", false)).toBe("failed");
+  });
+
+  it("defaults to unknown when no verdict is present (never assumes success)", () => {
+    expect(deriveTaskOutcome("I finished everything.", false)).toBe("unknown");
+  });
+
+  it("treats abnormal ends and empty output as failed", () => {
+    expect(deriveTaskOutcome("whatever", true)).toBe("failed");
+    expect(deriveTaskOutcome("   ", false)).toBe("failed");
+  });
+
+  it("strips the verdict marker from delivered text", () => {
+    expect(stripOutcomeVerdict("Here is the report.\n[[OUTCOME: failed]] missing API key")).toBe(
+      "Here is the report.",
+    );
+    expect(stripOutcomeVerdict("No verdict here")).toBe("No verdict here");
+  });
+});
+
+describe("compactMessages — failure fidelity", () => {
+  const config = resolveCompactionConfig({ keepRecentTurns: 1 });
+
+  it("renders a failed subagent as failed (never 'completed') and keeps its reason", async () => {
+    const { model } = fakeModel("SUMMARY");
+    const messages: Message[] = [
+      userMsg("please read my chats"),
+      assistantText("delegating to a subagent"),
+      userMsg(
+        '[Subagent Result] Subagent "read chats" (sub_fail) failed:\n\nI could not access the LinkedIn tools, so I read nothing.',
+        {
+          _subagentCallback: true,
+          subagentId: "sub_fail",
+          task: "read chats",
+          taskOutcome: "failed",
+        } as Message["metadata"],
+      ),
+      assistantText("continuing"),
+      userMsg("how did it go?"),
+      assistantText("let me check"),
+    ];
+    const res = await compactMessages(model, messages, config);
+    const content = res.messages[0]!.content as string;
+    expect(content).toContain("## Subagents");
+    expect(content).toContain("sub_fail");
+    // Rendered with the failed outcome, not "completed".
+    expect(content).toContain("— failed");
+    expect(content).not.toContain("(sub_fail) — completed");
+    // The failure reason survives verbatim.
+    expect(content).toContain("could not access the LinkedIn tools");
+  });
+
+  it("keeps failure-bearing messages when the input budget forces drops", async () => {
+    const { model, prompts } = fakeModel("S");
+    // Many bulky non-failure messages plus one early failure. The failure must
+    // survive into the summarizer input even if older bulk is dropped.
+    const messages: Message[] = [userMsg("start")];
+    messages.push(toolResult("ERROR: the deploy failed because the token expired"));
+    for (let i = 0; i < 400; i++) {
+      messages.push(assistantText("filler ".repeat(200) + i));
+      messages.push(userMsg(`ok ${i}`));
+    }
+    messages.push(userMsg("final question"));
+    messages.push(assistantText("final answer"));
+    await compactMessages(model, messages, config);
+    const sentPrompt = prompts.join("\n");
+    // The failure line is marked important and never dropped.
+    expect(sentPrompt).toContain("the deploy failed because the token expired");
+  });
+});