killeros 2.0.21 → 2.1.22

package/killeros/commands.ts

@@ -70,7 +70,7 @@ const BUILTIN_COMMANDS: ReadonlyArray<{ name: string; description: string }> = [
 ];
 
 const COMMAND_SYNTAX_HINTS: Readonly<Record<string, string>> = {
-  goal: "/goal [objective|clear|edit|pause|resume]",
+  goal: "/goal [objective|start|check|checks|limit|history|clear|edit|pause|resume]",
   handoff: "/handoff [next-session focus]",
   variants: "/variants [level]",
   model: "/model [provider/model]",

package/killeros/footer.ts

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import { watch } from "node:fs";
 import { type ExtensionAPI, type ExtensionContext, type Theme, type ThemeColor } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth, type TUI } from "@earendil-works/pi-tui";
 import { isCodexFastEnabled, subscribeCodexFast } from "./codex-fast-state.ts";
@@ -9,18 +10,45 @@ import { safeTerminalText } from "./safe-terminal-text.ts";
 import { LEVEL_COLORS, type ThinkingLevel } from "./variants.ts";
 
 const GIT_STATUS_REFRESH_INTERVAL_MS = 30_000;
+const GIT_STATUS_TIMEOUT_MS = 5_000;
+const GIT_STATUS_WATCH_DEBOUNCE_MS = 250;
+const GIT_STATUS_WATCH_INTERVAL_MS = 5_000;
 const CODEX_PROVIDER = "openai-codex";
 const colorDirectory = (text: string): string => `\x1B[38;2;240;248;154m${text}\x1B[39m`;
 
-function resolveUncommittedFileCount(cwd: string): Promise<number | undefined> {
+export interface GitFileChanges {
+  modified: number;
+  added: number;
+  deleted: number;
+}
+
+type GitStatusExecutor = (
+  file: string,
+  args: string[],
+  options: {
+    encoding: "utf8";
+    env: NodeJS.ProcessEnv;
+    maxBuffer: number;
+    timeout: number;
+    windowsHide: true;
+  },
+  callback: (error: Error | null, stdout: string) => void,
+) => unknown;
+
+/** Resolves changed-file counts with a bounded asynchronous Git status process. */
+export function resolveGitFileChanges(
+  cwd: string,
+  execute: GitStatusExecutor = execFile,
+): Promise<GitFileChanges | undefined> {
   return new Promise((resolve) => {
-    execFile(
+    execute(
       "git",
       ["-C", cwd, "status", "--porcelain=v1", "-z", "--untracked-files=all"],
       {
         encoding: "utf8",
+        env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
         maxBuffer: 4 * 1024 * 1024,
-        timeout: 1_000,
+        timeout: GIT_STATUS_TIMEOUT_MS,
         windowsHide: true,
       },
       (error, stdout) => {
@@ -29,25 +57,32 @@ function resolveUncommittedFileCount(cwd: string): Promise<number | undefined> {
           return;
         }
 
+        const changes: GitFileChanges = { modified: 0, added: 0, deleted: 0 };
         const entries = stdout.split("\0");
-        let count = 0;
         for (let index = 0; index < entries.length; index += 1) {
           const entry = entries[index];
           if (!entry) continue;
-          count += 1;
-          if (entry[0] === "R" || entry[0] === "C" || entry[1] === "R" || entry[1] === "C") index += 1;
+          const status = entry.slice(0, 2);
+          if (status.includes("D")) changes.deleted += 1;
+          else if (status === "??" || status.includes("A")) changes.added += 1;
+          else changes.modified += 1;
+          if (status.includes("R") || status.includes("C")) index += 1;
         }
-        resolve(count);
+        resolve(changes);
       },
     );
   });
 }
 
-/** Coalesces Git status requests to one active scan and one queued follow-up. */
-export function createGitStatusRefresh(
+async function resolveUncommittedFileCount(cwd: string): Promise<number | undefined> {
+  const changes = await resolveGitFileChanges(cwd);
+  return changes && changes.modified + changes.added + changes.deleted;
+}
+
+function createGitRefresh<T>(
   cwd: string,
-  onCount: (count: number | undefined) => void,
-  resolveCount: (cwd: string) => Promise<number | undefined> = resolveUncommittedFileCount,
+  onResult: (result: T | undefined) => void,
+  resolveResult: (cwd: string) => Promise<T | undefined>,
 ): { request: () => void; dispose: () => void } {
   let disposed = false;
   let pending = false;
@@ -59,9 +94,16 @@ export function createGitStatusRefresh(
       return;
     }
     pending = true;
-    void resolveCount(cwd).then((count) => {
-      if (!disposed) onCount(count);
-    }).finally(() => {
+    let result: Promise<T | undefined>;
+    try {
+      result = resolveResult(cwd);
+    } catch {
+      result = Promise.resolve(undefined);
+    }
+    void result.then(
+      (value) => { if (!disposed) onResult(value); },
+      () => { if (!disposed) onResult(undefined); },
+    ).finally(() => {
       pending = false;
       if (!disposed && queued) {
         queued = false;
@@ -78,7 +120,29 @@ export function createGitStatusRefresh(
   };
 }
 
+/** Coalesces Git status requests to one active scan and one queued follow-up. */
+export function createGitStatusRefresh(
+  cwd: string,
+  onCount: (count: number | undefined) => void,
+  resolveCount: (cwd: string) => Promise<number | undefined> = resolveUncommittedFileCount,
+): { request: () => void; dispose: () => void } {
+  return createGitRefresh(cwd, onCount, resolveCount);
+}
+
+/** Coalesces file-change scans and emits only successful results. */
+export function createGitFileChangesRefresh(
+  cwd: string,
+  onChanges: (changes: GitFileChanges) => void,
+  resolveChanges: (cwd: string) => Promise<GitFileChanges | undefined> = resolveGitFileChanges,
+): { request: () => void; dispose: () => void } {
+  return createGitRefresh(cwd, (changes) => {
+    if (changes !== undefined) onChanges(changes);
+  }, resolveChanges);
+}
+
 type ScheduleFallback = (refresh: () => void, intervalMs: number) => () => void;
+type WatchDirectory = (cwd: string, onChange: () => void, onError: () => void) => () => void;
+type ScheduleDelay = (refresh: () => void, delayMs: number) => () => void;
 
 const scheduleFallback: ScheduleFallback = (refresh, intervalMs) => {
   const timer = setInterval(refresh, intervalMs);
@@ -86,6 +150,18 @@ const scheduleFallback: ScheduleFallback = (refresh, intervalMs) => {
   return () => clearInterval(timer);
 };
 
+const watchDirectory: WatchDirectory = (cwd, onChange, onError) => {
+  const watcher = watch(cwd, { recursive: true }, onChange);
+  watcher.on("error", onError);
+  return () => watcher.close();
+};
+
+const scheduleDelay: ScheduleDelay = (refresh, delayMs) => {
+  const timer = setTimeout(refresh, delayMs);
+  timer.unref?.();
+  return () => clearTimeout(timer);
+};
+
 /** Schedules the fallback Git scan independently from footer rendering. */
 export function scheduleGitStatusFallback(
   refresh: () => void,
@@ -94,6 +170,55 @@ export function scheduleGitStatusFallback(
   return schedule(refresh, GIT_STATUS_REFRESH_INTERVAL_MS);
 }
 
+/** Throttles filesystem changes and falls back silently when watching is unavailable. */
+export function scheduleGitStatusWatch(
+  cwd: string,
+  refresh: () => void,
+  startWatching: WatchDirectory = watchDirectory,
+  schedule: ScheduleDelay = scheduleDelay,
+): () => void {
+  let disposed = false;
+  let coolingDown = false;
+  let queued = false;
+  let stopTimer: (() => void) | undefined;
+  let stopWatching: (() => void) | undefined;
+  const stop = (): void => {
+    if (disposed) return;
+    disposed = true;
+    stopTimer?.();
+    stopTimer = undefined;
+    stopWatching?.();
+    stopWatching = undefined;
+  };
+  const changed = (): void => {
+    if (disposed) return;
+    if (stopTimer) {
+      if (coolingDown) queued = true;
+      return;
+    }
+    stopTimer = schedule(() => {
+      stopTimer = undefined;
+      if (disposed) return;
+      refresh();
+      coolingDown = true;
+      stopTimer = schedule(() => {
+        stopTimer = undefined;
+        coolingDown = false;
+        if (queued) {
+          queued = false;
+          changed();
+        }
+      }, GIT_STATUS_WATCH_INTERVAL_MS);
+    }, GIT_STATUS_WATCH_DEBOUNCE_MS);
+  };
+  try {
+    stopWatching = startWatching(cwd, changed, stop);
+  } catch {
+    disposed = true;
+  }
+  return stop;
+}
+
 export function formatCost(usd: number): string {
   if (!Number.isFinite(usd)) return "$—";
   return `$${usd.toFixed(2)}`;
@@ -229,13 +354,20 @@ function renderFooter(rows: string[], width: number, theme: Theme): string[] {
 function formatGoalFooter(state: GoalState | undefined, theme: Theme): string {
   if (!state) return "";
   if (state.status === "active") {
-    return theme.fg("warning", `/goal is active (${formatTime(goalElapsedMilliseconds(state, Date.now()))})`);
+    const turns = state.maxTurns === undefined ? "" : ` ${state.turns}/${state.maxTurns}`;
+    return theme.fg("warning", `/goal is active${turns} (${formatTime(goalElapsedMilliseconds(state, Date.now()))})`);
   }
   if (state.status === "paused") return theme.fg("warning", "/goal is paused");
   if (state.status === "blocked") return theme.fg("error", "/goal is blocked");
   return "";
 }
 
+function formatGitFileChanges(changes: GitFileChanges, theme: Theme): string {
+  const total = changes.modified + changes.added + changes.deleted;
+  if (total === 0) return "";
+  return `${theme.fg("dim", `±${total} [`)}${theme.fg("warning", `~${changes.modified}`)} ${theme.fg("success", `+${changes.added}`)} ${theme.fg("error", `−${changes.deleted}`)}${theme.fg("dim", "]")}`;
+}
+
 export function registerFooter(pi: ExtensionAPI, goalRuntime: GoalRuntime): void {
   let currentModel: ExtensionContext["model"];
   let thinkingLevel: ThinkingLevel = "off";
@@ -243,7 +375,6 @@ export function registerFooter(pi: ExtensionAPI, goalRuntime: GoalRuntime): void
   let cachedSessionCost = 0;
   let sessionCostDirty = true;
   let unsubscribeCodexFast: (() => void) | undefined;
-  let requestGitStatusRefresh: (() => void) | undefined;
   const resetSessionCost = (): void => {
     cachedSessionCost = 0;
     sessionCostDirty = true;
@@ -273,25 +404,25 @@ export function registerFooter(pi: ExtensionAPI, goalRuntime: GoalRuntime): void
 
     ctx.ui.setFooter((tui, theme, footerData) => {
       activeTui = tui;
-      let uncommittedFileCount: number | undefined;
-      const gitStatus = createGitStatusRefresh(ctx.cwd, (count) => {
-        if (count === uncommittedFileCount) return;
-        uncommittedFileCount = count;
+      let gitFileChanges: GitFileChanges | undefined;
+      const gitStatus = createGitFileChangesRefresh(ctx.cwd, (changes) => {
+        if (JSON.stringify(changes) === JSON.stringify(gitFileChanges)) return;
+        gitFileChanges = changes;
         tui.requestRender();
       });
-      requestGitStatusRefresh = gitStatus.request;
       const unsubscribe = footerData.onBranchChange(() => {
         gitStatus.request();
         tui.requestRender();
       });
       gitStatus.request();
+      const stopWatch = scheduleGitStatusWatch(ctx.cwd, gitStatus.request);
       const stopFallback = scheduleGitStatusFallback(gitStatus.request);
       return {
         dispose() {
           unsubscribe();
+          stopWatch();
           stopFallback();
           gitStatus.dispose();
-          if (requestGitStatusRefresh === gitStatus.request) requestGitStatusRefresh = undefined;
           if (activeTui === tui) activeTui = undefined;
         },
         invalidate() {},
@@ -332,10 +463,9 @@ export function registerFooter(pi: ExtensionAPI, goalRuntime: GoalRuntime): void
               : footerRowFits(primaryFocused, "", width)
                 ? renderFooterRow(primaryFocused, "", width)
                 : renderFooterRow(essentialModel, context, width);
+          const changes = gitFileChanges ? formatGitFileChanges(gitFileChanges, theme) : "";
           const branchLabel = branch
-            ? uncommittedFileCount
-              ? `${theme.fg("dim", `${branch} · `)}${theme.fg("warning", `${uncommittedFileCount} changed`)}`
-              : theme.fg("dim", branch)
+            ? `${theme.fg("dim", branch)}${changes ? `${theme.fg("dim", " · ")}${changes}` : ""}`
             : "";
           const workspaceRight = goal || fullDirectory;
           const secondaryRow = footerRowFits(branchLabel, workspaceRight, width)
@@ -359,12 +489,8 @@ export function registerFooter(pi: ExtensionAPI, goalRuntime: GoalRuntime): void
     thinkingLevel = event.level;
     activeTui?.requestRender();
   });
-  const refreshAfterActivity = (): void => {
-    invalidateSessionCost();
-    requestGitStatusRefresh?.();
-  };
-  pi.on("turn_end", refreshAfterActivity);
-  pi.on("session_compact", refreshAfterActivity);
+  pi.on("turn_end", invalidateSessionCost);
+  pi.on("session_compact", invalidateSessionCost);
   pi.on("session_tree", () => {
     resetSessionCost();
     activeTui?.requestRender();
@@ -374,7 +500,6 @@ export function registerFooter(pi: ExtensionAPI, goalRuntime: GoalRuntime): void
     unsubscribeCodexFast = undefined;
     resetSessionCost();
     activeTui = undefined;
-    requestGitStatusRefresh = undefined;
     goalRuntime.requestRender = undefined;
   });
 }

package/killeros/goal-command.ts

@@ -0,0 +1,120 @@
+import { parseArgs } from "node:util";
+import { GOAL_CHECK_NAME_PATTERN, GOAL_MAX_TURNS, validateGoalObjective } from "./goal-state.ts";
+
+const GOAL_START_USAGE = "Usage: /goal start [--check <name>] [--turns <count>] -- <objective>";
+const GOAL_CHECK_USAGE = "Usage: /goal check <name|clear>";
+const GOAL_CHECKS_USAGE = "Usage: /goal checks";
+const GOAL_LIMIT_USAGE = "Usage: /goal limit <count|clear>";
+const GOAL_HISTORY_USAGE = "Usage: /goal history [count]";
+const RESERVED_OBJECTIVE_USAGE = "Objective begins with a reserved goal command. Use /goal start -- <objective>.";
+
+interface ControlledGoalStart {
+  objective: string;
+  completionCheckName?: string;
+  maxTurns?: number;
+}
+
+export type GoalCommand =
+  | { kind: "status" }
+  | { kind: "objective"; objective: string }
+  | { kind: "start"; objective: string; completionCheckName?: string; maxTurns?: number }
+  | { kind: "check"; value: { kind: "clear" } | { kind: "named"; name: string } }
+  | { kind: "checks" }
+  | { kind: "limit"; value: { kind: "clear" } | { kind: "count"; count: number } }
+  | { kind: "history"; count: number }
+  | { kind: "clear" }
+  | { kind: "edit" }
+  | { kind: "pause" }
+  | { kind: "resume" }
+  | { kind: "invalid"; message: string };
+
+const RESERVED_GOAL_WORDS = ["start", "check", "checks", "limit", "history", "clear", "edit", "pause", "resume"] as const;
+
+function parseBoundedInteger(value: string, maximum: number): number | undefined {
+  if (!/^[1-9][0-9]*$/u.test(value)) return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed <= maximum ? parsed : undefined;
+}
+
+function parseControlledGoalStart(input: string): ControlledGoalStart | undefined {
+  const separator = input.startsWith("-- ") ? 0 : input.indexOf(" -- ");
+  if (separator < 0) return undefined;
+  const optionText = input.slice(0, separator).trim();
+  const objective = validateGoalObjective(input.slice(separator + (separator === 0 ? 3 : 4)));
+  if (!objective) return undefined;
+  const tokens = optionText ? optionText.split(/\s+/u) : [];
+  if (tokens.filter((token) => token === "--check" || token.startsWith("--check=")).length > 1
+    || tokens.filter((token) => token === "--turns" || token.startsWith("--turns=")).length > 1) return undefined;
+  try {
+    const parsed = parseArgs({
+      args: tokens,
+      options: { check: { type: "string" }, turns: { type: "string" } },
+      strict: true,
+      allowPositionals: false,
+    });
+    const check = parsed.values.check;
+    const turns = parsed.values.turns;
+    if (check !== undefined && !GOAL_CHECK_NAME_PATTERN.test(check)) return undefined;
+    const maxTurns = turns === undefined ? undefined : parseBoundedInteger(turns, GOAL_MAX_TURNS);
+    if (turns !== undefined && maxTurns === undefined) return undefined;
+    return {
+      objective,
+      ...(check === undefined ? {} : { completionCheckName: check }),
+      ...(maxTurns === undefined ? {} : { maxTurns }),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Parses one raw /goal argument string into a closed command variant. */
+export function parseGoalCommand(args: string): GoalCommand {
+  const input = args.trim();
+  if (!input) return { kind: "status" };
+  const parts = input.split(/\s+/u);
+  const rawFirstWord = parts[0] ?? "";
+  const firstWord = RESERVED_GOAL_WORDS.find((word) => word === rawFirstWord.toLowerCase());
+  if (!firstWord) {
+    const objective = validateGoalObjective(input);
+    return objective
+      ? { kind: "objective", objective }
+      : { kind: "invalid", message: "A goal objective may not exceed 4,000 characters" };
+  }
+
+  if (firstWord === "start") {
+    const start = parseControlledGoalStart(input.slice(rawFirstWord.length).trimStart());
+    if (start) return { kind: "start", ...start };
+    return { kind: "invalid", message: rawFirstWord === firstWord ? GOAL_START_USAGE : RESERVED_OBJECTIVE_USAGE };
+  }
+  if (firstWord === "check") {
+    const value = parts[1];
+    if (parts.length === 2 && value?.toLowerCase() === "clear") return { kind: "check", value: { kind: "clear" } };
+    if (parts.length === 2 && value && GOAL_CHECK_NAME_PATTERN.test(value)) return { kind: "check", value: { kind: "named", name: value } };
+    return { kind: "invalid", message: rawFirstWord !== firstWord && parts.length > 2 ? RESERVED_OBJECTIVE_USAGE : GOAL_CHECK_USAGE };
+  }
+  if (firstWord === "checks") {
+    return parts.length === 1
+      ? { kind: "checks" }
+      : { kind: "invalid", message: rawFirstWord === firstWord ? GOAL_CHECKS_USAGE : RESERVED_OBJECTIVE_USAGE };
+  }
+  if (firstWord === "limit") {
+    const value = parts[1];
+    if (parts.length === 2 && value?.toLowerCase() === "clear") return { kind: "limit", value: { kind: "clear" } };
+    const count = parts.length === 2 && value ? parseBoundedInteger(value, GOAL_MAX_TURNS) : undefined;
+    if (count !== undefined) return { kind: "limit", value: { kind: "count", count } };
+    return { kind: "invalid", message: rawFirstWord !== firstWord && parts.length > 2 ? RESERVED_OBJECTIVE_USAGE : GOAL_LIMIT_USAGE };
+  }
+  if (firstWord === "history") {
+    if (parts.length === 1) return { kind: "history", count: 20 };
+    const count = parts.length === 2 && parts[1] ? parseBoundedInteger(parts[1], 50) : undefined;
+    if (count !== undefined) return { kind: "history", count };
+    return { kind: "invalid", message: rawFirstWord !== firstWord && parts.length > 2 ? RESERVED_OBJECTIVE_USAGE : GOAL_HISTORY_USAGE };
+  }
+  if (parts.length === 1) return { kind: firstWord };
+  return {
+    kind: "invalid",
+    message: rawFirstWord === firstWord
+      ? `Usage: /goal ${firstWord}`
+      : RESERVED_OBJECTIVE_USAGE,
+  };
+}

package/killeros/goal-history.ts

@@ -0,0 +1,71 @@
+import { formatTime, formatTokens } from "./display.ts";
+import { parseGoalState } from "./goal-state.ts";
+import type { GoalState } from "./runtime.ts";
+import { safeTerminalText } from "./safe-terminal-text.ts";
+
+const GOAL_ENTRY_TYPE = "killeros-goal";
+const VALID_GOAL_EVENTS: ReadonlySet<string> = new Set([
+  "set", "replace", "edit", "check", "limit", "turn", "pause", "resume",
+  "blocker-audit", "blocked", "complete", "error", "clear", "checkpoint",
+]);
+function isUnknownRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function tokenUsage(entry: Record<string, unknown>): number | undefined {
+  if (entry.type === "message" && isUnknownRecord(entry.message)
+    && (entry.message.role === "assistant" || entry.message.role === "toolResult")
+    && isUnknownRecord(entry.message.usage)
+    && typeof entry.message.usage.totalTokens === "number"
+    && Number.isFinite(entry.message.usage.totalTokens)
+    && entry.message.usage.totalTokens >= 0) {
+    return entry.message.usage.totalTokens;
+  }
+  if ((entry.type === "compaction" || entry.type === "branch_summary")
+    && isUnknownRecord(entry.usage)
+    && typeof entry.usage.totalTokens === "number"
+    && Number.isFinite(entry.usage.totalTokens)
+    && entry.usage.totalTokens >= 0) {
+    return entry.usage.totalTokens;
+  }
+  return undefined;
+}
+
+function preview(value: string): string {
+  const safe = safeTerminalText(value).replaceAll("\n", " ").trim();
+  const characters = [...safe];
+  return characters.length <= 160 ? safe : `${characters.slice(0, 159).join("")}…`;
+}
+
+function eventDetail(event: string, state: GoalState): string {
+  if (event === "check") return state.completionCheck ? `check ${state.completionCheck.name}` : "check cleared";
+  if (event === "limit") return state.maxTurns === undefined ? "limit cleared" : `limit ${state.maxTurns}`;
+  if (event === "blocker-audit" && state.blockerAudit) {
+    return `Blocker ${state.blockerAudit.streak}/3: ${state.blockerAudit.evidence ?? state.blockerAudit.key}`;
+  }
+  return state.result || state.objective;
+}
+
+/** Projects branch entries into the latest bounded goal-history rows. */
+export function formatGoalHistory(entries: readonly unknown[], count: number): string | undefined {
+  const lines: string[] = [];
+  let tokens = 0;
+  let previousState: GoalState | undefined;
+  for (const value of entries) {
+    if (!isUnknownRecord(value)) continue;
+    const usage = tokenUsage(value);
+    if (usage !== undefined) {
+      tokens += usage;
+      continue;
+    }
+    if (value.type !== "custom" || value.customType !== GOAL_ENTRY_TYPE || !isUnknownRecord(value.data)) continue;
+    const event = value.data.event;
+    if (typeof event !== "string" || !VALID_GOAL_EVENTS.has(event)) continue;
+    const state = value.data.state === null ? previousState : parseGoalState(value.data.state);
+    if (!state) continue;
+    if (value.data.state !== null) previousState = state;
+    if (event === "turn" || event === "checkpoint") continue;
+    lines.push(`+${formatTime(Math.max(0, state.updatedAt - state.createdAt))}  ${event}  turn ${state.turns}  ${formatTokens(Math.max(0, tokens - state.baselineTokens))} tokens  ${preview(eventDetail(event, state))}`);
+  }
+  return lines.length ? lines.slice(-count).join("\n") : undefined;
+}