@narumitw/pi-sync 0.54.2 → 0.56.0

package/src/commands/command-execution.ts

@@ -5,6 +5,7 @@ import { localConfigTemplate, readLocalConfigObject } from "../settings/settings
 import type { AnySyncConfig } from "../settings/settings-types.js";
 import { unlock, withLock } from "../state/lock.js";
 import { migrateLegacyStateDirectory, stateDirectoryMigrationNotice } from "../state/state-directory.js";
+import { withAgentSyncLock } from "../sync/agent-sync.js";
 import { throwIfAborted } from "../sync/signals.js";
 import { syncErrorGuidance } from "../sync/sync-error-guidance.js";
 import { isSyncDecisionRequiredError, SetupPullRequiresUiError } from "../sync/sync-errors.js";
@@ -13,6 +14,7 @@ import { RemoteSelectionMismatchError } from "../sync/sync-policy.js";
 import { automaticSyncSummary } from "../ui/automatic-sync-summary.js";
 import type { RunRouteResult } from "../ui/cancellable-operation.js";
 import { trackOperationDialogs } from "../ui/operation-dialogs.js";
+import { startupTransferSummary } from "../ui/sync-behavior.js";
 import { setSyncStatus } from "../ui/sync-status.js";
 import { safeTerminalText } from "../ui/terminal-text.js";
 import { parseOptions, resolveSyncCommand, splitArgs, usage, validateCommandOptions } from "./command.js";
@@ -48,7 +50,7 @@ export async function executeRecoveryCommand(
       const outcome = await withLock("pull", () => operations.pull(ctx, options));
       return { kind: "completed", ...(outcome ? { outcome } : {}) };
     }
-    await withLock("sync", () => operations.syncBoth(ctx, options));
+    await withAgentSyncLock(ctx, options, (current) => operations.syncBoth(ctx, current));
     return { kind: "completed" };
   } catch (error) {
     if (signal?.aborted) return { kind: "failed" };
@@ -155,7 +157,7 @@ export async function executeCommand(
       case "sync": {
         const operations = await loaders.operations();
         throwIfAborted(options.signal);
-        await withLock("sync", () => operations.syncBoth(ctx, options));
+        await withAgentSyncLock(ctx, options, (current) => operations.syncBoth(ctx, current));
         return { kind: "completed" };
       }
       case "history": {
@@ -256,7 +258,9 @@ async function showConfig(ctx: ExtensionCommandContext, options: CommandOptions)
       `automatic sync: ${automaticSyncSummary(config.automatic)}`,
       `settings field merge: ${config.mergeSettings ? "On (experimental)" : "Off"}`,
       `machine-local settings.json fields: ${(config.localFields ?? []).map(safeTerminalText).join(", ") || "none"}`,
-      `automatic transfer at startup: ${config.automaticTransfer ? "On — selected-file upload/replace/delete; no reload" : "Off"}`,
+      `startup transfer: ${startupTransferSummary(config)}`,
+      `agent mode: ${config.agentMode ? "On (experimental)" : "Off"}`,
+      `continuous sync: ${config.continuous ? (config.agentMode ? "On (experimental)" : "paused; Agent mode is Off") : "Off"}`,
       `included content: ${config.include.join(", ") || "none"}`,
       `sessions: ${config.include.includes("sessions") ? "included" : "not included"}`,
       `settings file: ${localConfigPath()}`,

package/src/commands/command-handler.ts

@@ -13,7 +13,7 @@ import {
   syncAttentionMatchesConfig,
 } from "../ui/sync-attention.js";
 import { setSyncStatus } from "../ui/sync-status.js";
-import { parseOptions, splitArgs } from "./command.js";
+import { parseOptions, splitArgs, validateCommandOptions } from "./command.js";
 import { executeCommand, executeRecoveryCommand } from "./command-execution.js";
 
 export async function handleCommand(
@@ -22,6 +22,7 @@ export async function handleCommand(
   sessionSignal: AbortSignal,
   loaders: SyncLoaders,
   attention: SyncAttentionController,
+  onExplicitSync?: (setup?: string) => void,
 ) {
   await reconcileObservation(attention, sessionSignal);
   if (sessionSignal.aborted) return;
@@ -31,8 +32,18 @@ export async function handleCommand(
     onCommit?: () => void,
     target?: string,
     onDialog?: (active: boolean) => void,
-  ) =>
-    executeCommand(
+  ) => {
+    const [command, ...args] = splitArgs(route);
+    if (command === "sync") {
+      try {
+        const options = parseOptions(args);
+        validateCommandOptions("sync", options);
+        onExplicitSync?.(target ?? options.setup);
+      } catch {
+        /* Invalid routes do not request an automatic retry. */
+      }
+    }
+    return executeCommand(
       route,
       ctx,
       combineSignals(sessionSignal, signal),
@@ -41,6 +52,7 @@ export async function handleCommand(
       target,
       onDialog,
     );
+  };
   if (!rawArgs.trim()) {
     try {
       const { showSyncManager } = await import("../ui/manager-ui.js");

package/src/commands/command-types.ts

@@ -1,3 +1,7 @@
+import type { AnySyncConfig } from "../settings/settings-types.js";
+import type { AgentAcceptance } from "../sync/agent-request.js";
+import type { StartupTimings } from "../sync/startup-timings.js";
+
 export interface CommandOptions {
   yes: boolean;
   force: boolean;
@@ -8,6 +12,12 @@ export interface CommandOptions {
   setup?: string;
   signal?: AbortSignal;
   onCommit?: () => void;
+  /** In-memory startup diagnostics only; never persisted or sent to a backend. */
+  startupTimings?: StartupTimings;
+  /** Internal validated resolver result; never parsed from command arguments. */
+  agentAcceptance?: AgentAcceptance;
+  /** Internal cycle authorization, ownership and durable request reservation; never command arguments. */
+  background?: { validate(config?: AnySyncConfig): void; reserve(key: string): Promise<void> };
   args: string[];
 }
 

package/src/commands/command.ts

@@ -1,4 +1,5 @@
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { AUTOMATIC_SYNC_DESCRIPTION, STARTUP_TRANSFER_DESCRIPTION } from "../ui/sync-behavior.js";
 import type { CommandArgumentCompletion, CommandOptions } from "./command-types.js";
 
 const YES_FLAG_COMPLETIONS: readonly CommandArgumentCompletion[] = [
@@ -232,8 +233,10 @@ export function usage() {
   return [
     "Usage: /sync <command>",
     `Commands: ${commands}`,
-    "Automatic sync: background startup checks only; use /sync to review and transfer. At shutdown, selected content is pushed automatically only when sessions are included. Startup checks run in TUI/RPC, not print/JSON.",
+    `Automatic sync: ${AUTOMATIC_SYNC_DESCRIPTION}`,
+    `Startup transfer: ${STARTUP_TRANSFER_DESCRIPTION}`,
     "Automatic transfer at startup is a separate opt-in: one conflict-free established-baseline transfer at idle in TUI/RPC, with conditional/lease publication and no resource reload.",
+    "Experimental Continuous sync is a separate default-Off opt-in in Settings. It requires Agent mode, monitors while Pi is open, and can incur recurring network/model costs. Safety blocks and durable automatic request limits remain.",
     "Settings: use /sync init or edit storage connections and sync setups in ~/.pi/agent/pi-sync.json (or the configured Pi agent directory). Version 1 and version 2 settings are unsupported and are never rewritten.",
   ].join("\n");
 }

package/src/settings/config.ts

@@ -52,15 +52,18 @@ function configFromSettings(settings: PiSyncSettingsV3, setupName?: string): Any
       `Invalid pi-sync settings: sync setup “${selectedName}” references missing storage connection “${connectionName}”.`,
     );
   }
-  return resolveSyncConfig(
-    selectedName,
-    setup,
-    connectionName,
-    connection,
-    settings.onSwitch,
-    settings.skipSecretScan ?? false,
-    settings.showStatus ?? true,
-  );
+  return {
+    ...resolveSyncConfig(
+      selectedName,
+      setup,
+      connectionName,
+      connection,
+      settings.onSwitch,
+      settings.skipSecretScan ?? false,
+      settings.showStatus ?? true,
+    ),
+    debug: settings.debug ?? false,
+  };
 }
 
 export type SyncSetupStorageReview = Pick<
@@ -77,6 +80,8 @@ export async function loadPartialConfig(setupName?: string): Promise<PartialConf
     include: [...config.include],
     automatic: config.automatic,
     automaticTransfer: config.automaticTransfer ?? false,
+    agentMode: config.agentMode ?? false,
+    continuous: config.continuous ?? false,
     onSwitch: config.onSwitch,
     showStatus: config.showStatus,
   };
@@ -112,10 +117,13 @@ export function syncConfigReviewIdentity(config: AnySyncConfig) {
     config.include,
     config.automatic,
     config.automaticTransfer ?? false,
+    config.agentMode ?? false,
     config.localFields,
     config.mergeSettings ?? false,
     config.mergeContent ?? false,
     config.partialSync ?? false,
+    // Preserve existing Off identities and cached candidates across the upgrade.
+    ...(config.continuous ? ["continuous"] : []),
   ]);
 }
 
@@ -126,7 +134,7 @@ export function syncConfigReviewFingerprint(config: AnySyncConfig) {
 /** Internal freshness token, including credentials; never display or persist it. */
 export function syncCheckConfigFingerprint(config: AnySyncConfig) {
   return createHash("sha256")
-    .update(JSON.stringify({ ...config, showStatus: undefined }))
+    .update(JSON.stringify({ ...config, showStatus: undefined, debug: undefined }))
     .digest("hex");
 }
 
@@ -163,6 +171,8 @@ function resolveSyncConfig(
     include,
     automatic: setup.sync.automatic,
     automaticTransfer: setup.sync.automaticTransfer ?? false,
+    agentMode: setup.sync.agentMode ?? false,
+    continuous: setup.sync.continuous ?? false,
     localFields: setup.sync.localFields === undefined ? undefined : normalizeLocalFields(setup.sync.localFields),
     mergeSettings: setup.sync.mergeSettings ?? false,
     mergeContent: setup.sync.mergeContent ?? false,

package/src/settings/settings-store.ts

@@ -1,6 +1,3 @@
-import { randomUUID } from "node:crypto";
-import fs from "node:fs/promises";
-import path from "node:path";
 import { localConfigPath, readMigratingLocalConfigDocument, updateLocalConfigDocument } from "./config-file.js";
 import type { OnSwitchAction, PiSyncSettingsV3 } from "./settings-types.js";
 import { DEFAULT_ON_SWITCH, validateSettingsDocument } from "./settings-validation.js";
@@ -30,6 +27,7 @@ export function localConfigTemplate(): PiSyncSettingsV3 {
     onSwitch: DEFAULT_ON_SWITCH,
     skipSecretScan: false,
     showStatus: true,
+    debug: false,
     storageConnections: {},
     syncSetups: {},
   };
@@ -62,34 +60,3 @@ export function updateLocalConfig(update: (current: PiSyncSettingsV3) => PiSyncS
 async function performLocalConfigUpdate(update: (current: PiSyncSettingsV3) => PiSyncSettingsV3, signal?: AbortSignal) {
   return updateLocalConfigDocument(localConfigTemplate(), update, validateSettingsDocument, signal);
 }
-
-export async function writeLocalConfigObject(value: PiSyncSettingsV3 | Record<string, unknown>) {
-  validateSettingsDocument(value as Record<string, unknown>);
-  const configPath = localConfigPath();
-  await fs.mkdir(path.dirname(configPath), { recursive: true });
-  try {
-    const stat = await fs.lstat(configPath);
-    if (stat.isSymbolicLink()) throw new Error(`Refusing to overwrite symlinked pi-sync settings: ${configPath}`);
-    if (!stat.isFile()) throw new Error(`pi-sync settings are not a regular file: ${configPath}`);
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-  }
-  const temporaryPath = path.join(
-    path.dirname(configPath),
-    `.${path.basename(configPath)}.${process.pid}.${randomUUID()}.tmp`,
-  );
-  let handle: fs.FileHandle | undefined;
-  try {
-    handle = await fs.open(temporaryPath, "wx", 0o600);
-    await handle.writeFile(`${JSON.stringify(value, null, "\t")}\n`, "utf8");
-    if (process.platform !== "win32") await handle.chmod(0o600);
-    await handle.sync();
-    await handle.close();
-    handle = undefined;
-    await fs.rename(temporaryPath, configPath);
-  } catch (error) {
-    await handle?.close().catch(() => undefined);
-    await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
-    throw error;
-  }
-}

package/src/settings/settings-types.ts

@@ -81,6 +81,10 @@ export interface SyncPolicySettings {
   automatic: boolean;
   /** Explicit opt-in, separate from the legacy observe/shutdown policy. */
   automaticTransfer?: boolean;
+  /** Experimental autonomous merged-sync authorization. */
+  agentMode?: boolean;
+  /** Separate explicit authorization for recurring background work. */
+  continuous?: boolean;
   /** Version 4: settings.json root fields never uploaded. */
   localFields?: string[];
   mergeSettings?: boolean;
@@ -101,6 +105,7 @@ export interface PiSyncSettingsV3 {
   onSwitch: OnSwitchAction;
   skipSecretScan?: boolean;
   showStatus?: boolean;
+  debug?: boolean;
   storageConnections: Record<string, StorageConnectionSettings>;
   syncSetups: Record<string, SyncSetupSettings>;
   [key: string]: unknown;
@@ -115,6 +120,8 @@ export interface SyncConfig<Backend extends ResolvedSyncBackend = ResolvedS3Back
   include: string[];
   automatic: boolean;
   automaticTransfer?: boolean;
+  agentMode?: boolean;
+  continuous?: boolean;
   localFields?: string[];
   mergeSettings?: boolean;
   mergeContent?: boolean;
@@ -122,6 +129,7 @@ export interface SyncConfig<Backend extends ResolvedSyncBackend = ResolvedS3Back
   onSwitch: OnSwitchAction;
   skipSecretScan: boolean;
   showStatus: boolean;
+  debug?: boolean;
   backend: Backend;
 }
 
@@ -137,6 +145,8 @@ export interface PartialConfig {
   include: string[];
   automatic: boolean;
   automaticTransfer?: boolean;
+  agentMode?: boolean;
+  continuous?: boolean;
   onSwitch: OnSwitchAction;
   showStatus: boolean;
   bucket?: string;

package/src/settings/settings-validation.ts

@@ -68,6 +68,9 @@ export function validateSettingsDocument(value: Record<string, unknown>): PiSync
   if (value.showStatus !== undefined && typeof value.showStatus !== "boolean") {
     throw new Error("Invalid pi-sync settings: showStatus must be boolean.");
   }
+  if (value.debug !== undefined && typeof value.debug !== "boolean") {
+    throw new Error("Invalid pi-sync settings: debug must be boolean.");
+  }
   const storageConnections = requireNamedObjectMap(
     value.storageConnections,
     "storageConnections",
@@ -216,7 +219,7 @@ function validateSyncSetup(name: string, value: Record<string, unknown>, connect
   const localFields = normalizeLocalFields(sync.localFields);
   if (localFields.length > 0 && !include.includes("settings.json"))
     throw new Error("Nonempty localFields requires settings.json in sync.include.");
-  for (const key of ["mergeContent", "partialSync"])
+  for (const key of ["mergeContent", "partialSync", "agentMode", "continuous"])
     if (sync[key] !== undefined && typeof sync[key] !== "boolean") throw new Error(`${key} must be boolean.`);
   if (sync.mergeSettings !== undefined && typeof sync.mergeSettings !== "boolean")
     throw new Error("mergeSettings must be boolean.");

package/src/snapshot/snapshot-codec.ts

@@ -2,6 +2,7 @@ import { Readable, Writable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { promisify } from "node:util";
 import { createGunzip, gzip } from "node:zlib";
+import { throwIfAborted } from "../sync/signals.js";
 import { snapshotSelectionInclude } from "../sync/sync-policy.js";
 import type { Snapshot } from "./snapshot-types.js";
 
@@ -47,8 +48,3 @@ export async function decodeSnapshot(
   snapshotSelectionInclude(parsed);
   return parsed;
 }
-
-function throwIfAborted(signal?: AbortSignal) {
-  if (!signal?.aborted) return;
-  throw signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
-}

package/src/state/lock.ts

@@ -3,6 +3,7 @@ import fs from "node:fs/promises";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import lockfile from "proper-lockfile";
 import type { CommandOptions } from "../commands/command-types.js";
+import { throwIfAborted } from "../sync/signals.js";
 import { LOCK_GUARD_STALE_MS, LOCK_GUARD_UPDATE_MS } from "./lock-policy.js";
 import { LOCKFILE_FS_ADAPTER } from "./lockfile-fs.js";
 import type { LockFile } from "./state-types.js";
@@ -57,8 +58,11 @@ export async function withLock<T>(
       inspection = { status: "missing" };
     }
     if (inspection.status === "valid") {
-      throw new Error(
-        `pi-sync is already running (${inspection.lock.command}, pid ${inspection.lock.pid}, started ${inspection.lock.startedAt}).`,
+      throw Object.assign(
+        new Error(
+          `pi-sync is already running (${inspection.lock.command}, pid ${inspection.lock.pid}, started ${inspection.lock.startedAt}).`,
+        ),
+        { code: "ELOCKED" },
       );
     }
     if (inspection.status === "unreadable") {
@@ -220,11 +224,6 @@ async function unlockGuarded(ctx: ExtensionCommandContext, options: CommandOptio
   }
 }
 
-function throwIfAborted(signal?: AbortSignal) {
-  if (!signal?.aborted) return;
-  throw signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
-}
-
 async function releaseGuard(guard: Guard) {
   try {
     await guard.release();
@@ -261,11 +260,15 @@ async function describeHeldLock() {
     return new Error("pi-sync lock owner exited; retry shortly while the lock guard expires.");
   }
   if (current) {
-    return new Error(
-      `Pi-sync is currently running (${current.command}, pid ${current.pid}, started ${current.startedAt}).`,
+    return Object.assign(
+      new Error(`Pi-sync is currently running (${current.command}, pid ${current.pid}, started ${current.startedAt}).`),
+      { code: "ELOCKED" },
     );
   }
-  return new Error("Pi-sync is currently running (lock metadata is unreadable or still being written).");
+  return Object.assign(
+    new Error("Pi-sync is currently running (lock metadata is unreadable or still being written)."),
+    { code: "ELOCKED" },
+  );
 }
 
 function isLockHeldError(error: unknown) {

package/src/state/merge-baseline-store.ts

@@ -66,7 +66,7 @@ export async function stageMergeBaseline(
     return (
       !collisions.has(file.path) &&
       accepted.lastFileHashes[file.path] === file.sha256 &&
-      (file.path === "settings.json" || config.mergeContent) &&
+      (file.path === "settings.json" || config.mergeContent || (config.agentMode && isMergeTextPath(file.path))) &&
       eligible(file)
     );
   });
@@ -145,6 +145,24 @@ export async function readMergeAncestors(config: AnySyncConfig, state: SyncState
   }
   return record.files;
 }
+/** A no-op must not skip seeding or repairing ancestors required by later merges. */
+export async function hasCurrentMergeBaseline(config: AnySyncConfig, snapshot: Snapshot, state: SyncState) {
+  try {
+    const ancestors = await readMergeAncestors(config, state);
+    if (!ancestors) return false;
+    const hashes = new Map(ancestors.map((file) => [file.path, file.sha256]));
+    return snapshot.files.every(
+      (file) =>
+        !(file.path === "settings.json" || config.mergeContent || (config.agentMode && isMergeTextPath(file.path))) ||
+        !eligible(file) ||
+        hashes.get(file.path) === file.sha256,
+    );
+  } catch {
+    // Preserve the existing full path's validation and repair behavior for unknown evidence.
+    return false;
+  }
+}
+
 export async function readMergeAncestor(config: AnySyncConfig, state: SyncState, filePath: string) {
   const file = (await readMergeAncestors(config, state))?.find((file) => file.path === filePath);
   return file ? Buffer.from(file.contentBase64, "base64") : undefined;

package/src/state/state-directory.ts

@@ -79,7 +79,14 @@ export async function migrateLegacyStateDirectory(): Promise<StateDirectoryPrepa
       realpath: false,
       stale: LOCK_GUARD_STALE_MS,
     });
-    if (legacyGuardHeld || (await pathExists(legacyLock))) {
+    // Idle continuous owners do not retain the exclusive migration guard.
+    // A live renewable lease still prevents moving their private state root.
+    const schedulerHeld = await lockfile.check(path.join(legacyStateDir(), "continuous", "scheduler"), {
+      fs: LOCKFILE_FS_ADAPTER,
+      realpath: false,
+      stale: LOCK_GUARD_STALE_MS,
+    });
+    if (legacyGuardHeld || schedulerHeld || (await pathExists(legacyLock))) {
       return {
         status: "deferred",
         message: