@gajae-code/coding-agent 0.14.2-nightly.20260818150120.32333814007.gd49c40a6c3c0 → 0.14.2

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [0.14.2] - 2026-08-20
+
+### Added
+- Added an opt-in crash upstream relay for cross-install aggregation. Handled tool errors are captured and relayed to a configurable Sentry upstream; relayed-upstream state transitions are journaled and indexed; and the relay is hardened across the trust boundary (no unsigned provenance), delivery watermarks (no replay races), egress and durability (bounded queues, LRU-bounded handled dedupe, restored fatal-occurrence journaling), and recovery/provenance paths closed by exact-head review. The generated config schema was regenerated after the global-only relay settings. Off by default; enabling requires explicit operator opt-in.
+- Added a manual-switch hint after provider safety stops: when a provider halts a turn for a safety reason, the session now surfaces that the operator can switch models/providers manually instead of leaving the stop unexplained (#4650, #4653).
+- Shift+Tab effort cycling now wins over profile suffixes, and operator-intent effort is distinguished from model-default appends, so explicit effort choices are no longer silently overridden at restore time (#4695, #4700).
+
+### Fixed
+- Fixed worker runtime state under `.gjc/state` being swept into leader-repository auto-checkpoints during team runs; checkpoint classification now excludes it (#4603).
+- Fixed ralplan explicit-target worktree handling end to end: runs bind to the explicit `--worktree-root` instead of fragmenting by writer cwd, a trailing `--worktree-root` with no operand is rejected, HEAD objects are verified and explicit-target writes contained, mutation fails closed on review findings, and `.gjc` is confined before migration and fails closed without procfs.
+- Fixed SDK broker liveness (#4704): a broker that stops publishing while its process stays alive is now terminated; the retained broker heartbeat and watchdog observation run off the JS thread; shutdown and observation no longer hold the retained writer lock; stale watchdog observations are fenced during teardown; startup admission reopens after authority recheck; and retained work is fenced across broker restarts.
+- Fixed agent steering losing or racing user input: a steer that interrupts an in-flight tool is delivered, the remaining abort-race gaps in steer-after-tool-interrupt are closed, and a live subagent await ends when user steering arrives instead of hanging.
+- Fixed rotating agent environment credentials not being reloaded and hardened the rotation path so concurrent readers never observe a partially written credential set.
+- Fixed the config CLI reporting success when a setting was not durably saved, and made retargeted CLI persistence fail closed instead of writing to an unintended target.
+- Fixed session robustness: a fatal resident blob now names the session and leaves a record; the corrupted-sentinel lane the strict check walked past is closed; and the transition materialize lane is bound and the dead invalid-ref guard dropped.
+- Fixed notification/herdr integration: recovery no longer re-quarantines native exchange debris, debris cleanup binds to native identity, pane authority binds to process identity so a nested gjc cannot release its parent pane's agent authority, and the native lint gate is satisfied.
+- Fixed `/usage` not surfacing cached usage for API-key credentials in `getCachedUsageReport` (#4686), and made the account-inventory usage tests hermetic on credential-free hosts (#4663).
+- Fixed the auth gateway rejecting explicit `null` fields on openai-chat requests (#4667).
+- Fixed Grok Build turns stalling by giving the provider the same 300s idle window other long-turn providers use.
+- Fixed skill discovery ignoring `skills.customDirectories`; configured directories are now scanned (#4713).
+- Fixed the escaped-non-ASCII em-dash exemption applying beyond display-only tools (#4627).
+- Fixed deep-interview Round 0 ask calls omitting required intent metadata, which produced HTTP 400 rejections on strict providers (#4651).
+- Fixed SDK terminal-in-progress prompt submissions being dropped past the delivery TTL.
+- Fixed postmortem tests writing into the real crash store; they now isolate into a fresh store.
 ## [0.14.1] - 2026-08-18
 - Fixed a resident-cache demotion aborting the turn it was supposed to rescue. The demotion is the salvage that runs *because* the cache already failed, so it materializes a store that is by definition missing blobs — yet it was the one materialize call site that never passed `missingPolicy`, inheriting the fail-closed default. It therefore threw `ResidentBlobMissingError` on the very entry it existed to rescue, the transition never committed, the store stayed broken, and every later turn repeated the same throw out of the `message_end` handler. That handler only `logger.warn`s, so the operator saw a bare `Operation aborted` with every pending tool marked `Tool execution was aborted.` and nothing naming a cache, a blob, or an errno — permanently, until the session was restarted. The salvage now substitutes the same placeholder the persistence path already uses, which never emits a `blob:sha256:` ref, so the invariant the fail-closed policy protects is preserved while the session stays usable. Unrecoverable substitutions are counted in `residentBlobPlaceholderCount` and logged once each with their kind, hash, and the demotion's errno, so silent content loss is visible rather than inferred.
 - Fixed the resident-cache GC reaping the cache of a *running* session, which made long-lived sessions abort every turn with an unexplained `Operation aborted`. The owner lease stores a process start time purely to detect PID reuse, and derived it from `ps -o lstart=` — a zoneless local wall clock rendered from `/etc/localtime` by `ps`, then bound to a zone by `Date.parse` in the reading runtime. Those are two independent zone resolutions: pinning `LC_ALL`/`LANG` stabilized the *format* but not the *instant*, so a reader whose runtime resolved UTC while `ps` rendered UTC+9 computed a start time nine hours off for the same live PID, declared the owner reused, and deleted its instance directory. Observed in the wild: a test process reaped the live instance directories of two running sessions in the same sweep (captured at 32,400,000 ms of skew, exactly the host offset). Each victim then lost the externalized bodies of its large `edit` snapshots, and every later turn died materializing them. The probe now pins `TZ=UTC` on the `ps` child and parses the render explicitly as GMT, so the value is absolute in any reader; leases carry `startTimeBasis: "utc"`, and a lease written before the pin leaves reuse unproven instead of stale, so upgrading cannot reap a live owner once on the way through.

package/dist/types/cli/crash-cli.d.ts

@@ -5,6 +5,18 @@
  * `crash/report.ts`, which is the part that carries the consent contract and is
  * therefore tested against stubbed boundaries.
  */
+import type { Settings } from "../config/settings";
 import { type CrashReportOutcome } from "../crash/report";
+import { type CrashRelayOutcome } from "../crash/upstream/relay";
 export declare function runCrashReportCommand(): Promise<CrashReportOutcome>;
 export declare function runCrashListCommand(json: boolean): Promise<void>;
+/**
+ * Batch-relay every due signature to the configured upstream.
+ *
+ * The startup relay is silent and best-effort; this is the loud form, so a
+ * refusal is reported as a refusal instead of being swallowed. It shares the
+ * same gate: with `crashReport.upstream` off, it explains that and exits
+ * non-zero rather than quietly doing nothing.
+ */
+export declare function crashRelayExitCode(outcome: CrashRelayOutcome): number;
+export declare function runCrashRelayCommand(settings: Settings): Promise<void>;

package/dist/types/commands/crash.d.ts

@@ -1,7 +1,8 @@
 /**
  * `gjc crash` — inspect local crash signatures and file an assisted, fully
- * consented bug report. Nothing leaves the machine without an explicit,
- * digest-confirmed confirmation for that exact invocation.
+ * consented bug report. `gjc crash report` requires an explicit,
+ * digest-confirmed confirmation for that exact invocation; `gjc crash relay`
+ * uses separately configured standing consent.
  */
 import { Command } from "@gajae-code/utils/cli";
 export default class Crash extends Command {

package/dist/types/commands/ralplan.d.ts

@@ -1,4 +1,7 @@
 import { Command } from "@gajae-code/utils/cli";
+import { type RalplanCommandResult } from "../gjc-runtime/ralplan-runtime";
+/** Public CLI path: validate --worktree-root before any settings migration, then dispatch. */
+export declare function runRalplanCliCommand(args: string[], cwd: string): Promise<RalplanCommandResult>;
 export default class Ralplan extends Command {
     static description: string;
     static strict: boolean;

package/dist/types/config/settings-schema.d.ts

@@ -1841,6 +1841,25 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "At interactive startup, show one rate-limited line when unreported crash signatures exist. Reads local state only; nothing is ever transmitted without the explicit consent flow in `gjc crash report`.";
         };
     };
+    readonly "crashReport.upstream": {
+        readonly type: "enum";
+        readonly values: readonly ["off", "sentry"];
+        readonly default: "off";
+        readonly ui: {
+            readonly tab: "interaction";
+            readonly label: "Crash Report Upstream (Global)";
+            readonly description: "Global-only opt-in to transmit sanitized crash signatures to an aggregation service for cross-install counting. Off sends nothing. Only fields approved by `sanitizeExternalCrashV1` are sent; prompt text, source code, file contents, and credentials are excluded.";
+        };
+    };
+    readonly "crashReport.upstreamDsn": {
+        readonly type: "string";
+        readonly default: "";
+        readonly ui: {
+            readonly tab: "interaction";
+            readonly label: "Crash Report Upstream DSN (Global)";
+            readonly description: "Global-only Sentry DSN for the opted-in upstream; ignored while Crash Report Upstream is off, and no default destination exists. Only fields approved by `sanitizeExternalCrashV1` are sent; prompt text, source code, file contents, and credentials are excluded.";
+        };
+    };
     readonly collapseChangelog: {
         readonly type: "boolean";
         readonly default: false;

package/dist/types/crash/index-store.d.ts

@@ -21,9 +21,15 @@ export interface CrashSignatureEntry {
     firstSeen: number;
     lastSeen: number;
     lastRecordId: string;
+    /** Journal-append-order occurrence id, independent of display-time `lastSeen`. */
+    lastAppendRecordId?: string;
     reportedAt?: number;
     reportedIssueUrl?: string;
     acknowledgedAt?: number;
+    /** Epoch ms this signature was last accepted by the configured upstream. */
+    relayedAt?: number;
+    /** Occurrence record represented by the durable upstream watermark. */
+    relayedRecordId?: string;
     /** Issues this install already "+1"ed, so re-invocations cannot spam comments. */
     commentedIssues?: string[];
 }

package/dist/types/crash/upstream/dsn.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Sentry DSNs are configuration, but accepting a malformed one can turn an
+ * opt-in crash relay into an unexpected network destination. Keep parsing
+ * deliberately narrow and reconstruct public-key-bearing forms only at the
+ * envelope boundary.
+ */
+export interface SentryDsn {
+    readonly publicKey: string;
+    readonly host: string;
+    readonly projectId: string;
+    readonly envelopeUrl: string;
+}
+/**
+ * Parse only the public-key DSN form used by the relay. Secrets, query values,
+ * fragments, and plaintext public destinations are all refused before a URL is
+ * ever retained as a network target.
+ */
+export declare function parseSentryDsn(raw: string): SentryDsn | undefined;
+/** Reconstruct the DSN required in the envelope header, nowhere else. */
+export declare function toDsnString(dsn: SentryDsn): string;
+/** Omit the public key from diagnostics so configuration can be logged safely. */
+export declare function redactDsn(dsn: SentryDsn): string;

package/dist/types/crash/upstream/envelope.d.ts

@@ -0,0 +1,38 @@
+import { type SentryDsn } from "./dsn";
+export interface CrashEventFrame {
+    readonly filename: string;
+    readonly function: string;
+}
+export interface BuildCrashEnvelopeInput {
+    readonly eventId: string;
+    readonly fingerprint: string;
+    readonly errorName: string;
+    readonly messageClass: string;
+    readonly frames: readonly CrashEventFrame[];
+    readonly firstSeen: number;
+    readonly lastSeen: number;
+    readonly lifetimeCount: number;
+    readonly release: string;
+    readonly platform: string;
+    readonly bunVersion: string;
+    readonly dsn: SentryDsn;
+    /** Upstream severity. Defaults to `fatal`; handled tool failures use `error`. */
+    readonly level?: "fatal" | "error";
+}
+export type BuildCrashEnvelopeResult = {
+    ok: true;
+    body: string;
+    eventId: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Create Sentry's required lowercase 128-bit event identifier. */
+export declare function newSentryEventId(): string;
+/** Build the exact auth header used for the hand-rolled envelope POST. */
+export declare function sentryAuthHeader(dsn: SentryDsn, clientVersion: string): string;
+/**
+ * Build a three-line event envelope. Sanitization failures and oversize output
+ * refuse the complete event: JSON must never be truncated into a new payload.
+ */
+export declare function buildCrashEnvelope(input: BuildCrashEnvelopeInput): BuildCrashEnvelopeResult;

package/dist/types/crash/upstream/relay.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Opt-in crash relay to a Sentry-compatible upstream.
+ *
+ * This is a **second, separate** egress channel from `gjc crash report`. The
+ * issue flow keeps its per-invocation, digest-confirmed consent boundary; this
+ * one is gated by configuration instead, and is therefore deliberately much
+ * narrower in what it can ever emit:
+ *
+ * 1. `crashReport.upstream` must be `sentry`. The default is `off`, and while
+ *    it is off this module performs no IO at all — not even a state read.
+ * 2. An operator must supply a DSN. No DSN literal is compiled into the binary,
+ *    so a build has no destination to fall back to; an unset DSN is a hard stop
+ *    and never means "use ours".
+ * 3. Every crash-derived byte must pass `sanitizeExternalCrashV1`. A refusal
+ *    drops that signature entirely. There is no less-sanitized fallback path.
+ *
+ * The relay never runs on the fatal path. A crashing process still does exactly
+ * one `O_APPEND` write and dies; relaying happens at the *next* startup, after
+ * compaction, where blocking and failing are both safe.
+ */
+import { type CrashSignatureView, type CrashStatePaths } from "../index-store";
+import { type SentryDsn } from "./dsn";
+/** Trusted environment variable form of the DSN, for CI and one-off runs. */
+export declare const CRASH_UPSTREAM_DSN_ENV = "GJC_CRASH_SENTRY_DSN";
+export interface CrashRelayConfig {
+    readonly upstream: "off" | "sentry";
+    readonly dsn: string;
+}
+/**
+ * The only settings surface the relay is allowed to read.
+ *
+ * `Settings.get` merges project `.gjc` configuration into the answer, so using
+ * it here would let merely opening a repository turn the relay on and choose
+ * its destination — an untrusted checkout could redirect crash signatures that
+ * were recorded long before it was cloned. Both keys are therefore read from
+ * the user/global layer only, which is exactly what `getGlobal` documents
+ * itself for.
+ */
+export interface TrustedRelaySettings {
+    getGlobal(path: "crashReport.upstream" | "crashReport.upstreamDsn"): unknown;
+}
+/**
+ * Resolve the relay configuration from the trusted layer.
+ *
+ * The values are re-validated rather than trusted by type. `getGlobal` reports
+ * whatever the hand-editable global config file holds, and it returns
+ * `undefined` instead of a schema default, so anything that is not literally
+ * `"sentry"` lands on `off` and anything that is not a string lands on an empty
+ * DSN. Both absent and malformed therefore fail closed.
+ */
+export declare function readTrustedRelayConfig(settings: TrustedRelaySettings): CrashRelayConfig;
+/**
+ * The exact shape the relay uses. Narrower than `typeof fetch` on purpose: the
+ * relay only ever issues one POST to a known URL, and depending on the full
+ * runtime signature (Bun adds `preconnect`) would force every caller and test
+ * double to fake surface this module never touches.
+ */
+export type CrashRelayFetch = (url: string, init: RequestInit) => Promise<Response>;
+export type CrashRelaySkip = "disabled" | "no-dsn" | "invalid-dsn" | "nothing-to-relay";
+export type CrashRelayOutcome = {
+    readonly status: "skipped";
+    readonly reason: CrashRelaySkip;
+} | {
+    readonly status: "ran";
+    /** Signatures the upstream accepted and that are now stamped `relayedAt`. */
+    readonly sent: number;
+    /** Signatures dropped because the sanitizer refused a field. */
+    readonly refused: number;
+    /** Signatures the upstream rejected or that failed in transport. */
+    readonly failed: number;
+};
+/**
+ * Severity of the store being relayed.
+ *
+ * Fatal crashes and handled tool failures live in separate files on purpose --
+ * handled errors are high-volume and would otherwise evict the rare, precious
+ * fatal records from a shared cap. They are relayed through the same code with
+ * the same egress contract, and differ upstream only by `level`, so a single
+ * project can hold both without the noisy class drowning the signal.
+ */
+export type CrashRelaySeverity = "fatal" | "error";
+export interface CrashRelayOptions {
+    readonly config: CrashRelayConfig;
+    readonly paths?: CrashStatePaths;
+    readonly handledPaths?: CrashStatePaths;
+    readonly severity?: CrashRelaySeverity;
+    readonly env?: Record<string, string | undefined>;
+    readonly fetchImpl?: CrashRelayFetch;
+    readonly now?: () => number;
+    readonly maxPerRun?: number;
+    readonly platform?: string;
+    readonly release?: string;
+    readonly bunVersion?: string;
+}
+/**
+ * Resolve the destination. Explicit config wins over the environment so a
+ * machine-wide export cannot silently redirect a configured install.
+ */
+export declare function resolveRelayDsn(config: CrashRelayConfig, env?: Record<string, string | undefined>): {
+    ok: true;
+    dsn: SentryDsn;
+} | {
+    ok: false;
+    reason: CrashRelaySkip;
+};
+/**
+ * A signature is due when new journal-append-order occurrences exist after the
+ * last durable watermark. `lastSeen` is display-time only and must not hide a
+ * backdated occurrence. Legacy indexes that only have `relayedAt` stay covered
+ * when that wall-clock stamp still covers `lastSeen`. After a downgrade that
+ * advanced `relayedAt` without rewriting `relayedRecordId`, the same lastSeen
+ * coverage applies only when the latest append is also the lastSeen record.
+ */
+export declare function isRelayDue(signature: CrashSignatureView): boolean;
+/**
+ * Automatic relay stores use the normal XDG state location only when the XDG
+ * value came from a trusted environment. `dirs.ts` rejects checkout `.env`
+ * declarations before resolving these paths, including dotenv-expanded values.
+ */
+export declare function resolveTrustedRelayStatePaths(): CrashStatePaths;
+export declare function resolveTrustedHandledRelayStatePaths(): CrashStatePaths;
+/**
+ * Relay every due signature once. Never throws: a broken upstream, an offline
+ * machine or a corrupt crash log must not be able to take down startup.
+ */
+export declare function relayCrashSignatures(options: CrashRelayOptions): Promise<CrashRelayOutcome>;
+/** Paths of the handled-error store. Never XDG: a supplied directory is joined directly. */
+export declare function resolveHandledErrorStatePaths(agentDir?: string): CrashStatePaths;
+/**
+ * Relay both stores in one pass.
+ *
+ * Fatal crashes go first: they are rarer and more valuable, so when the
+ * per-run cap binds they must not be starved by a noisy handled-error class.
+ * The cap is shared across both stores. The gate is evaluated once by the
+ * first call, and a skip there means the same skip applies to the second, so
+ * `off` still performs no IO at all.
+ */
+export declare function relayAllSignatures(options: CrashRelayOptions): Promise<CrashRelayOutcome>;

package/dist/types/gjc-runtime/ralplan-runtime.d.ts

@@ -155,6 +155,22 @@ export declare function resolveRalplanMaxReviewPassesPerLane(cwd: string, agentD
     source: string;
 }>;
 export declare function isRalplanArtifactWriteInvocation(args: readonly string[]): boolean;
+/**
+ * Explicit target-worktree routing (#4693). `--worktree-root <path>` selects the
+ * canonical git worktree that owns every ralplan persistence root (run state,
+ * stage artifacts, index ledger, HUD state, stuck markers, and review-budget
+ * accounting) regardless of the writer process's ambient cwd. Without the flag,
+ * behavior stays cwd-based. The invoking cwd is retained only for resolving a
+ * relative `--artifact` input file.
+ */
+interface RalplanTargetRoot {
+    /** Canonical persistence root: the invocation cwd, or the --worktree-root target. */
+    root: string;
+    /** True when the caller explicitly selected the target via --worktree-root. */
+    explicit: boolean;
+}
+export declare function resolveRalplanTargetRoot(args: readonly string[], invocationCwd: string): Promise<RalplanTargetRoot>;
+export declare function assertExplicitTargetGjcNotSymlinked(root: string): Promise<void>;
 export declare function runNativeRalplanCommand(args: string[], cwd?: string, options?: {
     agentDir?: string;
 }): Promise<RalplanCommandResult>;

package/dist/types/modes/components/assistant-message.d.ts

@@ -1,5 +1,6 @@
 import type { AssistantMessage, ImageContent, Usage } from "@gajae-code/ai/core";
 import { Container } from "@gajae-code/tui";
+import { type ProviderSafetyStopHintSession } from "../../session/provider-safety-stop-hint";
 interface AssistantMessageUpdateOptions {
     streaming?: boolean;
 }
@@ -11,7 +12,8 @@ export declare class AssistantMessageComponent extends Container {
     private hideThinkingBlock;
     private readonly onImageUpdate?;
     private readonly onVisibleMutation?;
-    constructor(message?: AssistantMessage, hideThinkingBlock?: boolean, onImageUpdate?: (() => void) | undefined, viewportAnchorId?: string, onVisibleMutation?: (() => void) | undefined);
+    private readonly hintSession?;
+    constructor(message?: AssistantMessage, hideThinkingBlock?: boolean, onImageUpdate?: (() => void) | undefined, viewportAnchorId?: string, onVisibleMutation?: (() => void) | undefined, hintSession?: ProviderSafetyStopHintSession | undefined);
     invalidate(): void;
     setHideThinkingBlock(hide: boolean): void;
     setToolResultImages(toolCallId: string, images: ImageContent[]): void;

package/dist/types/sdk/broker/broker.d.ts

@@ -233,6 +233,14 @@ export declare function setTerminalPersistenceHookForTest(broker: Broker, hook:
 export declare function setAmbiguityGraceForTest(broker: Broker, graceMs: number | undefined): void;
 /** Test-only hook for shortening the startup lock-artifact reap bound. */
 export declare function setLockArtifactGraceForTest(broker: Broker, graceMs: number | undefined): void;
+/** Test-only hook for shortening the bounded liveness deadline. */
+export declare function setLivenessGraceForTest(broker: Broker, graceMs: number | undefined): void;
+/**
+ * Test-only hook for stalling the heartbeat write, reproducing a publication tick
+ * whose awaited IO does not settle. Clearing it releases the stalled tick the way
+ * recovered IO would, instead of abandoning it forever.
+ */
+export declare function setHeartbeatStallForTest(broker: Broker, stalled: boolean): void;
 /** Test-only hook for forcing the observation the publication watchdog sees. */
 export declare function setPublicationObservationForTest(broker: Broker, observation: BrokerPublicationObservation | undefined): void;
 export {};

package/dist/types/sdk/broker/discovery.d.ts

@@ -3,6 +3,7 @@ import { SDK_STATE_VERSION } from "./state-version";
 export type BrokerPublicationObservation = "owned" | "absent" | "replaced" | "ambiguous";
 export interface RetainedBrokerDiscovery {
     observe(): BrokerPublicationObservation;
+    observeAsync(): Promise<BrokerPublicationObservation>;
     heartbeat(heartbeatAt: number): Promise<boolean>;
     close(): void;
 }

package/dist/types/sdk/bus/notification-service.d.ts

@@ -51,16 +51,6 @@ export interface NotificationExactUnlinkResult {
 export declare function readNotificationEndpointFile(file: string): Promise<NotificationEndpointFile>;
 /** Bump when the native exact-deletion identity contract changes. */
 export declare const NATIVE_PATH_IDENTITY_CONTRACT_VERSION = 1;
-/**
- * Remove exactly the inspected regular file.
- *
- * Intermediate directory symlinks (e.g. multi-account layouts that share
- * `notifications/` via a directory symlink) are resolved before the native
- * no-follow unlink. Only the parent path is canonicalized; the final basename
- * is rejoined so native exact_unlink still applies AT_SYMLINK_NOFOLLOW to the
- * final path component at mutation time. A final-component file symlink stays
- * `reparse_point` (including TOCTOU replacement after JS preflight).
- */
 export declare function exactUnlinkNotificationFile(file: string, identity: NotificationEndpointFileIdentity, quarantineName: string): NotificationExactUnlinkResult;
 /** Minimal filesystem surface the service needs; injectable for tests. */
 export interface NotificationServiceFs {
@@ -68,6 +58,8 @@ export interface NotificationServiceFs {
     readFile(file: string, encoding: "utf8"): Promise<string>;
     readEndpointFile(file: string): Promise<NotificationEndpointFile>;
     exactUnlink(file: string, identity: NotificationEndpointFileIdentity): Promise<NotificationExactUnlinkResult>;
+    /** Identity-bound direct unlink reserved for inert exchange debris. */
+    unlinkExact(file: string, identity: NotificationEndpointFileIdentity): Promise<NotificationExactUnlinkResult>;
     unlink(file: string): Promise<void>;
     writeFile?(file: string, data: string, opts?: WriteFileOptions): Promise<void>;
     stat?(file: string): Promise<{

package/dist/types/sdk/bus/telegram-daemon-contract.d.ts

@@ -269,7 +269,7 @@ export declare const SDK_LIFECYCLE_ROUTER_PROTOCOL_VERSION = 1;
  * Generation 169 delivers every ring-positioned session event live through the
  * bounded, capability-gated directed subscriber leg used by replay.
  */
-export declare const DAEMON_GENERATION = 170;
+export declare const DAEMON_GENERATION = 171;
 /**
  * Serving-compatibility boundary for daemon lifecycle requests. Epoch 7
  * requires durable publication receipts and acknowledged attachment dispatch,

package/dist/types/session/provider-safety-stop-hint.d.ts

@@ -0,0 +1,79 @@
+import type { AssistantMessage, Model } from "@gajae-code/ai/core";
+import { type ModelSelectorValue } from "../config/model-selector-value";
+/**
+ * Normalize a model selector for display: strip ANSI escape sequences and
+ * control characters, remove Unicode format characters, replace tabs with
+ * spaces, and bound the width. One shared implementation so the TUI render and
+ * the print-mode stderr render interpolate the identical safe value (#4653
+ * review: centralize selector sanitization instead of leaving each surface to
+ * bound itself).
+ */
+export declare function sanitizeModelSelectorForDisplay(selector: string): string;
+/**
+ * Session capabilities the hint resolver reads. Everything is optional so
+ * lightweight host/test contexts without model plumbing degrade to the static
+ * guidance instead of throwing.
+ */
+export interface ProviderSafetyStopHintSession {
+    getConfiguredModelChainState?(role: string): {
+        entries: readonly string[];
+        origin: string;
+        identity?: string;
+        explicitHead: boolean;
+    } | undefined;
+    settings?: {
+        getModelRole?(role: string): ModelSelectorValue | undefined;
+    };
+    getAvailableModels?(): Model[];
+}
+/** Whether an assistant message terminated as a provider safety stop (typed or legacy-persisted). */
+export declare function isProviderSafetyStop(message: AssistantMessage): boolean;
+/**
+ * The `provider/id` identity of the model that produced an assistant message.
+ * The message's own `provider`/`model` fields are the authoritative identity of
+ * the refusing attempt (they survive model switches after the error).
+ */
+export declare function refusingModelSelector(message: AssistantMessage): string | undefined;
+/**
+ * Resolve a safe, valid alternate model selector from the default role's
+ * configured chain — one that is NOT the model that refused. Presentation-only:
+ * reads configured intent, dispatches nothing, and mutates nothing (#4650).
+ *
+ * An entry is named only when the authoritative model selector resolver accepts
+ * it (`resolveSelector` with `allowInvalidThinkingSelectorFallback: false`, so
+ * malformed suffixes like `:bogus` fail closed while route-suffixed IDs keep
+ * their exact-ID semantics) AND the concrete model it resolves to differs from
+ * the refuser.
+ *
+ * The returned selector is RECONSTRUCTED from the resolved model — always
+ * `provider/id` qualified, never the original entry (#4653 review: the hint
+ * resolver runs without usage-preference context, so a bare/fuzzy/glob entry
+ * that resolves here can paste-resolve differently under the real `/model`
+ * command's usage-preference context; a provider-qualified selector pins the
+ * advertised command to exactly the model that was validated). Only a thinking
+ * suffix that itself validated is carried over, so the suggested command is one
+ * the resolver parses with identical semantics.
+ */
+export declare function resolveSafetyStopAlternateSelector(refuserSelector: string | undefined, chain: ModelSelectorValue | readonly string[] | undefined, availableModels: readonly Model[]): string | undefined;
+/**
+ * Bounded guidance shown after a provider safety stop: the failure is
+ * model-specific, the context need not be discarded, and the session continues
+ * after a manual switch. The configured alternate and the canonical manual
+ * switch command are named only when a validated alternate was resolved; the
+ * hint never claims the alternate is guaranteed to accept the same context.
+ */
+export declare function formatProviderSafetyStopHint(alternateSelector: string | undefined): string;
+/**
+ * Resolve the hint to display for a terminal provider safety stop, against the
+ * session's current configured default chain and available catalog. Returns a
+ * hint string for safety stops (static guidance when no valid alternate can be
+ * named) and `undefined` for every other error kind, so unrelated errors keep
+ * their existing rendering untouched.
+ */
+export declare function resolveProviderSafetyStopHint(message: AssistantMessage, session: ProviderSafetyStopHintSession | undefined): string | undefined;
+/**
+ * Compose the display error line for a provider safety stop: the provider's own
+ * refusal text is always retained verbatim, with the hint appended on a new
+ * line. Returns `undefined` for non-safety-stop errors.
+ */
+export declare function formatProviderSafetyStopDisplayError(message: AssistantMessage, alternateSelector: string | undefined): string | undefined;

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

@@ -210,6 +210,14 @@ export declare function transferSessionMessageIdentity(source: AgentMessage[], t
 export interface ThinkingLevelChangeEntry extends SessionEntryBase {
     type: "thinking_level_change";
     thinkingLevel?: string | null;
+    /**
+     * True only when an operator effort surface (`setThinkingLevelForControl`,
+     * Shift+Tab `cycleThinkingLevel`) recorded this entry. Model-driven appends
+     * (model-switch `defaultLevel`, temporary model switches, context clears,
+     * re-applies after model cycling) leave it unset so `getThinkingScopeForControl`
+     * never mints session scope without operator effort intent (issue #4695).
+     */
+    operatorIntent?: boolean;
 }
 export interface ModelChangeEntry extends SessionEntryBase {
     type: "model_change";
@@ -955,6 +963,14 @@ interface ResidentBlobSentinel {
     ref: string;
 }
 export declare function residentBlobSentinelForTests(kind: ResidentBlobKind, ref: string): ResidentBlobSentinel;
+export declare function assertResidentReferencesResolvableForTests(entries: readonly FileEntry[], textStore: BlobStore, imageStore?: BlobStore, binding?: {
+    sessionId?: string;
+    sessionFile?: string;
+}): void;
+export declare function materializeResidentEntriesThrowingForTests<T>(entries: T[], textStore: BlobStore, imageStore?: BlobStore, binding?: {
+    sessionId?: string;
+    sessionFile?: string;
+}): T[];
 export declare function materializeResidentEntriesForPersistenceForTests<T>(entries: T[], textStore: BlobStore, imageStore?: BlobStore): T[];
 /** Get recent sessions for display in welcome screen */
 export declare function getRecentSessions(sessionDir: string, limit?: number, storage?: SessionStorage): Promise<RecentSessionInfo[]>;
@@ -1277,7 +1293,7 @@ export declare class SessionManager {
      */
     appendMessage(message: Message | CustomMessage | HookMessage | BashExecutionMessage | PythonExecutionMessage | FileMentionMessage): string;
     /** Append a thinking level change as child of current leaf, then advance leaf. Returns entry id. */
-    appendThinkingLevelChange(thinkingLevel?: string): string;
+    appendThinkingLevelChange(thinkingLevel?: string, operatorIntent?: boolean): string;
     appendServiceTierChange(serviceTier: ServiceTier | null): string;
     /** Append a mode change as child of current leaf, then advance leaf. Returns entry id. */
     appendModeChange(mode: string, data?: Record<string, unknown>): string;

package/dist/types/tools/ask.d.ts

@@ -87,6 +87,14 @@ export declare class AskTool implements AgentTool<AskParametersSchema, AskToolDe
     readonly rawArgumentValidation: (arguments_: Record<string, unknown>) => RawArgumentValidationResult;
     readonly strict = true;
     readonly loadMode = "discoverable";
+    /**
+     * The only ask argument fields rendered to the user as display text: the
+     * question wording and the option labels. Everything else — ids,
+     * deep-interview metadata (intent contracts/reviews, references), workflow
+     * gate metadata — is structured or durable and stays subject to the
+     * fail-closed escaped-non-ASCII rejection even after the resample budget.
+     */
+    readonly displaySafeEscapedArgFields: readonly ["questions.question", "questions.options.label"];
     constructor(session: ToolSession);
     static createIf(session: ToolSession): AskTool | null;
     execute(_toolCallId: string, params: AskParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<AskToolDetails>, context?: AgentToolContext): Promise<AgentToolResult<AskToolDetails>>;

package/dist/types/tools/index.d.ts

@@ -172,6 +172,8 @@ export interface ToolSession {
     requestForegroundBashBackground?: () => boolean;
     /** Get the session-owned or inherited async job manager. */
     getAsyncJobManager?: () => AsyncJobManager | undefined;
+    /** Resolves when the session queues user steering (or `signal` aborts) without consuming it; wait-style tools use this to end their observation early. */
+    waitForUserSteering?: (signal: AbortSignal) => Promise<void>;
     /** Get session ID */
     getSessionId?: () => string | null;
     /** Get credential-selection session identity. */

package/dist/types/utils/herdr-pane.d.ts

@@ -11,6 +11,13 @@ export interface HerdrReportProcess {
 export interface HerdrReporterOptions {
     env?: NodeJS.ProcessEnv;
     which?: (command: string) => string | null;
+    /** Identity written into the ownership marker. Injectable so the nested-process
+     * case is testable without actually forking. */
+    pid?: number;
+    /** OS process incarnation probe, injectable for PID-reuse and recovery tests. */
+    processIncarnation?: (pid: number) => string | undefined;
+    /** Process liveness/incarnation probe, injectable for cross-platform recovery tests. */
+    processProbe?: (pid: number) => HerdrProcessProbe;
     spawn?: (command: string[], options: {
         env: NodeJS.ProcessEnv;
         stdin: "ignore";
@@ -18,6 +25,14 @@ export interface HerdrReporterOptions {
         stderr: "ignore";
     }) => HerdrReportProcess;
 }
+export type HerdrProcessProbe = {
+    state: "live";
+    incarnation: string;
+} | {
+    state: "absent";
+} | {
+    state: "unverifiable";
+};
 /** Session event shape consumed by the reporter. Narrow on purpose: the state
  * machine is driven only by lifecycle transitions, never by message content. */
 export interface HerdrSessionEvent {
@@ -41,6 +56,9 @@ export interface HerdrReporter {
  * unverified path scavenged from an install layout is a command this process
  * would execute, and PATH/`HERDR_BIN_PATH` are the trust boundary Herdr itself
  * documents.
+ *
+ * Also returns null when an ancestor gjc already owns this pane, so a nested
+ * invocation reports nothing at all.
  */
 export declare function resolveHerdrPaneEnvironment(options?: HerdrReporterOptions): HerdrPaneEnvironment | null;
 /** Build the argv for a state report. Exported for tests. */
@@ -63,11 +81,6 @@ export declare function buildHerdrClearTitleArgs(paneId: string, seq: number): s
  * instead of flickering to a placeholder during startup or a rename.
  */
 export declare function syncHerdrPaneTitle(sessionName: string | undefined, options?: HerdrReporterOptions): void;
-/**
- * Create a reporter bound to a pane. `subscribe` supplies the session event
- * stream and is parameterized so the state machine is testable without a live
- * session.
- */
 export declare function createHerdrReporter(paneEnv: HerdrPaneEnvironment, subscribe: (listener: (event: HerdrSessionEvent) => void) => () => void, options?: HerdrReporterOptions): HerdrReporter;
 /**
  * Install the Herdr reporter for a running session. No-op outside a Herdr pane.