@nac3/forge-cli 1.1.0 → 1.2.0

package/dist/chat/instance_lock.d.ts

@@ -0,0 +1,35 @@
+export interface LockHolder {
+    pid: number;
+    port: number;
+    root: string;
+    since: number;
+}
+export interface LockResult {
+    ok: boolean;
+    /** Present when ok=false: the live instance already holding this root. */
+    holder?: LockHolder;
+    /** Present when ok=true: remove the lock (only if we still own it). */
+    release?: () => void;
+    /** Present when ok=true: rewrite the stored port once the real bound port
+     *  is known (the requested port may have changed via fallback). */
+    update?: (port: number) => void;
+}
+/** Thrown by startChatServer when a live instance already owns the root. */
+export declare class DuplicateInstanceError extends Error {
+    readonly holder: LockHolder;
+    constructor(holder: LockHolder);
+}
+/** True when a process with `pid` is currently running. `process.kill(pid, 0)`
+ *  sends no signal -- it only probes existence. EPERM means it exists but is
+ *  not ours (still alive); ESRCH means gone. */
+export declare function pidAlive(pid: number): boolean;
+/** Claim the single-instance lock for a project root. Returns {ok:false,
+ *  holder} if a LIVE instance already owns it, else writes our lock and
+ *  returns {ok:true, release, update}. */
+export declare function acquireProjectLock(root: string, self: {
+    pid: number;
+    port: number;
+}): LockResult;
+/** A human, actionable message for the CLI when a duplicate is refused. */
+export declare function duplicateMessage(holder: LockHolder): string;
+//# sourceMappingURL=instance_lock.d.ts.map

package/dist/chat/instance_lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance_lock.d.ts","sourceRoot":"","sources":["../../src/chat/instance_lock.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,UAAU;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;CAAE;AAEvF,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,0EAA0E;IAC1E,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;uEACmE;IACnE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,4EAA4E;AAC5E,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;gBAChB,MAAM,EAAE,UAAU;CAK/B;AAaD;;gDAEgD;AAChD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAI7C;AAUD;;0CAE0C;AAC1C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CA+BhG;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAO3D"}

package/dist/chat/instance_lock.js

@@ -0,0 +1,118 @@
+/**
+ * Single-instance-per-project lock (2026-09-02).
+ *
+ * Guard so two `yf chat` instances do NOT open the SAME project root: a
+ * duplicate wastes a whole relay-poll stream (real Cloudflare cost) and
+ * causes the multi-instance relay race. The lock is a small JSON file under
+ * the OS temp dir, keyed by a hash of the NORMALISED root, holding the
+ * owner's { pid, port, since }.
+ *
+ * Rules:
+ *  - A live holder (its pid still alive AND not us) -> refuse.
+ *  - A stale lock (dead pid, or corrupt/absent file) -> reclaim.
+ *  - release() removes the file only if we still own it.
+ *  - Headless sub-sessions (agentMode) and the test harness bypass the lock
+ *    at the caller; this module only implements acquire/release.
+ *
+ * ASCII-only.
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** Thrown by startChatServer when a live instance already owns the root. */
+export class DuplicateInstanceError extends Error {
+    holder;
+    constructor(holder) {
+        super('Ya hay una instancia de Forge abierta en este proyecto.');
+        this.name = 'DuplicateInstanceError';
+        this.holder = holder;
+    }
+}
+function normRoot(root) {
+    const r = path.resolve(root);
+    return process.platform === 'win32' ? r.toLowerCase() : r;
+}
+function lockPath(root) {
+    const dir = path.join(os.tmpdir(), 'yujin-forge', 'locks');
+    const h = createHash('sha1').update(normRoot(root)).digest('hex').slice(0, 16);
+    return path.join(dir, h + '.json');
+}
+/** True when a process with `pid` is currently running. `process.kill(pid, 0)`
+ *  sends no signal -- it only probes existence. EPERM means it exists but is
+ *  not ours (still alive); ESRCH means gone. */
+export function pidAlive(pid) {
+    if (!pid || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+function readHolder(p) {
+    try {
+        const h = JSON.parse(readFileSync(p, 'utf-8'));
+        if (h && typeof h.pid === 'number')
+            return h;
+    }
+    catch { /* absent or corrupt */ }
+    return null;
+}
+/** Claim the single-instance lock for a project root. Returns {ok:false,
+ *  holder} if a LIVE instance already owns it, else writes our lock and
+ *  returns {ok:true, release, update}. */
+export function acquireProjectLock(root, self) {
+    const p = lockPath(root);
+    try {
+        mkdirSync(path.dirname(p), { recursive: true });
+    }
+    catch { /* exists */ }
+    const write = (port) => {
+        const holder = { pid: self.pid, port, root: path.resolve(root), since: Date.now() };
+        try {
+            writeFileSync(p, JSON.stringify(holder), 'utf-8');
+        }
+        catch { /* best effort */ }
+    };
+    /* Exclusive create wins the common no-lock case + the simultaneous race. */
+    try {
+        writeFileSync(p, JSON.stringify({ pid: self.pid, port: self.port, root: path.resolve(root), since: Date.now() }), { flag: 'wx' });
+    }
+    catch {
+        /* File exists -> inspect the incumbent. */
+        const held = readHolder(p);
+        if (held && held.pid !== self.pid && pidAlive(held.pid)) {
+            return { ok: false, holder: held };
+        }
+        /* Stale (dead pid) or ours -> reclaim by overwriting. */
+        write(self.port);
+    }
+    const release = () => {
+        const cur = readHolder(p);
+        if (cur && cur.pid === self.pid) {
+            try {
+                rmSync(p, { force: true });
+            }
+            catch { /* gone */ }
+        }
+    };
+    const update = (port) => {
+        const cur = readHolder(p);
+        if (!cur || cur.pid === self.pid)
+            write(port);
+    };
+    return { ok: true, release, update };
+}
+/** A human, actionable message for the CLI when a duplicate is refused. */
+export function duplicateMessage(holder) {
+    return 'Ya hay una instancia de Forge abierta en este proyecto:\n'
+        + '  ' + holder.root + '\n'
+        + '  (PID ' + holder.pid + ', panel en http://127.0.0.1:' + holder.port + ')\n\n'
+        + 'Abri esa instancia, o abri Forge en OTRA carpeta. Si estas seguro de que\n'
+        + 'la anterior murio, volve a intentar (el lock viejo se descarta solo) o\n'
+        + 'forza con --force.';
+}
+//# sourceMappingURL=instance_lock.js.map

package/dist/chat/instance_lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instance_lock.js","sourceRoot":"","sources":["../../src/chat/instance_lock.ts"],"names":[],"mappings":"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"}

package/dist/chat/server.d.ts

@@ -53,6 +53,10 @@ export interface StartOptions {
      *  phone command). The child's verb scope is gated separately by the
      *  YF_AGENT_MODE env flag in nac3_invoke. */
     agentMode?: boolean;
+    /** Escape hatch for the single-instance-per-root guard (2026-09-02). When
+     *  true, allow opening even if another live instance already owns this
+     *  project root. Wired to `yf chat --force`. */
+    allowDuplicateRoot?: boolean;
 }
 export interface StartedServer {
     server: Server;

package/dist/chat/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/chat/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/chat/server.ts"],"names":[],"mappings":"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"}

package/dist/chat/server.js

@@ -41,10 +41,12 @@ import { executeScaffold, rollbackScaffold } from './spec_scaffold.js';
 import { VERSION } from '../version.js';
 import { readProjectIdentityCached, formatProjectIdentityLines } from '../core/project_identity.js';
 import { buildDoctrineDigestLines } from './doctrine_digest.js';
+import { acquireProjectLock, DuplicateInstanceError } from './instance_lock.js';
 import { profilePromptLines, initProfile, activeProfile } from '../core/forge_profile.js';
 import { isAllowedSlot, listAllowedSlots } from '../core/provider_keys.js';
 import { toolStatusSection, startToolStatusRefresh, environmentLines } from './tool_status.js';
 import { RelayPublisher } from '../relay/relay_publisher.js';
+import { getInstanceIdentity } from '../relay/instance_identity.js';
 import { isMobilePaired, relayGate } from '../core/mobile_pairing_state.js';
 import { relayPoll } from '../relay/relay_client.js';
 import { startCommandConsumer } from '../relay/command_consumer.js';
@@ -74,6 +76,19 @@ async function findFreePort(start, host, maxTries = 50) {
     throw new Error('No free port found in ' + start + '..' + (start + maxTries));
 }
 export async function startChatServer(opts) {
+    /* Single-instance-per-project guard (2026-09-02). Refuse a 2nd `yf chat` on
+     * the SAME root: it wastes a whole relay-poll stream (real Cloudflare cost)
+     * and triggers the multi-instance relay race. Bypassed for headless
+     * sub-sessions (agentMode), the test harness (injected claude), and an
+     * explicit --force (allowDuplicateRoot). The port is a placeholder here and
+     * gets rewritten to the real bound port after listen. */
+    let projectLock = null;
+    if (!opts.agentMode && !opts.claude && !opts.allowDuplicateRoot) {
+        const lock = acquireProjectLock(opts.projectRoot, { pid: process.pid, port: opts.port });
+        if (!lock.ok && lock.holder)
+            throw new DuplicateInstanceError(lock.holder);
+        projectLock = lock;
+    }
     /* Port auto-increment: if the requested port is taken (another yf chat is
      * already there), step up to the next free one. Determined BEFORE anything
      * reads opts.port (panel MCP bridge, relay consumer, url), so every consumer
@@ -459,6 +474,22 @@ export async function startChatServer(opts) {
         };
         tryListen(opts.port);
     });
+    /* Port-race fix (2026-09-01). The eager `claude` client above was built
+     * BEFORE the EADDRINUSE retry could finalize opts.port. The CLI client
+     * FREEZES panelBridge.port at construction, so when two instances race for
+     * the same port and this one fell back, its panelBridge still points at the
+     * ORIGINAL (now someone else's) port -> the `claude -p` subprocess POSTs
+     * panel-invoke to the WRONG server with the wrong token -> 403. Now that
+     * opts.port is the REAL bound port, rebuild the CLI client so its bridge
+     * points home. No-op in the common (no-fallback) case; skipped when a client
+     * was injected (tests) or the provider is not the CLI bridge. */
+    if (!opts.claude && activeChatProvider === 'claude-code-cli') {
+        claude = await buildClaudeClient(activeChatProvider);
+    }
+    /* Now that the real bound port is known (post fallback), stamp it into the
+     * single-instance lock so a later duplicate points the user at the right
+     * panel URL. */
+    projectLock?.update?.(opts.port);
     /* P2 -- relay command consumer (inbound phone chat) + the board ctx.
      * Start the consumer ALWAYS: it self-gates on relayEnabled() every tick,
      * so if the user pairs a phone MID-SESSION it wakes up automatically (no
@@ -573,6 +604,17 @@ export async function startChatServer(opts) {
             if (bridgeHandle) {
                 Promise.resolve(bridgeHandle.stop()).catch(() => undefined);
             }
+            /* Release the single-instance-per-project lock (2026-09-02) so the next
+             * `yf chat` on this root is allowed in. */
+            try {
+                projectLock?.release?.();
+            }
+            catch { /* noop */ }
+            /* Stop the "remote running..." relay heartbeat. */
+            try {
+                stopRelayHeartbeat();
+            }
+            catch { /* noop */ }
             /* alpha.59z.136 slice 14 -- flush in-flight ingest session
              * writes BEFORE the server closes so test teardowns that
              * fs.rm the home directory immediately after do not race
@@ -606,6 +648,7 @@ function getRelayPublisher() {
         _relayPub = new RelayPublisher({
             deps: { deviceId: 'desktop-' + process.pid }, /* default auth = vault + license */
             enabled: relayEnabled,
+            instanceId: getInstanceIdentity().id, /* item 2: tag every event so the phone mirrors only the chosen instance */
         });
     }
     return _relayPub;
@@ -822,8 +865,10 @@ function startDesktopCommandConsumer(port, coord = {}) {
      * a phone interrupt lands MID-TURN instead of waiting for it to end.
      * Each filters to its own subset; the other still advances its cursor
      * past the skipped events. */
+    const selfInstanceId = getInstanceIdentity().id;
     const chat = startCommandConsumer({
         enabled: relayEnabled, intervalMs: 3000,
+        instanceId: selfInstanceId, /* item 2: run only commands targeted at me (or untargeted) */
         /* only MY project's chat commands (multi-instance integrity); the other
          * instances' consumers advance their cursor past the skipped ones. */
         accept: (c) => !c.control && ownsChatCommand(c.projectSlug),
@@ -833,12 +878,30 @@ function startDesktopCommandConsumer(port, coord = {}) {
     });
     const control = startCommandConsumer({
         enabled: relayEnabled, intervalMs: 1200,
+        instanceId: selfInstanceId,
         accept: (c) => !!c.control,
         pollCommands, runTurn, onControl, reply,
         onError: () => { },
     });
+    /* Item 2 (cross-machine): advertise this instance's presence on a slow
+     * heartbeat (gated by relayEnabled -> only when a phone is paired) so the
+     * phone can list + pick instances across machines and TTL-expire dead ones. */
+    const presenceTimer = setInterval(() => {
+        try {
+            const pub = getRelayPublisher();
+            if (!pub)
+                return;
+            const idn = getInstanceIdentity();
+            const slug = _relayBoardCtx?.slug ?? null;
+            pub.presence({ hostname: idn.hostname, pid: idn.pid, port, ...(slug ? { project_slug: slug, project_name: slug } : {}) });
+            void pub.flush();
+        }
+        catch { /* best-effort */ }
+    }, 15000);
+    if (typeof presenceTimer.unref === 'function')
+        presenceTimer.unref();
     return {
-        stop() { clearInterval(peerTimer); chat.stop(); control.stop(); },
+        stop() { clearInterval(peerTimer); clearInterval(presenceTimer); chat.stop(); control.stop(); },
         tickOnce: async () => { await refreshPeers(); await chat.tickOnce(); await control.tickOnce(); },
     };
 }
@@ -1006,31 +1069,56 @@ async function handleForgeTaskDelete(req, res, ctx) {
     const removed = await sup.remove(id);
     sendJson(res, removed ? 200 : 404, { ok: removed, id });
 }
+/* Low-frequency "remote running..." heartbeat to the phone while the desktop
+ * is thinking (Pablo 2026-09-02). Replaces the per-tool activity stream, which
+ * was the bulk of the relay's Cloudflare appends and only calmed anxiety. The
+ * pizarron (board) still refreshes -- THAT is the signal that adds value. */
+let _relayHeartbeat = null;
+function stopRelayHeartbeat() {
+    if (_relayHeartbeat) {
+        clearInterval(_relayHeartbeat);
+        _relayHeartbeat = null;
+    }
+}
+function startRelayHeartbeat() {
+    stopRelayHeartbeat();
+    _relayHeartbeat = setInterval(() => {
+        try {
+            const pub = getRelayPublisher();
+            if (!pub) {
+                stopRelayHeartbeat();
+                return;
+            }
+            pub.activity('remote running...', { kind: 'heartbeat' });
+            void pub.flush();
+        }
+        catch { /* best-effort */ }
+    }, 60_000);
+    if (typeof _relayHeartbeat.unref === 'function')
+        _relayHeartbeat.unref();
+}
 function relayForward(event, data) {
     const pub = getRelayPublisher();
     if (!pub)
         return;
     try {
         const d = (data && typeof data === 'object') ? data : {};
-        if (event === 'tool_round_start') {
-            pub.activity(String(d.summary || d.verb_hint || d.verb_id || 'trabajando'), d.detail);
-        }
-        else if (event === 'turn_start') {
+        /* tool_round_start: intentionally NO relay activity anymore -- the granular
+         * per-tool feed was the append-heavy part; the phone now gets a heartbeat. */
+        if (event === 'turn_start') {
             pub.status('working', { tier: d.tier, provider: d.provider, model: d.model });
-            /* PND-132 -- a per-turn heartbeat in the activity feed so it does not
-             * look frozen for hours on turns that run no tools (pure text replies).
-             * Before, the feed only got an entry on tool_round_start. */
-            const ut = typeof d.user_text === 'string' ? d.user_text.slice(0, 80) : '';
-            pub.activity(ut ? 'procesando: ' + ut : 'nuevo turno', { kind: 'task' });
+            pub.activity('remote running...', { kind: 'heartbeat' }); /* first line now; then every 60s */
+            startRelayHeartbeat();
         }
         else if (event === 'turn_complete') {
+            stopRelayHeartbeat();
             pub.status('round_done');
-            pub.activity('turno completo', { kind: 'task' });
             /* refresh the phone's board after each turn (workflow/pendings may
-             * have changed). */
+             * have changed) -- the pizarron is the value the user keeps. */
             publishBoardSnapshot();
         }
         else if (event === 'error') {
+            stopRelayHeartbeat();
             pub.status('error', { message: d.message ?? d.error ?? '' });
         }
     }