@wspc/cli 0.1.2 → 0.1.4

package/dist/cli.js

@@ -1464,9 +1464,9 @@ function createConsistencyFetch(opts) {
 }
 
 // src/version.ts
-var VERSION = "0.1.2";
+var VERSION = "0.1.4";
 var SPEC_SHA = "e0bbc1e3";
-var SPEC_FETCHED_AT = "2026-06-21T13:29:36.026Z";
+var SPEC_FETCHED_AT = "2026-06-22T06:55:37.490Z";
 var API_BASE = "https://api.wspc.ai";
 
 // src/index.ts
@@ -1620,8 +1620,19 @@ async function loadAuthedFetch(opts = {}) {
   const { fetch: fetch2, baseUrl } = await loadClientParts(opts);
   return { fetch: fetch2, baseUrl };
 }
+async function loadRealtimeAuthHeaders(opts = {}) {
+  const { baseUrl, authInterceptor } = await loadClientParts(opts);
+  const verifyUrl = new URL(opts.verifyPath ?? "/auth/me", `${baseUrl.replace(/\/$/, "")}/`);
+  const verifyResponse = await authInterceptor.execute(new Request(verifyUrl));
+  if (!verifyResponse.ok) {
+    throw new Error(`realtime auth failed: HTTP ${verifyResponse.status}`);
+  }
+  const request = await authInterceptor.onRequest(new Request(baseUrl));
+  return { baseUrl, headers: request.headers };
+}
 async function loadSdkClientWithAuthedFetch(opts = {}) {
-  return loadClientParts(opts);
+  const { _rawClient, fetch: fetch2, baseUrl } = await loadClientParts(opts);
+  return { _rawClient, fetch: fetch2, baseUrl };
 }
 async function loadClientParts(opts = {}) {
   const store = opts.store ?? new ConfigStore();
@@ -1641,7 +1652,7 @@ async function loadClientParts(opts = {}) {
       fetch: authedFetch
     })
   );
-  return { _rawClient: rawClient, fetch: authedFetch, baseUrl: resolved.apiBase };
+  return { _rawClient: rawClient, fetch: authedFetch, baseUrl: resolved.apiBase, authInterceptor: interceptor };
 }
 
 // src/handwritten/output/primitives.ts
@@ -1867,22 +1878,24 @@ function render(ctx, data) {
   renderPaginationFooter(data);
 }
 function renderPaginationFooter(data) {
-  if (data === null || typeof data !== "object") return;
-  const d = data;
-  if (typeof d.next_cursor === "string" && d.next_cursor.length > 0) {
-    process.stdout.write(dim(`  \u2026 more results \u2014 re-run with --cursor ${d.next_cursor}`) + "\n");
-  }
-  const id = typeof d.id === "string" ? d.id : "<id>";
-  if (typeof d.children_next_cursor === "string" && d.children_next_cursor.length > 0) {
+  if (!isRecord(data)) return;
+  const nextCursor = getString(data, "next_cursor");
+  if (nextCursor !== void 0 && nextCursor.length > 0) {
+    process.stdout.write(dim(`  \u2026 more results \u2014 re-run with --cursor ${nextCursor}`) + "\n");
+  }
+  const id = getString(data, "id") ?? "<id>";
+  const childrenNextCursor = getString(data, "children_next_cursor");
+  if (childrenNextCursor !== void 0 && childrenNextCursor.length > 0) {
     process.stdout.write(dim(`  \u2026 more children \u2014 wspc todo ls --parent ${id}`) + "\n");
   }
-  if (typeof d.comments_next_cursor === "string" && d.comments_next_cursor.length > 0) {
+  const commentsNextCursor = getString(data, "comments_next_cursor");
+  if (commentsNextCursor !== void 0 && commentsNextCursor.length > 0) {
     process.stdout.write(dim(`  \u2026 more comments \u2014 wspc todo comment ls ${id}`) + "\n");
   }
 }
 function drillDataPath(data, dataPath) {
   if (!dataPath) return data;
-  if (data === null || typeof data !== "object") return data;
+  if (!isRecord(data)) return data;
   const value = data[dataPath];
   return value === void 0 ? data : value;
 }
@@ -1910,9 +1923,9 @@ function renderGeneric(data, hints) {
 }
 function detectShape(data) {
   if (Array.isArray(data)) return "list";
-  if (typeof data === "object" && data !== null) {
+  if (isRecord(data)) {
     const keys = Object.keys(data);
-    const arrayKeys = keys.filter((k) => Array.isArray(data[k]));
+    const arrayKeys = keys.filter((k) => getArray(data, k) !== void 0);
     if (arrayKeys.length === 1) return "list";
     return "object";
   }
@@ -1920,9 +1933,10 @@ function detectShape(data) {
 }
 function extractItems(data) {
   if (Array.isArray(data)) return data;
-  if (typeof data === "object" && data !== null) {
-    for (const v of Object.values(data)) {
-      if (Array.isArray(v)) return v;
+  if (isRecord(data)) {
+    for (const key of Object.keys(data)) {
+      const value = getArray(data, key);
+      if (value !== void 0) return value;
     }
   }
   return [];
@@ -1933,13 +1947,13 @@ function renderList(data, hints) {
     process.stdout.write(dim("  " + (hints?.emptyMessage ?? "no items")) + "\n");
     return;
   }
-  const first = items[0];
+  const first = isRecord(items[0]) ? items[0] : {};
   const columns = pickColumns(first, hints?.columns);
   const format = hints?.format ?? {};
   const headers = columns.map((c) => c.toUpperCase());
   const rows = items.map(
     (item) => columns.map(
-      (col) => formatCell(item[col], format[col], hints?.enumColorMap?.[col])
+      (col) => formatCell(isRecord(item) ? item[col] : void 0, format[col], hints?.enumColorMap?.[col])
     )
   );
   process.stdout.write(table(headers, rows));
@@ -1957,7 +1971,7 @@ function pickColumns(first, hint) {
   return ordered.slice(0, 5);
 }
 function renderObject(data, hints) {
-  if (typeof data !== "object" || data === null) {
+  if (!isRecord(data)) {
     renderScalar(data);
     return;
   }
@@ -1966,7 +1980,7 @@ function renderObject(data, hints) {
   if (topKeys.length === 1) {
     const onlyKey = topKeys[0];
     const inner = obj[onlyKey];
-    if (inner && typeof inner === "object" && !Array.isArray(inner)) {
+    if (isRecord(inner)) {
       obj = inner;
     }
   }
@@ -1977,7 +1991,10 @@ function renderObject(data, hints) {
   }
   const format = hints?.format ?? {};
   const arrayFields = hints?.fields ? [] : Object.keys(obj).filter(
-    (k) => Array.isArray(obj[k]) && obj[k].length > 0
+    (k) => {
+      const value = getArray(obj, k);
+      return value !== void 0 && value.length > 0;
+    }
   );
   const formatted = fields.map((f) => [
     f,
@@ -2006,7 +2023,8 @@ function renderObject(data, hints) {
   for (const f of arrayFields) {
     const uncapped = f === "children" || f === "comments";
     const max = uncapped ? Number.POSITIVE_INFINITY : ARRAY_FIELD_MAX_ITEMS;
-    renderArrayField(f, obj[f], labelWidth, max);
+    const items = getArray(obj, f);
+    if (items !== void 0) renderArrayField(f, items, labelWidth, max);
   }
   const hadAbove = inlineFinal.length > 0 || arrayFields.length > 0;
   blocks.forEach(([f, value], i) => {
@@ -2058,28 +2076,31 @@ function formatArrayItem(item) {
   return JSON.stringify(item);
 }
 function formatTodoLike(item) {
-  if (!item || typeof item !== "object" || Array.isArray(item)) return null;
-  const rec = item;
-  if (typeof rec.id !== "string" || typeof rec.title !== "string") return null;
-  const id = idShort(rec.id);
-  const status = typeof rec.status === "string" ? statusBadge(rec.status) : "";
-  return status ? `${id}  ${status}  ${rec.title}` : `${id}  ${rec.title}`;
+  if (!isRecord(item)) return null;
+  const idValue = getString(item, "id");
+  const title = getString(item, "title");
+  if (idValue === void 0 || title === void 0) return null;
+  const status = getString(item, "status");
+  const id = idShort(idValue);
+  const statusText = status === void 0 ? "" : statusBadge(status);
+  return statusText ? `${id}  ${statusText}  ${title}` : `${id}  ${title}`;
 }
 function formatCommentLike(item) {
-  if (!item || typeof item !== "object" || Array.isArray(item)) return null;
-  const rec = item;
-  if (typeof rec.id !== "string" || typeof rec.content !== "string") return null;
-  const id = idShort(rec.id);
-  const when = rec.created_at !== void 0 ? `${relativeTime(rec.created_at)}  ` : "";
-  const snippet = truncate(rec.content, 60);
+  if (!isRecord(item)) return null;
+  const idValue = getString(item, "id");
+  const content = getString(item, "content");
+  if (idValue === void 0 || content === void 0) return null;
+  const id = idShort(idValue);
+  const when = item.created_at !== void 0 ? `${relativeTime(item.created_at)}  ` : "";
+  const snippet = truncate(content, 60);
   return `${id}  ${when}${snippet}`;
 }
 function formatAttendeeLike(item) {
-  if (!item || typeof item !== "object" || Array.isArray(item)) return null;
-  const rec = item;
-  const email = typeof rec.email === "string" ? rec.email : null;
+  if (!isRecord(item)) return null;
+  const email = getString(item, "email");
   if (!email) return null;
-  const name = typeof rec.display_name === "string" && rec.display_name.length > 0 ? rec.display_name : null;
+  const displayName = getString(item, "display_name");
+  const name = displayName !== void 0 && displayName.length > 0 ? displayName : void 0;
   return name ? `${name} <${email}>` : `<${email}>`;
 }
 function renderScalar(data) {
@@ -2100,6 +2121,17 @@ function renderScalar(data) {
 function isScalar(v) {
   return v === null || typeof v !== "object" && typeof v !== "function";
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getString(record, key) {
+  const value = record[key];
+  return typeof value === "string" ? value : void 0;
+}
+function getArray(record, key) {
+  const value = record[key];
+  return Array.isArray(value) ? value : void 0;
+}
 function formatCell(value, fmt, colorMap, opts) {
   if (fmt !== "enum-badge" && (value === void 0 || value === null)) return dim("\u2014");
   switch (fmt) {
@@ -3262,7 +3294,7 @@ var pushTestCommand = new Command45("test").description("Send a test push notifi
   }
   render({ kind: "push_test", display: { "shape": "object", "fields": ["ok", "status", "detail", "durationMs"], "format": { "ok": "bool-badge" } } }, result.data);
   if (result.data?.ok === false) {
-    process.exit(1);
+    process.exitCode = 1;
   }
 });
 
@@ -3840,13 +3872,15 @@ async function ensureClientId(opts) {
     apiBase: opts.baseUrl,
     fetchImpl: opts.fetchImpl
   });
-  const c = await opts.store.read();
-  const existing = c.envs[opts.envName]?.client_id;
+  let existing;
+  await opts.store.update((c) => {
+    existing = c.envs[opts.envName]?.client_id;
+    if (existing) return;
+    const targetEnv = c.envs[opts.envName] ??= { api_base: opts.baseUrl, accounts: {} };
+    targetEnv.api_base = opts.baseUrl;
+    targetEnv.accounts ??= {};
+  });
   if (existing) return existing;
-  const targetEnv = c.envs[opts.envName] ??= { api_base: opts.baseUrl, accounts: {} };
-  targetEnv.api_base = opts.baseUrl;
-  targetEnv.accounts ??= {};
-  await opts.store.write(c);
   const res = await fetchImpl(`${opts.baseUrl}/auth/oauth/register`, {
     method: "POST",
     headers: { "content-type": "application/json" },
@@ -3862,12 +3896,18 @@ async function ensureClientId(opts) {
   }
   const body = await res.json();
   if (!body.client_id) throw new Error("client_registration_failed: missing client_id in response");
-  const fresh = await opts.store.read();
-  const env = fresh.envs[opts.envName] ?? { api_base: opts.baseUrl, accounts: {} };
-  env.client_id = body.client_id;
-  fresh.envs[opts.envName] = env;
-  await opts.store.write(fresh);
-  return body.client_id;
+  let clientId = body.client_id;
+  await opts.store.update((c) => {
+    const env = c.envs[opts.envName] ??= { api_base: opts.baseUrl, accounts: {} };
+    env.api_base = opts.baseUrl;
+    env.accounts ??= {};
+    if (env.client_id) {
+      clientId = env.client_id;
+      return;
+    }
+    env.client_id = body.client_id;
+  });
+  return clientId;
 }
 
 // src/handwritten/auth/fetch-me.ts
@@ -3924,36 +3964,36 @@ async function runLogin(opts) {
   const now = opts.now ?? Date.now;
   const me = opts.fetchMe ?? ((o) => fetchMe(o));
   if (opts.apiKey) {
-    const initial = await opts.store.read();
-    getOrCreateEnv(initial, envName, opts.baseUrl);
-    initial.current_env = envName;
-    await opts.store.write(initial);
+    await opts.store.update((initial) => {
+      getOrCreateEnv(initial, envName, opts.baseUrl);
+      initial.current_env = envName;
+    });
     const who2 = await me({
       baseUrl: opts.baseUrl,
       token: opts.apiKey,
       store: opts.store,
       envName
     });
-    const c2 = await opts.store.read();
-    const env2 = getOrCreateEnv(c2, envName, opts.baseUrl);
-    const prev2 = env2.accounts[who2.email] ?? { email: who2.email };
-    const acct2 = env2.accounts[who2.email] = {
-      ...prev2,
-      email: who2.email,
-      user_id: who2.user_id,
-      api_key: opts.apiKey
-    };
-    delete acct2.refresh_token;
-    delete acct2.access_token;
-    delete acct2.access_token_expires_at;
-    env2.current_account = who2.email;
-    if (who2.email !== LEGACY_ACCOUNT_KEY) delete env2.accounts[LEGACY_ACCOUNT_KEY];
-    c2.current_env = envName;
-    await opts.store.write(c2);
+    await opts.store.update((c) => {
+      const env = getOrCreateEnv(c, envName, opts.baseUrl);
+      const prev = env.accounts[who2.email] ?? { email: who2.email };
+      const acct = env.accounts[who2.email] = {
+        ...prev,
+        email: who2.email,
+        user_id: who2.user_id,
+        api_key: opts.apiKey
+      };
+      delete acct.refresh_token;
+      delete acct.access_token;
+      delete acct.access_token_expires_at;
+      env.current_account = who2.email;
+      if (who2.email !== LEGACY_ACCOUNT_KEY) delete env.accounts[LEGACY_ACCOUNT_KEY];
+      c.current_env = envName;
+    });
     opts.output.write(`${green("\u2713")} logged in (api key) as ${bold(who2.email)} ${dim(`\u2192 env "${envName}"`)}`);
     return;
   }
-  const ensureClient = opts.ensureClient ?? ((env2) => ensureClientId({ store: opts.store, envName: env2, baseUrl: opts.baseUrl }));
+  const ensureClient = opts.ensureClient ?? ((env) => ensureClientId({ store: opts.store, envName: env, baseUrl: opts.baseUrl }));
   const clientId = opts.clientId ?? await ensureClient(envName);
   const flow = opts.deviceFlow ?? runDeviceFlow;
   const result = await flow({
@@ -3973,22 +4013,22 @@ async function runLogin(opts) {
     store: opts.store,
     envName
   });
-  const c = await opts.store.read();
-  const env = getOrCreateEnv(c, envName, opts.baseUrl);
-  const prev = env.accounts[who.email] ?? { email: who.email };
-  const acct = env.accounts[who.email] = {
-    ...prev,
-    email: who.email,
-    user_id: who.user_id,
-    refresh_token: result.refresh_token,
-    access_token: result.access_token,
-    access_token_expires_at: now() + result.expires_in * 1e3
-  };
-  delete acct.api_key;
-  env.current_account = who.email;
-  if (who.email !== LEGACY_ACCOUNT_KEY) delete env.accounts[LEGACY_ACCOUNT_KEY];
-  c.current_env = envName;
-  await opts.store.write(c);
+  await opts.store.update((c) => {
+    const env = getOrCreateEnv(c, envName, opts.baseUrl);
+    const prev = env.accounts[who.email] ?? { email: who.email };
+    const acct = env.accounts[who.email] = {
+      ...prev,
+      email: who.email,
+      user_id: who.user_id,
+      refresh_token: result.refresh_token,
+      access_token: result.access_token,
+      access_token_expires_at: now() + result.expires_in * 1e3
+    };
+    delete acct.api_key;
+    env.current_account = who.email;
+    if (who.email !== LEGACY_ACCOUNT_KEY) delete env.accounts[LEGACY_ACCOUNT_KEY];
+    c.current_env = envName;
+  });
   opts.output.writeJson({ event: "login_success", email: who.email });
   opts.output.write(`${green("\u2713")} logged in as ${bold(who.email)} ${dim(`\u2192 env "${envName}"`)}`);
 }
@@ -4025,27 +4065,32 @@ import { Command as Command63 } from "commander";
 
 // src/handwritten/auth/logout.ts
 async function runLogout(opts) {
-  const c = await opts.store.read();
-  const envName = opts.envName ?? c.current_env;
-  if (!envName || !c.envs[envName]) return { removed: [] };
-  const env = c.envs[envName];
-  env.accounts ??= {};
-  if (opts.all) {
-    const removed = Object.keys(env.accounts);
-    env.accounts = {};
-    env.current_account = void 0;
-    await opts.store.write(c);
-    return { removed };
-  }
-  const target = opts.email ?? env.current_account ?? (Object.keys(env.accounts).length === 1 ? Object.keys(env.accounts)[0] : void 0);
-  if (!target || !env.accounts[target]) return { removed: [] };
-  delete env.accounts[target];
-  if (env.current_account === target) {
-    const remaining = Object.keys(env.accounts);
-    env.current_account = remaining.length === 1 ? remaining[0] : void 0;
-  }
-  await opts.store.write(c);
-  return { removed: [target], newActive: env.current_account };
+  let removed = [];
+  let newActive;
+  let removedSingleAccount = false;
+  await opts.store.update((c) => {
+    const envName = opts.envName ?? c.current_env;
+    if (!envName || !c.envs[envName]) return;
+    const env = c.envs[envName];
+    env.accounts ??= {};
+    if (opts.all) {
+      removed = Object.keys(env.accounts);
+      env.accounts = {};
+      env.current_account = void 0;
+      return;
+    }
+    const target = opts.email ?? env.current_account ?? (Object.keys(env.accounts).length === 1 ? Object.keys(env.accounts)[0] : void 0);
+    if (!target || !env.accounts[target]) return;
+    delete env.accounts[target];
+    removed = [target];
+    removedSingleAccount = true;
+    if (env.current_account === target) {
+      const remaining = Object.keys(env.accounts);
+      env.current_account = remaining.length === 1 ? remaining[0] : void 0;
+    }
+    newActive = env.current_account;
+  });
+  return removedSingleAccount ? { removed, newActive } : { removed };
 }
 
 // src/handwritten/commands/logout.ts
@@ -4089,10 +4134,9 @@ registerRenderer("whoami", (data) => {
   }
 });
 async function backfillActiveEmail(store, envName, email, userId) {
-  const cfg = await store.read();
-  if (rekeyLegacyAccount(cfg, envName, email, userId)) {
-    await store.write(cfg);
-  }
+  await store.update((cfg) => {
+    rekeyLegacyAccount(cfg, envName, email, userId);
+  });
 }
 var whoamiCommand = new Command64("whoami").description("Show the active env, signed-in account, and organization").action(async () => {
   const store = new ConfigStore();
@@ -4167,24 +4211,24 @@ registerRenderer("config_show", (data) => {
   process.stdout.write(table(headers, rows));
 });
 async function setConfigKey(store, key, value) {
-  const c = await store.read();
-  const resolved = resolveAccount(c, { accountOverride: process.env.WSPC_ACCOUNT });
-  const env = c.envs[resolved.envName];
-  if (!env) throw new Error(`env "${resolved.envName}" not found`);
-  const acct = env.accounts[resolved.email];
-  if (!acct) throw new Error(`account "${resolved.email}" not found`);
-  switch (key) {
-    case "actor":
-      if (value !== "user" && value !== "agent") throw new Error("actor must be 'user' or 'agent'");
-      acct.actor = value;
-      break;
-    case "agent-label":
-      acct.agent_label = value;
-      break;
-    default:
-      throw new Error(`unknown config key: ${key}`);
-  }
-  await store.write(c);
+  await store.update((c) => {
+    const resolved = resolveAccount(c, { accountOverride: process.env.WSPC_ACCOUNT });
+    const env = c.envs[resolved.envName];
+    if (!env) throw new Error(`env "${resolved.envName}" not found`);
+    const acct = env.accounts[resolved.email];
+    if (!acct) throw new Error(`account "${resolved.email}" not found`);
+    switch (key) {
+      case "actor":
+        if (value !== "user" && value !== "agent") throw new Error("actor must be 'user' or 'agent'");
+        acct.actor = value;
+        break;
+      case "agent-label":
+        acct.agent_label = value;
+        break;
+      default:
+        throw new Error(`unknown config key: ${key}`);
+    }
+  });
 }
 configCommand.command("show").description("List configured envs (tokens redacted, current marked with \u2713)").action(async () => {
   const c = await new ConfigStore().read();
@@ -4210,10 +4254,10 @@ configCommand.command("set <key> <value>").description("Set a field on the activ
 });
 configCommand.command("use <env>").description("Switch current_env").action(async (env) => {
   const store = new ConfigStore();
-  const c = await store.read();
-  if (!c.envs[env]) throw new Error(`env "${env}" not found`);
-  c.current_env = env;
-  await store.write(c);
+  await store.update((c) => {
+    if (!c.envs[env]) throw new Error(`env "${env}" not found`);
+    c.current_env = env;
+  });
   process.stdout.write(`\u2713 current_env=${env}
 `);
 });
@@ -4234,15 +4278,15 @@ async function listAccounts(store) {
   }));
 }
 async function switchAccount(store, email) {
-  const c = await store.read();
-  const envName = c.current_env;
-  if (!envName || !c.envs[envName]) throw new Error("no current env; run `wspc login` first");
-  const env = c.envs[envName];
-  if (!env.accounts?.[email]) {
-    throw new Error(`no account '${email}' in env '${envName}'. Run \`wspc account ls\` or \`wspc login\`.`);
-  }
-  env.current_account = email;
-  await store.write(c);
+  await store.update((c) => {
+    const envName = c.current_env;
+    if (!envName || !c.envs[envName]) throw new Error("no current env; run `wspc login` first");
+    const env = c.envs[envName];
+    if (!env.accounts?.[email]) {
+      throw new Error(`no account '${email}' in env '${envName}'. Run \`wspc account ls\` or \`wspc login\`.`);
+    }
+    env.current_account = email;
+  });
 }
 registerRenderer("account_ls", (data) => {
   const rows = data.accounts;
@@ -4463,11 +4507,12 @@ import { pipeline } from "stream/promises";
 function parseContentDispositionFilename(header) {
   if (!header) return void 0;
   if (!header.toLowerCase().startsWith("attachment")) return void 0;
-  const quoted = header.match(/filename="([^"]+)"/i);
-  if (quoted) return quoted[1];
+  const quoted = header.match(/filename="([^"]*)"/i);
   const unquoted = header.match(/filename=([^;\s]+)/i);
-  if (unquoted) return unquoted[1];
-  return void 0;
+  const filename = quoted?.[1] ?? unquoted?.[1];
+  if (!filename || filename === "." || filename === "..") return void 0;
+  if (filename.includes("/") || filename.includes("\\")) return void 0;
+  return filename;
 }
 
 // src/handwritten/commands/email/attachment.ts
@@ -4595,6 +4640,29 @@ async function createDriveApi(opts = {}) {
 import { mkdir, open, readFile as readFile2, rename, rm, writeFile } from "fs/promises";
 import { randomUUID } from "crypto";
 import { join as join2 } from "path";
+import { DateTime as DateTime4 } from "luxon";
+
+// src/handwritten/commands/drive/clock.ts
+import { DateTime as DateTime3 } from "luxon";
+var systemDriveClock = {
+  now: () => DateTime3.utc()
+};
+function driveIsoTimestamp(clock = systemDriveClock) {
+  const timestamp = clock.now().toISO();
+  if (timestamp === null) {
+    throw new Error("invalid drive clock timestamp");
+  }
+  return timestamp;
+}
+function driveConflictTimestamp(clock = systemDriveClock) {
+  const timestamp = clock.now().toUTC();
+  if (!timestamp.isValid) {
+    throw new Error("invalid drive clock timestamp");
+  }
+  return timestamp.toFormat("yyyyLLdd'T'HHmmss'Z'");
+}
+
+// src/handwritten/commands/drive/state.ts
 var DRIVE_DIR = ".wspc-drive";
 var STATE_FILE = "state.json";
 function statePath(root) {
@@ -4608,13 +4676,13 @@ async function readDriveState(root) {
   }
   return parsed;
 }
-async function writeDriveState(root, state) {
+async function writeDriveState(root, state, clock) {
   await mkdir(join2(root, DRIVE_DIR), { recursive: true });
   const tmp = join2(root, DRIVE_DIR, `state.json.tmp-${process.pid}-${randomUUID()}`);
   const snapshot = JSON.stringify(
     {
       ...state,
-      updated_at: (/* @__PURE__ */ new Date()).toISOString()
+      updated_at: driveIsoTimestamp(clock)
     },
     null,
     2
@@ -4633,7 +4701,7 @@ async function writeDriveState(root, state) {
     await rm(tmp, { force: true });
   }
 }
-async function initDriveState(root, libraryId) {
+async function initDriveState(root, libraryId, clock) {
   await mkdir(join2(root, DRIVE_DIR), { recursive: true });
   try {
     const existing = await readDriveState(root);
@@ -4644,7 +4712,7 @@ async function initDriveState(root, libraryId) {
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
   }
-  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const now = driveIsoTimestamp(clock);
   const state = {
     schema_version: 1,
     library_id: libraryId,
@@ -4653,9 +4721,32 @@ async function initDriveState(root, libraryId) {
     entries: {},
     conflicts: {}
   };
-  await writeDriveState(root, state);
+  await writeDriveState(root, state, clock);
   return state;
 }
+async function ensureDriveRealtimeState(root) {
+  return withDriveLock(root, async () => {
+    const state = await readDriveState(root);
+    if (state.realtime?.client_id !== void 0) {
+      return state;
+    }
+    const next = {
+      ...state,
+      realtime: {
+        ...state.realtime,
+        client_id: `drvcli_${randomUUID().replace(/-/g, "")}`
+      }
+    };
+    await writeDriveState(root, next);
+    return next;
+  });
+}
+async function writeDriveRealtimeState(root, realtime) {
+  await withDriveLock(root, async () => {
+    const current = await readDriveState(root);
+    await writeDriveState(root, { ...current, realtime });
+  });
+}
 async function withDriveLock(root, fn) {
   await mkdir(join2(root, DRIVE_DIR), { recursive: true });
   const lockFile = join2(root, DRIVE_DIR, "sync.lock");
@@ -4674,18 +4765,28 @@ async function withDriveLock(root, fn) {
     });
   }
 }
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isDriveStateEntry(value) {
-  return isRecord(value) && typeof value.entry_id === "string" && typeof value.entry_version === "number" && typeof value.size_bytes === "number" && typeof value.last_synced_at === "string" && value.status === "synced" && (value.current_version_id === void 0 || typeof value.current_version_id === "string") && (value.content_sha256 === void 0 || typeof value.content_sha256 === "string") && (value.last_local_sha256 === void 0 || typeof value.last_local_sha256 === "string");
+  return isRecord2(value) && typeof value.entry_id === "string" && typeof value.entry_version === "number" && typeof value.size_bytes === "number" && typeof value.last_synced_at === "string" && value.status === "synced" && (value.current_version_id === void 0 || typeof value.current_version_id === "string") && (value.content_sha256 === void 0 || typeof value.content_sha256 === "string") && (value.last_local_sha256 === void 0 || typeof value.last_local_sha256 === "string");
 }
 function isDriveConflict(value) {
-  return isRecord(value) && typeof value.detected_at === "string" && typeof value.reason === "string" && (value.type === void 0 || value.type === "edit_edit" || value.type === "create_create" || value.type === "delete_edit" || value.type === "edit_delete") && (value.strategy === void 0 || value.strategy === "clean_merge" || value.strategy === "conflict_copy" || value.strategy === "record_only") && (value.base_version_id === void 0 || typeof value.base_version_id === "string") && (value.remote_entry_version === void 0 || typeof value.remote_entry_version === "number") && (value.remote_version_id === void 0 || typeof value.remote_version_id === "string") && (value.conflict_paths === void 0 || Array.isArray(value.conflict_paths) && value.conflict_paths.every((path) => typeof path === "string"));
+  return isRecord2(value) && typeof value.detected_at === "string" && typeof value.reason === "string" && (value.type === void 0 || value.type === "edit_edit" || value.type === "create_create" || value.type === "delete_edit" || value.type === "edit_delete") && (value.strategy === void 0 || value.strategy === "clean_merge" || value.strategy === "conflict_copy" || value.strategy === "record_only") && (value.base_version_id === void 0 || typeof value.base_version_id === "string") && (value.remote_entry_version === void 0 || typeof value.remote_entry_version === "number") && (value.remote_version_id === void 0 || typeof value.remote_version_id === "string") && (value.conflict_paths === void 0 || Array.isArray(value.conflict_paths) && value.conflict_paths.every((path) => typeof path === "string"));
+}
+function isDriveRealtimeState(value) {
+  const allowedKeys = /* @__PURE__ */ new Set(["client_id", "last_cursor", "last_connected_at", "last_event_at"]);
+  return isRecord2(value) && Object.keys(value).every((key) => allowedKeys.has(key)) && (value.client_id === void 0 || typeof value.client_id === "string" && /^drvcli_[A-Za-z0-9_-]+$/.test(value.client_id)) && (value.last_cursor === void 0 || typeof value.last_cursor === "string") && isOptionalIsoTimestamp(value.last_connected_at) && isOptionalIsoTimestamp(value.last_event_at);
+}
+function isOptionalIsoTimestamp(value) {
+  if (value === void 0) return true;
+  if (typeof value !== "string") return false;
+  if (!/T.*(?:Z|[+-]\d{2}:\d{2})$/.test(value)) return false;
+  return DateTime4.fromISO(value, { setZone: true }).isValid;
 }
 function isValidDriveState(value) {
-  if (!isRecord(value)) return false;
-  if (value.schema_version !== 1 || typeof value.library_id !== "string" || typeof value.created_at !== "string" || typeof value.updated_at !== "string" || !isRecord(value.entries) || !isRecord(value.conflicts)) {
+  if (!isRecord2(value)) return false;
+  if (value.schema_version !== 1 || typeof value.library_id !== "string" || typeof value.created_at !== "string" || typeof value.updated_at !== "string" || !isRecord2(value.entries) || !isRecord2(value.conflicts) || value.realtime !== void 0 && !isDriveRealtimeState(value.realtime)) {
     return false;
   }
   for (const entry of Object.values(value.entries)) {
@@ -4729,12 +4830,9 @@ function driveBindCommand() {
 
 // src/handwritten/commands/drive/sync.ts
 import { Command as Command71 } from "commander";
-import { createWriteStream as createWriteStream2 } from "fs";
-import { link, mkdir as mkdir2, readFile as readFile3, rename as rename2, rm as rm2, unlink, writeFile as writeFile2 } from "fs/promises";
-import { basename as basename2, dirname, join as join4, posix as pathPosix2, resolve as resolve3 } from "path";
-import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
-import { Readable as Readable2, Transform } from "stream";
-import { pipeline as pipeline2 } from "stream/promises";
+import { mkdir as mkdir3, readFile as readFile4, rm as rm3, writeFile as writeFile3 } from "fs/promises";
+import { basename as basename3, dirname as dirname2, join as join5, posix as pathPosix2, resolve as resolve3 } from "path";
+import { createHash as createHash3, randomUUID as randomUUID3 } from "crypto";
 
 // src/handwritten/commands/drive/decision.ts
 function decideDriveAction(entry, local, remote) {
@@ -4806,6 +4904,96 @@ function getRemoteStatus(entry, remote) {
   return "changed";
 }
 
+// src/handwritten/commands/drive/path-policy.ts
+import { isAbsolute, relative, resolve as resolve2, sep } from "path";
+var UTF8_SEGMENT_LIMIT = 255;
+var UTF8_PATH_LIMIT = 1024;
+var CONTROL_CHARS = /[\0-\x1f\x7f]/;
+var WINDOWS_DRIVE_PREFIX = /^[a-zA-Z]:/;
+var UNC_PREFIX = /^\\\\/;
+var ABSOLUTE_POSIX_DOUBLE_SLASH = /^\/\//;
+function validateDrivePath(drivePath) {
+  if (drivePath.length === 0) {
+    throw new Error("invalid drive path: empty");
+  }
+  if (isAbsolute(drivePath) || ABSOLUTE_POSIX_DOUBLE_SLASH.test(drivePath)) {
+    throw new Error(`invalid drive path: ${drivePath}`);
+  }
+  if (drivePath.includes("\\")) {
+    throw new Error("invalid drive path: backslash");
+  }
+  if (WINDOWS_DRIVE_PREFIX.test(drivePath) || UNC_PREFIX.test(drivePath)) {
+    throw new Error(`invalid drive path: ${drivePath}`);
+  }
+  if (CONTROL_CHARS.test(drivePath)) {
+    throw new Error(`invalid drive path: control character`);
+  }
+  if (Buffer.byteLength(drivePath, "utf8") > UTF8_PATH_LIMIT) {
+    throw new Error(`invalid drive path: exceeds ${UTF8_PATH_LIMIT} bytes`);
+  }
+  const segments = drivePath.split("/");
+  if (segments.some((segment) => segment.length === 0)) {
+    throw new Error("invalid drive path: empty segment");
+  }
+  if (segments.some((segment) => segment === "." || segment === "..")) {
+    throw new Error("invalid drive path: relative segment");
+  }
+  if (segments.some((segment) => Buffer.byteLength(segment, "utf8") > UTF8_SEGMENT_LIMIT)) {
+    throw new Error(`invalid drive path: segment exceeds ${UTF8_SEGMENT_LIMIT} bytes`);
+  }
+  return drivePath;
+}
+function resolveInsideRoot(root, drivePath) {
+  const normalizedPath = validateDrivePath(drivePath);
+  const absoluteRoot = resolve2(root);
+  const absolutePath = resolve2(absoluteRoot, normalizedPath);
+  const relativePath = relative(absoluteRoot, absolutePath);
+  if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${sep}`)) {
+    throw new Error(`drive path escapes root: ${drivePath}`);
+  }
+  return absolutePath;
+}
+
+// src/handwritten/commands/drive/manifest.ts
+function normalizeRemoteManifest(root, entries) {
+  const candidates = [];
+  const remoteFiles = {};
+  const pathErrors = [];
+  for (const entry of entries) {
+    try {
+      validateDrivePath(entry.path);
+      resolveInsideRoot(root, entry.path);
+      candidates.push(entry);
+    } catch (error) {
+      pathErrors.push({ path: entry.path, error: error instanceof Error ? error : new Error(String(error)) });
+    }
+  }
+  const byCaseFoldedPath = /* @__PURE__ */ new Map();
+  for (const entry of candidates) {
+    const folded = entry.path.toLowerCase();
+    const group = byCaseFoldedPath.get(folded) ?? [];
+    group.push(entry);
+    byCaseFoldedPath.set(folded, group);
+  }
+  for (const group of byCaseFoldedPath.values()) {
+    if (group.length > 1) {
+      const hasExactDuplicate = new Set(group.map((entry2) => entry2.path)).size < group.length;
+      const reason = hasExactDuplicate ? "REMOTE_PATH_DUPLICATE" : "REMOTE_PATH_CASE_CONFLICT";
+      for (const entry2 of group.sort((left, right) => left.path.localeCompare(right.path))) {
+        pathErrors.push({
+          path: entry2.path,
+          error: new Error(`${reason}: ${entry2.path}`),
+          appendPathResult: true
+        });
+      }
+      continue;
+    }
+    const [entry] = group;
+    if (entry) remoteFiles[entry.path] = entry;
+  }
+  return { remoteFiles, pathErrors };
+}
+
 // src/handwritten/commands/drive/merge.ts
 import { posix as pathPosix } from "path";
 import { TextDecoder } from "util";
@@ -4864,9 +5052,8 @@ function mergeText3(base, local, remote) {
   }
   return { clean: true, text: mergedLines.join(localNewline) };
 }
-function conflictCopyPath(path, side, now, versionId) {
+function conflictCopyPath(path, side, timestamp, versionId) {
   const parsed = pathPosix.parse(path);
-  const timestamp = now.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
   const shortVersionId = safeShortVersionId(versionId);
   const fileName = `${parsed.name}.${side}-conflict-${timestamp}-${shortVersionId}${parsed.ext}`;
   if (parsed.dir === "") {
@@ -4902,56 +5089,6 @@ function safeShortVersionId(versionId) {
   return (safeVersionId.length > 0 ? safeVersionId : "unknown").slice(0, 8);
 }
 
-// src/handwritten/commands/drive/path-policy.ts
-import { isAbsolute, relative, resolve as resolve2, sep } from "path";
-var UTF8_SEGMENT_LIMIT = 255;
-var UTF8_PATH_LIMIT = 1024;
-var CONTROL_CHARS = /[\0-\x1f\x7f]/;
-var WINDOWS_DRIVE_PREFIX = /^[a-zA-Z]:/;
-var UNC_PREFIX = /^\\\\/;
-var ABSOLUTE_POSIX_DOUBLE_SLASH = /^\/\//;
-function validateDrivePath(drivePath) {
-  if (drivePath.length === 0) {
-    throw new Error("invalid drive path: empty");
-  }
-  if (isAbsolute(drivePath) || ABSOLUTE_POSIX_DOUBLE_SLASH.test(drivePath)) {
-    throw new Error(`invalid drive path: ${drivePath}`);
-  }
-  if (drivePath.includes("\\")) {
-    throw new Error("invalid drive path: backslash");
-  }
-  if (WINDOWS_DRIVE_PREFIX.test(drivePath) || UNC_PREFIX.test(drivePath)) {
-    throw new Error(`invalid drive path: ${drivePath}`);
-  }
-  if (CONTROL_CHARS.test(drivePath)) {
-    throw new Error(`invalid drive path: control character`);
-  }
-  if (Buffer.byteLength(drivePath, "utf8") > UTF8_PATH_LIMIT) {
-    throw new Error(`invalid drive path: exceeds ${UTF8_PATH_LIMIT} bytes`);
-  }
-  const segments = drivePath.split("/");
-  if (segments.some((segment) => segment.length === 0)) {
-    throw new Error("invalid drive path: empty segment");
-  }
-  if (segments.some((segment) => segment === "." || segment === "..")) {
-    throw new Error("invalid drive path: relative segment");
-  }
-  if (segments.some((segment) => Buffer.byteLength(segment, "utf8") > UTF8_SEGMENT_LIMIT)) {
-    throw new Error(`invalid drive path: segment exceeds ${UTF8_SEGMENT_LIMIT} bytes`);
-  }
-  return drivePath;
-}
-function resolveInsideRoot(root, drivePath) {
-  const normalizedPath = validateDrivePath(drivePath);
-  const absoluteRoot = resolve2(root);
-  const absolutePath = resolve2(absoluteRoot, normalizedPath);
-  const relativePath = relative(absoluteRoot, absolutePath);
-  if (relativePath === "" || relativePath === ".." || relativePath.startsWith(`..${sep}`)) {
-    throw new Error(`drive path escapes root: ${drivePath}`);
-  }
-  return absolutePath;
-}
-
 // src/handwritten/commands/drive/scanner.ts
 import { createHash } from "crypto";
 import { constants as fsConstants } from "fs";
@@ -5072,470 +5209,33 @@ async function hashDriveFile(path) {
   }
 }
 
-// src/handwritten/commands/drive/sync.ts
-function emptySummary() {
-  return {
-    uploaded: 0,
-    downloaded: 0,
-    deleted: 0,
-    unchanged: 0,
-    merged: 0,
-    conflicts: 0,
-    errors: 0,
-    conflict_paths: [],
-    paths: []
-  };
+// src/handwritten/commands/drive/local-mutations.ts
+import { createWriteStream as createWriteStream2 } from "fs";
+import { link, mkdir as mkdir2, readFile as readFile3, rename as rename2, rm as rm2, unlink, writeFile as writeFile2 } from "fs/promises";
+import { basename as basename2, dirname, join as join4 } from "path";
+import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
+import { Readable as Readable2, Transform } from "stream";
+import { pipeline as pipeline2 } from "stream/promises";
+async function assertLocalStillScanned(localPath, scanned) {
+  const snapshot = await hashDriveFile(localPath).catch((error) => {
+    if (isNotFoundError(error)) return void 0;
+    throw error;
+  });
+  if (!snapshot || snapshot.sha256 !== scanned.sha256 || snapshot.sizeBytes !== scanned.size_bytes) {
+    throw new Error("local file changed after scan");
+  }
 }
-async function runDriveSyncOnce(root, api) {
-  return withDriveLock(root, async () => {
-    let state = await readDriveState(root);
-    const syncApi = api ?? await createDriveApi();
-    const summary = emptySummary();
-    const blockedPaths = /* @__PURE__ */ new Set();
-    const localFiles = await scanDriveFiles(root, {
-      onPathError: async (path, error) => {
-        await recordPathError(summary, blockedPaths, path, error);
-      }
+async function writeMergedLocalFile(root, path, bytes, digest, scanned, onLocalMutation) {
+  const target = resolveInsideRoot(root, path);
+  await mkdir2(dirname(target), { recursive: true });
+  const tmp = join4(dirname(target), `.${basename2(target)}.wspc-merge-${randomUUID2()}.tmp`);
+  try {
+    await writeFile2(tmp, bytes, { flag: "wx" });
+    return await installMergedLocalFile(root, path, tmp, scanned, digest, bytes.byteLength, onLocalMutation);
+  } finally {
+    await rm2(tmp, { force: true }).catch(() => {
     });
-    const remoteFiles = await fetchRemoteManifest(root, state, syncApi, summary, blockedPaths);
-    const paths = Array.from(
-      /* @__PURE__ */ new Set([...Object.keys(localFiles), ...Object.keys(remoteFiles), ...Object.keys(state.entries)])
-    ).filter((path) => !blockedPaths.has(path)).sort((left, right) => left.localeCompare(right));
-    for (const path of paths) {
-      const remote = remoteFiles[path];
-      const action = decideDriveAction(state.entries[path], localFiles[path], remote);
-      const result = await processPath({ root, state, api: syncApi, path, action, remote, local: localFiles[path], summary });
-      state = result.state;
-      if (result.stop) break;
-    }
-    recordUnresolvedConflicts(summary, state);
-    return summary;
-  });
-}
-function driveSyncCommand(api) {
-  const sync = new Command71("sync").description("Drive sync commands");
-  sync.command("once").description("Run one Drive sync pass").argument("[path]", "local folder path", ".").action(async (path) => {
-    const summary = await runDriveSyncOnce(resolve3(path), api);
-    render({ kind: "drive_sync_once", display: { shape: "object" } }, summary);
-    if (summary.conflicts > 0 || summary.errors > 0) {
-      process.exitCode = 1;
-    }
-  });
-  return sync;
-}
-async function fetchRemoteManifest(root, state, api, summary, blockedPaths) {
-  const candidates = [];
-  const remoteFiles = {};
-  let cursor;
-  do {
-    const page = await api.getManifest(state.library_id, cursor);
-    for (const entry of page.entries) {
-      try {
-        validateRemoteEntry(root, entry);
-        candidates.push(entry);
-      } catch (error) {
-        await recordPathError(summary, blockedPaths, entry.path, error);
-      }
-    }
-    cursor = page.next_cursor ?? void 0;
-  } while (cursor !== void 0);
-  const byCaseFoldedPath = /* @__PURE__ */ new Map();
-  for (const entry of candidates) {
-    const folded = entry.path.toLowerCase();
-    const group = byCaseFoldedPath.get(folded) ?? [];
-    group.push(entry);
-    byCaseFoldedPath.set(folded, group);
-  }
-  for (const group of byCaseFoldedPath.values()) {
-    const exactPathCounts = /* @__PURE__ */ new Map();
-    for (const entry2 of group) {
-      exactPathCounts.set(entry2.path, (exactPathCounts.get(entry2.path) ?? 0) + 1);
-    }
-    if (group.length > 1) {
-      const hasExactDuplicate = Array.from(exactPathCounts.values()).some((count) => count > 1);
-      const reason = hasExactDuplicate ? "REMOTE_PATH_DUPLICATE" : "REMOTE_PATH_CASE_CONFLICT";
-      for (const entry2 of group.sort((left, right) => left.path.localeCompare(right.path))) {
-        await recordPathError(summary, blockedPaths, entry2.path, new Error(`${reason}: ${entry2.path}`), {
-          appendPathResult: true
-        });
-      }
-      continue;
-    }
-    const [entry] = group;
-    if (entry) remoteFiles[entry.path] = entry;
-  }
-  return remoteFiles;
-}
-function validateRemoteEntry(root, entry) {
-  validateDrivePath(entry.path);
-  resolveInsideRoot(root, entry.path);
-}
-async function processPath(args) {
-  const { root, state, api, path, action, remote, local, summary } = args;
-  summary.paths.push({ path, action: action.type });
-  let durableStateRequired = false;
-  try {
-    if (action.type === "upload_create" || action.type === "upload_update") {
-      const localPath = resolveInsideRoot(root, path);
-      const { body, digest: uploadDigest } = await readStableUploadBody(localPath, local);
-      const uploaded = await api.uploadFile(state.library_id, path, body, uploadDigest, action.expectedEntryVersion);
-      durableStateRequired = true;
-      const nextState = cloneDriveState(state);
-      nextState.entries[path] = stateEntryFromRemote(uploaded.entry, uploadDigest);
-      delete nextState.conflicts[path];
-      await commitDriveState(root, nextState);
-      summary.uploaded += 1;
-      return { state: nextState, stop: false };
-    }
-    if (action.type === "download") {
-      if (!remote) throw new Error("remote entry missing for download");
-      await assertLocalSafeForDownload(root, path, state.entries[path]);
-      const digest = await downloadRemote(root, state.library_id, path, api, remote.content_sha256, state.entries[path], () => {
-        durableStateRequired = true;
-      });
-      const nextState = cloneDriveState(state);
-      nextState.entries[path] = stateEntryFromRemote(remote, digest);
-      delete nextState.conflicts[path];
-      await commitDriveState(root, nextState);
-      summary.downloaded += 1;
-      return { state: nextState, stop: false };
-    }
-    if (action.type === "delete_remote") {
-      await assertLocalAbsentBeforeRemoteDelete(root, path);
-      await api.deleteFile(state.library_id, path, action.expectedEntryVersion);
-      durableStateRequired = true;
-      await assertLocalAbsentBeforeRemoteDelete(root, path);
-      const nextState = cloneDriveState(state);
-      delete nextState.entries[path];
-      delete nextState.conflicts[path];
-      await commitDriveState(root, nextState);
-      summary.deleted += 1;
-      return { state: nextState, stop: false };
-    }
-    if (action.type === "delete_local") {
-      await removeLocalIfStillBase(root, path, state.entries[path], () => {
-        durableStateRequired = true;
-      });
-      const nextState = cloneDriveState(state);
-      delete nextState.entries[path];
-      delete nextState.conflicts[path];
-      await commitDriveState(root, nextState);
-      summary.deleted += 1;
-      return { state: nextState, stop: false };
-    }
-    if (action.type === "state_only") {
-      if (!remote) throw new Error("remote entry missing for state update");
-      const nextState = cloneDriveState(state);
-      nextState.entries[path] = stateEntryFromRemote(remote, local?.sha256 ?? remote.content_sha256);
-      delete nextState.conflicts[path];
-      await commitDriveState(root, nextState);
-      summary.unchanged += 1;
-      return { state: nextState, stop: false };
-    }
-    if (action.type === "remove_state") {
-      const nextState = cloneDriveState(state);
-      delete nextState.entries[path];
-      delete nextState.conflicts[path];
-      await commitDriveState(root, nextState);
-      summary.unchanged += 1;
-      return { state: nextState, stop: false };
-    }
-    if (action.type === "conflict") {
-      if (action.reason === "local_and_remote_changed") {
-        try {
-          const mergedState = await tryResolveConflict({
-            root,
-            state,
-            api,
-            path,
-            remote,
-            local,
-            onLocalMutation: () => {
-              durableStateRequired = true;
-            }
-          });
-          if (mergedState) {
-            summary.merged += 1;
-            summary.paths[summary.paths.length - 1] = { path, action: "merged" };
-            return { state: mergedState, stop: false };
-          }
-        } catch (error) {
-          if (!isLocalChangedDuringMerge(error)) {
-            throw error;
-          }
-          const nextState2 = await recordTypedConflict(root, state, path, action.reason, remote, {
-            type: "edit_edit",
-            strategy: "record_only",
-            reason: "local_changed_during_merge"
-          });
-          summary.conflicts += 1;
-          return { state: nextState2, stop: false };
-        }
-        const conflictCopyState = await recordRemoteConflictCopy({
-          root,
-          state,
-          api,
-          path,
-          reason: action.reason,
-          type: "edit_edit",
-          remote
-        });
-        if (conflictCopyState) {
-          summary.conflicts += 1;
-          return { state: conflictCopyState, stop: false };
-        }
-      }
-      if (action.reason === "local_and_remote_without_base") {
-        const conflictCopyState = await recordRemoteConflictCopy({
-          root,
-          state,
-          api,
-          path,
-          reason: action.reason,
-          type: "create_create",
-          remote
-        });
-        if (conflictCopyState) {
-          summary.conflicts += 1;
-          return { state: conflictCopyState, stop: false };
-        }
-      }
-      if (action.reason === "local_changed_remote_deleted") {
-        const nextState2 = await recordTypedConflict(root, state, path, action.reason, remote, {
-          type: "edit_delete",
-          strategy: "record_only"
-        });
-        summary.conflicts += 1;
-        return { state: nextState2, stop: false };
-      }
-      if (action.reason === "remote_changed_before_delete") {
-        const conflictCopyState = await recordRemoteConflictCopy({
-          root,
-          state,
-          api,
-          path,
-          reason: action.reason,
-          type: "delete_edit",
-          remote
-        });
-        if (conflictCopyState) {
-          summary.conflicts += 1;
-          return { state: conflictCopyState, stop: false };
-        }
-      }
-      const nextState = await recordConflict(root, state, path, action.reason, remote);
-      summary.conflicts += 1;
-      return { state: nextState, stop: false };
-    }
-    summary.unchanged += 1;
-  } catch (error) {
-    if (isVersionConflict(error)) {
-      try {
-        const nextState = await recordConflict(root, state, path, "VERSION_CONFLICT", remote);
-        summary.conflicts += 1;
-        summary.paths[summary.paths.length - 1] = { path, action: "conflict" };
-        return { state: nextState, stop: false };
-      } catch (writeError) {
-        await recordPathError(summary, void 0, path, writeError);
-        return { state, stop: durableStateRequired };
-      }
-    }
-    await recordPathError(summary, void 0, path, error);
-    return { state, stop: durableStateRequired };
-  }
-  return { state, stop: false };
-}
-async function tryResolveConflict(args) {
-  const { root, state, api, path, remote, local, onLocalMutation } = args;
-  const entry = state.entries[path];
-  const baseVersionId = entry?.current_version_id;
-  const remoteVersionId = remote?.current_version_id;
-  if (!entry || !remote || !local || baseVersionId === void 0 || remoteVersionId === void 0) {
-    return void 0;
-  }
-  const localPath = resolveInsideRoot(root, path);
-  let baseBytes;
-  let remoteBytes;
-  try {
-    const [downloadedBaseBytes, downloadedRemoteBytes] = await Promise.all([
-      downloadBytes(api, state.library_id, path, baseVersionId),
-      downloadBytes(api, state.library_id, path, remoteVersionId)
-    ]);
-    baseBytes = downloadedBaseBytes;
-    remoteBytes = downloadedRemoteBytes;
-  } catch (error) {
-    if (isExpectedVersionDownloadMissing(error)) {
-      return void 0;
-    }
-    throw error;
-  }
-  const localBytes = await readFile3(localPath);
-  const baseText = classifyMergeText(path, baseBytes, void 0);
-  const localText = classifyMergeText(path, localBytes, void 0);
-  const remoteText = classifyMergeText(path, remoteBytes, void 0);
-  if (!baseText.mergeable || !localText.mergeable || !remoteText.mergeable) {
-    return void 0;
-  }
-  const merged = mergeText3(baseText.text, localText.text, remoteText.text);
-  if (!merged.clean) {
-    return void 0;
-  }
-  await assertLocalStillScanned(localPath, local);
-  const mergedBytes = new TextEncoder().encode(merged.text);
-  const mergedDigest = createHash2("sha256").update(mergedBytes).digest("hex");
-  const install = await writeMergedLocalFile(root, path, mergedBytes, mergedDigest, local, onLocalMutation);
-  let uploaded;
-  try {
-    uploaded = await api.uploadFile(state.library_id, path, mergedBytes, mergedDigest, remote.entry_version);
-  } catch (error) {
-    await install.restore();
-    throw error;
-  }
-  await install.finalize();
-  const nextState = cloneDriveState(state);
-  nextState.entries[path] = stateEntryFromRemote(uploaded.entry, mergedDigest);
-  delete nextState.conflicts[path];
-  await commitDriveState(root, nextState);
-  return nextState;
-}
-async function downloadBytes(api, libraryId, path, versionId) {
-  const response = await api.downloadFile(libraryId, path, versionId);
-  return new Uint8Array(await response.arrayBuffer());
-}
-async function recordRemoteConflictCopy(args) {
-  const { root, state, api, path, reason, type, remote } = args;
-  const entry = state.entries[path];
-  const remoteVersionId = remote?.current_version_id;
-  if (!remote || remoteVersionId === void 0) {
-    return void 0;
-  }
-  if (await canReuseConflictCopy(root, state.conflicts[path], remoteVersionId)) {
-    return state;
-  }
-  const remoteBytes = await downloadBytes(api, state.library_id, path, remoteVersionId);
-  const copyPath = await writeConflictCopy(root, path, "remote", remoteVersionId, remoteBytes);
-  const nextState = cloneDriveState(state);
-  nextState.conflicts[path] = {
-    detected_at: (/* @__PURE__ */ new Date()).toISOString(),
-    reason,
-    type,
-    strategy: "conflict_copy",
-    base_version_id: entry?.current_version_id,
-    remote_version_id: remoteVersionId,
-    remote_entry_version: remote.entry_version,
-    conflict_paths: [copyPath]
-  };
-  await commitDriveState(root, nextState);
-  return nextState;
-}
-async function canReuseConflictCopy(root, conflict2, remoteVersionId) {
-  if (conflict2?.strategy !== "conflict_copy" || conflict2.remote_version_id !== remoteVersionId || !Array.isArray(conflict2.conflict_paths) || conflict2.conflict_paths.length === 0) {
-    return false;
-  }
-  for (const conflictPath of conflict2.conflict_paths) {
-    try {
-      validateDrivePath(conflictPath);
-      if (!await localFileExists(resolveInsideRoot(root, conflictPath))) {
-        return false;
-      }
-    } catch {
-      return false;
-    }
-  }
-  return true;
-}
-async function writeConflictCopy(root, path, side, versionId, bytes) {
-  const baseCopyPath = conflictCopyPath(path, side, /* @__PURE__ */ new Date(), versionId);
-  for (let suffix = 1; ; suffix += 1) {
-    const candidate = conflictCopyPathWithSuffix(baseCopyPath, suffix);
-    validateDrivePath(candidate);
-    const target = resolveInsideRoot(root, candidate);
-    await mkdir2(dirname(target), { recursive: true });
-    for (; ; ) {
-      const tmp = join4(dirname(target), `.${basename2(target)}.wspc-conflict-${randomUUID2()}.tmp`);
-      let tmpWritten = false;
-      try {
-        await writeFile2(tmp, bytes, { flag: "wx" });
-        tmpWritten = true;
-        await installNoOverwrite(tmp, target);
-        return candidate;
-      } catch (error) {
-        if (tmpWritten) {
-          await rm2(tmp, { force: true }).catch(() => {
-          });
-        }
-        if (isAlreadyExistsError(error)) {
-          if (tmpWritten) break;
-          continue;
-        }
-        throw error;
-      }
-    }
-  }
-}
-function conflictCopyPathWithSuffix(path, suffix) {
-  if (suffix === 1) {
-    return path;
-  }
-  const parsed = pathPosix2.parse(path);
-  const fileName = `${parsed.name}-${suffix}${parsed.ext}`;
-  if (parsed.dir === "") {
-    return fileName;
-  }
-  return pathPosix2.join(parsed.dir, fileName);
-}
-function isExpectedVersionDownloadMissing(error) {
-  const structured = error;
-  if (structured?.status === 404 || structured?.status === 410) return true;
-  if (structured?.response?.status === 404 || structured?.response?.status === 410) return true;
-  if (structured?.code === "VERSION_NOT_FOUND" || structured?.code === "NOT_FOUND") return true;
-  return /\b(?:HTTP 40[410]|missing version|version not found|not found)\b/i.test(errorMessage(error));
-}
-async function assertLocalStillScanned(localPath, scanned) {
-  const snapshot = await hashDriveFile(localPath).catch((error) => {
-    if (isNotFoundError(error)) return void 0;
-    throw error;
-  });
-  if (!snapshot || snapshot.sha256 !== scanned.sha256 || snapshot.sizeBytes !== scanned.size_bytes) {
-    throw new Error("local file changed after scan");
-  }
-}
-function recordUnresolvedConflicts(summary, state) {
-  const newlyRecorded = new Set(summary.paths.filter((result) => result.action === "conflict").map((result) => result.path));
-  const reportedPaths = new Set(summary.paths.map((result) => result.path));
-  for (const path of Object.keys(state.conflicts).sort((left, right) => left.localeCompare(right))) {
-    const conflictPaths = state.conflicts[path]?.conflict_paths;
-    if (conflictPaths) {
-      summary.conflict_paths.push(...conflictPaths);
-    }
-    if (!newlyRecorded.has(path)) {
-      summary.conflicts += 1;
-    }
-    const existingResult = summary.paths.find((result) => result.path === path);
-    if (existingResult?.action === "unchanged") {
-      existingResult.action = "conflict";
-      if (conflictPaths) existingResult.conflict_paths = conflictPaths;
-      continue;
-    }
-    if (existingResult?.action === "conflict" && conflictPaths) {
-      existingResult.conflict_paths = conflictPaths;
-    }
-    if (!reportedPaths.has(path)) {
-      summary.paths.push({ path, action: "conflict", ...conflictPaths ? { conflict_paths: conflictPaths } : {} });
-    }
-  }
-}
-async function writeMergedLocalFile(root, path, bytes, digest, scanned, onLocalMutation) {
-  const target = resolveInsideRoot(root, path);
-  await mkdir2(dirname(target), { recursive: true });
-  const tmp = join4(dirname(target), `.${basename2(target)}.wspc-merge-${randomUUID2()}.tmp`);
-  try {
-    await writeFile2(tmp, bytes, { flag: "wx" });
-    return await installMergedLocalFile(root, path, tmp, scanned, digest, bytes.byteLength, onLocalMutation);
-  } finally {
-    await rm2(tmp, { force: true }).catch(() => {
-    });
-  }
+  }
 }
 async function installMergedLocalFile(root, path, tmp, scanned, mergedSha256, mergedSizeBytes, onLocalMutation) {
   const target = resolveInsideRoot(root, path);
@@ -5645,160 +5345,584 @@ async function installDownloadedFile(root, path, tmp, entry, onLocalMutation) {
   const expectedSha256 = expectedLocalBaseSha256(entry);
   let backupIsExpectedBase = false;
   try {
-    try {
-      await rename2(target, backup);
-      onLocalMutation();
-    } catch (error) {
-      if (!isNotFoundError(error)) throw error;
-      await installNoOverwrite(tmp, target, onLocalMutation);
-      return;
+    try {
+      await rename2(target, backup);
+      onLocalMutation();
+    } catch (error) {
+      if (!isNotFoundError(error)) throw error;
+      await installNoOverwrite(tmp, target, onLocalMutation);
+      return;
+    }
+    const backupDigest = await hashDriveFile(backup);
+    if (!backupDigest) {
+      await restoreBackupWhenPossible(backup, target);
+      throw new Error("local file changed before download");
+    }
+    if (!expectedSha256 || backupDigest.sha256 !== expectedSha256) {
+      await restoreBackupWhenPossible(backup, target);
+      throw new Error("local file changed before download");
+    }
+    backupIsExpectedBase = true;
+    try {
+      await installNoOverwrite(tmp, target, onLocalMutation);
+    } catch (error) {
+      const restored = await restoreBackupWhenPossible(backup, target);
+      if (!restored && backupIsExpectedBase) {
+        await unlink(backup).catch(() => {
+        });
+      }
+      throw error;
+    }
+    await unlink(backup);
+  } catch (error) {
+    if (!backupIsExpectedBase) {
+      await restoreBackupWhenPossible(backup, target);
+    }
+    throw error;
+  }
+}
+async function removeLocalIfStillBase(root, path, entry, onLocalMutation) {
+  const target = resolveInsideRoot(root, path);
+  const backup = localMutationBackupPath(target);
+  const expectedSha256 = expectedLocalBaseSha256(entry);
+  if (!expectedSha256) {
+    throw new Error("local file has no sync base");
+  }
+  let backupIsExpectedBase = false;
+  try {
+    try {
+      await rename2(target, backup);
+      onLocalMutation();
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        throw new Error("local file changed before delete");
+      }
+      throw error;
+    }
+    const backupDigest = await hashDriveFile(backup);
+    if (!backupDigest || backupDigest.sha256 !== expectedSha256) {
+      await restoreBackupWhenPossible(backup, target);
+      throw new Error("local file changed before delete");
+    }
+    backupIsExpectedBase = true;
+    if (await localFileExists(target)) {
+      await unlink(backup).catch(() => {
+      });
+      throw new Error("local file reappeared during delete");
+    }
+    await unlink(backup);
+    if (await localFileExists(target)) {
+      throw new Error("local file reappeared during delete");
+    }
+  } catch (error) {
+    if (!backupIsExpectedBase) {
+      await restoreBackupWhenPossible(backup, target);
+    }
+    throw error;
+  }
+}
+async function installNoOverwrite(source, target, onLinked) {
+  await link(source, target);
+  onLinked?.();
+  await unlink(source);
+}
+async function restoreBackupWhenPossible(backup, target) {
+  try {
+    await installNoOverwrite(backup, target);
+    return true;
+  } catch (error) {
+    if (isAlreadyExistsError(error)) return false;
+    if (isNotFoundError(error)) return true;
+    return false;
+  }
+}
+async function localFileExists(path) {
+  const digest = await hashDriveFile(path).catch((error) => {
+    if (isNotFoundError(error)) return void 0;
+    throw error;
+  });
+  return digest !== void 0;
+}
+function localMutationBackupPath(target) {
+  return join4(dirname(target), `.${basename2(target)}.wspc-backup-${randomUUID2()}.tmp`);
+}
+function expectedLocalBaseSha256(entry) {
+  return entry?.last_local_sha256 ?? entry?.content_sha256;
+}
+async function readStableUploadBody(localPath, scanned) {
+  if (!scanned) {
+    throw new Error("local file missing from scan");
+  }
+  const snapshot = await hashDriveFile(localPath).catch((error) => {
+    if (isNotFoundError(error)) return void 0;
+    throw error;
+  });
+  if (!snapshot || snapshot.sha256 !== scanned.sha256 || snapshot.sizeBytes !== scanned.size_bytes) {
+    throw new Error("local file changed after scan");
+  }
+  const body = await readFile3(localPath).catch((error) => {
+    if (isNotFoundError(error)) return void 0;
+    throw error;
+  });
+  if (!body) {
+    throw new Error("local file changed after scan");
+  }
+  const uploadBytes = new Uint8Array(body.byteLength);
+  uploadBytes.set(body);
+  const digest = createHash2("sha256").update(uploadBytes).digest("hex");
+  if (digest !== scanned.sha256 || uploadBytes.byteLength !== scanned.size_bytes) {
+    throw new Error("local file changed after scan");
+  }
+  return { body: uploadBytes.buffer, digest };
+}
+async function assertLocalSafeForDownload(root, path, entry) {
+  const target = resolveInsideRoot(root, path);
+  const digest = await hashDriveFile(target).catch((error) => {
+    if (isNotFoundError(error)) return void 0;
+    throw error;
+  });
+  if (!digest) return;
+  if (!entry?.last_local_sha256) {
+    throw new Error("local file appeared before download");
+  }
+  if (digest.sha256 !== entry.last_local_sha256) {
+    throw new Error("local file changed before download");
+  }
+}
+async function assertLocalAbsentBeforeRemoteDelete(root, path) {
+  const digest = await hashDriveFile(resolveInsideRoot(root, path)).catch((error) => {
+    if (isNotFoundError(error)) return void 0;
+    throw error;
+  });
+  if (digest) {
+    throw new Error("local file appeared before remote delete");
+  }
+}
+function isNotFoundError(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function isAlreadyExistsError(error) {
+  return error instanceof Error && "code" in error && error.code === "EEXIST";
+}
+
+// src/handwritten/commands/drive/sync.ts
+function emptySummary() {
+  return {
+    uploaded: 0,
+    downloaded: 0,
+    deleted: 0,
+    unchanged: 0,
+    merged: 0,
+    conflicts: 0,
+    errors: 0,
+    conflict_paths: [],
+    paths: []
+  };
+}
+async function runDriveSyncOnce(root, api, clock = systemDriveClock) {
+  return withDriveLock(root, async () => {
+    let state = await readDriveState(root);
+    const syncApi = api ?? await createDriveApi();
+    const summary = emptySummary();
+    const blockedPaths = /* @__PURE__ */ new Set();
+    const localFiles = await scanDriveFiles(root, {
+      onPathError: async (path, error) => {
+        await recordPathError(summary, blockedPaths, path, error);
+      }
+    });
+    const remoteFiles = await fetchRemoteManifest(root, state, syncApi, summary, blockedPaths);
+    const paths = Array.from(
+      /* @__PURE__ */ new Set([...Object.keys(localFiles), ...Object.keys(remoteFiles), ...Object.keys(state.entries)])
+    ).filter((path) => !blockedPaths.has(path)).sort((left, right) => left.localeCompare(right));
+    for (const path of paths) {
+      const remote = remoteFiles[path];
+      const action = decideDriveAction(state.entries[path], localFiles[path], remote);
+      const result = await processPath({ root, state, api: syncApi, path, action, remote, local: localFiles[path], summary, clock });
+      state = result.state;
+      if (result.stop) break;
+    }
+    recordUnresolvedConflicts(summary, state);
+    return summary;
+  });
+}
+function driveSyncCommand(api) {
+  const sync = new Command71("sync").description("Drive sync commands");
+  sync.command("once").description("Run one Drive sync pass").argument("[path]", "local folder path", ".").action(async (path) => {
+    const summary = await runDriveSyncOnce(resolve3(path), api);
+    render({ kind: "drive_sync_once", display: { shape: "object" } }, summary);
+    if (summary.conflicts > 0 || summary.errors > 0) {
+      process.exitCode = 1;
+    }
+  });
+  return sync;
+}
+async function fetchRemoteManifest(root, state, api, summary, blockedPaths) {
+  const entries = [];
+  let cursor;
+  do {
+    const page = await api.getManifest(state.library_id, cursor);
+    entries.push(...page.entries);
+    cursor = page.next_cursor ?? void 0;
+  } while (cursor !== void 0);
+  const normalized = normalizeRemoteManifest(root, entries);
+  for (const pathError of normalized.pathErrors) {
+    await recordPathError(summary, blockedPaths, pathError.path, pathError.error, {
+      appendPathResult: pathError.appendPathResult
+    });
+  }
+  return normalized.remoteFiles;
+}
+async function processPath(args) {
+  const { root, state, api, path, action, remote, local, summary, clock } = args;
+  summary.paths.push({ path, action: action.type });
+  let durableStateRequired = false;
+  try {
+    if (action.type === "upload_create" || action.type === "upload_update") {
+      const localPath = resolveInsideRoot(root, path);
+      const { body, digest: uploadDigest } = await readStableUploadBody(localPath, local);
+      const uploaded = await api.uploadFile(state.library_id, path, body, uploadDigest, action.expectedEntryVersion);
+      durableStateRequired = true;
+      const nextState = cloneDriveState(state);
+      nextState.entries[path] = stateEntryFromRemote(uploaded.entry, uploadDigest, clock);
+      delete nextState.conflicts[path];
+      await writeDriveState(root, nextState, clock);
+      summary.uploaded += 1;
+      return { state: nextState, stop: false };
     }
-    const backupDigest = await hashDriveFile(backup);
-    if (!backupDigest) {
-      await restoreBackupWhenPossible(backup, target);
-      throw new Error("local file changed before download");
+    if (action.type === "download") {
+      if (!remote) throw new Error("remote entry missing for download");
+      await assertLocalSafeForDownload(root, path, state.entries[path]);
+      const digest = await downloadRemote(root, state.library_id, path, api, remote.content_sha256, state.entries[path], () => {
+        durableStateRequired = true;
+      });
+      const nextState = cloneDriveState(state);
+      nextState.entries[path] = stateEntryFromRemote(remote, digest, clock);
+      delete nextState.conflicts[path];
+      await writeDriveState(root, nextState, clock);
+      summary.downloaded += 1;
+      return { state: nextState, stop: false };
     }
-    if (!expectedSha256 || backupDigest.sha256 !== expectedSha256) {
-      await restoreBackupWhenPossible(backup, target);
-      throw new Error("local file changed before download");
+    if (action.type === "delete_remote") {
+      await assertLocalAbsentBeforeRemoteDelete(root, path);
+      await api.deleteFile(state.library_id, path, action.expectedEntryVersion);
+      durableStateRequired = true;
+      await assertLocalAbsentBeforeRemoteDelete(root, path);
+      const nextState = cloneDriveState(state);
+      delete nextState.entries[path];
+      delete nextState.conflicts[path];
+      await writeDriveState(root, nextState, clock);
+      summary.deleted += 1;
+      return { state: nextState, stop: false };
     }
-    backupIsExpectedBase = true;
-    try {
-      await installNoOverwrite(tmp, target, onLocalMutation);
-    } catch (error) {
-      const restored = await restoreBackupWhenPossible(backup, target);
-      if (!restored && backupIsExpectedBase) {
-        await unlink(backup).catch(() => {
+    if (action.type === "delete_local") {
+      await removeLocalIfStillBase(root, path, state.entries[path], () => {
+        durableStateRequired = true;
+      });
+      const nextState = cloneDriveState(state);
+      delete nextState.entries[path];
+      delete nextState.conflicts[path];
+      await writeDriveState(root, nextState, clock);
+      summary.deleted += 1;
+      return { state: nextState, stop: false };
+    }
+    if (action.type === "state_only") {
+      if (!remote) throw new Error("remote entry missing for state update");
+      const nextState = cloneDriveState(state);
+      nextState.entries[path] = stateEntryFromRemote(remote, local?.sha256 ?? remote.content_sha256, clock);
+      delete nextState.conflicts[path];
+      await writeDriveState(root, nextState, clock);
+      summary.unchanged += 1;
+      return { state: nextState, stop: false };
+    }
+    if (action.type === "remove_state") {
+      const nextState = cloneDriveState(state);
+      delete nextState.entries[path];
+      delete nextState.conflicts[path];
+      await writeDriveState(root, nextState, clock);
+      summary.unchanged += 1;
+      return { state: nextState, stop: false };
+    }
+    if (action.type === "conflict") {
+      if (action.reason === "local_and_remote_changed") {
+        try {
+          const mergedState = await tryResolveConflict({
+            root,
+            state,
+            api,
+            path,
+            remote,
+            local,
+            clock,
+            onLocalMutation: () => {
+              durableStateRequired = true;
+            }
+          });
+          if (mergedState) {
+            summary.merged += 1;
+            summary.paths[summary.paths.length - 1] = { path, action: "merged" };
+            return { state: mergedState, stop: false };
+          }
+        } catch (error) {
+          if (!isLocalChangedDuringMerge(error)) {
+            throw error;
+          }
+          const nextState2 = await recordTypedConflict(root, state, path, action.reason, remote, clock, {
+            type: "edit_edit",
+            strategy: "record_only",
+            reason: "local_changed_during_merge"
+          });
+          summary.conflicts += 1;
+          return { state: nextState2, stop: false };
+        }
+        const conflictCopyState = await recordRemoteConflictCopy({
+          root,
+          state,
+          api,
+          path,
+          reason: action.reason,
+          type: "edit_edit",
+          remote,
+          clock
         });
+        if (conflictCopyState) {
+          summary.conflicts += 1;
+          return { state: conflictCopyState, stop: false };
+        }
       }
-      throw error;
+      if (action.reason === "local_and_remote_without_base") {
+        const conflictCopyState = await recordRemoteConflictCopy({
+          root,
+          state,
+          api,
+          path,
+          reason: action.reason,
+          type: "create_create",
+          remote,
+          clock
+        });
+        if (conflictCopyState) {
+          summary.conflicts += 1;
+          return { state: conflictCopyState, stop: false };
+        }
+      }
+      if (action.reason === "local_changed_remote_deleted") {
+        const nextState2 = await recordTypedConflict(root, state, path, action.reason, remote, clock, {
+          type: "edit_delete",
+          strategy: "record_only"
+        });
+        summary.conflicts += 1;
+        return { state: nextState2, stop: false };
+      }
+      if (action.reason === "remote_changed_before_delete") {
+        const conflictCopyState = await recordRemoteConflictCopy({
+          root,
+          state,
+          api,
+          path,
+          reason: action.reason,
+          type: "delete_edit",
+          remote,
+          clock
+        });
+        if (conflictCopyState) {
+          summary.conflicts += 1;
+          return { state: conflictCopyState, stop: false };
+        }
+      }
+      const nextState = await recordConflict(root, state, path, action.reason, remote, clock);
+      summary.conflicts += 1;
+      return { state: nextState, stop: false };
     }
-    await unlink(backup);
+    summary.unchanged += 1;
   } catch (error) {
-    if (!backupIsExpectedBase) {
-      await restoreBackupWhenPossible(backup, target);
+    if (isVersionConflict(error)) {
+      try {
+        const nextState = await recordConflict(root, state, path, "VERSION_CONFLICT", remote, clock);
+        summary.conflicts += 1;
+        summary.paths[summary.paths.length - 1] = { path, action: "conflict" };
+        return { state: nextState, stop: false };
+      } catch (writeError) {
+        await recordPathError(summary, void 0, path, writeError);
+        return { state, stop: durableStateRequired };
+      }
     }
-    throw error;
+    await recordPathError(summary, void 0, path, error);
+    return { state, stop: durableStateRequired };
   }
+  return { state, stop: false };
 }
-async function removeLocalIfStillBase(root, path, entry, onLocalMutation) {
-  const target = resolveInsideRoot(root, path);
-  const backup = localMutationBackupPath(target);
-  const expectedSha256 = expectedLocalBaseSha256(entry);
-  if (!expectedSha256) {
-    throw new Error("local file has no sync base");
+async function tryResolveConflict(args) {
+  const { root, state, api, path, remote, local, clock, onLocalMutation } = args;
+  const entry = state.entries[path];
+  const baseVersionId = entry?.current_version_id;
+  const remoteVersionId = remote?.current_version_id;
+  if (!entry || !remote || !local || baseVersionId === void 0 || remoteVersionId === void 0) {
+    return void 0;
   }
-  let backupIsExpectedBase = false;
+  const localPath = resolveInsideRoot(root, path);
+  let baseBytes;
+  let remoteBytes;
   try {
-    try {
-      await rename2(target, backup);
-      onLocalMutation();
-    } catch (error) {
-      if (isNotFoundError(error)) {
-        throw new Error("local file changed before delete");
-      }
-      throw error;
-    }
-    const backupDigest = await hashDriveFile(backup);
-    if (!backupDigest || backupDigest.sha256 !== expectedSha256) {
-      await restoreBackupWhenPossible(backup, target);
-      throw new Error("local file changed before delete");
-    }
-    backupIsExpectedBase = true;
-    if (await localFileExists(target)) {
-      await unlink(backup).catch(() => {
-      });
-      throw new Error("local file reappeared during delete");
-    }
-    await unlink(backup);
-    if (await localFileExists(target)) {
-      throw new Error("local file reappeared during delete");
-    }
+    const [downloadedBaseBytes, downloadedRemoteBytes] = await Promise.all([
+      downloadBytes(api, state.library_id, path, baseVersionId),
+      downloadBytes(api, state.library_id, path, remoteVersionId)
+    ]);
+    baseBytes = downloadedBaseBytes;
+    remoteBytes = downloadedRemoteBytes;
   } catch (error) {
-    if (!backupIsExpectedBase) {
-      await restoreBackupWhenPossible(backup, target);
+    if (isExpectedVersionDownloadMissing(error)) {
+      return void 0;
     }
     throw error;
   }
-}
-async function installNoOverwrite(source, target, onLinked) {
-  await link(source, target);
-  onLinked?.();
-  await unlink(source);
-}
-async function restoreBackupWhenPossible(backup, target) {
+  const localBytes = await readFile4(localPath);
+  const baseText = classifyMergeText(path, baseBytes, void 0);
+  const localText = classifyMergeText(path, localBytes, void 0);
+  const remoteText = classifyMergeText(path, remoteBytes, void 0);
+  if (!baseText.mergeable || !localText.mergeable || !remoteText.mergeable) {
+    return void 0;
+  }
+  const merged = mergeText3(baseText.text, localText.text, remoteText.text);
+  if (!merged.clean) {
+    return void 0;
+  }
+  await assertLocalStillScanned(localPath, local);
+  const mergedBytes = new TextEncoder().encode(merged.text);
+  const mergedDigest = createHash3("sha256").update(mergedBytes).digest("hex");
+  const install = await writeMergedLocalFile(root, path, mergedBytes, mergedDigest, local, onLocalMutation);
+  let uploaded;
   try {
-    await installNoOverwrite(backup, target);
-    return true;
+    uploaded = await api.uploadFile(state.library_id, path, mergedBytes, mergedDigest, remote.entry_version);
   } catch (error) {
-    if (isAlreadyExistsError(error)) return false;
-    if (isNotFoundError(error)) return true;
-    return false;
-  }
-}
-async function localFileExists(path) {
-  const digest = await hashDriveFile(path).catch((error) => {
-    if (isNotFoundError(error)) return void 0;
+    await install.restore();
     throw error;
-  });
-  return digest !== void 0;
-}
-function localMutationBackupPath(target) {
-  return join4(dirname(target), `.${basename2(target)}.wspc-backup-${randomUUID2()}.tmp`);
+  }
+  await install.finalize();
+  const nextState = cloneDriveState(state);
+  nextState.entries[path] = stateEntryFromRemote(uploaded.entry, mergedDigest, clock);
+  delete nextState.conflicts[path];
+  await writeDriveState(root, nextState, clock);
+  return nextState;
 }
-function expectedLocalBaseSha256(entry) {
-  return entry?.last_local_sha256 ?? entry?.content_sha256;
+async function downloadBytes(api, libraryId, path, versionId) {
+  const response = await api.downloadFile(libraryId, path, versionId);
+  return new Uint8Array(await response.arrayBuffer());
 }
-async function readStableUploadBody(localPath, scanned) {
-  if (!scanned) {
-    throw new Error("local file missing from scan");
+async function recordRemoteConflictCopy(args) {
+  const { root, state, api, path, reason, type, remote, clock } = args;
+  const entry = state.entries[path];
+  const remoteVersionId = remote?.current_version_id;
+  if (!remote || remoteVersionId === void 0) {
+    return void 0;
   }
-  const snapshot = await hashDriveFile(localPath).catch((error) => {
-    if (isNotFoundError(error)) return void 0;
-    throw error;
-  });
-  if (!snapshot || snapshot.sha256 !== scanned.sha256 || snapshot.sizeBytes !== scanned.size_bytes) {
-    throw new Error("local file changed after scan");
+  if (await canReuseConflictCopy(root, state.conflicts[path], remoteVersionId)) {
+    return state;
   }
-  const body = await readFile3(localPath).catch((error) => {
-    if (isNotFoundError(error)) return void 0;
-    throw error;
-  });
-  if (!body) {
-    throw new Error("local file changed after scan");
+  const remoteBytes = await downloadBytes(api, state.library_id, path, remoteVersionId);
+  const copyPath = await writeConflictCopy(root, path, "remote", remoteVersionId, remoteBytes, clock);
+  const nextState = cloneDriveState(state);
+  nextState.conflicts[path] = {
+    detected_at: driveIsoTimestamp(clock),
+    reason,
+    type,
+    strategy: "conflict_copy",
+    base_version_id: entry?.current_version_id,
+    remote_version_id: remoteVersionId,
+    remote_entry_version: remote.entry_version,
+    conflict_paths: [copyPath]
+  };
+  await writeDriveState(root, nextState, clock);
+  return nextState;
+}
+async function canReuseConflictCopy(root, conflict2, remoteVersionId) {
+  if (conflict2?.strategy !== "conflict_copy" || conflict2.remote_version_id !== remoteVersionId || !Array.isArray(conflict2.conflict_paths) || conflict2.conflict_paths.length === 0) {
+    return false;
   }
-  const uploadBytes = new Uint8Array(body.byteLength);
-  uploadBytes.set(body);
-  const digest = createHash2("sha256").update(uploadBytes).digest("hex");
-  if (digest !== scanned.sha256 || uploadBytes.byteLength !== scanned.size_bytes) {
-    throw new Error("local file changed after scan");
+  for (const conflictPath of conflict2.conflict_paths) {
+    try {
+      validateDrivePath(conflictPath);
+      if (!await localFileExists(resolveInsideRoot(root, conflictPath))) {
+        return false;
+      }
+    } catch {
+      return false;
+    }
   }
-  return { body: uploadBytes.buffer, digest };
+  return true;
 }
-async function assertLocalSafeForDownload(root, path, entry) {
-  const target = resolveInsideRoot(root, path);
-  const digest = await hashDriveFile(target).catch((error) => {
-    if (isNotFoundError(error)) return void 0;
-    throw error;
-  });
-  if (!digest) return;
-  if (!entry?.last_local_sha256) {
-    throw new Error("local file appeared before download");
+async function writeConflictCopy(root, path, side, versionId, bytes, clock) {
+  const baseCopyPath = conflictCopyPath(path, side, driveConflictTimestamp(clock), versionId);
+  for (let suffix = 1; ; suffix += 1) {
+    const candidate = conflictCopyPathWithSuffix(baseCopyPath, suffix);
+    validateDrivePath(candidate);
+    const target = resolveInsideRoot(root, candidate);
+    await mkdir3(dirname2(target), { recursive: true });
+    for (; ; ) {
+      const tmp = join5(dirname2(target), `.${basename3(target)}.wspc-conflict-${randomUUID3()}.tmp`);
+      let tmpWritten = false;
+      try {
+        await writeFile3(tmp, bytes, { flag: "wx" });
+        tmpWritten = true;
+        await installNoOverwrite(tmp, target);
+        return candidate;
+      } catch (error) {
+        if (tmpWritten) {
+          await rm3(tmp, { force: true }).catch(() => {
+          });
+        }
+        if (error instanceof Error && "code" in error && error.code === "EEXIST") {
+          if (tmpWritten) break;
+          continue;
+        }
+        throw error;
+      }
+    }
   }
-  if (digest.sha256 !== entry.last_local_sha256) {
-    throw new Error("local file changed before download");
+}
+function conflictCopyPathWithSuffix(path, suffix) {
+  if (suffix === 1) {
+    return path;
   }
+  const parsed = pathPosix2.parse(path);
+  const fileName = `${parsed.name}-${suffix}${parsed.ext}`;
+  if (parsed.dir === "") {
+    return fileName;
+  }
+  return pathPosix2.join(parsed.dir, fileName);
 }
-async function assertLocalAbsentBeforeRemoteDelete(root, path) {
-  const digest = await hashDriveFile(resolveInsideRoot(root, path)).catch((error) => {
-    if (isNotFoundError(error)) return void 0;
-    throw error;
-  });
-  if (digest) {
-    throw new Error("local file appeared before remote delete");
+function isExpectedVersionDownloadMissing(error) {
+  const structured = error;
+  if (structured?.status === 404 || structured?.status === 410) return true;
+  if (structured?.response?.status === 404 || structured?.response?.status === 410) return true;
+  if (structured?.code === "VERSION_NOT_FOUND" || structured?.code === "NOT_FOUND") return true;
+  return /\b(?:HTTP 40[410]|missing version|version not found|not found)\b/i.test(errorMessage(error));
+}
+function recordUnresolvedConflicts(summary, state) {
+  const newlyRecorded = new Set(summary.paths.filter((result) => result.action === "conflict").map((result) => result.path));
+  const reportedPaths = new Set(summary.paths.map((result) => result.path));
+  for (const path of Object.keys(state.conflicts).sort((left, right) => left.localeCompare(right))) {
+    const conflictPaths = state.conflicts[path]?.conflict_paths;
+    if (conflictPaths) {
+      summary.conflict_paths.push(...conflictPaths);
+    }
+    if (!newlyRecorded.has(path)) {
+      summary.conflicts += 1;
+    }
+    const existingResult = summary.paths.find((result) => result.path === path);
+    if (existingResult?.action === "unchanged") {
+      existingResult.action = "conflict";
+      if (conflictPaths) existingResult.conflict_paths = conflictPaths;
+      continue;
+    }
+    if (existingResult?.action === "conflict" && conflictPaths) {
+      existingResult.conflict_paths = conflictPaths;
+    }
+    if (!reportedPaths.has(path)) {
+      summary.paths.push({ path, action: "conflict", ...conflictPaths ? { conflict_paths: conflictPaths } : {} });
+    }
   }
 }
-function stateEntryFromRemote(remote, localSha256) {
+function stateEntryFromRemote(remote, localSha256, clock) {
   return {
     entry_id: remote.id,
     entry_version: remote.entry_version,
@@ -5806,13 +5930,10 @@ function stateEntryFromRemote(remote, localSha256) {
     content_sha256: remote.content_sha256,
     size_bytes: remote.size_bytes,
     last_local_sha256: localSha256,
-    last_synced_at: (/* @__PURE__ */ new Date()).toISOString(),
+    last_synced_at: driveIsoTimestamp(clock),
     status: "synced"
   };
 }
-async function commitDriveState(root, nextState) {
-  await writeDriveState(root, nextState);
-}
 function cloneDriveState(state) {
   return {
     ...state,
@@ -5820,21 +5941,21 @@ function cloneDriveState(state) {
     conflicts: { ...state.conflicts }
   };
 }
-async function recordConflict(root, state, path, reason, remote) {
+async function recordConflict(root, state, path, reason, remote, clock) {
   const nextState = cloneDriveState(state);
-  nextState.conflicts[path] = conflict(reason, remote);
-  await commitDriveState(root, nextState);
+  nextState.conflicts[path] = conflict(reason, remote, clock);
+  await writeDriveState(root, nextState, clock);
   return nextState;
 }
-async function recordTypedConflict(root, state, path, reason, remote, metadata) {
+async function recordTypedConflict(root, state, path, reason, remote, clock, metadata) {
   const nextState = cloneDriveState(state);
   nextState.conflicts[path] = {
-    ...conflict(metadata.reason ?? reason, remote),
+    ...conflict(metadata.reason ?? reason, remote, clock),
     type: metadata.type,
     strategy: metadata.strategy,
     base_version_id: state.entries[path]?.current_version_id
   };
-  await commitDriveState(root, nextState);
+  await writeDriveState(root, nextState, clock);
   return nextState;
 }
 async function recordPathError(summary, blockedPaths, path, error, options = {}) {
@@ -5848,9 +5969,9 @@ async function recordPathError(summary, blockedPaths, path, error, options = {})
   void errorMessage(error);
   summary.errors += 1;
 }
-function conflict(reason, remote) {
+function conflict(reason, remote, clock) {
   return {
-    detected_at: (/* @__PURE__ */ new Date()).toISOString(),
+    detected_at: driveIsoTimestamp(clock),
     reason,
     remote_entry_version: remote?.entry_version,
     remote_version_id: remote?.current_version_id
@@ -5876,22 +5997,291 @@ function containsVersionConflict(value) {
     return false;
   }
 }
-function isNotFoundError(error) {
-  return error instanceof Error && "code" in error && error.code === "ENOENT";
-}
-function isAlreadyExistsError(error) {
-  return error instanceof Error && "code" in error && error.code === "EEXIST";
-}
 
 // src/handwritten/commands/drive/watch.ts
 import { Command as Command72 } from "commander";
 import chokidar from "chokidar";
 import { relative as relative2, resolve as resolve4 } from "path";
+
+// src/handwritten/commands/drive/realtime.ts
+function createDriveRealtimeSource(args) {
+  const connect = args.connect ?? nativeWebSocketConnector;
+  const clock = args.clock ?? systemDriveClock;
+  const scheduleTimeout = args.setTimeout ?? setTimeout;
+  const cancelTimeout = args.clearTimeout ?? clearTimeout;
+  let currentRealtime = { ...args.realtime };
+  let handlers;
+  let activeSocket;
+  let reconnectTimer;
+  let reconnectDelayMs = 1e3;
+  let stopped = false;
+  let authFailed = false;
+  let connectionId = 0;
+  function clearReconnectTimer() {
+    if (reconnectTimer === void 0) return;
+    cancelTimeout(reconnectTimer);
+    reconnectTimer = void 0;
+  }
+  async function persist(next) {
+    currentRealtime = next;
+    await args.writeRealtimeState(next);
+  }
+  async function persistBestEffort(next) {
+    try {
+      await persist(next);
+    } catch (error) {
+      handlers?.onWarning?.(redactedRealtimeError(error));
+    }
+  }
+  function connectNow() {
+    if (stopped || authFailed) return;
+    clearReconnectTimer();
+    const id = ++connectionId;
+    const url = buildDriveRealtimeUrl(args.baseUrl, args.libraryId, currentRealtime);
+    activeSocket = connect(url, {
+      open() {
+        if (id !== connectionId || stopped || authFailed) return;
+        reconnectDelayMs = 1e3;
+        void persistBestEffort({ ...currentRealtime, last_connected_at: driveIsoTimestamp(clock) }).then(() => handlers?.onConnected());
+      },
+      message(data) {
+        if (id !== connectionId || stopped || authFailed) return;
+        void handleMessage(data).catch((error) => handlers?.onWarning?.(redactedRealtimeError(error)));
+      },
+      close(error) {
+        closeConnection(id, error ?? "close");
+      }
+    }, args.headers === void 0 ? void 0 : { headers: args.headers });
+  }
+  function closeConnection(id, error) {
+    if (id !== connectionId || stopped || authFailed) return;
+    connectionId += 1;
+    const socket = activeSocket;
+    activeSocket = void 0;
+    clearReconnectTimer();
+    socket?.close();
+    if (isRealtimeAuthError(error)) {
+      authFailed = true;
+      handlers?.onAuthFailed(redactedRealtimeError(error));
+      return;
+    }
+    const delayMs = reconnectDelayMs;
+    handlers?.onReconnect(delayMs, redactedRealtimeError(error));
+    reconnectTimer = scheduleTimeout(() => {
+      reconnectTimer = void 0;
+      connectNow();
+    }, delayMs);
+    reconnectDelayMs = Math.min(delayMs * 2, 6e4);
+  }
+  async function handleMessage(data) {
+    const message = parseDriveRealtimeMessage(data);
+    if (message.type === "ready") {
+      if (message.replayed > 0) {
+        handlers?.onEvent({
+          debounce_ms: 2e3,
+          reason: "ready_replay",
+          ...message.cursor === void 0 ? {} : { cursor: message.cursor }
+        });
+      }
+      if (message.cursor !== void 0) {
+        await persistBestEffort({ ...currentRealtime, last_cursor: message.cursor });
+      }
+      return;
+    }
+    if (message.type === "library_changed") {
+      handlers?.onEvent({
+        debounce_ms: 2e3,
+        reason: "library_changed",
+        ...message.cursor === void 0 ? {} : { cursor: message.cursor },
+        ...message.path === void 0 ? {} : { path: message.path }
+      });
+      if (message.cursor !== void 0) {
+        await persistBestEffort({ ...currentRealtime, last_cursor: message.cursor, last_event_at: driveIsoTimestamp(clock) });
+      }
+      return;
+    }
+    if (message.type === "resync_required") {
+      const reason = message.reason ?? "resync_required";
+      handlers?.onEvent({
+        immediate: true,
+        reason,
+        ...message.cursor === void 0 ? {} : { cursor: message.cursor }
+      });
+      if (message.cursor !== void 0 || isInvalidCursorReason(reason)) {
+        await persistBestEffort(resyncRealtimeState(currentRealtime, message.cursor, reason, driveIsoTimestamp(clock)));
+      }
+      return;
+    }
+    if (message.type === "error") {
+      const error = message.message ?? message.code ?? "realtime error";
+      if (isRealtimeAuthError(error) || isRealtimeAuthError(message.code)) {
+        authFailed = true;
+        connectionId += 1;
+        clearReconnectTimer();
+        handlers?.onAuthFailed(redactedRealtimeError(error));
+        activeSocket?.close();
+        activeSocket = void 0;
+        return;
+      }
+      handlers?.onWarning?.(redactedRealtimeError(error));
+      return;
+    }
+    handlers?.onWarning?.("unknown realtime message");
+  }
+  return {
+    async start(nextHandlers) {
+      handlers = nextHandlers;
+      stopped = false;
+      authFailed = false;
+      connectNow();
+    },
+    async close() {
+      stopped = true;
+      clearReconnectTimer();
+      activeSocket?.close();
+      activeSocket = void 0;
+    }
+  };
+}
+function buildDriveRealtimeUrl(baseUrl, libraryId, realtime) {
+  if (realtime.client_id.length === 0) {
+    throw new Error("drive realtime client_id is required");
+  }
+  const url = new URL(baseUrl);
+  url.protocol = url.protocol === "http:" ? "ws:" : "wss:";
+  url.pathname = `/drive/libraries/${encodeURIComponent(libraryId)}/realtime`;
+  url.search = "";
+  url.hash = "";
+  if (realtime.last_cursor !== void 0) {
+    url.searchParams.set("cursor", realtime.last_cursor);
+  }
+  url.searchParams.set("client_id", realtime.client_id);
+  return url;
+}
+function parseDriveRealtimeMessage(raw) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return { type: "unknown" };
+  }
+  if (!isRecord3(value)) {
+    return { type: "unknown" };
+  }
+  const messageType = typeof value.type === "string" ? value.type : void 0;
+  const cursor = typeof value.cursor === "string" ? value.cursor : void 0;
+  if (messageType === "ready") {
+    return {
+      type: "ready",
+      replayed: typeof value.replayed === "number" ? value.replayed : 0,
+      ...cursor === void 0 ? {} : { cursor }
+    };
+  }
+  if (messageType === "library_changed") {
+    return {
+      type: "library_changed",
+      ...cursor === void 0 ? {} : { cursor },
+      ...typeof value.path === "string" ? { path: value.path } : {}
+    };
+  }
+  if (messageType === "resync_required") {
+    return {
+      type: "resync_required",
+      ...cursor === void 0 ? {} : { cursor },
+      ...typeof value.reason === "string" ? { reason: value.reason } : {}
+    };
+  }
+  if (messageType === "error") {
+    return {
+      type: "error",
+      ...typeof value.code === "string" ? { code: value.code } : {},
+      ...typeof value.message === "string" ? { message: redactedRealtimeError(value.message) } : {}
+    };
+  }
+  return {
+    type: "unknown",
+    ...messageType === void 0 ? {} : { message_type: messageType }
+  };
+}
+function redactedRealtimeError(error) {
+  const text = error instanceof Error ? error.message : String(error);
+  const status = text.match(/\bHTTP\s+(401|403|429|5\d\d)\b/i);
+  if (status?.[1] !== void 0) {
+    return `HTTP ${status[1]}`;
+  }
+  if (/\bauth|authorization\b/i.test(text)) {
+    return "auth failed";
+  }
+  if (/\bnetwork|fetch|close\b/i.test(text)) {
+    return "network error";
+  }
+  return "realtime error";
+}
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resyncRealtimeState(realtime, cursor, reason, lastEventAt) {
+  if (isInvalidCursorReason(reason)) {
+    const { last_cursor: _lastCursor, ...next } = realtime;
+    return { ...next, last_event_at: lastEventAt };
+  }
+  return {
+    ...realtime,
+    last_event_at: lastEventAt,
+    ...cursor === void 0 ? {} : { last_cursor: cursor }
+  };
+}
+function isInvalidCursorReason(reason) {
+  return /\bcursor[_ -]?(invalid|expired|gone|missing|not[_ -]?found)\b|\binvalid[_ -]?cursor\b/i.test(reason);
+}
+function isRealtimeAuthError(error) {
+  return /\b(401|403|auth|authorization|unauthorized|forbidden)\b/i.test(String(error));
+}
+function nativeWebSocketConnector(url, handlers, init) {
+  const WebSocketWithInit = WebSocket;
+  const ws = new WebSocketWithInit(url.toString(), init);
+  let closed = false;
+  let pendingError;
+  const closeOnce = (error) => {
+    if (closed) return;
+    closed = true;
+    handlers.close(error);
+  };
+  ws.addEventListener("open", () => handlers.open());
+  ws.addEventListener("message", (event) => handlers.message(String(event.data)));
+  ws.addEventListener("close", (event) => closeOnce(webSocketCloseError(event) ?? pendingError));
+  ws.addEventListener("error", (event) => {
+    pendingError = webSocketError(event);
+    if (isRealtimeAuthError(pendingError)) {
+      closeOnce(pendingError);
+    }
+  });
+  return { close: () => ws.close() };
+}
+function webSocketCloseError(event) {
+  if (event.code === 1e3) return void 0;
+  if (event.code === 4001 || event.code === 4401) return new Error("HTTP 401");
+  if (event.code === 4003 || event.code === 4403) return new Error("HTTP 403");
+  if (event.reason && isRealtimeAuthError(event.reason)) return new Error(event.reason);
+  if (event.reason) return new Error(event.reason);
+  return new Error(`WebSocket close ${event.code}`);
+}
+function webSocketError(event) {
+  if (typeof ErrorEvent !== "undefined" && event instanceof ErrorEvent) {
+    const detail = event.error instanceof Error ? event.error.message : event.message;
+    if (detail) return new Error(detail);
+  }
+  return new Error("network error");
+}
+
+// src/handwritten/commands/drive/watch.ts
 async function runDriveWatch(root, options = {}) {
   const runSync = options.runSync ?? runDriveSyncOnce;
   const debounceMs = options.debounceMs ?? 500;
+  const remoteDebounceMs = options.remoteDebounceMs ?? 2e3;
   const emit = options.onEvent ?? ((event) => render({ kind: "drive_watch", display: { shape: "object" } }, event));
   let debounceTimer;
+  let debounceDeadlineMs;
   let retryTimer;
   let resolveRetryTimer;
   let running = false;
@@ -5919,6 +6309,7 @@ async function runDriveWatch(root, options = {}) {
         } catch (error) {
           if (isAuthError(error) || isFatalWatchError(error) || !isRetryableWatchError(error)) throw error;
           emit({ kind: "drive_watch_retry", delay_ms: backoffMs, error: errorMessage2(error) });
+          if (stopped) return;
           await waitForManagedTimer(backoffMs);
           if (stopped) return;
           backoffMs = Math.min(backoffMs * 2, 6e4);
@@ -5933,6 +6324,27 @@ async function runDriveWatch(root, options = {}) {
     if (debounceTimer === void 0) return;
     clearTimeout(debounceTimer);
     debounceTimer = void 0;
+    debounceDeadlineMs = void 0;
+  }
+  function scheduleSync(delayMs) {
+    if (running) {
+      rerunRequested = true;
+      return;
+    }
+    if (delayMs <= 0) {
+      clearDebounceTimer();
+      requestSync().catch(stopWithError);
+      return;
+    }
+    const deadlineMs = Date.now() + delayMs;
+    if (debounceTimer !== void 0 && debounceDeadlineMs !== void 0 && debounceDeadlineMs <= deadlineMs) return;
+    clearDebounceTimer();
+    debounceDeadlineMs = deadlineMs;
+    debounceTimer = setTimeout(() => {
+      debounceTimer = void 0;
+      debounceDeadlineMs = void 0;
+      requestSync().catch(stopWithError);
+    }, delayMs);
   }
   function clearRetryTimer() {
     if (retryTimer === void 0) return;
@@ -5954,26 +6366,61 @@ async function runDriveWatch(root, options = {}) {
   }
   function stopWithError(error) {
     stopError = error;
+    stopped = true;
     clearDebounceTimer();
     clearRetryTimer();
     stopWatch?.();
   }
-  const state = await (options.readState ?? readDriveState)(root);
-  const source = options.source ?? createChokidarSource(root);
+  let source;
+  let realtimeSource;
   try {
+    let state = await (options.readState ?? readDriveState)(root);
+    realtimeSource = options.once ? void 0 : options.realtimeSource;
+    if (!options.once && realtimeSource === void 0) {
+      state = await ensureDriveRealtimeState(root);
+      const { baseUrl, headers } = await loadRealtimeAuthHeaders({
+        verifyPath: `/drive/libraries/${encodeURIComponent(state.library_id)}`
+      });
+      const realtime = state.realtime;
+      if (realtime === void 0) {
+        throw new Error("drive realtime state is required");
+      }
+      realtimeSource = createDriveRealtimeSource({
+        baseUrl,
+        headers,
+        libraryId: state.library_id,
+        realtime,
+        writeRealtimeState: (next) => writeDriveRealtimeState(root, next)
+      });
+    }
+    source = options.source ?? createChokidarSource(root);
     source.onChange((path) => {
       if (isDriveInternalPath(root, path)) return;
-      if (running) {
-        rerunRequested = true;
-        return;
-      }
-      clearDebounceTimer();
-      debounceTimer = setTimeout(() => {
-        debounceTimer = void 0;
-        requestSync().catch(stopWithError);
-      }, debounceMs);
+      scheduleSync(debounceMs);
     });
     emit({ kind: "drive_watch_started", root, library_id: state.library_id });
+    realtimeSource?.start({
+      onConnected() {
+        emit({ kind: "drive_realtime_connected", library_id: state.library_id });
+      },
+      onEvent(event) {
+        emit(realtimeEvent(event));
+        if (event.immediate) {
+          scheduleSync(0);
+          return;
+        }
+        scheduleSync(event.debounce_ms ?? remoteDebounceMs);
+      },
+      onReconnect(delayMs, error) {
+        emit({ kind: "drive_realtime_reconnecting", delay_ms: delayMs, error });
+      },
+      onAuthFailed(error) {
+        emit({ kind: "drive_realtime_auth_failed", error: error ?? "auth failed" });
+      },
+      onWarning(warning) {
+        emit({ kind: "drive_realtime_warning", warning });
+      }
+    }).catch(stopWithError);
     await requestSync();
     if (options.once) return;
     if (stopError !== void 0) throw stopError;
@@ -5987,7 +6434,7 @@ async function runDriveWatch(root, options = {}) {
     clearDebounceTimer();
     clearRetryTimer();
     cleanupSignalListeners();
-    await source.close();
+    await Promise.all([source?.close(), realtimeSource?.close()]);
   }
 }
 function driveWatchCommand(options = {}) {
@@ -6029,6 +6476,15 @@ function isRetryableWatchError(error) {
 function errorMessage2(error) {
   return error instanceof Error ? error.message : String(error);
 }
+function realtimeEvent(event) {
+  return {
+    kind: "drive_realtime_event",
+    message: "remote update received; syncing",
+    ...event.path === void 0 ? {} : { path: event.path },
+    ...event.reason === void 0 ? {} : { reason: event.reason },
+    ...event.cursor === void 0 ? {} : { cursor: event.cursor }
+  };
+}
 function waitForStopSignal(onRegistered) {
   return new Promise((resolveStop) => {
     const stop = () => resolveStop();