portable-agent-layer 0.61.3 → 0.62.0

package/src/hooks/lib/steering.ts

@@ -0,0 +1,162 @@
+/**
+ * Contextual Steering — deterministic prompt-type classifier that injects
+ * task-specific steering into the model's context at prompt time.
+ *
+ * Pure + fail-open: classifyPrompt is a regex table (no LLM, sub-millisecond).
+ * getSteeringReminder wraps matched snippets in a single <system-reminder>,
+ * byte-capped. It rides the same UserPromptSubmit path as inject-retrieval; the
+ * per-agent output adapter is shared (see inject-retrieval's writeForAgent).
+ *
+ * This is the prompt-time counterpart to STEERING_RULES.md: the always-on file
+ * keeps terse directives, while the verbose guidance lives here and is injected
+ * only when the prompt matches that task type.
+ */
+
+import { isEnabled, raw } from "./settings";
+
+/** The tags shipped as built-in defaults. Users may add their own tags via
+ *  pal-settings.json `steering.rules`, so the effective tag set is open-ended. */
+type SteeringTag =
+  | "debugging"
+  | "destructive"
+  | "refactor"
+  | "planning"
+  | "testing"
+  | "committing"
+  | "secrets";
+
+interface SteeringRule {
+  tag: string;
+  pattern: RegExp;
+  snippet: string;
+}
+
+// Ordered rule table. Multiple rules may match one prompt; classifyPrompt
+// returns every match in declaration order. Patterns are anchored on word
+// boundaries to avoid substring false-positives (e.g. "warm" ≠ "rm").
+const STEERING_RULES: Array<SteeringRule & { tag: SteeringTag }> = [
+  {
+    tag: "debugging",
+    pattern:
+      /\b(bugs?|broken|failing|fails?|errors?|crash\w*|regress\w*|debug\w*|not working|doesn'?t work|stack ?trace)\b/i,
+    snippet:
+      "Debugging something? If so, change one thing at a time and reproduce the failure before fixing — keep the correction surgical rather than a rewrite.",
+  },
+  {
+    tag: "destructive",
+    pattern:
+      /\b(delete|remove|drop|rm\s+-rf|force[- ]push|reset\s+--hard|wipe|truncate|prune)\b/i,
+    snippet:
+      "About to delete, force-push, or drop something irreversible? If so, list what's affected and confirm before acting — and if what you find contradicts how it was described, surface that first.",
+  },
+  {
+    tag: "refactor",
+    pattern:
+      /\b(refactor\w*|clean\s?up|simplif\w*|reorganiz\w*|restructur\w*|dead code|tech debt)\b/i,
+    snippet:
+      "Refactoring or cleaning up? If so, prefer first-principles simplification over adding new layers, and keep the change scoped to what was asked — flag dead code rather than silently rewriting neighboring files.",
+  },
+  {
+    tag: "planning",
+    pattern: /\b(plans?|planning|designs?|designing|architect\w*|roadmap)\b/i,
+    snippet:
+      "Planning or designing something? If you were asked to plan, present the approach and stop — wait for an explicit go-ahead before writing any code.",
+  },
+  {
+    tag: "testing",
+    pattern: /\b(tests?|testing|coverage|assertions?|vacuous)\b/i,
+    snippet:
+      "Adding or changing a test? Prove it isn't vacuous — make it fail first for the right reason, then restore it, so a green run actually means something.",
+  },
+  {
+    tag: "committing",
+    pattern: /\b(commits?|committing|pull requests?|cherry-pick|rebase|PR)\b|git push/i,
+    snippet:
+      "About to commit, push, or open a PR? Only do it if it was asked, and keep the commit scoped to exactly what was requested.",
+  },
+  {
+    tag: "secrets",
+    pattern: /\b(secrets?|api[\s-]?keys?|tokens?|passwords?|credentials?)\b|\.env\b/i,
+    snippet:
+      "Handling secrets, API keys, or credentials? Never hardcode them in source or commit them — keep them in env or private config, and never echo them into logs or output.",
+  },
+];
+
+const MAX_STEERING_BYTES = 1000;
+
+/** Merge shipped defaults with the user's pal-settings.json extension:
+ *  `steering.disable` removes built-ins by tag; `steering.rules` appends personal
+ *  rules. Malformed user entries (missing field or bad regex) are skipped, never
+ *  thrown — a broken personal rule must not disable steering for everyone. */
+function effectiveRules(): SteeringRule[] {
+  const cfg = raw().steering ?? {};
+  const disabled = new Set(cfg.disable ?? []);
+  const rules: SteeringRule[] = STEERING_RULES.filter((r) => !disabled.has(r.tag));
+  for (const u of cfg.rules ?? []) {
+    if (!u?.tag || !u?.pattern || !u?.snippet) continue;
+    let pattern: RegExp;
+    try {
+      pattern = new RegExp(u.pattern, "i");
+    } catch {
+      continue; // fail-open: skip malformed regex
+    }
+    rules.push({ tag: u.tag, pattern, snippet: u.snippet });
+  }
+  return rules;
+}
+
+/** Match a prompt against the effective rule set, one hit per tag, in order. */
+function matchRules(text: string): SteeringRule[] {
+  if (!text?.trim()) return [];
+  const matched: SteeringRule[] = [];
+  const seen = new Set<string>();
+  for (const rule of effectiveRules()) {
+    if (!seen.has(rule.tag) && rule.pattern.test(text)) {
+      seen.add(rule.tag);
+      matched.push(rule);
+    }
+  }
+  return matched;
+}
+
+/** Deterministically classify a prompt into steering tags. Pure, fail-open. */
+export function classifyPrompt(text: string): string[] {
+  return matchRules(text).map((r) => r.tag);
+}
+
+/** Build the steering <system-reminder> for a prompt, or null if nothing matches. */
+export function getSteeringReminder(prompt: string): string | null {
+  if (!isEnabled("contextualSteering")) return null;
+
+  let matched: SteeringRule[];
+  try {
+    matched = matchRules(prompt);
+  } catch {
+    return null; // fail-open: never block a prompt on a classifier error
+  }
+  if (matched.length === 0) return null;
+
+  const lines: string[] = [];
+  let budget = MAX_STEERING_BYTES;
+  for (const rule of matched) {
+    const line = `- ${rule.snippet}`;
+    const cost = Buffer.byteLength(line);
+    if (cost > budget) break; // byte-cap: drop the overflow tail, keep top matches
+    lines.push(line);
+    budget -= cost;
+  }
+  if (lines.length === 0) return null;
+
+  const inner = [
+    "Heuristic self-checks auto-matched on your prompt — they may be off; ignore any that don't apply:",
+    ...lines,
+  ];
+  // Dual-live test period: co-locate the report instruction with the trigger so
+  // it fires reliably across sessions/compaction. Flip steeringTestReport off to end it.
+  if (isEnabled("steeringTestReport")) {
+    inner.push(
+      "— Test period: assistant, briefly note to the user that a steering self-check fired, and which one(s)."
+    );
+  }
+  return ["<system-reminder>", ...inner, "</system-reminder>"].join("\n");
+}

package/src/hooks/lib/text-similarity.ts

@@ -155,3 +155,21 @@ export function similarity(a: string, b: string): number {
 
   return (2 * intersection) / (ka.size + kb.size);
 }
+
+/**
+ * Asymmetric containment: fraction of `query` keywords also present in `target`.
+ * Unlike Dice, it is not penalized by `target` being much longer, so a short
+ * keyword query can still match a full-sentence statement.
+ */
+export function containment(query: string, target: string): number {
+  const q = extractKeywords(query);
+  const t = extractKeywords(target);
+  if (q.size === 0 || t.size === 0) return 0;
+
+  let intersection = 0;
+  for (const w of q) {
+    if (t.has(w)) intersection++;
+  }
+
+  return intersection / q.size;
+}

package/src/hooks/lib/which.ts

@@ -0,0 +1,41 @@
+/**
+ * Cross-platform binary resolution — a manual PATH walk.
+ *
+ * Deliberately avoids Bun.which / a `which` subprocess because:
+ * 1. Ubuntu 24.04 dropped the `which` binary entirely.
+ * 2. Windows has no `which` at all.
+ * 3. Bun.which snapshots PATH at startup and ignores mid-test mutations.
+ * 4. Bun.spawn on Windows is inconsistent at resolving PATHEXT for bare
+ *    names — passing the full `.cmd`/`.exe` path bypasses that fragility.
+ */
+
+import { accessSync, constants, existsSync } from "node:fs";
+import { delimiter, resolve as resolvePath } from "node:path";
+
+/** Resolve a binary on PATH to its full absolute path, or null if absent. */
+export function findBinaryOnPath(name: string): string | null {
+  const PATH = process.env.PATH;
+  if (!PATH) return null;
+  const exts =
+    process.platform === "win32"
+      ? (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";")
+      : [""];
+  for (const dir of PATH.split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const candidate = resolvePath(dir, name + ext);
+      try {
+        if (process.platform === "win32") {
+          // Windows has no executable bit — existence in PATHEXT is enough.
+          if (existsSync(candidate)) return candidate;
+        } else {
+          accessSync(candidate, constants.X_OK);
+          return candidate;
+        }
+      } catch {
+        /* not here — try next */
+      }
+    }
+  }
+  return null;
+}

package/src/targets/lib.ts

@@ -166,7 +166,7 @@ export function mergeSettings(existing: Settings, template: Settings): Settings
     }
   }
 
-  // Merge permissions.allow (deduplicate)
+  // Merge permissions.allow (deduplicate), then drop deprecated entries.
   if (template.permissions?.allow) {
     result.permissions ??= {};
     result.permissions.allow ??= [];
@@ -176,6 +176,14 @@ export function mergeSettings(existing: Settings, template: Settings): Settings
       }
     }
   }
+  // Strip ineffective Grep(...)/Glob(...) rules left by older templates. Claude Code
+  // governs Grep/Glob via Read(...) rules, so a path-scoped Grep()/Glob() entry never
+  // matches and Claude Code warns about it on every prompt. Read(//*) already covers them.
+  if (result.permissions?.allow) {
+    result.permissions.allow = result.permissions.allow.filter(
+      (perm) => !isIneffectiveFileToolRule(perm)
+    );
+  }
 
   // Merge skillOverrides (object with skill name keys, add if not present)
   if (template.skillOverrides && typeof template.skillOverrides === "object") {
@@ -455,6 +463,15 @@ function canonicalPalCmd(cmd: string): string {
   return withoutEnv;
 }
 
+/**
+ * True for path-scoped Grep()/Glob() allow rules, which Claude Code cannot honor —
+ * it resolves Grep/Glob permission through Read(...) rules, so these never match and
+ * trigger a warning on every prompt. Bare "Grep"/"Glob" tool allows are left intact.
+ */
+function isIneffectiveFileToolRule(perm: string): boolean {
+  return /^(?:Grep|Glob)\(/.test(perm);
+}
+
 export function loadCodexHooksTemplate(
   templatePath: string,
   pkgRoot: string

package/src/targets/opencode/plugin.ts

@@ -5,6 +5,7 @@
  * This plugin just wires opencode's hook API to those shared functions.
  */
 
+import { spawnSync } from "node:child_process";
 import { resolve } from "node:path";
 import type { Plugin, PluginInput } from "@opencode-ai/plugin";
 
@@ -30,6 +31,27 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
     await lib<typeof import("../../hooks/lib/context")>("context.ts");
   const { checkBashCommand, checkFilePath } =
     await lib<typeof import("../../hooks/lib/security")>("security.ts");
+  const { findBinaryOnPath } =
+    await lib<typeof import("../../hooks/lib/which")>("which.ts");
+
+  // rtk output compression — PAL gates on presence, rtk owns the rewrite.
+  // `rtk hook check <cmd>` prints the rewritten command (exit 0) or nothing
+  // (exit 1) when a command isn't worth wrapping. Fail-open: absent rtk or any
+  // error leaves the command untouched.
+  const rtkBin = findBinaryOnPath("rtk");
+  const rtkRewrite = (cmd: string): string | null => {
+    if (!rtkBin || !cmd) return null;
+    try {
+      const r = spawnSync(rtkBin, ["hook", "check", cmd], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      });
+      const out = r.status === 0 ? (r.stdout ?? "").trim() : "";
+      return out && out !== cmd ? out : null;
+    } catch {
+      return null;
+    }
+  };
   const { logDebug, logError, logPromptSnapshot } =
     await lib<typeof import("../../hooks/lib/log")>("log.ts");
 
@@ -44,6 +66,8 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
   const { getRetrievalReminder } = await lib<
     typeof import("../../hooks/handlers/inject-retrieval")
   >("../handlers/inject-retrieval.ts");
+  const { getSteeringReminder } =
+    await lib<typeof import("../../hooks/lib/steering")>("steering.ts");
 
   function partsToText(parts: Array<Record<string, unknown>>): string {
     return parts
@@ -140,20 +164,22 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
       if (!text.trim()) return;
 
       const retrieval = await getRetrievalReminder(text);
-      logPromptSnapshot(text, retrieval);
+      const steering = getSteeringReminder(text);
+      const injectedText = [steering, retrieval].filter(Boolean).join("\n\n");
+      logPromptSnapshot(text, injectedText || null);
 
       await Promise.allSettled([
         captureRating(text, input.sessionID),
         captureSessionName(text, input.sessionID),
       ]);
 
-      if (retrieval) {
+      if (injectedText) {
         const injected = {
-          id: `pal-retrieval-${Date.now()}`,
+          id: `pal-promptctx-${Date.now()}`,
           sessionID: input.sessionID,
           messageID: input.messageID ?? `pal-msg-${Date.now()}`,
           type: "text" as const,
-          text: retrieval,
+          text: injectedText,
           synthetic: true,
         };
         output.parts = [injected, ...(output.parts ?? [])];
@@ -176,6 +202,11 @@ const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
         if (reason) {
           throw new Error(`PAL Security: Blocked — ${reason}`);
         }
+        const rewritten = rtkRewrite(cmd);
+        if (rewritten) {
+          if (typeof output.args === "string") output.args = rewritten;
+          else (output.args as Record<string, unknown>).command = rewritten;
+        }
       }
 
       if (toolName === "write" || toolName === "edit" || toolName === "patch") {

package/src/tools/agent/algorithm-reflect.ts

@@ -15,6 +15,7 @@
 import { appendFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { paths } from "../../hooks/lib/paths";
+import { emit } from "../lib/emit";
 
 // ── Types ──
 
@@ -121,7 +122,7 @@ Output: algorithm-reflections.jsonl in memory/learning/reflections/
   };
 
   const result = appendReflection(reflection);
-  console.log(JSON.stringify(result, null, 2));
+  emit.ok(result.message);
 }
 
 if (import.meta.main) run();

package/src/tools/agent/handoff-note.ts

@@ -14,6 +14,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { ensureDir, paths } from "../../hooks/lib/paths";
+import { emit } from "../lib/emit";
 
 interface HandoffEntry {
   timestamp: string;
@@ -102,7 +103,7 @@ Output: writes to memory/state/last-handoff.json keyed by cwd
       values.text || "",
       true
     );
-    console.log(JSON.stringify(result, null, 2));
+    emit.ok(result.message);
     process.exit(0);
   }
 
@@ -112,7 +113,7 @@ Output: writes to memory/state/last-handoff.json keyed by cwd
   }
 
   const result = writeHandoffNote(process.cwd(), values.title, values.text, false);
-  console.log(JSON.stringify(result, null, 2));
+  emit.ok(result.message);
 }
 
 if (import.meta.main) run();

package/src/tools/agent/project.ts

@@ -123,10 +123,24 @@ function cmdCreate(args: string[]): void {
 
 // ── resume ────────────────────────────────────────────────────────
 
+// resume returns a lean orientation view: all narrative sections, but the
+// Criteria/Changelog blobs collapse to open-ISC titles + counts. Full ISC text
+// is fetched on demand via show-isc / list-isc, so resume stays cheap on
+// projects carrying a large backlog.
 function cmdResume(args: string[]): void {
   const name = args[0];
   if (!name) fail("Usage: resume <name>");
-  ok({ project: requireProject(name) });
+  const { criteria, changelog, ...project } = requireProject(name);
+  const iscs = parseIscs(criteria ?? "");
+  const openIscs = iscs.filter((i) => !i.checked);
+  const done = iscs.filter((i) => i.checked).length + parseIscs(changelog ?? "").length;
+  ok({
+    project: {
+      ...project,
+      open_iscs: openIscs.map((i) => ({ id: i.id, title: iscTitle(i.text) })),
+      isc_summary: { open: openIscs.length, done },
+    },
+  });
 }
 
 // ── status transitions ────────────────────────────────────────────
@@ -351,6 +365,14 @@ function parseIscs(criteria: string): Isc[] {
   return out;
 }
 
+// Collapse a full ISC line to a glanceable title for resume: cut at the first
+// clause boundary, then hard-cap length. Full text stays reachable via show-isc.
+function iscTitle(text: string): string {
+  const boundary = text.search(/; | — | \(|\. /);
+  const clause = (boundary > 0 ? text.slice(0, boundary) : text).trim();
+  return clause.length > 80 ? `${clause.slice(0, 79).trimEnd()}…` : clause;
+}
+
 // Scans Criteria AND Changelog so an archived id can never be handed out again.
 function nextIscId(p: ProjectProgress): number {
   const ids = [...parseIscs(p.criteria ?? ""), ...parseIscs(p.changelog ?? "")].map(
@@ -493,6 +515,20 @@ function cmdListIsc(args: string[]): void {
   });
 }
 
+// show-isc prints one ISC's full text on demand — the "detail" counterpart to
+// resume's titles. Scans Criteria (open + not-yet-archived) and Changelog.
+function cmdShowIsc(args: string[]): void {
+  const name = args[0];
+  const id = Number(args[1]);
+  if (!name || !Number.isInteger(id) || id < 1) fail("Usage: show-isc <name> <id>");
+  const p = requireProject(name);
+  const isc = [...parseIscs(p.criteria ?? ""), ...parseIscs(p.changelog ?? "")].find(
+    (i) => i.id === id
+  );
+  if (!isc) fail(`ISC-${id} not found in project "${name}".`);
+  ok({ name, id: isc.id, status: isc.checked ? "closed" : "open", text: isc.text });
+}
+
 // Backfill: sweep any done ISCs still sitting in Criteria (legacy projects, or
 // completions from before archive-on-complete) into the Changelog in one pass.
 function cmdPruneIsc(args: string[]): void {
@@ -576,7 +612,7 @@ function help(): void {
 Commands:
   list                                          show all registered projects
   create [name] [--path PATH] [--objectives X]  register a project
-  resume <name>                                 print full project ISA
+  resume <name>                                 print lean project view (open-ISC titles; full text via show-isc)
   complete <name>                               mark complete
   archive <name>                                mark archived
   pause <name> | unpause <name>                 toggle paused/active
@@ -593,6 +629,7 @@ Commands:
   complete-isc <name> <id>                      mark ISC-N as done
   reopen-isc <name> <id>                        reopen ISC-N (mark not done)
   list-isc <name> [--all | --closed]           list open ISCs (default); --all or --closed for done
+  show-isc <name> <id>                          print one ISC's full text
   prune-isc <name>                              archive done ISCs from Criteria into the Changelog
   isa-init <name>                               mark project as ISA-initialized
   scaffold-task-isa <title>                     create a one-shot task ISA in memory/work/
@@ -685,6 +722,9 @@ function run(): void {
     case "list-isc":
       cmdListIsc(rest);
       return;
+    case "show-isc":
+      cmdShowIsc(rest);
+      return;
     case "prune-isc":
       cmdPruneIsc(rest);
       return;

package/src/tools/agent/relationship-note.ts

@@ -6,8 +6,8 @@
  * the user (O, W) and session diary entries (--b).
  *
  * Usage:
- *   bun ~/.pal/tools/relationship-note.ts --o "Rico prefers X" --confidence 0.80
- *   bun ~/.pal/tools/relationship-note.ts --w "Rico is building X in TypeScript"
+ *   bun ~/.pal/tools/relationship-note.ts --o "User prefers X" --confidence 0.80
+ *   bun ~/.pal/tools/relationship-note.ts --w "User is building X in TypeScript"
  *   bun ~/.pal/tools/relationship-note.ts --b "Debugged the cache split logic"
  *
  * Note types:
@@ -18,6 +18,7 @@
 
 import { parseArgs } from "node:util";
 import { appendNotes } from "../../hooks/lib/relationship";
+import { emit } from "../lib/emit";
 
 function run() {
   const { values } = parseArgs({
@@ -36,8 +37,8 @@ function run() {
 RelationshipNote — Append W/O/Session entries to today's relationship log
 
 Usage:
-  bun ~/.pal/tools/relationship-note.ts --o "Rico prefers X" --confidence 0.80
-  bun ~/.pal/tools/relationship-note.ts --w "Rico is building X in TypeScript"
+  bun ~/.pal/tools/relationship-note.ts --o "User prefers X" --confidence 0.80
+  bun ~/.pal/tools/relationship-note.ts --w "User is building X in TypeScript"
   bun ~/.pal/tools/relationship-note.ts --b "Debugged the cache split logic"
 
 Flags:
@@ -83,13 +84,7 @@ Output: appends to memory/relationship/YYYY-MM/YYYY-MM-DD.md
 
   appendNotes(notes);
 
-  console.log(
-    JSON.stringify(
-      { success: true, message: "Relationship note written", count: notes.length },
-      null,
-      2
-    )
-  );
+  emit.ok(`Relationship note written (${notes.length})`);
 }
 
 if (import.meta.main) run();

package/src/tools/agent/thread.ts

@@ -15,6 +15,7 @@ import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { ensureDir, paths } from "../../hooks/lib/paths";
+import { emit } from "../lib/emit";
 
 // ── Types ──
 
@@ -137,13 +138,7 @@ Usage:
       process.exit(1);
     }
     const thread = addThread(values.title, values.context ?? "");
-    console.log(
-      JSON.stringify(
-        { success: true, id: thread.id, message: `Thread added: ${thread.title}` },
-        null,
-        2
-      )
-    );
+    emit.data(`Added with id ${thread.id}`);
   }
 
   if (cmd === "resolve") {
@@ -151,12 +146,14 @@ Usage:
       console.error("--id required");
       process.exit(1);
     }
-    console.log(JSON.stringify(resolveThread(values.id), null, 2));
+    const resolved = resolveThread(values.id);
+    if (resolved.success) emit.ok(resolved.message ?? "Thread resolved");
+    else emit.data(JSON.stringify(resolved, null, 2));
   }
 
   if (cmd === "list") {
     const threads = listThreads(values.all ?? false);
-    console.log(JSON.stringify({ count: threads.length, threads }, null, 2));
+    emit.data(JSON.stringify({ count: threads.length, threads }, null, 2));
   }
 }
 

package/src/tools/agent/wisdom-frame.ts

@@ -19,6 +19,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { paths } from "../../hooks/lib/paths";
+import { emit } from "../lib/emit";
 
 // ── Types ──
 
@@ -233,7 +234,7 @@ Examples:
 
   const cliType = (values.type || "evolution") as ObservationType;
   const result = updateFrame(values.domain, values.observation, cliType);
-  console.log(JSON.stringify(result, null, 2));
+  emit.ok(result.message);
 }
 
 if (import.meta.main) run();

package/src/tools/lib/emit.ts

@@ -0,0 +1,31 @@
+/**
+ * Output convention for agent-invoked CLI tools: quiet on success, full on
+ * failure. The agent captures tool output over a pipe (non-TTY), where success
+ * confirmations are pure noise that costs context tokens; a human at a TTY wants
+ * them. Gate on the TTY signal, with PAL_VERBOSE / PAL_QUIET as explicit overrides.
+ *
+ *   data()  requested payload — ALWAYS emitted (list output, reports, results)
+ *   ok()    success confirmation / progress — only at a TTY or under PAL_VERBOSE
+ *
+ * Errors stay on console.error (stderr) + a non-zero exit — always surfaced,
+ * independent of this gate.
+ */
+
+function isVerbose(): boolean {
+  if (process.env.PAL_QUIET === "1") return false;
+  if (process.env.PAL_VERBOSE === "1") return true;
+  return Boolean(process.stdout.isTTY);
+}
+
+function line(stream: { write: (s: string) => void }, text: string): void {
+  stream.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+
+export const emit = {
+  data(text: string): void {
+    line(process.stdout, text);
+  },
+  ok(text: string): void {
+    if (isVerbose()) line(process.stdout, text);
+  },
+};