@aliou/pi-processes 0.10.2 → 0.10.4

package/extensions/processes/handlers/notifications.ts

@@ -60,10 +60,11 @@ export function registerNotificationDelivery(
       summary: `Suppressed ${count} log-match notifications because output was too fast.`,
       attention: "context",
     };
-    sendProcessNotificationMessage(pi, details, {
-      triggerTurn: false,
-      deliverAs: "steer",
-    });
+    sendProcessNotificationMessage(
+      pi,
+      details,
+      attentionToSendOptions(details.attention),
+    );
   };
 
   const flushSuppressedSummary = () => {

package/extensions/processes/notifications/log-matchers.ts

@@ -1,4 +1,5 @@
 import { compileLineMatcher } from "../../../src/utils/match-line";
+import { plainTextForDisplay } from "../../shared/display-text";
 import type { NotifyConfig } from "./registry";
 import type { Attention } from "./types";
 
@@ -130,8 +131,12 @@ function splitAppendedIntoLines(
   for (const entry of appended) {
     const split = entry.text.split("\n");
     for (const line of split) {
-      if (line.length === 0) continue;
-      lines.push({ type: entry.type, text: line });
+      // Match the same per-line visible text the log views render. This keeps
+      // CR-overwritten progress and invisible escape bytes from firing
+      // watches, without making watches depend on viewport width.
+      const displayLine = plainTextForDisplay(line);
+      if (displayLine.length === 0) continue;
+      lines.push({ type: entry.type, text: displayLine });
     }
   }
 

package/extensions/processes/notifications/service.ts

@@ -25,7 +25,10 @@ const DEFAULT_ATTENTION: Record<
   "onSuccess" | "onFailure" | "onKilled",
   Attention
 > = {
-  onSuccess: "context",
+  // Keep in sync with DEFAULT_NOTIFY_CONFIG in tools/notify.ts. Success
+  // defaults to a turn because "context" is only seen by an agent that is
+  // still streaming when the process ends.
+  onSuccess: "turn",
   onFailure: "turn",
   // External kills surface as context by default (see DEFAULT_NOTIFY_CONFIG
   // in tools/notify.ts for rationale). Intentional stops are classified

package/extensions/processes/tools/index.ts

@@ -54,7 +54,8 @@ export function registerProcessTool(
         "Manage long-running background processes: start, list, stop, write to stdin, update watches, clear finished entries, and inspect recent output. After starting a process, do not wait - notifications bring you back on exit and on log matches.",
       promptGuidelines: [
         "process tool: use process start for long-running commands (dev servers, watchers, builds) instead of shell background patterns like &, nohup, or setsid; give each process a specific name and check process list first when a duplicate would be noisy.",
-        "process tool: after process start, do not sleep, poll, or hold your turn. End your turn or move on. The process notifies you on exit (success, failure, killed) and on notify.logMatches matches, which brings you back.",
+        "process tool: after process start, do not sleep, poll, or hold your turn. End your turn or move on. Exits and notify.logMatches matches bring you back.",
+        "process tool: attention turn wakes you when idle; context only reaches you if you are still working; ignore never notifies. Keep turn for anything whose result you need.",
         "process tool: use notify.logMatches to get brought back on readiness or error signals instead of polling process output. If a watch is too noisy, use process update (watches.mode append/replace/remove/clear) to fix it without restarting.",
         "process tool: for the full lifecycle (start, list, output, update, write, stop, clear), notify options, use cases, and noisy-watch handling, read the pi-processes skill.",
       ],

package/extensions/processes/tools/notify.ts

@@ -14,7 +14,13 @@ export const MAX_NOTIFY_LOG_MATCHERS = MAX_LOG_MATCHERS_PER_PROCESS;
 export const MAX_NOTIFY_PATTERN_LENGTH = MAX_LOG_MATCH_PATTERN_LENGTH;
 
 const DEFAULT_NOTIFY_CONFIG = {
-  onSuccess: "context",
+  // A backgrounded process usually outlives the turn that started it, and
+  // "context" only reaches the agent if it happens to still be streaming when
+  // the process ends. Builds, tests, and other one-shot commands are started
+  // precisely because the agent needs the result, so success defaults to a
+  // turn. Long-running servers rarely exit 0, and callers that do not want the
+  // interruption can pass onSuccess: "context".
+  onSuccess: "turn",
   onFailure: "turn",
   // External kills (outside this manager) surface as context by default so
   // the agent and user learn that a managed process disappeared. Intentional
@@ -36,11 +42,14 @@ export function normalizeNotifyConfig(input: unknown): NotifyConfig {
 
   return {
     onSuccess:
-      normalizeAttention(input.onSuccess, "notify.onSuccess") ?? "context",
+      normalizeAttention(input.onSuccess, "notify.onSuccess") ??
+      DEFAULT_NOTIFY_CONFIG.onSuccess,
     onFailure:
-      normalizeAttention(input.onFailure, "notify.onFailure") ?? "turn",
+      normalizeAttention(input.onFailure, "notify.onFailure") ??
+      DEFAULT_NOTIFY_CONFIG.onFailure,
     onKilled:
-      normalizeAttention(input.onKilled, "notify.onKilled") ?? "context",
+      normalizeAttention(input.onKilled, "notify.onKilled") ??
+      DEFAULT_NOTIFY_CONFIG.onKilled,
     logMatches: normalizeLogMatches(logMatches),
   };
 }

package/extensions/processes/tools/schema.ts

@@ -110,28 +110,25 @@ const WatchUpdateItemParams = Type.Object({
   ),
   on: Type.Optional(
     StringEnum(PROCESS_NOTIFY_ATTENTIONS, {
-      description: "Agent attention for this log match. Defaults to turn.",
+      description: "Attention for this match. Defaults to turn.",
     }),
   ),
 });
 
-const NotifyParams = Type.Object({
+const NotifyProperties = {
   onSuccess: Type.Optional(
     StringEnum(PROCESS_NOTIFY_ATTENTIONS, {
-      description:
-        "Agent attention when the process exits successfully. Defaults to context.",
+      description: "Attention on clean exit. Defaults to turn.",
     }),
   ),
   onFailure: Type.Optional(
     StringEnum(PROCESS_NOTIFY_ATTENTIONS, {
-      description:
-        "Agent attention when the process fails or crashes. Defaults to turn.",
+      description: "Attention on failure or crash. Defaults to turn.",
     }),
   ),
   onKilled: Type.Optional(
     StringEnum(PROCESS_NOTIFY_ATTENTIONS, {
-      description:
-        "Agent attention when the process is killed. Defaults to context.",
+      description: "Attention on external kill. Defaults to context.",
     }),
   ),
   logMatches: Type.Optional(
@@ -141,6 +138,11 @@ const NotifyParams = Type.Object({
         "Log match notifications. Supports at most 20 matchers, with each pattern limited to 500 characters.",
     }),
   ),
+};
+
+const NotifyParams = Type.Object(NotifyProperties, {
+  description:
+    "Notify settings. Attention: turn wakes an idle agent, context only reaches an agent still working, ignore never notifies.",
 });
 
 export const ProcessesParams = Type.Object({

package/extensions/processes-logs/components/log-file-viewer.ts

@@ -1,8 +1,15 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { visibleWidth } from "@earendil-works/pi-tui";
-import { sanitizeForDisplay } from "../../shared/display-text";
+import {
+  plainTextForDisplay,
+  sanitizeForDisplay,
+} from "../../shared/display-text";
 import { trimToBudget } from "../../shared/line-buffer";
-import { type LogLineEmphasis, renderLogLine } from "../../shared/log-line";
+import {
+  displayTextOf,
+  type LogLineEmphasis,
+  renderLogLine,
+} from "../../shared/log-line";
 import { truncateToWidth } from "../../shared/truncate";
 import type { ProcessLogLine } from "../logs-client";
 
@@ -122,8 +129,9 @@ export class LogFileViewer {
    * priority (search current match > search match > notify match > stream).
    */
   addNotifyMatch(match: { line: string }): void {
-    // Stored sanitized so it can be compared against sanitized buffer lines.
-    const line = sanitizeForDisplay(match.line);
+    // Stored as plain visible text so invisible escape bytes cannot be what
+    // makes a notification marker match.
+    const line = plainTextForDisplay(match.line);
     if (line) this.notifyLines.add(line);
   }
 
@@ -192,7 +200,8 @@ export class LogFileViewer {
           ? "search-current"
           : matchSet.has(visibleIndex)
             ? "search"
-            : this.notifyLines.has(line.text)
+            : this.notifyLines.has(line.text) ||
+                this.notifyLines.has(displayTextOf(line))
               ? "notify"
               : "none";
       return renderLogLine(line, { theme: this.theme, width, emphasis });

package/extensions/shared/display-text.ts

@@ -13,10 +13,17 @@ const ESC = String.fromCodePoint(0x001b);
 const BEL = String.fromCodePoint(0x0007);
 const ST = String.fromCodePoint(0x009c);
 const RESET = `${ESC}[0m`;
+const C1_DCS = String.fromCodePoint(0x0090);
+const C1_SOS = String.fromCodePoint(0x0098);
+const C1_OSC = String.fromCodePoint(0x009d);
+const C1_PM = String.fromCodePoint(0x009e);
+const C1_APC = String.fromCodePoint(0x009f);
+const C1_STRING_INTRODUCERS = [C1_DCS, C1_SOS, C1_OSC, C1_PM, C1_APC];
 
-// Control characters a single display row must never contain. Tabs are handled
-// separately; newlines are dropped because they would shift the whole frame.
-// C1 controls are included: a raw \u009b is an alias for CSI on some terminals.
+// Control characters a single display row must never contain. Tabs and
+// carriage returns are handled separately; newlines are dropped because they
+// would shift the whole frame. C1 controls are included: a raw \u009b is an
+// alias for CSI on some terminals.
 // biome-ignore lint/suspicious/noControlCharactersInRegex: this regex intentionally targets terminal control characters.
 const DISPLAY_CONTROL_CHARS = /[\u0000-\u0008\u000a-\u001f\u007f-\u009f]/gu;
 
@@ -41,7 +48,9 @@ const TAB_WIDTH = 8;
  * into the rest of the frame.
  */
 export function sanitizeForDisplay(text: string): string {
-  if (!text.includes(ESC)) return cleanPlainText(text, 0).text;
+  if (!text.includes(ESC) && !hasC1StringIntroducer(text)) {
+    return cleanPlainText(text, 0).text;
+  }
 
   let out = "";
   let cursor = 0;
@@ -49,21 +58,34 @@ export function sanitizeForDisplay(text: string): string {
   let keptSgr = false;
 
   while (cursor < text.length) {
-    const escapeAt = text.indexOf(ESC, cursor);
-    if (escapeAt === -1) {
-      out += cleanPlainText(text.slice(cursor), column).text;
+    const sequenceAt = findNextSequenceStart(text, cursor);
+    if (sequenceAt === -1) {
+      const chunk = cleanPlainText(text.slice(cursor), column);
+      if (chunk.resetsRow) {
+        out = "";
+        keptSgr = false;
+      }
+      out += chunk.text;
       break;
     }
-    const chunk = cleanPlainText(text.slice(cursor, escapeAt), column);
+    const chunk = cleanPlainText(text.slice(cursor, sequenceAt), column);
+    if (chunk.resetsRow) {
+      out = "";
+      keptSgr = false;
+    }
     out += chunk.text;
     column = chunk.column;
 
-    const sequence = readEscapeSequence(text, escapeAt);
-    if (sequence.isSgr) {
-      out += text.slice(escapeAt, sequence.end);
-      keptSgr = true;
+    if (text[sequenceAt] === ESC) {
+      const sequence = readEscapeSequence(text, sequenceAt);
+      if (sequence.isSgr) {
+        out += text.slice(sequenceAt, sequence.end);
+        keptSgr = true;
+      }
+      cursor = sequence.end;
+    } else {
+      cursor = readC1StringSequence(text, sequenceAt).end;
     }
-    cursor = sequence.end;
   }
 
   if (!keptSgr || out.endsWith(RESET)) return out;
@@ -79,6 +101,22 @@ export function truncateForDisplay(text: string, width: number): string {
   return closeSgr(truncateToWidth(sanitizeForDisplay(text), width, "…"));
 }
 
+/**
+ * Return the unstyled text a user can actually read after terminal controls
+ * have been interpreted/dropped. Use this for comparisons such as search,
+ * notify markers, and log watches so invisible escape bytes cannot match.
+ */
+export function plainTextForDisplay(text: string): string {
+  return stripSgr(sanitizeForDisplay(text));
+}
+
+const SGR = new RegExp(`${ESC}\\[[0-9;:]*m`, "gu");
+
+/** Drop the SGR sequences `sanitizeForDisplay` kept for rendering colors. */
+export function stripSgr(text: string): string {
+  return text.replace(SGR, "");
+}
+
 /**
  * Re-close colors after truncation. `sanitizeForDisplay` ends a colored string
  * with a reset, but truncating can cut that reset off and let the color bleed
@@ -97,21 +135,42 @@ export function closeSgr(text: string): string {
 function cleanPlainText(
   text: string,
   column: number,
-): { text: string; column: number } {
-  const clean = text.replace(DISPLAY_CONTROL_CHARS, "");
+): { text: string; column: number; resetsRow: boolean } {
+  const carriageReturn = text.lastIndexOf("\r");
+  const resetsRow = carriageReturn !== -1;
+  const visibleText = resetsRow ? text.slice(carriageReturn + 1) : text;
+  const startColumn = resetsRow ? 0 : column;
+  const clean = visibleText.replace(DISPLAY_CONTROL_CHARS, "");
   if (!clean.includes("\t")) {
-    return { text: clean, column: column + visibleWidth(clean) };
+    return {
+      text: clean,
+      column: startColumn + visibleWidth(clean),
+      resetsRow,
+    };
   }
 
   const parts = clean.split("\t");
   let out = parts[0] ?? "";
-  let col = column + visibleWidth(out);
+  let col = startColumn + visibleWidth(out);
   for (const part of parts.slice(1)) {
     const spaces = TAB_WIDTH - (col % TAB_WIDTH);
     out += " ".repeat(spaces) + part;
     col += spaces + visibleWidth(part);
   }
-  return { text: out, column: col };
+  return { text: out, column: col, resetsRow };
+}
+
+function findNextSequenceStart(text: string, cursor: number): number {
+  let next = text.indexOf(ESC, cursor);
+  for (const introducer of C1_STRING_INTRODUCERS) {
+    const index = text.indexOf(introducer, cursor);
+    if (index !== -1 && (next === -1 || index < next)) next = index;
+  }
+  return next;
+}
+
+function hasC1StringIntroducer(text: string): boolean {
+  return C1_STRING_INTRODUCERS.some((introducer) => text.includes(introducer));
 }
 
 /**
@@ -151,6 +210,12 @@ function readEscapeSequence(
   return { end: start + 2, isSgr: false };
 }
 
+function readC1StringSequence(text: string, start: number): { end: number } {
+  const introducer = text[start];
+  const allowBel = introducer === C1_OSC || introducer === C1_APC;
+  return { end: findStringTerminator(text, start + 1, allowBel) };
+}
+
 /** Index just past the terminator of a string sequence, else end of input. */
 function findStringTerminator(
   text: string,

package/extensions/shared/log-line.ts

@@ -10,7 +10,12 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { visibleWidth } from "@earendil-works/pi-tui";
 
-import { closeSgr, sanitizeForDisplay } from "./display-text";
+import {
+  closeSgr,
+  plainTextForDisplay,
+  sanitizeForDisplay,
+  stripSgr,
+} from "./display-text";
 import { truncateToWidth } from "./truncate";
 
 export interface DisplayLogLine {
@@ -60,7 +65,7 @@ export function renderLogLine(
 
 /** Text of a log line as the views display it, for match comparisons. */
 export function displayTextOf(line: DisplayLogLine): string {
-  return sanitizeForDisplay(line.text);
+  return plainTextForDisplay(line.text);
 }
 
 function toneLogText(
@@ -75,10 +80,3 @@ function toneLogText(
   if (type === "stderr") return theme.fg("warning", text);
   return text;
 }
-
-const SGR = new RegExp(`${String.fromCodePoint(0x001b)}\\[[0-9;:]*m`, "gu");
-
-/** Drop the SGR sequences `sanitizeForDisplay` kept. */
-function stripSgr(text: string): string {
-  return text.replace(SGR, "");
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-processes",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "license": "MIT",
   "type": "module",
   "private": false,

package/skills/pi-processes/SKILL.md

@@ -15,9 +15,11 @@ A started process runs in the background and the manager brings you back when so
 2. End your turn or move on to other work. Do not call `process output` in a loop waiting for "ready".
 3. The process notifies you when:
    - a `logMatches` pattern hits (readiness, error, progress),
-   - the process exits successfully (`onSuccess`, default `context`),
+   - the process exits successfully (`onSuccess`, default `turn`),
    - the process fails or crashes (`onFailure`, default `turn`),
-   - the process is killed, by you or externally (`onKilled`, default `context`).
+   - the process is killed externally (`onKilled`, default `context`, which does not wake an idle agent).
+
+   Stopping a process yourself never notifies.
 4. When a watch is too noisy or wrong, fix it with `process update` — do not restart the process just to change watches.
 5. `process stop` obsolete live processes and `process clear` finished entries when they are no longer useful.
 
@@ -50,6 +52,8 @@ Good:
 }
 ```
 
+`onSuccess: "context"` here because a dev server exiting cleanly needs no reaction. Keep the default `turn` for builds, tests, and other one-shot commands whose result you need.
+
 Optional `cwd` sets the working directory for the spawned command. Omit it to inherit the agent's current working directory.
 
 Empty `logMatches` patterns (literal or regex) are rejected at start and update time. Use `mode: "regex"` only when literal matching is not enough, scope by `stream` to cut noise, and use `repeat: true` when a matcher should fire more than once.
@@ -214,9 +218,9 @@ Good:
 
 Exit attention:
 
-- `notify.onSuccess` — when the process exits successfully. Defaults to `context`.
-- `notify.onFailure` — when the process fails or crashes. Defaults to `turn`.
-- `notify.onKilled` — when the process is killed, by you or externally. Defaults to `context`.
+- `notify.onSuccess` — clean exit. Defaults to `turn`.
+- `notify.onFailure` — failure or crash. Defaults to `turn`.
+- `notify.onKilled` — killed from outside the tool. Defaults to `context`. Stopping a process yourself never notifies.
 
 Log match watches (`notify.logMatches`, up to 20, each pattern up to 500 chars):
 
@@ -226,7 +230,13 @@ Log match watches (`notify.logMatches`, up to 20, each pattern up to 500 chars):
 - `repeat` — `false` (default) fires once; `true` fires on every match.
 - `on` — `turn`, `context`, or `ignore`. Overrides the default attention for that watch. Defaults to `turn`.
 
-`turn` interrupts with an agent message. `context` adds the notice as context without interrupting. `ignore` records the match silently.
+Attention levels:
+
+- `turn` — starts an agent turn. Reaches you even when you are idle.
+- `context` — recorded in the transcript, no turn. It reaches you only if you are still working when the event fires; an idle agent is not woken and sees it on the next user message.
+- `ignore` — recorded, never notifies.
+
+Use `context` only when nothing needs to happen in response.
 
 ## Use cases