feat(harness): re-anchor discipline via context event on every LLM call

[pablontiv]

Re-land of #41 (approved, then closed; head branch deleted, so this is a fresh PR with the same commit). Rebased onto current main (1c218795). Opened as draft for now.

What changed vs the original #41: one conflict resolved by keeping both the #50 4R review-gate helpers and the new harness-reminder functions — they happened to land in the same region of extensions/gentle-ai.ts. The harness logic is byte-identical to the approved commit.

Stacked on #40 (re-land of the orchestrator-prompt-refresh PR); shows a cumulative diff until that one merges, then collapses to its single commit.

Part of #39. Stacked on #40 (review the last commit only).

Summary

• Registers Pi's context event and appends a compact harness reminder before every LLM call, including iterations after steer()/followUp() where before_agent_start does not fire.
• The reminder is a role: "custom" message (Pi converts it to a user message for the provider). Per-call ephemeral by design: the transform result is used for that single call and never persisted to session history.
• Strip-then-append strategy guarantees exactly one reminder per call, even if a previous reminder sits mid-array or another extension appended messages after it.

Changes

File	Change
extensions/gentle-ai.ts	buildContextReminder(), applyHarnessReminder(), pi.on("context") registration
tests/gentle-ai.test.ts	Immutability, dedupe (including reminder mid-array), ordering, and empty-array tests

Test plan

• pnpm test green at this commit on current main: 161 pass, 0 fail. Original count on the older base was 60.
• Live smoke on pi 0.78.0: in a real session the model confirms the reminder block is visible and quotes its first rule verbatim
• Event surface verified identical between pi-coding-agent 0.74.0 (lockfile dev dep) and 0.78.0

Notes

The reminder costs roughly 90 tokens per call. Its content lives in a single module const so it stays the only source of truth.

Summary by CodeRabbit

• New Features

  • Improved context handling by automatically injecting a single, up-to-date “gentle-harness-reminder” into each context message payload.
  • Enhanced orchestrator prompt loading with safer file reading and graceful handling when the prompt file is missing.

• Tests

  • Added unit tests covering prompt reloading behavior, missing-file behavior, and reminder injection rules (non-mutation, deduplication, and correct placement).

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a5e6ef17-49c2-4208-b634-080d6241dec7

📥 Commits

Reviewing files that changed from the base of the PR and between 20bedc2 and 6edc0e4.

📒 Files selected for processing (2)

• extensions/gentle-ai.ts
• tests/gentle-ai.test.ts

---

📝 Walkthrough

Walkthrough

Replaces the cached getOrchestratorPrompt with a per-call getOrchestratorPromptImpl(pathOverride?) that falls back to an empty string on file errors. Adds buildContextReminder() and applyHarnessReminder(messages) helpers that inject a single deduplicated harness reminder into every context event. All new helpers are covered by unit tests and exposed via __testing.

Changes

Harness Reminder Injection and Orchestrator Prompt Refactor

Layer / File(s)	Summary
Orchestrator prompt: per-call read with fallback extensions/gentle-ai.ts, tests/gentle-ai.test.ts	Replaces cached getOrchestratorPrompt with getOrchestratorPromptImpl(pathOverride?) that reads orchestrator.md fresh on each call and returns "" on missing/unreadable files. Tests verify re-read behavior and empty-string fallback.
buildContextReminder and applyHarnessReminder helpers extensions/gentle-ai.ts, tests/gentle-ai.test.ts	Adds the gentle-harness-reminder constant payload, buildContextReminder() factory, and applyHarnessReminder(messages) that strips prior reminder entries and appends a fresh one. Tests cover shape validation, non-mutation, deduplication, mid-array removal, empty input, and append-at-end behavior.
context event handler wiring extensions/gentle-ai.ts	Adds pi.on("context") handler that passes event.messages through applyHarnessReminder so every context event carries exactly one current harness reminder.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• feat(harness): strengthen harness persistence using Pi's context and compaction events #39: This PR implements per-call re-anchoring via the context event using buildContextReminder() and applyHarnessReminder() for deduplication, which directly addresses the proposal described in that issue.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 12.50% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 're-anchor discipline via context event on every LLM call' directly describes the main change: injecting a harness reminder message via the context event hook before each LLM call, which is the core feature in both the implementation and test changes.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@extensions/gentle-ai.ts`:
- Around line 1920-1928: The buildContextReminder function has a
self-referential return type annotation ReturnType<typeof buildContextReminder>
which creates a circular reference that TypeScript rejects. Remove the explicit
return type annotation completely from the function signature and allow
TypeScript to infer the return type directly from the object literal being
returned, which contains the role, customType, content, display, and timestamp
properties.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1da1d833-d75e-4b38-82ea-90502886f717

📥 Commits

Reviewing files that changed from the base of the PR and between 1dab94a and 20bedc2.

📒 Files selected for processing (2)

• extensions/gentle-ai.ts
• tests/gentle-ai.test.ts