@oh-my-pi/pi-coding-agent 17.2.10 → 17.2.12

package/dist/types/secrets/message-transform.d.ts

@@ -0,0 +1,40 @@
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { AssistantMessage, Context, Message } from "@oh-my-pi/pi-ai";
+import type { SessionContext } from "../session/session-context.js";
+import type { SecretObfuscator } from "./obfuscator.js";
+/**
+ * Restore secret placeholders for local display. Only message kinds the model
+ * itself authored from obfuscated context carry placeholders — assistant
+ * content and the LLM-written branch/compaction summaries. User, developer, and
+ * tool-result messages are persisted with their literal text, so operator-authored
+ * placeholder-shaped text must survive untouched; those roles are never walked.
+ */
+export declare function deobfuscateSessionContext(sessionContext: SessionContext, obfuscator: SecretObfuscator | undefined): SessionContext;
+export declare function deobfuscateAgentMessages(obfuscator: SecretObfuscator, messages: AgentMessage[]): AgentMessage[];
+/**
+ * Restore placeholders in assistant content: visible text and tool-call
+ * arguments/intent/rawBlock. Thinking and signatures are opaque
+ * provider-replay/hidden-reasoning data and pass through byte-identical.
+ */
+export declare function deobfuscateAssistantContent(obfuscator: SecretObfuscator, content: AssistantMessage["content"]): AssistantMessage["content"];
+/**
+ * Restore placeholders inside a tool call's arguments. Arguments are arbitrary
+ * model-authored JSON, so tool-call arguments are the ONLY place a recursive
+ * JSON walk runs.
+ */
+export declare function deobfuscateToolArguments(obfuscator: SecretObfuscator, args: Record<string, unknown>): Record<string, unknown>;
+/** Redact secrets inside a tool call's arguments (same JSON-walk exception as {@link deobfuscateToolArguments}). */
+export declare function obfuscateToolArguments(obfuscator: SecretObfuscator, args: Record<string, unknown>, sharedRegexSecretValues?: ReadonlySet<string>): Record<string, unknown>;
+/**
+ * Redact secrets from outbound messages. User messages, tool results, and
+ * user-authored developer messages (e.g. `@file` mentions) are obfuscated.
+ * Assistant replay content is re-obfuscated too, because session restoration
+ * expands keyed placeholders locally before the next provider request. Inline
+ * image bytes are never walked.
+ */
+export declare function obfuscateMessages(obfuscator: SecretObfuscator, messages: Message[]): Message[];
+/**
+ * Redact outbound provider context. Only conversation messages are rewritten;
+ * the static system prompt and tool schemas pass through unchanged.
+ */
+export declare function obfuscateProviderContext(obfuscator: SecretObfuscator | undefined, context: Context): Context;

package/dist/types/secrets/obfuscator.d.ts

@@ -1,6 +1,3 @@
-import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
-import type { AssistantMessage, Context, Message } from "@oh-my-pi/pi-ai";
-import type { SessionContext } from "../session/session-context.js";
 export interface SecretEntry {
     type: "plain" | "regex";
     content: string;
@@ -15,75 +12,6 @@ export type JsonValue = string | number | boolean | null | JsonValue[] | {
 export type JsonRecord = {
     [key: string]: JsonValue | undefined;
 };
-/**
- * Whether a default (no custom `replacement`) replace-mode regex can never
- * safely redact a 1-2 char match: `findNonMatchingReplacement`'s bounded
- * search — the same search `#generateRegexReplacement` runs at match time —
- * finds no candidate the regex fails to re-match. This holds independent of
- * any actual per-install key: the search already exhausts every character in
- * `REPLACEMENT_CHARS` (the alphabet `buildKeyedReplacementRun` draws its
- * fallback marker from) plus punctuation and whitespace, so if none of those
- * escape the regex, no key-derived marker drawn from the same alphabet can
- * either — the marker is guaranteed to re-match too, making every such match
- * unresolvable: the fallback could only ever emit the raw matched text
- * unchanged. Probed with a value (`"\0".repeat(length)`) the bounded search
- * never treats as a real candidate, so the result depends only on the
- * regex's own matching behavior, not on this specific probe.
- */
-export declare function regexHasUnresolvableShortMatchFallback(regex: RegExp): boolean;
-export declare const MIN_OBFUSCATE_SECRET_LEN = 8;
-/** Normalize a friendly name into the model-visible placeholder prefix. */
-export declare function sanitizeSecretFriendlyName(name: string): string | undefined;
-/**
- * Whether an entry needs the persisted placeholder key: either because it can
- * produce a reversible (keyed) obfuscate-mode placeholder, or because a default
- * (no custom `replacement`) replace-mode regex can reach
- * `#generateRegexReplacement`'s key-derived idempotent fallback marker (see
- * `#generateReplacement`) when every same-length candidate re-matches a
- * pathological match-everything config (e.g. `[\s\S]{8}`). That fallback depends
- * on the persisted per-install key — not just length — to stay a fixed point
- * across a process restart; without a persisted key, a fresh install falls back
- * to a process-random key (`defaultPlaceholderKey()`), so the fallback marker
- * would churn across restarts even though the algorithm itself is stable. A
- * regex WITH a custom `replacement` never reaches that fallback (it always emits
- * the literal configured string), and a plain replace secret's replacement is
- * pure content-hash (`#generateSecretReplacement`), so neither needs the key.
- * Short plain obfuscate entries are toned down (never placeheld), so they must
- * NOT force key creation: otherwise a `secret-placeholder.key` file is written
- * and persisted for a config that ends up with no active secrets, leaving the
- * key readable via a tool and reusable for later placeholders.
- */
-export declare function secretEntryNeedsPlaceholderKey(entry: SecretEntry): boolean;
-/**
- * Whether a SET of entries needs the persisted placeholder key. `obfuscate()`
- * applies plain replace-mode mappings before the plain-obfuscate pass, so a plain
- * obfuscate entry only emits a reversible (keyed) placeholder when its content can
- * still appear AFTER the replace phase. When no obfuscate entry can ever produce a
- * placeholder, the persisted key must NOT be required/created — otherwise an
- * effectively replace-only secret set still writes `secret-placeholder.key` and
- * fails startup when the agent config dir is unwritable.
- *
- * The decision models the replace phase as the obfuscator actually runs it:
- * replace mappings are content-keyed (later duplicate wins) and applied in
- * descending content-length order; for a fresh probe (no prior placeholders) that
- * phase is plain sequential substring replacement. A plain obfuscate entry needs
- * the key when its content survives that simulated phase (direct typing) OR when
- * any effective replacement can form the content via tiling — a substring,
- * wholesale superstring, or prefix/suffix border that joins with surrounding
- * passthrough bytes (see `replacementCanFormContent`). This covers direct
- * shadowing (`SECRET -> safe`), reintroduction, duplicate ordering, transitive
- * chains, and context-joined fragments uniformly. Default (omitted) replacements
- * are deterministic, length-preserving, and distinct, so a same-content shadow
- * with no other interacting replacement stays key-free.
- * Replacement outputs are themselves rewritten by every later (shorter-content)
- * replacement before the plain-obfuscate pass sees them, so a fragment that a
- * subsequent replacement erases (`AA -> SEC` then `S -> X` turns every `SEC` into
- * `XEC`) no longer forces the key. Surrounding bytes stay modeled as arbitrary
- * passthrough, so testing the surviving fragment only drops false positives and
- * never under-approximates a real key need.
- */
-export declare function secretEntriesNeedPlaceholderKey(entries: SecretEntry[]): boolean;
-export declare function stripPendingSecretPlaceholderSuffix(text: string): string;
 export declare class SecretObfuscator {
     #private;
     constructor(entries: SecretEntry[], key?: string | (() => string));
@@ -99,39 +27,3 @@ export declare class SecretObfuscator {
     collectRegexSecretValuesForObfuscation(text: string): Set<string>;
     stripUnsafeFriendlyPlaceholderPrefixes(text: string, sharedRegexSecretValues: ReadonlySet<string>): string;
 }
-/**
- * Restore secret placeholders for local display. Only message kinds the model
- * itself authored from obfuscated context carry placeholders — assistant
- * content and the LLM-written branch/compaction summaries. User, developer, and
- * tool-result messages are persisted with their literal text, so operator-authored
- * placeholder-shaped text must survive untouched; those roles are never walked.
- */
-export declare function deobfuscateSessionContext(sessionContext: SessionContext, obfuscator: SecretObfuscator | undefined): SessionContext;
-export declare function deobfuscateAgentMessages(obfuscator: SecretObfuscator, messages: AgentMessage[]): AgentMessage[];
-/**
- * Restore placeholders in assistant content: visible text and tool-call
- * arguments/intent/rawBlock. Thinking and signatures are opaque
- * provider-replay/hidden-reasoning data and pass through byte-identical.
- */
-export declare function deobfuscateAssistantContent(obfuscator: SecretObfuscator, content: AssistantMessage["content"]): AssistantMessage["content"];
-/**
- * Restore placeholders inside a tool call's arguments. Arguments are arbitrary
- * model-authored JSON, so tool-call arguments are the ONLY place a recursive
- * JSON walk runs.
- */
-export declare function deobfuscateToolArguments(obfuscator: SecretObfuscator, args: Record<string, unknown>): Record<string, unknown>;
-/** Redact secrets inside a tool call's arguments (same JSON-walk exception as {@link deobfuscateToolArguments}). */
-export declare function obfuscateToolArguments(obfuscator: SecretObfuscator, args: Record<string, unknown>, sharedRegexSecretValues?: ReadonlySet<string>): Record<string, unknown>;
-/**
- * Redact secrets from outbound messages. User messages, tool results, and
- * user-authored developer messages (e.g. `@file` mentions) are obfuscated.
- * Assistant replay content is re-obfuscated too, because session restoration
- * expands keyed placeholders locally before the next provider request. Inline
- * image bytes are never walked.
- */
-export declare function obfuscateMessages(obfuscator: SecretObfuscator, messages: Message[]): Message[];
-/**
- * Redact outbound provider context. Only conversation messages are rewritten;
- * the static system prompt and tool schemas pass through unchanged.
- */
-export declare function obfuscateProviderContext(obfuscator: SecretObfuscator | undefined, context: Context): Context;

package/dist/types/secrets/placeholder-scan.d.ts

@@ -0,0 +1,95 @@
+import type { JsonValue, SecretObfuscator } from "./obfuscator.js";
+import { type RegexScanSegment, type ReplaceRegexScan } from "./placeholder.js";
+export declare function transformOutsidePlaceholdersTracked(text: string, origin: string, shouldSkipPlaceholder: (placeholder: string) => boolean, transform: (chunk: string) => string, preservePlaceholder?: (placeholder: string) => string): {
+    text: string;
+    origin: string;
+};
+export declare function trailingOutsidePreservedPlaceholderChunk(text: string, shouldPreservePlaceholder: (placeholder: string) => boolean): string;
+export declare function buildReplaceRegexScan(text: string, ranges: ReadonlyArray<{
+    start: number;
+    end: number;
+}>, deobfuscateMap: ReadonlyMap<string, {
+    secret: string;
+    recursive: boolean;
+}>): ReplaceRegexScan;
+export declare function mapReplaceRegexMatch(segments: ReadonlyArray<RegexScanSegment>, scanStart: number, scanEnd: number): {
+    start: number;
+    end: number;
+    recursive: boolean;
+    preserveGeneratedPlaceholders: boolean;
+    partialPlaceholderCut: boolean;
+    cutResumeIndex: number;
+    firstPlaceholderScanStart: number;
+};
+/**
+ * Extend a scan-space resume position past a consecutive run of generated
+ * placeholder segments starting exactly at it, with no raw gap in between. A
+ * cut-resolution resume point that happens to land precisely on the START of
+ * ANOTHER placeholder must not stop there and hand it to a fresh `regex.exec`
+ * attempt — the same content, scanned as an opaque adjacent placeholder run,
+ * must resolve identically whether the run's LEADING member is still raw text
+ * (this call is about to placeholder it) or is ALREADY a placeholder from a
+ * prior call or an earlier pass of this same call. Without this, a bounded
+ * regex whose reach spans two adjacent secrets plus trailing spillover bytes
+ * (e.g. `[A-Z]{9}` over `ABCDEFGH` + `SECRETUV` + `A`) resolves the leading
+ * secret as its own independent redaction on the FIRST obfuscate() call (a
+ * genuinely raw prefix gets its own match, then the discard for the rest
+ * resumes right after it), but on a LATER call — once that prefix is itself a
+ * placeholder — the very first match attempt starts already inside the
+ * placeholder run, cannot be prefix-narrowed at all, and its discard resume
+ * point lands mid-run instead of past it, exposing a shorter tail (`SECRETUV`
+ * + `A`) to a clean, un-cut match the first call never attempted. Chaining the
+ * resume point through every immediately-adjacent placeholder makes both
+ * calls land on the exact same next scan position.
+ */
+export declare function extendPastAdjacentPlaceholders(segments: ReadonlyArray<RegexScanSegment>, index: number): number;
+export declare function redactWithFixedReplacementOutsidePlaceholders(text: string, origin: string, replacement: string, shouldPreservePlaceholder: (placeholder: string) => boolean): {
+    text: string;
+    origin: string;
+};
+export declare function deobfuscateGeneratedPlaceholderRanges(text: string, start: number, end: number, ranges: ReadonlyArray<{
+    start: number;
+    end: number;
+}>, deobfuscateMap: ReadonlyMap<string, {
+    secret: string;
+    recursive: boolean;
+}>): {
+    text: string;
+    recursive: boolean;
+};
+export declare function placeholderInnerText(text: string, start: number, end: number, ranges: ReadonlyArray<{
+    start: number;
+    end: number;
+}>, deobfuscateMap: ReadonlyMap<string, {
+    secret: string;
+    recursive: boolean;
+}>): string;
+export declare function textOutsidePlaceholderRanges(text: string, start: number, end: number, ranges: ReadonlyArray<{
+    start: number;
+    end: number;
+}>): string;
+export declare function outsidePlaceholderRangesAnyIndependentlyMatch(text: string, scanText: string, segments: ReadonlyArray<RegexScanSegment>, start: number, end: number, ranges: ReadonlyArray<{
+    start: number;
+    end: number;
+}>, regex: RegExp): boolean;
+export declare function firstOutsidePlaceholderRange(start: number, end: number, ranges: ReadonlyArray<{
+    start: number;
+    end: number;
+}>): {
+    start: number;
+    end: number;
+} | undefined;
+export declare function countOutsidePlaceholderRanges(start: number, end: number, ranges: ReadonlyArray<{
+    start: number;
+    end: number;
+}>): number;
+export declare function replaceRange(text: string, start: number, end: number, replacement: string): string;
+/** Deep-walk an object, transforming all string values. */
+export declare function deepWalkStrings<T>(obj: T, transform: (s: string) => string): T;
+export declare function collectJsonRegexSecretValues(obfuscator: SecretObfuscator, value: JsonValue): Set<string>;
+/**
+ * Map every string in arbitrary JSON. Used ONLY for tool-call arguments, whose
+ * shape is model-authored and not known ahead of time. No other caller may walk
+ * untyped data: every message/content path is handled by a typed transformer.
+ */
+export declare function mapJsonStrings(value: JsonValue, fn: (s: string) => string): JsonValue;

package/dist/types/secrets/placeholder.d.ts

@@ -0,0 +1,94 @@
+import type { SecretEntry } from "./obfuscator.js";
+export declare const MIN_OBFUSCATE_SECRET_LEN = 8;
+export declare function defaultPlaceholderKey(): string;
+type PlaceholderCaseHint = "U" | "L" | "C" | "M";
+/** Normalize a friendly name into the model-visible placeholder prefix. */
+export declare function sanitizeSecretFriendlyName(name: string): string | undefined;
+/**
+ * Normalize a secret value into the same alnum-only, uppercased shape a
+ * friendly-name label or placeholder prefix is sanitized into, so comparing a
+ * raw (possibly lowercase/punctuated) secret value against already-sanitized,
+ * model-visible text does not miss a case- or separator-only variant. Unlike
+ * `sanitizeSecretFriendlyName` this never truncates and never signals "empty"
+ * via `undefined` — callers already guard on `.length > 0` before comparing.
+ */
+export declare function sanitizeForCollisionCheck(value: string): string;
+export declare function sanitizedLabelCollidesWithSecret(sanitizedLabel: string, sanitizedSecret: string): boolean;
+/**
+ * Whether an entry needs the persisted placeholder key: either because it can
+ * produce a reversible (keyed) obfuscate-mode placeholder, or because a default
+ * (no custom `replacement`) replace-mode regex can reach
+ * `#generateRegexReplacement`'s key-derived idempotent fallback marker (see
+ * `#generateReplacement`) when every same-length candidate re-matches a
+ * pathological match-everything config (e.g. `[\s\S]{8}`). That fallback depends
+ * on the persisted per-install key — not just length — to stay a fixed point
+ * across a process restart; without a persisted key, a fresh install falls back
+ * to a process-random key (`defaultPlaceholderKey()`), so the fallback marker
+ * would churn across restarts even though the algorithm itself is stable. A
+ * regex WITH a custom `replacement` never reaches that fallback (it always emits
+ * the literal configured string), and a plain replace secret's replacement is
+ * pure content-hash (`#generateSecretReplacement`), so neither needs the key.
+ * Short plain obfuscate entries are toned down (never placeheld), so they must
+ * NOT force key creation: otherwise a `secret-placeholder.key` file is written
+ * and persisted for a config that ends up with no active secrets, leaving the
+ * key readable via a tool and reusable for later placeholders.
+ */
+export declare function secretEntryNeedsPlaceholderKey(entry: SecretEntry): boolean;
+/**
+ * Whether a SET of entries needs the persisted placeholder key. `obfuscate()`
+ * applies plain replace-mode mappings before the plain-obfuscate pass, so a plain
+ * obfuscate entry only emits a reversible (keyed) placeholder when its content can
+ * still appear AFTER the replace phase. When no obfuscate entry can ever produce a
+ * placeholder, the persisted key must NOT be required/created — otherwise an
+ * effectively replace-only secret set still writes `secret-placeholder.key` and
+ * fails startup when the agent config dir is unwritable.
+ *
+ * The decision models the replace phase as the obfuscator actually runs it:
+ * replace mappings are content-keyed (later duplicate wins) and applied in
+ * descending content-length order; for a fresh probe (no prior placeholders) that
+ * phase is plain sequential substring replacement. A plain obfuscate entry needs
+ * the key when its content survives that simulated phase (direct typing) OR when
+ * any effective replacement can form the content via tiling — a substring,
+ * wholesale superstring, or prefix/suffix border that joins with surrounding
+ * passthrough bytes (see `replacementCanFormContent`). This covers direct
+ * shadowing (`SECRET -> safe`), reintroduction, duplicate ordering, transitive
+ * chains, and context-joined fragments uniformly. Default (omitted) replacements
+ * are deterministic, length-preserving, and distinct, so a same-content shadow
+ * with no other interacting replacement stays key-free.
+ * Replacement outputs are themselves rewritten by every later (shorter-content)
+ * replacement before the plain-obfuscate pass sees them, so a fragment that a
+ * subsequent replacement erases (`AA -> SEC` then `S -> X` turns every `SEC` into
+ * `XEC`) no longer forces the key. Surrounding bytes stay modeled as arbitrary
+ * passthrough, so testing the surviving fragment only drops false positives and
+ * never under-approximates a real key need.
+ */
+export declare function secretEntriesNeedPlaceholderKey(entries: SecretEntry[]): boolean;
+export declare function buildHashBase(key: string, value: string): string;
+export declare function buildKeyedReplacementRun(key: string, length: number): string;
+export declare function inferCaseHint(secret: string): PlaceholderCaseHint | undefined;
+export declare function buildPlaceholder(hint: PlaceholderCaseHint | undefined, base: string, friendlyName?: string): string;
+/** Regex matching `$$HASH$$`, `$$HASH:U$$`, and `$$FRIENDLY_HASH(:hint)$$` placeholders. */
+export declare const PLACEHOLDER_RE: RegExp;
+export declare function resumePlaceholderScanAfterRejectedCandidate(match: RegExpExecArray): void;
+export declare function placeholderWithoutFriendlyName(placeholder: string): string | undefined;
+export declare function lookupFriendlyPlaceholderAlias(deobfuscateMap: ReadonlyMap<string, {
+    secret: string;
+    recursive: boolean;
+}>, placeholder: string): {
+    secret: string;
+    recursive: boolean;
+} | undefined;
+export declare function stripPendingSecretPlaceholderSuffix(text: string): string;
+export interface RegexScanSegment {
+    scanStart: number;
+    scanEnd: number;
+    textStart: number;
+    textEnd: number;
+    generatedPlaceholder: boolean;
+    recursive: boolean;
+}
+export interface ReplaceRegexScan {
+    text: string;
+    segments: RegexScanSegment[];
+}
+export {};

package/dist/types/secrets/replacement.d.ts

@@ -0,0 +1,82 @@
+export declare const REPLACEMENT_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+/** Generate a deterministic same-length replacement string from a secret value. */
+export declare function generateDeterministicReplacement(secret: string): string;
+/**
+ * Force a length-preserving deterministic replacement to differ from the secret
+ * it stands in for. `generateDeterministicReplacement` seeds its first 1–2 chars
+ * with the `Z`/`ZZ` sentinel, so a whole configured value that is exactly `Z` or
+ * `ZZ` (or an astronomically unlikely longer hash collision) would otherwise be
+ * emitted unchanged and ship the raw secret to the provider. Flip the first char
+ * to a fixed different glyph: same length, still deterministic, guaranteed != the
+ * secret. Only safe for a whole CONFIGURED value (a plain secret matches its own
+ * literal, so the perturbed output is no longer matched and stays a fixed point);
+ * per-chunk remainders must keep the sentinel to remain idempotent across restart.
+ */
+export declare function ensureDistinctReplacement(replacement: string, secret: string): string;
+export interface RegexMatchContext {
+    /** Full text the match was found in (positions are offsets into it). */
+    text: string;
+    /** Start/end of the matched span being replaced. */
+    start: number;
+    end: number;
+}
+/**
+ * Whether `candidate`, substituted for the matched span in its surrounding text,
+ * is re-matched by `regex` at its own position. A replace-mode regex that depends
+ * on context (lookbehind/lookahead/`\b`) can match a candidate that does NOT match
+ * in isolation: e.g. `(?<=api=)[AZ]` never matches a bare `A`, but `api=A` does, so
+ * a candidate `A` chosen by an isolation test is re-redacted on the next obfuscate()
+ * pass and can oscillate back to the raw matched value. The probe substitutes the
+ * candidate into the FULL text — not a truncated window — so a wide lookbehind or
+ * lookahead (e.g. `(?<=A{600})`) still evaluates against the context that makes it
+ * match. Truncating that context dropped the assertion's reach and falsely
+ * accepted an oscillating, leaky candidate. The scan starts a bounded distance
+ * left of the span and stops once a match begins at/after the span's end (matches
+ * arrive in order), keeping per-candidate cost independent of total text length.
+ */
+export declare function regexRematchesInContext(candidate: string, regex: RegExp, ctx: RegexMatchContext): boolean;
+/**
+ * Search same-length replacements for one the regex does NOT match, so a default
+ * regex secret whose deterministic replacement collides with its own value (the
+ * `Z`/`ZZ` sentinel, or an astronomical hash collision) is still redacted to a
+ * STABLE nonmatching value instead of shipping the raw secret. A nonmatching
+ * candidate is a fixed point under re-obfuscation — the regex never re-matches it,
+ * so it cannot re-leak on a later pass. The search stays bounded to O(length *
+ * alphabet) regardless of value length: first exhaust every single-position
+ * substitution against a deterministic baseline (`AAAA…`, then `!AAA…`, `A!AA…`,
+ * …) so any regex that only needs one out-of-class byte — regardless of position —
+ * is found in a handful of probes rather than enumerating every combination (which
+ * for a 3-byte match-everything config, e.g. `[\s\S]{3}`, would otherwise run
+ * 90**3 = 729000 candidates through the regex on every single match, stalling
+ * provider requests). Candidates are enumerated deterministically over a stable
+ * ASCII alphabet: alphanumerics first (usually enough), then punctuation fallback
+ * bytes when the regex covers every alphanumeric candidate. When the regex still
+ * matches around a lone perturbed byte (for example `[A-Za-z0-9].*` matching the
+ * unperturbed tail), full-width same-byte candidates (`!!!!!`, `_____`, …) are
+ * tried next. When the regex covers every non-whitespace candidate (e.g. `\S{n}`),
+ * whitespace markers (a full space/tab run, then a single whitespace byte among
+ * non-whitespace filler) are tried as a last resort. A genuine match-everything
+ * regex (`.`/`[\s\S]`, which also matches space and tab) still exhausts this bounded
+ * sweep and returns undefined, letting the caller keep its own fixed-point fallback
+ * — bounded search can in principle miss an escape that depends jointly on
+ * multiple positions in a way no single-position swap reaches, but no realistic
+ * secret-redaction regex (character classes, literal matches, anchored/bounded
+ * repeats) has that shape.
+ */
+export declare function findNonMatchingReplacement(value: string, regex: RegExp, context: RegexMatchContext): string | undefined;
+/**
+ * Whether a default (no custom `replacement`) replace-mode regex can never
+ * safely redact a 1-2 char match: `findNonMatchingReplacement`'s bounded
+ * search — the same search `#generateRegexReplacement` runs at match time —
+ * finds no candidate the regex fails to re-match. This holds independent of
+ * any actual per-install key: the search already exhausts every character in
+ * `REPLACEMENT_CHARS` (the alphabet `buildKeyedReplacementRun` draws its
+ * fallback marker from) plus punctuation and whitespace, so if none of those
+ * escape the regex, no key-derived marker drawn from the same alphabet can
+ * either — the marker is guaranteed to re-match too, making every such match
+ * unresolvable: the fallback could only ever emit the raw matched text
+ * unchanged. Probed with a value (`"\0".repeat(length)`) the bounded search
+ * never treats as a real candidate, so the result depends only on the
+ * regex's own matching behavior, not on this specific probe.
+ */
+export declare function regexHasUnresolvableShortMatchFallback(regex: RegExp): boolean;

package/dist/types/session/agent-session-events.d.ts

@@ -2,7 +2,7 @@ import type { AgentEvent, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { CompactionResult } from "@oh-my-pi/pi-agent-core/compaction";
 import type { Effort } from "@oh-my-pi/pi-ai";
 import type { Rule } from "../capability/rule.js";
-import type { RecoveredRetryError } from "../extensibility/shared-events.js";
+import type { RetryErrorUpdate } from "../extensibility/shared-events.js";
 import type { Goal, GoalModeState } from "../goals/state.js";
 import type { ConfiguredThinkingLevel } from "../thinking.js";
 import type { TodoItem } from "../tools/todo.js";
@@ -40,7 +40,7 @@ export type AgentSessionEvent = Exclude<AgentEvent, {
     success: boolean;
     attempt: number;
     finalError?: string;
-    recoveredErrors?: RecoveredRetryError[];
+    retryErrors?: RetryErrorUpdate[];
 } | {
     type: "retry_fallback_applied";
     from: string;

package/dist/types/session/agent-session-types.d.ts

@@ -24,6 +24,12 @@ export declare const SHUTDOWN_CONSOLIDATE_BUDGET_MS = 1500;
 /** Options controlling session disposal. */
 export interface AgentSessionDisposeOptions {
     mnemopiConsolidateTimeoutMs?: number;
+    /**
+     * Deadline for the settle/drain wait before the terminal memory release
+     * (default 5s). The bounded-teardown paths (signal handlers, tests) may
+     * shorten it; late event handlers are still finalized after they settle.
+     */
+    drainTimeoutMs?: number;
     /**
      * Postmortem reason that triggered this dispose (signal/fatal teardown
      * paths). When set, the persisted `session_exit` diagnostic records it

package/dist/types/session/agent-session.d.ts

@@ -41,7 +41,7 @@ import type { DaemonCompletionNotification } from "../launch/protocol.js";
 import { type MnemopiSessionState } from "../mnemopi/state.js";
 import { type PlanApprovalDetails } from "../plan-mode/approved-plan.js";
 import type { PlanModeState } from "../plan-mode/state.js";
-import { type SecretObfuscator } from "../secrets/obfuscator.js";
+import type { SecretObfuscator } from "../secrets/obfuscator.js";
 import { type ConfiguredThinkingLevel } from "../thinking.js";
 import { type AskToolDetails, type AskToolInput } from "../tools/ask.js";
 import type { CheckpointState, CompletedRewindState } from "../tools/checkpoint.js";
@@ -83,7 +83,7 @@ export declare class AgentSession {
     /**
      * Arm prewalk outside the normal startup path so an explicit slash command starts immediately.
      */
-    armPrewalk(target: Model, thinkingLevel?: ConfiguredThinkingLevel): void;
+    armPrewalk(target: Model, thinkingLevel?: ConfiguredThinkingLevel): boolean;
     /** Validate the active plan artifact and shape an `xd://propose` result for review-mode hosts. */
     preparePlanForReview(title: string): Promise<AgentToolResult<PlanApprovalDetails>>;
     constructor(config: AgentSessionConfig);

package/dist/types/session/messages.d.ts

@@ -12,6 +12,7 @@ import type { OutputMeta } from "../tools/output-meta.js";
 export declare const SKILL_PROMPT_MESSAGE_TYPE = "skill-prompt";
 export declare const LSP_LATE_DIAGNOSTIC_MESSAGE_TYPE = "lsp-late-diagnostic";
 export declare const BACKGROUND_TAN_DISPATCH_MESSAGE_TYPE = "background-tan-dispatch";
+export declare const PREWALK_PLAN_MESSAGE_TYPE = "prewalk-plan";
 /**
  * Logs provider-error turns so their actual cause is available outside the
  * session transcript. No-op for non-error stop reasons.

package/dist/types/session/prewalk.d.ts

@@ -6,6 +6,8 @@ import { type ConfiguredThinkingLevel } from "../thinking.js";
 import type { PlanProposalHandler } from "../tools/resolve.js";
 import type { PlanYolo, Prewalk } from "./agent-session-types.js";
 import type { SessionManager } from "./session-manager.js";
+/** Hidden plan steering is consumed within the live run and must not reappear after a context rebuild. */
+export declare function isPrewalkPlanNudge(message: AgentMessage): boolean;
 /** Capabilities the prewalk coordinator borrows from its owning session. */
 export interface PrewalkCoordinatorHost {
     agent: Agent;
@@ -41,7 +43,7 @@ export declare class PrewalkCoordinator {
     /** Advances the one-way prewalk switch at a completed assistant-turn boundary. */
     advanceAtTurnEnd(liveMessages: AgentMessage[], context: AgentTurnEndContext | undefined): Promise<void>;
     /** Arms a prewalk immediately for an explicit slash-command request. */
-    arm(target: Model, thinkingLevel?: ConfiguredThinkingLevel): void;
+    arm(target: Model, thinkingLevel?: ConfiguredThinkingLevel): boolean;
     /** Lazily enables plan-yolo's plan phase before the first prompt is built. */
     armPlanYoloIfNeeded(): Promise<void>;
 }

package/dist/types/session/session-handoff.d.ts

@@ -4,7 +4,7 @@ import type { Message, Model, ServiceTier, SimpleStreamOptions } from "@oh-my-pi
 import type { ModelRegistry } from "../config/model-registry.js";
 import type { Settings } from "../config/settings.js";
 import type { ExtensionRunner } from "../extensibility/extensions/index.js";
-import { type SecretObfuscator } from "../secrets/obfuscator.js";
+import type { SecretObfuscator } from "../secrets/obfuscator.js";
 import type { HandoffResult, SessionHandoffOptions } from "./agent-session-types.js";
 import type { BashSessionTransition } from "./bash-runner.js";
 import type { SessionContext } from "./session-context.js";
@@ -55,9 +55,9 @@ export declare class SessionHandoff {
     #private;
     constructor(host: SessionHandoffHost);
     /**
-     * Cancel in-progress handoff generation.
+     * Cancel in-progress handoff generation, preserving a harness-provided reason.
      */
-    abortHandoff(): void;
+    abortHandoff(reason?: Error): void;
     /**
      * Check if handoff generation is in progress.
      */

package/dist/types/session/session-manager.d.ts

@@ -133,6 +133,38 @@ export declare class SessionManager {
     flushSync(): void;
     /** Flush, then close the append writer. */
     close(): Promise<void>;
+    /**
+     * Raise the terminal write barrier ahead of the final {@link close}. Once
+     * sealed:
+     * - every later append, title change, and rewrite is a dropped no-op —
+     *   including work an event handler tries to enqueue while dispose is
+     *   awaiting `close()` on the disk tail;
+     * - the disk epoch is bumped, so queued-but-unexecuted tail work is
+     *   superseded and an ALREADY-RUNNING fenced/repair rewrite (awaiting the
+     *   tail, drain, writer close, or the atomic stage) fails its commit guard
+     *   at the rename fence instead of publishing over a revived file.
+     * The final `close()` itself is scheduled after the bump and still runs;
+     * pre-seal hot-path appends are already in the page cache. Idempotent;
+     * terminal.
+     */
+    seal(): void;
+    /**
+     * Terminal release: drop the in-memory transcript and complete the
+     * {@link seal}. The entry journal and its index mirror the agent's message
+     * array (tool results, file contents, base64 frame images); on a disposed
+     * session — e.g. a parked subagent still referenced by the lifecycle
+     * adoption record — they would otherwise stay pinned for the process
+     * lifetime.
+     *
+     * Closes the append writer; with the seal up, nothing can reopen it. A
+     * revival may reopen the same JSONL through a NEW manager the moment
+     * dispose returns; a late event handler resuming on THIS manager must
+     * never race that writer — and a post-release rewrite would persist the
+     * now-empty entry list, truncating the transcript. Reads after this point
+     * reopen from disk (revival, `history://`). Only call from session
+     * dispose, after the final `close()`; idempotent.
+     */
+    releaseRetainedEntries(): void;
     getCwd(): string;
     /** Additional workspace directories beyond cwd (multi-root), absolute and normalized. */
     getAdditionalDirectories(): string[];

package/dist/types/session/session-provider-boundary.d.ts

@@ -5,7 +5,7 @@ import type { ImageContent, Message, Model, SimpleStreamOptions } from "@oh-my-p
 import type { ModelRegistry } from "../config/model-registry.js";
 import type { Settings } from "../config/settings.js";
 import type { LocalProtocolOptions } from "../internal-urls/index.js";
-import { type SecretObfuscator } from "../secrets/obfuscator.js";
+import type { SecretObfuscator } from "../secrets/obfuscator.js";
 import { type CustomMessage } from "./messages.js";
 import type { BuildSessionContextOptions, SessionContext } from "./session-context.js";
 import type { SessionManager } from "./session-manager.js";

package/dist/types/session/session-tools.d.ts

@@ -108,6 +108,14 @@ export declare class SessionTools {
     get baseSystemPrompt(): string[];
     /** Replaces the controller-owned base prompt without applying it to the agent. */
     setBaseSystemPrompt(prompt: string[]): void;
+    /**
+     * Registers the per-turn `before_agent_start` system-prompt override and
+     * applies it to the agent. Base rebuilds during the turn preserve it until
+     * {@link clearTurnSystemPromptOverride}.
+     */
+    setTurnSystemPromptOverride(prompt: string[]): void;
+    /** Drops the active per-turn override; later rebuilds fall back to the base prompt. */
+    clearTurnSystemPromptOverride(): void;
     /** Skills currently rendered into the system prompt. */
     get skills(): Skill[];
     /** Diagnostics produced while loading the current skills. */

package/dist/types/session/turn-recovery.d.ts

@@ -100,8 +100,13 @@ export declare class TurnRecovery {
         autoContinue: boolean;
         triggerContextTokens?: number;
     }): Promise<RecoveryCompactionResult>;
-    /** Restores the configured primary after fallback cooldown expiry. */
-    maybeRestoreRetryFallbackPrimary(): Promise<void>;
+    /**
+     * Restores the configured primary after fallback cooldown expiry.
+     * @returns true when the active model was actually switched back to the
+     * primary, so callers can re-run the pre-send context-fit check against the
+     * reverted (possibly smaller) window before issuing the next request.
+     */
+    maybeRestoreRetryFallbackPrimary(): Promise<boolean>;
     /** Applies model fallback policy from live usage health before a turn starts. */
     maybeApplyUsageAwareFallback(signal: AbortSignal, confirmer?: UsageFallbackConfirmer): Promise<boolean>;
     /** Applies automatic retry, credential rotation, and model fallback policy. */
@@ -151,9 +156,9 @@ export declare class TurnRecovery {
      */
     isRetryableReasonlessAbort(message: AssistantMessage): boolean;
     /**
-     * Check if an error is retryable (transient errors or usage limits).
+     * Check if an error is retryable (transient errors, usage limits, or
+     * account-scoped policy denials that can rotate credentials).
      * Context overflow is NOT retryable (handled by compaction instead).
-     * Usage-limit errors are retryable because the retry handler performs credential switching.
      */
     isRetryableError(message: AssistantMessage): boolean;
     /**

package/dist/types/slash-commands/builtin-collaboration.d.ts

@@ -0,0 +1,2 @@
+import type { SlashCommandSpec } from "./types.js";
+export declare const BUILTIN_COLLABORATION_SLASH_COMMANDS: ReadonlyArray<SlashCommandSpec>;