@modelprofile.com/flexharness 12.4.0 → 13.0.0

package/readme.md

@@ -693,7 +693,7 @@ await harness.dispose();
 
 Only one run may be active in a session. Additional prompts enter a bounded FIFO owned by FlexHarness, while different sessions can run concurrently. `enqueuePrompt()` resolves with `{ queueId, completion }` after the immutable prompt and options have been accepted into that runtime queue and `prompt.queued` has been emitted. `startPrompt()` keeps its durable-admission behavior: it waits for its FIFO turn and resolves with `{ queueId, runId, completion }` only after the canonical generation claim, run ID, and initial public audit messages have been durably reserved and the corresponding start events have been emitted. `prompt()` preserves the simpler behavior by awaiting completion internally.
 
-Queue entries expose `queued`, `starting`, `scheduled`, `running`, `completed`, `failed`, and `cancelled` status through `getPromptQueueEntry()` and `listPromptQueueEntries()`. The list is ordered by process-local `queueSequence`. `getPromptQueueEntry()` throws `FlexHarnessNotFoundError` for an unknown or evicted ID. `cancelPrompt()` cancels one exact queue ID: a waiting entry leaves the FIFO and releases capacity immediately but remains queryable as `cancelled` until terminal retention evicts it; a promoted entry uses the canonical run cancellation path. Cancelling a terminal entry returns `false`, while an unknown ID throws. `abort()` remains scoped to the currently active run.
+Queue entries expose `queued`, `starting`, `scheduled`, `running`, `completed`, `failed`, and `cancelled` status through `getPromptQueueEntry()` and `listPromptQueueEntries()`. The list is ordered by process-local `queueSequence`. `getPromptQueueEntry()` throws `FlexHarnessNotFoundError` for an unknown or evicted ID. `cancelPrompt()` cancels one exact queue ID: a waiting entry leaves the FIFO and releases capacity immediately but remains queryable as `cancelled` until terminal retention evicts it; a promoted entry uses the canonical run cancellation path and is stopped with the same `FlexHarnessAbortError` ("The run was aborted.") as `abort()`; only a waiting entry is rejected with "The queued prompt was cancelled.". A cancelled run, whether stopped or found interrupted on reload, puts its `error` on the assistant message only; its user message is `cancelled` without an `error`, while a failed run marks both messages. Cancelling a terminal entry returns `false`, while an unknown ID throws. `abort()` remains scoped to the currently active run.
 
 The displayed queue limits are the defaults. Outstanding count and byte limits apply per session and include every non-terminal queued or active prompt until it settles. Pending-admission limits apply to the complete harness while scope aliases are unresolved. Terminal retention applies per session. Exceeding an admission limit throws `FlexHarnessQueueFullError`.
 
@@ -705,7 +705,7 @@ The reservation save is the admission point. A save failure produces no start ev
 
 `listMessagePage()` returns the newest contiguous page in chronological order. `limit` must be an integer from 1 through 50 and defaults to 50. `nextCursor` is opaque, limited to 4096 UTF-8 bytes, bound to the resolved storage namespace and session, and remains stable when newer messages are appended. Mismatched and stale cursors fail validation. Each page carries `startIndex`, the zero-based index of its first message in the session's visible history (for an empty page, the index the page ends at), so a consumer can order and page by absolute position. Appending messages leaves every index unchanged; a branch after an undo reuses the positions of the history it replaces, so a consumer re-reads its pages after `session.history.changed`. `getMessage()` performs an exact lookup. Transfer identifiers are limited to 512 bytes, text and reasoning parts to 96 KiB, complete messages to 480 KiB, and complete page envelopes to 512 KiB. A page may therefore contain fewer messages than requested. Oversized text is truncated and an otherwise oversized parts collection is replaced with an explicit elision marker; metadata that still cannot fit fails validation. Canonical private Agent events are unchanged.
 
-`updateSession()` supports title replacement, explicit title clearing with `null`, and archive state through `archived`. Title-only updates remain available while prompts are queued or running, while permission is pending, and after archival. Requests containing `archived` are rejected while the session has any outstanding prompt or pending permission; a mixed title-and-archive request is rejected atomically without changing the title. Archived sessions expose `archivedAt`. Deleting a session cascades through its complete descendant subtree. One durable root-keyed tombstone group hides every newly affected live session, and the delete also joins any already-separate descendant cleanup groups without rewriting their roots. FlexHarness then cancels queued and active subtree work, emits terminal queue events, waits for admitted initialization, and purges runtime queue status while cleaning runtime and persisted domains child-first. The requested root tombstone is removed last after every domain confirms cleanup; project-management cleanup confirmation is a retained durable project tombstone rather than physical removal. An imported session can hold no project-management state, so its deletion writes no project tombstone. A successful live `deleteSession()` call emits `session.deleted` for each session it newly tombstoned; retries of an existing tombstone and automatic load, retirement, or disposal cleanup emit no deletion events. Direct deletion of a descendant cascades only through that descendant's subtree. Cleanup authority follows the resolved storage namespace, so scope aliases share the same groups. A partial failure retains durable ownership for retry by a later `deleteSession()`, namespace load, `retireScope()`, or `dispose()` call.
+`updateSession()` supports title replacement, explicit title clearing with `null`, and archive state through `archived`. Title-only updates remain available while prompts are queued or running, while permission is pending, and after archival. Requests containing `archived` are rejected while the session has any outstanding prompt or pending permission; a mixed title-and-archive request is rejected atomically without changing the title. Archived sessions expose `archivedAt`. Every session exposes `preview` once a run with prompt text was admitted: its first prompt as one line (whitespace runs collapsed, cut at a character boundary to `maxTitleBytes`), with no model call, so a host can name a session nobody titled (`title || preview`). It is set once, a session stored before previews existed takes it from its first prompt at its next run, and no caller sets or clears it. Deleting a session cascades through its complete descendant subtree. One durable root-keyed tombstone group hides every newly affected live session, and the delete also joins any already-separate descendant cleanup groups without rewriting their roots. FlexHarness then cancels queued and active subtree work, emits terminal queue events, waits for admitted initialization, and purges runtime queue status while cleaning runtime and persisted domains child-first. The requested root tombstone is removed last after every domain confirms cleanup; project-management cleanup confirmation is a retained durable project tombstone rather than physical removal. An imported session can hold no project-management state, so its deletion writes no project tombstone. A successful live `deleteSession()` call emits `session.deleted` for each session it newly tombstoned; retries of an existing tombstone and automatic load, retirement, or disposal cleanup emit no deletion events. Direct deletion of a descendant cascades only through that descendant's subtree. Cleanup authority follows the resolved storage namespace, so scope aliases share the same groups. A partial failure retains durable ownership for retry by a later `deleteSession()`, namespace load, `retireScope()`, or `dispose()` call.
 
 `deleteSessionGenerationCohort()` is the generation-fenced destructive form for controllers. Its `root` and every `authorizedCohort` entry use the exact `{ sessionId, sessionGenerationId, sessionGenerationSequence }` shape. The cohort contains unique entries in strictly ascending `sessionId` order and is limited by `FLEX_SESSION_GENERATION_COHORT_MAX_ENTRIES` (2048). FlexHarness atomically validates the matching root, its complete live subtree, and every retained descendant tombstone group before reserving deletion. A missing or different root generation returns `{ matched: false }` without touching a newer generation; a missing or mismatched cascade entry throws before new tombstoning or cleanup. Extra valid entries do not expand the cascade. A matched partial cleanup remains retryable with the same authority and resolves to `{ matched: true }` when cleanup completes. The existing `deleteSession()` method remains available for callers that intentionally own the complete reusable-ID namespace.
 
@@ -872,11 +872,13 @@ for (const group of info.groups) {
     group.visibility,
     group.affectedWorkspaces,
     group.affectedWorkspacesTruncated,
+    group.barrierCauses,
+    group.reasonCodes,
   );
 }
 ```
 
-The immutable result exposes `undoAvailable`, `redoAvailable`, and groups classified as `candidate`, `barrier`, or `no-change`. Group metadata contains at most 64 unique affected workspaces; `affectedWorkspacesTruncated` is `true` when additional unique descriptors were omitted. It never includes capture IDs or provider references.
+The immutable result exposes `undoAvailable`, `redoAvailable`, and groups classified as `candidate`, `barrier`, or `no-change`. Group metadata contains at most 64 unique affected workspaces; `affectedWorkspacesTruncated` is `true` when additional unique descriptors were omitted. `barrierCauses` states why a barrier blocks traversal, each cause once in this order: `pending` while a capture runs or its outcome is not final, `nonrevertible` for a workspace outcome that cannot be reverted, `transcript-only` for legacy transcript history without a workspace capture; it is empty for candidate and no-change groups (`FLEX_SESSION_REVERSION_BARRIER_CAUSES` lists the order). `reasonCodes` lists the distinct `reasonCode`s of the group's nonrevertible segments in segment order, so an application can say why a turn is not revertible even when its provider named no affected workspace. It never includes capture IDs or provider references.
 
 `workspaceSnapshots` is application-owned. Every context contains `scopeId`, `scope`, `storageKey`, `sessionId`, the required canonical `sessionGenerationId` and `sessionGenerationSequence`, `runId`, deterministic `captureId`, and an `AbortSignal`. Apply contexts additionally contain the normalized `reference`, per-segment `operationId`, and `direction`; release contexts contain the reference. Deleted-session recovery retains the same generation from the durable tombstone, so providers can reject callbacks from an older same-ID generation.
 
@@ -923,7 +925,7 @@ Resolved model identity contains provider and model IDs plus optional display na
 
 Public audit history is safe to send to controllers: attachment parts contain source and size metadata, never inline base64, data URLs, or remote URL payloads. Canonical private Agent events retain those values solely for subsequent model turns.
 
-Sessions expose `idle`, `scheduled`, `running`, `waiting_permission`, `failed`, and `cancelled` status. Persisted non-terminal activity is repaired from canonical Agent generation outcomes after process restart; incomplete messages and parts normalize to `cancelled` unless an accepted hidden terminal stage can be promoted.
+Sessions expose `idle`, `scheduled`, `running`, `waiting_permission`, `failed`, and `cancelled` status. A run stopped by `abort()`, `cancelPrompt()` or a rejected permission leaves its session `cancelled`; only a run that failed leaves it `failed`. Persisted non-terminal activity is repaired from canonical Agent generation outcomes after process restart; incomplete messages and parts normalize to `cancelled` unless an accepted hidden terminal stage can be promoted.
 
 ## Conversation Import
 
@@ -1023,6 +1025,8 @@ Pending requests are runtime-only and queryable with `listPendingPermissions()`.
 
 `always` is invalid when the request has no `rememberKey`. Remembered decisions are persisted before the waiting tool resolves. If persistence fails, the key is rolled back and the request remains pending so the response can be retried. Concurrent response attempts are serialized and exactly one successful response settles a request.
 
+`reject` stops the run as a decision, not as a failure. The waiting tool call fails with `FlexHarnessPermissionRejectedError`, a `FlexHarnessAbortError` with code `FLEX_PERMISSION_REJECTED` and the rejected `permissionId`, and the run ends the way `abort()` or `cancelPrompt()` ends it; the model is not asked to recover. The run's completion rejects with that error. `run.finished` and the finished queue entry have status `cancelled` and an `error` whose `permissionId` names the rejected request. The run's terminal user and assistant messages are `cancelled`; the assistant message carries `rejectedPermissionId` next to its `error`, and so does the session's `activity`; the session's status is `cancelled`, as after a stop. The refused tool part fails with the rejection as its error and carries the same `rejectedPermissionId`. Other permissions still pending in the run are rejected with it, and runs it delegated stop with "The parent run was aborted.". As with a stop, a run rejected after its model produced output stays in future context, where the refused call's result says the permission was rejected. A permission policy `deny` ends the run the same way.
+
 ## Tool Output Safety
 
 FlexHarness wraps every provided tool `execute` method before AgentSession receives it. Direct outputs and every `AsyncIterable` yield are converted into bounded JSON-safe values. Circular references, functions, symbols, bigint values, dates, URLs, and binary values receive deterministic descriptions or records. Returned error objects and unreadable getter values receive fixed descriptions without their original messages. Thrown errors and iterator failures remain failures but are converted to the safe external-error projection before AgentSession observes them.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/flexharness',
-  version: '12.4.0',
+  version: '13.0.0',
   description: 'The FlexHarness toolbox source repository and shared dependency catalog.'
 }

package/ts/classes.flexharness.callbacks.ts

@@ -1,5 +1,5 @@
 import * as plugins from './plugins.js';
-import { FlexHarnessCallbackOverflowError } from './errors.js';
+import { FlexHarnessCallbackOverflowError, FlexHarnessPermissionRejectedError } from './errors.js';
 import {
   FLEX_TOOL_CATALOG_TOOL_NAMES,
   type IFlexReasoningMessagePart,
@@ -26,7 +26,7 @@ import type {
 import type { FlexHarnessCore } from './classes.flexharness.core.js';
 
 /** How a tool call ended, as its part records it. */
-type TToolPartOutcome = { output: TJsonValue } | { error: string };
+type TToolPartOutcome = { output: TJsonValue } | { error: string; rejectedPermissionId?: string };
 
 const outcomeBytes = (outcome: TToolPartOutcome): number =>
   'output' in outcome ? jsonBytes(outcome.output) : Buffer.byteLength(outcome.error);
@@ -328,7 +328,12 @@ export class FlexHarnessRunCallbacks<TScope> {
     if (event.success) {
       return { output: normalizeJsonValue(event.output, { ...this.core.toolOutputLimits, maxBytes: maxOutputBytes }) };
     }
-    return { error: this.core.projectExternalError(run, trustedExecutionError ?? event.error, 'toolCallback').message };
+    return {
+      error: this.core.projectExternalError(run, trustedExecutionError ?? event.error, 'toolCallback').message,
+      ...(trustedExecutionError instanceof FlexHarnessPermissionRejectedError
+        ? { rejectedPermissionId: trustedExecutionError.permissionId }
+        : {}),
+    };
   }
 
   private completeToolPart(
@@ -344,6 +349,7 @@ export class FlexHarnessRunCallbacks<TScope> {
       part.status = 'failed';
       delete part.output;
       part.error = outcome.error;
+      if (outcome.rejectedPermissionId) part.rejectedPermissionId = outcome.rejectedPermissionId;
     }
     const original = run.deduplicatedToolCalls.get(toolCallId);
     if (original !== undefined) {

package/ts/classes.flexharness.core.ts

@@ -1125,7 +1125,8 @@ export class FlexHarnessCore<TScope> {
     }
     if (status !== 'completed') {
       const message = status === 'cancelled' ? repairCancellationMessage : externalErrorFallback.message;
-      userMessage.error = message;
+      // As for a run that ends live: a failed run marks its prompt too, a cancelled one only its answer.
+      if (status === 'failed') userMessage.error = message;
       assistantMessage.error = message;
       if (stage?.usage) {
         assistantMessage.usage = cloneSerializable(stage.usage);

package/ts/classes.flexharness.permissions.ts

@@ -115,10 +115,12 @@ export class FlexHarnessPermissions<TScope> {
         origin: 'policy',
       });
       if (policyDecision === 'deny') {
+        // A policy deny is the session's decision, not a fault: the run stops as cancelled.
         const rejection = this.core.trustInternalError(
           new FlexHarnessPermissionRejectedError(candidate.permissionId),
         );
-        this.core.runs.abortRunInternally(run, rejection);
+        if (candidate.toolCallId) run.trustedToolExecutionErrors.set(candidate.toolCallId, rejection);
+        this.core.runs.cancelRun(run, rejection);
         throw rejection;
       }
       return;
@@ -345,10 +347,14 @@ export class FlexHarnessPermissions<TScope> {
       decision,
     });
     if (decision === 'reject') {
+      // A person's rejection stops the run as cancelled, like an owner's stop, not as a failure.
       const rejection = this.core.trustInternalError(
         new FlexHarnessPermissionRejectedError(pending.request.permissionId),
       );
-      this.core.runs.abortRunInternally(pending.run, rejection, context);
+      // The tool part of the refused call names the rejection rather than a generic failure.
+      const { toolCallId } = pending.request;
+      if (toolCallId) pending.run.trustedToolExecutionErrors.set(toolCallId, rejection);
+      this.core.runs.cancelRun(pending.run, rejection, context);
       pending.reject(rejection);
     } else {
       pending.resolve();

package/ts/classes.flexharness.prompts.ts

@@ -37,6 +37,7 @@ import type {
   IPendingPromptAdmission,
 } from './interfaces.flexharness.js';
 import { combineErrors, isAbortError } from './utils.flexharness.js';
+import { sessionPreview } from './utils.sessionpreview.js';
 import type { FlexHarnessCore } from './classes.flexharness.core.js';
 
 const maxScheduleDebounceMs = 24 * 60 * 60 * 1000;
@@ -188,9 +189,14 @@ export class FlexHarnessPromptQueue<TScope> {
       if (stored.terminalPromptQueueEntries.has(queueId)) return false;
       throw new FlexHarnessNotFoundError('Prompt queue entry', queueId);
     }
+    // Only a prompt still waiting in the FIFO is a cancelled queued prompt. One that started is a
+    // run the owner stopped, and says so exactly as `abort()` does.
+    const reason = queued.status === 'queued'
+      ? new FlexHarnessAbortError('The queued prompt was cancelled.')
+      : new FlexHarnessAbortError();
     return this.cancelQueuedPrompt(
       queued,
-      this.core.trustInternalError(new FlexHarnessAbortError('The queued prompt was cancelled.')),
+      this.core.trustInternalError(reason),
       this.core.compaction.createCompactorContext(scopeId, scope.scope, state.storageKey, sessionId),
     );
   }
@@ -634,6 +640,8 @@ export class FlexHarnessPromptQueue<TScope> {
             startedAt: reservation.userMessage.createdAt,
           };
           run.stored.session.updatedAt = reservation.userMessage.createdAt;
+          const preview = run.stored.session.preview ?? sessionPreview(run.stored.messages);
+          if (preview !== undefined) run.stored.session.preview = preview;
         });
       } catch (error) {
         if (containsStoreCommitUncertainty(error)) run.state.lifecycle = 'fenced';

package/ts/classes.flexharness.reversions.ts

@@ -11,6 +11,7 @@ import {
   FLEX_REVERSION_REASON_CODE_MAX_BYTES,
   FLEX_REVERSION_REFERENCE_MAX_BYTES,
   FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES,
+  FLEX_SESSION_REVERSION_BARRIER_CAUSES,
   FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES,
   type IFlexAgentContextInvocation,
   type IFlexAffectedWorkspace,
@@ -24,6 +25,7 @@ import {
   type IFlexSessionTombstone,
   type IFlexUndoSessionResult,
   type TFlexProjectionSnapshot,
+  type TFlexSessionReversionBarrierCause,
   type TFlexTurnReversionFinalizedOutcome,
   type TJsonValue,
 } from './interfaces.js';
@@ -81,6 +83,8 @@ export class FlexHarnessReversions<TScope> {
         visibility: index < stored.revertCursor ? 'visible' : 'hidden',
         affectedWorkspaces: cloneSerializable(group.affectedWorkspaces),
         affectedWorkspacesTruncated: group.affectedWorkspacesTruncated,
+        barrierCauses: [...group.barrierCauses],
+        reasonCodes: [...group.reasonCodes],
       })),
     });
   }
@@ -143,6 +147,8 @@ export class FlexHarnessReversions<TScope> {
           kind: 'candidate',
           affectedWorkspaces: [],
           affectedWorkspacesTruncated: false,
+          barrierCauses: [],
+          reasonCodes: [],
         });
       } else if (groups.length > 0) {
         groups[groups.length - 1].segments.push(segment);
@@ -162,13 +168,23 @@ export class FlexHarnessReversions<TScope> {
         }
       }
       group.affectedWorkspaces = [...affected.values()];
+      group.reasonCodes = [...new Set(group.segments.flatMap((segment) => (
+        segment.disposition === 'nonrevertible' && segment.reasonCode !== undefined
+          ? [segment.reasonCode]
+          : []
+      )))];
       if (this.core.reversionPolicy === 'transcript-optional') continue;
-      if (group.segments.some((segment) =>
-        segment.status === 'capturing'
-        || segment.disposition === 'pending'
-        || (segment.protocolVersion === 1 && segment.provenance === 'transcript')
-        || segment.disposition === 'nonrevertible')) {
+      const causes = new Set<TFlexSessionReversionBarrierCause>();
+      for (const segment of group.segments) {
+        if (segment.status === 'capturing' || segment.disposition === 'pending') causes.add('pending');
+        if (segment.disposition === 'nonrevertible') causes.add('nonrevertible');
+        if (segment.protocolVersion === 1 && segment.provenance === 'transcript') {
+          causes.add('transcript-only');
+        }
+      }
+      if (causes.size > 0) {
         group.kind = 'barrier';
+        group.barrierCauses = FLEX_SESSION_REVERSION_BARRIER_CAUSES.filter((cause) => causes.has(cause));
       } else if (group.segments.some((segment) => segment.disposition === 'revertible')) {
         group.kind = 'candidate';
       } else {

package/ts/classes.flexharness.runs.ts

@@ -3,6 +3,7 @@ import {
   FlexHarnessAbortError,
   FlexHarnessExternalError,
   FlexHarnessNotFoundError,
+  FlexHarnessPermissionRejectedError,
   FlexHarnessRunError,
   FlexHarnessStepLimitError,
   FlexHarnessValidationError,
@@ -53,6 +54,7 @@ import {
   externalErrorFallback,
   requireSessionGeneration,
   combineErrors,
+  delegatedCancellation,
   terminalActivityError,
 } from './utils.flexharness.js';
 import type { FlexHarnessCore } from './classes.flexharness.core.js';
@@ -664,9 +666,8 @@ export class FlexHarnessRuns<TScope> {
     if (!active || active.runId !== runId || active.phase === 'finalizing' || active.phase === 'promoting') {
       return false;
     }
-    const cancellation = reason instanceof FlexHarnessAbortError
-      ? reason
-      : this.core.trustInternalError(new FlexHarnessAbortError('The parent run was aborted.'));
+    const cancellation = delegatedCancellation(reason)
+      ?? this.core.trustInternalError(new FlexHarnessAbortError('The parent run was aborted.'));
     this.cancelRun(active, cancellation);
     return true;
   }
@@ -914,9 +915,15 @@ export class FlexHarnessRuns<TScope> {
       assistantMessage.usage = cloneSerializable(run.usage);
       const message = truncateUtf8(error?.message ?? externalErrorFallback.message, maxTransferMetadataBytes);
       const limit = error instanceof FlexHarnessExternalError ? error.limit : undefined;
-      for (const failedMessage of [userMessage, assistantMessage]) {
+      const rejectedPermissionId = error instanceof FlexHarnessPermissionRejectedError
+        ? error.permissionId
+        : undefined;
+      // A failed turn fails its prompt too. A stopped turn is no fault of its prompt, so the prompt
+      // stays an ordinary user message and only the answer it stopped carries the stop.
+      for (const failedMessage of status === 'cancelled' ? [assistantMessage] : [userMessage, assistantMessage]) {
         failedMessage.error = message;
         if (limit) failedMessage.limit = cloneSerializable(limit);
+        if (rejectedPermissionId) failedMessage.rejectedPermissionId = rejectedPermissionId;
       }
     }
     return {

package/ts/classes.flexharness.subagents.ts

@@ -41,6 +41,7 @@ import {
   requireSessionGeneration,
   sha256Hex,
   combineErrors,
+  delegatedCancellation,
 } from './utils.flexharness.js';
 import type { FlexHarnessCore } from './classes.flexharness.core.js';
 
@@ -379,9 +380,8 @@ export class FlexHarnessSubagents<TScope> {
     let queued: Awaited<ReturnType<typeof this.core.prompts.enqueuePromptInternal>> | undefined;
     let admission: IFlexPromptAdmission | undefined;
     const abortChild = () => {
-      const reason = run.controller.signal.reason instanceof FlexHarnessAbortError
-        ? run.controller.signal.reason
-        : this.core.trustInternalError(new FlexHarnessAbortError('The parent run was aborted.'));
+      const reason = delegatedCancellation(run.controller.signal.reason)
+        ?? this.core.trustInternalError(new FlexHarnessAbortError('The parent run was aborted.'));
       const ownedChild = child ?? run.state.sessions.get(reservedSessionId);
       if (
         ownedChild

package/ts/errors.ts

@@ -112,8 +112,9 @@ export class FlexHarnessQueueFullError extends FlexHarnessError {
 }
 
 export class FlexHarnessAbortError extends FlexHarnessError {
-  constructor(message = 'The run was aborted.', options?: ErrorOptions) {
-    super('FLEX_ABORTED', message, options);
+  /** `code` names a more specific stop for a subclass, such as a rejected permission. */
+  constructor(message = 'The run was aborted.', options?: ErrorOptions, code = 'FLEX_ABORTED') {
+    super(code, message, options);
     this.name = 'FlexHarnessAbortError';
   }
 }
@@ -143,10 +144,17 @@ export class FlexHarnessExternalError extends FlexHarnessError {
   }
 }
 
-export class FlexHarnessPermissionRejectedError extends FlexHarnessError {
+/**
+ * A permission was rejected, by a `reject` response or by the session's permission policy. The
+ * rejection is a decision, not a fault: it stops the run like an owner's cancellation.
+ */
+export class FlexHarnessPermissionRejectedError extends FlexHarnessAbortError {
+  public readonly permissionId: string;
+
   constructor(permissionId: string, options?: ErrorOptions) {
-    super('FLEX_PERMISSION_REJECTED', `Permission "${permissionId}" was rejected.`, options);
+    super(`Permission "${permissionId}" was rejected.`, options, 'FLEX_PERMISSION_REJECTED');
     this.name = 'FlexHarnessPermissionRejectedError';
+    this.permissionId = permissionId;
   }
 }
 
@@ -247,6 +255,7 @@ export function errorToInfo(error: unknown): IFlexErrorInfo {
       message: error.message,
       code: error.code,
       ...(error instanceof FlexHarnessExternalError && error.limit ? { limit: error.limit } : {}),
+      ...(error instanceof FlexHarnessPermissionRejectedError ? { permissionId: error.permissionId } : {}),
     };
   }
   if (error instanceof Error) {

package/ts/interfaces.flexharness.ts

@@ -35,6 +35,7 @@ import type {
   TFlexPromptQueueStatus,
   TFlexPendingReversion,
   TFlexProjectionSnapshot,
+  TFlexSessionReversionBarrierCause,
   TFlexSessionReversionGroupKind,
   TFlexTurnReversionFinalizedOutcome,
 } from './interfaces.js';
@@ -114,6 +115,8 @@ export interface IReversionGroup {
   kind: TFlexSessionReversionGroupKind;
   affectedWorkspaces: IFlexAffectedWorkspace[];
   affectedWorkspacesTruncated: boolean;
+  barrierCauses: TFlexSessionReversionBarrierCause[];
+  reasonCodes: string[];
 }
 
 export type TNormalizedCaptureInspection =

package/ts/interfaces.ts

@@ -174,6 +174,8 @@ export interface IFlexToolMessagePart {
    * did not run; its output is the earlier call's.
    */
   deduplicatedFrom?: string;
+  /** For a failed call whose permission was rejected: the rejected request's `permissionId`. */
+  rejectedPermissionId?: string;
   model?: IFlexModelIdentity;
   /** ISO time the tool call began. Absent on parts recorded before part times existed. */
   startedAt?: string;
@@ -216,6 +218,8 @@ export interface IFlexMessage {
   error?: string;
   /** The model limit that failed this run, next to its error. */
   limit?: TFlexModelLimit;
+  /** The permission whose rejection stopped this run, next to its error. */
+  rejectedPermissionId?: string;
   /** On a user message that steered its running run: the caller's steer identity. */
   steerId?: string;
 }
@@ -228,6 +232,8 @@ export interface IFlexSessionActivity {
   error?: string;
   /** The model limit that failed the last run, next to its error. */
   limit?: TFlexModelLimit;
+  /** The permission whose rejection stopped the last run, next to its error. */
+  rejectedPermissionId?: string;
 }
 
 export interface IFlexSession {
@@ -238,6 +244,13 @@ export interface IFlexSession {
   /** Opaque immutable configuration revision bound to this exact session generation. */
   configurationRef?: string;
   title?: string;
+  /**
+   * The session's first prompt as one line, bounded like a title (`maxTitleBytes`), so a session
+   * nobody titled can still be named. The harness sets it when the first run with prompt text is
+   * admitted, and for a session stored before previews existed at its next run; it never changes
+   * afterwards and is never set by a caller. Absent until then.
+   */
+  preview?: string;
   createdAt: string;
   updatedAt: string;
   archivedAt?: string;
@@ -1696,12 +1709,30 @@ export type TFlexReversionPolicy = 'transcript-optional' | 'workspace-required';
 
 export type TFlexSessionReversionGroupKind = 'candidate' | 'barrier' | 'no-change';
 
+/**
+ * Why a group is a barrier: `pending` while a capture runs or its outcome is not final,
+ * `nonrevertible` for a workspace outcome that cannot be reverted, `transcript-only` for legacy
+ * transcript history without a workspace capture.
+ */
+export type TFlexSessionReversionBarrierCause = 'pending' | 'nonrevertible' | 'transcript-only';
+
+/** The barrier causes in the order a group lists them. */
+export const FLEX_SESSION_REVERSION_BARRIER_CAUSES: readonly TFlexSessionReversionBarrierCause[] = [
+  'pending',
+  'nonrevertible',
+  'transcript-only',
+];
+
 export interface IFlexSessionReversionGroup {
   readonly runId: string;
   readonly kind: TFlexSessionReversionGroupKind;
   readonly visibility: 'visible' | 'hidden';
   readonly affectedWorkspaces: readonly IFlexAffectedWorkspace[];
   readonly affectedWorkspacesTruncated: boolean;
+  /** Each cause of a barrier once, in the order of the type; empty for every other kind. */
+  readonly barrierCauses: readonly TFlexSessionReversionBarrierCause[];
+  /** The distinct reason codes of the group's nonrevertible segments, in segment order. */
+  readonly reasonCodes: readonly string[];
 }
 
 export interface IFlexSessionReversionInfo {
@@ -2128,6 +2159,8 @@ export interface IFlexErrorInfo {
   code?: string;
   /** Set when a model usage or rate limit caused the error. */
   limit?: TFlexModelLimit;
+  /** Set when a rejected permission stopped the run: the rejected request's `permissionId`. */
+  permissionId?: string;
 }
 
 export type TFlexHarnessEvent =

package/ts/readme.md

@@ -693,7 +693,7 @@ await harness.dispose();
 
 Only one run may be active in a session. Additional prompts enter a bounded FIFO owned by FlexHarness, while different sessions can run concurrently. `enqueuePrompt()` resolves with `{ queueId, completion }` after the immutable prompt and options have been accepted into that runtime queue and `prompt.queued` has been emitted. `startPrompt()` keeps its durable-admission behavior: it waits for its FIFO turn and resolves with `{ queueId, runId, completion }` only after the canonical generation claim, run ID, and initial public audit messages have been durably reserved and the corresponding start events have been emitted. `prompt()` preserves the simpler behavior by awaiting completion internally.
 
-Queue entries expose `queued`, `starting`, `scheduled`, `running`, `completed`, `failed`, and `cancelled` status through `getPromptQueueEntry()` and `listPromptQueueEntries()`. The list is ordered by process-local `queueSequence`. `getPromptQueueEntry()` throws `FlexHarnessNotFoundError` for an unknown or evicted ID. `cancelPrompt()` cancels one exact queue ID: a waiting entry leaves the FIFO and releases capacity immediately but remains queryable as `cancelled` until terminal retention evicts it; a promoted entry uses the canonical run cancellation path. Cancelling a terminal entry returns `false`, while an unknown ID throws. `abort()` remains scoped to the currently active run.
+Queue entries expose `queued`, `starting`, `scheduled`, `running`, `completed`, `failed`, and `cancelled` status through `getPromptQueueEntry()` and `listPromptQueueEntries()`. The list is ordered by process-local `queueSequence`. `getPromptQueueEntry()` throws `FlexHarnessNotFoundError` for an unknown or evicted ID. `cancelPrompt()` cancels one exact queue ID: a waiting entry leaves the FIFO and releases capacity immediately but remains queryable as `cancelled` until terminal retention evicts it; a promoted entry uses the canonical run cancellation path and is stopped with the same `FlexHarnessAbortError` ("The run was aborted.") as `abort()`; only a waiting entry is rejected with "The queued prompt was cancelled.". A cancelled run, whether stopped or found interrupted on reload, puts its `error` on the assistant message only; its user message is `cancelled` without an `error`, while a failed run marks both messages. Cancelling a terminal entry returns `false`, while an unknown ID throws. `abort()` remains scoped to the currently active run.
 
 The displayed queue limits are the defaults. Outstanding count and byte limits apply per session and include every non-terminal queued or active prompt until it settles. Pending-admission limits apply to the complete harness while scope aliases are unresolved. Terminal retention applies per session. Exceeding an admission limit throws `FlexHarnessQueueFullError`.
 
@@ -705,7 +705,7 @@ The reservation save is the admission point. A save failure produces no start ev
 
 `listMessagePage()` returns the newest contiguous page in chronological order. `limit` must be an integer from 1 through 50 and defaults to 50. `nextCursor` is opaque, limited to 4096 UTF-8 bytes, bound to the resolved storage namespace and session, and remains stable when newer messages are appended. Mismatched and stale cursors fail validation. Each page carries `startIndex`, the zero-based index of its first message in the session's visible history (for an empty page, the index the page ends at), so a consumer can order and page by absolute position. Appending messages leaves every index unchanged; a branch after an undo reuses the positions of the history it replaces, so a consumer re-reads its pages after `session.history.changed`. `getMessage()` performs an exact lookup. Transfer identifiers are limited to 512 bytes, text and reasoning parts to 96 KiB, complete messages to 480 KiB, and complete page envelopes to 512 KiB. A page may therefore contain fewer messages than requested. Oversized text is truncated and an otherwise oversized parts collection is replaced with an explicit elision marker; metadata that still cannot fit fails validation. Canonical private Agent events are unchanged.
 
-`updateSession()` supports title replacement, explicit title clearing with `null`, and archive state through `archived`. Title-only updates remain available while prompts are queued or running, while permission is pending, and after archival. Requests containing `archived` are rejected while the session has any outstanding prompt or pending permission; a mixed title-and-archive request is rejected atomically without changing the title. Archived sessions expose `archivedAt`. Deleting a session cascades through its complete descendant subtree. One durable root-keyed tombstone group hides every newly affected live session, and the delete also joins any already-separate descendant cleanup groups without rewriting their roots. FlexHarness then cancels queued and active subtree work, emits terminal queue events, waits for admitted initialization, and purges runtime queue status while cleaning runtime and persisted domains child-first. The requested root tombstone is removed last after every domain confirms cleanup; project-management cleanup confirmation is a retained durable project tombstone rather than physical removal. An imported session can hold no project-management state, so its deletion writes no project tombstone. A successful live `deleteSession()` call emits `session.deleted` for each session it newly tombstoned; retries of an existing tombstone and automatic load, retirement, or disposal cleanup emit no deletion events. Direct deletion of a descendant cascades only through that descendant's subtree. Cleanup authority follows the resolved storage namespace, so scope aliases share the same groups. A partial failure retains durable ownership for retry by a later `deleteSession()`, namespace load, `retireScope()`, or `dispose()` call.
+`updateSession()` supports title replacement, explicit title clearing with `null`, and archive state through `archived`. Title-only updates remain available while prompts are queued or running, while permission is pending, and after archival. Requests containing `archived` are rejected while the session has any outstanding prompt or pending permission; a mixed title-and-archive request is rejected atomically without changing the title. Archived sessions expose `archivedAt`. Every session exposes `preview` once a run with prompt text was admitted: its first prompt as one line (whitespace runs collapsed, cut at a character boundary to `maxTitleBytes`), with no model call, so a host can name a session nobody titled (`title || preview`). It is set once, a session stored before previews existed takes it from its first prompt at its next run, and no caller sets or clears it. Deleting a session cascades through its complete descendant subtree. One durable root-keyed tombstone group hides every newly affected live session, and the delete also joins any already-separate descendant cleanup groups without rewriting their roots. FlexHarness then cancels queued and active subtree work, emits terminal queue events, waits for admitted initialization, and purges runtime queue status while cleaning runtime and persisted domains child-first. The requested root tombstone is removed last after every domain confirms cleanup; project-management cleanup confirmation is a retained durable project tombstone rather than physical removal. An imported session can hold no project-management state, so its deletion writes no project tombstone. A successful live `deleteSession()` call emits `session.deleted` for each session it newly tombstoned; retries of an existing tombstone and automatic load, retirement, or disposal cleanup emit no deletion events. Direct deletion of a descendant cascades only through that descendant's subtree. Cleanup authority follows the resolved storage namespace, so scope aliases share the same groups. A partial failure retains durable ownership for retry by a later `deleteSession()`, namespace load, `retireScope()`, or `dispose()` call.
 
 `deleteSessionGenerationCohort()` is the generation-fenced destructive form for controllers. Its `root` and every `authorizedCohort` entry use the exact `{ sessionId, sessionGenerationId, sessionGenerationSequence }` shape. The cohort contains unique entries in strictly ascending `sessionId` order and is limited by `FLEX_SESSION_GENERATION_COHORT_MAX_ENTRIES` (2048). FlexHarness atomically validates the matching root, its complete live subtree, and every retained descendant tombstone group before reserving deletion. A missing or different root generation returns `{ matched: false }` without touching a newer generation; a missing or mismatched cascade entry throws before new tombstoning or cleanup. Extra valid entries do not expand the cascade. A matched partial cleanup remains retryable with the same authority and resolves to `{ matched: true }` when cleanup completes. The existing `deleteSession()` method remains available for callers that intentionally own the complete reusable-ID namespace.
 
@@ -872,11 +872,13 @@ for (const group of info.groups) {
     group.visibility,
     group.affectedWorkspaces,
     group.affectedWorkspacesTruncated,
+    group.barrierCauses,
+    group.reasonCodes,
   );
 }
 ```
 
-The immutable result exposes `undoAvailable`, `redoAvailable`, and groups classified as `candidate`, `barrier`, or `no-change`. Group metadata contains at most 64 unique affected workspaces; `affectedWorkspacesTruncated` is `true` when additional unique descriptors were omitted. It never includes capture IDs or provider references.
+The immutable result exposes `undoAvailable`, `redoAvailable`, and groups classified as `candidate`, `barrier`, or `no-change`. Group metadata contains at most 64 unique affected workspaces; `affectedWorkspacesTruncated` is `true` when additional unique descriptors were omitted. `barrierCauses` states why a barrier blocks traversal, each cause once in this order: `pending` while a capture runs or its outcome is not final, `nonrevertible` for a workspace outcome that cannot be reverted, `transcript-only` for legacy transcript history without a workspace capture; it is empty for candidate and no-change groups (`FLEX_SESSION_REVERSION_BARRIER_CAUSES` lists the order). `reasonCodes` lists the distinct `reasonCode`s of the group's nonrevertible segments in segment order, so an application can say why a turn is not revertible even when its provider named no affected workspace. It never includes capture IDs or provider references.
 
 `workspaceSnapshots` is application-owned. Every context contains `scopeId`, `scope`, `storageKey`, `sessionId`, the required canonical `sessionGenerationId` and `sessionGenerationSequence`, `runId`, deterministic `captureId`, and an `AbortSignal`. Apply contexts additionally contain the normalized `reference`, per-segment `operationId`, and `direction`; release contexts contain the reference. Deleted-session recovery retains the same generation from the durable tombstone, so providers can reject callbacks from an older same-ID generation.
 
@@ -923,7 +925,7 @@ Resolved model identity contains provider and model IDs plus optional display na
 
 Public audit history is safe to send to controllers: attachment parts contain source and size metadata, never inline base64, data URLs, or remote URL payloads. Canonical private Agent events retain those values solely for subsequent model turns.
 
-Sessions expose `idle`, `scheduled`, `running`, `waiting_permission`, `failed`, and `cancelled` status. Persisted non-terminal activity is repaired from canonical Agent generation outcomes after process restart; incomplete messages and parts normalize to `cancelled` unless an accepted hidden terminal stage can be promoted.
+Sessions expose `idle`, `scheduled`, `running`, `waiting_permission`, `failed`, and `cancelled` status. A run stopped by `abort()`, `cancelPrompt()` or a rejected permission leaves its session `cancelled`; only a run that failed leaves it `failed`. Persisted non-terminal activity is repaired from canonical Agent generation outcomes after process restart; incomplete messages and parts normalize to `cancelled` unless an accepted hidden terminal stage can be promoted.
 
 ## Conversation Import
 
@@ -1023,6 +1025,8 @@ Pending requests are runtime-only and queryable with `listPendingPermissions()`.
 
 `always` is invalid when the request has no `rememberKey`. Remembered decisions are persisted before the waiting tool resolves. If persistence fails, the key is rolled back and the request remains pending so the response can be retried. Concurrent response attempts are serialized and exactly one successful response settles a request.
 
+`reject` stops the run as a decision, not as a failure. The waiting tool call fails with `FlexHarnessPermissionRejectedError`, a `FlexHarnessAbortError` with code `FLEX_PERMISSION_REJECTED` and the rejected `permissionId`, and the run ends the way `abort()` or `cancelPrompt()` ends it; the model is not asked to recover. The run's completion rejects with that error. `run.finished` and the finished queue entry have status `cancelled` and an `error` whose `permissionId` names the rejected request. The run's terminal user and assistant messages are `cancelled`; the assistant message carries `rejectedPermissionId` next to its `error`, and so does the session's `activity`; the session's status is `cancelled`, as after a stop. The refused tool part fails with the rejection as its error and carries the same `rejectedPermissionId`. Other permissions still pending in the run are rejected with it, and runs it delegated stop with "The parent run was aborted.". As with a stop, a run rejected after its model produced output stays in future context, where the refused call's result says the permission was rejected. A permission policy `deny` ends the run the same way.
+
 ## Tool Output Safety
 
 FlexHarness wraps every provided tool `execute` method before AgentSession receives it. Direct outputs and every `AsyncIterable` yield are converted into bounded JSON-safe values. Circular references, functions, symbols, bigint values, dates, URLs, and binary values receive deterministic descriptions or records. Returned error objects and unreadable getter values receive fixed descriptions without their original messages. Thrown errors and iterator failures remain failures but are converted to the safe external-error projection before AgentSession observes them.

package/ts/utils.flexharness.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import {
   FlexHarnessAbortError,
+  FlexHarnessPermissionRejectedError,
   FlexHarnessRunError,
   FlexHarnessValidationError,
 } from './errors.js';
@@ -106,14 +107,27 @@ export function combineErrors(errors: unknown[]): unknown {
   return Object.freeze(combined);
 }
 
-/** The error and model limit a finished run leaves on its session activity. */
-export function terminalActivityError(message: IFlexMessage): Pick<IFlexSessionActivity, 'error' | 'limit'> {
+/** The error, model limit and rejected permission a finished run leaves on its session activity. */
+export function terminalActivityError(
+  message: IFlexMessage,
+): Pick<IFlexSessionActivity, 'error' | 'limit' | 'rejectedPermissionId'> {
   return {
     ...(message.error ? { error: message.error } : {}),
     ...(message.limit ? { limit: message.limit } : {}),
+    ...(message.rejectedPermissionId ? { rejectedPermissionId: message.rejectedPermissionId } : {}),
   };
 }
 
+/**
+ * The parent run's cancellation when the runs it delegated share it: a stop stops them alike, but a
+ * permission the parent rejected is the parent's own.
+ */
+export function delegatedCancellation(reason: unknown): FlexHarnessAbortError | undefined {
+  return reason instanceof FlexHarnessAbortError && !(reason instanceof FlexHarnessPermissionRejectedError)
+    ? reason
+    : undefined;
+}
+
 export function isAbortError(error: unknown): boolean {
   return error instanceof FlexHarnessAbortError
     || (error instanceof DOMException && error.name === 'AbortError')

package/ts/utils.json.ts

@@ -533,6 +533,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
       'sessionGenerationSequence',
       'configurationRef',
       'title',
+      'preview',
       'createdAt',
       'updatedAt',
       'archivedAt',
@@ -555,6 +556,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
     throw new FlexHarnessStoreFormatError(`${path}.configurationRef is invalid.`);
   }
   requireOptionalString(session.title, `${path}.title`);
+  requireOptionalString(session.preview, `${path}.preview`);
   requireString(session.createdAt, `${path}.createdAt`);
   requireString(session.updatedAt, `${path}.updatedAt`);
   requireOptionalString(session.archivedAt, `${path}.archivedAt`);
@@ -562,7 +564,11 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
     throw new FlexHarnessStoreFormatError(`${path}.status is invalid.`);
   }
   const activity = requireRecord(session.activity, `${path}.activity`);
-  requireOnlyKeys(activity, ['runId', 'status', 'startedAt', 'completedAt', 'error', 'limit'], `${path}.activity`);
+  requireOnlyKeys(
+    activity,
+    ['runId', 'status', 'startedAt', 'completedAt', 'error', 'limit', 'rejectedPermissionId'],
+    `${path}.activity`,
+  );
   if (!activityStatuses.includes(activity.status as (typeof activityStatuses)[number])) {
     throw new FlexHarnessStoreFormatError(`${path}.activity.status is invalid.`);
   }
@@ -571,6 +577,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   requireOptionalString(activity.completedAt, `${path}.activity.completedAt`);
   requireOptionalString(activity.error, `${path}.activity.error`);
   requireOptionalModelLimit(activity.limit, `${path}.activity.limit`);
+  requireOptionalString(activity.rejectedPermissionId, `${path}.activity.rejectedPermissionId`);
   const relationship = [
     session.parentSessionId,
     session.parentRunId,
@@ -767,6 +774,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
       'usage',
       'error',
       'limit',
+      'rejectedPermissionId',
       'steerId',
     ],
     path,
@@ -784,6 +792,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
   requireOptionalString(message.completedAt, `${path}.completedAt`);
   requireOptionalString(message.error, `${path}.error`);
   requireOptionalModelLimit(message.limit, `${path}.limit`);
+  requireOptionalString(message.rejectedPermissionId, `${path}.rejectedPermissionId`);
   if (message.steerId !== undefined) {
     requireString(message.steerId, `${path}.steerId`);
     if (message.role !== 'user') {
@@ -834,6 +843,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
           'childSessionId',
           'parentToolCallId',
           'deduplicatedFrom',
+          'rejectedPermissionId',
           'model',
           'startedAt',
           'completedAt',
@@ -852,6 +862,7 @@ function validateMessage(value: unknown, path: string): IValidatedMessageIdentit
       requireOptionalString(part.childSessionId, `${partPath}.childSessionId`);
       requireOptionalString(part.parentToolCallId, `${partPath}.parentToolCallId`);
       requireOptionalString(part.deduplicatedFrom, `${partPath}.deduplicatedFrom`);
+      requireOptionalString(part.rejectedPermissionId, `${partPath}.rejectedPermissionId`);
       if (part.model !== undefined) validateModel(part.model, `${partPath}.model`);
       requireOptionalString(part.startedAt, `${partPath}.startedAt`);
       requireOptionalString(part.completedAt, `${partPath}.completedAt`);