fix(automation): region-aware run-history compaction keeps loop containers + early failures (#3234)

[os-zhuang]

Summary

Follow-up to #1505 (region step logs). AutomationEngine.compactStepsForHistory() bounded a terminal run's persisted step log to the last MAX_PERSISTED_HISTORY_STEPS entries with a plain tail-slice. With the ADR-0031 structured-region step logs, a single loop can now emit iterations × body-steps entries, so the tail-slice:

• dropped the loop/parallel/try_catch container step (it precedes all its body steps), leaving getRun/listRuns — served from durable history after a restart or ring-buffer eviction — with body steps the Runs surface (objectui FlowRunsPanel) could no longer nest; and
• silently hid an early failure (e.g. iteration 2 of 500), the single most useful thing about a failed run.

The fix

New exported, region-aware compactStepLogForHistory (the private method delegates to it). Under budget the log is kept whole (stacks stripped) — unchanged. Over budget it selects a bounded, order-preserving subset that keeps the run's structural backbone:

1. every top-level step (parentNodeId === undefined) — start/end, main-graph nodes, and the region container steps (bounded by the flow's static node count, not by loop iterations);
2. every failure, wherever it occurred, each pulled in with its ancestor container chain for context;
3. the most recent body steps (what the run was doing when it ended), each also with its ancestor chain.

Every retained body step therefore keeps its enclosing container(s) — so the compacted log never contains an orphan and the observability surface's per-iteration / per-region nesting still reconstructs — and the result is hard-capped at max, so steps_json stays bounded (#2585). Parent lookup is O(n) via a running last-seen-index map (the same "nearest preceding container instance" that FlowRunsPanel.buildStepTree nests under).

Verification

• run-history.test.ts — 14/14 pass (7 new: cap, container/backbone retention, recent-iteration tail, early-failure retention, order preservation, nested-container no-orphan).
• Full @objectstack/service-automation suite — 326/326 pass (no regression).
• tsup build incl. DTS typecheck — pass. ESLint — clean.
• Changeset: @objectstack/service-automation minor.

Closes #3234.

🤖 Generated with Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Canceled		Jul 18, 2026 5:15pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): packages/services.

6 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/automation/webhooks.mdx (via packages/services)
• content/docs/kernel/runtime-services/audit-service.mdx (via packages/services)
• content/docs/kernel/runtime-services/index.mdx (via packages/services)
• content/docs/kernel/runtime-services/settings-service.mdx (via packages/services)
• content/docs/plugins/packages.mdx (via packages/services)
• content/docs/protocol/kernel/i18n-standard.mdx (via packages/services)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.