@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/long-horizon/src/engine/runaway.ts

@@ -49,7 +49,10 @@ export const ANTI_POISONING_SUFFIX =
   "other persistent instruction files.";
 
 /** Tools whose repetition with varying args indicates polling, not work. */
-const POLLING_TOOLS = new Set(["bg_status", "bg_logs", "get_helper_result", "loop_status", "get_goal"]);
+const POLLING_TOOLS = new Set(["bg_status", "bg_logs", "read_subagent", "loop_status", "get_goal"]);
+
+/** Goal bookkeeping tools: always exempt from repetition reminders. */
+const EXEMPT_TOOLS = new Set(["get_goal", "update_goal"]);
 
 export interface RunawayStep {
   readonly tool: string;
@@ -64,15 +67,60 @@ export interface RunawayGuardDeps {
   remindAfter?: number;
 }
 
+/** Stable JSON: object keys sorted so equal args hash equal regardless of order. */
+export function stableStringify(value: unknown): string {
+  if (value === undefined) return "null";
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+      .join(",")}}`;
+  }
+  try {
+    return JSON.stringify(value) ?? "null";
+  } catch {
+    return String(value);
+  }
+}
+
 function fingerprint(value: unknown): string {
-  const json = (() => {
-    try {
-      return JSON.stringify(value ?? null);
-    } catch {
-      return String(value);
-    }
-  })();
-  return createHash("sha256").update(json).digest("hex").slice(0, 16);
+  return createHash("sha256").update(stableStringify(value)).digest("hex").slice(0, 16);
+}
+
+function commandOf(input: unknown): string {
+  if (typeof input === "string") return input;
+  if (typeof input !== "object" || input === null) return "";
+  const record = input as Record<string, unknown>;
+  for (const key of ["command", "cmd", "script"]) {
+    if (typeof record[key] === "string" && record[key].length > 0) return record[key] as string;
+  }
+  return "";
+}
+
+/** bash rg/grep that found nothing (exit 1) is expected work, not a loop. */
+export function isExpectedShellSearchNoMatch(input: unknown, isError: boolean, resultText: string): boolean {
+  if (!isError) return false;
+  const command = commandOf(input);
+  if (!/\b(?:rg|grep|findstr)\b/.test(command)) return false;
+  return /exit (?:code |status )?1\b|^no matches|^no match|^$/i.test(resultText.trim()) || resultText.trim() === "";
+}
+
+/** kanboard read subcommands via bash never count as repeated work. */
+function isKanboardRead(command: string): boolean {
+  return /(?:^|[\s/"'])unipi-kanboard(?:\.exe)?\s+(?:--\S+\s+)*(?:list|show|search|next|chain|attachments|status)\b/.test(command);
+}
+
+/** Steps that reflect legitimate state inspection, not loops. */
+export function isExemptStep(step: RunawayStep): boolean {
+  if (EXEMPT_TOOLS.has(step.tool)) return true;
+  if (step.tool === "bash" || step.tool === "powershell") {
+    const command = commandOf(step.input);
+    if (isKanboardRead(command)) return true;
+    if (isExpectedShellSearchNoMatch(step.input, step.isError, step.resultText)) return true;
+  }
+  return false;
 }
 
 /** Errors normalize to their family: first line, digits and paths removed. */
@@ -93,13 +141,22 @@ export interface RunawayObservation {
 
 /** Pure detector: returns the highest-priority qualifying signal, if any. */
 export function detectRunaway(
-  steps: readonly RunawayStep[],
+  allSteps: readonly RunawayStep[],
   remindAfter: number = DEFAULT_REMIND_AFTER,
 ): RunawayObservation | null {
+  // Exempt steps (goal bookkeeping, search no-matches, kanboard reads) never
+  // count toward any repeat.
+  const steps = allSteps.filter((step) => !isExemptStep(step));
   if (steps.length < remindAfter) return null;
 
+  // Action identity = tool + stable-sorted args: "identical arguments" must
+  // mean actually identical arguments.
   const actionKeys = steps.map((step) => `${step.tool}:${fingerprint(step.input)}`);
-  const resultKeys = steps.map((step) => fingerprint(step.resultText.slice(0, 400)));
+  // Result identity is bound to the action: identical output under different
+  // args is not a repeat (e.g. two different reads returning empty).
+  const resultKeys = steps.map(
+    (step) => `${step.tool}:${fingerprint(step.input)}:${fingerprint(step.resultText.slice(0, 400))}`,
+  );
   const errorKeys = steps.map((step) => (step.isError ? errorFamily(step.resultText) : null));
 
   const count = (keys: readonly string[]): { key: string; count: number } => {

package/packages/long-horizon/src/engine/verifier.ts

@@ -18,6 +18,7 @@
  */
 
 import { createHash } from "node:crypto";
+import { gatherEvidence } from "@pi-unipi/core";
 
 export const MAX_CHANGE_CHARS = 4_000;
 export const MAX_CHANGE_ITEMS = 100;
@@ -49,6 +50,8 @@ export interface VerifierDeps {
   readonly timeoutMs?: number;
   readonly setTimeout?: (fn: () => void, ms: number) => unknown;
   readonly clearTimeout?: (handle: unknown) => void;
+  /** Cross-module evidence (kanboard claims, …); defaults to core's registry. */
+  readonly gather?: typeof gatherEvidence;
 }
 
 const VERIFIER_SYSTEM = `You are the completion verifier for an autonomous coding agent. Given an OBJECTIVE and an EVIDENCE BRIEF, judge whether the objective is fully satisfied.
@@ -161,6 +164,22 @@ export async function verifyCompletion(
   brief: string,
   abortSignal?: AbortSignal,
 ): Promise<VerificationVerdict> {
+  // Cross-module evidence first: any blocking item forces not_met WITHOUT
+  // paying for an evaluator call (the evidence is already conclusive).
+  const gather = deps.gather ?? gatherEvidence;
+  const evidence = await gather();
+  if (evidence.blocking.length > 0) {
+    return {
+      verdict: "not_met",
+      reason: "board: open work remains",
+      missing: [...evidence.blocking],
+      evaluatorFailed: false,
+    };
+  }
+  if (evidence.notes.length > 0) {
+    brief = `${brief}\n--- MODULE EVIDENCE ---\n${evidence.notes.join("\n")}`;
+  }
+
   const prompt = buildVerificationPrompt(objective, brief);
   const timeoutMs = deps.timeoutMs ?? DEFAULT_VERIFIER_TIMEOUT_MS;
   const setT = deps.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));

package/packages/long-horizon/src/gate.ts

@@ -17,7 +17,7 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { emitEvent, UNIPI_EVENTS, setSharedLongHorizonMode } from "@pi-unipi/core";
+import { emitEvent, isChildProcess, UNIPI_EVENTS, setSharedLongHorizonMode } from "@pi-unipi/core";
 import { LH_MODES, MODE_REGISTRY, modeForOwnerKind, type LhMode } from "./modes.js";
 import type { OwnerCoordinator, OwnerState } from "./owner.js";
 import { resolveMode, type ResolutionSource } from "./judge/resolve.js";
@@ -30,6 +30,8 @@ export interface GateState {
   readonly mode: LhMode;
   readonly source: ResolutionSource;
   readonly confidence?: number;
+  /** Resolved from the sticky session mode (/unipi:regular, goal stop), not a one-shot. */
+  readonly sticky?: boolean;
 }
 
 export interface GateDeps {
@@ -48,12 +50,9 @@ export interface GateDeps {
 }
 
 /** Delegation tools governed by the exposure matrix (design §8). */
-export const DELEGATION_TOOLS: readonly string[] = [
-  "spawn_helper",
-  "get_helper_result",
-  "bg_delegate",
-  "bg_result",
-];
+// Devin-model subagents are first-class: run_subagent is available in every
+// mode. The delegation matrix mechanism is kept for future mode tools.
+export const DELEGATION_TOOLS: readonly string[] = [];
 
 /** Every mode-control tool name across modes (todowrite rides all four). */
 export const ALL_MODE_TOOLS: readonly string[] = [
@@ -122,7 +121,7 @@ export function renderModeFragment(state: GateState, owner?: OwnerState, parked?
       `Available long-horizon tools: ${definition.controlTools.join(", ")}.` +
         (definition.delegation === "full"
           ? " Delegation tools are available for parallel work."
-          : " Delegation tools are hidden; finish here or ask the user to switch modes."),
+          : ""),
     );
   }
   const status = ownerPresenceLine(owner, parked);
@@ -137,6 +136,8 @@ export function renderModeFragment(state: GateState, owner?: OwnerState, parked?
 export class Gate {
   private turn: GateState | null = null;
   private pendingExplicit: LhMode | null = null;
+  /** Sticky per-session mode (/unipi:regular): judge/default skip until an explicit command clears it. */
+  private sessionOverride: LhMode | null = null;
   /** Mode of the last badge shown, so only mode TRANSITIONS reprint. */
   private lastBadge: LhMode | null = null;
   private readonly deps: GateDeps;
@@ -145,9 +146,17 @@ export class Gate {
     this.deps = deps;
   }
 
-  /** Commands call this before sendUserMessage to force next-turn mode. */
+  /** Commands call this before sendUserMessage to force next-turn mode (one-shot;
+   *  an explicit command also escapes a sticky session mode). */
   setExplicit(mode: LhMode): void {
     this.pendingExplicit = mode;
+    this.sessionOverride = null;
+  }
+
+  /** Pin the session to a mode (/unipi:regular, goal stop): every later turn resolves to it. */
+  setSessionMode(mode: LhMode): void {
+    this.sessionOverride = mode;
+    this.pendingExplicit = null;
   }
 
   current(): GateState | null {
@@ -155,10 +164,17 @@ export class Gate {
   }
 
   async resolveForTurn(prompt: string): Promise<GateState> {
+    // Children are the hands, the lead is the voice: no LH modes, no judge,
+    // no owners in fusion/subagent children (escape hatch: UNIPI_LH_ALLOW_CHILD).
+    if (isChildProcess() && process.env.UNIPI_LH_ALLOW_CHILD !== "1") {
+      this.pendingExplicit = null;
+      this.turn = { mode: "none", source: "child" };
+      return this.turn;
+    }
     const settings = this.deps.loadSettings?.() ?? loadSettings();
     // Explicit switch away from an active owner suspends it first (max-1
     // park slot; a held slot refuses the override and the owner keeps mode).
-    let explicit = this.pendingExplicit;
+    let explicit = this.sessionOverride ?? this.pendingExplicit;
     if (explicit) {
       const active = this.deps.owner.getActive();
       if (active && modeForOwnerKind(active.kind) !== explicit) {
@@ -184,6 +200,7 @@ export class Gate {
       mode: resolution.mode,
       source: resolution.source,
       ...(resolution.confidence !== undefined ? { confidence: resolution.confidence } : {}),
+      ...(this.sessionOverride !== null && explicit === this.sessionOverride ? { sticky: true } : {}),
     };
     return this.turn;
   }
@@ -212,7 +229,7 @@ export class Gate {
       //   - mode changed from last     → worth showing
       //   - same mode as last shown    → silent (footer already reflects it)
       const showBadge =
-        state.source === "explicit" || this.lastBadge !== state.mode;
+        (state.source === "explicit" && !state.sticky) || this.lastBadge !== state.mode;
       this.lastBadge = state.mode;
       if (showBadge) {
         try {
@@ -230,7 +247,15 @@ export class Gate {
         this.deps.owner.getActive(),
         this.deps.owner.getParked(),
       );
-      return { systemPrompt: `${event.systemPrompt}\n\n${fragment}` };
+      // A named section, not a systemPrompt replacement: a forced prompt is
+      // opaque to pi (forceSystemPrompt) and would drop sections other modules
+      // added — e.g. fusion's lead policy. renderModeFragment already emits
+      // the <long-horizon> wrapper; strip it, pi re-wraps the section.
+      const inner = fragment
+        .replace(/^<long-horizon[^>]*>\n?/, "")
+        .replace(/\n?<\/long-horizon>(\n|$)/, "$1");
+      event.systemPromptOptions.sections["long-horizon"] = inner;
+      return undefined;
     });
 
     pi.on("before_provider_request", (event) => {

package/packages/long-horizon/src/judge/resolve.ts

@@ -26,6 +26,7 @@ export type ResolutionSource =
   | "owner"
   | "judge"
   | "judge_abstained_low_confidence"
+  | "child"
   | "default";
 
 export interface Resolution {

package/packages/long-horizon/src/owner.ts

@@ -12,9 +12,13 @@
  */
 
 import { randomUUID } from "node:crypto";
-import { ensureDir, tryRead, writeJson } from "@pi-unipi/core";
+import { ensureDir, isChildProcess, markSharedOwnerStopped, setSharedOwner, tryRead, writeJson } from "@pi-unipi/core";
 import type { OwnerKind } from "./modes.js";
 
+/** Surfaced by create_goal / ralph / swarm / graph tools inside children. */
+export const CHILD_OWNER_REFUSAL =
+  "Long-horizon owners are not available inside a child agent — do the work and report back to the lead.";
+
 export type OwnerStatus = "active" | "parked";
 
 export interface OwnerLease {
@@ -109,9 +113,13 @@ export class OwnerCoordinator {
 
   /**
    * Create and activate a new owner. Refuses while another owner is active —
-   * callers surface "finish or suspend the current owner first".
+   * callers surface "finish or suspend the current owner first". In child
+   * processes owning is refused outright (throw — tool failures must throw).
    */
   activate(kind: OwnerKind, label: string): OwnerState | undefined {
+    if (isChildProcess() && process.env.UNIPI_LH_ALLOW_CHILD !== "1") {
+      throw new Error(CHILD_OWNER_REFUSAL);
+    }
     if (this.active) return undefined;
     const ownerId = randomUUID();
     const now = new Date(this.deps.now?.() ?? Date.now()).toISOString();
@@ -216,15 +224,32 @@ export class OwnerCoordinator {
     }
     const snapshot = this.snapshot();
     this.deps.onChange?.(snapshot, { type: "restored", snapshot });
+    this.publishStatus({ type: "restored", snapshot });
     return snapshot;
   }
 
   private commit(event: OwnerEvent): OwnerState | undefined {
     this.persist();
+    this.publishStatus(event);
     this.deps.onChange?.(this.snapshot(), event);
     return "owner" in event ? event.owner : undefined;
   }
 
+  /** Publish the transition to the shared holder kanboard's monitor reads. */
+  private publishStatus(event: OwnerEvent): void {
+    try {
+      if (event.type === "finished") markSharedOwnerStopped(stopKindOf(event.reason));
+      // Parked (paused) goals go through suspend, not finish — kanboard must
+      // see them as a stop of kind "paused" this run, same as finish would.
+      if (event.type === "suspended") markSharedOwnerStopped("paused");
+      if (this.active) setSharedOwner({ kind: this.active.kind, status: "active" });
+      else if (this.parked) setSharedOwner({ kind: this.parked.kind, status: "parked" });
+      else setSharedOwner(undefined);
+    } catch {
+      // Status publishing must never roll back a committed transition.
+    }
+  }
+
   private commitActive(patch: Partial<OwnerState>): OwnerState {
     if (!this.active) throw new Error("commitActive without an active owner");
     const next = this.withOwner(this.active, patch);
@@ -253,3 +278,11 @@ function renewLease(owner: OwnerState): OwnerLease {
     generation: owner.lease.generation + 1,
   });
 }
+
+/** Map a terminal reason to the coarse stop kind kanboard's monitor needs. */
+export function stopKindOf(reason: string): "complete" | "paused" | "budget" | "other" {
+  if (reason === "complete" || reason.startsWith("complete(")) return "complete";
+  if (reason === "paused" || reason.startsWith("paused(")) return "paused";
+  if (reason.includes("budget")) return "budget";
+  return "other";
+}

package/packages/long-horizon/src/progress.ts

@@ -0,0 +1,87 @@
+/**
+ * User-only progress bars for long-horizon owners.
+ *
+ *   ↻ Ralph · docs-cleanup  ████████▒▒░░░░░░░░░░  4/10 items  iteration 3/20
+ *   ◎ Goal                  ███████████▒▒░░░░░░░  ~55%  turn 4/30
+ *     Parser and CLI flags done; tests for the error paths are left.
+ *
+ * Ralph counts its checklist. A goal has no countable progress, so a one-off
+ * side call (never in the session context) estimates % done + a summary.
+ */
+
+import type { ProgressData } from "@pi-unipi/core";
+import type { GoalState } from "./engine/goal-state.js";
+import type { RalphLoop } from "./engine/ralph.js";
+
+export function ralphProgressData(ralph: Pick<RalphLoop, "get" | "progressSummary">): ProgressData | undefined {
+  const st = ralph.get();
+  if (!st) return undefined;
+  const p = ralph.progressSummary();
+  const live = st.status === "active";
+  const active = live ? Math.min(st.itemsPerIteration, Math.max(0, p.total - p.checked)) : 0;
+  return {
+    icon: "↻",
+    label: `Ralph · ${st.name}`,
+    done: p.checked,
+    active,
+    total: p.total,
+    unit: "items",
+    detail: `iteration ${String(st.iteration)}/${String(st.maxIterations)}${live ? "" : ` · ${st.status}`}`,
+    summary: live && p.next.length > 0 ? `next: ${p.next.slice(0, 3).join(" · ")}` : undefined,
+  };
+}
+
+export interface GoalEvidence {
+  commands: readonly string[];
+  changedFiles: readonly string[];
+  recentTail: ReadonlyArray<{ role: string; text: string }>;
+}
+
+export function goalEstimatePrompt(goal: Pick<GoalState, "objective" | "turn" | "maxTurns">, evidence: GoalEvidence | undefined, previous: number | undefined): string {
+  const lines = [
+    "Estimate progress on a goal for a progress bar shown to the user. Be honest and conservative: 100 only when the objective is fully met.",
+    "",
+    `Objective: ${goal.objective}`,
+    `Turn ${String(goal.turn)} of at most ${String(goal.maxTurns)}.`,
+  ];
+  if (previous !== undefined) lines.push(`Previous estimate: ${String(previous)}%.`);
+  if (evidence) {
+    if (evidence.changedFiles.length) lines.push(`Files touched recently: ${[...new Set(evidence.changedFiles)].slice(-12).join(", ")}`);
+    if (evidence.commands.length) lines.push(`Commands run recently: ${evidence.commands.slice(-8).join(" | ")}`);
+    if (evidence.recentTail.length) {
+      lines.push("", "Latest messages:");
+      for (const m of evidence.recentTail.slice(-4)) lines.push(`[${m.role}] ${m.text.slice(0, 600)}`);
+    }
+  }
+  lines.push("", 'Reply with JSON only: {"percent": <integer 0-100>, "summary": "<one or two short sentences: what is done, what is left>"}');
+  return lines.join("\n");
+}
+
+/** Pull `{percent, summary}` out of a model reply (tolerates fences and prose). */
+export function parseEstimate(text: string): { percent: number; summary: string } | undefined {
+  const match = text.match(/\{[\s\S]*\}/u);
+  if (!match) return undefined;
+  try {
+    const raw = JSON.parse(match[0]) as { percent?: unknown; summary?: unknown };
+    const n = typeof raw.percent === "number" ? raw.percent : Number(raw.percent);
+    if (!Number.isFinite(n)) return undefined;
+    return { percent: Math.max(0, Math.min(100, Math.round(n))), summary: typeof raw.summary === "string" ? raw.summary.trim() : "" };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Shade = the slice in progress; a live goal always shows one. */
+export function goalProgressData(goal: Pick<GoalState, "turn" | "maxTurns" | "status">, percent: number, summary: string): ProgressData {
+  const live = goal.status === "active" || goal.status === "waiting";
+  return {
+    icon: "◎",
+    label: "Goal",
+    done: goal.status === "complete" ? 100 : percent,
+    active: live ? Math.max(1, Math.min(10, 100 - percent)) : 0,
+    total: 100,
+    estimated: goal.status !== "complete",
+    detail: `turn ${String(goal.turn)}/${String(goal.maxTurns)}${live ? "" : ` · ${goal.status}`}`,
+    summary: summary || undefined,
+  };
+}

package/packages/long-horizon/src/prompts/goal.ts

@@ -96,7 +96,7 @@ export function renderContinuationHint(goal: GoalState, verifierReason?: string)
     goal.noProgressStreak > 0 ? `, ${goal.noProgressStreak}/${goal.stallCap} no-progress` : "";
   const budget =
     goal.tokenBudget !== null && !goal.tokensBaselinePending
-      ? `, ${Math.max(0, goal.tokensNow - goal.tokensAtStart)}/${goal.tokenBudget} tok`
+      ? `, ${Math.max(0, goal.tokensNow - goal.tokensAtStart)}/${goal.tokenBudget} tok${goal.tokensEstimated ? " (est.)" : ""}`
       : "";
   return (
     `${CONTINUATION_HINT}` +