@stechquick/studio-cli 4.1.1-0 → 4.1.2-0

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

@@ -12,6 +12,7 @@ const qjsonCompiled_1 = require("../../../common/agentic/modelFiles/qjsonCompile
 const pull_1 = require("../control/pull");
 const push_1 = require("../control/push");
 const state_1 = require("../util/state");
+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");
@@ -20,36 +21,37 @@ const PING_INTERVAL_MS = 20000;
 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;
-    // Sabit rendezvous portu listener'ı — web buraya bağlanınca efemer portu bildirir, sonra serbest bırakılır.
+    // 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.
+    // 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;
     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;
-    port = 0; // OS'in atadığı efemer port (bind() doldurur)
+    port = 0; // ephemeral port assigned by the OS (bind() fills it in)
     rootDir;
     constructor(options = {}) {
         this.host = options.host ?? "127.0.0.1";
@@ -61,27 +63,28 @@ class BridgeServer {
         return this.rootDir;
     }
     async start() {
-        // Önceki (çökmüş) server'dan kalma claim'i temizle — bu fresh bir server.
-        //TODO: bunu burada yapmanin yan etkilerini dusun.
+        // 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.removeServerInfoSync)(this.rootDir);
+            (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();
     }
-    // Sabit rendezvous portunu dinle. Web buraya bağlanınca efemer bridge portunu bildirir, sonra portu
-    // serbest bırakırız (başka CLI kullanabilir). Port doluysa (başka CLI tutuyor) sessizce atla.
+    // 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 });
-        // Web bağlanınca efemer portu bildir. Rendezvous'u BURADA kapatma — web efemer porta bağlanıp
-        // hello ile canlı client olunca kapatılır (onHello → closeRendezvous). Böylece web efemer'a
-        // ulaşamazsa rendezvous'tan tekrar deneyebilir.
+        // 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); // frame flush olsun
+            setTimeout(() => conn.close(1000, "rendezvous done"), 500); // let the frame flush
         });
         try {
             await wss.listen();
@@ -91,9 +94,9 @@ class BridgeServer {
         catch (err) {
             wss.close();
             if (err.code === "EADDRINUSE") {
-                // Başka bir CLI zaten keşif noktası. Protokol-launch (klasörsüz) ise bu instance redundant —
-                // web onu değil rendezvous'u tutanı bulur → orphan kalmasın diye çık. Elle `--dir <path>`
-                // başlatılmışsa (rootDir set) çıkma; kullanıcı bilinçli açtı, savedPort'la ulaşılabilir.
+                // 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();
@@ -118,15 +121,16 @@ class BridgeServer {
     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();
         if (this.rootDir !== undefined)
-            (0, serverInfo_1.removeServerInfoSync)(this.rootDir);
+            (0, serverInfo_1.clearServerInfoRuntimeSync)(this.rootDir);
     }
-    /** OS'in atadığı efemer porta bind et (port:0 → OS boş port seçer). Portu web rendezvous ile öğrenir. */
+    /** 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 wss = new wsRaw_1.RawWebSocketServer({ host: this.host, port: 0 });
         wss.onConnection((conn) => this.onConnection(conn));
@@ -135,7 +139,7 @@ class BridgeServer {
         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);
         peer.onEnvelope((env) => this.dispatch(peer, env));
@@ -144,8 +148,8 @@ class BridgeServer {
     }
     onPeerClose(peer) {
         if (peer === this.bridgeClient) {
-            // F5/sayfa kapanması: client gider ama claim + server.json KALIR (reconnect için).
-            // Picker açıkken tab kapandıysa sahipsiz pencereyi kapat (sonuç zaten düşürülecek).
+            // 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;
@@ -164,8 +168,8 @@ class BridgeServer {
     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":
@@ -180,7 +184,7 @@ class BridgeServer {
             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;
@@ -220,8 +224,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;
@@ -230,20 +234,20 @@ 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, 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, 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}`);
@@ -253,9 +257,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
@@ -270,12 +274,12 @@ class BridgeServer {
         peer.reply(env, "helloAck", { cliVersion: version_1.VERSION, protocol: protocolVersion_1.GENERATION, rootDir: this.rootDir ?? null });
         this.startPing();
         this.cancelIdleExit();
-        // Web efemer porta bağlanıp handshake yaptı → keşif tamam, rendezvous'u serbest bırak.
+        // 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) {
@@ -301,7 +305,7 @@ class BridgeServer {
         peer.reply(env, "helloAck", { cliVersion: version_1.VERSION, protocol: protocolVersion_1.GENERATION, rootDir: this.rootDir ?? null });
         this.startPing();
         this.cancelIdleExit();
-        // Test client push'lardan SONRA bağlanmış/F5 atmış olabilir → oturumun birikmiş gövdelerini gönder.
+        // 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");
     }
@@ -322,9 +326,9 @@ class BridgeServer {
             logger_1.logger.error(`failed to write server.json: ${err.message}`);
         }
     }
-    // Klasörsüz server: web helloAck.rootDir === null görüp pickFolder ister. Native picker açılır;
-    // dolu klasör (canlı başka server claim'i) seçilirse folderInUse yollanıp picker yeniden açılır.
-    // Seçimde rootDir set edilir + (claim'liyse) server.json yazılır. Cancel → path:null.
+    // 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" });
@@ -343,7 +347,7 @@ class BridgeServer {
             while (peer.isOpen) {
                 const picked = await (0, pickWorkspaceDir_1.pickWorkspaceDir)();
                 if (!peer.isOpen)
-                    return; // picker açıkken tab kapandı → sonucu düşür
+                    return; // tab closed while the picker was open → drop the result
                 if (!picked) {
                     peer.reply(env, "pickFolderResult", { path: null });
                     return;
@@ -353,6 +357,13 @@ class BridgeServer {
                     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);
@@ -365,10 +376,10 @@ class BridgeServer {
             this._pickerOpen = false;
         }
     }
-    // --- control kanalı (HTTP /control/<cmd>) — santral relay ---
-    // wsRaw'dan gelen WS-olmayan HTTP. Control isteğini sahiplen (true); gerisi false → 426.
+    // --- 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();
@@ -379,20 +390,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" });
@@ -439,7 +450,7 @@ 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" });
@@ -452,16 +463,18 @@ class BridgeServer {
         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":...}
+                    // 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.workspaceDir, 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: `${total} model(s)${readOnly > 0 ? ` (${readOnly} read-only)` : ""} and .ai-kit pulled` }) + "\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");
@@ -469,12 +482,12 @@ class BridgeServer {
                     return;
                 }
                 case "push": {
-                    // rootDir'i tara → mevcut (models) + yeni (newModels) dosyaları topla → bulk relay → state güncelle.
+                    // 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);
-                    // NDJSON stream aç — client progress bar çizer (controlClient.ts readNdjsonStream).
+                    // 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");
@@ -484,20 +497,28 @@ class BridgeServer {
                         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 pushTimeoutMs = Math.max(300000, total * 60000);
-                        const result = await this.bridgeClient.request("push", { models, newModels, deletedIds }, pushTimeoutMs);
-                        // 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 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 };
@@ -507,8 +528,8 @@ class BridgeServer {
                         counts.okRefFiles = await this.syncReferences(result.results ?? [], result.deletedResults ?? [], state, res);
                         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);
                         }
@@ -521,8 +542,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);
@@ -586,9 +607,9 @@ 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.
-     *  Move owner'ı değiştirdiyse local frontmatter'daki ownerName da güncellenir. */
+    // --- 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) {
@@ -612,7 +633,7 @@ class BridgeServer {
             tick();
         }
     }
-    /** Move sonrası dosyanın frontmatter ownerName'ini yeni owner'a günceller (gövde/hash değişmez). */
+    /** 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 {
@@ -626,7 +647,7 @@ class BridgeServer {
             logger_1.logger.warn(`frontmatter ownerName update failed for ${pm.newName}: ${err.message}`);
         }
     }
-    /** Yeni dosyalar: yeni yaratılana frontmatter yaz, state hash hesapla; her öğe için progress. */
+    /** 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) {
@@ -657,7 +678,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) {
@@ -670,9 +691,9 @@ 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 }] : []);
@@ -691,7 +712,7 @@ class BridgeServer {
                 }
             }
             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);
@@ -712,7 +733,7 @@ class BridgeServer {
         }
         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;
@@ -738,10 +759,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 ?? []) {
@@ -754,7 +775,7 @@ 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;
@@ -765,7 +786,7 @@ class BridgeServer {
         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);
@@ -773,8 +794,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;
@@ -791,7 +812,7 @@ 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}`);
@@ -812,28 +833,28 @@ 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, qjsonCompiled_1.stripQJsonCompiledFields)(payload.model) : payload.model;
-            // Kullanıcı Studio'da kaydettiyse test replay'i (F5) bayat push gövdesine dönmesin.
+            // 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)(rootDir);
-            // Push echo guard: hash state ile aynıysa (az önce pushladık) body yazmayı atla
+            // 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)(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));
@@ -857,9 +878,9 @@ class BridgeServer {
             }
         }
     }
-    // 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}`);
@@ -888,28 +909,27 @@ class BridgeServer {
             logger_1.logger.debug(`modelDeleted: no workspace — dropping id=${payload.modelId}`);
             return;
         }
-        this.lastSync.delete(payload.modelId); // replay silinen modeli diriltmesin
+        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.workspaceDir);
         delete state[payload.modelId];
         await (0, state_1.writeState)(this.workspaceDir, state);
-        logger_1.logger.info(`auto-deleted: ${(0, node_path_1.relative)(this.workspaceDir, abs)}`);
+        this.trashQueue.enqueue(abs, this.workspaceDir);
     }
     async handleCheckoutChanged(payload) {
         if (this.rootDir === undefined) {
             logger_1.logger.debug(`checkoutChanged: no workspace — dropping id=${payload.modelId}`);
             return;
         }
-        // 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.
+        // 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;
@@ -936,7 +956,7 @@ class BridgeServer {
         }
         return null;
     }
-    // --- keepalive (bridge client'a) ---
+    // --- keepalive (to the bridge client) ---
     startPing() {
         this.stopPing();
         this.pingTimer = setInterval(() => {
@@ -951,8 +971,8 @@ class BridgeServer {
             this.pingTimer = undefined;
         }
     }
-    // Client'sız (tarayıcı/sekme kapalı ya da hiç bağlanılmamış) geçen süre IDLE_EXIT_MS'i aşarsa
-    // process'i kapat → arka planda claimsiz port birikmesin. Bir client bağlanınca iptal edilir.
+    // 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(() => {
@@ -969,8 +989,9 @@ class BridgeServer {
     }
 }
 exports.BridgeServer = BridgeServer;
-// Klasörde canlı bir başka studio server var mı? server.json'daki pid'in yaşadığına bakar.
-// Bayat (çökmüş server) server.json'u kilit saymaz — o klasör yeniden claim edilebilir.
+// 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 {
@@ -979,16 +1000,28 @@ function isWorkspaceLocked(dir) {
     catch {
         return false;
     }
-    if (!info)
+    const pid = info?.pid;
+    if (pid === undefined)
         return false;
     try {
-        process.kill(info.pid, 0);
+        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 })) {