@montytools/cli 0.2.10 → 0.4.0

package/bin/monty.mjs

@@ -4,8 +4,10 @@
 // deterministic final line (`deployed: …` / `error: …`).
 
 import { spawn, spawnSync } from "node:child_process";
-import { randomBytes } from "node:crypto";
-import { cpSync, mkdirSync, readFileSync, rmSync, writeFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import { appendFileSync, closeSync, cpSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, symlinkSync, writeFileSync, readdirSync, statSync, existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { StringDecoder } from "node:string_decoder";
 import { createServer } from "node:http";
 import { connect as netConnect } from "node:net";
 import { homedir } from "node:os";
@@ -20,9 +22,29 @@ const CONFIG_PATH = join(CONFIG_DIR, "config.json");
 const DEFAULT_HOST = "https://usemonty.dev";
 const DEV_SESSION_HEARTBEAT_MS = 30_000;
 const DEV_SESSION_REQUEST_TIMEOUT_MS = 10_000;
-// Every app's source lives in one predictable place. `monty create` stamps
-// here by default (override with --dir) and `monty login` provisions it.
-const MONTY_HOME = join(homedir(), "Monty");
+// The local session contract (.monty/dev.json + dev.log): the running dev
+// shell advertises itself so a second `monty dev` (an agent, or the Monty
+// desktop) attaches instead of superseding, and `monty logs` reads the log.
+const DEV_JSON_STALE_MS = 90_000; // freshness window for dev.json.updatedAt
+const DEV_JSON_TOUCH_MS = 15_000; // dedicated updatedAt cadence (NOT the heartbeat — that starts minutes late, or never when logged out)
+const DEV_LOG_MAX_BYTES = 8 * 1024 * 1024; // rotate dev.log at 8 MiB (disk bound ≈ 16 MiB with dev.log.1)
+const LOGS_DEFAULT_LINES = 50;
+const LOGS_POLL_MS = 300;
+const ATTACH_TAIL_LINES = 10;
+const TAKEOVER_WAIT_MS = 5_000; // grace per phase (SIGTERM, then SIGKILL)
+// eslint-disable-next-line no-control-regex -- dev.log is ANSI-free by contract
+const ANSI_RE = new RegExp(
+  "[\\u001B\\u009B][[\\]()#;?]*(?:(?:(?:[a-zA-Z\\d]*(?:;[-a-zA-Z\\d/#&.:=?%@~_]*)*)?\\u0007)|(?:(?:\\d{1,4}(?:;\\d{0,4})*)?[\\dA-PR-TZcf-nq-uy=><~]))",
+  "g",
+);
+// Every app's source lives in one predictable, hidden place: `monty create`
+// registers the app first and the server-minted id names the folder
+// (~/.monty/apps/<id>) — id-keyed because slugs may be renamed later; the
+// `id` stamped into monty.config.ts is the durable identity. `monty login`
+// provisions the home; --dir overrides per create. Pre-id apps in the legacy
+// visible home (~/Monty) keep working — every scan reads both.
+const MONTY_HOME = join(CONFIG_DIR, "apps");
+const LEGACY_MONTY_HOME = join(homedir(), "Monty");
 
 const [, , command, ...rest] = process.argv;
 
@@ -297,12 +319,24 @@ function readSlugFromConfig(dir) {
   }
 }
 
-function listLocalApps() {
-  if (!existsSync(MONTY_HOME)) return [];
-  return readdirSync(MONTY_HOME)
-    .map((name) => join(MONTY_HOME, name))
+function readIdFromConfig(dir) {
+  try {
+    return /^[ \t]*id:\s*"([^"]+)"/m.exec(readFileSync(join(dir, "monty.config.ts"), "utf8"))?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function scanAppsHome(root) {
+  if (!existsSync(root)) return [];
+  return readdirSync(root)
+    .map((name) => join(root, name))
     .filter((p) => existsSync(join(p, "monty.config.ts")))
-    .map((p) => ({ path: p, slug: readSlugFromConfig(p) ?? basename(p) }));
+    .map((p) => ({ path: p, slug: readSlugFromConfig(p) ?? basename(p), id: readIdFromConfig(p) }));
+}
+
+function listLocalApps() {
+  return [...scanAppsHome(MONTY_HOME), ...scanAppsHome(LEGACY_MONTY_HOME)];
 }
 
 function current() {
@@ -311,8 +345,10 @@ function current() {
     fail("NOT_IN_APP", `You are not inside a Monty app. \`monty apps\` lists local apps; cd "$(monty select <slug>)" jumps to one.`);
   }
   console.log(`app: ${readSlugFromConfig(root) ?? "?"}`);
+  const id = readIdFromConfig(root);
+  if (id) console.log(`id: ${id}`);
   console.log(`path: ${root}`);
-  if (!root.startsWith(MONTY_HOME)) {
+  if (!root.startsWith(MONTY_HOME) && !root.startsWith(LEGACY_MONTY_HOME)) {
     console.log(`note: outside ${MONTY_HOME} (fine, but apps normally live there)`);
   }
 }
@@ -323,10 +359,10 @@ function select() {
     fail("MISSING_SLUG", `Usage: cd "$(monty select <slug>)" — prints the app's folder.`);
   }
   const apps = listLocalApps();
-  const hit = apps.find((a) => a.slug === slug || basename(a.path) === slug);
+  const hit = apps.find((a) => a.slug === slug || a.id === slug || basename(a.path) === slug);
   if (!hit) {
     const known = apps.map((a) => a.slug).join(", ") || "(none)";
-    fail("APP_NOT_LOCAL", `No local source for "${slug}" in ${MONTY_HOME}. Local apps: ${known}. Create it with \`monty create ${slug}\`.`);
+    fail("APP_NOT_LOCAL", `No local source for "${slug}" on this machine. Local apps: ${known}. Create it with \`monty create ${slug}\`.`);
   }
   // Bare path on stdout so command substitution works: cd "$(monty select x)"
   console.log(hit.path);
@@ -341,22 +377,267 @@ function apps() {
   for (const a of local) console.log(`${a.slug}\t${a.path}`);
 }
 
+// Pack the app's source tree (node_modules/dist/.monty/.git excluded) into a
+// tar.gz buffer + its sha256 — the snapshot unit `monty commit` and deploys
+// both upload. gzip runs with -n (no embedded timestamp) so an UNCHANGED
+// tree packs to identical bytes — that's what makes "nothing to commit"
+// detectable by hash. Returns null when packing fails; { tooLarge } past
+// the 10MB cap.
+function packSource(appDir) {
+  mkdirSync(join(appDir, ".monty"), { recursive: true });
+  const srcTar = join(appDir, ".monty", "source-upload.tar.gz");
+  const excludes = ["./node_modules", "./dist", "./.monty", "./.git", "./.env.local", "./release"]
+    .map((p) => `--exclude ${JSON.stringify(p)}`)
+    .join(" ");
+  const packRes =
+    process.platform === "win32"
+      ? spawnSync("tar", ["-czf", srcTar, "--exclude", "./node_modules", "--exclude", "./dist", "--exclude", "./.monty", "--exclude", "./.git", "--exclude", "./.env.local", "--exclude", "./release", "-C", appDir, "."], { stdio: "pipe" })
+      : spawnSync("sh", ["-c", `tar -cf - ${excludes} -C ${JSON.stringify(appDir)} . | gzip -n > ${JSON.stringify(srcTar)}`], { stdio: "pipe" });
+  if (packRes.status !== 0) {
+    rmSync(srcTar, { force: true });
+    return null;
+  }
+  const buf = readFileSync(srcTar);
+  rmSync(srcTar, { force: true });
+  if (buf.byteLength > 10 * 1024 * 1024) return { tooLarge: true };
+  return { buf, hash: createHash("sha256").update(buf).digest("hex") };
+}
+
+function readSlug(appDir) {
+  try {
+    return /slug:\s*"([^"]+)"/.exec(readFileSync(join(appDir, "monty.config.ts"), "utf8"))?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+// ── monty commit ───────────────────────────────────────────────────────────
+// Version the app's source WITHOUT publishing: pack the tree, upload it as
+// one line of history. Git commit with everything stripped except "track
+// versions" — no branches, no diffs, no local repo; history lives in the
+// workspace and survives this folder.
+async function commit() {
+  const appDir = requireAppDir("commit");
+  const slug = readSlug(appDir);
+  if (!slug) fail("NO_SLUG", "monty.config.ts has no slug — fix the config, then retry.");
+  const { host, key } = loadConfig();
+  if (!key) fail("NOT_LOGGED_IN", "Committing stores the snapshot in your workspace. Run `monty login` first.");
+  const mIdx = rest.indexOf("-m");
+  const message = flag("message") ?? (mIdx >= 0 ? rest[mIdx + 1] : undefined) ?? "checkpoint";
+  const packed = packSource(appDir);
+  if (packed === null) fail("PACK_FAILED", "Packing the source failed (tar error). Retry; check the folder is readable.");
+  if (packed.tooLarge) fail("SOURCE_TOO_LARGE", "The source tree exceeds 10 MB (node_modules/dist excluded). Remove large assets, then retry.");
+  try {
+    const stamp = JSON.parse(readFileSync(join(appDir, ".monty", "source.json"), "utf8"));
+    if (stamp.hash === packed.hash) {
+      console.log(`nothing to commit — source unchanged since ${packed.hash.slice(0, 7)}`);
+      return;
+    }
+  } catch {
+    /* no stamp yet — first commit from this folder */
+  }
+  const form = new FormData();
+  form.set("monty", JSON.stringify({ slug, hash: packed.hash, message }));
+  form.set("source", new Blob([packed.buf]), "source.tar.gz");
+  const res = await fetch(`${host}/api/source`, {
+    method: "POST",
+    headers: { authorization: `Bearer ${key}` },
+    body: form,
+  });
+  const body = await res.json().catch(() => null);
+  if (!res.ok || !body?.ok) {
+    fail(body?.code ?? `HTTP_${res.status}`, body?.fix ?? "Uploading the snapshot failed — check the connection and retry.");
+  }
+  writeFileSync(
+    join(appDir, ".monty", "source.json"),
+    JSON.stringify({ hash: packed.hash, syncedAt: Date.now() }) + "\n",
+  );
+  console.log(`committed: ${packed.hash.slice(0, 7)} "${message}" (${(packed.buf.byteLength / 1024).toFixed(0)} KB)`);
+}
+
+// ── monty log ──────────────────────────────────────────────────────────────
+// The app's version history, newest first. Commits and publishes share one
+// timeline. (Not `monty logs` — that tails the dev shell.)
+async function versionsLog() {
+  const slug = rest.find((a) => !a.startsWith("-")) ?? readSlug(process.cwd());
+  if (!slug) fail("NO_SLUG", "Usage: monty log [slug] — or run it inside an app folder.");
+  const { host, key } = loadConfig();
+  if (!key) fail("NOT_LOGGED_IN", "Run `monty login` first.");
+  const res = await fetch(`${host}/api/source?slug=${slug}&list=1`, {
+    headers: { authorization: `Bearer ${key}` },
+  });
+  const body = await res.json().catch(() => null);
+  if (!res.ok || !body?.ok) {
+    fail(body?.code ?? `HTTP_${res.status}`, body?.fix ?? "Could not list versions — check the connection and `monty login`.");
+  }
+  if (body.versions.length === 0) {
+    console.log(`no versions of "${slug}" yet — \`monty commit\` or a publish creates the first one.`);
+    return;
+  }
+  for (const v of body.versions) {
+    const when = new Date(v.createdAt).toISOString().slice(0, 16).replace("T", " ");
+    console.log(`${v.hash.slice(0, 7)}  ${when}  ${v.published ? "[published] " : ""}${v.message}`);
+  }
+  console.log(`\nrestore one: monty pull ${slug} --version <hash> [--force]`);
+}
+
+// ── monty pull ─────────────────────────────────────────────────────────────
+// Restore an app's published source snapshot onto this machine. Every
+// `monty deploy`/publish uploads the source tree beside the bundle; pull is
+// how a second machine (or one that lost the folder) gets the code back.
+// Refuses to touch an existing folder without --force — it may hold
+// unpublished work the snapshot would destroy.
+async function pull() {
+  const slug = rest.find((a) => !a.startsWith("--"));
+  if (!slug || !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug)) {
+    fail("INVALID_SLUG", "Usage: monty pull <slug> [--force]");
+  }
+  const { host, key } = loadConfig();
+  if (!key) {
+    fail("NOT_LOGGED_IN", `Pulling needs your workspace (${host}). Run \`monty login\` first.`);
+  }
+  const appsRes = await fetch(`${host}/api/apps`, { headers: { authorization: `Bearer ${key}` } });
+  const appsBody = await appsRes.json().catch(() => null);
+  if (!appsRes.ok || !appsBody?.ok) {
+    fail(appsBody?.code ?? `HTTP_${appsRes.status}`, appsBody?.fix ?? "Could not list workspace apps — check the connection and `monty login`.");
+  }
+  const app = appsBody.apps.find((a) => a.slug === slug);
+  if (!app) {
+    fail("APP_NOT_FOUND", `No app "${slug}" in this workspace. \`monty apps\` lists what exists.`);
+  }
+  // --version <hash-prefix>: restore a specific snapshot from `monty log`
+  // instead of the newest one. Prefixes resolve against the history list.
+  const versionFlag = flag("version");
+  let expectedHash = app.sourceHash;
+  let downloadUrl = `${host}/api/source?slug=${slug}`;
+  if (versionFlag) {
+    const vres = await fetch(`${host}/api/source?slug=${slug}&list=1`, {
+      headers: { authorization: `Bearer ${key}` },
+    });
+    const vbody = await vres.json().catch(() => null);
+    if (!vres.ok || !vbody?.ok) {
+      fail(vbody?.code ?? `HTTP_${vres.status}`, vbody?.fix ?? "Could not list versions — retry.");
+    }
+    const matches = vbody.versions.filter((v) => v.hash.startsWith(versionFlag));
+    if (matches.length === 0) {
+      fail("VERSION_NOT_FOUND", `No version of "${slug}" matches "${versionFlag}". \`monty log ${slug}\` lists what exists.`);
+    }
+    if (matches.length > 1) {
+      fail("VERSION_AMBIGUOUS", `"${versionFlag}" matches ${matches.length} versions — use more characters of the hash.`);
+    }
+    expectedHash = matches[0].hash;
+    downloadUrl = `${host}/api/source?slug=${slug}&hash=${expectedHash}`;
+  } else if (!app.sourceHash) {
+    fail("NO_SOURCE", `"${slug}" has no source snapshot yet — snapshots ride each publish and \`monty commit\`. Run either once from the machine that has the source, then pull works everywhere.`);
+  }
+  const target = app.id ? join(MONTY_HOME, app.id) : join(LEGACY_MONTY_HOME, slug);
+  if (existsSync(target) && !rest.includes("--force")) {
+    fail("DIR_EXISTS", `${target} already exists and may hold unpublished work. Compare it with the published version first; re-run with --force to REPLACE it with the snapshot.`);
+  }
+
+  console.log(`pull: ${slug}${versionFlag ? ` @ ${expectedHash.slice(0, 7)}` : ""} <- ${host}`);
+  const res = await fetch(downloadUrl, {
+    headers: { authorization: `Bearer ${key}` },
+  });
+  if (!res.ok) {
+    const b = await res.json().catch(() => null);
+    fail(b?.code ?? `HTTP_${res.status}`, b?.fix ?? "Downloading the snapshot failed — retry.");
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  const hash = createHash("sha256").update(buf).digest("hex");
+  if (hash !== expectedHash) {
+    fail("SOURCE_CORRUPT", "The downloaded snapshot failed verification — retry; if it persists, republish the app from a machine that has the source.");
+  }
+
+  // Extract into a staging folder, then move into place — a failed extract
+  // never leaves a half-written app folder.
+  const staging = `${target}.pull-tmp`;
+  rmSync(staging, { recursive: true, force: true });
+  mkdirSync(staging, { recursive: true });
+  const tarFile = join(staging, ".source.tar.gz");
+  writeFileSync(tarFile, buf);
+  const untar = spawnSync("tar", ["-xzf", tarFile, "-C", staging], { stdio: "pipe" });
+  rmSync(tarFile, { force: true });
+  if (untar.status !== 0) {
+    rmSync(staging, { recursive: true, force: true });
+    fail("EXTRACT_FAILED", "Unpacking the snapshot failed. Retry; if it persists, republish the app.");
+  }
+  if (existsSync(target)) rmSync(target, { recursive: true, force: true });
+  renameSync(staging, target);
+
+  // Same follow-ups as create: client env from the platform + the sync stamp.
+  try {
+    const cfg = await fetch(`${host}/api/config`).then((r) => r.json());
+    writeFileSync(
+      join(target, ".env.local"),
+      `VITE_CONVEX_URL=${cfg.convexUrl}\nVITE_CLERK_PUBLISHABLE_KEY=${cfg.clerkPublishableKey}\n`,
+    );
+  } catch {
+    console.log(`config: WARNING — could not reach ${host}/api/config; copy .env.example to .env.local manually`);
+  }
+  mkdirSync(join(target, ".monty"), { recursive: true });
+  writeFileSync(
+    join(target, ".monty", "source.json"),
+    JSON.stringify({ hash, syncedAt: Date.now() }) + "\n",
+  );
+  console.log(`pulled: ${target}`);
+  console.log("next: `monty install`, then `monty dev`.");
+}
+
 // ── monty create ───────────────────────────────────────────────────────────
 async function create() {
   const slug = rest.find((a) => !a.startsWith("--"));
-  if (!slug || !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug)) {
-    fail("INVALID_SLUG", 'Usage: monty create <slug> — lowercase letters/digits with single hyphens (e.g. "standup-notes").');
+  if (!slug || slug.length > 64 || !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(slug)) {
+    fail("INVALID_SLUG", 'Usage: monty create <slug> — lowercase letters/digits with single hyphens, max 64 chars (e.g. "standup-notes").');
+  }
+  // An app with this slug already on disk means create is the wrong verb —
+  // fail BEFORE registering, and never suggest deleting anything: the folder
+  // may hold real, uncommitted work.
+  const dupe = listLocalApps().find((a) => a.slug === slug);
+  if (dupe) {
+    fail("APP_EXISTS", `"${slug}" already exists on this machine at ${dupe.path}. Keep working on it there (cd "$(monty select ${slug})"); pick a different slug for a new app.`);
   }
   const name =
     flag("name") ??
     slug.split("-").map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
   const icon = flag("icon") ?? "layout-grid";
-  // Apps live in ~/Monty/<slug> unless --dir points elsewhere.
+
+  // Step 0: register the app — the DB mints the id that names the local
+  // folder and rides monty.config.ts, and it arbitrates slug uniqueness
+  // workspace-wide. Creating is therefore online + logged-in, by design.
+  const { host, key } = loadConfig();
+  if (!key) {
+    fail("NOT_LOGGED_IN", `Creating an app registers it in your workspace (${host}). Run \`monty login\` first.`);
+  }
+  let appId;
+  try {
+    const r = await fetch(`${host}/api/apps`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+      body: JSON.stringify({ slug, name, icon }),
+      signal: AbortSignal.timeout(15_000),
+    });
+    const data = await r.json().catch(() => null);
+    // The id names a folder and is stamped into a TS file — accept only a
+    // plain Convex-id-shaped token, never anything path- or quote-capable.
+    if (!r.ok || !data?.ok || typeof data.appId !== "string" || !/^[a-z0-9]{10,64}$/i.test(data.appId)) {
+      fail(
+        data?.code ?? "CREATE_FAILED",
+        data?.fix ?? `Registering the app with ${host} failed (status ${r.status}). Retry; if it persists, run \`monty login\` again.`,
+      );
+    }
+    appId = data.appId;
+  } catch {
+    fail("HOST_UNREACHABLE", `Could not reach ${host} — creating an app registers it in your workspace, so it needs the network. Check your connection and retry.`);
+  }
+  console.log(`registered: ${slug} (id ${appId})`);
+
+  // Source lands in the id-keyed hidden home unless --dir points elsewhere.
   const target = flag("dir")
     ? join(process.cwd(), flag("dir"))
-    : join(MONTY_HOME, slug);
+    : join(MONTY_HOME, appId);
   if (existsSync(target)) {
-    fail("DIR_EXISTS", `${target} already exists. Pick another slug or remove the directory.`);
+    fail("DIR_EXISTS", `${target} already exists. Remove it (a previous create for "${slug}" left it behind), then retry.`);
   }
   mkdirSync(dirname(target), { recursive: true });
 
@@ -380,12 +661,13 @@ async function create() {
     },
   });
 
-  // Stamp identity into the copied files.
+  // Stamp identity into the copied files. The id line is INSERTED (the
+  // template ships without one — only real creates have a server id).
   const configPath = join(target, "monty.config.ts");
   writeFileSync(
     configPath,
     readFileSync(configPath, "utf8")
-      .replace(/slug: "[^"]*"/, `slug: "${slug}"`)
+      .replace(/^([ \t]*)slug: "[^"]*"/m, `$1id: "${appId}",\n$1slug: "${slug}"`)
       .replace(/name: "[^"]*"/, `name: "${name}"`)
       .replace(/icon: "[^"]*"/, `icon: "${icon}"`),
   );
@@ -399,8 +681,27 @@ async function create() {
     readFileSync(htmlPath, "utf8").replace(/<title>[^<]*<\/title>/, `<title>${name}</title>`),
   );
 
+  // The user's brief (--description, e.g. from the desktop's create dialog)
+  // goes to the TOP of AGENTS.md — agent harnesses can't be handed an initial
+  // prompt portably, but they all read the project instruction file. CLAUDE.md
+  // symlinks to AGENTS.md so claude sees the same brief codex/opencode do.
+  const description = flag("description");
+  const agentsPath = join(target, "AGENTS.md");
+  if (description?.trim() && existsSync(agentsPath)) {
+    const brief = `# What to build: ${name}\n\n${description.trim()}\n\nThat brief is the product goal. Everything below is the platform contract for building it.\n\n---\n\n`;
+    writeFileSync(agentsPath, brief + readFileSync(agentsPath, "utf8"));
+    console.log("brief: AGENTS.md carries the app description");
+  }
+  if (!existsSync(join(target, "CLAUDE.md"))) {
+    try {
+      symlinkSync("AGENTS.md", join(target, "CLAUDE.md"));
+    } catch {
+      // Symlinks need privileges on Windows — Claude Code's @import reads the same.
+      writeFileSync(join(target, "CLAUDE.md"), "@AGENTS.md\n");
+    }
+  }
+
   // Client config comes from the platform — public values, no dashboard trip.
-  const host = loadConfig()?.host ?? DEFAULT_HOST;
   try {
     const cfg = await fetch(`${host}/api/config`).then((r) => r.json());
     writeFileSync(
@@ -418,18 +719,15 @@ async function create() {
   if (buildId && /^[a-z0-9]{10,64}$/i.test(buildId)) {
     mkdirSync(join(target, ".monty"), { recursive: true });
     writeFileSync(join(target, ".monty", "build"), buildId + "\n");
-    const cfg = loadConfig();
-    if (cfg?.key) {
-      try {
-        await fetch(`${cfg.host ?? DEFAULT_HOST}/api/build`, {
-          method: "POST",
-          headers: { authorization: `Bearer ${cfg.key}`, "content-type": "application/json" },
-          body: JSON.stringify({ buildId, slug }),
-        });
-        console.log("build: workspace notified — the New app screen is following along");
-      } catch {
-        /* progress signal only — never block create */
-      }
+    try {
+      await fetch(`${host}/api/build`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+        body: JSON.stringify({ buildId, slug }),
+      });
+      console.log("build: workspace notified — the New app screen is following along");
+    } catch {
+      /* progress signal only — never block create */
     }
   }
 
@@ -556,6 +854,353 @@ function syncSdkViteCache(appDir) {
   writeFileSync(stampPath, `${v}\n`);
 }
 
+// ── the local dev-session contract ─────────────────────────────────────────
+// The running dev shell advertises itself in <app>/.monty/dev.json (atomic
+// tmp+rename writes, a 15s touch timer drives updatedAt) and tees everything
+// it prints into <app>/.monty/dev.log. That file pair is the same-machine
+// contract shared by a second `monty dev` (attaches instead of superseding),
+// `monty logs`, and the Monty desktop. Advisory only — cross-machine
+// arbitration stays with the platform's session lock.
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function devPaths(appDir) {
+  const dir = join(appDir, ".monty");
+  return { dir, json: join(dir, "dev.json"), log: join(dir, "dev.log"), prevLog: join(dir, "dev.log.1") };
+}
+
+async function readDevJson(appDir) {
+  const { json } = devPaths(appDir);
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      return JSON.parse(readFileSync(json, "utf8"));
+    } catch (e) {
+      if (e.code === "ENOENT") return null;
+      await sleep(50); // mid-rename window — settle and retry once
+    }
+  }
+  return { unreadable: true };
+}
+
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code !== "ESRCH"; // EPERM = exists (another user's process)
+  }
+}
+
+// LIVE ⇔ pid alive && (updatedAt fresh || vite still answering on the
+// recorded port). The port+HTTP fallback keeps a healthy session attachable
+// right after a laptop wake, before the touch timer's next beat.
+async function checkDevSession(appDir) {
+  const s = await readDevJson(appDir);
+  if (!s) return { live: false, session: null, reason: "no session" };
+  if (s.unreadable) return { live: false, session: null, reason: "unreadable session file" };
+  if (!Number.isInteger(s.pid) || s.pid <= 0 || typeof s.sessionId !== "string" || typeof s.updatedAt !== "number") {
+    return { live: false, session: s, reason: "malformed session file" };
+  }
+  if (s.pid === process.pid) return { live: false, session: s, reason: "own pid" };
+  if (!pidAlive(s.pid)) return { live: false, session: s, reason: `process ${s.pid} not running` };
+  if (Date.now() - s.updatedAt <= DEV_JSON_STALE_MS) return { live: true, session: s };
+  if (Number.isInteger(s.port) && ((await portTaken("127.0.0.1", s.port)) || (await portTaken("::1", s.port)))) {
+    const probeVite = (origin) =>
+      fetch(`${origin}:${s.port}/@vite/client`, { signal: AbortSignal.timeout(1000) })
+        .then((r) => r.ok)
+        .catch(() => false);
+    // Both loopback stacks — a vite bound only to ::1 must still read LIVE.
+    if ((await probeVite("http://127.0.0.1")) || (await probeVite("http://[::1]"))) {
+      return { live: true, session: s };
+    }
+  }
+  return { live: false, session: s, reason: `not responding (no update for ${Math.round((Date.now() - s.updatedAt) / 1000)}s)` };
+}
+
+function readLogTail(appDir, n) {
+  try {
+    const lines = readFileSync(devPaths(appDir).log, "utf8").split("\n");
+    while (lines.length && lines[lines.length - 1] === "") lines.pop();
+    return lines.slice(-n);
+  } catch {
+    return [];
+  }
+}
+
+function fmtDuration(seconds) {
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+  return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`;
+}
+
+// dev.json writer for THIS session: atomic tmp+rename, never clobbers or
+// deletes a DIFFERENT session's file (we lost a race / were superseded), and
+// SEALS on removal — a late heartbeat or timer resolving after shutdown must
+// not resurrect a session file for a process that is exiting.
+function makeSessionFile(appDir, sessionId) {
+  const { json } = devPaths(appDir);
+  const tmp = `${json}.${process.pid}.tmp`;
+  let current = null;
+  let sealed = false;
+  const ownsFile = () => {
+    try {
+      const onDisk = JSON.parse(readFileSync(json, "utf8"));
+      return !onDisk?.sessionId || onDisk.sessionId === sessionId;
+    } catch {
+      return true; // absent or unreadable — ours to (re)write
+    }
+  };
+  return {
+    write(patch) {
+      if (sealed) return;
+      current = { ...(current ?? {}), ...patch, updatedAt: Date.now() };
+      if (!ownsFile()) return;
+      try {
+        mkdirSync(dirname(json), { recursive: true });
+        writeFileSync(tmp, JSON.stringify(current, null, 2) + "\n");
+        renameSync(tmp, json);
+      } catch {
+        /* advisory file — the next touch retries */
+      }
+    },
+    remove() {
+      sealed = true;
+      if (ownsFile()) rmSync(json, { force: true });
+      rmSync(tmp, { force: true });
+    },
+  };
+}
+
+// dev.log writer: SYNCHRONOUS appends — a write can never outlive the
+// session (nothing async to race on shutdown), a full disk degrades to
+// silent log loss instead of an uncaught stream error, and fail()'s
+// process.exit cannot drop the final line. Session-start rotation to
+// dev.log.1, 8 MiB size rotation. Each source() is a line assembler that
+// buffers partial chunks (UTF-8-safe across chunk boundaries), strips ANSI,
+// and stamps HH:MM:SS — terminal mirrors always get the ORIGINAL bytes,
+// only the log is normalized.
+function openDevLog(appDir) {
+  const { log, prevLog } = devPaths(appDir);
+  mkdirSync(dirname(log), { recursive: true });
+  try {
+    renameSync(log, prevLog);
+  } catch {
+    /* first session in this folder */
+  }
+  let bytes = 0;
+  let closed = false;
+  const write = (line) => {
+    if (closed) return;
+    try {
+      appendFileSync(log, line);
+    } catch {
+      return; /* the log must never take the session down */
+    }
+    bytes += Buffer.byteLength(line);
+    if (bytes >= DEV_LOG_MAX_BYTES) {
+      bytes = 0;
+      try {
+        renameSync(log, prevLog);
+      } catch (e) {
+        if (e.code !== "ENOENT") {
+          // Rotation blocked (e.g. dev.log.1 locked on win32): truncate in
+          // place — bounded disk beats an ever-growing log, and followers
+          // recover via their shrink-reopen rule.
+          try {
+            writeFileSync(log, "");
+          } catch {
+            /* still capped at the next cycle */
+          }
+        }
+      }
+      try {
+        appendFileSync(log, `--- log rotated ${new Date().toISOString()} ---\n`);
+      } catch {
+        /* ignore */
+      }
+    }
+  };
+  const stamp = () => new Date().toTimeString().slice(0, 8);
+  const source = (prefix = "") => {
+    const decoder = new StringDecoder("utf8"); // multi-byte chars split across chunks decode intact
+    let buf = "";
+    const emit = (l) => write(`${stamp()} ${prefix}${l.replace(ANSI_RE, "")}\n`);
+    const fn = (chunk) => {
+      buf += typeof chunk === "string" ? chunk : decoder.write(chunk);
+      const lines = buf.split("\n");
+      buf = lines.pop();
+      lines.forEach(emit);
+    };
+    fn.flush = () => {
+      buf += decoder.end();
+      if (buf) {
+        emit(buf);
+        buf = "";
+      }
+    };
+    return fn;
+  };
+  write(`--- monty dev started ${new Date().toISOString()} (pid ${process.pid}) ---\n`);
+  return { source, path: log, close: () => { closed = true; } };
+}
+
+// The vite bin as the APP resolves it, spawned via process.execPath — no npx
+// wrapper, so child.kill() actually kills vite (and win32 avoids the Node>=22
+// .cmd EINVAL). createRequire walks node_modules upward, so hoisted installs
+// (workspace apps like demos/) and pnpm symlink layouts all resolve.
+function resolveViteBin(appDir) {
+  try {
+    const req = createRequire(join(appDir, "package.json"));
+    const pkgPath = req.resolve("vite/package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.vite;
+    if (bin) return join(dirname(pkgPath), bin);
+  } catch {
+    /* not installed anywhere up the tree */
+  }
+  return null;
+}
+
+// Attach output: a fast status glance for agents. Never blocks, always exit 0.
+function printAttach(appDir, s) {
+  const up = fmtDuration(Math.max(0, Math.round((Date.now() - (s.startedAt ?? s.updatedAt)) / 1000)));
+  console.log(`dev: already running for "${s.slug ?? "?"}" — attached, nothing to start (pid ${s.pid}, up ${up})`);
+  if (s.state === "starting") {
+    console.log("state: starting (vite not ready yet — `monty logs -f` to watch)");
+  } else {
+    console.log(`ready: ${s.appUrl ?? `http://localhost:${s.port}`}`);
+    if (!s.loggedIn) {
+      console.log("state: local-only (not logged in — run `monty login`, then `monty dev --takeover`)");
+    } else if (s.state === "online") {
+      const beat = typeof s.lastHeartbeatAt === "number" ? Math.round((Date.now() - s.lastHeartbeatAt) / 1000) : null;
+      console.log(
+        beat !== null && beat > Math.round(DEV_JSON_STALE_MS / 1000)
+          ? `state: online (no heartbeat for ${beat}s — Studio may show offline)`
+          : `state: online (heartbeat ${beat ?? "?"}s ago)`,
+      );
+      if (s.studioUrl) console.log(`studio: ${s.studioUrl} — your app runs there while this is up; click Publish to go Live`);
+    } else {
+      console.log("state: ready (registering with the workspace — the Studio link appears on the first successful heartbeat)");
+    }
+  }
+  console.log("logs: `monty logs -f` follows output; `monty logs -n 100` shows recent lines");
+  const tail = readLogTail(appDir, ATTACH_TAIL_LINES);
+  if (tail.length) {
+    console.log(`log: last ${tail.length} line(s) of .monty/dev.log`);
+    for (const l of tail) console.log(l);
+  } else {
+    console.log("log: (no log lines yet)");
+  }
+  if (flag("port")) console.log(`note: --port ignored — session already on :${s.port} (\`monty dev --takeover\` to restart)`);
+}
+
+// `monty dev --takeover`: stop the recorded session (SIGTERM → SIGKILL; win32
+// has no graceful phase — process.kill is TerminateProcess, so go straight to
+// taskkill /T), free the platform lock with the OLD sessionId (a hard-killed
+// process can't), and hand the folder to a fresh start.
+async function performTakeover(appDir, s) {
+  const signalPid = (pid, sig) => {
+    try {
+      process.kill(pid, sig);
+      return true;
+    } catch (e) {
+      return e.code === "ESRCH";
+    }
+  };
+  const gone = async () =>
+    !pidAlive(s.pid) &&
+    !(Number.isInteger(s.port) && ((await portTaken("127.0.0.1", s.port)) || (await portTaken("::1", s.port))));
+  const waitGone = async (ms) => {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+      if (await gone()) return true;
+      await sleep(200);
+    }
+    return gone();
+  };
+  console.log(`takeover: stopping session pid ${s.pid}…`);
+  if (process.platform === "win32") {
+    spawnSync("taskkill", ["/pid", String(s.pid), "/T", "/F"], { stdio: "ignore" });
+    if (Number.isInteger(s.vitePid)) spawnSync("taskkill", ["/pid", String(s.vitePid), "/T", "/F"], { stdio: "ignore" });
+  } else if (!signalPid(s.pid, "SIGTERM")) {
+    fail("TAKEOVER_FAILED", `The running session (pid ${s.pid}) belongs to another user. Stop it manually, then rerun \`monty dev\`.`);
+  }
+  let ok = await waitGone(TAKEOVER_WAIT_MS);
+  if (!ok && process.platform !== "win32") {
+    console.log("takeover: SIGTERM ignored — escalating to SIGKILL");
+    signalPid(s.pid, "SIGKILL");
+    if (Number.isInteger(s.vitePid)) signalPid(s.vitePid, "SIGKILL");
+    if (Number.isInteger(s.tunnelPid)) signalPid(s.tunnelPid, "SIGKILL");
+    ok = await waitGone(TAKEOVER_WAIT_MS);
+  }
+  if (!ok) {
+    fail("TAKEOVER_PORT_BUSY", `Killed the old session but port ${s.port} is still in use. Wait a few seconds and retry, or run \`monty dev --port <n>\`.`);
+  }
+  console.log(`takeover: session stopped, port ${s.port ?? "?"} free`);
+  // Free the platform lock immediately using the OLD session's id AND host —
+  // after a SIGKILL/taskkill the dead process never got to clear it, the
+  // fresh start would otherwise race the 90s TTL, and the old session may
+  // have been registered against a different host than this shell resolves.
+  const sessionHost = typeof s.host === "string" ? s.host.replace(/\/+$/, "") : null;
+  const key = sessionHost ? (normalizedConfig().profiles[sessionHost]?.key ?? null) : null;
+  if (key && typeof s.slug === "string" && typeof s.sessionId === "string") {
+    try {
+      await fetch(`${sessionHost}/api/dev-session`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+        body: JSON.stringify({ slug: s.slug, sessionId: s.sessionId, end: true }),
+        signal: AbortSignal.timeout(3000),
+      });
+    } catch {
+      /* the bounded claim window covers the TTL race */
+    }
+  }
+  rmSync(devPaths(appDir).json, { force: true }); // ownership death is proven
+}
+
+// A dead CLI pid can leave a LIVE orphaned vite (kill -9 skips endSession).
+// checkDevSession correctly calls that session stale — so --takeover on a
+// stale file sweeps the recorded child pids when the recorded port is still
+// busy, instead of abandoning the port forever.
+async function sweepOrphans(s) {
+  const portBusy = async () =>
+    Number.isInteger(s.port) && ((await portTaken("127.0.0.1", s.port)) || (await portTaken("::1", s.port)));
+  if (!(await portBusy())) return;
+  console.log(`takeover: dead session left port ${s.port} busy — cleaning up its processes`);
+  const signalPid = (pid, sig) => {
+    try {
+      process.kill(pid, sig);
+    } catch {
+      /* already gone or not ours */
+    }
+  };
+  const kids = [s.vitePid, s.tunnelPid].filter((p) => Number.isInteger(p));
+  for (const pid of kids) {
+    if (process.platform === "win32") spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" });
+    else signalPid(pid, "SIGTERM");
+  }
+  let until = Date.now() + TAKEOVER_WAIT_MS;
+  while (Date.now() < until) {
+    if (!(await portBusy())) {
+      console.log(`takeover: port ${s.port} free`);
+      return;
+    }
+    await sleep(200);
+  }
+  if (process.platform !== "win32") {
+    for (const pid of kids) signalPid(pid, "SIGKILL");
+    until = Date.now() + TAKEOVER_WAIT_MS;
+    while (Date.now() < until) {
+      if (!(await portBusy())) {
+        console.log(`takeover: port ${s.port} free`);
+        return;
+      }
+      await sleep(200);
+    }
+  }
+  console.log(`warn: port ${s.port} is still busy after cleanup — picking another port`);
+}
+
 // ── monty dev ──────────────────────────────────────────────────────────────
 // Puts the app in Studio: vite locally + a Cloudflare quick tunnel registered
 // as the app's STUDIO channel, so workspace admins see the app (HMR included)
@@ -564,6 +1209,51 @@ function syncSdkViteCache(appDir) {
 // clicks Publish in the workspace, this process builds + uploads to Live.
 async function dev() {
   const appDir = requireAppDir("dev");
+
+  // Attach check FIRST — before skills/sdk/compile — so a second `monty dev`
+  // is a fast, harmless status glance and can never mutate node_modules
+  // under a live session's vite.
+  const takeover = rest.includes("--takeover");
+  const probe = await checkDevSession(appDir);
+  if (probe.live && !takeover) {
+    printAttach(appDir, probe.session);
+    process.exit(0);
+  }
+  if (probe.live && takeover) {
+    await performTakeover(appDir, probe.session);
+  } else if (probe.session) {
+    console.log(`dev: stale session file from pid ${probe.session.pid} (${probe.reason}) — starting fresh`);
+    if (takeover) {
+      // The stale session's children may have survived it (kill -9 skips
+      // endSession) — sweep them so the recorded port is reclaimable.
+      await sweepOrphans(probe.session);
+    } else if (Number.isInteger(probe.session.port) && (await portTaken("127.0.0.1", probe.session.port))) {
+      console.log(`warn: port ${probe.session.port} is still busy (orphaned vite?) — picking another port; \`monty dev --takeover\` cleans it up`);
+    }
+    rmSync(devPaths(appDir).json, { force: true });
+  } else if (takeover) {
+    console.log("takeover: no running session — starting normally");
+  }
+
+  // Open the log and capture our own output BEFORE the slow steps, so sdk
+  // installs and compile failures land in dev.log for `monty logs`.
+  const logSink = openDevLog(appDir);
+  const cliTee = logSink.source();
+  {
+    const origLog = console.log.bind(console);
+    const origErr = console.error.bind(console);
+    console.log = (...a) => {
+      origLog(...a);
+      cliTee(a.join(" ") + "\n");
+    };
+    console.error = (...a) => {
+      origErr(...a);
+      cliTee(a.join(" ") + "\n");
+    };
+  }
+  console.log("logs: .monty/dev.log (follow with `monty logs -f`)");
+
+  installSkills({ appDir });
   ensureSdk(appDir);
   const meta = await compileConfig(appDir);
   const cfg = loadConfig();
@@ -573,16 +1263,26 @@ async function dev() {
   const requested = flag("port");
   const port = requested ? Number(requested) : await freePort(5173);
 
+  const viteBin = resolveViteBin(appDir);
+  if (!viteBin) {
+    fail("VITE_MISSING", "vite is not installed in this app. Run `monty install`, then `monty dev` again.");
+  }
+
   console.log(`dev: starting vite on :${port} (app "${meta.slug}")`);
-  const child = spawn("npx", ["vite", "dev", "--port", String(port), "--strictPort"], {
+  const child = spawn(process.execPath, [viteBin, "dev", "--port", String(port), "--strictPort"], {
     cwd: appDir,
-    stdio: ["ignore", "pipe", "inherit"],
+    stdio: ["ignore", "pipe", "pipe"],
   });
 
   let tunnelChild = null;
+  let pubChild = null;
   let hbTimer = null;
+  let touchTimer = null;
+  let cronTimer = null;
   let publishing = false;
   let ended = false;
+  let registeredOnce = false;
+  const devStartedAt = Date.now();
   const sessionId = `dev_${randomBytes(16).toString("hex")}`;
   const buildFile = join(appDir, ".monty", "build");
   const buildId = existsSync(buildFile) ? readFileSync(buildFile, "utf8").trim() : undefined;
@@ -593,6 +1293,72 @@ async function dev() {
   const configPath = join(appDir, "monty.config.ts");
   let configMtime = statSync(configPath).mtimeMs;
 
+  // Advertise this session. The touch timer (not the platform heartbeat,
+  // which starts minutes late or never when logged out) keeps updatedAt
+  // fresh so attach/desktop liveness checks stay honest.
+  const loggedIn = Boolean(cfg?.key);
+  const sf = makeSessionFile(appDir, sessionId);
+  sf.write({
+    version: 1,
+    cli: CLI_VERSION,
+    pid: process.pid,
+    vitePid: child.pid ?? null,
+    tunnelPid: null,
+    port,
+    slug: meta.slug,
+    appDir,
+    host,
+    sessionId,
+    state: "starting",
+    loggedIn,
+    appUrl: `http://localhost:${port}`,
+    tunnelUrl: null,
+    studioUrl: loggedIn ? `${host}/studio/${meta.slug}` : null,
+    previewUrl: loggedIn
+      ? `${host}/studio/${meta.slug}?dev=${encodeURIComponent(`http://localhost:${port}`)}`
+      : null,
+    publishing: false,
+    lastHeartbeatAt: null,
+    logFile: logSink.path,
+    startedAt: Date.now(),
+  });
+  touchTimer = setInterval(() => sf.write({}), DEV_JSON_TOUCH_MS);
+
+  // The STUDIO cron runner: the Live counterpart is a real Cloudflare Cron
+  // Trigger on the app's fn-worker; here the CLI matches monty.config.ts
+  // `schedule` entries against the UTC clock once per minute and invokes the
+  // fn through the same /__monty/fn runtime (x-monty-schedule marks the
+  // lane, so ctx.viewer matches Live exactly). Config edits hot-apply via
+  // currentMeta. Fire-and-forget: a failing cron fn prints its instruction
+  // here and never blocks the loop.
+  let lastCronMinute = null;
+  function cronTick() {
+    const sched = currentMeta?.schedule;
+    if (!sched || !loggedIn) return;
+    const now = new Date();
+    const minute = Math.floor(now.getTime() / 60_000);
+    if (minute === lastCronMinute) return;
+    lastCronMinute = minute;
+    for (const [fn, expr] of Object.entries(sched)) {
+      if (!cronMatches(expr, now)) continue;
+      console.log(`cron: "${expr}" → ${fn}() (UTC)`);
+      const t0 = Date.now();
+      fetch(`http://localhost:${port}/__monty/fn/${fn}`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-monty-schedule": expr },
+        body: "{}",
+      }).then(async (r) => {
+        if (r.ok) {
+          console.log(`cron: ${fn} ok (${Date.now() - t0}ms)`);
+        } else {
+          const e = await r.json().catch(() => null);
+          console.log(`cron: ${fn} failed [${e?.code ?? r.status}] ${e?.fix ?? ""}`);
+        }
+      }).catch((e) => console.log(`cron: ${fn} unreachable — ${e?.message ?? e}`));
+    }
+  }
+  cronTimer = setInterval(cronTick, 20_000);
+
   async function refreshSchemaIfChanged() {
     try {
       const m = statSync(configPath).mtimeMs;
@@ -625,7 +1391,15 @@ async function dev() {
     if (ended) return;
     ended = true;
     if (hbTimer) clearInterval(hbTimer);
+    if (touchTimer) clearInterval(touchTimer);
+    if (cronTimer) clearInterval(cronTimer);
+    try { pubChild?.kill(); } catch { /* already gone */ }
     try { tunnelChild?.kill(); } catch { /* already gone */ }
+    // vite is a direct child (no npx wrapper), so this actually kills it —
+    // a bare SIGTERM from the desktop must never orphan vite on the port.
+    try { child.kill(); } catch { /* already gone */ }
+    sf.remove();
+    logSink.close();
     await clearDevSession();
   }
 
@@ -633,23 +1407,39 @@ async function dev() {
     if (ended) return;
     ended = true;
     if (hbTimer) clearInterval(hbTimer);
+    if (touchTimer) clearInterval(touchTimer);
+    if (cronTimer) clearInterval(cronTimer);
+    try { pubChild?.kill(); } catch { /* already gone */ }
     try { tunnelChild?.kill(); } catch { /* already gone */ }
     try { child.kill(); } catch { /* already gone */ }
     console.log(`dev-session: superseded — ${fix}`);
+    sf.remove(); // guarded — never deletes the new owner's file
+    logSink.close();
     setTimeout(() => process.exit(0), 50);
   }
 
   async function heartbeat(originUrl, { claim = false } = {}) {
+    if (ended) return false; // shutdown already ran — no side effects
     await refreshSchemaIfChanged();
     try {
+      // Re-read the key EVERY beat: the desktop (or a fresh `monty login`)
+      // may have replaced an expired key while this session runs — the
+      // session must heal itself, not beat forever with a dead key.
+      const liveKey = loadConfig()?.key ?? cfg.key;
       const r = await fetch(`${host}/api/dev-session`, {
         method: "POST",
-        headers: { authorization: `Bearer ${cfg.key}`, "content-type": "application/json" },
+        headers: { authorization: `Bearer ${liveKey}`, "content-type": "application/json" },
         body: JSON.stringify({
           slug: meta.slug,
           tunnelUrl: originUrl,
           sessionId,
-          claim,
+          // Keep claiming until the first successful registration, but only
+          // within the lock's own 90s TTL window: after a takeover/crash the
+          // old lock may linger, and a single failed first beat must not
+          // strand this session into DEV_SESSION_SUPERSEDED against a dead
+          // owner. BOUNDED so a never-registering session (broken network)
+          // can't steal the lock from a newer active session forever.
+          claim: claim || (!registeredOnce && Date.now() - devStartedAt < 90_000),
           name: currentMeta.name,
           icon: currentMeta.icon,
           buildId,
@@ -667,17 +1457,41 @@ async function dev() {
           return false;
         }
         console.log(`dev-session: ${data?.code ?? r.status}${data?.fix ? ` — ${data.fix}` : ""}`);
+        // A dead key is a SIGNED-OUT session — advertise it so the desktop
+        // (which owns the session) can surface sign-in instead of letting
+        // this line repeat in a log nobody watches.
+        if (data?.code === "INVALID_CLI_KEY" || data?.code === "MISSING_CLI_KEY") {
+          sf.write({ loggedIn: false });
+        }
         return false;
       }
-      if (data?.publishRequested && !publishing) {
+      if (!registeredOnce) {
+        registeredOnce = true;
+        sf.write({ state: "online", loggedIn: true, lastHeartbeatAt: Date.now() });
+      } else {
+        sf.write({ loggedIn: true, lastHeartbeatAt: Date.now() });
+      }
+      if (data?.publishRequested && !publishing && !ended) {
         publishing = true;
+        sf.write({ publishing: true });
         console.log("publish: requested from the workspace — building & uploading…");
+        const pubTee = logSink.source();
         await new Promise((resolve) => {
-          const pub = spawn(process.execPath, [fileURLToPath(import.meta.url), "deploy", "--from-dev"], {
+          pubChild = spawn(process.execPath, [fileURLToPath(import.meta.url), "deploy", "--from-dev"], {
             cwd: appDir,
-            stdio: ["ignore", "inherit", "inherit"],
+            stdio: ["ignore", "pipe", "pipe"],
+          });
+          pubChild.stdout.on("data", (c) => {
+            process.stdout.write(c);
+            pubTee(c);
           });
-          pub.on("exit", (code) => {
+          pubChild.stderr.on("data", (c) => {
+            process.stderr.write(c);
+            pubTee(c);
+          });
+          pubChild.on("exit", (code) => {
+            pubChild = null;
+            pubTee.flush();
             console.log(
               code === 0
                 ? "publish: done — the app is Live for the workspace (Studio session continues)"
@@ -687,6 +1501,7 @@ async function dev() {
           });
         });
         publishing = false;
+        sf.write({ publishing: false });
       }
       return true;
     } catch {
@@ -708,6 +1523,9 @@ async function dev() {
       const version = ++tunnelVersion;
       if (!initial) {
         console.log(`tunnel: changed to ${url}`);
+        // The old public URL is dead the moment cloudflared rotated — stop
+        // advertising it while DNS gating runs (it can fail for minutes).
+        sf.write({ tunnelUrl: null });
         await clearDevSession();
       }
       console.log("tunnel: waiting for DNS to go live (prevents cached failures in your browser)…");
@@ -722,6 +1540,7 @@ async function dev() {
         return "failed";
       }
       originUrl = url;
+      sf.write({ tunnelUrl: url });
       console.log(initial ? "tunnel: DNS live" : "tunnel: DNS live; Studio URL updated");
       if (!initial && !(await heartbeat(originUrl))) {
         console.log("dev-session: Studio still has no registered tunnel; the next heartbeat will retry");
@@ -738,8 +1557,12 @@ async function dev() {
     };
     if (!rest.includes("--no-tunnel")) {
       console.log("tunnel: starting (cloudflared quick tunnel)…");
-      const t = await startTunnel(port, registerTunnelUrl);
+      // cloudflared output is teed to dev.log only (the terminal stays quiet,
+      // exactly as today) — post-mortems get the tunnel noise.
+      const cloudflaredTee = logSink.source("cloudflared: ");
+      const t = await startTunnel(port, registerTunnelUrl, cloudflaredTee);
       tunnelChild = t.child;
+      sf.write({ tunnelPid: t.child?.pid ?? null });
       if (t.url) {
         console.log(`tunnel: ${t.url}`);
         await activateTunnelUrl(t.url, { initial: true });
@@ -757,17 +1580,37 @@ async function dev() {
   }
 
   let announced = false;
+  const viteOutTee = logSink.source();
+  const viteErrTee = logSink.source();
   child.stdout.on("data", (chunk) => {
     const text = chunk.toString();
     process.stdout.write(text);
-    if (!announced && /localhost:\d+/.test(text)) {
+    viteOutTee(chunk);
+    // Strip ANSI before scanning: under FORCE_COLOR/colorized environments
+    // (Solo, some CI ptys) vite colors the URL and the escape codes land
+    // BETWEEN "localhost:" and the digits — the raw text never matches.
+    if (!announced && /localhost:\d+/.test(text.replace(ANSI_RE, ""))) {
       announced = true;
+      sf.write({ state: "ready" });
       console.log(`data: sandboxed to "${meta.slug}#dev" (Studio sandbox; Live records untouched)`);
       console.log(`ready: http://localhost:${port}`);
       void startDevSession();
     }
   });
+  // vite stderr is where build errors and the SDK's browser-error mirror
+  // land — piped (was inherit) so `monty logs` sees them too.
+  child.stderr.on("data", (chunk) => {
+    process.stderr.write(chunk);
+    viteErrTee(chunk);
+  });
+  child.on("error", (e) => {
+    void endSession().then(() => {
+      fail("VITE_SPAWN_FAILED", `Could not start vite: ${e?.message ?? e}. Run \`monty install\`, then retry.`);
+    });
+  });
   child.on("exit", (code) => {
+    viteOutTee.flush();
+    viteErrTee.flush();
     void endSession().then(() => process.exit(code ?? 0));
   });
   process.on("SIGINT", () => {
@@ -776,9 +1619,132 @@ async function dev() {
   process.on("SIGTERM", () => {
     void endSession().then(() => process.exit(143));
   });
+  // Closing the terminal window (SIGHUP) and unexpected crashes must clean
+  // up too — every stale dev.json is a lie to the next `monty dev`.
+  process.on("SIGHUP", () => {
+    void endSession().then(() => process.exit(129));
+  });
+  process.on("uncaughtException", (e) => {
+    console.error(`dev: unexpected error — ${e?.stack ?? e}`);
+    void endSession().then(() => process.exit(1));
+  });
+  process.on("unhandledRejection", (e) => {
+    console.error(`dev: unexpected error — ${e?.stack ?? e}`);
+    void endSession().then(() => process.exit(1));
+  });
 }
 
 
+// ── monty logs ─────────────────────────────────────────────────────────────
+// The agent's window into the (possibly background) dev shell: pure file
+// reads over .monty/dev.log — no skills refresh, no sdk, no compile, no
+// network. stdout carries ONLY log lines (every note goes to stderr), so
+// `monty logs | grep …` stays clean.
+async function logs() {
+  const appDir = requireAppDir("logs");
+  const { log, prevLog } = devPaths(appDir);
+  const follow = rest.includes("-f") || rest.includes("--follow");
+  const nIdx = rest.indexOf("-n");
+  const n = nIdx >= 0 ? Number(rest[nIdx + 1]) : LOGS_DEFAULT_LINES;
+  if (!Number.isInteger(n) || n < 0 || n > 10000) {
+    fail("LOGS_USAGE", "Usage: monty logs [-n <lines>] [-f] — <lines> is a non-negative integer (default 50).");
+  }
+  const note = (m) => process.stderr.write(`${m}\n`);
+
+  const s = await readDevJson(appDir);
+  const sessionLive =
+    s !== null &&
+    !s.unreadable &&
+    Number.isInteger(s.pid) &&
+    pidAlive(s.pid) &&
+    typeof s.updatedAt === "number" &&
+    Date.now() - s.updatedAt <= DEV_JSON_STALE_MS;
+
+  if (!existsSync(log)) {
+    if (sessionLive && follow) {
+      note("note: dev session starting — waiting for the log file…");
+    } else if (sessionLive) {
+      note("note: dev session starting — no log yet (`monty logs -f` waits for it)");
+      return;
+    } else if (existsSync(prevLog)) {
+      note("note: no dev session is running — the previous session's log is .monty/dev.log.1");
+      return;
+    } else {
+      fail("NO_DEV_LOG", "No dev session has run in this app folder yet. Start one with `monty dev`.");
+    }
+  } else if (!sessionLive && !(await checkDevSession(appDir)).live) {
+    // The cheap pid+fresh check false-negatives right after a laptop wake —
+    // only print the note once the full liveness check (port + vite probe)
+    // agrees the session is gone.
+    note("note: no dev session is running — showing the last session's log (start one with `monty dev`)");
+  }
+
+  let offset = 0;
+  let lastIno = null;
+  if (existsSync(log)) {
+    const content = readFileSync(log, "utf8");
+    offset = Buffer.byteLength(content);
+    try {
+      lastIno = statSync(log).ino;
+    } catch {
+      /* raced a rotation — the poll loop resyncs */
+    }
+    if (n > 0) {
+      const lines = content.split("\n");
+      while (lines.length && lines[lines.length - 1] === "") lines.pop();
+      for (const l of lines.slice(-n)) process.stdout.write(`${l}\n`);
+    }
+  }
+  if (!follow) return;
+
+  // Follow by polling the PATH (never a held fd): a rotation shrinks the
+  // file (reopen at 0 — the fresh file starts with a marker, nothing
+  // replays), a restart repopulates the same path, transient ENOENT is the
+  // rename window. fs.watch is deliberately not used (platform-flaky,
+  // inode-bound across rotation).
+  let partial = "";
+  setInterval(() => {
+    let st;
+    try {
+      st = statSync(log);
+    } catch {
+      return;
+    }
+    // A new inode at the same path = rotation or session restart — reopen at
+    // 0 even when the fresh file already grew past our old offset.
+    if (lastIno !== null && st.ino !== lastIno) {
+      offset = 0;
+      partial = "";
+    }
+    lastIno = st.ino;
+    const size = st.size;
+    if (size < offset) {
+      offset = 0;
+      partial = "";
+    }
+    if (size === offset) return;
+    let fd;
+    try {
+      fd = openSync(log, "r");
+    } catch {
+      return;
+    }
+    try {
+      const buf = Buffer.alloc(size - offset);
+      const read = readSync(fd, buf, 0, buf.length, offset);
+      offset += read;
+      const text = partial + buf.toString("utf8", 0, read);
+      const lines = text.split("\n");
+      partial = lines.pop();
+      for (const l of lines) process.stdout.write(`${l}\n`);
+    } finally {
+      closeSync(fd);
+    }
+  }, LOGS_POLL_MS);
+  process.on("SIGINT", () => process.exit(0));
+  process.on("SIGTERM", () => process.exit(0));
+}
+
 // trycloudflare DNS takes up to a couple of minutes to propagate. Registering
 // the origin before it resolves would make admins' browsers cache NXDOMAIN
 // (macOS negative cache ≈ 30 min of a broken iframe) — so gate on DNS via
@@ -816,13 +1782,15 @@ async function waitForDns(hostname) {
 
 // Cloudflare quick tunnel via the cloudflared npm wrapper (downloads the
 // binary on first use). Resolves with the public URL, or null on failure —
-// Studio then falls back to localhost-only registration.
-function startTunnel(port, onUrlChange) {
+// Studio then falls back to localhost-only registration. onOutput receives
+// every chunk (both fds) for the dev.log tee.
+function startTunnel(port, onUrlChange, onOutput) {
   return new Promise((resolve) => {
     let child;
     try {
       child = spawn("npx", ["-y", "cloudflared", "tunnel", "--url", `http://localhost:${port}`], {
         stdio: ["ignore", "pipe", "pipe"],
+        shell: process.platform === "win32", // Node >=22 refuses .cmd spawns without it
       });
     } catch {
       return resolve({ child: null, url: null });
@@ -836,7 +1804,9 @@ function startTunnel(port, onUrlChange) {
     }, 45_000);
     let currentUrl = null;
     const scan = (chunk) => {
-      const urls = String(chunk).match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/g) ?? [];
+      onOutput?.(chunk);
+      // Same ANSI hazard as the vite ready-scan: match on stripped text.
+      const urls = String(chunk).replace(ANSI_RE, "").match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/g) ?? [];
       for (const url of urls) {
         if (url === currentUrl) continue;
         currentUrl = url;
@@ -1039,11 +2009,54 @@ async function deploy() {
   // 3a) Server functions (optional): bundle server/index.ts into one worker
   //     script and ride the SAME deploy. The manifest (fns) goes in meta so
   //     the router gates /__monty/fn/* without a lookup.
-  const serverBundle = await bundleServerFns(appDir);
+  const serverBundle = await bundleServerFns(appDir, meta.schedule);
+  const publicFns = Array.isArray(meta.publicFns) ? meta.publicFns : [];
+  const scheduleEntries = Object.entries(meta.schedule ?? {});
+  if (!serverBundle && (publicFns.length > 0 || scheduleEntries.length > 0)) {
+    fail("SERVER_DIR_MISSING",
+      "monty.config.ts declares publicFns/schedule, but this app has no server/index.ts. Create it with the named exports, or remove the declarations.");
+  }
   if (serverBundle) {
+    for (const name of publicFns) {
+      if (!serverBundle.fns.includes(name)) {
+        fail("PUBLIC_FN_UNKNOWN",
+          `publicFns names "${name}" but server/index.ts exports no such function. Export it (e.g. \`export async function ${name}(req, ctx) {…}\`) or remove it from monty.config.ts.`);
+      }
+    }
+    for (const [name] of scheduleEntries) {
+      if (!serverBundle.fns.includes(name)) {
+        fail("SCHEDULE_UNKNOWN_FN",
+          `schedule targets "${name}" but server/index.ts exports no such function. Export it (e.g. \`export async function ${name}(args, ctx) {…}\`) or remove the entry from monty.config.ts.`);
+      }
+    }
     meta.fns = serverBundle.fns;
     form.set("server-worker", new Blob([serverBundle.code]), "server-worker.mjs");
     console.log(`fns: bundled ${serverBundle.fns.length} server function(s) (${serverBundle.fns.join(", ")})`);
+    if (publicFns.length > 0) {
+      console.log(`public: ${publicFns.map((f) => `/__monty/public/${f}`).join(", ")} — open to the internet; verify signatures in the function`);
+    }
+    if (scheduleEntries.length > 0) {
+      console.log(`schedule: ${scheduleEntries.map(([f, c]) => `${f} @ "${c}"`).join(", ")} (UTC; Live cron changes can take ~15 min to propagate)`);
+    }
+  }
+  // 3b) SOURCE snapshot rides every publish. Without it the platform keeps
+  // only the minified bundle and the sole copy of the app's code is this
+  // folder — delete it and the source is gone forever. The snapshot is what
+  // `monty pull <slug>` restores on any machine, and the publish lands in
+  // the same version history as `monty commit`.
+  let sourceHash = null;
+  {
+    const packed = packSource(appDir);
+    if (packed === null) {
+      console.log("source: WARNING — could not pack a snapshot (tar failed); `monty pull` will not work for this publish.");
+    } else if (packed.tooLarge) {
+      console.log("source: WARNING — snapshot exceeds 10 MB, skipped; `monty pull` will not work for this app. Remove large assets from the app folder.");
+    } else {
+      sourceHash = packed.hash;
+      meta.sourceHash = sourceHash;
+      form.set("source", new Blob([packed.buf]), "source.tar.gz");
+      console.log(`source: ${(packed.buf.byteLength / 1024).toFixed(0)} KB snapshot rides this publish (restore anywhere: monty pull ${meta.slug})`);
+    }
   }
   form.set("monty", JSON.stringify(meta));
   let total = 0;
@@ -1065,13 +2078,21 @@ async function deploy() {
   }
   console.log(`origin: ${body.origin}`);
   console.log(`deployed: ${body.url} (version ${body.version})`);
+  // Stamp what was published — pull uses this to tell "unchanged since last
+  // sync" from "locally modified".
+  if (sourceHash) {
+    writeFileSync(
+      join(appDir, ".monty", "source.json"),
+      JSON.stringify({ hash: sourceHash, syncedAt: Date.now() }) + "\n",
+    );
+  }
 }
 
 // Bundle server/index.ts (if present) into ONE Worker script: a generated
 // entry wraps the app's exports with @montytools/sdk/fn-worker's makeFnWorker,
 // esbuild bundles it for workerd. node: imports are rejected at compile time
 // — Live runs on Cloudflare Workers, not Node. Returns { code, fns } or null.
-async function bundleServerFns(appDir) {
+async function bundleServerFns(appDir, schedule) {
   const serverEntry = join(appDir, "server", "index.ts");
   if (!existsSync(serverEntry)) return null;
   const { build } = await import("esbuild");
@@ -1079,10 +2100,13 @@ async function bundleServerFns(appDir) {
   mkdirSync(tmpDir, { recursive: true });
   const entry = join(tmpDir, "fn-worker-entry.mjs");
   const out = join(tmpDir, "fn-worker-out.mjs");
+  // The schedule map is baked into the bundle: Cloudflare's scheduled()
+  // hands back only the matching cron expression, so the worker needs the
+  // expression→fn mapping at runtime.
   writeFileSync(entry, [
     `import * as appFns from "../server/index";`,
     `import { makeFnWorker } from "@montytools/sdk/fn-worker";`,
-    `export default makeFnWorker(appFns);`,
+    `export default makeFnWorker(appFns, { schedule: ${JSON.stringify(schedule ?? {})} });`,
   ].join("\n"));
   // Fail the deploy if server code reaches for Node built-ins — a Worker
   // can't run them, and a silent runtime crash on Live is the worst outcome.
@@ -1180,9 +2204,70 @@ function walk(dir) {
   return out;
 }
 
+// ── cron matching (the Studio ticker in `monty dev`) ──────────────────────
+// UTC, 5 fields, standard syntax: *  a,b  a-b  */n  a-b/n  plus month/day
+// names (JAN, MON). Deliberately forgiving: an unparsable field simply never
+// matches locally — Cloudflare is the syntax authority at deploy, so a bad
+// expression fails there with its own message.
+const CRON_MONTHS = { jan: 1, feb: 2, mar: 3, apr: 4, may: 5, jun: 6, jul: 7, aug: 8, sep: 9, oct: 10, nov: 11, dec: 12 };
+const CRON_DAYS = { sun: 0, mon: 1, tue: 2, wed: 3, thu: 4, fri: 5, sat: 6 };
+
+function cronMatches(expr, date) {
+  const fields = String(expr).trim().split(/\s+/);
+  if (fields.length !== 5) return false;
+  const values = [
+    date.getUTCMinutes(),
+    date.getUTCHours(),
+    date.getUTCDate(),
+    date.getUTCMonth() + 1,
+    date.getUTCDay(),
+  ];
+  const bounds = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 7]];
+  return fields.every((field, i) => cronFieldMatches(field, values[i], bounds[i], i));
+}
+
+function cronFieldMatches(field, value, [lo, hi], idx) {
+  const names = idx === 3 ? CRON_MONTHS : idx === 4 ? CRON_DAYS : null;
+  const num = (t) => {
+    const named = names?.[t.toLowerCase()];
+    if (named !== undefined) return named;
+    const n = Number(t);
+    return Number.isInteger(n) ? n : null;
+  };
+  for (const part of field.split(",")) {
+    const [rangeRaw, stepRaw] = part.split("/");
+    const step = stepRaw === undefined ? 1 : Number(stepRaw);
+    if (!Number.isInteger(step) || step < 1) continue;
+    let from;
+    let to;
+    if (rangeRaw === "*" || rangeRaw === "") {
+      from = lo;
+      to = hi;
+    } else if (rangeRaw.includes("-")) {
+      const [a, b] = rangeRaw.split("-");
+      from = num(a);
+      to = num(b);
+    } else {
+      from = num(rangeRaw);
+      to = stepRaw === undefined ? from : hi; // "5/10": from 5 to max, step 10
+    }
+    if (from === null || to === null || from > to) continue;
+    for (let v = from; v <= to; v += step) {
+      // day-of-week: cron accepts 7 for Sunday alongside 0
+      if (v === value || (idx === 4 && v === 7 && value === 0)) return true;
+    }
+  }
+  return false;
+}
+
 // ── dispatch ───────────────────────────────────────────────────────────────
 // Keep agent skills fresh on every invocation (user level + current app).
-installSkills({ appDir: findAppRoot(process.cwd()) });
+// `dev` and `logs` skip the refresh here: attach and log reads must stay
+// fast (a skills refresh can shell out to npx for two minutes) — dev's
+// fresh-start path installs skills itself once it owns the session.
+if (command !== "dev" && command !== "logs") {
+  installSkills({ appDir: findAppRoot(process.cwd()) });
+}
 
 switch (command) {
   case "login":
@@ -1191,9 +2276,22 @@ switch (command) {
   case "create":
     await create();
     break;
+  case "pull":
+    await pull();
+    break;
+  case "commit":
+    await commit();
+    break;
+  case "log":
+  case "versions":
+    await versionsLog();
+    break;
   case "dev":
     await dev();
     break;
+  case "logs":
+    await logs();
+    break;
   case "add":
     await add();
     break;
@@ -1233,16 +2331,20 @@ switch (command) {
     await secret();
     break;
   default:
-    console.log("usage: monty <login|create|current|select|apps|install|dev|build|typecheck|add|components|docs|deploy|skills>");
+    console.log("usage: monty <login|create|pull|commit|log|current|select|apps|install|dev|logs|build|typecheck|add|components|docs|deploy|skills>");
     console.log("  login       [--host <url>] [--key <mk_...>]  sign in (opens your browser to authorize)");
-    console.log("  create      <slug> [--name N] [--icon I] [--build ID]  stamp a new app into ~/Monty/<slug>");
-    console.log("  dev         [--port N]                      run the app in Studio locally, auto-picks a free port (sandboxed data)");
+    console.log("  create      <slug> [--name N] [--icon I] [--build ID]  register + stamp a new app into ~/.monty/apps/<id> (needs login)");
+    console.log("  pull        <slug> [--version H] [--force]  restore the app's source snapshot (latest, or one from `monty log`)");
+    console.log("  commit      [-m \"message\"]                  version the app's source in the workspace without publishing");
+    console.log("  log         [slug]                          the app's source version history (commits + publishes)");
+    console.log("  dev         [--port N] [--no-tunnel] [--takeover]  run the app in Studio, or attach to a running session (sandboxed data)");
+    console.log("  logs        [-n N] [-f]                     read/follow the dev shell log (vite output, browser errors, publish results)");
     console.log("  add         <name...>                      install curated UI components (see `monty components`)");
     console.log("  components  [query]                        list the curated component catalog");
     console.log("  docs        <name>                         view a component's source before installing");
     console.log("  current                                     which app folder am I in?");
     console.log("  select      <slug>                          print an app's folder — cd \"$(monty select x)\"");
-    console.log("  apps                                        list local apps in ~/Monty");
+    console.log("  apps                                        list local apps (~/.monty/apps + legacy ~/Monty)");
     console.log("  install                                     install app dependencies");
     console.log("  build                                       production build (vite, via monty)");
     console.log("  typecheck                                   typecheck (builds first if needed)");