Pi Posthorse boundary

Type: agentic-system-analyses/types/agentic-system-boundary.md

Boundary and evidence

This run analyses Posthorse as a complete Pi extension, not as an enclosing agent runtime. Its intended use is to continue long model-driven tasks across fresh context windows while keeping notes and earlier conversation recoverable. It qualifies as an agentic mechanism because its shipped entry point installs model-callable tools, request guidance and turn/compaction hooks into Pi's model execution loop (SRC-1, package.json, index.ts, src/rollover.ts, src/context-tools.ts). The target class is extension or tool mechanism; the boundary kind is whole-system, relative to this extension, not the external host.

The package declares the loading path directly (SRC-1, package.json):

"pi": { "extensions": [ "./index.ts" ], --- package.json

That entry point exports createPosthorse(getPolicy) and a default extension factory. It registers rollover policy, notes, history and renderers together. The boundary includes this factory and its same-repository consumers; it is not restricted to the exported library API (SRC-1, index.ts, test/official.test.mjs, test/native.test.mjs, test/harness.ts). The implementation declares the responsibility split (SRC-1, index.ts):

• Pi owns persisted retain-none context boundaries. Posthorse owns reminder and
• rollover policy, bounded recovery, durable notes, and history retrieval. --- index.ts

Included functional loop

• Produce and maintain retained state: the notes tool creates, replaces and appends text files; storage helpers choose shared Git-worktree or agent-package locations and migrate notes out of agent-installed checkouts. Request guidance tells the model how to keep current-state notes, including edits through other available tools. Those external editors are not implemented by Posthorse (SRC-1, src/notes.ts, src/files.ts, src/budget.ts).
• Admit a fresh window: new_context checks handoff capacity and records its successful callback ID. Turn-end handling checks foreground results, abort conditions and current handoff capacity before drafting a retain-none compaction. Automatic compaction hooks construct recovery text from branch entries and projected content; a narrower turn-end threshold fallback handles eligible fresh-window spans. Manual compaction remains host-owned (SRC-1, src/context-tools.ts, src/rollover.ts, src/recovery.ts, src/recovery-results.ts).
• Reload and consume: notes reads/searches return stored text; history searches/read pages consume the current branch or project-scoped session files, including nested subagent journals. History normalization and recovery processing account for context edits and legacy window data. Notes/history share page reservations. Request-local guidance tells the continuing model to restore state and verify it before further work (SRC-1, src/history.ts, src/history-search.ts, src/session-files.ts, src/history-entries.ts, src/history-pages.ts, src/paging.ts, src/budget.ts).
• Evaluate the loop: shipped SDK test drivers load the factory or file extension, create sessions with a faux provider, and exercise retention, rollover, retrieval and reopening. These are included source consumers, not excluded enclosing applications. Their source establishes intended assertions, not observed passing runs (SRC-1, test/official.test.mjs, test/native.test.mjs, test/host.test.mjs, test/pi-loader.ts).

The request guidance explicitly connects retention to later consumption (SRC-1, src/budget.ts):

After a rollover, earlier conversation stays in history. Restore notes and todos, then verify live state before stateful or external work; automatic handoffs record inputs, not progress. Keep one concise current-state note per task. Preserve decisions and safety constraints; link fuller evidence and history instead of copying them. Edit changed sections rather than resending unchanged content. --- src/budget.ts

A same-repository test driver includes reopening the persisted journal (SRC-1, test/official.test.mjs):

const reopened = SessionManager.open(h.sessionManager.getSessionFile()); assert.deepEqual( reopened.buildSessionContext().messages, JSON.parse(JSON.stringify(h.sessionManager.buildSessionContext().messages)), ); --- test/official.test.mjs:269-273

Repository coverage

The tracked tree and shipped imports were inspected before selecting whole-system scope. All production TypeScript files were read. Test inspection covered driver setup, the explicit-reset/notes/history/resume scenario, and a bounded inventory of test declarations; it was not a full assertion audit. The following table accounts for every top-level tracked file or directory. “Excluded” means deliberately outside functional analysis, not inaccessible. Unread support-file contents are distinguished from evidence gaps.

External responsibilities and evidence limits

Pi's SDK, session manager, model/provider execution, compaction preparation and persistence, scheduling, built-in editors and physical request sizing are external dependencies, not Posthorse responsibilities. TUI components and TypeBox schemas are imported dependencies; Node/filesystem/Git metadata and optional local ripgrep support storage and archive retrieval. No external dependency implementation is frozen in this run. This prevents independent certification of host persistence, provider-boundary safety, host-version compatibility, external editor behavior or third-party component correctness (SRC-1, package.json, index.ts, src/rollover.ts, src/files.ts, src/session-files.ts, docs/reference.md). Background work outside the foreground tool batch and application-specific task execution are excluded; the boundary cannot establish their synchronization or task correctness (SRC-1, src/context-tools.ts, docs/reference.md).

The immutable evidence is repository commit 307ef6bf05bc8bd8d718725761ffdf2f2ef72539, with applicability cutoff 2026-10-14. The supplied checkout's HEAD matched this commit and its tracked diff was clean. The overall tier is code-grounded. Source-native documentation supplies intent and attributed reports, not independent verification. No target code, tests or examples were executed; no provider calls, production session traces, qualification artifacts or controlled experiment were supplied. Those missing evidence layers prevent measured effectiveness, runtime success, production cost and causal-improvement conclusions. Available but unread files above are not access gaps.

Source register