killeros 2.1.29 → 2.1.30

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to KillerOS are documented here.
 
 ## [Unreleased]
 
+## [2.1.30] - 2026-09-21
+
+### Added
+
+- Added measured assistant output-token throughput to settled worked-for receipts, excluding first-token latency, tool execution, and gaps between model calls.
+
+### Fixed
+
+- Prevented competing stale-settings-lock recovery attempts from removing a new writer's lock and losing settings updates.
+- Recorded change receipts in repositories using Git's reftable reference backend while still rejecting receipts when `HEAD` moves during a response.
+- Serialized global `killeros.json` updates across Pi processes so concurrent automatic-compaction and notification changes no longer discard successful writes or fail during Windows file replacement.
+- Accepted `/handoff` summaries with `## ` lines inside fenced code blocks instead of rejecting the complete summary for an extra section.
+- Changed the footer's `ctx` percentage to show context remaining, matching `/auto-compact` threshold direction while preserving urgency colors and the `/compact` hint.
+- Reported `/goal` objectives with unsupported terminal content separately from the 4,000-character limit.
+
 ## [2.1.29] - 2026-09-19
 
 ### Added

package/README.md

@@ -32,7 +32,7 @@ Or from GitHub:
 pi install git:github.com/KyrosHendrix/pi-KillerOS
 ```
 
-Pin a release by appending its tag, for example `@v2.1.29`. Add `-l` to install only for the current project. Restart Pi after installing.
+Pin a release by appending its tag, for example `@v2.1.30`. Add `-l` to install only for the current project. Restart Pi after installing.
 
 ## Commands
 

package/killeros/change-receipt.ts

@@ -234,24 +234,18 @@ async function snapshotKnownPaths(repo: Repository, baseline: Snapshot, paths: r
 }
 
 async function currentHead(repo: Repository): Promise<string> {
-  const head = (await readBoundedFile(path.join(repo.gitDirectory, "HEAD"), 4_096)).toString("ascii").trim();
-  if (/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/u.test(head)) return head;
-  const match = /^ref: (refs\/[^\0\r\n]+)$/u.exec(head);
-  const reference = match?.[1];
-  if (!reference || reference.includes("\\") || reference.split("/").some((part) => part === "." || part === "..")) throw new GitFailure("error");
+  let resolved: Buffer;
   try {
-    return (await readBoundedFile(path.join(repo.commonDirectory, ...reference.split("/")), 4_096)).toString("ascii").trim();
+    resolved = await runGit(repo.root, ["rev-parse", "--verify", "HEAD"], undefined, 4_096);
   } catch (error) {
-    if (!missingFile(error)) throw error;
-  }
-  try {
-    const packed = (await readBoundedFile(path.join(repo.commonDirectory, "packed-refs"), GIT_OUTPUT_LIMIT)).toString("ascii");
-    const packedMatch = new RegExp(`^([0-9a-f]{40}(?:[0-9a-f]{24})?) ${reference.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}$`, "mu").exec(packed);
-    return packedMatch?.[1] ?? "(initial)";
-  } catch (error) {
-    if (missingFile(error)) return "(initial)";
-    throw error;
+    if (!(error instanceof GitFailure) || error.reason !== "error") throw error;
+    const reference = decode(await runGit(repo.root, ["symbolic-ref", "--quiet", "HEAD"], undefined, 4_096)).trim();
+    if (!/^refs\/[^\0\r\n]+$/u.test(reference)) throw new GitFailure("error");
+    return "(initial)";
   }
+  const head = decode(resolved).trim();
+  if (!/^[0-9a-f]{40}(?:[0-9a-f]{24})?$/u.test(head)) throw new GitFailure("error");
+  return head;
 }
 
 function observes(filePath: string, observedPaths: readonly string[]): boolean {

package/killeros/footer.ts

@@ -259,11 +259,11 @@ export function contextPercentRemaining(ctx: ExtensionContext): number | null {
 export function formatContextProgress(tokensUsed: number | null, contextWindow: number, theme: Theme): string {
   if (tokensUsed === null || !Number.isFinite(tokensUsed)) return theme.fg("dim", "ctx —%");
   const windowSize = Number.isFinite(contextWindow) && contextWindow > 0 ? contextWindow : 128_000;
-  const used = Math.max(0, Math.min(windowSize, Math.max(0, tokensUsed)));
-  const percentUsed = Math.max(0, Math.min(100, Math.round((used / windowSize) * 100)));
-  const color: ThemeColor = percentUsed > 80 ? "error" : percentUsed >= 50 ? "warning" : "success";
-  const action = percentUsed >= 85 ? " · /compact" : "";
-  return theme.fg(color, `ctx ${percentUsed}%${action}`);
+  const used = Math.max(0, tokensUsed);
+  const percentRemaining = Math.max(0, Math.min(100, Math.round(((windowSize - used) / windowSize) * 100)));
+  const color: ThemeColor = percentRemaining > 50 ? "success" : percentRemaining >= 20 ? "warning" : "error";
+  const action = percentRemaining <= 15 ? " · /compact" : "";
+  return theme.fg(color, `ctx ${percentRemaining}%${action}`);
 }
 
 function sumSessionCost(ctx: ExtensionContext): number {

package/killeros/goal-command.ts

@@ -1,4 +1,5 @@
 import { validateGoalObjective } from "./goal-state.ts";
+import { safeTerminalText } from "./safe-terminal-text.ts";
 
 export type GoalCommand =
   | { kind: "status" }
@@ -17,7 +18,9 @@ export function parseGoalCommand(args: string): GoalCommand {
   if (lowered === "resume") return { kind: "resume" };
   if (lowered === "clear") return { kind: "clear" };
   const objective = validateGoalObjective(input);
-  return objective
-    ? { kind: "objective", objective }
-    : { kind: "invalid", message: "A goal objective may not exceed 4,000 characters" };
+  if (objective) return { kind: "objective", objective };
+  if (safeTerminalText(input) !== input) {
+    return { kind: "invalid", message: "A goal objective contains unsupported content" };
+  }
+  return { kind: "invalid", message: "A goal objective may not exceed 4,000 characters" };
 }

package/killeros/handoff.ts

@@ -91,10 +91,46 @@ export function resolveHandoffMaxTokens(settings: Readonly<KillerosSettings>, ov
   return positiveIntOr(override, positiveIntOr(settings.handoffMaxTokens, DEFAULT_HANDOFF_MAX_TOKENS));
 }
 
+/** Finds fenced code spans so `## ` lines inside them are not treated as headings. */
+function fencedCodeRanges(document: string): Array<{ start: number; end: number }> {
+  const ranges: Array<{ start: number; end: number }> = [];
+  let fenceStart: number | null = null;
+  let fenceChar = "";
+  let fenceLength = 0;
+  for (const line of document.matchAll(/[^\r\n]*(?:\r\n|\n|$)/g)) {
+    if (line[0].length === 0) break;
+    const lineStart = line.index ?? 0;
+    const lineEnd = lineStart + line[0].length;
+    const text = line[0].replace(/\r?\n$/, "");
+    const fence = /^[ \t]{0,3}(`{3,}|~{3,})/.exec(text);
+    if (!fence) continue;
+    const marker: string = fence[1];
+    const rest = text.slice(fence[0].length);
+    if (fenceStart === null) {
+      if (marker.startsWith("`") && rest.includes("`")) continue;
+      fenceStart = lineStart;
+      fenceChar = marker[0];
+      fenceLength = marker.length;
+    } else if (marker[0] === fenceChar && marker.length >= fenceLength && /^[ \t]*$/.test(rest)) {
+      ranges.push({ start: fenceStart, end: lineEnd });
+      fenceStart = null;
+      fenceChar = "";
+      fenceLength = 0;
+    }
+  }
+  if (fenceStart !== null) ranges.push({ start: fenceStart, end: document.length });
+  return ranges;
+}
+
 /** Checks that the model returned every section needed to continue safely. */
 function hasRequiredHandoffContent(document: string, focus: string): boolean {
   if (focus && !document.includes(focus)) return false;
-  const headings = [...document.matchAll(/^## ([^\r\n]+?)[ \t]*\r?$/gmu)];
+  const ranges = fencedCodeRanges(document);
+  const headings = [...document.matchAll(/^## ([^\r\n]+?)[ \t]*\r?$/gmu)]
+    .filter((heading) => {
+      const index = heading.index ?? 0;
+      return !ranges.some((range) => index >= range.start && index < range.end);
+    });
   if (headings.length !== HANDOFF_SECTIONS.length) return false;
   return headings.every((heading, index) => {
     if (heading[1] !== HANDOFF_SECTIONS[index]) return false;

package/killeros/settings.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { linkSync, mkdirSync, readFileSync, renameSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { hasErrorCode } from "./errors.ts";
@@ -26,16 +26,103 @@ function readStoredSettings(settingsPath: string): KillerosSettings {
   }
 }
 
+const LOCK_RETRY_MILLISECONDS = 10;
+const LOCK_TIMEOUT_MILLISECONDS = 10_000;
+
+function readLockOwnerPid(lockPath: string): number | undefined {
+  try {
+    const value: unknown = JSON.parse(readFileSync(lockPath, "utf8"));
+    if (!isSettings(value) || typeof value.pid !== "number" || !Number.isSafeInteger(value.pid) || value.pid <= 0) return undefined;
+    return value.pid;
+  } catch {
+    return undefined;
+  }
+}
+
+function isProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return !hasErrorCode(error, "ESRCH");
+  }
+}
+
+function moveLockAside(lockPath: string): boolean {
+  const stalePath = `${lockPath}.${process.pid}.${randomUUID()}.stale`;
+  const deadline = Date.now() + LOCK_TIMEOUT_MILLISECONDS;
+  while (true) {
+    try {
+      renameSync(lockPath, stalePath);
+      break;
+    } catch (error) {
+      if (hasErrorCode(error, "ENOENT")) return false;
+      if (
+        Date.now() >= deadline
+        || !["EACCES", "EBUSY", "EPERM"].some((code) => hasErrorCode(error, code))
+      ) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_RETRY_MILLISECONDS);
+    }
+  }
+  rmSync(stalePath, { force: true });
+  return true;
+}
+
+function recoverSettingsLock(lockPath: string, expectedPid: number): boolean {
+  const recoveryPath = `${lockPath}.recovery`;
+  try {
+    mkdirSync(recoveryPath);
+  } catch (error) {
+    if (hasErrorCode(error, "EEXIST")) return false;
+    throw error;
+  }
+  try {
+    // Recheck under exclusive recovery ownership; another waiter may have replaced the lock.
+    return readLockOwnerPid(lockPath) === expectedPid && !isProcessRunning(expectedPid) && moveLockAside(lockPath);
+  } finally {
+    // ponytail: a crash during recovery leaves .recovery for manual removal; never steal it and risk lost writes.
+    rmdirSync(recoveryPath);
+  }
+}
+
+function acquireSettingsLock(settingsPath: string): () => void {
+  const lockPath = `${settingsPath}.lock`;
+  const ownerPath = `${lockPath}.${process.pid}.${randomUUID()}.tmp`;
+  const deadline = Date.now() + LOCK_TIMEOUT_MILLISECONDS;
+  writeFileSync(ownerPath, JSON.stringify({ pid: process.pid }), { encoding: "utf8", mode: 0o600, flag: "wx" });
+  try {
+    while (true) {
+      try {
+        linkSync(ownerPath, lockPath);
+        break;
+      } catch (error) {
+        if (!hasErrorCode(error, "EEXIST")) throw error;
+        const currentOwnerPid = readLockOwnerPid(lockPath);
+        if (currentOwnerPid && !isProcessRunning(currentOwnerPid) && recoverSettingsLock(lockPath, currentOwnerPid)) continue;
+        if (Date.now() >= deadline) throw new Error(`Timed out waiting for KillerOS settings lock: ${lockPath}`);
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_RETRY_MILLISECONDS);
+      }
+    }
+  } finally {
+    rmSync(ownerPath, { force: true });
+  }
+
+  return () => {
+    moveLockAside(lockPath);
+  };
+}
+
 export function createKillerosSettingsStore(
   settingsPath = join(getAgentDir(), "killeros.json"),
 ): KillerosSettingsStore {
   return {
     load: () => readStoredSettings(settingsPath),
     update: (patch) => {
-      const current = readStoredSettings(settingsPath);
       mkdirSync(dirname(settingsPath), { recursive: true });
+      const releaseLock = acquireSettingsLock(settingsPath);
       const temporaryPath = `${settingsPath}.${process.pid}.${randomUUID()}.tmp`;
       try {
+        const current = readStoredSettings(settingsPath);
         writeFileSync(
           temporaryPath,
           `${JSON.stringify({ ...current, ...patch }, null, 2)}\n`,
@@ -43,7 +130,11 @@ export function createKillerosSettingsStore(
         );
         renameSync(temporaryPath, settingsPath);
       } finally {
-        rmSync(temporaryPath, { force: true });
+        try {
+          rmSync(temporaryPath, { force: true });
+        } finally {
+          releaseLock();
+        }
       }
     },
   };

package/killeros/worked-for.ts

@@ -48,6 +48,8 @@ export interface WorkedForEntryDataV4 {
   checks: CheckAttempt[];
   omittedChecks: { passed: number; failed: number };
   model?: string;
+  outputTokens?: number;
+  decodeMilliseconds?: number;
 }
 
 type WorkedForEntryData = WorkedForEntryDataV1 | WorkedForEntryDataV2 | WorkedForEntryDataV3 | WorkedForEntryDataV4;
@@ -66,6 +68,10 @@ function integer(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value) && Number.isInteger(value) && value >= 0;
 }
 
+function positiveInteger(value: unknown): value is number {
+  return integer(value) && value > 0;
+}
+
 function record(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -148,6 +154,9 @@ function parseV4(data: Record<string, unknown>): WorkedForEntryDataV4 | undefine
     checks.push({ label, outcome: check.outcome });
   }
   const model = parseModelName(data.model);
+  const throughput = positiveInteger(data.outputTokens) && positiveInteger(data.decodeMilliseconds)
+    ? { outputTokens: data.outputTokens, decodeMilliseconds: data.decodeMilliseconds }
+    : {};
   return {
     version: 4,
     milliseconds: data.milliseconds,
@@ -157,6 +166,7 @@ function parseV4(data: Record<string, unknown>): WorkedForEntryDataV4 | undefine
     checks,
     omittedChecks: { passed: data.omittedChecks.passed, failed: data.omittedChecks.failed },
     ...(model ? { model } : {}),
+    ...throughput,
   };
 }
 
@@ -221,9 +231,15 @@ class WorkedForV4Component implements Component {
     const { data, theme } = this;
     const outcome = OUTCOMES[data.outcome];
     const headline = theme.fg(outcome.color, outcome.label);
+    const tokensPerSecond = data.outputTokens !== undefined && data.decodeMilliseconds !== undefined
+      ? data.outputTokens / (data.decodeMilliseconds / 1_000)
+      : undefined;
+    const speedSuffix = tokensPerSecond !== undefined && Number.isFinite(tokensPerSecond) && tokensPerSecond > 0
+      ? ` · ${tokensPerSecond.toFixed(1)} tok/s`
+      : "";
     const modelSuffix = data.model ? ` · ${data.model}` : "";
     const lines = [
-      `${headline}${theme.fg("dim", ` · ${formatWorkedForDuration(data.milliseconds)} · ↑ ${formatTokens(data.tokens)} tokens${modelSuffix}`)}`,
+      `${headline}${theme.fg("dim", ` · ${formatWorkedForDuration(data.milliseconds)} · ↑ ${formatTokens(data.tokens)} tokens${speedSuffix}${modelSuffix}`)}`,
     ];
     if (data.changes.state === "unavailable") lines.push(theme.fg("dim", "Changes unavailable"));
     else if (data.changes.totalFiles === 0) lines.push(theme.fg("dim", "No files changed"));
@@ -287,8 +303,34 @@ type ActiveReceipt = {
   modelProvider: string | undefined;
   modelId: string | undefined;
   modelMismatch: boolean;
+  outputTokens: number;
+  decodeMilliseconds: number;
+  decodeStartedAt: number | undefined;
+  throughputInvalid: boolean;
 };
 
+function finishAssistantStream(
+  receipt: ActiveReceipt,
+  outputTokens: number,
+  endedAt: number,
+  failed: boolean,
+): void {
+  if (failed) {
+    if (receipt.decodeStartedAt !== undefined) receipt.throughputInvalid = true;
+  } else if (receipt.decodeStartedAt !== undefined) {
+    const decodeMilliseconds = endedAt - receipt.decodeStartedAt;
+    if (positiveInteger(outputTokens) && positiveInteger(decodeMilliseconds)) {
+      receipt.outputTokens += outputTokens;
+      receipt.decodeMilliseconds += decodeMilliseconds;
+    } else {
+      receipt.throughputInvalid = true;
+    }
+  } else if (outputTokens !== 0) {
+    receipt.throughputInvalid = true;
+  }
+  receipt.decodeStartedAt = undefined;
+}
+
 function receiptModelName(
   settled: ActiveReceipt,
   model: ExtensionContext["model"],
@@ -349,30 +391,46 @@ export function registerWorkedFor(
       modelProvider: undefined,
       modelId: undefined,
       modelMismatch: false,
+      outputTokens: 0,
+      decodeMilliseconds: 0,
+      decodeStartedAt: undefined,
+      throughputInvalid: false,
     };
     active = state;
     const collection = await state.collection;
     if (active !== state) await collection.dispose();
   });
 
+  pi.on("message_update", (event, ctx) => {
+    if (ctx.mode !== "tui" || !active) return;
+    const update = event.assistantMessageEvent;
+    if ((update.type === "text_delta" || update.type === "thinking_delta" || update.type === "toolcall_delta")
+      && update.delta.length > 0) active.decodeStartedAt ??= now();
+  });
+
   pi.on("message_end", (event, ctx) => {
     if (ctx.mode !== "tui" || !active) return;
     if (event.message.role !== "assistant") return;
     const provider: unknown = event.message.provider;
     const modelId: unknown = event.message.model;
-    if (typeof provider !== "string" || typeof modelId !== "string") {
-      active.modelMismatch = true;
-      return;
-    }
-    if (active.modelProvider === undefined || active.modelId === undefined) {
-      active.modelProvider = provider;
-      active.modelId = modelId;
-    } else if (active.modelProvider !== provider || active.modelId !== modelId) {
-      active.modelMismatch = true;
-    }
-    if (event.message.responseModel !== undefined && event.message.responseModel !== modelId) {
-      active.modelMismatch = true;
+    if (typeof provider !== "string" || typeof modelId !== "string") active.modelMismatch = true;
+    else {
+      if (active.modelProvider === undefined || active.modelId === undefined) {
+        active.modelProvider = provider;
+        active.modelId = modelId;
+      } else if (active.modelProvider !== provider || active.modelId !== modelId) {
+        active.modelMismatch = true;
+      }
+      if (event.message.responseModel !== undefined && event.message.responseModel !== modelId) {
+        active.modelMismatch = true;
+      }
     }
+    finishAssistantStream(
+      active,
+      event.message.usage.output,
+      now(),
+      event.message.stopReason === "error" || event.message.stopReason === "aborted",
+    );
   });
 
   pi.on("tool_result", (event: ToolResultEvent, ctx) => {
@@ -404,6 +462,10 @@ export function registerWorkedFor(
       ctx.ui.notify(`Change receipt unavailable: ${changes.reason}`, "warning");
     }
     const settledTokens = sessionTokenTotal(ctx);
+    const throughput = !settled.throughputInvalid && settled.decodeStartedAt === undefined && !settled.modelMismatch
+      && positiveInteger(settled.outputTokens) && positiveInteger(settled.decodeMilliseconds)
+      ? { outputTokens: settled.outputTokens, decodeMilliseconds: settled.decodeMilliseconds }
+      : {};
     const data = fitPayload({
       version: 4,
       milliseconds: Math.max(0, now() - settled.startedAt),
@@ -413,6 +475,7 @@ export function registerWorkedFor(
       checks: settled.checks,
       omittedChecks: settled.omittedChecks,
       ...(model ? { model } : {}),
+      ...throughput,
     });
     try {
       pi.appendEntry<WorkedForEntryDataV4>(WORKED_FOR_ENTRY_TYPE, data);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "killeros",
-  "version": "2.1.29",
+  "version": "2.1.30",
   "description": "TUI, goals, and workflow automation for the Pi coding agent",
   "type": "module",
   "keywords": [