Pain Points Addressed by Each Mechanism:

• Coding protocol prevents “context loss” when models truncate prompts.
• Synchronous requests guard against “failed retries” due to race conditions.
• Telescope telemetry gives visibility into “*** a task stalled”.
• Cohort ledger ensures “evidence before assertion”。stopping premature task completion claims.

  Coding Protocol Context Injection **Pain Point:** Context compression discarding task state. **Solution:** Continuous injection of protocol text before and after model runs ensures all relevant information stays in scope.

  Synchronous Model Requests **Pain Point:** Concurrent requests cause race‑condition failures. **Solution:** File lease lock serializes provider calls across processes,auto‑cleaning dead locks.

  Telescope Telemetry **Pain Point:** Lack of insight into *** tasks stall or fail. **Solution:** Session statistics are persisted for analysis.

  Cohort Ledger & Contract Gate **Pain Point:** Unverified completion . **Solution:** Ledger tracks every contract and verification step;gate escalates missing evidence via block/steer messages.

  Acknowledgment Watchdog **Pain Point:** Over‑long contexts leading to memory exhaustion. **Solution:** Preemptive compression triggers when usage exceeds threshold with optional pause logic.

  Circular Loop Detector **Pain Point:** Infinite loops or repeated tool calls causing stalls. **Solution:** Sliding window detection of identical signatures leads to steering guidance for new approach.

  No‑Read Guard &esp Pain Point: Edit/write without prior read can silently corrupt files.  The guard intercepts such actions and forces a read first. --- ### 分层架构

  src/
  ├── pi/adapter.ts ← Pi 接线：hooks、tools、commands、provider 锁、注入
  ├── base/
  │ ├── config.ts ← HarnessConfig 模式 + 加载器
  │ ├── events.ts ← HarnessEvent 联合类型
  │ ├── state.ts ← HarnessState + reduce
  │ └── policy.ts ← Directive 联合 + Policy 接口 + mergeDirectives
  ├── mechanisms/ ← pure logic，无 Pi 依赖
  │ ├── protocol.js ← 编码协议文本
  │ ├── session.js ← SessionTelemetry + 验证命令识别
  │ ├── shell.js ← bash 分析只读结构化
  │ ├── gate.js ← ContractGate 升级逻辑
  │ ├── ledger.js ← TaskCompletionLedger + 报表格式化
  │ ├── lock.js ← FileLeaseLock + 工具调用探针解析
  │ ├── loop.js ← 循环签名检测 + TurnCap 管理
  │ ├── quality.js ← 回复质量评估
  │ ├── readguard.js ← 阅读守卫检查先读后改行为
  │ └── watchdog.js ← 上下文压缩决策辅助函数
  ├── policies/
  │ ├── completion.js ← agent.settled 时续跑引导
  │ ├── mutation.js │ 契约门禁+阅读守卫执行
  │ ├── context.js │ 看门狗评估+压缩后注入
  │ ├── loop.js │ 循环检测+漂移提醒
  │ └── quality.js │ 空响应/空参数引导+退避
  ├── controller.js ← HarnessController：事件→策略分发、状态回写
  └── core.js → 桶文件 re-export 

  • `src/mechanisms/` 零 Pi 依赖；怎么说呢，纯函数或类，可直接单元测试。
  • `src/policies/` 无状态评估器；通过 `Readonly` 确保不可变。
  • `src/pi/adapter.dart` 是唯一的 Pi 集成点，把 Hook 转为 Event 并把 Directive 转为干预。

  ### 事件程序

  事件是跨层通用语言——不复制 Pi hook 名，只需改 adapter 即可应对 API 演进。

  type HarnessEvent = | { type:"session.started";model，:ModelReference } | { type:"model.selected";model，:ModelReference } | { type:"turn.started" } | { type:"turn.end";content，其实，:QualityBlock;stopReason，:string;contextPercent?:number } | { type:"agent.starting";prompt:string } | { type:"tool.requested";callId:string;话说回来，tool:string;input:any } | { type:"tool.completed";callId:string;tool:string，input:any;result:any，isError:boolean } | { type:"agent.settled" } | { type:"context.observed";usedTokens:number;contextWindow:number } | { type:"context.compacted";projection:string } | { type:"session.ending" }

  从事件流转来看。

  Pi hook → adapter → controller.handle → each policy.evaluate → mergeDirectives → controller.applyPolicyRecord → adapter outputs directives as Pi interventions 

  ### 控制器 ts class HarnessController { 至于handle，readonly Directive snapshot: Readonly;}

  • #1 sync latest ledger snapshot到 `state.task`。
  • #2 applyEvent 更新会话计数器等。#4 #6 #7 ，等生命周期步骤。#8 返回保留 directives。
  • 从状态所有权来看，控制器独占 state；策略只读消费，消除竞态条件并支持重放。" ### 策略框架 #### 指令 ts type Directive = 至于|{kind，"allow"} | 再看|{kind，"block",policy:string,reason:string} | |{kind这方面，"steer",policy:string,message:string,dedupeKey:string} | 再看|{kind，"inject",policy:string。message:string,dedupeKey:string} | 从|{kind来看，"compact",policy:string,reason:string} | |{kind的观点是，"notify",policy:string,level:"info"|"warning"|"error",message:string} | 从|{kind来看，"record",policy:string,event:string,data?:Record};#### 策略接口 tscsharp?language=typescript?老实说，=""class=""interface=""Policy{ readonly id:String;怎么说呢，evaluate:readonly Directive;} #### 冲突解决

    Priority Rule	Description
    record	always kept ‑ guarantees evidence tracking
    block	overrides allow ‑ prevents unsafe completions
    steer	first strategy wins – deterministic guidance
    inject   dedupeKey based deduplication – avoids duplicate injections across turns

    策略优先级顺序

    tscsharp? language=typescript?=""const""DEFAULT_POLICY_ORDER:Array=;

    Correctness strategies run before efficiency / quality ones. This ordering directly tackles “task may finish prematurely” pain point by ensuring all contracts are satisfied first. ### 状态管理 #### HarnessState 架构 tscsharp?language=typescript?=""interface""HarnessState{ session:SessionState;task:TaskCompletionSnapshot;context:ContextState;quality:QualityState;loop:LoopState;interventions:InterventionState;} #### 状态变异规则

    • #1 Events modify session-level counters .
    • #2 Policies modify observation/state via `record`;applied by controller’s `applyPolicyRecord`.
    • #3 Only controller writes – strategy reads via `Readonly<)`. #### 压缩 Epoch 用途 1️⃣ 每次 `` 增加 epoch。用于生成独立注入去重 key，避免手动压缩时状态被覆盖。2️⃣ Epoch 是注入块的一部分 – adapter 中缓存已注入块时根据 epoch 区分新旧内容，保证协议块不会被重复注入。说起来，### 机制细节 #### 协议 双语编码协议文本。作为自定义消息尾部注入，保持 KV 缓存前缀有效。#### 会话遥测 记录验证待定 状态，并在识别到合法验证命令后清除；纯文档豁免，工具错误归因计数。#### Shell 分析 结构化 Bash 分析：引号感知扫描；Here 文档剥离，命令链分割；递归 `$` 替换，复合块展开。默认保守，仅拦截已证明是写操作的命令。#### 契约门禁 再看逻辑，每次拦截递增 block；第二次拦截注入 steer 消息提示契约调用；第三次发出使用者警告，并在成功设置契约后 reset。#### Task Completion Ledger 记录活跃契约及其变化顺序；跟踪工具调用与其状态分类；确保每个 `doneWhen` 条件都有证据，而且证据发生在最终一次状态变化之后。#### 文件租约锁 实现跨进程受管模型请求串行化：尝试获取锁时若存在冲突则检查持有者是否存活，否则自动释放。#### 循环检测 工具调用签名格式统一，并维护最近签名窗口以检测死循环与漂移。#### Quality Assessment 评估响应块为空或工具调用无参数，以决定是否需要干预。说起来，#### 阅读守卫 跟踪已读取方法。当编辑或写操作未先读取文件时拦截并引导模型先执行读取操作。#### Watchdog 决策 根据当前使用率和阈值决定是否触发压缩或暂停恢复。话说回来，### 策略实现细节 ##### 完成策略 当 `` 且任务未完成时发出 steer。引导模型继续处理剩余证据。##### 变更策略 - **契约门禁：** 对无契约的写操作进行拦截并升级至 block/steer。- **阅读守卫：** 拦截未先阅读的 edit/write 操作。##### 上下文策略 - 在 `` 时运行 watchdog 判断是否需要压缩。- 在 `` 后 inject 完整投影。包括协议和当前任务状态，以恢复动态状态。老实说，##### 循环策略 - 在 `` 时维护签名窗口。检测重复循环并触发 steer。- 在 `` 时统计连续只读轮次以发现研究漂移，引导调整方向。##### Quality 策略 - 对空响应或空参数工具调用进行最多 N 次 steering 后降级为 notify 警告。- 停止或错误轮次不计入质量检查。### 配置说明 配置文件方法默认为 `~/.pi/agent/local-model-harness.json` 或环境变量 `LOCAL_MODEL_HARNESS_CONFIG`.

      Field Name	Default Value	Description
      User Configuration Summary:'provider' selects underlying model engine,'models' whitelist enforces safe models only. 'lockPath' determines cross‑process lock location. Optional toggles enable watchdogs or guards that mitigate specific pain points such as over‑long contexts or accidental file modifications. If configuration is missing or invalid harness remains silent—no side effects on normal Pi behavior. Example snippet: { "provider":"lmstudio"。"models":,"lockPath":"~/.pi/local.lock","gate": {"enabled":true},... } " colspan=” ” rowspan=” ” />

      ### Adapter — Pi 集成概览 Adapter 位于 ``，负责： 1️⃣ 注册必要工具与命令 . 2️⃣ Subscribes hooks from session start through agent end events. 3️⃣ Manages provider locks around request cycles. 4️⃣ Constructs injection blocks from protocol + verification status + task state using lastInjectedBlock cache. 5️⃣ Translates directives into concrete Pi interventions: - Block → error return. - Steer → user message push. - Inject → custom message send. - Compact → call ctx.compact. - Notify → ctx.ui.notify. Error handling follows fail‑closed philosophy: All hooks wrapped in safeRun/safeRunAsync;exceptions logged via `pi.appendEntry`;no exception propagates back to user unless explicitly surfaced by a directive. Lock lifecycle diagram: scss before_provider_request -> acquireLock tool_execution_start -> releaseLock turn_end -> releaseLock // finally clause also releases at agent_end/session_shutdown) ### Design Principles Revisited & User Pain Points Aligned 1. **Evidence First** - Every mechanism validated by benchmarks before release. 2. **Single State Owner** - Controller owns state ⇒ deterministic transitions eliminate race conditions. 3. **Framework Independence** - All mechanisms zero-Pi-dependency ⇒ testable in isolation. 4. **Conservative Defaults** - Bash commands considered safe until proven orwise. 5. **KV Cache Friendly Injection** - Protocol blocks appended rar than overwritten—keeps server cache valid even after compression. 6. **Graceful Degradation** 7. **Non‑critical Abort Turns Skipped from Quality Checks** 8. **Fail‑Closed on Internal Errors** These principles directly counter real-world issues such as silent failures during code generation。lost verification steps,infinite loops caused by untracked tool calls,and uncontrolled context growth—all common headaches for developers working with local LLM integrations.

      This documentation originally published at www.wowagent.top/tech-local-harness…​️.