@stechquick/studio-cli 4.2.0-0 → 4.2.0-1

package/dist/studio-cli/src/server/bridgeServer.js

@@ -6,98 +6,174 @@ const node_path_1 = require("node:path");
 const wsRaw_1 = require("./wsRaw");
 const peer_1 = require("./peer");
 const serverInfo_1 = require("./serverInfo");
+const pickWorkspaceDir_1 = require("../control/pickWorkspaceDir");
 const logger_1 = require("../util/logger");
+const qjsonCompiled_1 = require("../../../common/agentic/modelFiles/qjsonCompiled");
+const jsonBody_1 = require("../../../common/agentic/modelFiles/jsonBody");
 const pull_1 = require("../control/pull");
 const push_1 = require("../control/push");
 const state_1 = require("../util/state");
-const frontmatter_1 = require("../util/frontmatter");
-const modelRef_1 = require("../util/modelRef");
+const trash_1 = require("../util/trash");
+const frontmatter_1 = require("../../../common/agentic/modelFiles/frontmatter");
+const modelRefs_1 = require("../../../common/agentic/modelFiles/modelRefs");
 const version_1 = require("../version");
-const protocolVersion_1 = require("../../../common/studioCli/protocolVersion");
+const protocolVersion_1 = require("../../../common/agentic/studioCli/protocolVersion");
 const PING_INTERVAL_MS = 20000;
-const PORT_RANGE_END = 7350;
+// A peer that sends no frame at all for this long is treated as dead. Deliberately generous
+// (15 missed pings), and one value for every peer in every state — the harm is lopsided. A
+// leftover process is a background annoyance nobody watches in real time, but a false drop is
+// instant and costly: the primary has NO periodic reconnect (ui .../studioCli/index.ts only
+// retries on app-open), so the user must reconnect by hand. Two things block a live browser's
+// main thread long enough to look dead — a paused DevTools breakpoint, and one heavy synchronous
+// step of a push — and a single limit this generous covers both without a special case.
+const PEER_SILENCE_LIMIT_MS = 300000;
+// A sweep landing this late means the HOST was suspended (laptop lid), not that peers fell silent.
+const SUSPEND_GAP_MS = PING_INTERVAL_MS * 2;
+const IDLE_EXIT_MS = 120000;
+const RENDEZVOUS_BIND_RETRY_MS = 2000;
 /**
- * Lokal WebSocket server (santral). Tek bridge client (browser) + ileride kısa-ömürlü
- * control client'lar. Port-range keşfi + `.studio/server.json` claim + tipli dispatch.
+ * Local WebSocket server (hub). One bridge client (browser) + short-lived
+ * control clients later. Port-range discovery + `.studio/server.json` claim + typed dispatch.
  */
 class BridgeServer {
     wss;
+    // Fixed rendezvous port listener — when the web connects here it announces the ephemeral port, then it is released.
+    rendezvousWss;
     bridgeClient;
-    // AI test tarayıcısı (?cliRole=test) — SINK: event göndermez, yalnız syncModels alır.
+    // AI test browser (?cliRole=test) — SINK: sends no events, only receives syncModels.
     testClient;
-    // Bu oturumda push'lanan gövdeler (id → item, push'lar arası merge). Test client sonradan
-    // bağlanınca / F5'te replay edilir — sync, bağlanma sırasından bağımsız çalışır.
+    // Every live peer on the ephemeral port, including ones that have not said hello yet.
+    // The ping/reap loop walks THIS, not the two named slots: a peer that connects and then
+    // goes silent before hello belongs to neither slot and would otherwise never be reaped.
+    // (Rendezvous peers are not here — they live on their own server and self-close in 500ms.)
+    peers = new Set();
+    // Bodies pushed in this session (id → item, merged across pushes). Replayed when the test client
+    // connects later / on F5 — sync works regardless of connection order.
     lastSync = new Map();
-    // GET /render hedefi — primary hello'dan gelir, YALNIZ BELLEKTE tutulur (server.json'a yazılmaz:
-    // workspace dosyaları agent'a/git'e açıktır, oturum bilgisi diske inmez).
+    // GET /render target — comes from the primary hello, kept IN MEMORY ONLY (not written to server.json:
+    // workspace files are exposed to the agent/git, session info must not hit disk).
     renderTarget;
     claimedAppId;
     pingTimer;
+    lastTickAt = 0; // when the last ping sweep ran — detects host suspend (see pingTick)
+    idleTimer;
+    rendezvousRetryTimer;
     _pushInProgress = false;
-    // Push'un checkout ettiği (yeni yaratılan) model id'leri. studio.checkout → checkoutChangedHook
-    // echo'su reply'dan SONRA da gelebildiği için (_pushInProgress yetmez); bu id'lerin checkoutChanged'i
-    // id bazında, consume-once bastırılır → zamanlamadan bağımsız, manuel checkout'lar etkilenmez.
+    // Model ids checked out by the push (newly created). Because the studio.checkout → checkoutChangedHook
+    // echo can also arrive AFTER the reply (_pushInProgress isn't enough); the checkoutChanged for these ids is
+    // suppressed per-id, consume-once → timing-independent, manual checkouts are unaffected.
     _expectedCheckoutEchoes = new Set();
     _deferredModelCreated = [];
     _deferredModelChanged = [];
+    _pickerOpen = false;
+    trashQueue = new trash_1.TrashQueue();
     host;
-    startPort;
-    port = 0; // gerçekte bağlanan port (start() doldurur)
+    port = 0; // ephemeral port assigned by the OS (bind() fills it in)
     rootDir;
-    constructor(options) {
+    constructor(options = {}) {
         this.host = options.host ?? "127.0.0.1";
-        this.startPort = options.port;
         this.rootDir = options.rootDir;
     }
+    get workspaceDir() {
+        if (this.rootDir === undefined)
+            throw new Error("no workspace selected");
+        return this.rootDir;
+    }
     async start() {
-        // Önceki (çökmüş) server'dan kalma claim'i temizle — bu fresh bir server.
-        //TODO: bunu burada yapmanin yan etkilerini dusun. 
-        (0, serverInfo_1.removeServerInfoSync)(this.rootDir);
+        // Clear the runtime claim (port/pid) left over from a previous (crashed) server — this is a fresh
+        // server. The appId binding is kept.
+        //TODO: think about the side effects of doing this here.
+        if (this.rootDir !== undefined)
+            (0, serverInfo_1.clearServerInfoRuntimeSync)(this.rootDir);
         await this.bind();
         logger_1.logger.info(`bridge listening on ws://${this.host}:${this.port}`);
+        await this.bindRendezvous();
         logger_1.logger.info("waiting for Studio web to connect…");
+        this.armIdleExit();
+    }
+    // Listen on the fixed rendezvous port. When the web connects it announces the ephemeral bridge port, then we
+    // release the port (another CLI can use it). If the port is in use (another CLI holds it) silently skip.
+    async bindRendezvous() {
+        const wss = new wsRaw_1.RawWebSocketServer({ host: this.host, port: protocolVersion_1.RENDEZVOUS_PORT });
+        // Announce the ephemeral port when the web connects. Do NOT close the rendezvous HERE — it is closed once the
+        // web connects to the ephemeral port and becomes a live client via hello (onHello → closeRendezvous). This way
+        // if the web can't reach the ephemeral port it can retry via the rendezvous.
+        wss.onConnection((conn) => {
+            new peer_1.Peer(conn).send("rendezvous", { port: this.port });
+            logger_1.logger.info(`rendezvous → announced port ${this.port}`);
+            setTimeout(() => conn.close(1000, "rendezvous done"), 500); // let the frame flush
+        });
+        try {
+            await wss.listen();
+            this.rendezvousWss = wss;
+            logger_1.logger.info(`rendezvous listening on ws://${this.host}:${protocolVersion_1.RENDEZVOUS_PORT}`);
+        }
+        catch (err) {
+            wss.close();
+            if (err.code === "EADDRINUSE") {
+                // Another CLI is already the discovery point. If this is a protocol-launch (no folder) this instance is
+                // redundant — the web finds the rendezvous holder, not this one → exit so it doesn't stay orphaned. If
+                // launched manually with `--dir <path>` (rootDir set) don't exit; the user opened it deliberately, reachable via savedPort.
+                if (this.rootDir === undefined) {
+                    logger_1.logger.info(`rendezvous ${protocolVersion_1.RENDEZVOUS_PORT} held by another CLI — redundant launch, exiting`);
+                    this.close();
+                    process.exit(0);
+                }
+                logger_1.logger.info(`rendezvous ${protocolVersion_1.RENDEZVOUS_PORT} in use — will retry in ${RENDEZVOUS_BIND_RETRY_MS / 1000}s`);
+                this.rendezvousRetryTimer = setTimeout(() => void this.bindRendezvous(), RENDEZVOUS_BIND_RETRY_MS);
+            }
+            else {
+                logger_1.logger.error(`rendezvous bind failed: ${err.message}`);
+            }
+        }
+    }
+    closeRendezvous() {
+        if (this.rendezvousRetryTimer) {
+            clearTimeout(this.rendezvousRetryTimer);
+            this.rendezvousRetryTimer = undefined;
+        }
+        this.rendezvousWss?.close();
+        this.rendezvousWss = undefined;
     }
     close() {
         this.stopPing();
+        this.cancelIdleExit();
+        this.trashQueue.dispose();
+        (0, pickWorkspaceDir_1.killActivePicker)();
+        this.closeRendezvous();
         this.bridgeClient?.close(1001, "cli shutting down");
         this.testClient?.close(1001, "cli shutting down");
         this.wss?.close();
-        (0, serverInfo_1.removeServerInfoSync)(this.rootDir);
+        if (this.rootDir !== undefined)
+            (0, serverInfo_1.clearServerInfoRuntimeSync)(this.rootDir);
     }
-    /** İlk boş portu bind et (startPort … PORT_RANGE_END). Hepsi doluysa hata. */
+    /** Bind to the ephemeral port assigned by the OS (port:0 → the OS picks a free port). The web learns the port via the rendezvous. */
     async bind() {
-        const end = Math.max(this.startPort, PORT_RANGE_END);
-        for (let p = this.startPort; p <= end; p++) {
-            const wss = new wsRaw_1.RawWebSocketServer({ host: this.host, port: p });
-            wss.onConnection((conn) => this.onConnection(conn));
-            wss.onRequest((req, res) => this.routeRequest(req, res));
-            try {
-                await wss.listen();
-                this.wss = wss;
-                this.port = p;
-                return;
-            }
-            catch (err) {
-                wss.close();
-                if (err.code === "EADDRINUSE") {
-                    logger_1.logger.debug(`port ${p} in use — trying next`);
-                    continue;
-                }
-                throw err;
-            }
-        }
-        throw new Error(`no free port in ${this.startPort}-${end}`);
+        const wss = new wsRaw_1.RawWebSocketServer({ host: this.host, port: 0 });
+        wss.onConnection((conn) => this.onConnection(conn));
+        wss.onRequest((req, res) => this.routeRequest(req, res));
+        await wss.listen();
+        this.wss = wss;
+        this.port = wss.boundPort;
     }
-    // --- bağlantı yaşam döngüsü ---
+    // --- connection lifecycle ---
     onConnection(conn) {
         const peer = new peer_1.Peer(conn);
+        this.peers.add(peer);
         peer.onEnvelope((env) => this.dispatch(peer, env));
         peer.onClose(() => this.onPeerClose(peer));
         logger_1.logger.debug("peer connected");
+        // Start pinging at CONNECT, not at hello — otherwise a peer that never handshakes is
+        // never probed and leaks a socket for the lifetime of the process.
+        this.startPing();
     }
     onPeerClose(peer) {
+        this.peers.delete(peer);
         if (peer === this.bridgeClient) {
-            // F5/sayfa kapanması: client gider ama claim + server.json KALIR (reconnect için).
+            // F5/page close: the client goes away but the claim + server.json REMAIN (for reconnect).
+            // If the tab closed while the picker was open, close the orphaned window (its result will be dropped anyway).
+            if (this._pickerOpen)
+                (0, pickWorkspaceDir_1.killActivePicker)();
             this.bridgeClient = undefined;
             logger_1.logger.info("bridge client disconnected (claim kept for reconnect)");
         }
@@ -105,27 +181,34 @@ class BridgeServer {
             this.testClient = undefined;
             logger_1.logger.info("test client disconnected");
         }
+        // Idle exit tracks the CLIENT slots — a bare peer is not a session. The ping loop tracks
+        // the registry instead, so a silent pre-hello peer keeps being probed until it is reaped.
         if (!this.bridgeClient && !this.testClient)
+            this.armIdleExit();
+        if (this.peers.size === 0)
             this.stopPing();
     }
     // --- dispatch ---
     dispatch(peer, env) {
         switch (env.type) {
             case "whoAreYou":
-                /** Probe — yan etki YOK; mevcut durumu + protokol/sürümü bildirir (claim etmez).
-                 * Uyumluluk kontrolü UI'da bu cevaba göre yapılır (bkz. docs/PROTOCOL-VERSION-CHECK.md). */
+                /** Probe — NO side effects; reports the current state + protocol/version (does not claim).
+                 * The compatibility check is done in the UI based on this reply (see docs/PROTOCOL-VERSION-CHECK.md). */
                 peer.reply(env, "whoAreYouResult", { hasClient: this.bridgeClient?.isOpen ?? false, hasTestClient: this.testClient?.isOpen ?? false, appId: this.claimedAppId ?? null, protocol: protocolVersion_1.GENERATION, cliVersion: version_1.VERSION });
                 return;
             case "hello":
                 this.onHello(peer, env);
                 return;
+            case "pickFolder":
+                void this.onPickFolder(peer, env);
+                return;
             case "ping":
                 peer.reply(env, "pong", {});
                 return;
             case "pong":
                 return;
             case "bye":
-                // Yalnız PRIMARY'nin bye'ı server'ı kapatır; test client'ın gidişi slotu boşaltır.
+                // Only the PRIMARY's bye shuts down the server; the test client leaving just frees the slot.
                 if (peer === this.testClient) {
                     logger_1.logger.info(`test client said bye (${env.payload.reason})`);
                     this.testClient = undefined;
@@ -165,8 +248,8 @@ class BridgeServer {
                 logger_1.logger.warn(`unhandled message type: ${env.type}`);
         }
     }
-    /** Dosya yazan event'ler yalnız primary'den kabul edilir (test SINK'tir; web tarafı zaten
-     *  göndermez — bu ikinci emniyet). */
+    /** File-writing events are only accepted from the primary (test is a SINK; the web side doesn't send
+     *  them anyway — this is a second safeguard). */
     isPrimary(peer) {
         if (peer === this.bridgeClient)
             return true;
@@ -175,22 +258,22 @@ class BridgeServer {
     }
     onHello(peer, env) {
         const p = env.payload;
-        // Protokol uyumluluğu UI tarafında whoAreYou probe'unda çözülür; hello'ya gelindiyse taraflar
-        // zaten uyumludur (bkz. docs/PROTOCOL-VERSION-CHECK.md). Burada protokol kontrolü YOK.
+        // Protocol compatibility is resolved on the UI side in the whoAreYou probe; if we got to hello the parties
+        // are already compatible (see docs/PROTOCOL-VERSION-CHECK.md). NO protocol check here.
         if (p.role === "test") {
             this.onHelloTest(peer, env);
             return;
         }
-        // Zaten canlı bir bridge client varsa (başka tab) → meşgul.
+        // If there's already a live bridge client (another tab) → busy.
         if (this.bridgeClient?.isOpen && this.bridgeClient !== peer) {
-            peer.reply(env, "helloAck", { cliVersion: version_1.VERSION }, { message: "bridge already in use", title: "Bridge busy" });
+            peer.reply(env, "helloAck", { cliVersion: version_1.VERSION, protocol: protocolVersion_1.GENERATION, rootDir: this.rootDir ?? null }, { message: "bridge already in use", title: "Bridge busy" });
             logger_1.logger.warn(`hello rejected — bridge already in use (app ${this.claimedAppId})`);
             peer.close(1013, "bridge already in use");
             return;
         }
-        // Claim'li ve farklı app → bu server başka workspace'e ait.
+        // Claimed and a different app → this server belongs to another workspace.
         if (this.claimedAppId !== undefined && this.claimedAppId !== p.appId) {
-            peer.reply(env, "helloAck", { cliVersion: version_1.VERSION }, { message: `server claimed by another app (${this.claimedAppId})`, title: "Wrong workspace" });
+            peer.reply(env, "helloAck", { cliVersion: version_1.VERSION, protocol: protocolVersion_1.GENERATION, rootDir: this.rootDir ?? null }, { message: `server claimed by another app (${this.claimedAppId})`, title: "Wrong workspace" });
             logger_1.logger.warn(`hello rejected — claimed by ${this.claimedAppId}, got ${p.appId}`);
             peer.close(1008, "wrong workspace");
             return;
@@ -198,9 +281,9 @@ class BridgeServer {
         const fresh = this.claimedAppId === undefined;
         this.claimedAppId = p.appId;
         this.bridgeClient = peer;
-        // Her primary hello'da tazele (reconnect'te origin/org değişmiş olabilir).
+        // Refresh on every primary hello (origin/org may have changed on reconnect).
         this.renderTarget = (p.organizationId && p.origin) ? { organizationId: p.organizationId, origin: p.origin } : undefined;
-        // Teşhis: /render'ın çalışıp çalışmayacağı bağlantı anında görünsün (eski UI build'i org/origin göndermez).
+        // Diagnostic: make it visible at connect time whether /render will work (an old UI build doesn't send org/origin).
         if (this.renderTarget)
             logger_1.logger.info(`render check ready — ${this.renderTarget.origin}/studio/${this.renderTarget.organizationId}/${p.appId}`);
         else
@@ -212,41 +295,49 @@ class BridgeServer {
         else {
             logger_1.logger.info(`hello — reconnect to app "${p.appName}" (${p.appId})`);
         }
-        peer.reply(env, "helloAck", { cliVersion: version_1.VERSION });
+        peer.reply(env, "helloAck", { cliVersion: version_1.VERSION, protocol: protocolVersion_1.GENERATION, rootDir: this.rootDir ?? null });
         this.startPing();
+        this.cancelIdleExit();
+        // The web connected to the ephemeral port and handshaked → discovery done, release the rendezvous.
+        this.closeRendezvous();
     }
-    /** Test rolü hello'su. Test client claim ETMEZ, server.json'a dokunmaz; yalnız mevcut claim'e
-     *  eklemlenir. Canlı primary ŞART DEĞİL — claim primary F5'inde de kalır (onPeerClose) ve
-     *  primary'siz test client zararsızdır (control komutları zaten 409 döner). */
+    /** Test-role hello. The test client does NOT claim, doesn't touch server.json; it just attaches to the
+     *  existing claim. A live primary is NOT required — the claim survives the primary's F5 (onPeerClose) and
+     *  a test client without a primary is harmless (control commands return 409 anyway). */
     onHelloTest(peer, env) {
         const p = env.payload;
         if (this.claimedAppId === undefined) {
-            peer.reply(env, "helloAck", { cliVersion: version_1.VERSION }, { message: "no primary claim yet — connect the main Studio tab first", title: "No primary" });
+            peer.reply(env, "helloAck", { cliVersion: version_1.VERSION, protocol: protocolVersion_1.GENERATION, rootDir: this.rootDir ?? null }, { message: "no primary claim yet — connect the main Studio tab first", title: "No primary" });
             logger_1.logger.warn("test hello rejected — no primary claim yet");
             peer.close(1013, "no primary claim");
             return;
         }
         if (this.claimedAppId !== p.appId) {
-            peer.reply(env, "helloAck", { cliVersion: version_1.VERSION }, { message: `server claimed by another app (${this.claimedAppId})`, title: "Wrong workspace" });
+            peer.reply(env, "helloAck", { cliVersion: version_1.VERSION, protocol: protocolVersion_1.GENERATION, rootDir: this.rootDir ?? null }, { message: `server claimed by another app (${this.claimedAppId})`, title: "Wrong workspace" });
             logger_1.logger.warn(`test hello rejected — claimed by ${this.claimedAppId}, got ${p.appId}`);
             peer.close(1008, "wrong workspace");
             return;
         }
         if (this.testClient?.isOpen && this.testClient !== peer) {
-            peer.reply(env, "helloAck", { cliVersion: version_1.VERSION }, { message: "test slot already in use", title: "Test slot busy" });
+            peer.reply(env, "helloAck", { cliVersion: version_1.VERSION, protocol: protocolVersion_1.GENERATION, rootDir: this.rootDir ?? null }, { message: "test slot already in use", title: "Test slot busy" });
             logger_1.logger.warn("test hello rejected — test slot already in use");
             peer.close(1013, "test slot busy");
             return;
         }
         this.testClient = peer;
         logger_1.logger.info(`hello — test client joined app "${p.appName}" (${p.appId})`);
-        peer.reply(env, "helloAck", { cliVersion: version_1.VERSION });
+        peer.reply(env, "helloAck", { cliVersion: version_1.VERSION, protocol: protocolVersion_1.GENERATION, rootDir: this.rootDir ?? null });
         this.startPing();
-        // Test client push'lardan SONRA bağlanmış/F5 atmış olabilir → oturumun birikmiş gövdelerini gönder.
+        this.cancelIdleExit();
+        // The test client may have connected/F5'd AFTER the pushes → send the session's accumulated bodies.
         if (this.lastSync.size > 0)
             void this.sendSyncModels("replay");
     }
     async claim(appId) {
+        if (this.rootDir === undefined) {
+            logger_1.logger.debug(`claim deferred — no workspace yet (appId=${appId})`);
+            return;
+        }
         try {
             await (0, serverInfo_1.writeServerInfo)(this.rootDir, {
                 port: this.port,
@@ -259,10 +350,60 @@ class BridgeServer {
             logger_1.logger.error(`failed to write server.json: ${err.message}`);
         }
     }
-    // --- control kanalı (HTTP /control/<cmd>) — santral relay ---
-    // wsRaw'dan gelen WS-olmayan HTTP. Control isteğini sahiplen (true); gerisi false → 426.
+    // Folderless server: the web sees helloAck.rootDir === null and asks for pickFolder. The native picker opens;
+    // if an occupied folder (another live server's claim) is picked, folderInUse is sent and the picker reopens.
+    // On selection rootDir is set + (if claimed) server.json is written. Cancel → path:null.
+    async onPickFolder(peer, env) {
+        if (peer !== this.bridgeClient) {
+            peer.reply(env, "pickFolderResult", { path: null }, { message: "only the primary client can pick a folder" });
+            return;
+        }
+        if (this.rootDir !== undefined) {
+            peer.reply(env, "pickFolderResult", { path: this.rootDir });
+            return;
+        }
+        if (this._pickerOpen) {
+            peer.reply(env, "pickFolderResult", { path: null }, { message: "folder picker already open" });
+            return;
+        }
+        this._pickerOpen = true;
+        try {
+            while (peer.isOpen) {
+                const picked = await (0, pickWorkspaceDir_1.pickWorkspaceDir)();
+                if (!peer.isOpen)
+                    return; // tab closed while the picker was open → drop the result
+                if (!picked) {
+                    peer.reply(env, "pickFolderResult", { path: null });
+                    return;
+                }
+                if (isWorkspaceLocked(picked)) {
+                    logger_1.logger.warn(`workspace already in use — asking again: ${picked}`);
+                    peer.send("folderInUse", { path: picked });
+                    continue;
+                }
+                // The folder carries a persistent appId binding; if it belongs to a different app, don't let this
+                // app's files mix into it — reopen the picker (same warning as a live in-use folder).
+                if (this.claimedAppId !== undefined && belongsToAnotherApp(picked, this.claimedAppId)) {
+                    logger_1.logger.warn(`workspace belongs to another app — asking again: ${picked}`);
+                    peer.send("folderInUse", { path: picked });
+                    continue;
+                }
+                this.rootDir = picked;
+                if (this.claimedAppId !== undefined)
+                    await this.claim(this.claimedAppId);
+                logger_1.logger.info(`workspace selected: ${picked}`);
+                peer.reply(env, "pickFolderResult", { path: picked });
+                return;
+            }
+        }
+        finally {
+            this._pickerOpen = false;
+        }
+    }
+    // --- control channel (HTTP /control/<cmd>) — hub relay ---
+    // Non-WS HTTP coming from wsRaw. Own the control request (true); everything else false → 426.
     routeRequest(req, res) {
-        // CORS preflight — browser'ın OPTIONS isteğini karşıla.
+        // CORS preflight — handle the browser's OPTIONS request.
         if (req.method === "OPTIONS") {
             res.writeHead(204, this.corsHeaders());
             res.end();
@@ -273,20 +414,20 @@ class BridgeServer {
             void this.handleControl(cmd, req, res);
             return true;
         }
-        // Render-check: agent Playwright ile bu sabit lokal URL'i açar; CLI primary tab'dan TAZE token
-        // isteyip Studio editör URL'ine 302 redirect eder. Agent token'ı hiç görmez/işlemez.
+        // Render-check: the agent opens this fixed local URL with Playwright; the CLI requests a FRESH token from
+        // the primary tab and 302-redirects to the Studio editor URL. The agent never sees/handles the token.
         if (req.method === "GET" && req.url && req.url.split("?")[0] === "/render") {
             void this.handleRenderRedirect(res);
             return true;
         }
         return false;
     }
-    /** `<origin>/studio/<org>/<app>?cliRole=test#token=<taze token>` adresine 302 redirect.
-     *  Token her istekte primary'den TALEPLE alınır (hello-anı token'ı ~1 saatte bayatlar; api.getToken()
-     *  MSAL'dan sessizce yeniler) ve YALNIZ fragment'te taşınır (query değil → access log/Referer'a
-     *  sızmaz; sunucuya hiç gitmez). Diske asla yazılmaz. Yanıtta CORS header'ı BİLEREK YOK — yabancı
-     *  bir sayfa fetch ile redirect zincirini okuyamasın; endpoint yalnız doğrudan navigasyon içindir.
-     *  `?cliRole=test` sayesinde tab açılır açılmaz test client olarak auto-connect olur. */
+    /** 302 redirect to `<origin>/studio/<org>/<app>?cliRole=test#token=<fresh token>`.
+     *  The token is requested ON DEMAND from the primary on every request (the hello-time token goes stale in ~1 hour;
+     *  api.getToken() silently refreshes it from MSAL) and is carried ONLY in the fragment (not the query → doesn't leak
+     *  to access logs/Referer; never reaches the server). Never written to disk. The response DELIBERATELY has NO CORS
+     *  header — so a foreign page can't read the redirect chain via fetch; the endpoint is for direct navigation only.
+     *  Thanks to `?cliRole=test` the tab auto-connects as a test client as soon as it opens. */
     async handleRenderRedirect(res) {
         if (!this.bridgeClient?.isOpen || this.claimedAppId === undefined) {
             this.respondNoCors(res, 503, { error: "no authenticated Studio session — open Studio and connect the CLI first" });
@@ -310,7 +451,7 @@ class BridgeServer {
         }
         const { origin, organizationId } = this.renderTarget;
         const path = `/studio/${encodeURIComponent(organizationId)}/${encodeURIComponent(this.claimedAppId)}`;
-        const target = `${origin}${path}?cliRole=test#token=${encodeURIComponent(token)}`;
+        const target = `${origin}${path}?cliRole=test&cliPort=${this.port}#token=${encodeURIComponent(token)}`;
         res.writeHead(302, { Location: target });
         res.end();
     }
@@ -333,25 +474,31 @@ class BridgeServer {
             req.on("error", reject);
         });
     }
-    // Control komutunu erit: gereken mesajı bridgeClient'a relay et, cevabı HTTP'ye dön.
+    // Resolve the control command: relay the needed message to the bridgeClient, return the reply over HTTP.
     async handleControl(cmd, req, res) {
         if (!this.bridgeClient?.isOpen) {
             this.respond(res, 409, { error: "studio not connected" });
             return;
         }
+        if (this.rootDir === undefined) {
+            this.respond(res, 409, { error: "no workspace selected — pick a folder in Studio first" });
+            return;
+        }
         try {
             switch (cmd) {
                 case "pull": {
-                    // browser pullResult (snapshot) ile reply eder → dosyaları SERVER yazar (+ state).
-                    // Yanıt: NDJSON stream — her model sonrası {"progress":x,"total":y}, sonda {"message":...}
-                    const snapshot = await this.bridgeClient.request("pull", {});
+                    // the browser replies with pullResult (snapshot) → the SERVER writes the files (+ state).
+                    // Response: NDJSON stream — {"progress":x,"total":y} after each model, {"message":...} at the end
+                    const snapshot = await this.bridgeClient.request("pull", {}, 300000);
                     const modelTotal = snapshot.models.length;
                     res.writeHead(200, { "Content-Type": "application/x-ndjson", ...this.corsHeaders() });
                     try {
-                        const { total, readOnly } = await (0, pull_1.pull)(this.rootDir, snapshot, (written) => {
+                        const { total, readOnly, failed } = await (0, pull_1.pull)(this.workspaceDir, snapshot, (written) => {
                             res.write(JSON.stringify({ progress: written, total: modelTotal }) + "\n");
                         });
-                        res.end(JSON.stringify({ message: `pulled ${total} model(s)${readOnly > 0 ? ` (${readOnly} read-only)` : ""}` }) + "\n");
+                        for (const f of failed)
+                            res.write(JSON.stringify({ skipped: `${f.name} — ${f.error}` }) + "\n");
+                        res.end(JSON.stringify({ message: `${total} model(s)${readOnly > 0 ? ` (${readOnly} read-only)` : ""}${failed.length > 0 ? `, ${failed.length} failed` : ""} and .ai-kit pulled` }) + "\n");
                     }
                     catch (err) {
                         res.end(JSON.stringify({ error: err.message }) + "\n");
@@ -359,45 +506,54 @@ class BridgeServer {
                     return;
                 }
                 case "push": {
-                    // rootDir'i tara → mevcut (models) + yeni (newModels) dosyaları topla → bulk relay → state güncelle.
-                    const state = (0, state_1.readState)(this.rootDir);
-                    const { models, newModels, skipped, deletedIds } = await (0, push_1.push)(this.rootDir, state);
-                    // NDJSON stream aç — client progress bar çizer (controlClient.ts readNdjsonStream).
+                    // scan rootDir → collect existing (models) + new (newModels) files → bulk relay → update state.
+                    const state = (0, state_1.readState)(this.workspaceDir);
+                    const { models, newModels, skipped, deletedIds } = await (0, push_1.push)(this.workspaceDir, state);
+                    // open an NDJSON stream — the client draws a progress bar (controlClient.ts readNdjsonStream).
                     res.writeHead(200, { "Content-Type": "application/x-ndjson", ...this.corsHeaders() });
-                    // Her skipped dosya için bireysel satır yaz.
+                    // Write an individual line for each skipped file.
                     for (const s of skipped) {
                         const hint = s.reason === "readonly" ? "read-only (use startWorking to check out)" : "unsupported type";
                         res.write(JSON.stringify({ skipped: `${s.localKey} — ${hint}` }) + "\n");
                     }
                     if (models.length === 0 && newModels.length === 0 && deletedIds.length === 0) {
-                        res.end(JSON.stringify({ message: `nothing to push` }) + "\n");
+                        res.end(JSON.stringify({ message: `push OK — already up to date, no changes to send` }) + "\n");
                         return;
                     }
                     const total = models.length + newModels.length + deletedIds.length;
-                    // Push sırasında gelen modelChanged/modelCreated eventleri push'un kendi updateModel
-                    // çağrılarından kaynaklanır (echo). Deferred queue'ya al; push bitince işle.
+                    // modelChanged/modelCreated events that arrive during the push come from the push's own updateModel
+                    // calls (echo). Put them in the deferred queue; process when the push finishes.
                     this._pushInProgress = true;
-                    this._expectedCheckoutEchoes.clear(); // önceki push'tan kalan (echo'su gelmemiş) id'leri temizle
+                    this._expectedCheckoutEchoes.clear(); // clear ids left over from a previous push (whose echo never arrived)
                     try {
                         res.write(JSON.stringify({ progress: 0, total }) + "\n");
-                        const result = await this.bridgeClient.request("push", { models, newModels, deletedIds }, 60000);
-                        // Yeni yaratılan modeller push tarafından checkout edilir → checkoutChanged echo'su beklenir.
-                        // (Mevcut modeller rename/move/body'de checkout etmez.) Echo geç gelse de id ile bastırılır.
+                        const pushTimeoutMs = Math.max(300000, total * 60000);
+                        const heartbeat = setInterval(() => { if (!res.writableEnded)
+                            res.write(JSON.stringify({ keepalive: 1 }) + "\n"); }, 20000);
+                        let result;
+                        try {
+                            result = await this.bridgeClient.request("push", { models, newModels, deletedIds }, pushTimeoutMs);
+                        }
+                        finally {
+                            clearInterval(heartbeat);
+                        }
+                        // Newly created models are checked out by the push → a checkoutChanged echo is expected.
+                        // (Existing models don't check out on rename/move/body.) Even if the echo arrives late it's suppressed by id.
                         for (const r of result.newModelResults ?? [])
                             if (r.ok && r.id)
                                 this._expectedCheckoutEchoes.add(r.id);
-                        // Progress: her uygulanan öğe için tek satır (mevcut + yeni + silinen).
+                        // Progress: one line per applied item (existing + new + deleted).
                         let done = 0;
                         const tick = () => res.write(JSON.stringify({ progress: ++done, total }) + "\n");
                         const counts = { okBody: 0, okRenamed: 0, okMoved: 0, okBoth: 0, okDeleted: 0, okRefFiles: 0 };
-                        this.applyExistingResults(result.results ?? [], models, state, counts, tick);
-                        await this.applyNewModelResults(result.newModelResults ?? [], newModels, state, counts, tick);
+                        await this.applyExistingResults(result.results ?? [], models, state, counts, tick);
+                        await this.applyNewModelResults(result.newModelResults ?? [], newModels, state, counts, tick, res);
                         this.applyDeletedResults(result.deletedResults ?? [], state, counts, tick);
                         counts.okRefFiles = await this.syncReferences(result.results ?? [], result.deletedResults ?? [], state, res);
-                        await (0, state_1.writeState)(this.rootDir, state);
+                        await (0, state_1.writeState)(this.workspaceDir, state);
                         res.end(JSON.stringify({ message: this.buildPushSummary(counts, models, newModels, skipped) }) + "\n");
-                        // Test tabına yansıt — HTTP yanıtı kapandıktan sonra, best-effort (push'u asla bloklamaz;
-                        // hata da push'a sızmaz — res zaten kapandı, catch'e düşmemeli).
+                        // Reflect to the test tab — after the HTTP response is closed, best-effort (never blocks the push;
+                        // errors don't leak into the push either — res is already closed, must not fall into catch).
                         try {
                             this.afterPushSync(models, newModels, result);
                         }
@@ -410,8 +566,8 @@ class BridgeServer {
                     }
                     finally {
                         this._pushInProgress = false;
-                        // Reply sonrası gelebilecek checkout echo'su _expectedCheckoutEchoes ile (id bazında) bastırılır.
-                        // Deferred echo eventlerini işle (push'un kendi kaynaklıları no-op olur).
+                        // A checkout echo that may arrive after the reply is suppressed (per-id) via _expectedCheckoutEchoes.
+                        // Process the deferred echo events (those originating from the push itself become no-ops).
                         const deferredChanged = this._deferredModelChanged.splice(0);
                         for (const d of deferredChanged)
                             void this.handleModelChanged(d);
@@ -438,7 +594,7 @@ class BridgeServer {
                         this.respond(res, 400, { error: "modelId required" });
                         return;
                     }
-                    const result = await this.bridgeClient.request("startWorking", { modelId: body.modelId });
+                    const result = await this.bridgeClient.request("startWorking", { modelId: body.modelId }, 20000);
                     this.respond(res, 200, result);
                     return;
                 }
@@ -459,7 +615,7 @@ class BridgeServer {
                         this.respond(res, 400, { error: "modelId required" });
                         return;
                     }
-                    const result = await this.bridgeClient.request("convertToBlock", { modelId: body.modelId });
+                    const result = await this.bridgeClient.request("convertToBlock", { modelId: body.modelId }, 20000);
                     this.respond(res, 200, result);
                     return;
                 }
@@ -475,9 +631,10 @@ class BridgeServer {
         res.writeHead(status, { "Content-Type": "application/json", ...this.corsHeaders() });
         res.end(JSON.stringify(body));
     }
-    // --- push sonuç işleme (handleControl "push" yardımcıları) ---
-    /** Mevcut modeller: bodyChanged'da state hash güncelle; rename/move sayaçları; her öğe için progress. */
-    applyExistingResults(results, models, state, counts, tick) {
+    // --- push result processing (handleControl "push" helpers) ---
+    /** Existing models: update the state hash on bodyChanged; rename/move counters; progress per item.
+     *  If the move changed the owner, the ownerName in the local frontmatter is updated too. */
+    async applyExistingResults(results, models, state, counts, tick) {
         for (const r of results) {
             if (!r.ok) {
                 logger_1.logger.warn(`push ${r.id}: ${r.error ?? "failed"}`);
@@ -495,14 +652,32 @@ class BridgeServer {
                 counts.okRenamed++;
             else if (r.moved)
                 counts.okMoved++;
+            if (pm && r.moved && r.ownerName !== undefined)
+                await this.rewriteOwnerName(pm, r.ownerName);
             tick();
         }
     }
-    /** Yeni dosyalar: yeni yaratılana frontmatter yaz, state hash hesapla; her öğe için progress. */
-    async applyNewModelResults(results, newModels, state, counts, tick) {
+    /** After a move, updates the file's frontmatter ownerName to the new owner (body/hash unchanged). */
+    async rewriteOwnerName(pm, ownerName) {
+        const abs = (0, node_path_1.join)(this.workspaceDir, ...pm.relDir.split("/").filter(Boolean), `${pm.newName}.${pm.modelType}`);
+        try {
+            const parsed = (0, frontmatter_1.parseFrontmatter)(await (0, promises_1.readFile)(abs, "utf8"));
+            if (!parsed || parsed.meta.ownerName === ownerName)
+                return;
+            await (0, promises_1.writeFile)(abs, (0, frontmatter_1.writeWithFrontmatter)({ ...parsed.meta, ownerName }, parsed.body), "utf8");
+            logger_1.logger.info(`frontmatter ownerName → ${ownerName}: ${(0, node_path_1.relative)(this.workspaceDir, abs)}`);
+        }
+        catch (err) {
+            logger_1.logger.warn(`frontmatter ownerName update failed for ${pm.newName}: ${err.message}`);
+        }
+    }
+    /** New files: write frontmatter to the newly created one, compute the state hash; progress per item. */
+    async applyNewModelResults(results, newModels, state, counts, tick, res) {
         for (const r of results) {
             if (!r.ok || !r.id || !r.key) {
-                logger_1.logger.warn(`push ${r.localKey}: ${r.error ?? "failed"}`);
+                const reason = r.error ?? "failed";
+                logger_1.logger.warn(`push ${r.localKey}: ${reason}`);
+                res.write(JSON.stringify({ skipped: `${r.localKey} — ${reason}` }) + "\n");
                 tick();
                 continue;
             }
@@ -511,10 +686,14 @@ class BridgeServer {
                 tick();
                 continue;
             }
-            const absPath = (0, node_path_1.join)(this.rootDir, ...r.localKey.split("/"));
+            const absPath = (0, node_path_1.join)(this.workspaceDir, ...r.localKey.split("/"));
             const isNewlyCreated = !nm.existingId || r.id !== nm.existingId;
             if (isNewlyCreated) {
-                await (0, promises_1.writeFile)(absPath, (0, frontmatter_1.writeWithFrontmatter)({ id: r.id, ownerName: r.ownerName ?? "/" }, nm.body), "utf8");
+                const bodyToWrite = r.body === undefined
+                    ? nm.body // local file content — already formatted
+                    : (nm.modelType === "qjson" ? (0, qjsonCompiled_1.stripQJsonCompiledFields)(r.body) : (0, jsonBody_1.formatJsonBody)(r.body, nm.modelType));
+                const prevMeta = (0, frontmatter_1.parseFrontmatter)(await (0, promises_1.readFile)(absPath, "utf8"))?.meta;
+                await (0, promises_1.writeFile)(absPath, (0, frontmatter_1.writeWithFrontmatter)({ ...prevMeta, id: r.id, ownerName: r.ownerName ?? "/" }, bodyToWrite), "utf8");
             }
             const createdContent = await (0, promises_1.readFile)(absPath, "utf8");
             const createdFm = (0, frontmatter_1.parseFrontmatter)(createdContent);
@@ -523,7 +702,7 @@ class BridgeServer {
             tick();
         }
     }
-    /** Silinen modeller: state'ten çıkar; her öğe için progress. */
+    /** Deleted models: remove from state; progress per item. */
     applyDeletedResults(results, state, counts, tick) {
         for (const r of results) {
             if (!r.ok) {
@@ -536,27 +715,28 @@ class BridgeServer {
             tick();
         }
     }
-    /** EPIC 13b — rename/move sonrası diğer dosyalardaki <<type:oldPath>> → <<type:newPath>> düzelt;
-     *  delete'te dangling referansları `skipped` satırıyla uyar. Düzeltilen dosya sayısı döner.
-     *  (Studio'da bağ id ile sabit; lokalde path ile olduğu için referans EDEN dosyalar bayatlar.) */
+    /** EPIC 13b — after rename/move, fix <<type:oldPath>> → <<type:newPath>> in other files;
+     *  on delete, warn about dangling references with a `skipped` line. Returns the number of fixed files.
+     *  (In Studio the link is fixed by id; locally it's by path, so the REFERENCING files go stale.) */
     async syncReferences(results, deletedResults, state, res) {
+        const rootDir = this.workspaceDir;
         const renames = results.flatMap(r => (r.ok && r.oldPath && r.newPath && r.oldPath !== r.newPath) ? [{ oldPath: r.oldPath, newPath: r.newPath }] : []);
         const deletedPaths = deletedResults.flatMap(r => (r.ok && r.deletedPath) ? [r.deletedPath] : []);
         if (renames.length === 0 && deletedPaths.length === 0)
             return 0;
         let okRefFiles = 0;
-        for (const abs of await walkDir(this.rootDir)) {
+        for (const abs of await walkDir(rootDir)) {
             let content = await (0, promises_1.readFile)(abs, "utf8");
             let changed = false;
             for (const rn of renames) {
-                const rw = (0, modelRef_1.rewriteRefPath)(content, rn.oldPath, rn.newPath);
+                const rw = (0, modelRefs_1.rewriteRefPath)(content, rn.oldPath, rn.newPath);
                 if (rw.count > 0) {
                     content = rw.content;
                     changed = true;
                 }
             }
             if (changed) {
-                // Referans eden dosya checkout edilmemişse (0444) yazılamaz → geçici writable yap, sonra geri al.
+                // If the referencing file isn't checked out (0444) it can't be written → make it temporarily writable, then revert.
                 const wasWritable = !!((await (0, promises_1.stat)(abs)).mode & 0o200);
                 if (!wasWritable)
                     await (0, promises_1.chmod)(abs, 0o644);
@@ -567,17 +747,17 @@ class BridgeServer {
                 if (fm)
                     state[fm.meta.id] = (0, state_1.sha)(fm.body);
                 okRefFiles++;
-                logger_1.logger.info(`ref-sync: ${(0, node_path_1.relative)(this.rootDir, abs)}`);
+                logger_1.logger.info(`ref-sync: ${(0, node_path_1.relative)(rootDir, abs)}`);
             }
             for (const dp of deletedPaths) {
-                if ((0, modelRef_1.hasRefPath)(content, dp)) {
-                    res.write(JSON.stringify({ skipped: `${(0, node_path_1.relative)(this.rootDir, abs).replace(/\\/g, "/")} — references deleted '${dp}' (fix manually)` }) + "\n");
+                if ((0, modelRefs_1.hasRefPath)(content, dp)) {
+                    res.write(JSON.stringify({ skipped: `${(0, node_path_1.relative)(rootDir, abs).replace(/\\/g, "/")} — references deleted '${dp}' (fix manually)` }) + "\n");
                 }
             }
         }
         return okRefFiles;
     }
-    /** push özet mesajı (son NDJSON satırı). */
+    /** push summary message (last NDJSON line). */
     buildPushSummary(counts, models, newModels, skipped) {
         const parts = [];
         const bodyTotal = models.filter(m => m.bodyChanged).length + newModels.length;
@@ -594,7 +774,7 @@ class BridgeServer {
         if (counts.okRefFiles > 0)
             parts.push(`refs updated in ${counts.okRefFiles} file(s)`);
         if (parts.length === 0)
-            parts.push("nothing to push");
+            parts.push("push OK — already up to date, no changes to send");
         const readonlyCount = skipped.filter(s => s.reason === "readonly").length;
         const unsupportedCount = skipped.filter(s => s.reason === "unsupported-type").length;
         if (readonlyCount > 0)
@@ -603,10 +783,10 @@ class BridgeServer {
             parts.push(`${unsupportedCount} unsupported type skipped`);
         return parts.join(", ");
     }
-    // --- test client sync (push edilen gövdelerin test tabına yansıtılması) ---
-    /** Push sonuçlarından sync item'larını çıkarır, lastSync'e merge eder ve (bağlıysa) test
-     *  client'a yollar. Primary push payload'ı ASLA replay edilmez — applyNewModel backend'de model
-     *  yaratır, replay double-create olur; bu yüzden FINAL id'lerle bu hafif mesaj gönderilir. */
+    // --- test client sync (reflecting pushed bodies to the test tab) ---
+    /** Extracts sync items from the push results, merges them into lastSync and (if connected) sends them to the
+     *  test client. The primary push payload is NEVER replayed — applyNewModel creates a model on the backend,
+     *  replaying would double-create; so this lightweight message is sent with the FINAL ids. */
     afterPushSync(models, newModels, result) {
         const items = [];
         for (const r of result.results ?? []) {
@@ -619,18 +799,18 @@ class BridgeServer {
         }
         for (const r of result.newModelResults ?? []) {
             if (!r.ok || !r.id)
-                continue; // primary'de create başarısızsa test'e HİÇ gitmez (hayalet model yok)
+                continue; // if create failed on the primary it does NOT go to the test at all (no ghost model)
             const nm = newModels.find(m => m.localKey === r.localKey);
             if (!nm)
                 continue;
-            items.push({ id: r.id, modelType: nm.modelType, key: r.key, body: nm.body, name: r.name ?? nm.name, relDir: nm.relDir, isNew: !nm.existingId || r.id !== nm.existingId });
+            items.push({ id: r.id, modelType: nm.modelType, key: r.key, body: r.body ?? nm.body, name: r.name ?? nm.name, relDir: nm.relDir, isNew: !nm.existingId || r.id !== nm.existingId });
         }
         for (const it of items)
             this.lastSync.set(it.id, it);
         for (const d of result.deletedResults ?? [])
             if (d.ok)
                 this.lastSync.delete(d.id);
-        // Gövdesiz rename/move/create/delete de test tabında refreshItems gerektirir.
+        // bodyless rename/move/create/delete also require refreshItems in the test tab.
         const treeChanged = (result.results ?? []).some(r => r.ok && (r.renamed === true || r.moved === true))
             || (result.newModelResults ?? []).some(r => r.ok)
             || (result.deletedResults ?? []).some(r => r.ok);
@@ -638,8 +818,8 @@ class BridgeServer {
             void this.sendSyncModels("push", items, treeChanged);
         }
     }
-    /** syncModels'i test client'a yollar. replay → lastSync'ün tamamı (test hello/F5 sonrası).
-     *  Best-effort: hata yalnız loglanır; timeout 60s (handler refreshItems + editör açabilir). */
+    /** Sends syncModels to the test client. replay → the entire lastSync (after test hello/F5).
+     *  Best-effort: errors are only logged; timeout 60s (the handler may refreshItems + open the editor). */
     async sendSyncModels(reason, items, treeChanged = false) {
         if (!this.testClient?.isOpen || this.claimedAppId === undefined)
             return;
@@ -656,13 +836,18 @@ class BridgeServer {
             logger_1.logger.warn(`test sync (${reason}) failed: ${err.message}`);
         }
     }
-    // --- web → local otomatik sync (modelChanged) ---
+    // --- web → local auto sync (modelChanged) ---
     async handleModelChanged(payload) {
+        if (this.rootDir === undefined) {
+            logger_1.logger.debug(`modelChanged: no workspace — dropping id=${payload.modelId}`);
+            return;
+        }
         if (this._pushInProgress) {
             this._deferredModelChanged.push(payload);
             logger_1.logger.debug(`modelChanged: push in progress — deferring for id=${payload.modelId}`);
             return;
         }
+        const rootDir = this.workspaceDir;
         const abs = await this.findFileById(payload.modelId);
         if (!abs) {
             logger_1.logger.debug(`modelChanged: no local file for id=${payload.modelId}`);
@@ -672,55 +857,59 @@ class BridgeServer {
         const fm = (0, frontmatter_1.parseFrontmatter)(existing);
         if (!fm)
             return;
-        // model="" → rename-only mesaj (body VMM'de yüklü değildi); body yazma atla
+        // model="" → rename-only message (the body wasn't loaded in the VMM); skip writing the body
         if (payload.model !== "") {
             const ext = (0, node_path_1.extname)(abs).slice(1).toLowerCase();
-            const body = ext === "qjson" ? (0, pull_1.stripQJsonCompiledFields)(payload.model) : payload.model;
-            // Kullanıcı Studio'da kaydettiyse test replay'i (F5) bayat push gövdesine dönmesin.
+            const body = ext === "qjson" ? (0, qjsonCompiled_1.stripQJsonCompiledFields)(payload.model) : (0, jsonBody_1.formatJsonBody)(payload.model, ext);
+            // If the user saved in Studio, the test replay (F5) must not revert to the stale push body.
             const prev = this.lastSync.get(payload.modelId);
             if (prev)
                 this.lastSync.set(payload.modelId, { ...prev, body });
-            const state = (0, state_1.readState)(this.rootDir);
-            // Push echo guard: hash state ile aynıysa (az önce pushladık) body yazmayı atla
+            const state = (0, state_1.readState)(rootDir);
+            // Push echo guard: if the hash equals state (we just pushed) skip writing the body
             if ((0, state_1.sha)(body) !== state[payload.modelId]) {
                 try {
                     await (0, promises_1.chmod)(abs, 0o644);
                 }
-                catch { /* zaten yazılabilir veya dosya yok */ }
+                catch { /* already writable or the file doesn't exist */ }
                 await (0, promises_1.writeFile)(abs, (0, frontmatter_1.writeWithFrontmatter)(fm.meta, body), "utf8");
                 state[payload.modelId] = (0, state_1.sha)(body);
-                await (0, state_1.writeState)(this.rootDir, state);
-                logger_1.logger.info(`auto-pulled: ${(0, node_path_1.relative)(this.rootDir, abs)}`);
+                await (0, state_1.writeState)(rootDir, state);
+                logger_1.logger.info(`auto-pulled: ${(0, node_path_1.relative)(rootDir, abs)}`);
             }
         }
-        // Rename ve move sırayla yapılır; currentAbs güncel yolu takip eder.
+        // Rename and move are done in order; currentAbs tracks the current path.
         let currentAbs = abs;
         if (payload.newName) {
             const newAbs = (0, node_path_1.join)((0, node_path_1.dirname)(currentAbs), payload.newName + (0, node_path_1.extname)(currentAbs));
             if (newAbs !== currentAbs) {
                 await (0, promises_1.rename)(currentAbs, newAbs);
-                logger_1.logger.info(`auto-renamed: ${(0, node_path_1.relative)(this.rootDir, currentAbs)} → ${(0, node_path_1.relative)(this.rootDir, newAbs)}`);
+                logger_1.logger.info(`auto-renamed: ${(0, node_path_1.relative)(rootDir, currentAbs)} → ${(0, node_path_1.relative)(rootDir, newAbs)}`);
                 currentAbs = newAbs;
             }
         }
         if (payload.newRelDir !== undefined) {
-            const currentRelDir = (0, node_path_1.relative)(this.rootDir, (0, node_path_1.dirname)(currentAbs)).replace(/\\/g, "/");
+            const currentRelDir = (0, node_path_1.relative)(rootDir, (0, node_path_1.dirname)(currentAbs)).replace(/\\/g, "/");
             const normCurrentRelDir = currentRelDir === "." ? "" : currentRelDir;
             if (payload.newRelDir !== normCurrentRelDir) {
                 const targetDir = payload.newRelDir
-                    ? (0, node_path_1.join)(this.rootDir, ...payload.newRelDir.split("/"))
-                    : this.rootDir;
+                    ? (0, node_path_1.join)(rootDir, ...payload.newRelDir.split("/"))
+                    : rootDir;
                 const newAbs = (0, node_path_1.join)(targetDir, (0, node_path_1.basename)(currentAbs));
                 await (0, promises_1.mkdir)(targetDir, { recursive: true });
                 await (0, promises_1.rename)(currentAbs, newAbs);
-                logger_1.logger.info(`auto-moved: ${(0, node_path_1.relative)(this.rootDir, currentAbs)} → ${(0, node_path_1.relative)(this.rootDir, newAbs)}`);
+                logger_1.logger.info(`auto-moved: ${(0, node_path_1.relative)(rootDir, currentAbs)} → ${(0, node_path_1.relative)(rootDir, newAbs)}`);
             }
         }
     }
-    // Studio'da yeni model yaratıldı → lokale tek dosya yaz (pull ile aynı writeModel mantığı).
-    // Echo guard: aynı ID'li dosya zaten varsa (push ile yaratıldıysa veya zaten pull'landıysa) atla.
-    // Push devam ederken gelen eventler deferred queue'ya alınır (frontmatter henüz yazılmadı).
+    // A new model was created in Studio → write a single file locally (same writeModel logic as pull).
+    // Echo guard: if a file with the same ID already exists (created by the push or already pulled) skip.
+    // Events arriving while a push is in progress go into the deferred queue (frontmatter not written yet).
     async handleModelCreated(payload) {
+        if (this.rootDir === undefined) {
+            logger_1.logger.debug(`modelCreated: no workspace — dropping id=${payload.model.ID}`);
+            return;
+        }
         if (this._pushInProgress) {
             this._deferredModelCreated.push(payload);
             logger_1.logger.debug(`modelCreated: push in progress — deferring for id=${payload.model.ID}`);
@@ -731,33 +920,40 @@ class BridgeServer {
             logger_1.logger.debug(`modelCreated: file already exists for id=${payload.model.ID} — skipping (echo)`);
             return;
         }
-        const { hash } = await (0, pull_1.writeModel)(this.rootDir, payload.model, payload.readOnly);
+        const { hash } = await (0, pull_1.writeModel)(this.workspaceDir, payload.model, payload.readOnly);
         if (hash !== undefined) {
-            const state = (0, state_1.readState)(this.rootDir);
+            const state = (0, state_1.readState)(this.workspaceDir);
             state[payload.model.ID] = hash;
-            await (0, state_1.writeState)(this.rootDir, state);
+            await (0, state_1.writeState)(this.workspaceDir, state);
         }
         logger_1.logger.info(`auto-pulled (new): ${payload.model.name}`);
     }
     async handleModelDeleted(payload) {
-        this.lastSync.delete(payload.modelId); // replay silinen modeli diriltmesin
+        if (this.rootDir === undefined) {
+            logger_1.logger.debug(`modelDeleted: no workspace — dropping id=${payload.modelId}`);
+            return;
+        }
+        this.lastSync.delete(payload.modelId); // so replay doesn't resurrect the deleted model
         const abs = await this.findFileById(payload.modelId);
         if (!abs) {
             logger_1.logger.debug(`modelDeleted: no local file for id=${payload.modelId}`);
             return;
         }
-        await (0, promises_1.unlink)(abs);
-        const state = (0, state_1.readState)(this.rootDir);
+        const state = (0, state_1.readState)(this.workspaceDir);
         delete state[payload.modelId];
-        await (0, state_1.writeState)(this.rootDir, state);
-        logger_1.logger.info(`auto-deleted: ${(0, node_path_1.relative)(this.rootDir, abs)}`);
+        await (0, state_1.writeState)(this.workspaceDir, state);
+        this.trashQueue.enqueue(abs, this.workspaceDir);
     }
     async handleCheckoutChanged(payload) {
-        // Push'un kendi checkout'undan kaynaklanan echo (yeni model yaratınca studio.checkout).
-        // Dosya push tarafından zaten doğru modda yazılıyor → log/chmod gereksiz, düşür.
-        // - Push sürerken: tümünü bastır.
-        // - Reply'dan sonra geç gelen echo: yalnız push'un checkout ettiği id'ler, consume-once.
-        // Yalnızca Studio'da manuel start/stop working log'lanır.
+        if (this.rootDir === undefined) {
+            logger_1.logger.debug(`checkoutChanged: no workspace — dropping id=${payload.modelId}`);
+            return;
+        }
+        // Echo caused by the push's own checkout (studio.checkout when a new model is created).
+        // The file is already written in the correct mode by the push → log/chmod unnecessary, drop it.
+        // - While the push is running: suppress all.
+        // - Echo arriving late after the reply: only ids the push checked out, consume-once.
+        // Only manual start/stop working in Studio is logged.
         if (this._pushInProgress) {
             logger_1.logger.debug(`checkoutChanged: push in progress — ignoring (echo) for id=${payload.modelId}`);
             return;
@@ -773,10 +969,10 @@ class BridgeServer {
         }
         const mode = payload.checkedOutByMe ? 0o644 : 0o444;
         await (0, promises_1.chmod)(abs, mode);
-        logger_1.logger.info(`checkout-changed: ${(0, node_path_1.relative)(this.rootDir, abs)} → ${payload.checkedOutByMe ? "editable (0644)" : "read-only (0444)"}`);
+        logger_1.logger.info(`checkout-changed: ${(0, node_path_1.relative)(this.workspaceDir, abs)} → ${payload.checkedOutByMe ? "editable (0644)" : "read-only (0444)"}`);
     }
     async findFileById(modelId) {
-        for (const abs of await walkDir(this.rootDir)) {
+        for (const abs of await walkDir(this.workspaceDir)) {
             const content = await (0, promises_1.readFile)(abs, "utf8");
             const fm = (0, frontmatter_1.parseFrontmatter)(content);
             if (fm?.meta.id === modelId)
@@ -784,14 +980,52 @@ class BridgeServer {
         }
         return null;
     }
-    // --- keepalive (bridge client'a) ---
+    // --- keepalive / liveness (every peer) ---
+    /** Idempotent — called on every new connection. Restarting the interval here would mean a
+     *  peer reconnecting more often than PING_INTERVAL_MS keeps resetting it, so no ping is ever
+     *  actually sent. */
     startPing() {
-        this.stopPing();
-        this.pingTimer = setInterval(() => {
-            for (const p of [this.bridgeClient, this.testClient])
-                if (p?.isOpen)
-                    p.send("ping", {});
-        }, PING_INTERVAL_MS);
+        if (this.pingTimer)
+            return;
+        this.lastTickAt = Date.now();
+        this.pingTimer = setInterval(() => this.pingTick(), PING_INTERVAL_MS);
+    }
+    /** Reap the silent, ping the rest.
+     *
+     *  Reaping is what makes orphaned CLI processes go away. armIdleExit() is only re-armed from
+     *  onPeerClose, and onHello cancels it — so once a client handshakes, ONLY a close event can
+     *  restart the shutdown timer. A client that dies without sending a FIN (sleep, VPN switch,
+     *  tab crash) leaves socket.destroyed false forever, onPeerClose never fires, and the process
+     *  lives on holding its workspace claim. Dropping the peer here supplies that missing close:
+     *  destroy → onPeerClose → armIdleExit → the process exits on its own.
+     *
+     *  Iterates a COPY: destroy() notifies synchronously, which mutates this.peers mid-loop. */
+    pingTick() {
+        // A sweep that lands far past its schedule means the whole HOST was suspended (laptop lid),
+        // not that peers went quiet: no ping could be sent during the gap, yet Date.now() jumped by
+        // its full length. Reaping on that first sweep after waking would drop perfectly healthy
+        // clients, so forgive the gap and re-measure everyone from now.
+        const sinceLastTick = Date.now() - this.lastTickAt;
+        this.lastTickAt = Date.now();
+        if (sinceLastTick > SUSPEND_GAP_MS) {
+            logger_1.logger.info(`ping sweep ${Math.round(sinceLastTick / 1000)}s late — host was suspended, re-measuring peers`);
+            for (const peer of this.peers)
+                peer.markAlive();
+        }
+        for (const peer of [...this.peers]) {
+            if (!peer.isOpen) {
+                this.peers.delete(peer); // close handler should have done this; belt and braces
+                continue;
+            }
+            if (peer.msSinceLastMessage >= PEER_SILENCE_LIMIT_MS) {
+                logger_1.logger.warn(`peer silent for ${Math.round(peer.msSinceLastMessage / 1000)}s — dropping`);
+                peer.destroy(1001, "no response to ping");
+                continue;
+            }
+            peer.send("ping", {});
+        }
+        if (this.peers.size === 0)
+            this.stopPing();
     }
     stopPing() {
         if (this.pingTimer) {
@@ -799,8 +1033,57 @@ class BridgeServer {
             this.pingTimer = undefined;
         }
     }
+    // If the time spent without a client (browser/tab closed or never connected) exceeds IDLE_EXIT_MS
+    // shut the process down → so claimless ports don't pile up in the background. Canceled when a client connects.
+    armIdleExit() {
+        this.cancelIdleExit();
+        this.idleTimer = setTimeout(() => {
+            logger_1.logger.info(`no client for ${IDLE_EXIT_MS / 1000}s — shutting down`);
+            this.close();
+            process.exit(0);
+        }, IDLE_EXIT_MS);
+    }
+    cancelIdleExit() {
+        if (this.idleTimer) {
+            clearTimeout(this.idleTimer);
+            this.idleTimer = undefined;
+        }
+    }
 }
 exports.BridgeServer = BridgeServer;
+// Is there another live studio server in the folder? Checks whether the pid in server.json is alive.
+// No pid (disconnected — only the appId binding remains) or a dead pid isn't treated as a lock — that
+// folder can be re-claimed.
+function isWorkspaceLocked(dir) {
+    let info;
+    try {
+        info = (0, serverInfo_1.readServerInfo)(dir);
+    }
+    catch {
+        return false;
+    }
+    const pid = info?.pid;
+    if (pid === undefined)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+// Does the folder's persistent server.json appId differ from the connecting app? → it belongs to another
+// app (its files must not be mixed with this app's). No binding (empty folder) or the same app → false.
+function belongsToAnotherApp(dir, appId) {
+    try {
+        const info = (0, serverInfo_1.readServerInfo)(dir);
+        return info?.appId !== undefined && info.appId !== appId;
+    }
+    catch {
+        return false;
+    }
+}
 async function walkDir(dir) {
     const out = [];
     for (const entry of await (0, promises_1.readdir)(dir, { withFileTypes: true })) {