@narumitw/pi-sync 0.57.10 → 0.57.12

package/src/snapshot/snapshot-mutation-queues.ts

@@ -0,0 +1,142 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+
+type MutationGuards = { signal?: AbortSignal; validateMutation?: () => void };
+
+function assertCurrent(options: MutationGuards) {
+  options.validateMutation?.();
+  options.signal?.throwIfAborted();
+}
+
+function isMissing(error: unknown) {
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+
+async function targetMissing(target: string, options: MutationGuards) {
+  assertCurrent(options);
+  try {
+    await fs.lstat(target);
+    assertCurrent(options);
+    return false;
+  } catch (error) {
+    assertCurrent(options);
+    if (!isMissing(error)) throw error;
+    return true;
+  }
+}
+
+async function queueKey(target: string, options: MutationGuards) {
+  assertCurrent(options);
+  try {
+    const key = await fs.realpath(target);
+    assertCurrent(options);
+    return key;
+  } catch (error) {
+    assertCurrent(options);
+    if (!isMissing(error)) throw error;
+    return path.resolve(target);
+  }
+}
+
+/** Resolve missing descendants too, including descendants of a file scheduled for removal. */
+async function assertCanonicalParent(target: string, options: MutationGuards) {
+  const parent = path.dirname(path.resolve(target));
+  const suffix: string[] = [];
+  for (let current = parent; ; current = path.dirname(current)) {
+    assertCurrent(options);
+    let canonical: string;
+    try {
+      canonical = await fs.realpath(current);
+    } catch (error) {
+      assertCurrent(options);
+      if (!isMissing(error) || path.dirname(current) === current) throw error;
+      suffix.unshift(path.basename(current));
+      continue;
+    }
+    assertCurrent(options);
+    // Pi queues existing paths by realpath and missing paths by lexical resolve.
+    // Its public API cannot reserve a missing alias key while that alias exists,
+    // or report a key that changes during registration. Refuse aliased parents
+    // before mutation rather than risk a non-reentrant queue or overwrite a writer.
+    if (path.join(canonical, ...suffix) !== parent)
+      throw new Error(
+        "Snapshot mutation through an aliased parent is unsafe; use the canonical agent/session path. Transaction evidence retained for review.",
+      );
+    return;
+  }
+}
+
+export async function assertCanonicalMutationTargets(targets: readonly string[], options: MutationGuards) {
+  for (const target of targets) await assertCanonicalParent(target, options);
+}
+
+export async function withTargetQueues<T>(
+  targets: readonly string[],
+  options: MutationGuards,
+  action: (heldKeys: ReadonlySet<string>) => Promise<T>,
+): Promise<T> {
+  // Check the whole group before reserving any key or changing live files.
+  await assertCanonicalMutationTargets(targets, options);
+  const keys = new Set<string>();
+  const missing = new Set<string>();
+  for (const target of targets) {
+    if (await targetMissing(target, options)) missing.add(target);
+    const key = await queueKey(target, options);
+    if (keys.has(key)) throw new Error("Transaction targets alias the same file.");
+    keys.add(key);
+  }
+  const ordered = [...keys].sort();
+  async function acquire(index: number): Promise<T> {
+    assertCurrent(options);
+    const key = ordered[index];
+    // Pass the resolved key, not an alias whose lookup can select a different key.
+    if (key) return withFileMutationQueue(key, () => acquire(index + 1));
+    for (const target of targets) {
+      await assertCanonicalParent(target, options);
+      if (missing.has(target) && !(await targetMissing(target, options)))
+        throw new Error("Missing transaction target appeared during queue acquisition; review is required.");
+      if (!keys.has(await queueKey(target, options)))
+        throw new Error("Transaction queue identity changed; review is required.");
+    }
+    assertCurrent(options);
+    return action(keys);
+  }
+  return acquire(0);
+}
+
+export async function withMissingTargetQueues<T>(
+  targets: readonly string[],
+  heldKeys: ReadonlySet<string>,
+  options: MutationGuards,
+  action: (heldKeys: ReadonlySet<string>) => Promise<T>,
+): Promise<T> {
+  const unique = [...new Set(targets)];
+  const requireAbsent = async () => {
+    for (const target of unique) {
+      await assertCanonicalParent(target, options);
+      if (!(await targetMissing(target, options)))
+        throw new Error("Snapshot target changed before destination queue reservation; evidence retained.");
+    }
+  };
+  // Canonical parents make each missing key equal to the intended installed key.
+  // Retain the old physical key and exclude it from these non-reentrant queues.
+  const keys = unique
+    .map((target) => path.resolve(target))
+    .filter((key) => !heldKeys.has(key))
+    .sort();
+  await requireAbsent();
+  const combined = new Set([...heldKeys, ...keys]);
+  async function acquire(index: number): Promise<T> {
+    assertCurrent(options);
+    const key = keys[index];
+    if (key) return withFileMutationQueue(key, () => acquire(index + 1));
+    // A writer registered in the removal gap must finish before this check.
+    // Even recognizable pre/postimages belong to that writer, not this transaction.
+    await requireAbsent();
+    assertCurrent(options);
+    return action(combined);
+  }
+  return acquire(0);
+}

package/src/snapshot/snapshot-transaction.ts

@@ -2,7 +2,6 @@ import { createHash, randomUUID } from "node:crypto";
 import type { Stats } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { assertWithinRoot, isDeniedPath, isPathInside } from "../paths.js";
 import { syncDirectory, writeJson } from "../state/json-file.js";
 import { withLock } from "../state/lock.js";
@@ -11,6 +10,7 @@ import { stateDir } from "../state/state-directory.js";
 import { mergePathIdentity } from "../sync/file-merge-planner.js";
 import { agentDir, configuredSessionDir } from "./session-paths.js";
 import { caseReplacementSpelling, coalesceCaseReplacements, isCaseReplacement } from "./snapshot-case-replacement.js";
+import { withMissingTargetQueues, withTargetQueues } from "./snapshot-mutation-queues.js";
 import { sessionStorageRoot } from "./snapshot-paths.js";
 import {
   prepareSessionRootTransition,
@@ -69,7 +69,7 @@ export async function applySnapshotTransaction(plan: SnapshotApplyPlan, options:
   const targets = [...new Set([...coalesced.plan.deletes, ...coalesced.plan.writes.map((item) => item.target)])].sort();
   if (targets.length > 16_384)
     throw new Error("Snapshot transaction exceeds its target bound; review a smaller transfer.");
-  return withTargetQueues(targets, async () => {
+  return withTargetQueues(targets, options, async (heldKeys) => {
     options.signal?.throwIfAborted();
     if (
       targets.some((target) =>
@@ -134,6 +134,10 @@ export async function applySnapshotTransaction(plan: SnapshotApplyPlan, options:
         ...(entry.afterTarget ? [[entry.afterTarget, entry] as const] : []),
       ]),
     );
+    // A released additional key cannot authorize rollback, even for recognized raced bytes.
+    const changesQueueKey = transaction.journal.entries.some(
+      (entry) => !heldKeys.has(entry.target) || (entry.afterTarget && !heldKeys.has(entry.afterTarget)),
+    );
     try {
       for (const target of transaction.deletes.sort((a, b) => a.length - b.length)) {
         options.signal?.throwIfAborted();
@@ -142,75 +146,81 @@ export async function applySnapshotTransaction(plan: SnapshotApplyPlan, options:
         await removeOwnedTarget(transaction.directory, entry, transaction.journal, options);
         await syncDirectory(path.dirname(target));
       }
-      await withCaseDestinationQueues([...coalesced.replacements], options, async () => {
-        await retireRemovalIntent(
-          transaction.directory,
-          transaction.journal,
-          transaction.journal.entries.filter(
-            (entry) => entry.removalPending && (entry.afterImage !== "missing" || (entry.postFiles?.length ?? 0) > 0),
-          ),
-          options,
-        );
-        // Only this uninterrupted call knows which deleted writes have not attempted installation yet.
-        const uninstalledWrites = new Set(transaction.deletedWrites);
-        for (const item of plan.writes) {
-          options.signal?.throwIfAborted();
-          const entry = entriesByTarget.get(item.target);
-          if (!entry) throw new Error("Unowned transaction target.");
-          const deletedByThisCall = uninstalledWrites.delete(entry.target);
-          await verifyTarget(transaction.directory, entry, transaction.journal, deletedByThisCall);
-          options.validateMutation?.();
-          options.signal?.throwIfAborted();
-          await fs.mkdir(path.dirname(item.target), { recursive: true });
-          options.validateMutation?.();
-          options.signal?.throwIfAborted();
-          const temp = path.join(path.dirname(item.target), `.pi-sync.json.${randomUUID()}.apply`);
-          try {
-            let mode = 0o600;
-            try {
-              const stat = await fs.lstat(item.target);
-              if (stat.isFile()) mode = stat.mode & 0o777;
-            } catch (error) {
-              if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-            }
-            const handle = await fs.open(temp, "wx", mode);
-            try {
-              await handle.writeFile(item.content);
-              await handle.sync();
-            } finally {
-              await handle.close();
-            }
+      await withMissingTargetQueues(
+        transaction.journal.entries
+          .filter((entry) => entry.removalPending)
+          .flatMap((entry) => [entry.target, ...(entry.afterTarget ? [entry.afterTarget] : [])]),
+        heldKeys,
+        options,
+        async () => {
+          await retireRemovalIntent(
+            transaction.directory,
+            transaction.journal,
+            transaction.journal.entries.filter(
+              (entry) => entry.removalPending && (entry.afterImage !== "missing" || (entry.postFiles?.length ?? 0) > 0),
+            ),
+            options,
+          );
+          // Only this uninterrupted call knows which deleted writes have not attempted installation yet.
+          const uninstalledWrites = new Set(transaction.deletedWrites);
+          for (const item of plan.writes) {
+            options.signal?.throwIfAborted();
+            const entry = entriesByTarget.get(item.target);
+            if (!entry) throw new Error("Unowned transaction target.");
+            const deletedByThisCall = uninstalledWrites.delete(entry.target);
             await verifyTarget(transaction.directory, entry, transaction.journal, deletedByThisCall);
+            options.validateMutation?.();
             options.signal?.throwIfAborted();
+            await fs.mkdir(path.dirname(item.target), { recursive: true });
             options.validateMutation?.();
-            await fs.rename(temp, item.target);
-            await syncDirectory(path.dirname(item.target));
-          } finally {
-            await fs.rm(temp, { force: true });
+            options.signal?.throwIfAborted();
+            const temp = path.join(path.dirname(item.target), `.pi-sync.json.${randomUUID()}.apply`);
+            try {
+              let mode = 0o600;
+              try {
+                const stat = await fs.lstat(item.target);
+                if (stat.isFile()) mode = stat.mode & 0o777;
+              } catch (error) {
+                if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+              }
+              const handle = await fs.open(temp, "wx", mode);
+              try {
+                await handle.writeFile(item.content);
+                await handle.sync();
+              } finally {
+                await handle.close();
+              }
+              await verifyTarget(transaction.directory, entry, transaction.journal, deletedByThisCall);
+              options.signal?.throwIfAborted();
+              options.validateMutation?.();
+              await fs.rename(temp, item.target);
+              await syncDirectory(path.dirname(item.target));
+            } finally {
+              await fs.rm(temp, { force: true });
+            }
           }
-        }
-        options.validateMutation?.();
-        options.signal?.throwIfAborted();
-        await syncMutationParents(
-          targets,
-          [transaction.journal.root, ...(transaction.journal.sessionRoot ? [transaction.journal.sessionRoot] : [])],
-          options,
-        );
-        options.validateMutation?.();
-        options.signal?.throwIfAborted();
-      });
+          options.validateMutation?.();
+          options.signal?.throwIfAborted();
+          await syncMutationParents(
+            targets,
+            [transaction.journal.root, ...(transaction.journal.sessionRoot ? [transaction.journal.sessionRoot] : [])],
+            options,
+          );
+          options.validateMutation?.();
+          options.signal?.throwIfAborted();
+        },
+      );
     } catch (error) {
       // Aborted owners cannot roll back files after another session has replaced them.
       if (options.signal?.aborted)
         throw new Error("Snapshot apply cancelled; guarded transaction evidence retained for review.");
-      // Additional spelling queues have been released: do not start a case rollback
-      // under only the original key. Startup recovery reserves its own destination key.
-      if (coalesced.replacements.size)
-        throw new Error("Case replacement apply failed; guarded transaction evidence retained for review.", {
+      // Additional queues have been released. Recovery must reserve missing keys afresh.
+      if (changesQueueKey)
+        throw new Error("Snapshot apply failed; guarded transaction evidence retained for review.", {
           cause: error,
         });
       try {
-        await restoreTransaction(transaction.directory, transaction.journal, options);
+        await restoreTransaction(transaction.directory, transaction.journal, options, heldKeys);
       } catch (recoveryError) {
         throw new AggregateError(
           [error, recoveryError],
@@ -285,8 +295,8 @@ export async function recoverPendingSnapshotTransactions(options: TransactionOpt
       await removeTransaction(directory);
       continue;
     }
-    await withTargetQueues(journal.entries.map((entry) => entry.target).sort(), () =>
-      restoreTransaction(directory, journal, { ...options, sessionDir }),
+    await withTargetQueues(journal.entries.map((entry) => entry.target).sort(), options, (heldKeys) =>
+      restoreTransaction(directory, journal, { ...options, sessionDir }, heldKeys),
     );
   }
 }
@@ -388,7 +398,36 @@ async function prepareTransaction(
   return { directory, journal, deletes: indexed.deletes, deletedWrites: indexed.deletedWrites };
 }
 
-async function restoreTransaction(directory: string, journal: TransactionJournal, options: TransactionOptions) {
+async function restoreTransaction(
+  directory: string,
+  journal: TransactionJournal,
+  options: TransactionOptions,
+  heldKeys: ReadonlySet<string>,
+) {
+  validateJournal(directory, journal, options.sessionDir);
+  const missingSpellings: string[] = [];
+  for (const entry of journal.entries) {
+    if (!entry.afterTarget) continue;
+    options.validateMutation?.();
+    options.signal?.throwIfAborted();
+    const spelling = await caseReplacementSpelling(entry.target, entry.afterTarget);
+    options.validateMutation?.();
+    options.signal?.throwIfAborted();
+    if (spelling === undefined) missingSpellings.push(entry.target, entry.afterTarget);
+  }
+  // Reserve an interrupted removal's other spelling before staging or image checks:
+  // recognizable bytes installed by a writer in that gap are not our postimage.
+  return withMissingTargetQueues(missingSpellings, heldKeys, options, (reservedKeys) =>
+    restoreQueuedTransaction(directory, journal, options, reservedKeys),
+  );
+}
+
+async function restoreQueuedTransaction(
+  directory: string,
+  journal: TransactionJournal,
+  options: TransactionOptions,
+  heldKeys: ReadonlySet<string>,
+) {
   validateJournal(directory, journal, options.sessionDir);
   options.validateMutation?.();
   options.signal?.throwIfAborted();
@@ -453,8 +492,13 @@ async function restoreTransaction(directory: string, journal: TransactionJournal
           !(await removeOwnedTarget(directory, entry, journal, options, before))
         )
           continue;
-        await withCaseDestinationQueues(
-          needsCaseQueue && entry.afterTarget ? [[entry.afterTarget, entry.target]] : [],
+        await withMissingTargetQueues(
+          entry.afterTarget && (needsCaseQueue || verified === "missing")
+            ? [entry.target, entry.afterTarget]
+            : verified.startsWith("directory:")
+              ? [entry.target]
+              : [],
+          heldKeys,
           options,
           async () => {
             const atRename = await verifyTarget(directory, entry, journal);
@@ -501,17 +545,19 @@ async function restoreTransaction(directory: string, journal: TransactionJournal
       options.validateMutation?.();
       options.signal?.throwIfAborted();
       if (!(await removeOwnedTarget(directory, entry, journal, options, before))) continue;
-      const atRename = await verifyTarget(directory, entry, journal);
-      options.validateMutation?.();
-      options.signal?.throwIfAborted();
-      if (atRename === before) continue;
-      await retireRestorationIntent(directory, journal, entry, options);
-      const atInstall = await verifyTarget(directory, entry, journal, atRename === "missing");
-      options.validateMutation?.();
-      options.signal?.throwIfAborted();
-      if (atInstall === before) continue;
-      await fs.rename(temporary, entry.target);
-      await syncDirectory(path.dirname(entry.target));
+      await withMissingTargetQueues([entry.target], heldKeys, options, async () => {
+        const atRename = await verifyTarget(directory, entry, journal);
+        options.validateMutation?.();
+        options.signal?.throwIfAborted();
+        if (atRename === before) return;
+        await retireRestorationIntent(directory, journal, entry, options);
+        const atInstall = await verifyTarget(directory, entry, journal, atRename === "missing");
+        options.validateMutation?.();
+        options.signal?.throwIfAborted();
+        if (atInstall === before) return;
+        await fs.rename(temporary, entry.target);
+        await syncDirectory(path.dirname(entry.target));
+      });
     } finally {
       await fs.rm(temporary, { recursive: true, force: true });
     }
@@ -867,55 +913,6 @@ async function assertSafeParents(root: string, sessionRoot: string | undefined,
     }
   }
 }
-async function withTargetQueues<T>(targets: string[], action: () => Promise<T>) {
-  const keys = new Set<string>();
-  for (const target of targets) {
-    let key = path.resolve(target);
-    try {
-      key = await fs.realpath(target);
-    } catch (error) {
-      const code = (error as NodeJS.ErrnoException).code;
-      if (code !== "ENOENT" && code !== "ENOTDIR") throw error;
-    }
-    if (keys.has(key)) throw new Error("Transaction targets alias the same file.");
-    keys.add(key);
-  }
-  async function acquire(index: number): Promise<T> {
-    const target = targets[index];
-    return target ? withFileMutationQueue(target, () => acquire(index + 1)) : action();
-  }
-  return acquire(0);
-}
-async function withCaseDestinationQueues<T>(
-  spellings: readonly (readonly [string, string])[],
-  options: TransactionOptions,
-  action: () => Promise<T>,
-): Promise<T> {
-  if (!spellings.length) return action();
-  const requireAbsent = async () => {
-    for (const [before, after] of spellings) {
-      options.validateMutation?.();
-      options.signal?.throwIfAborted();
-      const spelling = await caseReplacementSpelling(before, after);
-      options.validateMutation?.();
-      options.signal?.throwIfAborted();
-      if (spelling !== undefined)
-        throw new Error("Case replacement changed before destination queue reservation; evidence retained.");
-    }
-  };
-  // Existing aliases share one non-reentrant realpath queue. Only after removal can
-  // we reserve the distinct missing spelling while retaining the original queue.
-  // Pi writers that registered in the gap finish before this callback; refuse their
-  // bytes, including recognizable pre/postimages, rather than treating them as ours.
-  await requireAbsent();
-  return withTargetQueues(
-    spellings.map(([, after]) => after),
-    async () => {
-      await requireAbsent();
-      return action();
-    },
-  );
-}
 async function completeTransaction(directory: string, journal: TransactionJournal) {
   // Publish completion before deleting any backup. A surviving journal after power loss
   // may only retry cleanup, never roll back already accepted files.

package/src/sync/agent-candidate.ts

@@ -93,7 +93,7 @@ export function buildAgentEvidence(
   const evidence: AgentEvidence = { units: [], files: [], unsupported: [] };
   if (plan.kind !== "planned") return evidence;
   if (plan.conflicts.length > AGENT_MAX_UNITS)
-    throw new Error("Agent mode paused: too many conflict paths for bounded analysis.");
+    throw new Error("Autonomous sync paused: too many conflict paths for bounded analysis.");
   for (const conflict of plan.conflicts) {
     try {
       if (conflict.reason !== "both-changed") throw new Error("unsupported conflict");
@@ -159,7 +159,7 @@ export function buildAgentEvidence(
     }
   }
   if (evidence.units.length > AGENT_MAX_UNITS || Buffer.byteLength(JSON.stringify(evidence.units)) > AGENT_INPUT_BYTES)
-    throw new Error("Agent mode paused: conflict evidence exceeds its input bound.");
+    throw new Error("Autonomous sync paused: conflict evidence exceeds its input bound.");
   // Scan only the actual disclosure image; skipSecretScan never authorizes model disclosure.
   if (
     scanSnapshot({
@@ -169,7 +169,7 @@ export function buildAgentEvidence(
       ),
     }).length
   )
-    throw new Error("Agent mode paused: possible secrets in model evidence; nothing was disclosed.");
+    throw new Error("Autonomous sync paused: possible secrets in model evidence; nothing was disclosed.");
   return evidence;
 }
 

package/src/sync/agent-plan.ts

@@ -34,24 +34,27 @@ export async function resolveAgentPlan(
     return plan;
   }
   if (!ctx.hasUI || (ctx.mode !== "tui" && ctx.mode !== "rpc"))
-    throw new Error("Agent mode paused: TUI/RPC is required.");
+    throw new Error("Autonomous sync paused: TUI/RPC is required.");
   const ancestors = (await readMergeAncestors(config, state)) ?? [];
   await validate();
   let evidence: ReturnType<typeof buildAgentEvidence>;
   try {
     evidence = buildAgentEvidence(plan, local, remote, ancestors);
   } catch {
-    throw new ContinuousError("unsafe", "Agent mode paused: unsafe or unsupported conflict evidence.");
+    throw new ContinuousError("unsafe", "Autonomous sync paused: unsafe or unsupported conflict evidence.");
   }
   if (!config.partialSync && evidence.unsupported.length)
-    throw new ContinuousError("unsafe", "Agent mode paused: unsupported conflicts prevent an all-or-nothing transfer.");
+    throw new ContinuousError(
+      "unsafe",
+      "Autonomous sync paused: unsupported conflicts prevent an all-or-nothing transfer.",
+    );
   if (!evidence.files.length) {
     if (options.agentRetryRefusal)
       throw new ContinuousError("unsafe", "No eligible cached refusal for the current evidence. Use Sync now.");
     if (config.partialSync) return plan;
     throw new ContinuousError(
       "unsafe",
-      "Agent mode paused: unsupported conflict or missing verified ancestor; evidence is unchanged.",
+      "Autonomous sync paused: unsupported conflict or missing verified ancestor; evidence is unchanged.",
     );
   }
   if (!evidence.units.length) {
@@ -59,7 +62,7 @@ export async function resolveAgentPlan(
       throw new ContinuousError("unsafe", "No eligible cached refusal for the current evidence. Use Sync now.");
     return applyAgentCandidate(plan, evidence, { version: 1, results: [] });
   }
-  if (!ctx.model) throw new ContinuousError("model", "Agent mode paused: select an available model first.");
+  if (!ctx.model) throw new ContinuousError("model", "Autonomous sync paused: select an available model first.");
   const model = digest(ctx.model);
   const key = digest([
     1,
@@ -75,7 +78,7 @@ export async function resolveAgentPlan(
     try {
       return applyAgentCandidate(plan, evidence, options.agentAcceptance.candidate);
     } catch {
-      throw new ContinuousError("unsafe", "Agent mode paused: candidate refused or unsupported conflict remains.");
+      throw new ContinuousError("unsafe", "Autonomous sync paused: candidate refused or unsupported conflict remains.");
     }
   }
   const validateEvidence = async (signal = options.signal) => {
@@ -85,7 +88,7 @@ export async function resolveAgentPlan(
       signal?.throwIfAborted();
     };
     await check();
-    if (digest(ctx.model) !== model) throw new Error("Agent mode paused: selected model changed.");
+    if (digest(ctx.model) !== model) throw new Error("Autonomous sync paused: selected model changed.");
     const current = await createSnapshot(config.snapshotIdentity, { ...snapshotOptions, signal });
     await check();
     const currentState = await readStateForConfig(config);
@@ -98,7 +101,7 @@ export async function resolveAgentPlan(
       !currentHead ||
       !backend.sameRevision(head.revision, currentHead.revision)
     )
-      throw new ContinuousError("stale", "Agent mode paused: conflict evidence changed; retry a fresh sync.");
+      throw new ContinuousError("stale", "Autonomous sync paused: conflict evidence changed; retry a fresh sync.");
   };
   throw new AgentResolutionRequired(key, evidence, validateEvidence);
 }

package/src/sync/agent-runner.ts

@@ -39,9 +39,9 @@ export async function runAgentResolver(
   beforeRequest?: (signal: AbortSignal) => Promise<void>,
 ): Promise<string> {
   const model = ctx.model;
-  if (!model) throw new ContinuousError("model", "Agent mode paused: select an available model first.");
+  if (!model) throw new ContinuousError("model", "Autonomous sync paused: select an available model first.");
   if (!Number.isSafeInteger(model.maxTokens) || model.maxTokens < 0)
-    throw new Error("Agent mode paused: selected model has an invalid output limit.");
+    throw new Error("Autonomous sync paused: selected model has an invalid output limit.");
   // Pi uses zero for unknown limits, including virtual models. Its registry caps routed requests.
   const maxTokens = model.maxTokens > 0 ? Math.min(AGENT_MAX_TOKENS, model.maxTokens) : AGENT_MAX_TOKENS;
   const controller = new AbortController();
@@ -74,7 +74,7 @@ export async function runAgentResolver(
       },
     });
     const childModel = runtime.getModel(provider, "resolver");
-    if (!childModel) throw new Error("Agent mode paused: resolver model unavailable.");
+    if (!childModel) throw new Error("Autonomous sync paused: resolver model unavailable.");
     ({ session } = await createAgentSession({
       cwd: ctx.cwd,
       model: childModel,
@@ -104,7 +104,7 @@ export async function runAgentResolver(
     });
     child.agent.streamFunction = async (_model, context, options) => {
       ownedSignal.throwIfAborted();
-      if (++calls > 1) throw new Error("Agent mode paused: one provider request per candidate is permitted.");
+      if (++calls > 1) throw new Error("Autonomous sync paused: one provider request per candidate is permitted.");
       await validate(ownedSignal);
       ownedSignal.throwIfAborted();
       if (beforeRequest) {
@@ -146,15 +146,16 @@ export async function runAgentResolver(
         last.stopReason !== "stop" ||
         last.content.some((block) => block.type !== "text" && block.type !== "thinking")
       )
-        throw new Error("Agent mode paused: incomplete, failed or tool-bearing model output.");
+        throw new Error("Autonomous sync paused: incomplete, failed or tool-bearing model output.");
       const output = last.content
         .filter((block) => block.type === "text")
         .map((block) => block.text)
         .join("");
-      if (Buffer.byteLength(output) > AGENT_OUTPUT_BYTES) throw new Error("Agent mode paused: output bound exceeded.");
+      if (Buffer.byteLength(output) > AGENT_OUTPUT_BYTES)
+        throw new Error("Autonomous sync paused: output bound exceeded.");
       if (ctx.hasUI)
         ctx.ui.notify(
-          `Pi Sync agent candidate: ${last.usage.totalTokens} tokens. Semantic correctness is not guaranteed.`,
+          `Pi Sync resolver candidate: ${last.usage.totalTokens} tokens. Semantic correctness is not guaranteed.`,
           "info",
         );
       return output;
@@ -169,13 +170,13 @@ export async function runAgentResolver(
     if (failure.retry)
       throw new ContinuousError(
         failure.kind,
-        "Agent mode paused: transient resolver transport failure.",
+        "Autonomous sync paused: transient resolver transport failure.",
         failure.delay,
       );
     // Provider errors can quote submitted content or auth; never surface their payload.
     throw new ContinuousError(
       "model",
-      "Agent mode paused: resolver failed or returned unusable output. Check model access and retry later.",
+      "Autonomous sync paused: resolver failed or returned unusable output. Check model access and retry later.",
     );
   } finally {
     clearTimeout(timer);

package/src/sync/agent-store.ts

@@ -92,7 +92,7 @@ export async function withAgentClaim<T>(fn: (assertOwner: () => Promise<void>) =
       await withClaimGuard(async () => {
         const existing = await readClaim();
         if (existing && alive(existing.pid))
-          throw new ContinuousError("contention", "Agent mode deferred: another local resolver is running.");
+          throw new ContinuousError("contention", "Autonomous sync deferred: another local resolver is running.");
         // A durability failure can occur after rename: cleanup must own partial initialization too.
         armed = true;
         await writeJson(paths().claim, claim);

package/src/sync/agent-sync.ts

@@ -89,7 +89,7 @@ export async function withAgentSyncLock<T>(
         try {
           candidate = parseAgentCandidate(raw, request.evidence);
         } catch {
-          throw new ContinuousError("model", "Agent mode paused: invalid resolver output; evidence retained.");
+          throw new ContinuousError("model", "Autonomous sync paused: invalid resolver output; evidence retained.");
         }
         if (retry && candidate.results.some((row) => "refuse" in row))
           throw new ContinuousError("model", "The model refused again. The previous refusal was retained.");
@@ -132,7 +132,7 @@ export async function withAgentSyncLock<T>(
           request = error;
         }
       }
-      throw new ContinuousError("stale", "Agent mode paused: content changed repeatedly; retry later.");
+      throw new ContinuousError("stale", "Autonomous sync paused: content changed repeatedly; retry later.");
     } finally {
       options.signal?.removeEventListener("abort", onAbort);
       if (!options.signal?.aborted) clearStatus();