handmux 0.30.0 → 0.31.0

package/dist/src/workspace/checkpointer.js

@@ -1,9 +1,17 @@
 import { captureWorkspace } from './capture.js';
 import { detectEnvironmentChange } from './environment.js';
+import { lockOwnerLabel } from './lock.js';
 import { fingerprintSnapshot } from './schema.js';
 function sameSnapshot(left, right) {
     return fingerprintSnapshot(left) === fingerprintSnapshot(right);
 }
+function formatDuration(ms) {
+    const seconds = Math.max(0, Math.round(ms / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.round(seconds / 60);
+    return minutes < 60 ? `${minutes}m` : `${Math.round(minutes / 60)}h`;
+}
 function snapshotEnvironment(observed) {
     return {
         id: observed.id,
@@ -13,8 +21,16 @@ function snapshotEnvironment(observed) {
 }
 async function reconcileOnce(deps, cause) {
     const handle = await deps.lock.tryAcquire({ operationId: `checkpointer:${cause}` });
-    if (!handle)
-        return { status: 'locked' };
+    if (!handle) {
+        // Report who is holding it: "locked" on its own is indistinguishable from a stuck lock, which is
+        // exactly how a blocked checkpointer stayed invisible.
+        let owner = null;
+        try {
+            owner = await deps.lock.readOwner?.() ?? null;
+        }
+        catch { /* the holder may be unreadable */ }
+        return { status: 'locked', owner };
+    }
     try {
         const observed = await deps.observeEnvironment();
         if (!observed || observed.status === 'unknown')
@@ -75,6 +91,19 @@ export function createCheckpointer({ setInterval = globalThis.setInterval, clear
     let stopPromise = null;
     let lastResult = null;
     let lastError = null;
+    let blockedSince = null;
+    let blockedOwner = null;
+    function recordResult(result) {
+        lastResult = result;
+        if (result.status !== 'locked') {
+            blockedSince = null;
+            blockedOwner = null;
+            return;
+        }
+        if (blockedSince === null)
+            blockedSince = now();
+        blockedOwner = lockOwnerLabel(result.owner);
+    }
     function launch(cause) {
         const current = reconcileOnce(deps, cause);
         running = current;
@@ -89,7 +118,7 @@ export function createCheckpointer({ setInterval = globalThis.setInterval, clear
             }
         };
         current.then((result) => {
-            lastResult = result;
+            recordResult(result);
             lastError = null;
             settled();
         }, () => {
@@ -131,6 +160,12 @@ export function createCheckpointer({ setInterval = globalThis.setInterval, clear
     const outstanding = () => (running ?? pendingConfirmation?.promise ?? null);
     return {
         reconcile,
+        // How long the writer lock has been unavailable, with whoever holds it. Null while reconciliation is
+        // free to run. Readiness cannot answer this — a restore holding the lock is legitimately "locked" and
+        // the launcher must still see the server as up — so the protection status consumes this instead.
+        blocked() {
+            return blockedSince === null ? null : { since: blockedSince, owner: blockedOwner };
+        },
         health() {
             if (stopping || stopped)
                 return { status: 'degraded', detail: 'workspace-stopped' };
@@ -142,7 +177,16 @@ export function createCheckpointer({ setInterval = globalThis.setInterval, clear
                 return { status: 'ready', detail: null };
             }
             if (lastResult.status === 'locked') {
-                return { status: 'ready', detail: 'workspace-writer-locked' };
+                // Still "ready": a restore holds this lock on purpose, and the launcher must not read that as the
+                // server being down. The detail carries the holder and the duration so a lock that never clears is
+                // diagnosable from the outside.
+                const held = blockedSince === null ? null : formatDuration(now() - blockedSince);
+                return {
+                    status: 'ready',
+                    detail: 'workspace-writer-locked'
+                        + (blockedOwner ? `: ${blockedOwner}` : '')
+                        + (held ? ` for ${held}` : ''),
+                };
             }
             return { status: 'degraded', detail: `workspace-${lastResult.status || 'unknown'}` };
         },

package/dist/src/workspace/lock.js

@@ -17,13 +17,19 @@ function defaultProcessAlive(pid) {
     }
 }
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-function ownerLabel(value) {
+/** Who a lock record says is holding it, or null when the record says nothing usable. */
+export function lockOwnerLabel(value) {
     const owner = asRecord(value);
     if (!owner)
-        return 'unknown owner';
-    const operation = typeof owner.operationId === 'string' && owner.operationId ? owner.operationId : 'unknown operation';
-    const pid = Number.isInteger(owner.pid) ? owner.pid : 'unknown';
-    return `${operation} (pid ${pid})`;
+        return null;
+    const operation = typeof owner.operationId === 'string' && owner.operationId ? owner.operationId : null;
+    const pid = Number.isInteger(owner.pid) ? owner.pid : null;
+    if (!operation && pid === null)
+        return null;
+    return `${operation || 'unknown operation'} (pid ${pid ?? 'unknown'})`;
+}
+function ownerLabel(value) {
+    return lockOwnerLabel(value) ?? 'unknown owner';
 }
 export function createWorkspaceLock({ dir, fs = fsp, pid = process.pid, now = Date.now, isProcessAlive = defaultProcessAlive, wait = delay, timeoutMs = 5_000, retryMs = 50, staleGraceMs = 5_000, randomUUID = crypto.randomUUID, }) {
     if (typeof dir !== 'string' || !dir)
@@ -46,21 +52,59 @@ export function createWorkspaceLock({ dir, fs = fsp, pid = process.pid, now = Da
             return { value: null, mtimeMs: stat.mtimeMs };
         }
     }
+    async function reclaimUnreadableOwner(record) {
+        // The record is missing, truncated, or malformed — the shape a holder leaves when it dies between
+        // creating the directory and writing its record. Age is the directory's own, which is when it appeared.
+        // `rmdir` only removes an EMPTY directory, so this can never take the lock from a holder that has
+        // already written its record; an empty directory is by definition nobody's. The worst a contender can
+        // do to a holder is hit the microseconds before that holder's own record exists, and that holder then
+        // fails loudly instead of silently sharing the lock.
+        try {
+            await fs.rmdir(dir);
+            return true;
+        }
+        catch (error) {
+            if (errorCode(error) === 'ENOENT')
+                return true;
+            if (errorCode(error) !== 'ENOTEMPTY')
+                return false;
+        }
+        // Not empty after all: a record exists but cannot be read. Move the whole directory aside. The
+        // destination comes from the observed mtime, never from the unvalidated record, so no path is built
+        // from content we could not verify — and because the directory is not empty, the tombstone it leaves
+        // cannot be replaced by a lock taken after this look.
+        const staleDir = `${dir}.stale.unreadable-${Math.round(record.mtimeMs)}`;
+        try {
+            await fs.rename(dir, staleDir);
+        }
+        catch (error) {
+            if (errorCode(error) === 'ENOENT')
+                return true;
+            return false;
+        }
+        return true;
+    }
     async function reclaimIfStale(record) {
         if (!record)
             return true;
         const owner = asRecord(record.value);
-        if (!owner || typeof owner.token !== 'string' || !SAFE_TOKEN.test(owner.token))
-            return false;
-        const startedAt = typeof owner.startedAt === 'string' ? Date.parse(owner.startedAt) : Number.NaN;
+        const candidate = owner?.token;
+        const token = typeof candidate === 'string' && SAFE_TOKEN.test(candidate) ? candidate : null;
+        // An unusable record carries no trustworthy clock, so its age comes from the directory itself.
+        const startedAt = token && owner && typeof owner.startedAt === 'string' ? Date.parse(owner.startedAt) : Number.NaN;
         const age = now() - (Number.isFinite(startedAt) ? startedAt : record.mtimeMs);
+        // The grace period is what keeps a contender out of the window between a holder's `mkdir` and the
+        // record it is about to write.
         if (age < staleGraceMs)
             return false;
-        if (typeof owner.pid === 'number' && Number.isInteger(owner.pid) && await isProcessAlive(owner.pid))
+        const pid = owner && typeof owner.pid === 'number' && Number.isInteger(owner.pid) ? owner.pid : null;
+        if (pid !== null && await isProcessAlive(pid))
             return false;
+        if (!token)
+            return reclaimUnreadableOwner(record);
         // Every contender that observed this owner uses the SAME destination. The winner leaves the renamed
         // directory as a tombstone, so a loser cannot later rename a newly-created lock out of the way.
-        const staleDir = `${dir}.stale.${owner.token}`;
+        const staleDir = `${dir}.stale.${token}`;
         try {
             await fs.rename(dir, staleDir);
         }

package/dist/src/workspace/runtime.js

@@ -7,6 +7,10 @@ import { buildRecoveryMapping, } from './mapping.js';
 const recordOf = (value) => (value && typeof value === 'object' && !Array.isArray(value)
     ? value : null);
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+// A restore holds the writer lock for as long as it runs, and that is normal — so a lock somebody else is
+// holding only means the workspace stopped being captured once it has been held far longer than a restore
+// takes. Nothing here steals the lock; it changes what the status reports.
+const WRITER_BLOCK_THRESHOLD_MS = 5 * 60_000;
 function unwrapCheckpoint(result) {
     const record = recordOf(result);
     if (record?.status !== 'ok' || !record.value) {
@@ -192,17 +196,28 @@ export function createWorkspaceRuntime({ store, tmux, lock, checkpointer, now =
         catch {
             return { status: 'degraded', lastSuccessfulCaptureAt: null, errorCode: 'live-unavailable' };
         }
+        if (live.status !== 'ok' && live.status !== 'empty') {
+            return {
+                status: 'degraded',
+                lastSuccessfulCaptureAt: null,
+                errorCode: live.status === 'corrupt' ? 'live-corrupt' : 'live-unavailable',
+            };
+        }
+        // A healthy live copy is not protection: if the writer lock has been out of reach for long enough, the
+        // copy is simply the last one that was ever written, and capture is what has stopped.
+        const blocked = checkpointer.blocked?.();
+        if (blocked && Number.isFinite(blocked.since) && now() - blocked.since >= WRITER_BLOCK_THRESHOLD_MS) {
+            return {
+                status: 'degraded',
+                lastSuccessfulCaptureAt: live.status === 'ok' ? live.value.capturedAt || null : null,
+                errorCode: 'writer-locked',
+                blockedBy: blocked.owner,
+            };
+        }
         if (live.status === 'ok') {
             return { status: 'protected', lastSuccessfulCaptureAt: live.value.capturedAt || null, errorCode: null };
         }
-        if (live.status === 'empty') {
-            return { status: 'unprotected', lastSuccessfulCaptureAt: null, errorCode: null };
-        }
-        return {
-            status: 'degraded',
-            lastSuccessfulCaptureAt: null,
-            errorCode: live.status === 'corrupt' ? 'live-corrupt' : 'live-unavailable',
-        };
+        return { status: 'unprotected', lastSuccessfulCaptureAt: null, errorCode: null };
     }
     async function performRestore(operationId, request, onProgress, onRunning, onTerminal) {
         let result;

package/dist/src/workspaceProtocol.js

@@ -42,6 +42,7 @@ export function parseWorkspaceProtectionStatus(value) {
         ...optionalField('status', memberOf(PROTECTION_STATUSES, status.status)),
         ...optionalField('lastSuccessfulCaptureAt', optionalString(status.lastSuccessfulCaptureAt)),
         ...optionalField('errorCode', optionalString(status.errorCode)),
+        ...optionalField('blockedBy', optionalString(status.blockedBy)),
     };
 }
 export function parseWorkspaceRestoreStart(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handmux",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "A mobile vibe-coding cockpit — built on tmux: drive your live session, Claude Code / Codex — anything a terminal can run — from your phone.",
   "type": "module",
   "license": "AGPL-3.0-only",
@@ -75,13 +75,13 @@
     "vitest": "^2.0.0"
   },
   "whatsNew": [
+    {"version":"0.31.0","date":"2026-09-22","zh":"CodeBuddy 对话接入 · Agent 状态更可靠","en":"CodeBuddy chat support · more reliable Agent state"},
     {"version":"0.30.0","date":"2026-09-19","zh":"文档预览全面升级：朗读、目录、查找、图表","en":"A full document reader: read-aloud, outline, search, diagrams"},
     {"version":"0.29.2","date":"2026-09-18","zh":"修复 Linux 下 Claude 事件上报的兼容问题","en":"Compatibility fix for Claude event reporting on Linux"},
     {"version":"0.29.1","date":"2026-09-18","zh":"修复 Claude 对话入口丢失 · 长时间运行不再变卡","en":"Fix lost Claude chat entries · no slowdown after long runs"},
     {"version":"0.29.0","date":"2026-09-16","zh":"可信设备与可信地址保护","en":"Trusted device and address protection"},
     {"version":"0.28.0","date":"2026-09-11","zh":"Claude 对话更可靠 · 工具图片预览","en":"More reliable Claude chat · tool image previews"},
     {"version":"0.27.2","date":"2026-09-08","zh":"修复多标签页偶发鉴权弹窗","en":"Fix intermittent authentication prompts across tabs"},
-    {"version":"0.27.1","date":"2026-09-08","zh":"腾讯语音 · 终端光标修复 · Codex 对话恢复","en":"Tencent voice · terminal cursor fixes · Codex chat recovery"},
-    {"version":"0.27.0","date":"2026-09-05","zh":"腾讯语音输入 · 终端输入更准确","en":"Tencent voice input · more accurate terminal typing"}
+    {"version":"0.27.1","date":"2026-09-08","zh":"腾讯语音 · 终端光标修复 · Codex 对话恢复","en":"Tencent voice · terminal cursor fixes · Codex chat recovery"}
   ]
 }

package/dist/public/assets/channel-kkiOw5AC.js

@@ -1 +0,0 @@
-import{U as o,a as n}from"./mermaid.core-BmCR7le1.js";const t=(r,a)=>o.lang.round(n.parse(r)[a]);export{t as c};