@springbrand/agent-runtime 0.3.0-alpha.16 → 0.3.0-alpha.18

package/src/session/cloudflare/storage.ts

@@ -1,537 +1,14 @@
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import {
-  prepareStorageCommit,
-  validateCommittedWrites,
-  resolveListReadOptions,
-  value,
-  branchTip,
-  setValue,
-  insertEntry,
-  insertUsage,
-  type Storage,
-  type Write,
-  type CommitResult,
-  type Entry,
-  type EntryStructure,
-  type EntryScan,
-  type StorageBranchScan,
-  type UsageRow,
-  type UsageScan,
-  type Value,
-  type ValueList,
-  type StoredValue,
-  type ListElement,
-  type ListReadOptions,
-  type SessionStats,
-  type SessionMetadata,
-} from "@earendil-works/pi-agent-core/harness/session";
-import type { Context } from "@earendil-works/pi-agent-core/harness/context";
-
-export const CURRENT_PI_STORAGE_VERSION = 3;
-
-/** Pi's Storage contract, with every physical commit confined to one DO transaction. */
-export class CloudflareSessionStorage implements Storage {
-  private closed = false;
-  private readonly sql: SqlStorage;
-  readonly metadata: SessionMetadata;
-
-  constructor(private readonly storage: DurableObjectStorage) {
-    this.sql = storage.sql;
-    const hasVersion =
-      this.sql
-        .exec(
-          "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'pi_storage_state'",
-        )
-        .toArray().length > 0;
-    const hasLegacy =
-      this.sql
-        .exec(
-          "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'pi_session_entries'",
-        )
-        .toArray().length > 0;
-    if (!hasVersion && hasLegacy) {
-      throw new Error(
-        "Pi session requires an explicit legacy-to-0.85 migration",
-      );
-    }
-    if (hasVersion) {
-      const version = this.sql
-        .exec<{
-          storage_version: number;
-        }>("SELECT storage_version FROM pi_storage_state WHERE singleton = 1")
-        .one().storage_version;
-      if (version !== CURRENT_PI_STORAGE_VERSION)
-        throw new Error(
-          `Unsupported Cloudflare Pi storage version: ${version}`,
-        );
-    }
-    this.sql.exec(`
-      CREATE TABLE IF NOT EXISTS pi_session_entry_submission (entry_id TEXT PRIMARY KEY, submission_id TEXT NOT NULL);
-      CREATE TABLE IF NOT EXISTS pi_entries (
-        id TEXT PRIMARY KEY, seq INTEGER NOT NULL UNIQUE, parent_id TEXT,
-        type TEXT NOT NULL, custom_type TEXT, timestamp INTEGER NOT NULL, body TEXT NOT NULL
-      );
-      CREATE TABLE IF NOT EXISTS pi_values (
-        namespace TEXT NOT NULL, key TEXT NOT NULL, seq INTEGER NOT NULL, body TEXT NOT NULL,
-        PRIMARY KEY(namespace, key)
-      );
-      CREATE TABLE IF NOT EXISTS pi_lists (
-        namespace TEXT NOT NULL, key TEXT NOT NULL, seq INTEGER PRIMARY KEY, body TEXT NOT NULL
-      );
-      CREATE INDEX IF NOT EXISTS pi_lists_address ON pi_lists(namespace, key, seq);
-      CREATE TABLE IF NOT EXISTS pi_usage (id TEXT PRIMARY KEY, seq INTEGER NOT NULL UNIQUE, body TEXT NOT NULL);
-      CREATE TABLE IF NOT EXISTS pi_storage_state (singleton INTEGER PRIMARY KEY CHECK(singleton = 1), next_seq INTEGER NOT NULL, storage_version INTEGER NOT NULL, session_id TEXT NOT NULL, created_at INTEGER NOT NULL, stats TEXT NOT NULL);
-    `);
-    this.sql.exec(
-      "INSERT OR IGNORE INTO pi_storage_state VALUES (1, 1, ?, ?, ?, ?)",
-      CURRENT_PI_STORAGE_VERSION,
-      crypto.randomUUID(),
-      Date.now(),
-      JSON.stringify({
-        messageCount: 0,
-        usage: {
-          input: 0,
-          output: 0,
-          cacheRead: 0,
-          cacheWrite: 0,
-          totalTokens: 0,
-          cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-        },
-      }),
-    );
-    const row = this.sql
-      .exec<{
-        storage_version: number;
-        session_id: string;
-        created_at: number;
-      }>(
-        "SELECT storage_version, session_id, created_at FROM pi_storage_state WHERE singleton = 1",
-      )
-      .one();
-    this.metadata = {
-      id: row.session_id,
-      createdAt: row.created_at,
-      storageVersion: row.storage_version,
-    };
-  }
-
-  private assertOpen(context?: Context): void {
-    if (this.closed) throw new Error("Session storage is closed");
-    context?.abortSignal?.throwIfAborted();
-  }
-
-  /** Synchronous boundary also used by the host's admission/settlement transaction. */
-  commitSync(writes: Write[], context?: Context): CommitResult {
-    this.assertOpen(context);
-    return this.storage.transactionSync(() => {
-      const firstSeq = this.sql
-        .exec<{
-          next_seq: number;
-        }>("SELECT next_seq FROM pi_storage_state WHERE singleton = 1")
-        .one().next_seq;
-      const prepared = prepareStorageCommit(writes, firstSeq, Date.now());
-      validateCommittedWrites(prepared.writes, firstSeq, {
-        hasEntryId: (id) =>
-          this.sql.exec("SELECT 1 FROM pi_entries WHERE id = ?", id).toArray()
-            .length > 0,
-        hasEntryOrUsageId: (id) =>
-          this.sql
-            .exec(
-              "SELECT 1 FROM pi_entries WHERE id = ? UNION ALL SELECT 1 FROM pi_usage WHERE id = ?",
-              id,
-              id,
-            )
-            .toArray().length > 0,
-      });
-      const stats = this.statsSync();
-      for (const write of prepared.writes) {
-        switch (write.kind) {
-          case "entry": {
-            const { kind: _kind, ...entry } = write;
-            if (entry.type === "message") stats.messageCount += 1;
-            this.sql.exec(
-              "INSERT INTO pi_entries VALUES (?, ?, ?, ?, ?, ?, ?)",
-              entry.id,
-              entry.seq,
-              entry.parentId,
-              entry.type,
-              entry.customType ?? null,
-              entry.timestamp,
-              JSON.stringify(entry),
-            );
-            break;
-          }
-          case "usage": {
-            const { kind: _kind, ...row } = write;
-            for (const key of [
-              "input",
-              "output",
-              "cacheRead",
-              "cacheWrite",
-              "totalTokens",
-              "cacheWrite1h",
-              "reasoning",
-            ] as const) {
-              if (row.usage[key] !== undefined)
-                stats.usage[key] = (stats.usage[key] ?? 0) + row.usage[key];
-            }
-            for (const key of [
-              "input",
-              "output",
-              "cacheRead",
-              "cacheWrite",
-              "total",
-            ] as const)
-              stats.usage.cost[key] += row.usage.cost[key];
-            this.sql.exec(
-              "INSERT INTO pi_usage VALUES (?, ?, ?)",
-              row.id,
-              row.seq,
-              JSON.stringify(row),
-            );
-            break;
-          }
-          case "value":
-            if (write.op === "delete")
-              this.sql.exec(
-                "DELETE FROM pi_values WHERE namespace = ? AND key = ?",
-                write.namespace,
-                write.key,
-              );
-            else
-              this.sql.exec(
-                "INSERT INTO pi_values VALUES (?, ?, ?, ?) ON CONFLICT(namespace, key) DO UPDATE SET seq = excluded.seq, body = excluded.body",
-                write.namespace,
-                write.key,
-                write.seq,
-                JSON.stringify(write.value),
-              );
-            break;
-          case "list":
-            if (write.op === "delete")
-              this.sql.exec(
-                "DELETE FROM pi_lists WHERE namespace = ? AND key = ?",
-                write.namespace,
-                write.key,
-              );
-            else
-              this.sql.exec(
-                "INSERT INTO pi_lists VALUES (?, ?, ?, ?)",
-                write.namespace,
-                write.key,
-                write.seq,
-                JSON.stringify(write.value),
-              );
-            break;
-        }
-      }
-      this.sql.exec(
-        "UPDATE pi_storage_state SET next_seq = ?, stats = ? WHERE singleton = 1",
-        firstSeq + writes.length,
-        JSON.stringify(stats),
-      );
-      return { ...prepared.result, stats };
-    });
-  }
-
-  async commit(writes: Write[], context: Context): Promise<CommitResult> {
-    return this.commitSync(writes, context);
-  }
-
-  async getEntries(
-    ids: string[],
-    context: Context,
-  ): Promise<Map<string, Entry>> {
-    return this.getEntriesSync(ids, context);
-  }
-
-  getEntriesSync(ids: string[], context?: Context): Map<string, Entry> {
-    this.assertOpen(context);
-    const entries = new Map<string, Entry>();
-    for (const id of ids) {
-      const row = this.sql
-        .exec<{ body: string }>("SELECT body FROM pi_entries WHERE id = ?", id)
-        .toArray()[0];
-      if (row) entries.set(id, JSON.parse(row.body));
-    }
-    return entries;
-  }
-
-  async getValue<T>(
-    address: Value<T>,
-    context: Context,
-  ): Promise<StoredValue<T> | undefined> {
-    return this.getValueSync(address, context);
-  }
-
-  getValueSync<T>(
-    address: Value<T>,
-    context?: Context,
-  ): StoredValue<T> | undefined {
-    this.assertOpen(context);
-    const row = this.sql
-      .exec<{
-        seq: number;
-        body: string;
-      }>(
-        "SELECT seq, body FROM pi_values WHERE namespace = ? AND key = ?",
-        address.namespace,
-        address.key,
-      )
-      .toArray()[0];
-    return row
-      ? { address, seq: row.seq, value: JSON.parse(row.body) }
-      : undefined;
-  }
-
-  async scanValues<T>(
-    prefix: Value<T>,
-    context: Context,
-  ): Promise<StoredValue<T>[]> {
-    this.assertOpen(context);
-    return this.sql
-      .exec<{ key: string; seq: number; body: string }>(
-        "SELECT key, seq, body FROM pi_values WHERE namespace = ? AND substr(key, 1, length(?)) = ? ORDER BY key COLLATE BINARY",
-        prefix.namespace,
-        prefix.key,
-        prefix.key,
-      )
-      .toArray()
-      .map((row) => ({
-        address: value<T>(prefix.namespace, row.key),
-        seq: row.seq,
-        value: JSON.parse(row.body),
-      }));
-  }
-
-  async readList<T>(
-    address: ValueList<T>,
-    options: ListReadOptions | undefined,
-    context: Context,
-  ): Promise<ListElement<T>[]> {
-    this.assertOpen(context);
-    const resolved = resolveListReadOptions(options);
-    const descending = resolved.order === "desc";
-    const comparison = descending ? "<" : ">";
-    return this.sql
-      .exec<{ seq: number; body: string }>(
-        `SELECT seq, body FROM pi_lists WHERE namespace = ? AND key = ? AND (? IS NULL OR seq ${comparison} ?) ORDER BY seq ${descending ? "DESC" : "ASC"} LIMIT ?`,
-        address.namespace,
-        address.key,
-        resolved.cursor?.seq ?? null,
-        resolved.cursor?.seq ?? null,
-        resolved.limit,
-      )
-      .toArray()
-      .map((row) => ({ seq: row.seq, value: JSON.parse(row.body) }));
-  }
-
-  private branchRows(query: StorageBranchScan, structure: boolean) {
-    // Stops follow the requested traversal direction; filters must not hide a stop entry.
-    const oldestFirst = query.order === "oldestFirst";
-    const rows = this.sql
-      .exec<{
-        id: string;
-        parentId: string | null;
-        seq: number;
-        timestamp: number;
-        type: Entry["type"];
-        customType: string | null;
-        body?: string;
-      }>(
-        `
-      WITH RECURSIVE path AS (
-        SELECT id, parent_id, seq, timestamp, type, custom_type${structure ? "" : ", body"} FROM pi_entries WHERE id = ?
-        UNION ALL
-        SELECT e.id, e.parent_id, e.seq, e.timestamp, e.type, e.custom_type${structure ? "" : ", e.body"}
-        FROM pi_entries e JOIN path p ON e.id = p.parent_id
-      ) SELECT id, parent_id AS parentId, seq, timestamp, type, custom_type AS customType${structure ? "" : ", body"}
-        FROM path ORDER BY seq ${oldestFirst ? "ASC" : "DESC"}
-    `,
-        query.start,
-      )
-      .toArray();
-    if (!rows.length) throw new Error(`Unknown branch start: ${query.start}`);
-    const root = oldestFirst ? rows[0]! : rows.at(-1)!;
-    if (root.parentId !== null)
-      throw new Error("Corrupt branch: missing parent");
-    const stop = rows.findIndex(
-      (row) => row.id === query.stopAtId || row.type === query.stopAtType,
-    );
-    return (stop < 0 ? rows : rows.slice(0, stop + 1))
-      .filter(
-        (row) =>
-          (query.type === undefined || query.type === row.type) &&
-          (query.customType === undefined ||
-            query.customType === row.customType) &&
-          (query.cursor === undefined ||
-            (oldestFirst
-              ? row.seq > query.cursor.seq
-              : row.seq < query.cursor.seq)),
-      )
-      .slice(
-        0,
-        query.limit === undefined ? undefined : Math.max(0, query.limit),
-      );
-  }
-
-  async scanBranch(
-    query: StorageBranchScan,
-    context: Context,
-  ): Promise<Entry[]> {
-    return this.scanBranchSync(query, context);
-  }
-
-  scanBranchSync(query: StorageBranchScan, context?: Context): Entry[] {
-    this.assertOpen(context);
-    return this.branchRows(query, false).map((row) => JSON.parse(row.body!));
-  }
-
-  async scanBranchStructure(
-    query: StorageBranchScan,
-    context: Context,
-  ): Promise<EntryStructure[]> {
-    this.assertOpen(context);
-    return this.branchRows(query, true).map(
-      ({ customType, body: _body, ...row }) => ({
-        ...row,
-        ...(customType === null ? {} : { customType }),
-      }),
-    );
-  }
-
-  async scanEntries(query: EntryScan, context: Context): Promise<Entry[]> {
-    this.assertOpen(context);
-    return this.sql
-      .exec<{ body: string }>(
-        `
-      SELECT body FROM pi_entries WHERE (? IS NULL OR type = ?) AND (? IS NULL OR custom_type = ?)
-      AND (? IS NULL OR seq >= ?) AND (? IS NULL OR seq <= ?) ORDER BY seq ${query.order === "desc" ? "DESC" : "ASC"} LIMIT ?`,
-        query.type ?? null,
-        query.type ?? null,
-        query.customType ?? null,
-        query.customType ?? null,
-        query.fromSeq ?? null,
-        query.fromSeq ?? null,
-        query.toSeq ?? null,
-        query.toSeq ?? null,
-        query.limit === undefined ? -1 : Math.max(0, Math.trunc(query.limit)),
-      )
-      .toArray()
-      .map((row) => JSON.parse(row.body));
-  }
-
-  async scanUsage(query: UsageScan, context: Context): Promise<UsageRow[]> {
-    this.assertOpen(context);
-    return this.sql
-      .exec<{ body: string }>(
-        `
-      SELECT body FROM pi_usage WHERE (? IS NULL OR seq >= ?) AND (? IS NULL OR seq <= ?)
-      ORDER BY seq ${query.order === "desc" ? "DESC" : "ASC"} LIMIT ?`,
-        query.fromSeq ?? null,
-        query.fromSeq ?? null,
-        query.toSeq ?? null,
-        query.toSeq ?? null,
-        query.limit === undefined ? -1 : Math.max(0, Math.trunc(query.limit)),
-      )
-      .toArray()
-      .map((row) => JSON.parse(row.body));
-  }
-
-  private statsSync(): SessionStats {
-    return JSON.parse(
-      this.sql
-        .exec<{
-          stats: string;
-        }>("SELECT stats FROM pi_storage_state WHERE singleton = 1")
-        .one().stats,
-    );
-  }
-
-  async getStats(context: Context): Promise<SessionStats> {
-    this.assertOpen(context);
-    return this.statsSync();
-  }
-
-  /** Host commits use this single branch; off-branch entries remain available by ID. */
-  branch(): Entry[] {
-    const tip = this.getValueSync(branchTip("main"))?.value;
-    return tip ? this.scanBranchSync({ start: tip, order: "oldestFirst" }) : [];
-  }
-
-  entry(id: string): Entry | undefined {
-    return this.getEntriesSync([id]).get(id);
-  }
-
-  appendMessage(input: {
-    id: string;
-    message: AgentMessage;
-    submissionId?: string;
-  }): boolean {
-    return this.storage.transactionSync(() => {
-      if (this.entry(input.id)) return false;
-      const usage =
-        input.message.role === "assistant" ||
-        input.message.role === "toolResult"
-          ? input.message.usage
-          : undefined;
-      this.commitSync([
-        insertEntry({
-          id: input.id,
-          parentId: this.getValueSync(branchTip("main"))?.value ?? null,
-          type: "message",
-          message: input.message,
-        }),
-        setValue(branchTip("main"), input.id),
-        ...(usage
-          ? [
-              insertUsage({
-                id: crypto.randomUUID(),
-                entryId: input.id,
-                usage,
-                adjustment: false,
-              }),
-            ]
-          : []),
-      ]);
-      if (input.submissionId)
-        this.sql.exec(
-          "INSERT INTO pi_session_entry_submission VALUES (?, ?)",
-          input.id,
-          input.submissionId,
-        );
-      return true;
-    });
-  }
-
-  entries(): Entry[] {
-    return this.sql
-      .exec<{ body: string }>("SELECT body FROM pi_entries ORDER BY seq")
-      .toArray()
-      .map((row) => JSON.parse(row.body));
-  }
-
-  clear(): void {
-    this.storage.transactionSync(() => {
-      this.sql.exec(
-        "DELETE FROM pi_session_entry_submission; DELETE FROM pi_entries; DELETE FROM pi_values; DELETE FROM pi_lists; DELETE FROM pi_usage;",
-      );
-      const usage = {
-        input: 0,
-        output: 0,
-        cacheRead: 0,
-        cacheWrite: 0,
-        totalTokens: 0,
-        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-      };
-      this.sql.exec(
-        "UPDATE pi_storage_state SET stats = ? WHERE singleton = 1",
-        JSON.stringify({ messageCount: 0, usage }),
-      );
-    });
-  }
-
-  async close(_context?: Context): Promise<void> {
-    this.closed = true;
-  }
+import { defineDoc, type ConversationId, type Storage } from "@earendil-works/pi-durable";
+import { openDurableObjectSqliteStorage } from "@earendil-works/pi-durable/storage/sqlite/cloudflare";
+
+/** The host selects a native conversation when regenerating or clearing history. */
+export const RuntimeConversation = defineDoc({
+  kind: "springbrand.conversation",
+  version: 1,
+  scope: "session",
+  initial: (): { id: ConversationId | null } => ({ id: null }),
+});
+
+export async function openNativeStorage(storage: DurableObjectStorage): Promise<Storage> {
+  return openDurableObjectSqliteStorage(storage);
 }

package/src/session/index.ts

@@ -1,39 +1,26 @@
-import { StorageBackedSession } from "@earendil-works/pi-agent-core/harness/session";
-import {
-  migrateCurrentPiSession,
-  migrateLegacyPiSession,
-} from "./cloudflare/migration";
-import { CloudflareSessionStorage } from "./cloudflare/storage";
+import { createSession, type Storage } from "@earendil-works/pi-durable";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { migratePiSession } from "./cloudflare/migration";
+import { openNativeStorage } from "./cloudflare/storage";
 
-export { migrateLegacyPiSession } from "./cloudflare/migration";
-export { CloudflareSessionStorage } from "./cloudflare/storage";
+export { RuntimeConversation } from "./cloudflare/storage";
+export { migratePiSession } from "./cloudflare/migration";
 
-/** Open only after the startup transaction has installed the current database format. */
-export function openPiSessionStorage(
-  storage: DurableObjectStorage,
-): CloudflareSessionStorage {
-  return storage.transactionSync(() => {
-    const tables = new Set(
-      storage.sql
-        .exec<{ name: string }>(
-          "SELECT name FROM sqlite_master WHERE type = 'table' AND name IN ('pi_storage_state', 'pi_session_entries')",
-        )
-        .toArray()
-        .map((row) => row.name),
-    );
-    if (!tables.has("pi_storage_state") && tables.has("pi_session_entries")) {
-      migrateLegacyPiSession(storage, { dryRun: false });
-    } else if (tables.has("pi_storage_state")) {
-      migrateCurrentPiSession(storage);
-    }
-    return new CloudflareSessionStorage(storage);
-  });
-}
+const migrations = new WeakMap<DurableObjectStorage, Promise<void>>();
 
-/** Open the single official Pi Session owned by one Cloudflare Agent facet. */
-export function openCloudflareSession(
-  storage: DurableObjectStorage,
-): StorageBackedSession {
-  const store = openPiSessionStorage(storage);
-  return new StorageBackedSession(store.metadata, store);
+/** Migration completes before native execution or history reads are admitted. */
+export async function openCloudflareSession(storage: DurableObjectStorage): Promise<Storage> {
+  let migrating = migrations.get(storage);
+  if (!migrating) {
+    migrating = (async () => {
+      const native = await openNativeStorage(storage);
+      const session = createSession(native);
+      try { await migratePiSession(storage, session); }
+      finally { await session.close(BACKGROUND_CONTEXT); }
+    })();
+    migrations.set(storage, migrating);
+    migrating.catch(() => migrations.delete(storage));
+  }
+  await migrating;
+  return openNativeStorage(storage);
 }

package/src/submission/finalization.ts

@@ -1,5 +1,5 @@
 import type { AssistantMessage } from "@earendil-works/pi-ai";
-import type { CancelQueuedResult } from "@earendil-works/pi-agent-core";
+import type { CancelQueuedResult } from "./steer-delivery";
 import type { ConversationHistory } from "../conversation/history";
 import type { MessageUiRepository } from "../conversation/repository";
 import type { RuntimeTelemetryCoordinator } from "../telemetry/coordinator";
@@ -13,6 +13,8 @@ import type { SteerRepository } from "./steer-repository";
 
 /** Commits the Submission outcome and human/Host facts after accepted steering is preserved. */
 export class SubmissionFinalizer {
+  /** User-stop markers appended after their terminal commit; `finish()` awaits its own. */
+  private readonly stopMarkers = new Map<string, Promise<unknown>>();
   constructor(private readonly options: {
     submissions: SubmissionRepository;
     steers: SteerRepository;
@@ -53,7 +55,13 @@ export class SubmissionFinalizer {
     const output = (await this.options.conversation.storedMessages())
       .filter((entry) => entry.submissionId === submissionId && entry.message.role === "assistant")
       .at(-1)?.message;
-    return this.commit(submissionId, outcome, message, output?.role === "assistant" ? output : undefined);
+    const completed = this.commit(submissionId, outcome, message, output?.role === "assistant" ? output : undefined);
+    const marker = this.stopMarkers.get(submissionId);
+    if (marker) {
+      this.stopMarkers.delete(submissionId);
+      await marker;
+    }
+    return completed;
   }
 
   /** Shares atomic terminal facts with an admitted handoff cancelled before execution. */
@@ -63,7 +71,8 @@ export class SubmissionFinalizer {
     message?: string,
     output?: AssistantMessage,
   ): StoredSubmission {
-    return this.options.transaction(() => {
+    let stoppedByUser = false;
+    const completed = this.options.transaction(() => {
       // Host admission and history reads can await while an explicit stop wins.
       const latest = this.read(submissionId);
       if (isTerminalSubmissionStatus(latest.status)) return latest;
@@ -79,16 +88,9 @@ export class SubmissionFinalizer {
       const status = effectiveOutcome === "succeeded" ? "completed" : effectiveOutcome === "aborted" ? "aborted" : "error";
       this.options.submissions.updateTerminal(submissionId, status, reason, Date.now());
       const completed = this.read(submissionId);
-      if (effectiveOutcome === "aborted" && reason === USER_STOP_REASON) {
-        if (completed.completedAt === null) {
-          throw new Error(
-            `Aborted SpringBrand submission has no completion time: ${submissionId}`,
-          );
-        }
-        this.options.conversation.appendTurnAbortedMarker(
-          submissionId,
-          completed.completedAt,
-        );
+      stoppedByUser = effectiveOutcome === "aborted" && reason === USER_STOP_REASON;
+      if (stoppedByUser && completed.completedAt === null) {
+        throw new Error(`Aborted SpringBrand submission has no completion time: ${submissionId}`);
       }
       this.options.events.submissionTerminal(completed);
       this.options.telemetry.capture("turnFinished", {
@@ -101,6 +103,20 @@ export class SubmissionFinalizer {
       });
       return completed;
     });
+    if (stoppedByUser) this.appendStopMarker(submissionId, completed.completedAt!);
+    return completed;
+  }
+
+  /**
+   * The browser projects `interruptedByUser` from this marker and the next model request sees it as user context.
+   * Pi history writes are async, so the marker follows the synchronous terminal commit.
+   */
+  private appendStopMarker(submissionId: string, completedAt: number): void {
+    const marker = this.options.conversation.appendTurnAbortedMarker(submissionId, completedAt).catch((error: unknown) => {
+      console.warn("[runtime-stop-marker:failed]", submissionId, error instanceof Error ? error.message : String(error));
+    });
+    this.stopMarkers.set(submissionId, marker);
+    this.options.waitUntil(marker);
   }
 
   private read(submissionId: string): StoredSubmission {