@lotics/cli 0.116.0 → 0.127.0

package/dist/src/cli.js

@@ -26822,12 +26822,12 @@ var require_tokens = __commonJS({
       });
     }
     exports2.assignCategoriesMapProp = assignCategoriesMapProp;
-    function singleAssignCategoriesToksMap(path8, nextNode) {
-      utils_1.forEach(path8, function(pathNode) {
+    function singleAssignCategoriesToksMap(path10, nextNode) {
+      utils_1.forEach(path10, function(pathNode) {
         nextNode.categoryMatchesMap[pathNode.tokenTypeIdx] = true;
       });
       utils_1.forEach(nextNode.CATEGORIES, function(nextCategory) {
-        var newPath = path8.concat(nextNode);
+        var newPath = path10.concat(nextNode);
         if (!utils_1.contains(newPath, nextCategory)) {
           singleAssignCategoriesToksMap(newPath, nextCategory);
         }
@@ -28590,10 +28590,10 @@ var require_interpreter = __commonJS({
       /** @class */
       (function(_super) {
         __extends(AbstractNextPossibleTokensWalker2, _super);
-        function AbstractNextPossibleTokensWalker2(topProd, path8) {
+        function AbstractNextPossibleTokensWalker2(topProd, path10) {
           var _this = _super.call(this) || this;
           _this.topProd = topProd;
-          _this.path = path8;
+          _this.path = path10;
           _this.possibleTokTypes = [];
           _this.nextProductionName = "";
           _this.nextProductionOccurrence = 0;
@@ -28647,9 +28647,9 @@ var require_interpreter = __commonJS({
       /** @class */
       (function(_super) {
         __extends(NextAfterTokenWalker2, _super);
-        function NextAfterTokenWalker2(topProd, path8) {
-          var _this = _super.call(this, topProd, path8) || this;
-          _this.path = path8;
+        function NextAfterTokenWalker2(topProd, path10) {
+          var _this = _super.call(this, topProd, path10) || this;
+          _this.path = path10;
           _this.nextTerminalName = "";
           _this.nextTerminalOccurrence = 0;
           _this.nextTerminalName = _this.path.lastTok.name;
@@ -29346,10 +29346,10 @@ var require_lookahead = __commonJS({
       }
       return result;
     }
-    function pathToHashKeys(path8) {
+    function pathToHashKeys(path10) {
       var keys3 = [""];
-      for (var i2 = 0; i2 < path8.length; i2++) {
-        var tokType = path8[i2];
+      for (var i2 = 0; i2 < path10.length; i2++) {
+        var tokType = path10[i2];
         var longerKeys = [];
         for (var j = 0; j < keys3.length; j++) {
           var currShorterKey = keys3[j];
@@ -29661,9 +29661,9 @@ var require_checks = __commonJS({
       return errors2;
     }
     exports2.validateRuleIsOverridden = validateRuleIsOverridden;
-    function validateNoLeftRecursion(topRule, currRule, errMsgProvider, path8) {
-      if (path8 === void 0) {
-        path8 = [];
+    function validateNoLeftRecursion(topRule, currRule, errMsgProvider, path10) {
+      if (path10 === void 0) {
+        path10 = [];
       }
       var errors2 = [];
       var nextNonTerminals = getFirstNoneTerminal(currRule.definition);
@@ -29676,15 +29676,15 @@ var require_checks = __commonJS({
           errors2.push({
             message: errMsgProvider.buildLeftRecursionError({
               topLevelRule: topRule,
-              leftRecursionPath: path8
+              leftRecursionPath: path10
             }),
             type: parser_1.ParserDefinitionErrorType.LEFT_RECURSION,
             ruleName
           });
         }
-        var validNextSteps = utils2.difference(nextNonTerminals, path8.concat([topRule]));
+        var validNextSteps = utils2.difference(nextNonTerminals, path10.concat([topRule]));
         var errorsFromNextSteps = utils2.map(validNextSteps, function(currRefRule) {
-          var newPath = utils2.cloneArr(path8);
+          var newPath = utils2.cloneArr(path10);
           newPath.push(currRefRule);
           return validateNoLeftRecursion(topRule, currRefRule, errMsgProvider, newPath);
         });
@@ -37293,8 +37293,8 @@ var require_utils4 = __commonJS({
       var result = transform2[inputType][outputType](input);
       return result;
     };
-    exports2.resolve = function(path8) {
-      var parts = path8.split("/");
+    exports2.resolve = function(path10) {
+      var parts = path10.split("/");
       var result = [];
       for (var index = 0; index < parts.length; index++) {
         var part = parts[index];
@@ -43147,18 +43147,18 @@ var require_object = __commonJS({
       var object2 = new ZipObject(name2, zipObjectContent, o);
       this.files[name2] = object2;
     };
-    var parentFolder = function(path8) {
-      if (path8.slice(-1) === "/") {
-        path8 = path8.substring(0, path8.length - 1);
+    var parentFolder = function(path10) {
+      if (path10.slice(-1) === "/") {
+        path10 = path10.substring(0, path10.length - 1);
       }
-      var lastSlash = path8.lastIndexOf("/");
-      return lastSlash > 0 ? path8.substring(0, lastSlash) : "";
+      var lastSlash = path10.lastIndexOf("/");
+      return lastSlash > 0 ? path10.substring(0, lastSlash) : "";
     };
-    var forceTrailingSlash = function(path8) {
-      if (path8.slice(-1) !== "/") {
-        path8 += "/";
+    var forceTrailingSlash = function(path10) {
+      if (path10.slice(-1) !== "/") {
+        path10 += "/";
       }
-      return path8;
+      return path10;
     };
     var folderAdd = function(name2, createFolders) {
       createFolders = typeof createFolders !== "undefined" ? createFolders : defaults2.createFolders;
@@ -44160,9 +44160,9 @@ var require_lib4 = __commonJS({
 // src/cli.ts
 import dns from "node:dns";
 import net2 from "node:net";
-import fs9 from "node:fs";
-import os2 from "node:os";
-import path7 from "node:path";
+import fs11 from "node:fs";
+import os4 from "node:os";
+import path9 from "node:path";
 import readline from "node:readline";
 
 // ../shared/src/transport_error.ts
@@ -44181,16 +44181,81 @@ function transportErrorMessage(status, parsed) {
 }
 
 // src/client.ts
+import fs2 from "node:fs";
+import path2 from "node:path";
+
+// src/invocation.ts
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+function telemetryEnabled(env = process.env) {
+  return env.LOTICS_TELEMETRY === "1";
+}
+function commandPath(argv) {
+  const parts = [];
+  for (const raw of argv) {
+    if (parts.length >= 3) break;
+    if (raw.startsWith("-") || raw.startsWith("@") || raw.startsWith("{")) break;
+    if (raw.includes("/") || raw.includes(".")) break;
+    if (!/^[a-z][a-z0-9_-]*$/i.test(raw)) break;
+    if (isResourceId(raw)) break;
+    parts.push(raw);
+  }
+  return parts.length > 0 ? parts.join(".") : "unknown";
+}
+function isResourceId(token) {
+  const match2 = /^[a-z]{2,5}_([A-Za-z0-9]{8,})$/.exec(token);
+  return match2 !== null && /[A-Z0-9]/.test(match2[1]);
+}
+function userAgent(version2) {
+  return `lotics-cli/${version2} node/${process.version} ${os.platform()}`;
+}
+var invocation = null;
+function setInvocation(command, session, version2) {
+  invocation = { command, session, userAgent: userAgent(version2) };
+}
+function getInvocation() {
+  return invocation;
+}
+var IDLE_GAP_MS = 30 * 60 * 1e3;
+function sessionStorePath() {
+  return path.join(os.homedir(), ".lotics", "session.json");
+}
+function readSession(file2) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file2, "utf-8"));
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const { id, last_seen } = parsed;
+    if (typeof id !== "string" || typeof last_seen !== "number") return null;
+    return { id, last_seen };
+  } catch {
+    return null;
+  }
+}
+function sessionId(now = Date.now(), env = process.env) {
+  if (!telemetryEnabled(env)) return null;
+  const harnessSession = env.CLAUDE_CODE_SESSION_ID;
+  if (harnessSession !== void 0 && harnessSession !== "") return harnessSession;
+  const file2 = sessionStorePath();
+  const stored = readSession(file2);
+  const id = stored !== null && now - stored.last_seen < IDLE_GAP_MS ? stored.id : `cli_${now.toString(36)}${Math.random().toString(36).slice(2, 10)}`;
+  try {
+    fs.mkdirSync(path.dirname(file2), { recursive: true });
+    fs.writeFileSync(file2, JSON.stringify({ id, last_seen: now }), { mode: 384 });
+  } catch {
+  }
+  return id;
+}
+
+// src/client.ts
 function findAvailableFilename(dir, filename, reserved) {
   const isTaken = (name2) => {
-    const full = path.join(dir, name2);
+    const full = path2.join(dir, name2);
     if (reserved?.has(full)) return true;
-    return fs.existsSync(full);
+    return fs2.existsSync(full);
   };
   const claim = (name2) => {
-    reserved?.add(path.join(dir, name2));
+    reserved?.add(path2.join(dir, name2));
     return name2;
   };
   if (!isTaken(filename)) return claim(filename);
@@ -44219,7 +44284,7 @@ var MIME_MAP = {
   ".zip": "application/zip"
 };
 function getMimeType(filename) {
-  const ext = path.extname(filename).toLowerCase();
+  const ext = path2.extname(filename).toLowerCase();
   return MIME_MAP[ext] ?? "application/octet-stream";
 }
 var API_BASE_URL = process.env.LOTICS_API_URL ?? "https://api.lotics.ai";
@@ -44250,9 +44315,21 @@ var LoticsClient = class {
     }
     throw new Error(`${response.status}: ${message2}`);
   }
+  /**
+   * The backend's `log()` middleware registers `user-agent` and
+   * `x-posthog-session-id` onto the per-request Logger, so they ride EVERY log
+   * line that request emits — the validation 400, the tool error, the timing.
+   * Sending them is therefore the whole of the correlation work: it turns an
+   * anonymous API-key request into "`app workflow set`, from cli 0.117.0, the
+   * fourth command of this session".
+   */
   buildHeaders() {
+    const invocation2 = getInvocation();
     const headers = {
-      "Authorization": `Bearer ${this.apiKey}`
+      "Authorization": `Bearer ${this.apiKey}`,
+      // Unversioned when the SDK is used as a library — there is no CLI process
+      // whose version to name, and a wrong one is worse than none.
+      "user-agent": invocation2?.userAgent ?? "lotics-cli"
     };
     if (this.workspaceId) {
       headers["x-workspace-id"] = this.workspaceId;
@@ -44260,10 +44337,16 @@ var LoticsClient = class {
     if (this.viewAsMemberId) {
       headers["x-view-as-member-id"] = this.viewAsMemberId;
     }
+    if (invocation2) {
+      headers["x-lotics-cli-command"] = invocation2.command;
+      if (invocation2.session !== null) {
+        headers["x-posthog-session-id"] = invocation2.session;
+      }
+    }
     return headers;
   }
-  async request(method, path8, body) {
-    const url2 = `${this.baseUrl}${path8}`;
+  async request(method, path10, body) {
+    const url2 = `${this.baseUrl}${path10}`;
     const headers = this.buildHeaders();
     const init = { method, headers };
     if (body !== void 0) {
@@ -44744,7 +44827,8 @@ var LoticsClient = class {
       ...body.inputs ? { inputs: body.inputs } : {},
       ...body.outputs ? { outputs: body.outputs } : {},
       ...body.name ? { name: body.name } : {},
-      ...body.description ? { description: body.description } : {}
+      ...body.description ? { description: body.description } : {},
+      ...body.expected_body_sha ? { expected_body_sha: body.expected_body_sha } : {}
     });
   }
   /**
@@ -44755,8 +44839,13 @@ var LoticsClient = class {
    * deploy validates the manifest. Note: `apps.queries` is manifest-authoritative,
    * so the next `lotics app deploy` overwrites this from the manifest.
    */
-  async setAppQuery(app_id, alias, declaration) {
-    return this.execute("set_app_query", { app_id, alias, declaration });
+  async setAppQuery(app_id, alias, declaration, expected_sha) {
+    return this.execute("set_app_query", {
+      app_id,
+      alias,
+      declaration,
+      ...expected_sha ? { expected_sha } : {}
+    });
   }
   /**
    * Bind (create or replace) an app agent by alias via the `set_app_agent` tool
@@ -44955,6 +45044,7 @@ var LoticsClient = class {
       formData.append("capabilities", JSON.stringify(args.capabilities));
     }
     formData.append("workflow_aliases", JSON.stringify(args.workflow_aliases ?? []));
+    formData.append("agent_aliases", JSON.stringify(args.agent_aliases ?? []));
     formData.append("query_aliases", JSON.stringify(args.query_aliases ?? []));
     const url2 = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
     const response = await fetch(url2, {
@@ -44981,8 +45071,8 @@ var LoticsClient = class {
       throw new Error(`${response.status}: Failed to download file`);
     }
     const buffer = Buffer.from(await response.arrayBuffer());
-    const absolutePath = path.resolve(outputPath);
-    await fs.promises.writeFile(absolutePath, buffer);
+    const absolutePath = path2.resolve(outputPath);
+    await fs2.promises.writeFile(absolutePath, buffer);
     return absolutePath;
   }
   async downloadFileById(fileId, outputDir, options) {
@@ -44998,10 +45088,10 @@ var LoticsClient = class {
     const match2 = disposition.match(/filename="?([^";\n]+)"?/);
     const originalFilename = match2?.[1] ?? fileId;
     const buffer = Buffer.from(await response.arrayBuffer());
-    const dir = outputDir ? path.resolve(outputDir) : process.cwd();
+    const dir = outputDir ? path2.resolve(outputDir) : process.cwd();
     const filename = findAvailableFilename(dir, originalFilename, options?.reserved);
-    const absolutePath = path.join(dir, filename);
-    await fs.promises.writeFile(absolutePath, buffer);
+    const absolutePath = path2.join(dir, filename);
+    await fs2.promises.writeFile(absolutePath, buffer);
     return { path: absolutePath, filename };
   }
   async downloadRecordFiles(recordId, fieldKey, outputDir) {
@@ -45029,9 +45119,9 @@ var LoticsClient = class {
   async uploadFiles(filePaths, options) {
     const formData = new FormData();
     for (let i2 = 0; i2 < filePaths.length; i2++) {
-      const absolutePath = path.resolve(filePaths[i2]);
-      const buffer = await fs.promises.readFile(absolutePath);
-      const filename = options?.filenames?.[i2] ?? path.basename(absolutePath);
+      const absolutePath = path2.resolve(filePaths[i2]);
+      const buffer = await fs2.promises.readFile(absolutePath);
+      const filename = options?.filenames?.[i2] ?? path2.basename(absolutePath);
       const mimeType = getMimeType(filename);
       const blob = new Blob([buffer], { type: mimeType });
       formData.append("file", blob, filename);
@@ -45047,24 +45137,189 @@ var LoticsClient = class {
   }
 };
 
+// src/telemetry.ts
+import crypto from "node:crypto";
+import fs3 from "node:fs";
+import os2 from "node:os";
+import path3 from "node:path";
+
+// ../shared/src/content_sha.ts
+import { createHash } from "node:crypto";
+function contentSha(text) {
+  return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+function declarationSha(value2) {
+  return contentSha(JSON.stringify(canonicalize(value2)));
+}
+function canonicalize(value2) {
+  if (Array.isArray(value2)) return value2.map(canonicalize);
+  if (typeof value2 === "object" && value2 !== null) {
+    const out = {};
+    for (const key of Object.keys(value2).sort()) {
+      out[key] = canonicalize(value2[key]);
+    }
+    return out;
+  }
+  return value2;
+}
+
+// src/telemetry.ts
+var MAX_ERROR_CHARS = 2e3;
+var MAX_SPOOL_BYTES = 1024 * 1024;
+var MAX_FLUSH_EVENTS = 500;
+function spoolPath() {
+  return path3.join(os2.homedir(), ".lotics", "telemetry.ndjson");
+}
+var stderrTail = "";
+function recordStderr(text) {
+  stderrTail = (stderrTail + text).slice(-MAX_ERROR_CHARS);
+}
+function installStderrCapture() {
+  const original = process.stderr.write.bind(process.stderr);
+  process.stderr.write = ((chunk, encoding, cb) => {
+    recordStderr(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf-8"));
+    return typeof encoding === "function" ? original(chunk, encoding) : original(chunk, encoding, cb);
+  });
+}
+function stripNarration(tail) {
+  return tail.split("\n").filter((line) => !line.startsWith("lotics \u2192 ")).join("\n").trim();
+}
+function argsShape(args, prefix = "", depth = 0) {
+  if (depth > 6) return [];
+  if (Array.isArray(args)) {
+    const head = args.length > 0 ? argsShape(args[0], `${prefix}[]`, depth + 1) : [];
+    return [`${prefix}:array`, ...head];
+  }
+  if (typeof args === "object" && args !== null) {
+    const out = prefix === "" ? [] : [`${prefix}:object`];
+    for (const [key, value2] of Object.entries(args)) {
+      out.push(...argsShape(value2, prefix === "" ? key : `${prefix}.${key}`, depth + 1));
+    }
+    return out;
+  }
+  return prefix === "" ? [] : [`${prefix}:${args === null ? "null" : typeof args}`];
+}
+var pendingArgs = null;
+function noteToolArgs(args) {
+  if (!telemetryEnabled()) return;
+  pendingArgs = { args_sha: declarationSha(args), args_shape: argsShape(args) };
+}
+var pendingScope = {};
+function noteScope(scope) {
+  if (!telemetryEnabled()) return;
+  pendingScope = { ...pendingScope, ...scope };
+}
+function buildEvent(exitCode, durationMs, now) {
+  const invocation2 = getInvocation();
+  if (invocation2 === null || invocation2.session === null) return null;
+  const message2 = exitCode === 0 ? "" : stripNarration(stderrTail);
+  return {
+    event_id: crypto.randomUUID(),
+    ts: now.toISOString(),
+    cli_session_id: invocation2.session,
+    cli_command: invocation2.command,
+    // `--flag=value` splits — the name is a fact about the command, the value is data.
+    cli_flags: process.argv.slice(2).filter((a) => a.startsWith("-")).map((a) => a.split("=")[0]),
+    exit_code: exitCode,
+    duration_ms: durationMs,
+    cli_version: invocation2.userAgent.split(" ")[0].replace("lotics-cli/", ""),
+    ...message2 !== "" && { error_message: message2 },
+    ...pendingArgs,
+    ...pendingScope
+  };
+}
+function appendEvent(event) {
+  const file2 = spoolPath();
+  try {
+    fs3.mkdirSync(path3.dirname(file2), { recursive: true });
+    if ((fs3.statSync(file2, { throwIfNoEntry: false })?.size ?? 0) > MAX_SPOOL_BYTES) {
+      fs3.rmSync(file2, { force: true });
+    }
+    fs3.appendFileSync(file2, `${JSON.stringify(event)}
+`, { mode: 384 });
+  } catch {
+  }
+}
+function readSpool() {
+  try {
+    const events = [];
+    const lines = [];
+    for (const line of fs3.readFileSync(spoolPath(), "utf-8").split("\n")) {
+      if (line.trim() === "") continue;
+      try {
+        events.push(JSON.parse(line));
+        lines.push(line);
+      } catch {
+      }
+    }
+    return { events, lines };
+  } catch {
+    return { events: [], lines: [] };
+  }
+}
+function clearSpool(sent) {
+  try {
+    const current = fs3.readFileSync(spoolPath(), "utf-8");
+    fs3.writeFileSync(spoolPath(), current.startsWith(sent) ? current.slice(sent.length) : "", {
+      mode: 384
+    });
+  } catch {
+  }
+}
+function installTelemetry(startedAt2 = Date.now()) {
+  if (!telemetryEnabled()) return;
+  installStderrCapture();
+  process.on("exit", (code) => {
+    const event = buildEvent(code, Date.now() - startedAt2, /* @__PURE__ */ new Date());
+    if (event !== null) appendEvent(event);
+  });
+}
+function flushSpool(post, minEvents = 5) {
+  if (!telemetryEnabled()) return;
+  const { events, lines } = readSpool();
+  if (events.length < minEvents) return;
+  const batch = events.slice(0, MAX_FLUSH_EVENTS);
+  const sent = `${lines.slice(0, batch.length).join("\n")}
+`;
+  void post(batch).then(() => {
+    clearSpool(sent);
+  }).catch(() => {
+  });
+}
+async function postEvents(baseUrl, apiKey, events, timeoutMs = 5e3) {
+  const controller = new AbortController();
+  const timer2 = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(`${baseUrl}/v1/cli/telemetry`, {
+      method: "POST",
+      headers: { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ events }),
+      signal: controller.signal
+    });
+    if (!res.ok) throw new Error(`telemetry flush: ${res.status}`);
+  } finally {
+    clearTimeout(timer2);
+  }
+}
+
 // src/config.ts
-import fs2 from "node:fs";
-import path2 from "node:path";
-import os from "node:os";
+import fs4 from "node:fs";
+import path4 from "node:path";
+import os3 from "node:os";
 function globalConfigFile() {
-  return path2.join(os.homedir(), ".lotics", "config.json");
+  return path4.join(os3.homedir(), ".lotics", "config.json");
 }
 function configFileForScope(scope) {
   if (scope === "local") {
-    return path2.join(process.cwd(), ".lotics", "config.json");
+    return path4.join(process.cwd(), ".lotics", "config.json");
   }
   let dir = process.cwd();
   for (; ; ) {
-    const candidate = path2.join(dir, ".lotics", "config.json");
-    if (fs2.existsSync(candidate)) {
+    const candidate = path4.join(dir, ".lotics", "config.json");
+    if (fs4.existsSync(candidate)) {
       return candidate;
     }
-    const parent = path2.dirname(dir);
+    const parent = path4.dirname(dir);
     if (parent === dir) {
       break;
     }
@@ -45074,25 +45329,25 @@ function configFileForScope(scope) {
 }
 function readConfigFile(file2) {
   try {
-    const raw = fs2.readFileSync(file2, "utf-8");
+    const raw = fs4.readFileSync(file2, "utf-8");
     return JSON.parse(raw);
   } catch {
     return null;
   }
 }
 function writeConfigFile(file2, config2) {
-  fs2.mkdirSync(path2.dirname(file2), { recursive: true, mode: 448 });
+  fs4.mkdirSync(path4.dirname(file2), { recursive: true, mode: 448 });
   const tmp = `${file2}.${process.pid}.tmp`;
-  fs2.writeFileSync(tmp, JSON.stringify(config2, null, 2) + "\n", { encoding: "utf-8", mode: 384 });
-  fs2.chmodSync(tmp, 384);
-  fs2.renameSync(tmp, file2);
+  fs4.writeFileSync(tmp, JSON.stringify(config2, null, 2) + "\n", { encoding: "utf-8", mode: 384 });
+  fs4.chmodSync(tmp, 384);
+  fs4.renameSync(tmp, file2);
 }
 function saveConfig(config2, scope = "auto") {
   writeConfigFile(configFileForScope(scope), config2);
 }
 function deleteConfig(scope = "auto") {
   try {
-    fs2.unlinkSync(configFileForScope(scope));
+    fs4.unlinkSync(configFileForScope(scope));
   } catch {
   }
 }
@@ -45319,20 +45574,20 @@ Update available: ${current} \u2192 ${latest}`);
 // src/version.ts
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import path3 from "node:path";
-var pkgPath = path3.resolve(path3.dirname(fileURLToPath(import.meta.url)), "../../package.json");
+import path5 from "node:path";
+var pkgPath = path5.resolve(path5.dirname(fileURLToPath(import.meta.url)), "../../package.json");
 var pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
 var VERSION = pkg.version;
 
 // src/app_commands.ts
-import fs4 from "node:fs";
-import path5 from "node:path";
+import fs6 from "node:fs";
+import path7 from "node:path";
 import { spawn as spawn2 } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 
 // src/starter_template.ts
-var STARTER_FALLBACK_UI_VERSION = "27.11.0";
+var STARTER_FALLBACK_UI_VERSION = "28.1.0";
 var STARTER_FALLBACK_SDK_VERSION = "0.52.0";
 var STARTER_REACT_NATIVE_VERSION = "0.85.3";
 var VITEST_SETUP_FILENAME = "vitest.setup.ts";
@@ -45538,7 +45793,6 @@ export default defineConfig({
   //   const base = loticsResolve();
   //   resolve: { ...base, alias: [...base.alias, { find: "x", replacement: "y" }] }
   resolve: loticsResolve(),
-  },
   optimizeDeps: {
     // The dev dep-optimizer must pre-bundle @lotics/ui's RN-ecosystem + markdown
     // CJS-interop deps or \`lotics app dev\` blanks the iframe ("does not provide an
@@ -46559,7 +46813,7 @@ function createUploadRelay(now = Date.now) {
 }
 
 // src/dev/file_relay.ts
-import { createHash } from "node:crypto";
+import { createHash as createHash2 } from "node:crypto";
 var TTL_MS = 24 * 60 * 60 * 1e3;
 var MAX_ENTRIES = 5e3;
 var PRESIGNED_KEYS = /* @__PURE__ */ new Set(["url", "thumbnail_url", "preview_url"]);
@@ -46567,7 +46821,7 @@ var isFileObject = (o) => typeof o.filename === "string" && typeof o.mime_type =
 var isRemoteUrl = (v) => typeof v === "string" && /^https?:\/\//i.test(v);
 function createFileRelay(wrapperOrigin, now = Date.now) {
   const seen = /* @__PURE__ */ new Map();
-  const tokenFor = (url2) => createHash("sha256").update(url2).digest("hex").slice(0, 24);
+  const tokenFor = (url2) => createHash2("sha256").update(url2).digest("hex").slice(0, 24);
   const remember = (url2) => {
     const token = tokenFor(url2);
     seen.set(token, { url: url2, at: now() });
@@ -46681,7 +46935,7 @@ async function startDevServer(args) {
     if (req.method === "POST" && url2 === "/_rpc") {
       try {
         const body = await readJson(req);
-        const startedAt = Date.now();
+        const startedAt2 = Date.now();
         const result = await dispatchRpc(
           args.client,
           {
@@ -46691,7 +46945,7 @@ async function startDevServer(args) {
           },
           { commentsEnabled: args.commentsEnabled }
         );
-        const ms = Date.now() - startedAt;
+        const ms = Date.now() - startedAt2;
         process.stderr.write(`[rpc] ${body.op} ${ms}ms
 `);
         res.writeHead(200, { "Content-Type": "application/json" });
@@ -46844,13 +47098,13 @@ async function startDevServer(args) {
         const chunks = [];
         for await (const chunk of req) chunks.push(chunk);
         const bytes = Buffer.concat(chunks);
-        const startedAt = Date.now();
+        const startedAt2 = Date.now();
         const upstream = await fetch(destination, {
           method: "PUT",
           body: bytes,
           headers: { "Content-Type": req.headers["content-type"] ?? "application/octet-stream" }
         });
-        const ms = Date.now() - startedAt;
+        const ms = Date.now() - startedAt2;
         if (upstream.ok) {
           uploads.settle(fileId);
           process.stderr.write(`[upload] ${fileId} ${bytes.length}B ${ms}ms
@@ -47246,6 +47500,9 @@ function calledAppAliases(sourceText) {
   }
   return out;
 }
+function orphanedAliases(bound, called) {
+  return unboundAliases(bound, called);
+}
 function unboundAliases(called, bound) {
   const missing = (from, against) => {
     const have = new Set(against ?? []);
@@ -47533,8 +47790,8 @@ export type AppRoles = typeof ROLE;
 }
 
 // src/app_workflow_check.ts
-import fs3 from "node:fs";
-import path4 from "node:path";
+import fs5 from "node:fs";
+import path6 from "node:path";
 import { createRequire } from "node:module";
 
 // ../shared/src/parse_workflow_js.ts
@@ -48306,10 +48563,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path8) {
-  if (!path8)
+function getElementAtPath(obj, path10) {
+  if (!path10)
     return obj;
-  return path8.reduce((acc, key) => acc?.[key], obj);
+  return path10.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys3 = Object.keys(promisesObj);
@@ -48718,11 +48975,11 @@ function explicitlyAborted(x2, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path8, issues) {
+function prefixIssues(path10, issues) {
   return issues.map((iss) => {
     var _a4;
     (_a4 = iss).path ?? (_a4.path = []);
-    iss.path.unshift(path8);
+    iss.path.unshift(path10);
     return iss;
   });
 }
@@ -48869,16 +49126,16 @@ function flattenError(error52, mapper = (issue2) => issue2.message) {
 }
 function formatError(error52, mapper = (issue2) => issue2.message) {
   const fieldErrors = { _errors: [] };
-  const processError = (error53, path8 = []) => {
+  const processError = (error53, path10 = []) => {
     for (const issue2 of error53.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path8, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path10, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path8, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path10, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path8, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path10, ...issue2.path]);
       } else {
-        const fullpath = [...path8, ...issue2.path];
+        const fullpath = [...path10, ...issue2.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue2));
         } else {
@@ -48905,17 +49162,17 @@ function formatError(error52, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error52, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error53, path8 = []) => {
+  const processError = (error53, path10 = []) => {
     var _a4, _b2;
     for (const issue2 of error53.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path8, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path10, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path8, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path10, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path8, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path10, ...issue2.path]);
       } else {
-        const fullpath = [...path8, ...issue2.path];
+        const fullpath = [...path10, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -48947,8 +49204,8 @@ function treeifyError(error52, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path8 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path8) {
+  const path10 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path10) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -61640,13 +61897,13 @@ function resolveRef(ref2, ctx) {
   if (!ref2.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path8 = ref2.slice(1).split("/").filter(Boolean);
-  if (path8.length === 0) {
+  const path10 = ref2.slice(1).split("/").filter(Boolean);
+  if (path10.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path8[0] === defsKey) {
-    const key = path8[1];
+  if (path10[0] === defsKey) {
+    const key = path10[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref2}`);
     }
@@ -64478,6 +64735,7 @@ var PICKER_MODEL_TIERS = MODEL_TIERS.filter(
   (tier) => tier !== UTILITY_MODEL_TIER
 );
 var EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
+var PREFIX_CACHE_TTLS = ["5m", "1h"];
 
 // ../shared/src/schemas/apps.ts
 var queryColumnTypeSchema = zod_default.enum([
@@ -64903,6 +65161,9 @@ var appWorkflowDeclarationSchema = zod_default.object({
   ),
   description: zod_default.string().optional().describe(
     "What this workflow does, in one line \u2014 read by an agent choosing between the app's aliases, the same job a query's `description` does. `lotics app workflow set` sends it, so it lives beside the body in version control; omitted, the workflow keeps the description already on it."
+  ),
+  body_sha: zod_default.string().optional().describe(
+    "Fingerprint of the body currently bound to this alias, written by the server on every accepted `set_app_workflow`. Never sent by a caller \u2014 it is the value a caller's `expected_body_sha` is checked against, so that a push built on a stale copy of the body is refused instead of silently overwriting whatever replaced it. Absent on a binding last written before the field existed, where no comparison is possible."
   )
 });
 var appWorkflowContractSchema = zod_default.object({
@@ -64941,6 +65202,9 @@ var appAgentDeclarationSchema = zod_default.object({
   effort_level: zod_default.enum(EFFORT_LEVELS).optional().describe(
     "Reasoning depth for adaptive-thinking tiers \u2014 one of the chosen tier's supported levels (validated against model_tier at declare time). Omit to use the model default; ignored on tiers without adaptive thinking."
   ),
+  prefix_cache_ttl: zod_default.enum(PREFIX_CACHE_TTLS).optional().describe(
+    `How long this agent's prompt-cache prefix (tools + system block) is kept warm. Omit \u2014 the default (5m, Anthropic's own) is right for essentially every agent. "1h" doubles the write price (2x the input rate against 1.25x) to buy only the 5m..1h band, and an entry nothing re-reads inside the hour is paid for twice over; declining it still leaves the prefix cached at the default. Set it only from measured cadence, never a guess.`
+  ),
   inputs: zod_default.record(zod_default.string(), appWorkflowInputSchema).optional().describe(
     "Typed input schema for one run. Keys are input names; values declare type + constraints. The server validates the run payload against this before invoking; CLI codegen emits a typed `useAgentRun<alias>` signature. Omit for an untyped payload."
   ),
@@ -65782,10 +66046,10 @@ async function reduce2(arr, callback, initial2) {
   if (arguments.length < 3) {
     throw new Error("reduce: initial value is required \u2014 reduce(arr, (acc, x) => ..., initial)");
   }
-  const startedAt = Date.now();
+  const startedAt2 = Date.now();
   let acc = initial2;
   for (let i2 = 0; i2 < arr.length; i2++) {
-    if (i2 % 1024 === 0 && Date.now() - startedAt > REDUCE_TIME_BUDGET_MS) {
+    if (i2 % 1024 === 0 && Date.now() - startedAt2 > REDUCE_TIME_BUDGET_MS) {
       throw new Error(
         `reduce: exceeded time budget of ${REDUCE_TIME_BUDGET_MS}ms after ${i2} iterations`
       );
@@ -66313,9 +66577,9 @@ __export(expression_object_exports, {
   pick: () => pick3,
   values: () => values2
 });
-function getNestedValue(obj, path8) {
+function getNestedValue(obj, path10) {
   if (obj == null) return void 0;
-  const parts = path8.split(".");
+  const parts = path10.split(".");
   let value2 = obj;
   for (const part of parts) {
     if (value2 == null) return void 0;
@@ -66354,11 +66618,11 @@ function entries(obj) {
   }
   return Object.entries(obj);
 }
-function get(obj, path8, defaultValue) {
-  if (typeof path8 !== "string") {
+function get(obj, path10, defaultValue) {
+  if (typeof path10 !== "string") {
     throw new Error("get: path must be a string");
   }
-  const value2 = getNestedValue(obj, path8);
+  const value2 = getNestedValue(obj, path10);
   return value2 !== void 0 ? value2 : defaultValue;
 }
 function pick3(obj, fields) {
@@ -68241,17 +68505,17 @@ function readFromChanges(chain2) {
     if (first3.kind === "bracket-number" || first3.kind === "bracket-expr") {
       fail(first3.node, "changes is keyed by field name, not numeric index.");
     }
-    const path8 = [{ at: "key", key: first3.key }];
+    const path10 = [{ at: "key", key: first3.key }];
     for (const seg of segments.slice(1)) {
       if (seg.kind === "bracket-number") {
-        path8.push({ at: "index", index: seg.index });
+        path10.push({ at: "index", index: seg.index });
       } else if (seg.kind === "bracket-expr") {
-        path8.push({ at: "index", index: seg.expr });
+        path10.push({ at: "index", index: seg.expr });
       } else {
-        path8.push({ at: "key", key: seg.key });
+        path10.push({ at: "key", key: seg.key });
       }
     }
-    return { kind: "read", source: { from: "trigger_changes" }, path: path8 };
+    return { kind: "read", source: { from: "trigger_changes" }, path: path10 };
   });
 }
 var TRIGGER_RECORD_VIEWS = /* @__PURE__ */ new Map([
@@ -68269,17 +68533,17 @@ function readFromTrigger(chain2) {
     return view === "trigger_changes" ? readFromChanges(lowered) : readFromRecord(view, lowered);
   }
   return wrapOptionalGuards(chain2, (segments) => {
-    const path8 = [];
+    const path10 = [];
     for (const seg of segments) {
       if (seg.kind === "bracket-number") {
-        path8.push({ at: "index", index: seg.index });
+        path10.push({ at: "index", index: seg.index });
       } else if (seg.kind === "bracket-expr") {
-        path8.push({ at: "index", index: seg.expr });
+        path10.push({ at: "index", index: seg.expr });
       } else {
-        path8.push({ at: "key", key: seg.key });
+        path10.push({ at: "key", key: seg.key });
       }
     }
-    return { kind: "read", source: { from: "trigger" }, path: path8 };
+    return { kind: "read", source: { from: "trigger" }, path: path10 };
   });
 }
 function readFromRuntime(chain2) {
@@ -68301,17 +68565,17 @@ function readFromRuntime(chain2) {
     const parked = PARKED_RUNTIME_KEYS.get(key);
     if (parked) fail(first3.node, parked, parkedRuntimeKeyConstruct(key));
     const source = { from: "runtime", key };
-    const path8 = [];
+    const path10 = [];
     for (const seg of segments.slice(1)) {
       if (seg.kind === "bracket-number") {
-        path8.push({ at: "index", index: seg.index });
+        path10.push({ at: "index", index: seg.index });
       } else if (seg.kind === "bracket-expr") {
-        path8.push({ at: "index", index: seg.expr });
+        path10.push({ at: "index", index: seg.expr });
       } else {
-        path8.push({ at: "key", key: seg.key });
+        path10.push({ at: "key", key: seg.key });
       }
     }
-    return { kind: "read", source, path: path8 };
+    return { kind: "read", source, path: path10 };
   });
 }
 function readFromForeachItem(chain2) {
@@ -68347,17 +68611,17 @@ function readFromLexical(name2, chain2) {
 }
 function readFromStepOutput(stepId, chain2) {
   return wrapOptionalGuards(chain2, (segments) => {
-    const path8 = [];
+    const path10 = [];
     for (const seg of segments) {
       if (seg.kind === "bracket-number") {
-        path8.push({ at: "index", index: seg.index });
+        path10.push({ at: "index", index: seg.index });
       } else if (seg.kind === "bracket-expr") {
-        path8.push({ at: "index", index: seg.expr });
+        path10.push({ at: "index", index: seg.expr });
       } else {
-        path8.push({ at: "key", key: seg.key });
+        path10.push({ at: "key", key: seg.key });
       }
     }
-    return { kind: "read", source: { from: "step_output", step_id: stepId }, path: path8 };
+    return { kind: "read", source: { from: "step_output", step_id: stepId }, path: path10 };
   });
 }
 function classifyRecordPath(segs) {
@@ -70011,7 +70275,7 @@ function subsetIssues(bodySource, offset) {
   ];
 }
 async function loadProjectTypescript(projectDir) {
-  const requireFromProject = createRequire(path4.join(projectDir, "package.json"));
+  const requireFromProject = createRequire(path6.join(projectDir, "package.json"));
   let resolved;
   try {
     resolved = requireFromProject.resolve("typescript");
@@ -70024,12 +70288,12 @@ async function loadProjectTypescript(projectDir) {
   return mod2.default ?? mod2;
 }
 function pathToImportUrl(p) {
-  const resolved = path4.resolve(p);
+  const resolved = path6.resolve(p);
   const prefixed = resolved.startsWith("/") ? resolved : `/${resolved}`;
-  return `file://${prefixed.split(path4.sep).join("/")}`;
+  return `file://${prefixed.split(path6.sep).join("/")}`;
 }
 function checkOneWorkflowBody(tsApi, input) {
-  const wrapped = fs3.readFileSync(input.bodyPath, "utf-8");
+  const wrapped = fs5.readFileSync(input.bodyPath, "utf-8");
   const offset = bodyLineOffset(wrapped);
   const subset = subsetIssues(stripWorkflowHeader(wrapped), offset);
   if (subset) return subset;
@@ -70076,7 +70340,7 @@ function checkOneWorkflowBody(tsApi, input) {
 }
 function createCheckedSourceHost(tsApi, options, bodyPath, bodyText) {
   const base = tsApi.createCompilerHost(options, false);
-  const key = (fileName) => base.getCanonicalFileName(path4.resolve(fileName).replace(/\\/g, "/"));
+  const key = (fileName) => base.getCanonicalFileName(path6.resolve(fileName).replace(/\\/g, "/"));
   const bodyKey = key(bodyPath);
   return {
     ...base,
@@ -70145,6 +70409,14 @@ function orderedLike(value2, template) {
     [...first3, ...rest2].map((k) => [k, orderedLike(from[k], tmpl[k])])
   );
 }
+function toManifestWorkflows(live) {
+  return Object.fromEntries(
+    Object.entries(live).map(([alias, { body_sha: _serverState, ...declaration }]) => [
+      alias,
+      declaration
+    ])
+  );
+}
 function toManifestAgents(agents) {
   return Object.fromEntries(
     Object.entries(agents).map(([alias, { instructions: _prose, ...typed }]) => [alias, typed])
@@ -70163,27 +70435,58 @@ function sameSchema(a, b) {
   };
   return JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
 }
-function agentTypeDivergences(manifestAgents, liveAgents) {
+function workflowTypeDivergences(manifestWorkflows, liveWorkflows) {
   const out = [];
-  for (const [alias, declared] of Object.entries(manifestAgents ?? {})) {
-    const live = (liveAgents ?? {})[alias];
+  for (const [alias, declared] of Object.entries(manifestWorkflows ?? {})) {
+    const live = (liveWorkflows ?? {})[alias];
     if (!live) {
-      out.push(
-        `${alias} \u2014 typed locally but NOT bound on the app, so useAgentRun("${alias}") 400s at runtime`
-      );
+      out.push({ alias });
       continue;
     }
-    for (const key of AGENT_TYPED_KEYS) {
-      if (!sameSchema(declared[key], live[key])) {
-        out.push(`${alias}.${key} \u2014 local types disagree with the live agent`);
-      }
+    for (const key of ["inputs", "outputs"]) {
+      if (!sameSchema(declared[key], live[key])) out.push({ alias, key });
     }
   }
   return out;
 }
-var WORKFLOWS_DIR = path5.join("src", "workflows");
-var WORKFLOW_GLOBALS_DIR = path5.join(".lotics", "workflows");
-var AGENTS_DIR = path5.join("src", "agents");
+function syncedEntry(entry) {
+  if (entry === void 0) return void 0;
+  return typeof entry === "string" ? { content: entry } : entry;
+}
+function readSynced(projectDir) {
+  try {
+    const pkg2 = JSON.parse(
+      fs6.readFileSync(path7.join(projectDir, "package.json"), "utf-8")
+    );
+    const raw = pkg2.lotics?.synced ?? {};
+    return {
+      workflows: normalizeSyncedMap(raw.workflows),
+      agents: normalizeSyncedMap(raw.agents),
+      queries: normalizeSyncedMap(raw.queries)
+    };
+  } catch {
+    return { workflows: {}, agents: {}, queries: {} };
+  }
+}
+function normalizeSyncedMap(map3) {
+  return Object.fromEntries(
+    Object.entries(map3 ?? {}).map(([alias, entry]) => [
+      alias,
+      syncedEntry(entry)
+    ])
+  );
+}
+function writeSynced(projectDir, kind, alias, entry) {
+  const pkgPath2 = path7.join(projectDir, "package.json");
+  const pkg2 = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
+  if (!pkg2.lotics) return;
+  pkg2.lotics.synced ??= {};
+  pkg2.lotics.synced[kind] = { ...pkg2.lotics.synced[kind], [alias]: entry };
+  fs6.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
+}
+var WORKFLOWS_DIR = path7.join("src", "workflows");
+var WORKFLOW_GLOBALS_DIR = path7.join(".lotics", "workflows");
+var AGENTS_DIR = path7.join("src", "agents");
 var WORKFLOW_TSCONFIG_EXCLUDES = ["src/workflows", ".lotics/workflows"];
 var LOTICS_INCLUDE_GLOB = ".lotics/**/*";
 var STALE_LOTICS_INCLUDES = /* @__PURE__ */ new Set([".lotics", "./.lotics", ".lotics/"]);
@@ -70193,11 +70496,8 @@ function toWorkflowDtsDeclaration(d) {
 function isMissingWorkflowBodyError(error52) {
   return /has no step source|cannot be rendered|unsupported step/i.test(error52);
 }
-function isUnknownWorkflowAliasError(err2) {
-  return err2 instanceof Error && err2.message.startsWith("400:") && /has no workflow alias/i.test(err2.message);
-}
 function workflowFileHeader(alias) {
-  const refPath = path5.join("..", "..", WORKFLOW_GLOBALS_DIR, `${alias}.globals.d.ts`).split(path5.sep).join("/");
+  const refPath = path7.join("..", "..", WORKFLOW_GLOBALS_DIR, `${alias}.globals.d.ts`).split(path7.sep).join("/");
   return `/// <reference path="${refPath}" />
 // Auto-pulled workflow body for "${alias}". Edit the BODY between the wrapper
 // lines below, then check + push with:
@@ -70211,65 +70511,68 @@ export {};
 `;
 }
 function workflowFilePath(projectDir, alias) {
-  return path5.join(projectDir, WORKFLOWS_DIR, `${alias}.ts`);
+  return path7.join(projectDir, WORKFLOWS_DIR, `${alias}.ts`);
 }
 var GLOBALS_SUFFIX = ".globals.d.ts";
 function workflowGlobalsPath(projectDir, alias) {
-  return path5.join(projectDir, WORKFLOW_GLOBALS_DIR, `${alias}${GLOBALS_SUFFIX}`);
+  return path7.join(projectDir, WORKFLOW_GLOBALS_DIR, `${alias}${GLOBALS_SUFFIX}`);
 }
 function pruneOrphanWorkflowGlobals(projectDir, declared) {
-  const dir = path5.join(projectDir, WORKFLOW_GLOBALS_DIR);
-  if (!fs4.existsSync(dir)) return [];
+  const dir = path7.join(projectDir, WORKFLOW_GLOBALS_DIR);
+  if (!fs6.existsSync(dir)) return [];
   const removed = [];
-  for (const entry of fs4.readdirSync(dir)) {
+  for (const entry of fs6.readdirSync(dir)) {
     if (!entry.endsWith(GLOBALS_SUFFIX)) continue;
     const alias = entry.slice(0, -GLOBALS_SUFFIX.length);
     if (declared.has(alias)) continue;
-    fs4.unlinkSync(path5.join(dir, entry));
+    fs6.unlinkSync(path7.join(dir, entry));
     removed.push(alias);
   }
   return removed.sort();
 }
 function orphanWorkflowBodies(projectDir, declared) {
-  const dir = path5.join(projectDir, WORKFLOWS_DIR);
-  if (!fs4.existsSync(dir)) return [];
-  return fs4.readdirSync(dir).filter((e) => e.endsWith(".ts") && !e.endsWith(".d.ts") && !e.endsWith(".test.ts")).map((e) => e.slice(0, -".ts".length)).filter((alias) => !declared.has(alias)).sort();
+  const dir = path7.join(projectDir, WORKFLOWS_DIR);
+  if (!fs6.existsSync(dir)) return [];
+  return fs6.readdirSync(dir).filter((e) => e.endsWith(".ts") && !e.endsWith(".d.ts") && !e.endsWith(".test.ts")).map((e) => e.slice(0, -".ts".length)).filter((alias) => !declared.has(alias)).sort();
 }
 function writeWorkflowGlobals(projectDir, alias, dts) {
-  const dir = path5.join(projectDir, WORKFLOW_GLOBALS_DIR);
-  fs4.mkdirSync(dir, { recursive: true });
+  const dir = path7.join(projectDir, WORKFLOW_GLOBALS_DIR);
+  fs6.mkdirSync(dir, { recursive: true });
   const file2 = workflowGlobalsPath(projectDir, alias);
-  fs4.writeFileSync(file2, `${dts.replace(/\s+$/, "")}
+  fs6.writeFileSync(file2, `${dts.replace(/\s+$/, "")}
 `);
   return file2;
 }
+function normalizeWorkflowBody(source) {
+  return source.replace(/\s+$/, "");
+}
 function writeWorkflowFile(projectDir, alias, source, envelope = { prefix: WORKFLOW_ENVELOPE_PREFIX, suffix: WORKFLOW_ENVELOPE_SUFFIX }) {
-  const dir = path5.join(projectDir, WORKFLOWS_DIR);
-  fs4.mkdirSync(dir, { recursive: true });
+  const dir = path7.join(projectDir, WORKFLOWS_DIR);
+  fs6.mkdirSync(dir, { recursive: true });
   const file2 = workflowFilePath(projectDir, alias);
-  const body = source.replace(/\s+$/, "");
-  fs4.writeFileSync(file2, `${workflowFileHeader(alias)}
+  const body = normalizeWorkflowBody(source);
+  fs6.writeFileSync(file2, `${workflowFileHeader(alias)}
 ${envelope.prefix}${body}${envelope.suffix}
 `);
   return file2;
 }
 function agentFilePath2(projectDir, alias) {
-  return path5.join(projectDir, ...agentFilePath(alias).split("/"));
+  return path7.join(projectDir, ...agentFilePath(alias).split("/"));
 }
 var CLI_AGENT_NOTES = [
   "Pulled from the LIVE app row; edit here, then: lotics app agent set <alias>",
   "The typed fields (inputs/outputs/tool_names/model_tier) live in package.json#lotics.agents"
 ];
 function writeAgentFile(projectDir, alias, instructions) {
-  fs4.mkdirSync(path5.join(projectDir, AGENTS_DIR), { recursive: true });
+  fs6.mkdirSync(path7.join(projectDir, AGENTS_DIR), { recursive: true });
   const file2 = agentFilePath2(projectDir, alias);
-  fs4.writeFileSync(
+  fs6.writeFileSync(
     file2,
     wrapAgentFile({ alias, instructions, notes: CLI_AGENT_NOTES.map((n) => n.replace("<alias>", alias)) })
   );
   return file2;
 }
-function writeAgentFiles(projectDir, agents) {
+function writeAgentFiles(projectDir, agents, opts) {
   const written = [];
   for (const [alias, declaration] of Object.entries(agents)) {
     const instructions = declaration.instructions;
@@ -70277,15 +70580,33 @@ function writeAgentFiles(projectDir, agents) {
       console.error(`\u26A0 Skipped src/agents/${alias}.md \u2014 the live declaration carries no instructions.`);
       continue;
     }
+    if (!opts.overwrite && localPromptUnpushed(projectDir, alias)) {
+      opts.kept.push(`src/agents/${alias}.md`);
+      continue;
+    }
     writeAgentFile(projectDir, alias, instructions);
     written.push(alias);
   }
   return written;
 }
+function localPromptUnpushed(projectDir, alias) {
+  const file2 = agentFilePath2(projectDir, alias);
+  if (!fs6.existsSync(file2)) return false;
+  const baseline = readSynced(projectDir).agents[alias]?.content;
+  if (baseline === void 0) return true;
+  return contentSha(stripAgentHeader(fs6.readFileSync(file2, "utf-8"))) !== baseline;
+}
 function generatedWorkflowDescription(appName, alias) {
   return `Workflow invoked by app "${appName}" via useWorkflow("${alias}").`;
 }
-async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows) {
+function localBodyUnpushed(projectDir, alias) {
+  const file2 = workflowFilePath(projectDir, alias);
+  if (!fs6.existsSync(file2)) return false;
+  const baseline = readSynced(projectDir).workflows[alias]?.content;
+  if (baseline === void 0) return true;
+  return contentSha(stripWorkflowHeader(fs6.readFileSync(file2, "utf-8"))) !== baseline;
+}
+async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows, opts) {
   const written = [];
   for (const [alias, declaration] of Object.entries(workflows)) {
     const res = await client.getAppWorkflow(app_id, alias);
@@ -70294,7 +70615,9 @@ async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows
         `Could not read workflow "${alias}" of ${app_id}: ${res.error}. Reading app workflow source requires an admin member \u2014 check the role behind this API key.`
       );
     }
-    const source = res.result === null || typeof res.result !== "object" ? null : res.result.source;
+    const result = res.result === null || typeof res.result !== "object" ? null : res.result;
+    const source = result?.source;
+    const body_sha = typeof result?.body_sha === "string" ? result.body_sha : void 0;
     if (typeof source !== "string" || source.trim() === "") {
       console.error(
         `\u26A0 Skipped src/workflows/${alias}.ts \u2014 legacy workflow with no rendered body.`
@@ -70308,7 +70631,15 @@ async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows
       alias,
       toWorkflowDtsDeclaration(declaration)
     );
+    if (!opts.overwrite && localBodyUnpushed(projectDir, alias)) {
+      opts.kept.push(`src/workflows/${alias}.ts`);
+      continue;
+    }
     writeWorkflowFile(projectDir, alias, source, envelope);
+    writeSynced(projectDir, "workflows", alias, {
+      content: contentSha(normalizeWorkflowBody(source)),
+      ...body_sha ? { live: body_sha } : {}
+    });
     const rowDescription = res.result.description;
     if (typeof rowDescription === "string" && rowDescription !== "" && // Skip the server's GENERATED default. It is what an undescribed alias
     // carries, so writing it back would commit a line of noise per workflow
@@ -70323,12 +70654,12 @@ async function writeWorkflowFiles(client, projectDir, app_id, appName, workflows
   return written;
 }
 function writeWorkflowDescription(projectDir, alias, description) {
-  const pkgPath2 = path5.join(projectDir, "package.json");
-  const pkg2 = JSON.parse(fs4.readFileSync(pkgPath2, "utf-8"));
+  const pkgPath2 = path7.join(projectDir, "package.json");
+  const pkg2 = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
   const declaration = pkg2.lotics?.workflows?.[alias];
   if (!declaration) return;
   declaration.description = description;
-  fs4.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
+  fs6.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
 }
 async function fetchWorkflowGlobals(client, projectDir, app_id, alias, declaration) {
   try {
@@ -70348,14 +70679,9 @@ async function fetchWorkflowGlobals(client, projectDir, app_id, alias, declarati
   }
 }
 async function fetchWorkflowDts(client, app_id, alias, declaration) {
-  try {
-    return await client.getAppWorkflowDts(app_id, alias);
-  } catch (err2) {
-    if (declaration && isUnknownWorkflowAliasError(err2)) {
-      return client.getAppWorkflowDts(app_id, alias, declaration);
-    }
-    throw err2;
-  }
+  const declaresSchema = declaration !== void 0 && (declaration.inputs !== void 0 || declaration.outputs !== void 0);
+  if (declaresSchema) return client.getAppWorkflowDts(app_id, alias, declaration);
+  return client.getAppWorkflowDts(app_id, alias);
 }
 function runTar(args, cwd) {
   return new Promise((resolve2, reject2) => {
@@ -70383,25 +70709,26 @@ function runNpm(args, cwd) {
 }
 function readAppWorkspaceId(projectDir) {
   try {
-    const pkgPath2 = path5.join(projectDir, "package.json");
-    if (!fs4.existsSync(pkgPath2)) return null;
-    const pkg2 = JSON.parse(fs4.readFileSync(pkgPath2, "utf-8"));
+    const pkgPath2 = path7.join(projectDir, "package.json");
+    if (!fs6.existsSync(pkgPath2)) return null;
+    const pkg2 = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
     return pkg2.lotics?.workspace_id ?? null;
   } catch {
     return null;
   }
 }
 function readAppMeta(projectDir) {
-  const pkgPath2 = path5.join(projectDir, "package.json");
-  if (!fs4.existsSync(pkgPath2)) {
+  const pkgPath2 = path7.join(projectDir, "package.json");
+  if (!fs6.existsSync(pkgPath2)) {
     throw new Error(`No package.json found at ${projectDir}. Run 'lotics app create' first.`);
   }
-  const pkg2 = JSON.parse(fs4.readFileSync(pkgPath2, "utf-8"));
+  const pkg2 = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
   if (!pkg2.lotics?.app_id || !pkg2.lotics.workspace_id) {
     throw new Error(
       `package.json is missing the 'lotics' field with app_id and workspace_id. Was this folder created with 'lotics app create'?`
     );
   }
+  noteScope({ app_id: pkg2.lotics.app_id });
   return {
     app_id: pkg2.lotics.app_id,
     workspace_id: pkg2.lotics.workspace_id,
@@ -70424,19 +70751,22 @@ var APP_META_KEYS = Object.keys({
   capabilities: true
 });
 function writeAppMeta(projectDir, meta3) {
-  const pkgPath2 = path5.join(projectDir, "package.json");
-  const pkg2 = JSON.parse(fs4.readFileSync(pkgPath2, "utf-8"));
+  const pkgPath2 = path7.join(projectDir, "package.json");
+  const pkg2 = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
   const existing = pkg2.lotics && typeof pkg2.lotics === "object" ? pkg2.lotics : {};
+  const supplied = new Set(
+    Object.entries(meta3).filter(([, value2]) => value2 !== void 0).map(([key]) => key)
+  );
   const preserved = {};
   for (const [key, value2] of Object.entries(existing)) {
-    if (!APP_META_KEYS.includes(key)) preserved[key] = value2;
+    if (!supplied.has(key)) preserved[key] = value2;
   }
   pkg2.lotics = { ...meta3, ...preserved };
-  fs4.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
+  fs6.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
 }
 function writeWorkflowOutputs(projectDir, alias, outputs) {
-  const pkgPath2 = path5.join(projectDir, "package.json");
-  const pkg2 = JSON.parse(fs4.readFileSync(pkgPath2, "utf-8"));
+  const pkgPath2 = path7.join(projectDir, "package.json");
+  const pkg2 = JSON.parse(fs6.readFileSync(pkgPath2, "utf-8"));
   const declaration = pkg2.lotics?.workflows?.[alias];
   if (!declaration) {
     throw new Error(
@@ -70444,11 +70774,24 @@ function writeWorkflowOutputs(projectDir, alias, outputs) {
     );
   }
   declaration.outputs = outputs;
-  fs4.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
+  fs6.writeFileSync(pkgPath2, JSON.stringify(pkg2, null, 2) + "\n");
+}
+function workflowBodyDrift(projectDir, workflows, synced = {}) {
+  const drifted = [];
+  for (const alias of Object.keys(workflows ?? {})) {
+    const baseline = syncedEntry(synced[alias])?.content;
+    if (baseline === void 0) continue;
+    const file2 = workflowFilePath(projectDir, alias);
+    if (!fs6.existsSync(file2)) continue;
+    const source = stripWorkflowHeader(fs6.readFileSync(file2, "utf-8"));
+    if (source.trim() === "" || contentSha(source) === baseline) continue;
+    drifted.push(alias);
+  }
+  return drifted;
 }
 function ensureAppTsconfig(projectDir) {
-  const tsconfigPath = path5.join(projectDir, "tsconfig.json");
-  if (!fs4.existsSync(tsconfigPath)) {
+  const tsconfigPath = path7.join(projectDir, "tsconfig.json");
+  if (!fs6.existsSync(tsconfigPath)) {
     console.error(
       `\u26A0 No tsconfig.json at ${projectDir} \u2014 could not ensure "include" has "${LOTICS_INCLUDE_GLOB}" (a bare .lotics loads none of the generated types) or "exclude" has ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")}.`
     );
@@ -70456,7 +70799,7 @@ function ensureAppTsconfig(projectDir) {
   }
   let parsed;
   try {
-    parsed = JSON.parse(fs4.readFileSync(tsconfigPath, "utf-8"));
+    parsed = JSON.parse(fs6.readFileSync(tsconfigPath, "utf-8"));
   } catch (err2) {
     console.error(
       `\u26A0 Could not parse tsconfig.json (${err2 instanceof Error ? err2.message : String(err2)}) \u2014 ensure "include" has "${LOTICS_INCLUDE_GLOB}" and "exclude" has ${WORKFLOW_TSCONFIG_EXCLUDES.join(", ")} manually.`
@@ -70489,7 +70832,7 @@ function ensureAppTsconfig(projectDir) {
     );
   }
   if (changes.length === 0) return;
-  fs4.writeFileSync(tsconfigPath, JSON.stringify(parsed, null, 2) + "\n");
+  fs6.writeFileSync(tsconfigPath, JSON.stringify(parsed, null, 2) + "\n");
   console.error(`Patched tsconfig.json: ${changes.join("; ")}.`);
 }
 var LINK_TSCONFIG = ".lotics/tsconfig.link.json";
@@ -70499,15 +70842,15 @@ function writeDevLinkTsconfig(projectDir) {
   if (uiSrc) {
     paths["@lotics/ui/*"] = [`${uiSrc}/*`];
     for (const peer of readKitPeerNames(projectDir)) {
-      const typesDir = path5.join(projectDir, "node_modules", typesPackageFor(peer));
-      const runtimeDir = path5.join(projectDir, "node_modules", peer);
-      const target = fs4.existsSync(typesDir) ? `../node_modules/${typesPackageFor(peer)}` : fs4.existsSync(runtimeDir) ? `../node_modules/${peer}` : null;
+      const typesDir = path7.join(projectDir, "node_modules", typesPackageFor(peer));
+      const runtimeDir = path7.join(projectDir, "node_modules", peer);
+      const target = fs6.existsSync(typesDir) ? `../node_modules/${typesPackageFor(peer)}` : fs6.existsSync(runtimeDir) ? `../node_modules/${peer}` : null;
       if (!target) continue;
       paths[peer] = [target];
       paths[`${peer}/*`] = [`${target}/*`];
     }
   }
-  const file2 = path5.join(projectDir, ".lotics", "tsconfig.link.json");
+  const file2 = path7.join(projectDir, ".lotics", "tsconfig.link.json");
   const header = uiSrc ? `// GENERATED by \`lotics app codegen\` \u2014 do not edit.
 // LOTICS_UI_SRC is set, so @lotics/ui resolves to your working copy for tsc,
 // vitest, eslint and your editor \u2014 the same copy Vite is bundling. The peer
@@ -70518,52 +70861,52 @@ function writeDevLinkTsconfig(projectDir) {
 // LOTICS_UI_SRC is not set, so this is inert and @lotics/ui resolves from
 // node_modules as normal.
 `;
-  fs4.writeFileSync(file2, `${header}${JSON.stringify({ compilerOptions: { paths } }, null, 2)}
+  fs6.writeFileSync(file2, `${header}${JSON.stringify({ compilerOptions: { paths } }, null, 2)}
 `);
   return file2;
 }
 function writeKitTypeAugmentation(projectDir) {
   const uiSrc = process.env.LOTICS_UI_SRC;
-  const source = uiSrc ? path5.join(uiSrc, "react_native.d.ts") : path5.join(projectDir, "node_modules", "@lotics", "ui", "src", "react_native.d.ts");
-  const target = path5.join(projectDir, ".lotics", "react_native.d.ts");
-  if (!fs4.existsSync(source)) {
-    if (fs4.existsSync(target)) fs4.rmSync(target);
+  const source = uiSrc ? path7.join(uiSrc, "react_native.d.ts") : path7.join(projectDir, "node_modules", "@lotics", "ui", "src", "react_native.d.ts");
+  const target = path7.join(projectDir, ".lotics", "react_native.d.ts");
+  if (!fs6.existsSync(source)) {
+    if (fs6.existsSync(target)) fs6.rmSync(target);
     return;
   }
-  fs4.writeFileSync(
+  fs6.writeFileSync(
     target,
     `// GENERATED by \`lotics app codegen\` from @lotics/ui \u2014 do not edit.
 // The kit's web-only ViewStyle/TextStyle properties, which react-native does
 // not model. Delete any hand-copied src/react_native.d.ts; this replaces it.
-` + fs4.readFileSync(source, "utf-8")
+` + fs6.readFileSync(source, "utf-8")
   );
 }
 function typesPackageFor(peer) {
   return peer.startsWith("@") ? `@types/${peer.slice(1).replace("/", "__")}` : `@types/${peer}`;
 }
 function readKitPeerNames(projectDir) {
-  const kitPkg = path5.join(projectDir, "node_modules", "@lotics", "ui", "package.json");
-  if (!fs4.existsSync(kitPkg)) return [];
-  const parsed = JSON.parse(fs4.readFileSync(kitPkg, "utf-8"));
+  const kitPkg = path7.join(projectDir, "node_modules", "@lotics", "ui", "package.json");
+  if (!fs6.existsSync(kitPkg)) return [];
+  const parsed = JSON.parse(fs6.readFileSync(kitPkg, "utf-8"));
   const peers = parsed.peerDependencies;
   return peers && typeof peers === "object" ? Object.keys(peers) : [];
 }
 function writeAppDts(projectDir, manifest) {
-  const dotLotics = path5.join(projectDir, ".lotics");
-  fs4.mkdirSync(dotLotics, { recursive: true });
+  const dotLotics = path7.join(projectDir, ".lotics");
+  fs6.mkdirSync(dotLotics, { recursive: true });
   const written = [
-    [path5.join(dotLotics, "app_workflows.d.ts"), generateAppWorkflowsDts(manifest.workflows)],
-    [path5.join(dotLotics, "app_queries.d.ts"), generateAppQueriesDts(manifest.queries)],
-    [path5.join(dotLotics, "app_agents.d.ts"), generateAppAgentsDts(manifest.agents)]
+    [path7.join(dotLotics, "app_workflows.d.ts"), generateAppWorkflowsDts(manifest.workflows)],
+    [path7.join(dotLotics, "app_queries.d.ts"), generateAppQueriesDts(manifest.queries)],
+    [path7.join(dotLotics, "app_agents.d.ts"), generateAppAgentsDts(manifest.agents)]
   ];
-  for (const [file2, content] of written) fs4.writeFileSync(file2, content);
+  for (const [file2, content] of written) fs6.writeFileSync(file2, content);
   writeDevLinkTsconfig(projectDir);
   writeKitTypeAugmentation(projectDir);
   ensureAppTsconfig(projectDir);
   return written.map(([file2]) => file2);
 }
 function readCodegenTablesAllowlist(projectDir) {
-  const pkg2 = JSON.parse(fs4.readFileSync(path5.join(projectDir, "package.json"), "utf-8"));
+  const pkg2 = JSON.parse(fs6.readFileSync(path7.join(projectDir, "package.json"), "utf-8"));
   const tables = pkg2.lotics?.codegen?.tables;
   return Array.isArray(tables) ? tables.filter((t) => typeof t === "string") : [];
 }
@@ -70576,17 +70919,17 @@ function resolveCodegenTableIds(projectDir, queries) {
   return [...ids];
 }
 function writeAppFields(projectDir, tables) {
-  const dotLotics = path5.join(projectDir, ".lotics");
-  fs4.mkdirSync(dotLotics, { recursive: true });
-  const file2 = path5.join(dotLotics, "app_fields.ts");
-  fs4.writeFileSync(file2, generateAppFields(tables));
+  const dotLotics = path7.join(projectDir, ".lotics");
+  fs6.mkdirSync(dotLotics, { recursive: true });
+  const file2 = path7.join(dotLotics, "app_fields.ts");
+  fs6.writeFileSync(file2, generateAppFields(tables));
   return file2;
 }
 function writeBindingAppFields(projectDir, binding) {
-  const dotLotics = path5.join(projectDir, ".lotics");
-  fs4.mkdirSync(dotLotics, { recursive: true });
-  const file2 = path5.join(dotLotics, "app_fields.ts");
-  fs4.writeFileSync(file2, generatePackageAppFields(binding));
+  const dotLotics = path7.join(projectDir, ".lotics");
+  fs6.mkdirSync(dotLotics, { recursive: true });
+  const file2 = path7.join(dotLotics, "app_fields.ts");
+  fs6.writeFileSync(file2, generatePackageAppFields(binding));
   ensureAppVitestSetup(projectDir);
   return file2;
 }
@@ -70608,6 +70951,15 @@ async function writeGeneratedAppFields(client, projectDir, app, queries) {
     } else {
       const tableIds = resolveCodegenTableIds(projectDir, queries);
       const tables = await client.getWorkspaceSchema(tableIds);
+      const missing = tableIds.filter((id) => !tables.some((t) => t.id === id));
+      if (missing.length > 0) {
+        console.error(
+          `\u26A0 Skipped .lotics/app_fields.ts \u2014 ${missing.length} table(s) the app queries could not be read: ${missing.join(", ")}.
+  Writing anyway would bake a narrowed F/OPT map that compiles and then throws at runtime. Check this key's access to those tables.
+  An existing app_fields.ts is kept and still works; a project that has none yet will fail to BUILD until this resolves \u2014 which is the loud failure, not a new problem.`
+        );
+        return;
+      }
       const fieldsPath = writeAppFields(projectDir, tables);
       console.error(
         `Wrote ${fieldsPath} (baked form \u2014 bespoke; ${tables.length} table${tables.length === 1 ? "" : "s"})`
@@ -70619,7 +70971,7 @@ async function writeGeneratedAppFields(client, projectDir, app, queries) {
 }
 function warnAppFieldsUnwritten(projectDir, err2) {
   const reason = err2 instanceof Error ? err2.message : String(err2);
-  if (fs4.existsSync(path5.join(projectDir, ".lotics", "app_fields.ts"))) {
+  if (fs6.existsSync(path7.join(projectDir, ".lotics", "app_fields.ts"))) {
     console.error(`\u26A0 Could not regenerate .lotics/app_fields.ts (${reason}). Kept the existing file.`);
     return;
   }
@@ -70630,8 +70982,8 @@ function warnAppFieldsUnwritten(projectDir, err2) {
 function warnAboutDevLink(projectDir, command) {
   const uiSrc = process.env.LOTICS_UI_SRC;
   if (!uiSrc) return;
-  const viteConfigPath = path5.join(projectDir, "vite.config.ts");
-  const config2 = fs4.existsSync(viteConfigPath) ? fs4.readFileSync(viteConfigPath, "utf-8") : "";
+  const viteConfigPath = path7.join(projectDir, "vite.config.ts");
+  const config2 = fs6.existsSync(viteConfigPath) ? fs6.readFileSync(viteConfigPath, "utf-8") : "";
   const linked = config2.includes("loticsResolve") || config2.includes("LOTICS_UI_SRC");
   if (!linked) {
     console.error(
@@ -70649,19 +71001,19 @@ function warnAboutDevLink(projectDir, command) {
   }
 }
 function ensureAppVitestSetup(projectDir) {
-  const setupPath = path5.join(projectDir, VITEST_SETUP_FILENAME);
-  if (!fs4.existsSync(setupPath)) {
-    fs4.writeFileSync(setupPath, VITEST_SETUP_CONTENT);
+  const setupPath = path7.join(projectDir, VITEST_SETUP_FILENAME);
+  if (!fs6.existsSync(setupPath)) {
+    fs6.writeFileSync(setupPath, VITEST_SETUP_CONTENT);
     console.error(`Wrote ${VITEST_SETUP_FILENAME} (stubs getAppBinding so \`npm test\` collects).`);
-  } else if (!fs4.readFileSync(setupPath, "utf-8").includes("getAppBinding")) {
+  } else if (!fs6.readFileSync(setupPath, "utf-8").includes("getAppBinding")) {
     console.error(
       `\u26A0 ${VITEST_SETUP_FILENAME} exists but does not stub getAppBinding \u2014 \`npm test\` will fail to collect any test that imports the app graph (the binding-form .lotics/app_fields.ts awaits a network call). Add the stub to it:
 ${VITEST_SETUP_CONTENT}`
     );
   }
-  const viteConfigPath = path5.join(projectDir, "vite.config.ts");
-  if (!fs4.existsSync(viteConfigPath)) return;
-  const viteConfig = fs4.readFileSync(viteConfigPath, "utf-8");
+  const viteConfigPath = path7.join(projectDir, "vite.config.ts");
+  if (!fs6.existsSync(viteConfigPath)) return;
+  const viteConfig = fs6.readFileSync(viteConfigPath, "utf-8");
   if (/setupFiles\s*:/.test(viteConfig) && viteConfig.includes(VITEST_SETUP_FILENAME)) return;
   console.error(
     `\u26A0 vite.config.ts does not wire ${VITEST_SETUP_FILENAME} \u2014 \`npm test\` will fail to collect any test that imports the app graph (the binding-form .lotics/app_fields.ts awaits a network call). Add it to the \`test\` block:
@@ -70669,7 +71021,7 @@ ${VITEST_SETUP_CONTENT}`
   );
 }
 async function appCodegen(args) {
-  const projectDir = path5.resolve(args.projectDir ?? process.cwd());
+  const projectDir = path7.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
   const dtsPaths = writeAppDts(projectDir, {
     workflows: meta3.workflows,
@@ -70683,7 +71035,7 @@ async function appCodegen(args) {
   }
   for (const alias of orphanWorkflowBodies(projectDir, declared)) {
     console.error(
-      `\u26A0 ${path5.join(WORKFLOWS_DIR, `${alias}.ts`)} is not declared in package.json#lotics.workflows \u2014 'workflow check' and 'workflow set' both skip it. Declare the alias or delete the file.`
+      `\u26A0 ${path7.join(WORKFLOWS_DIR, `${alias}.ts`)} is not declared in package.json#lotics.workflows \u2014 'workflow check' and 'workflow set' both skip it. Declare the alias or delete the file.`
     );
   }
   if (!args.client) {
@@ -70734,8 +71086,8 @@ async function refreshWorkflowGlobals(client, projectDir, app_id, workflows) {
 }
 async function refreshWorkflowTypes(client, projectDir, app_id, alias, declaration) {
   const file2 = workflowFilePath(projectDir, alias);
-  if (!fs4.existsSync(file2)) return false;
-  const body = stripWorkflowHeader(fs4.readFileSync(file2, "utf-8"));
+  if (!fs6.existsSync(file2)) return false;
+  const body = stripWorkflowHeader(fs6.readFileSync(file2, "utf-8"));
   if (body.trim() === "") return false;
   const envelope = await fetchWorkflowGlobals(client, projectDir, app_id, alias, declaration);
   writeWorkflowFile(projectDir, alias, body, envelope);
@@ -70747,14 +71099,14 @@ function stampPulledManifest(projectDir, args) {
     workspace_id: args.workspace_id,
     current_version_id: args.current_version_id,
     version_number: args.version_number,
-    workflows: args.workflows,
+    workflows: toManifestWorkflows(args.workflows),
     queries: args.queries,
     // The prose is stripped here and only here: `args.agents` is the LIVE map
     // (its instructions feed `writeAgentFiles`), the manifest gets the typed half.
     agents: toManifestAgents(args.agents)
   });
   writeAppDts(projectDir, {
-    workflows: args.workflows,
+    workflows: toManifestWorkflows(args.workflows),
     queries: args.queries,
     agents: toManifestAgents(args.agents)
   });
@@ -70765,21 +71117,21 @@ async function downloadToFile(url2, destPath) {
     throw new Error(`Failed to download ${url2}: ${response.status}`);
   }
   const buffer = Buffer.from(await response.arrayBuffer());
-  fs4.writeFileSync(destPath, buffer);
+  fs6.writeFileSync(destPath, buffer);
 }
 function appDirName(name2) {
   const cleaned = name2.replace(/[/\\]+/g, "-").replace(/[<>:"|?*]/g, "").replace(/\s+/g, " ").trim().replace(/^[.\s-]+|[.\s-]+$/g, "");
   return cleaned || "app";
 }
 async function appCreate(client, args) {
-  const targetPath = path5.resolve(args.targetPath ?? appDirName(args.name));
-  if (fs4.existsSync(targetPath)) {
-    const entries2 = fs4.readdirSync(targetPath);
+  const targetPath = path7.resolve(args.targetPath ?? appDirName(args.name));
+  if (fs6.existsSync(targetPath)) {
+    const entries2 = fs6.readdirSync(targetPath);
     if (entries2.length > 0) {
       throw new Error(`Target directory ${targetPath} is not empty.`);
     }
   }
-  fs4.mkdirSync(targetPath, { recursive: true });
+  fs6.mkdirSync(targetPath, { recursive: true });
   const app = await client.createApp({ name: args.name });
   console.error(`Created app: ${app.name} (${app.id})`);
   const [uiLatest, sdkLatest] = await Promise.all([
@@ -70794,9 +71146,9 @@ async function appCreate(client, args) {
     sdk_version: sdkLatest ? `^${sdkLatest}` : void 0
   });
   for (const file2 of files) {
-    const fullPath = path5.join(targetPath, file2.path);
-    fs4.mkdirSync(path5.dirname(fullPath), { recursive: true });
-    fs4.writeFileSync(fullPath, file2.content);
+    const fullPath = path7.join(targetPath, file2.path);
+    fs6.mkdirSync(path7.dirname(fullPath), { recursive: true });
+    fs6.writeFileSync(fullPath, file2.content);
   }
   console.error(`Scaffolded ${files.length} files into ${targetPath}`);
   writeAppDts(targetPath, {});
@@ -70809,7 +71161,7 @@ async function appCreate(client, args) {
   });
   console.error(`
 Ready. Next steps:`);
-  console.error(`  cd ${path5.relative(process.cwd(), targetPath) || "."}`);
+  console.error(`  cd ${path7.relative(process.cwd(), targetPath) || "."}`);
   console.error(`  # edit src/App.tsx, then:`);
   console.error(`  lotics app deploy`);
 }
@@ -70866,11 +71218,11 @@ async function appVersions(client, args) {
   }
 }
 function defaultPullTarget(appId, appName) {
-  const cwdPkgPath = path5.join(process.cwd(), "package.json");
-  if (fs4.existsSync(cwdPkgPath)) {
+  const cwdPkgPath = path7.join(process.cwd(), "package.json");
+  if (fs6.existsSync(cwdPkgPath)) {
     let pkg2 = null;
     try {
-      pkg2 = JSON.parse(fs4.readFileSync(cwdPkgPath, "utf-8"));
+      pkg2 = JSON.parse(fs6.readFileSync(cwdPkgPath, "utf-8"));
     } catch (err2) {
       console.error(
         `\u26A0 Could not parse ${cwdPkgPath} (${err2 instanceof Error ? err2.message : String(err2)}) \u2014 pulling into a fresh ${appDirName(appName)}/ subdir.`
@@ -70889,16 +71241,20 @@ async function appPull(client, args) {
   }
   const version2 = await client.getAppVersion(app.id, app.current_version_id);
   const sourceUrl = await client.getAppVersionSourceUrl(app.id, version2.id);
-  const targetPath = path5.resolve(args.targetPath ?? defaultPullTarget(app.id, app.name));
-  fs4.mkdirSync(targetPath, { recursive: true });
-  const tmpFile = path5.join(tmpdir(), `lotics-app-${app.id}-${Date.now()}.tar.gz`);
+  const targetPath = path7.resolve(args.targetPath ?? defaultPullTarget(app.id, app.name));
+  fs6.mkdirSync(targetPath, { recursive: true });
+  const tmpFile = path7.join(tmpdir(), `lotics-app-${app.id}-${Date.now()}.tar.gz`);
   console.error(`Downloading source archive...`);
   await downloadToFile(sourceUrl, tmpFile);
+  const keptLocal = [];
+  const stagingDir = fs6.mkdtempSync(path7.join(tmpdir(), `lotics-pull-${app.id}-`));
   try {
+    await runTar(["-xzf", tmpFile, "-C", stagingDir], stagingDir);
     console.error(`Extracting to ${targetPath}...`);
-    await runTar(["-xzf", tmpFile, "-C", targetPath], targetPath);
+    keptLocal.push(...copyTree(stagingDir, targetPath, { overwrite: args.force === true }));
   } finally {
-    if (fs4.existsSync(tmpFile)) fs4.unlinkSync(tmpFile);
+    if (fs6.existsSync(tmpFile)) fs6.unlinkSync(tmpFile);
+    fs6.rmSync(stagingDir, { recursive: true, force: true });
   }
   stampPulledManifest(targetPath, {
     app_id: app.id,
@@ -70909,6 +71265,10 @@ async function appPull(client, args) {
     queries: app.queries ?? {},
     agents: app.agents ?? {}
   });
+  for (const [alias, declaration] of Object.entries(app.queries ?? {})) {
+    const sha = declarationSha(declaration);
+    writeSynced(targetPath, "queries", alias, { content: sha, live: sha });
+  }
   await writeGeneratedAppFields(
     client,
     targetPath,
@@ -70917,7 +71277,10 @@ async function appPull(client, args) {
   );
   const workflows = app.workflows ?? {};
   if (Object.keys(workflows).length > 0) {
-    const written = await writeWorkflowFiles(client, targetPath, app.id, app.name, workflows);
+    const written = await writeWorkflowFiles(client, targetPath, app.id, app.name, workflows, {
+      overwrite: args.force === true,
+      kept: keptLocal
+    });
     if (written.length > 0) {
       console.error(
         `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/ (${written.join(", ")})`
@@ -70926,7 +71289,16 @@ async function appPull(client, args) {
   }
   const agents = app.agents ?? {};
   if (Object.keys(agents).length > 0) {
-    const written = writeAgentFiles(targetPath, agents);
+    const written = writeAgentFiles(targetPath, agents, {
+      overwrite: args.force === true,
+      kept: keptLocal
+    });
+    for (const alias of written) {
+      const instructions = agents[alias]?.instructions;
+      if (instructions === void 0) continue;
+      const sha = contentSha(instructions);
+      writeSynced(targetPath, "agents", alias, { content: sha, live: sha });
+    }
     if (written.length > 0) {
       console.error(
         `Wrote ${written.length} agent instruction ${written.length === 1 ? "file" : "files"} to ${AGENTS_DIR}/ (${written.join(", ")})`
@@ -70935,62 +71307,69 @@ async function appPull(client, args) {
   }
   console.error(`Installing npm dependencies...`);
   await runNpm(["install"], targetPath);
+  reportKeptLocalFiles(keptLocal, app.id);
   console.error(`
 Ready. Next steps:`);
-  console.error(`  cd ${path5.relative(process.cwd(), targetPath) || "."}`);
+  console.error(`  cd ${path7.relative(process.cwd(), targetPath) || "."}`);
   console.error(`  # edit src/App.tsx`);
   console.error(`  lotics app deploy`);
 }
 function readAppSourceText(projectDir) {
-  const srcDir = path5.join(projectDir, "src");
-  if (!fs4.existsSync(srcDir)) return "";
+  const srcDir = path7.join(projectDir, "src");
+  if (!fs6.existsSync(srcDir)) return "";
   const parts = [];
   const walk2 = (dir) => {
-    for (const entry of fs4.readdirSync(dir, { withFileTypes: true })) {
-      const full = path5.join(dir, entry.name);
+    for (const entry of fs6.readdirSync(dir, { withFileTypes: true })) {
+      const full = path7.join(dir, entry.name);
       if (entry.isDirectory()) walk2(full);
-      else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) parts.push(fs4.readFileSync(full, "utf8"));
+      else if (/\.(ts|tsx|js|jsx)$/.test(entry.name)) parts.push(fs6.readFileSync(full, "utf8"));
     }
   };
   walk2(srcDir);
   return parts.join("\n");
 }
 async function appDeploy(client, args) {
-  const projectDir = path5.resolve(args.projectDir ?? process.cwd());
+  const projectDir = path7.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
   warnAboutDevLink(projectDir, "deploy");
   const liveApp = await client.getApp(meta3.app_id);
-  const divergences = agentTypeDivergences(meta3.agents, liveApp.agents);
-  if (divergences.length > 0) {
-    console.error(
-      `
-Refusing to deploy \u2014 package.json#lotics.agents disagrees with the live app:
-` + divergences.map((d) => `  \u2022 ${d}`).join("\n") + `
-
-  lotics.agents is a REFLECTION of the app, not an authoring surface, but it is what
-  types useAgentRun \u2014 so this build was checked against an agent that does not exist.
-  To take the app's shape:      lotics app codegen   (refreshes the block + the types)
-  To CHANGE the agent instead:  lotics run set_app_agent '{"app_id":"${meta3.app_id}","alias":"\u2026","outputs":{\u2026}}'
-                                (send only what changes \u2014 the server merges), then codegen.`
-    );
-    process.exit(1);
+  const pending = pendingBindings({
+    projectDir,
+    meta: meta3,
+    synced: readSynced(projectDir).workflows,
+    live: liveApp
+  });
+  if (!nothingPending(pending)) {
+    await pushPendingBindings(client, projectDir, pending);
   }
   const sourceText = readAppSourceText(projectDir);
   const called = calledAppAliases(sourceText);
-  warnIfAgentProseDiffers(projectDir, liveApp.agents);
   warnIfDynamicAliases(called);
   warnIfUndeclaredCapabilities(sourceText, meta3.capabilities);
   writeAppDts(projectDir, { workflows: meta3.workflows, queries: meta3.queries, agents: meta3.agents });
+  try {
+    await writeGeneratedAppFields(
+      client,
+      projectDir,
+      { app_id: meta3.app_id, package_id: liveApp.package_id },
+      meta3.queries ?? {}
+    );
+  } catch (err2) {
+    console.error(
+      `\u26A0 Could not regenerate .lotics/app_fields.ts (${err2.message}).
+  The build will use whatever is on disk \u2014 run 'lotics app codegen' if this app is published.`
+    );
+  }
   console.error("Building...");
   await runNpm(["run", "build"], projectDir);
-  const distDir = path5.join(projectDir, "dist");
-  if (!fs4.existsSync(distDir)) {
+  const distDir = path7.join(projectDir, "dist");
+  if (!fs6.existsSync(distDir)) {
     throw new Error(
       `Build did not produce a dist/ directory in ${projectDir}. Check that 'npm run build' is configured correctly (Vite/etc. defaults to dist/).`
     );
   }
-  const tmpSource = path5.join(tmpdir(), `lotics-source-${Date.now()}.tar.gz`);
-  const tmpDist = path5.join(tmpdir(), `lotics-dist-${Date.now()}.tar.gz`);
+  const tmpSource = path7.join(tmpdir(), `lotics-source-${Date.now()}.tar.gz`);
+  const tmpDist = path7.join(tmpdir(), `lotics-dist-${Date.now()}.tar.gz`);
   try {
     console.error("Packaging source...");
     await runTar(
@@ -71014,10 +71393,10 @@ Refusing to deploy \u2014 package.json#lotics.agents disagrees with the live app
       const result = await client.deployAppVersion({
         queries: liveQueries,
         app_id: meta3.app_id,
-        source_archive: fs4.readFileSync(tmpSource),
-        dist_archive: fs4.readFileSync(tmpDist),
+        source_archive: fs6.readFileSync(tmpSource),
+        dist_archive: fs6.readFileSync(tmpDist),
         prev_version_id: meta3.current_version_id,
-        message: args.message,
+        message: args.message ?? derivedDeployMessage(pending),
         // Capabilities ARE manifest-authoritative: always send,
         // defaulting to `{}` when the manifest declares none — so deleting the
         // `capabilities` block turns every capability OFF on the next deploy
@@ -71032,7 +71411,8 @@ Refusing to deploy \u2014 package.json#lotics.agents disagrees with the live app
         // with whatever the author last remembered to write. Stop calling an
         // alias + redeploy to lift the guard before removing its binding.
         workflow_aliases: called.workflows,
-        query_aliases: called.queries
+        query_aliases: called.queries,
+        agent_aliases: called.agents
       });
       writeAppMeta(projectDir, {
         ...meta3,
@@ -71041,14 +71421,24 @@ Refusing to deploy \u2014 package.json#lotics.agents disagrees with the live app
       });
       console.error(`Deployed v${result.version_number} (${result.version_id})`);
       console.error(`Bundle size: ${(result.bundle_size_bytes / 1024).toFixed(1)} KB`);
+      let liveAfter;
       try {
-        const app = await client.getApp(meta3.app_id);
-        warnIfUnbranded(app);
-        warnIfUnboundAliases(app, called);
-        warnIfQueriesDiffer(app, meta3.queries ?? {});
+        liveAfter = await client.getApp(meta3.app_id);
       } catch (err2) {
         console.error(`(skipped post-deploy checks: ${err2.message})`);
       }
+      if (liveAfter) {
+        warnIfUnbranded(liveAfter);
+        warnIfUnboundAliases(liveAfter, called);
+      }
+      if (liveAfter) {
+        await pruneOrphanedBindings(
+          client,
+          meta3.app_id,
+          orphanedBindings(called, liveAfter),
+          called.dynamic
+        );
+      }
     } catch (err2) {
       const e = err2;
       if (e.code === "VERSION_CONFLICT") {
@@ -71060,8 +71450,8 @@ Refusing to deploy \u2014 package.json#lotics.agents disagrees with the live app
       throw err2;
     }
   } finally {
-    if (fs4.existsSync(tmpSource)) fs4.unlinkSync(tmpSource);
-    if (fs4.existsSync(tmpDist)) fs4.unlinkSync(tmpDist);
+    if (fs6.existsSync(tmpSource)) fs6.unlinkSync(tmpSource);
+    if (fs6.existsSync(tmpDist)) fs6.unlinkSync(tmpDist);
   }
 }
 function warnIfUnbranded(app) {
@@ -71088,54 +71478,233 @@ async function readLiveQueries(client, appId) {
     process.exit(1);
   }
 }
-function warnIfQueriesDiffer(app, manifest) {
-  const drifted = driftedQueryAliases(manifest, app.queries);
-  if (drifted.length === 0) return;
-  console.error(
-    `
-\u26A0 ${drifted.length} quer${drifted.length === 1 ? "y" : "ies"} in package.json differ from the app: ${drifted.join(", ")}
-  A deploy does not write them. Push yours with 'lotics app query set --all'
-  (or one alias at a time), or adopt the app's with 'lotics app pull'.`
-  );
-}
 async function appCheck(client, args = {}) {
-  const projectDir = path5.resolve(args.projectDir ?? process.cwd());
+  const projectDir = path7.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
   const app = await client.getApp(meta3.app_id);
   const sourceText = readAppSourceText(projectDir);
   const called = calledAppAliases(sourceText);
-  const divergences = agentTypeDivergences(meta3.agents, app.agents);
-  for (const d of divergences) {
-    console.error(`\u2717 package.json#lotics.agents.${d}`);
-  }
-  if (divergences.length > 0) {
-    console.error(
-      `  A deploy REFUSES this: the bundle would be typed against an agent that does not exist.
-  Take the app's shape with 'lotics app pull ${meta3.app_id}', or change the agent with set_app_agent.`
-    );
-  }
   warnAboutDevLink(projectDir, "deploy");
-  warnIfAgentProseDiffers(projectDir, app.agents);
+  warnAboutOrphanedBindings(called, app);
+  const pending = pendingBindings({
+    projectDir,
+    meta: meta3,
+    synced: readSynced(projectDir).workflows,
+    live: app
+  });
+  reportPending(pending);
   warnIfDynamicAliases(called);
   warnIfUndeclaredCapabilities(sourceText, meta3.capabilities);
   warnIfUnboundAliases(app, called);
-  warnIfQueriesDiffer(app, meta3.queries ?? {});
   warnIfUnbranded(app);
-  if (divergences.length > 0) process.exit(1);
+  if (!nothingPending(pending)) {
+    process.exit(1);
+  }
   console.error("Checked the app's bindings, capabilities and agent schemas \u2014 nothing blocking.");
 }
-function warnIfAgentProseDiffers(projectDir, liveAgents) {
+async function pushPendingBindings(client, projectDir, pending) {
+  const plan = [
+    ...pending.queries.map((alias) => `query ${alias}`),
+    ...pending.workflows.map((alias) => `workflow ${alias}`),
+    ...pending.agents.map((alias) => `agent ${alias}`)
+  ];
+  console.error(
+    `
+Pushing ${plan.length} binding${plan.length === 1 ? "" : "s"} ahead of the app: ${plan.join(", ")}`
+  );
+  for (const alias of pending.queries) {
+    await appQuerySet(client, { alias, projectDir });
+  }
+  for (const alias of pending.workflows) {
+    await appWorkflowSet(client, { alias, projectDir });
+  }
+  for (const alias of pending.agents) {
+    await appAgentSet(client, { alias, projectDir });
+  }
+}
+function pendingBindings(args) {
+  const { projectDir, meta: meta3, synced, live } = args;
+  const workflows = /* @__PURE__ */ new Set([
+    ...workflowBodyDrift(projectDir, meta3.workflows, synced),
+    ...divergedWorkflowAliases(meta3.workflows, live.workflows)
+  ]);
+  return {
+    workflows: [...workflows].sort(),
+    agents: [
+      .../* @__PURE__ */ new Set([
+        ...driftedAgentAliases(projectDir, live.agents),
+        // A manifest declaration that disagrees with the live row is a push now,
+        // the same as a workflow's. `agentTypeDivergences` renders one line per
+        // (alias, key) for a human, and the alias is its first token — but an
+        // alias that diverged on both `inputs` and `outputs` still needs exactly
+        // one push.
+        ...divergedAgentAliases(meta3.agents, live.agents)
+      ])
+    ].sort(),
+    // Only aliases the manifest DECLARES. `driftedQueryAliases` is symmetric —
+    // it unions both key sets — so an alias deleted locally but still bound live
+    // reads as drift, and queueing it sends the author to a push that refuses
+    // ("declare it first") for a declaration they deliberately removed. A
+    // deletion is not a push, and this detector only decides what to push;
+    // unbinding is `remove_app_query`, which no deploy runs for any artifact.
+    queries: [...driftedQueryAliases(meta3.queries ?? {}, live.queries)].filter((alias) => (meta3.queries ?? {})[alias] !== void 0).sort()
+  };
+}
+function reportPending(pending) {
+  const lines = [
+    ...pending.workflows.map((a) => `  \u2022 workflow "${a}" \u2014 lotics app workflow set ${a}`),
+    ...pending.agents.map((a) => `  \u2022 agent "${a}" \u2014 lotics app agent set ${a}`),
+    ...pending.queries.map((a) => `  \u2022 query "${a}" \u2014 lotics app query set ${a}`)
+  ];
+  if (lines.length === 0) return;
+  console.error(
+    `
+\u2717 ${lines.length} binding${lines.length === 1 ? " is" : "s are"} ahead of the app:
+` + lines.join("\n") + `
+
+  A version shipped now would not reproduce what runs. 'lotics app deploy' pushes
+  these for you; revert the file instead to drop the edit.`
+  );
+}
+function nothingPending(pending) {
+  return pending.workflows.length === 0 && pending.agents.length === 0 && pending.queries.length === 0;
+}
+function divergedAgentAliases(manifestAgents, liveAgents) {
+  const out = [];
+  for (const [alias, declared] of Object.entries(manifestAgents ?? {})) {
+    const live = (liveAgents ?? {})[alias];
+    if (!live) continue;
+    if (AGENT_TYPED_KEYS.some((key) => !sameSchema(declared[key], live[key]))) out.push(alias);
+  }
+  return out;
+}
+function driftedAgentAliases(projectDir, liveAgents) {
+  const drifted = [];
   for (const [alias, live] of Object.entries(liveAgents ?? {})) {
     const file2 = agentFilePath2(projectDir, alias);
-    if (!fs4.existsSync(file2)) continue;
-    const local = stripAgentHeader(fs4.readFileSync(file2, "utf-8"));
+    if (!fs6.existsSync(file2)) continue;
+    const local = stripAgentHeader(fs6.readFileSync(file2, "utf-8"));
     if (local === "" || local === (live.instructions ?? "")) continue;
+    drifted.push(alias);
+  }
+  return drifted.sort();
+}
+function divergedWorkflowAliases(manifestWorkflows, liveWorkflows) {
+  return [
+    ...new Set(workflowTypeDivergences(manifestWorkflows, liveWorkflows).map((d) => d.alias))
+  ].sort();
+}
+function orphanedBindings(called, live) {
+  const agentDeclarations = Object.values(live.agents ?? {});
+  const referenced = {
+    queries: [...called.queries, ...agentDeclarations.flatMap((a) => a.query_aliases ?? [])],
+    workflows: [...called.workflows, ...agentDeclarations.flatMap((a) => a.workflow_aliases ?? [])],
+    // Nothing declares an agent but the client bundle — an agent cannot run another.
+    agents: called.agents
+  };
+  return orphanedAliases(
+    {
+      queries: Object.keys(live.queries ?? {}),
+      workflows: Object.keys(live.workflows ?? {}),
+      agents: Object.keys(live.agents ?? {})
+    },
+    referenced
+  );
+}
+function warnAboutOrphanedBindings(called, live) {
+  const orphans = orphanedBindings(called, live);
+  const lines = [
+    ...orphans.queries.map((a) => `  \u2022 query ${a}`),
+    ...orphans.workflows.map((a) => `  \u2022 workflow ${a}`),
+    ...orphans.agents.map((a) => `  \u2022 agent ${a}`)
+  ];
+  if (lines.length === 0) return 0;
+  console.error(
+    `
+\u26A0 ${lines.length} binding(s) are live but named nowhere in this bundle:
+` + lines.join("\n") + (called.dynamic.length > 0 ? `
+
+  This app computes an alias at runtime, so one of these may be called after
+  all \u2014 a deploy therefore leaves them ALL in place. Make those call sites
+  literal and a deploy will clean them up.` : `
+
+  A deploy unbinds these after it ships.`)
+  );
+  return lines.length;
+}
+async function pruneOrphanedBindings(client, appId, orphans, dynamic) {
+  const targets = [
+    ...orphans.queries.map((alias) => ({ tool: "remove_app_query", alias, label: `query ${alias}` })),
+    ...orphans.workflows.map((alias) => ({
+      tool: "remove_app_workflow",
+      alias,
+      label: `workflow ${alias}`
+    })),
+    ...orphans.agents.map((alias) => ({ tool: "remove_app_agent", alias, label: `agent ${alias}` }))
+  ];
+  if (targets.length === 0) return 0;
+  if (dynamic.length > 0) {
     console.error(
       `
-\u26A0 ${path5.relative(projectDir, file2)} differs from the live agent's instructions.
-  A deploy does not push prose. Send it with 'lotics app agent set ${alias}'.`
+\u26A0 Left ${targets.length} unused binding(s) in place: this app calls ${dynamic.join(" / ")} with an alias it computes at runtime, and a static scan cannot tell which binding that reaches \u2014 so any of these may be live:
+` + targets.map((t) => `    \u2022 ${t.label}`).join("\n") + `
+  Make those call sites literal and the next deploy will clean them up, or remove the ones you know are dead by hand.`
     );
+    return targets.length;
+  }
+  let failed = 0;
+  for (const target of targets) {
+    const res = await client.execute(target.tool, { app_id: appId, alias: target.alias });
+    if (res.error) {
+      failed += 1;
+      console.error(`  \u2717 could not unbind ${target.label} \u2014 ${res.error}`);
+      continue;
+    }
+    console.error(`  \u2713 unbound ${target.label}`);
   }
+  return failed;
+}
+function derivedDeployMessage(pending) {
+  const parts = [
+    ...pending.queries.map((a) => `query ${a}`),
+    ...pending.workflows.map((a) => `workflow ${a}`),
+    ...pending.agents.map((a) => `agent ${a}`)
+  ];
+  return parts.length === 0 ? "Deployed app code" : `Deployed app code; pushed ${parts.join(", ")}`;
+}
+function copyTree(from, to, opts, relative = "") {
+  const kept = [];
+  for (const entry of fs6.readdirSync(from, { withFileTypes: true })) {
+    const src = path7.join(from, entry.name);
+    const dest = path7.join(to, entry.name);
+    const rel = path7.join(relative, entry.name);
+    if (entry.isDirectory()) {
+      fs6.mkdirSync(dest, { recursive: true });
+      kept.push(...copyTree(src, dest, opts, rel));
+      continue;
+    }
+    if (!opts.overwrite && fs6.existsSync(dest)) {
+      if (fs6.readFileSync(src).equals(fs6.readFileSync(dest))) continue;
+      kept.push(rel);
+      continue;
+    }
+    fs6.copyFileSync(src, dest);
+  }
+  return kept;
+}
+function reportKeptLocalFiles(kept, appId) {
+  if (kept.length === 0) return;
+  console.error(
+    `
+${kept.length} local file(s) differ from the app and were KEPT, not overwritten:
+` + kept.slice(0, 20).map((f) => `  \u2022 ${f}`).join("\n") + (kept.length > 20 ? `
+  \u2026 and ${kept.length - 20} more` : ``) + `
+
+  Everything else was refreshed from the app. Your edits are intact.
+  Ship them:            lotics app deploy      (pushes bodies, prompts and declarations)
+  See the difference:   lotics app check
+  Take the app's copy:  lotics app pull ${appId} --force   (DISCARDS the files above)`
+  );
 }
 function warnIfDynamicAliases(called) {
   if (called.dynamic.length === 0) return;
@@ -71179,7 +71748,7 @@ function warnIfUnboundAliases(app, called) {
   console.error(lines.join("\n"));
 }
 async function appDev(client, args) {
-  const projectDir = path5.resolve(args.projectDir ?? process.cwd());
+  const projectDir = path7.resolve(args.projectDir ?? process.cwd());
   const meta3 = readAppMeta(projectDir);
   warnAboutDevLink(projectDir, "dev");
   writeAppDts(projectDir, { workflows: meta3.workflows, queries: meta3.queries, agents: meta3.agents });
@@ -71350,11 +71919,11 @@ var AGENT_RUN_POLL = {
   existenceTimeoutMs: 5e3
 };
 var sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
-async function fetchSettledAgentRun(client, appId, sessionId, runId, timing) {
+async function fetchSettledAgentRun(client, appId, sessionId2, runId, timing) {
   const settleDeadline = Date.now() + timing.settleTimeoutMs;
   const existenceDeadline = Date.now() + timing.existenceTimeoutMs;
   for (; ; ) {
-    const { runs } = await client.listAgentRuns(appId, sessionId);
+    const { runs } = await client.listAgentRuns(appId, sessionId2);
     const target = runId ? runs.find((r) => r.id === runId) : runs[runs.length - 1];
     if (target) {
       if (target.status !== "running" || Date.now() >= settleDeadline) return target;
@@ -71365,20 +71934,20 @@ async function fetchSettledAgentRun(client, appId, sessionId, runId, timing) {
   }
 }
 async function appAgentRun(client, args, timing = AGENT_RUN_POLL) {
-  const sessionId = args.sessionId ?? `cli-${randomUUID()}`;
+  const sessionId2 = args.sessionId ?? `cli-${randomUUID()}`;
   const continuing = args.sessionId !== void 0;
   const res = await client.appAgentRunStream(args.app_id, args.alias, {
-    session_id: sessionId,
+    session_id: sessionId2,
     input: args.input
   });
   const runId = res.headers.get("x-app-agent-run-id") ?? void 0;
   if (res.body) {
     await streamAgentTextDeltas(res.body, (piece) => process.stderr.write(piece));
   }
-  const run = await fetchSettledAgentRun(client, args.app_id, sessionId, runId, timing);
+  const run = await fetchSettledAgentRun(client, args.app_id, sessionId2, runId, timing);
   if (!run) {
     console.error(`
-Could not find the settled run for session ${sessionId} on ${args.app_id}.`);
+Could not find the settled run for session ${sessionId2} on ${args.app_id}.`);
     console.error("The run may still be in progress \u2014 re-check with `lotics run` against the app's agent-runs.");
     process.exit(1);
   }
@@ -71394,13 +71963,14 @@ Could not find the settled run for session ${sessionId} on ${args.app_id}.`);
 Agent "${args.alias}" run ${run.id} \u2192 ${run.status}${run.error_message ? `: ${run.error_message}` : ""}`
   );
   console.error(
-    continuing ? `Session: ${sessionId}` : `Session: ${sessionId}  (fresh \u2014 pass --session ${sessionId} to continue this thread)`
+    continuing ? `Session: ${sessionId2}` : `Session: ${sessionId2}  (fresh \u2014 pass --session ${sessionId2} to continue this thread)`
   );
   if (run.status !== "completed") process.exit(1);
 }
 async function appAgentSet(client, args) {
-  const projectDir = process.cwd();
+  const projectDir = args.projectDir ?? process.cwd();
   const meta3 = readAppMeta(projectDir);
+  noteScope({ alias: args.alias });
   const app = await client.getApp(meta3.app_id);
   const live = app.agents?.[args.alias];
   if (!live) {
@@ -71409,31 +71979,51 @@ async function appAgentSet(client, args) {
     );
     process.exit(1);
   }
+  const declared = meta3.agents?.[args.alias];
+  const hasDeclaration = declared?.inputs !== void 0 || declared?.outputs !== void 0;
   const file2 = agentFilePath2(projectDir, args.alias);
-  if (!fs4.existsSync(file2)) {
+  if (!fs6.existsSync(file2) && !hasDeclaration) {
     console.error(
-      `No instructions at ${path5.relative(projectDir, file2)}. Run 'lotics app pull ${meta3.app_id}' to write ${AGENTS_DIR}/${args.alias}.md, then edit it.`
+      `No instructions at ${path7.relative(projectDir, file2)}, and nothing declared in package.json#lotics.agents.${args.alias} to push instead.
+  Run 'lotics app pull ${meta3.app_id}' to write ${AGENTS_DIR}/${args.alias}.md, then edit it.`
     );
     process.exit(1);
   }
-  const instructions = stripAgentHeader(fs4.readFileSync(file2, "utf-8"));
+  const instructions = fs6.existsSync(file2) ? stripAgentHeader(fs6.readFileSync(file2, "utf-8")) : void 0;
   if (instructions === "") {
     console.error(
-      `${path5.relative(projectDir, file2)} is empty after stripping the header \u2014 refusing to push an empty prompt.`
+      `${path7.relative(projectDir, file2)} is empty after stripping the header \u2014 refusing to push an empty prompt.`
     );
     process.exit(1);
   }
-  const res = await client.setAppAgent(meta3.app_id, args.alias, { instructions });
+  const proseBaseline = readSynced(projectDir).agents[args.alias]?.live;
+  const res = await client.setAppAgent(meta3.app_id, args.alias, {
+    // Prose and its precondition ride together. Gating a declaration-only push on
+    // the prose baseline would refuse it because someone edited a PROMPT — a
+    // precondition must guard what this call actually writes.
+    ...instructions !== void 0 ? { instructions, ...proseBaseline ? { expected_instructions_sha: proseBaseline } : {} } : {},
+    ...declared?.inputs !== void 0 ? { inputs: declared.inputs } : {},
+    ...declared?.outputs !== void 0 ? { outputs: declared.outputs } : {}
+  });
   if (res.error) {
     console.error(`Failed to set agent "${args.alias}": ${res.error}`);
     process.exit(1);
   }
+  if (instructions !== void 0) {
+    const proseSha = contentSha(instructions);
+    writeSynced(projectDir, "agents", args.alias, { content: proseSha, live: proseSha });
+  }
+  const pushed = [
+    ...instructions !== void 0 ? [`${instructions.length} chars of instructions`] : [],
+    ...declared?.inputs !== void 0 ? ["inputs"] : [],
+    ...declared?.outputs !== void 0 ? ["outputs"] : []
+  ];
   console.error(
-    `Set agent "${args.alias}" (${instructions.length} chars of instructions` + (live.model_tier ? `, ${live.model_tier}` : "") + `). Typed fields left as they are.`
+    `Set agent "${args.alias}" (${pushed.join(", ")}` + (live.model_tier ? `, ${live.model_tier}` : "") + `). Everything else left as it is.`
   );
 }
 async function appWorkflowSet(client, args) {
-  const projectDir = process.cwd();
+  const projectDir = args.projectDir ?? process.cwd();
   const meta3 = readAppMeta(projectDir);
   const declaration = meta3.workflows?.[args.alias];
   if (!declaration) {
@@ -71443,15 +72033,18 @@ async function appWorkflowSet(client, args) {
     process.exit(1);
   }
   const file2 = workflowFilePath(projectDir, args.alias);
-  if (!fs4.existsSync(file2)) {
+  if (!fs6.existsSync(file2)) {
     console.error(
-      `No workflow body at ${path5.relative(projectDir, file2)}. Run 'lotics app pull ${meta3.app_id}' to write src/workflows/${args.alias}.ts, then edit it.`
+      `No workflow body at ${path7.relative(projectDir, file2)}.
+  If "${args.alias}" is already bound:  lotics app pull ${meta3.app_id}   (writes the body)
+  If it is a NEW alias you declared:    create that file yourself, then re-run this.`
     );
     process.exit(1);
   }
-  const source = stripWorkflowHeader(fs4.readFileSync(file2, "utf-8"));
+  noteScope({ alias: args.alias });
+  const source = stripWorkflowHeader(fs6.readFileSync(file2, "utf-8"));
   if (source.trim() === "") {
-    console.error(`Workflow body ${path5.relative(projectDir, file2)} is empty after stripping the header.`);
+    console.error(`Workflow body ${path7.relative(projectDir, file2)} is empty after stripping the header.`);
     process.exit(1);
   }
   const res = await client.setAppWorkflow(meta3.app_id, args.alias, {
@@ -71465,12 +72058,21 @@ async function appWorkflowSet(client, args) {
     // `Workflow invoked by app "X" via useWorkflow("y")`. Absent leaves
     // whatever is on the row, so this can never blank a description set
     // elsewhere.
-    description: declaration.description
+    description: declaration.description,
+    // The body this edit was built on. Turns the push into a conditional write:
+    // if the live body moved since this project last saw it, the server refuses
+    // rather than letting this copy overwrite a change nobody here has seen.
+    expected_body_sha: readSynced(projectDir).workflows[args.alias]?.live
   });
   if (res.error) {
     console.error(`Failed to set workflow "${args.alias}": ${res.error}`);
     process.exit(1);
   }
+  const pushedBodySha = res.result !== null && typeof res.result === "object" ? res.result.body_sha : void 0;
+  writeSynced(projectDir, "workflows", args.alias, {
+    content: contentSha(source),
+    ...typeof pushedBodySha === "string" ? { live: pushedBodySha } : {}
+  });
   const result = res.result ?? {};
   const workflowId = typeof result.workflow_id === "string" ? result.workflow_id : "(unknown)";
   console.error(`Set workflow "${args.alias}" \u2192 ${workflowId}`);
@@ -71490,10 +72092,11 @@ async function appWorkflowSet(client, args) {
   }
 }
 async function appQuerySet(client, args) {
-  const projectDir = process.cwd();
+  const projectDir = args.projectDir ?? process.cwd();
   const meta3 = readAppMeta(projectDir);
   const declared = meta3.queries ?? {};
   const aliases = "all" in args ? Object.keys(declared).sort() : [args.alias];
+  if (!("all" in args)) noteScope({ alias: args.alias });
   if (aliases.length === 0) {
     console.error("No queries in package.json#lotics.queries \u2014 nothing to push.");
     return;
@@ -71507,19 +72110,26 @@ async function appQuerySet(client, args) {
       );
       process.exit(1);
     }
-    const res = await client.setAppQuery(meta3.app_id, alias, declaration);
+    const res = await client.setAppQuery(
+      meta3.app_id,
+      alias,
+      declaration,
+      readSynced(projectDir).queries[alias]?.live
+    );
     if (res.error) {
       if (pushed.length > 0) console.error(`Pushed before the failure: ${pushed.join(", ")}.`);
       console.error(`Failed to set query "${alias}": ${res.error}`);
       process.exit(1);
     }
+    const querySha = declarationSha(declaration);
+    writeSynced(projectDir, "queries", alias, { content: querySha, live: querySha });
     pushed.push(alias);
   }
   console.error(
     `Set ${pushed.length} quer${pushed.length === 1 ? "y" : "ies"} on ${meta3.app_id}: ${pushed.join(", ")}.`
   );
 }
-async function appWorkflowPull(client) {
+async function appWorkflowPull(client, args = {}) {
   const projectDir = process.cwd();
   const meta3 = readAppMeta(projectDir);
   const app = await client.getApp(meta3.app_id);
@@ -71528,10 +72138,15 @@ async function appWorkflowPull(client) {
     console.error(`App ${meta3.app_id} has no bound workflows.`);
     return;
   }
-  const written = await writeWorkflowFiles(client, projectDir, meta3.app_id, app.name, workflows);
+  const kept = [];
+  const written = await writeWorkflowFiles(client, projectDir, meta3.app_id, app.name, workflows, {
+    overwrite: args.force === true,
+    kept
+  });
   console.error(
     `Wrote ${written.length} workflow ${written.length === 1 ? "body" : "bodies"} to ${WORKFLOWS_DIR}/` + (written.length > 0 ? ` (${written.join(", ")})` : "")
   );
+  reportKeptLocalFiles(kept, meta3.app_id);
   ensureAppTsconfig(projectDir);
 }
 async function appWorkflowCheck(args) {
@@ -71558,15 +72173,15 @@ async function appWorkflowCheck(args) {
   for (const alias of aliases) {
     const bodyPath = workflowFilePath(projectDir, alias);
     const globalsPath = workflowGlobalsPath(projectDir, alias);
-    if (!fs4.existsSync(bodyPath)) {
+    if (!fs6.existsSync(bodyPath)) {
       console.error(
-        `\u26A0 Skipped "${alias}" \u2014 no body at ${path5.relative(projectDir, bodyPath)}. Run 'lotics app workflow pull' to write it.`
+        `\u26A0 Skipped "${alias}" \u2014 no body at ${path7.relative(projectDir, bodyPath)}. Run 'lotics app workflow pull' to write it.`
       );
       continue;
     }
-    if (!fs4.existsSync(globalsPath)) {
+    if (!fs6.existsSync(globalsPath)) {
       console.error(
-        `Cannot check "${alias}" \u2014 missing types at ${path5.relative(projectDir, globalsPath)}. Run 'lotics app workflow pull' (or 'lotics app codegen') to fetch them.`
+        `Cannot check "${alias}" \u2014 missing types at ${path7.relative(projectDir, globalsPath)}. Run 'lotics app workflow pull' (or 'lotics app codegen') to fetch them.`
       );
       process.exit(1);
     }
@@ -71585,7 +72200,7 @@ async function appWorkflowCheck(args) {
 function printWorkflowCheckResults(projectDir, results) {
   let totalErrors = 0;
   for (const r of results) {
-    const rel = path5.relative(projectDir, r.bodyPath);
+    const rel = path7.relative(projectDir, r.bodyPath);
     if (r.issues.length === 0) {
       console.error(`\u2713 ${r.alias} (${rel}) \u2014 clean`);
       continue;
@@ -71614,6 +72229,7 @@ ${totalErrors} error${totalErrors === 1 ? "" : "s"} across ${results.length - pa
 function parseArgs(argv) {
   const flags = {
     json: false,
+    force: false,
     timeout: void 0,
     output: void 0,
     as: void 0,
@@ -71646,6 +72262,9 @@ function parseArgs(argv) {
       case "--json":
         flags.json = true;
         break;
+      case "--force":
+        flags.force = true;
+        break;
       case "--timeout":
         flags.timeout = parseInt(argv[++i2], 10);
         break;
@@ -71789,11 +72408,11 @@ async function validateOrgWorkspacePin(client, orgId, profile) {
 }
 
 // src/xlsx.ts
-import fs6 from "node:fs";
+import fs8 from "node:fs";
 
 // src/file_command_io.ts
-import fs5 from "node:fs";
-import path6 from "node:path";
+import fs7 from "node:fs";
+import path8 from "node:path";
 var CliError = class extends Error {
   constructor(message2) {
     super(message2);
@@ -71814,14 +72433,14 @@ function rejectExtraArgs(rest2, arity, usage) {
   fail2(`${usage} takes ${arity} argument${arity === 1 ? "" : "s"} after <file>, got ${rest2.length}. Unused: ${rest2.slice(arity).join(" ")}`);
 }
 function writeFileAtomic(filePath, bytes) {
-  const dir = path6.dirname(path6.resolve(filePath));
-  const tmp = path6.join(dir, `.${path6.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
-  fs5.writeFileSync(tmp, bytes);
+  const dir = path8.dirname(path8.resolve(filePath));
+  const tmp = path8.join(dir, `.${path8.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+  fs7.writeFileSync(tmp, bytes);
   try {
-    fs5.renameSync(tmp, filePath);
+    fs7.renameSync(tmp, filePath);
   } catch (error52) {
     try {
-      fs5.unlinkSync(tmp);
+      fs7.unlinkSync(tmp);
     } catch {
     }
     throw error52;
@@ -74618,16 +75237,16 @@ var MatcherView = class {
    * @returns {string|undefined}
    */
   getCurrentTag() {
-    const path8 = this._matcher.path;
-    return path8.length > 0 ? path8[path8.length - 1].tag : void 0;
+    const path10 = this._matcher.path;
+    return path10.length > 0 ? path10[path10.length - 1].tag : void 0;
   }
   /**
    * Get current namespace.
    * @returns {string|undefined}
    */
   getCurrentNamespace() {
-    const path8 = this._matcher.path;
-    return path8.length > 0 ? path8[path8.length - 1].namespace : void 0;
+    const path10 = this._matcher.path;
+    return path10.length > 0 ? path10[path10.length - 1].namespace : void 0;
   }
   /**
    * Get current node's attribute value.
@@ -74635,9 +75254,9 @@ var MatcherView = class {
    * @returns {*}
    */
   getAttrValue(attrName) {
-    const path8 = this._matcher.path;
-    if (path8.length === 0) return void 0;
-    return path8[path8.length - 1].values?.[attrName];
+    const path10 = this._matcher.path;
+    if (path10.length === 0) return void 0;
+    return path10[path10.length - 1].values?.[attrName];
   }
   /**
    * Check if current node has an attribute.
@@ -74645,9 +75264,9 @@ var MatcherView = class {
    * @returns {boolean}
    */
   hasAttr(attrName) {
-    const path8 = this._matcher.path;
-    if (path8.length === 0) return false;
-    const current = path8[path8.length - 1];
+    const path10 = this._matcher.path;
+    if (path10.length === 0) return false;
+    const current = path10[path10.length - 1];
     return current.values !== void 0 && attrName in current.values;
   }
   /**
@@ -74673,18 +75292,18 @@ var MatcherView = class {
    * @returns {number}
    */
   getPosition() {
-    const path8 = this._matcher.path;
-    if (path8.length === 0) return -1;
-    return path8[path8.length - 1].position ?? 0;
+    const path10 = this._matcher.path;
+    if (path10.length === 0) return -1;
+    return path10[path10.length - 1].position ?? 0;
   }
   /**
    * Get current node's repeat counter (occurrence count of this tag name).
    * @returns {number}
    */
   getCounter() {
-    const path8 = this._matcher.path;
-    if (path8.length === 0) return -1;
-    return path8[path8.length - 1].counter ?? 0;
+    const path10 = this._matcher.path;
+    if (path10.length === 0) return -1;
+    return path10[path10.length - 1].counter ?? 0;
   }
   /**
    * Get current node's sibling index (alias for getPosition).
@@ -80342,10 +80961,10 @@ function resolveRelativePath(basePath, relativePath) {
   }
   return resolved.join("/");
 }
-function findZipEntry(zipEntries, path8) {
-  if (zipEntries[path8]) return zipEntries[path8];
-  if (zipEntries[`xl/${path8}`]) return zipEntries[`xl/${path8}`];
-  const noSlash = path8.replace(/^\//, "");
+function findZipEntry(zipEntries, path10) {
+  if (zipEntries[path10]) return zipEntries[path10];
+  if (zipEntries[`xl/${path10}`]) return zipEntries[`xl/${path10}`];
+  const noSlash = path10.replace(/^\//, "");
   if (zipEntries[noSlash]) return zipEntries[noSlash];
   return void 0;
 }
@@ -81974,9 +82593,9 @@ function parseExcelFromZip(zip, options) {
   }
   return result;
 }
-function findEntry(zip, path8) {
-  if (zip[path8]) return zip[path8];
-  const lower2 = path8.toLowerCase();
+function findEntry(zip, path10) {
+  if (zip[path10]) return zip[path10];
+  const lower2 = path10.toLowerCase();
   for (const key of Object.keys(zip)) {
     if (key.toLowerCase() === lower2) return zip[key];
   }
@@ -82613,12 +83232,12 @@ function extractPivotRoundTripInfo(originalZip) {
     if (paths.length > 0) pivotTablesBySheetIndex.set(i2, paths);
   }
   const pivotXmlPaths = [];
-  for (const path8 of Object.keys(originalZip)) {
-    if (path8.startsWith("xl/pivotTables/") && path8.endsWith(".xml")) {
-      pivotXmlPaths.push(path8);
+  for (const path10 of Object.keys(originalZip)) {
+    if (path10.startsWith("xl/pivotTables/") && path10.endsWith(".xml")) {
+      pivotXmlPaths.push(path10);
     }
-    if (path8.startsWith("xl/pivotCache/") && path8.endsWith(".xml")) {
-      pivotXmlPaths.push(path8);
+    if (path10.startsWith("xl/pivotCache/") && path10.endsWith(".xml")) {
+      pivotXmlPaths.push(path10);
     }
   }
   return { cachesByWorkbook, pivotTablesBySheetIndex, pivotXmlPaths };
@@ -82626,15 +83245,15 @@ function extractPivotRoundTripInfo(originalZip) {
 function decode3(bytes) {
   return new TextDecoder().decode(bytes);
 }
-function pivotContentTypeFor(path8) {
-  if (path8.startsWith("xl/pivotTables/") && path8.endsWith(".xml")) {
-    return `<Override PartName="/${path8}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotTable+xml"/>`;
+function pivotContentTypeFor(path10) {
+  if (path10.startsWith("xl/pivotTables/") && path10.endsWith(".xml")) {
+    return `<Override PartName="/${path10}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotTable+xml"/>`;
   }
-  if (path8.includes("/pivotCacheDefinition") && path8.endsWith(".xml")) {
-    return `<Override PartName="/${path8}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml"/>`;
+  if (path10.includes("/pivotCacheDefinition") && path10.endsWith(".xml")) {
+    return `<Override PartName="/${path10}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml"/>`;
   }
-  if (path8.includes("/pivotCacheRecords") && path8.endsWith(".xml")) {
-    return `<Override PartName="/${path8}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheRecords+xml"/>`;
+  if (path10.includes("/pivotCacheRecords") && path10.endsWith(".xml")) {
+    return `<Override PartName="/${path10}" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheRecords+xml"/>`;
   }
   return void 0;
 }
@@ -82707,16 +83326,16 @@ function exportWorkbook(workbook, originalZip) {
       regeneratedPaths.add(`xl/worksheets/sheet${i2 + 1}.xml`);
       regeneratedPaths.add(`xl/worksheets/_rels/sheet${i2 + 1}.xml.rels`);
     }
-    for (const path8 of Object.keys(originalZip)) {
-      if (path8.startsWith("xl/drawings/") || path8.startsWith("xl/charts/") || path8.startsWith("xl/tables/") || path8.startsWith("xl/media/")) {
-        regeneratedPaths.add(path8);
+    for (const path10 of Object.keys(originalZip)) {
+      if (path10.startsWith("xl/drawings/") || path10.startsWith("xl/charts/") || path10.startsWith("xl/tables/") || path10.startsWith("xl/media/")) {
+        regeneratedPaths.add(path10);
       }
     }
-    for (const [path8, data2] of Object.entries(originalZip)) {
-      if (regeneratedPaths.has(path8)) continue;
-      const ext = path8.slice(path8.lastIndexOf(".") + 1).toLowerCase();
+    for (const [path10, data2] of Object.entries(originalZip)) {
+      if (regeneratedPaths.has(path10)) continue;
+      const ext = path10.slice(path10.lastIndexOf(".") + 1).toLowerCase();
       if (!DECLARED_EXTENSIONS.includes(ext)) continue;
-      entries2[path8] = data2;
+      entries2[path10] = data2;
     }
   }
   const sharedStrings = buildSharedStrings(workbook);
@@ -82732,8 +83351,8 @@ function exportWorkbook(workbook, originalZip) {
     buildWorkbookRels(workbook, pivotInfo)
   );
   const extraContentTypes = [];
-  for (const path8 of pivotInfo.pivotXmlPaths) {
-    const ct = pivotContentTypeFor(path8);
+  for (const path10 of pivotInfo.pivotXmlPaths) {
+    const ct = pivotContentTypeFor(path10);
     if (ct) extraContentTypes.push(ct);
   }
   let globalChartIndex = 1;
@@ -91756,14 +92375,14 @@ var DependencyGraph = class {
       stack.push({ cell: p, path: [cell, p] });
     }
     while (stack.length > 0) {
-      const { cell: current, path: path8 } = stack.pop();
-      if (current === cell) return path8;
+      const { cell: current, path: path10 } = stack.pop();
+      if (current === cell) return path10;
       if (visited.has(current)) continue;
       visited.add(current);
       const nextPrec = this.precedents.get(current);
       if (!nextPrec) continue;
       for (const p of nextPrec) {
-        stack.push({ cell: p, path: [...path8, p] });
+        stack.push({ cell: p, path: [...path10, p] });
       }
     }
     return null;
@@ -92975,8 +93594,8 @@ var SIMPLE_SHEET_KEYS = /* @__PURE__ */ new Set(["name", "cells", "merges", "fre
 var MAX_COLUMN = 16384;
 var MAX_ROW = 1048576;
 function loadFile(filePath) {
-  if (!fs6.existsSync(filePath)) fail2(`File not found: ${filePath}`);
-  const buffer = fs6.readFileSync(filePath);
+  if (!fs8.existsSync(filePath)) fail2(`File not found: ${filePath}`);
+  const buffer = fs8.readFileSync(filePath);
   const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
   const originalZip = unzipXlsx(arrayBuffer);
   const parsed = parseExcelBuffer(arrayBuffer);
@@ -93026,7 +93645,7 @@ function lazyEngine(workbook) {
   };
 }
 function readToJson(filePath, filter3, opts) {
-  const buffer = fs6.readFileSync(filePath);
+  const buffer = fs8.readFileSync(filePath);
   const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
   const parsed = parseExcelBuffer(arrayBuffer);
   let sheets = parsed.sheets;
@@ -93539,7 +94158,7 @@ async function runXlsxCommand(subcommand, toolArgs, restArgs) {
 }
 
 // src/docx.ts
-import fs7 from "node:fs";
+import fs9 from "node:fs";
 
 // ../ooxml/src/doc/errors.ts
 var DocParseError = class extends Error {
@@ -98155,8 +98774,8 @@ async function docModelToDocx(model) {
 // ../ooxml/src/opc.ts
 var import_jszip = __toESM(require_lib4(), 1);
 function dropFolderEntries(zip) {
-  for (const [path8, entry] of Object.entries(zip.files)) {
-    if (entry.dir) delete zip.files[path8];
+  for (const [path10, entry] of Object.entries(zip.files)) {
+    if (entry.dir) delete zip.files[path10];
   }
 }
 
@@ -98388,11 +99007,11 @@ async function parseDocx(buffer) {
   const zip = await import_jszip3.default.loadAsync(buffer);
   const parts = /* @__PURE__ */ new Map();
   const filePromises = [];
-  zip.forEach((path8, file2) => {
+  zip.forEach((path10, file2) => {
     if (file2.dir) return;
     filePromises.push(
       file2.async("uint8array").then((bytes) => {
-        parts.set(path8, bytes);
+        parts.set(path10, bytes);
       })
     );
   });
@@ -98624,9 +99243,9 @@ var DEFAULT_PARTS = [
   ["word/theme/theme1.xml", () => encoder.encode(THEME_XML)]
 ];
 function fillDefaultParts(parts) {
-  for (const [path8, makeBytes] of DEFAULT_PARTS) {
-    if (!parts.has(path8)) {
-      parts.set(path8, makeBytes());
+  for (const [path10, makeBytes] of DEFAULT_PARTS) {
+    if (!parts.has(path10)) {
+      parts.set(path10, makeBytes());
     }
   }
   return parts;
@@ -98636,9 +99255,9 @@ function fillDefaultParts(parts) {
 async function serializeDocx(doc) {
   const zip = new import_jszip4.default();
   const parts = fillDefaultParts(new Map(doc.parts));
-  for (const [path8, bytes] of parts) {
-    if (path8 === "word/document.xml") continue;
-    zip.file(path8, bytes);
+  for (const [path10, bytes] of parts) {
+    if (path10 === "word/document.xml") continue;
+    zip.file(path10, bytes);
   }
   const documentXml = serializeDocumentXml(doc);
   zip.file("word/document.xml", documentXml);
@@ -98725,8 +99344,8 @@ var DEFAULT_DOC_ATTRS = {
   "@_xmlns:w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
 };
 async function loadFile2(filePath) {
-  if (!fs7.existsSync(filePath)) fail2(`File not found: ${filePath}`);
-  const bytes = fs7.readFileSync(filePath);
+  if (!fs9.existsSync(filePath)) fail2(`File not found: ${filePath}`);
+  const bytes = fs9.readFileSync(filePath);
   if (isLegacyDoc(bytes)) {
     const upgraded = await saveDocxToBuffer(await loadDocxFromBuffer(bytes));
     return parseDocx(new Uint8Array(upgraded));
@@ -99211,10 +99830,10 @@ async function runDocxCommand(subcommand, toolArgs, restArgs) {
 }
 
 // src/knowledge.ts
-import fs8 from "node:fs";
+import fs10 from "node:fs";
 function readBodyFile(filePath) {
-  if (!fs8.existsSync(filePath)) fail2(`File not found: ${filePath}`);
-  return fs8.readFileSync(filePath, "utf-8");
+  if (!fs10.existsSync(filePath)) fail2(`File not found: ${filePath}`);
+  return fs10.readFileSync(filePath, "utf-8");
 }
 function resolveBody(flags, required2) {
   if (flags.from !== void 0 && flags.content !== void 0) {
@@ -99551,6 +100170,7 @@ async function runPreviewCommand(filePath, flags) {
 }
 
 // src/cli.ts
+var startedAt = Date.now();
 dns.setDefaultResultOrder("ipv4first");
 net2.setDefaultAutoSelectFamilyAttemptTimeout(2e3);
 function printHelp() {
@@ -99614,7 +100234,8 @@ COMMANDS
   lotics app codegen [path]            Regenerate .lotics/* (types + field/option ids)
                                        from the manifest + workspace schema \u2014 no deploy
   lotics app check                     Run every deploy pre-flight WITHOUT building or
-                                       shipping: agent schemas vs the live app, aliases
+                                       shipping: agent schemas vs the live app, workflow
+                                       declarations and BODIES vs what is live, aliases
                                        the code calls but nothing bound, undeclared
                                        capabilities, query drift. Exits 1 on what a
                                        deploy would refuse, so CI can gate on it
@@ -99763,8 +100384,8 @@ function prompt(question) {
     });
   });
 }
-async function publicPost(path8, body) {
-  const response = await fetch(`${API_BASE_URL}${path8}`, {
+async function publicPost(path10, body) {
+  const response = await fetch(`${API_BASE_URL}${path10}`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify(body)
@@ -99861,6 +100482,8 @@ function requireClient(flags, appWorkspaceId) {
     process.exit(1);
   }
   const viewAsMemberId = flags.viewAs ?? process.env.LOTICS_VIEW_AS;
+  noteScope({ org_id: ctx.orgId ?? void 0, workspace_id: ctx.workspaceId });
+  flushSpool((events) => postEvents(API_BASE_URL, ctx.apiKey, events));
   return {
     client: new LoticsClient({ apiKey: ctx.apiKey, workspaceId: ctx.workspaceId, viewAsMemberId }),
     ctx
@@ -99875,6 +100498,7 @@ var SOURCE_LABELS = {
   global_profile: "global active profile"
 };
 function announceTarget(ctx, workspaceId) {
+  noteScope({ org_id: ctx.orgId ?? void 0, workspace_id: workspaceId });
   const org = ctx.orgName ?? ctx.orgId ?? "(org from key)";
   if (ctx.source === "global_profile") {
     console.error(
@@ -99929,13 +100553,13 @@ async function resolveWorkspace(client, ctx) {
 function resolveUploadPaths(rawPaths) {
   const result = [];
   for (const p of rawPaths) {
-    const resolved = path7.resolve(p);
-    const stat = fs9.statSync(resolved);
+    const resolved = path9.resolve(p);
+    const stat = fs11.statSync(resolved);
     if (stat.isDirectory()) {
-      const entries2 = fs9.readdirSync(resolved, { withFileTypes: true });
+      const entries2 = fs11.readdirSync(resolved, { withFileTypes: true });
       for (const entry of entries2) {
         if (entry.isFile()) {
-          result.push(path7.join(resolved, entry.name));
+          result.push(path9.join(resolved, entry.name));
         }
       }
     } else {
@@ -99945,6 +100569,8 @@ function resolveUploadPaths(rawPaths) {
   return result;
 }
 async function main() {
+  setInvocation(commandPath(process.argv.slice(2)), sessionId(), VERSION);
+  installTelemetry(startedAt);
   const parsed = parseArgs(process.argv.slice(2));
   const { restArgs, flags } = parsed;
   let { command, subcommand, toolArgs } = parsed;
@@ -100058,13 +100684,13 @@ async function main() {
   if (command === "preview") {
     if (subcommand && isStoredFileId(subcommand)) {
       const { client: client2 } = requireClient(flags);
-      const tmpDir = fs9.mkdtempSync(path7.join(os2.tmpdir(), "lotics-preview-"));
+      const tmpDir = fs11.mkdtempSync(path9.join(os4.tmpdir(), "lotics-preview-"));
       try {
         const { path: localPath, filename } = await client2.downloadFileById(subcommand, tmpDir);
         const output = flags.output ?? defaultPreviewOutputPath(filename, process.cwd());
         await runPreviewCommand(localPath, { output });
       } finally {
-        fs9.rmSync(tmpDir, { recursive: true, force: true });
+        fs11.rmSync(tmpDir, { recursive: true, force: true });
       }
       return;
     }
@@ -100337,17 +100963,11 @@ Available workspaces:`);
         process.exit(1);
       }
       const targetPath = restArgs[0];
-      await appPull(client, { app_id: appId, targetPath });
+      await appPull(client, { app_id: appId, targetPath, force: flags.force === true });
       return;
     }
     if (subcommand === "deploy") {
-      const message2 = (flags.message ?? toolArgs)?.trim();
-      if (!message2) {
-        console.error('Usage: lotics app deploy -m "<what changed + why>"');
-        console.error("A deploy message is required \u2014 it's the version's audit trail (see `lotics app versions`).");
-        process.exit(1);
-      }
-      await appDeploy(client, { message: message2 });
+      await appDeploy(client, { message: (flags.message ?? toolArgs)?.trim() || void 0 });
       return;
     }
     if (subcommand === "subdomain") {
@@ -100402,7 +101022,7 @@ Available workspaces:`);
         const ingested = await ingestJsonArgs({
           rawArg: restArgs[1],
           stdinIsTTY: process.stdin.isTTY ?? false,
-          readFile: (p) => fs9.readFileSync(p, "utf-8"),
+          readFile: (p) => fs11.readFileSync(p, "utf-8"),
           readStdin
         });
         if (ingested.kind === "error") {
@@ -100428,7 +101048,7 @@ Available workspaces:`);
         return;
       }
       if (action === "pull") {
-        await appWorkflowPull(client);
+        await appWorkflowPull(client, { force: flags.force === true });
         return;
       }
       workflowUsage();
@@ -100453,7 +101073,7 @@ Available workspaces:`);
         const ingested = await ingestJsonArgs({
           rawArg: restArgs[2],
           stdinIsTTY: process.stdin.isTTY ?? false,
-          readFile: (p) => fs9.readFileSync(p, "utf-8"),
+          readFile: (p) => fs11.readFileSync(p, "utf-8"),
           readStdin
         });
         if (ingested.kind === "error") {
@@ -100609,7 +101229,7 @@ ${JSON.stringify(info.input_schema, null, 2)}`);
     const ingested = await ingestJsonArgs({
       rawArg: toolArgs,
       stdinIsTTY: process.stdin.isTTY ?? false,
-      readFile: (p) => fs9.readFileSync(p, "utf-8"),
+      readFile: (p) => fs11.readFileSync(p, "utf-8"),
       readStdin
     });
     if (ingested.kind === "error") {
@@ -100617,6 +101237,7 @@ ${JSON.stringify(info.input_schema, null, 2)}`);
       process.exit(1);
     }
     const args = ingested.args;
+    noteToolArgs(args);
     const timeoutMs = flags.timeout ?? 6e4;
     const result = await client.execute(toolName, args, { format: "text", timeoutMs });
     if (result.error) {