@tyhld/conductor 0.6.0 → 0.8.0

package/dist/relay.js

@@ -57,7 +57,30 @@ function envPositiveNumber(name, def) {
     return Number.isFinite(parsed) && parsed > 0 ? parsed : def;
 }
 /**
- * 生存の見張り(keepalive)を打ち切るまでの上限(ms)。既定30分＝中央のタイムアウトと同じ長さ。
+ * ★中央（devlog-tracker）が「手が挙がっていても必ず現場を解放する」上限(ms)。
+ *
+ * 【この数字の持ち主は中央】便1 PR#250 で中央がこう決めた:
+ *   「busy の印が新しい間は30分の時間切れをしない。ただし着信から3時間で必ず解放する
+ *     （手を挙げ直しても伸びない）」。
+ *   ＝relay がどれだけ手を挙げ続けても、3時間を過ぎれば現場は解放される。
+ *
+ * 【★片方だけ動かさないこと】中央がこの値を変えたら、ここも合わせる。
+ *   合っていないと次のどちらかになる:
+ *     ・ここが短い … 中央はまだ守ってくれるのに職人が先に手を下ろす＝割り込まれる
+ *                    （2026-09-04 に実際に起きた。中央3時間・relay 30分だった）
+ *     ・ここが長い … 中央は既に解放しているのに職人だけ手を挙げ続ける＝意味がない
+ *   ★長い側は下の clampToCentralHold が構造的に潰す（設定を間違えても中央を超えない）。
+ */
+export const CENTRAL_BUSY_HOLD_MAX_MS = 3 * 60 * 60 * 1000; // 3時間（中央 PR#250 と同じ値）
+/**
+ * 見張りの上限を中央の上限に収める。★中央より長い値は意味がないので切り詰める。
+ *   環境変数で誤って長く設定しても、中央を超えないことをここで保証する。
+ */
+export function clampToCentralHold(ms) {
+    return Math.min(ms, CENTRAL_BUSY_HOLD_MAX_MS);
+}
+/**
+ * 生存の見張り(keepalive)を打ち切るまでの上限(ms)。★既定は中央と同じ3時間。
  *
  * 【なぜ pending とは別の寿命が要るのか（調査 176aebcf・案①-a）】
  *   上の RELAY_PENDING_TIMEOUT_MS は「配達の追跡」を諦める時計で、固着して次の指示を拾えなく
@@ -70,11 +93,23 @@ function envPositiveNumber(name, def) {
  *   そこで「配達の追跡(pending)」と「生存の見張り(keepalive)」の寿命を分ける。pending は従来
  *   どおり15分で解除して次の指示を拾えるようにし、生存通知だけをこの時計で続ける。
  *
- * 【なぜ30分か】中央が sent/stalled を timeout（＝諦めて現場を解放）に落とすのと同じ長さ。
- *   これより長く見張っても、中央は既に別の指示を配れる状態になっており意味がない。
- *   環境変数 RELAY_KEEPALIVE_MAX_MS で上書き可（正の数のみ）。
+ * 【なぜ30分→3時間へ広げたか（えふさん決定 2026-09-04）】
+ *   便2で「作業中です」と手を挙げる仕掛けを入れたが、この上限が30分のままだと
+ *   30分で手が下りて、また割り込まれる。実測 2026-09-04: 15分の pending 解除が18件＝
+ *   30分を超える便が常態で、割り込まれた便は着信から35分だった。
+ *   ★中央だけ3時間に伸びていて、職人側が30分で足を引っ張っている状態だったので合わせる。
+ *
+ * 【★引き受けたリスク（えふさん判断）】職人が固まった場合、その現場は最大3時間ふさがる。
+ *   だから「時間で下ろす」以外の下ろし方が生命線になる。次の4つは時間を待たずに効く:
+ *     ① 画面の DONE を検出した        （decideKeepalive の 'done'）
+ *     ② 中央で終端になった            （'probe' → isCentralFinished）
+ *     ③ 職人が静止した                （'probe' → 手を下ろす。終端でなくても下ろす）
+ *     ④ relayTick 入口の砦            （pending でも keepalive でもなくなったら必ず下ろす）
+ *   ★この4つはテスト（test/relay-busy-hold.test.ts）で固定してある。外すと落ちる。
+ *
+ *   環境変数 RELAY_KEEPALIVE_MAX_MS で上書き可（正の数のみ・★中央の上限までに切り詰める）。
  */
-export const RELAY_KEEPALIVE_MAX_MS = envPositiveNumber('RELAY_KEEPALIVE_MAX_MS', 30 * 60 * 1000);
+export const RELAY_KEEPALIVE_MAX_MS = clampToCentralHold(envPositiveNumber('RELAY_KEEPALIVE_MAX_MS', CENTRAL_BUSY_HOLD_MAX_MS));
 /**
  * 自動再送(2-a)のポリシー。生存中の職人が動かないときに同一指示を再送する。
  *   - RELAY_RESEND_DELAY_MS: 初回送信(sentAt)から最初の再送までの待機(ms)。既定30秒。
@@ -183,6 +218,7 @@ export function createRelayState() {
         deliverCounts: new Map(),
         abandoned: new Set(),
         promptPending: false,
+        busyRaisedId: null,
     };
 }
 /**
@@ -1391,9 +1427,18 @@ export function decideHeartbeat(alive, throttleOk) {
  *   （＝/seen の perm 系）。画面から質問を読む処理ごと撤去したため、送るのは body 無しの生存通知だけ。
  *   確認そのものは PermissionRequest フックが別の口（hook-requests）でデータとして届ける。
  */
-export async function sendHeartbeat(cfg, id) {
+export async function sendHeartbeat(cfg, id, busy = false) {
     try {
-        const res = await fetch(`${cfg.url}/api/conductor/commands/${encodeURIComponent(id)}/seen`, { method: 'PATCH', headers: authHeaders(cfg) });
+        // ★busy が【真偽値の true】のときだけ body を載せる。それ以外は今までと1バイトも変えない
+        //   （body 無しの PATCH）。中央も "true" や 1 のような真偽値でない値は無視する仕様。
+        const init = busy === true
+            ? {
+                method: 'PATCH',
+                headers: { ...authHeaders(cfg), 'Content-Type': 'application/json' },
+                body: JSON.stringify({ busy: true }),
+            }
+            : { method: 'PATCH', headers: authHeaders(cfg) };
+        const res = await fetch(`${cfg.url}/api/conductor/commands/${encodeURIComponent(id)}/seen`, init);
         if (!res.ok) {
             log(`site=${cfg.site} id=${id} heartbeat -> HTTP ${res.status} NG（次回再試行・縮退で安全）`);
         }
@@ -1402,6 +1447,45 @@ export async function sendHeartbeat(cfg, id) {
         log(`site=${cfg.site} id=${id} heartbeat -> 失敗: ${err instanceof Error ? err.message : String(err)}（縮退で安全）`);
     }
 }
+/**
+ * いま「作業中です」と手を挙げる（busy:true を載せる）かを決める純粋関数。
+ *
+ * 【★手を挙げるのは「手を動かしている」印があるときだけ】
+ *   使うのは busy シグナル（入力枠フッターの `esc to interrupt` / スピナー＝hasBusySignal）。
+ *   これは「職人がいま処理を回している」ことを画面から直に読める、いちばん確かな印である。
+ *
+ * 【★選択メニュー中は挙げない】
+ *   メニューは【人の答え待ち】で、職人の手は止まっている。ここで手を挙げ続けると、
+ *   誰も答えないまま現場が長時間ふさがる。生存通知（lastSeenAt）は従来どおりメニュー中も
+ *   送るので、「落ちた職人」と誤認されることはない＝退行しない。
+ *
+ * 【★迷ったら挙げない】
+ *   busy とメニューが同時に見えるような読み取りは、どちらとも言い切れない。挙げなければ
+ *   従来どおり（中央は30分で解放）＝いまと同じ動きに戻るだけなので、そちらへ倒す。
+ */
+export function shouldRaiseBusy(busySignal, menuOpen) {
+    if (menuOpen)
+        return false;
+    return busySignal === true;
+}
+/**
+ * 手を挙げた／下ろしたの【変わり目だけ】をログに出す。状態は state.busyRaisedId が持つ。
+ *   ★毎回のハートビートで出すと現場のログが埋まるので、変わったときだけ1行。
+ *   ★秘密は出さない（現場名と指示idだけ）。
+ */
+export function noteBusyEdge(state, site, id, raise, logLine) {
+    if (raise) {
+        if (state.busyRaisedId !== id) {
+            state.busyRaisedId = id;
+            logLine(`site=${site} id=${id} 作業中の手を挙げました（中央の時間切れを保留させます）`);
+        }
+        return;
+    }
+    if (state.busyRaisedId === id) {
+        state.busyRaisedId = null;
+        logLine(`site=${site} id=${id} 作業中の手を下ろしました（中央は従来どおり時間で解放します）`);
+    }
+}
 // ───────────────────────────────────────────────────────────────────────────
 // 生存の見張り（keepalive）— 配達の追跡(pending)とは別の寿命で回す（調査 176aebcf・案①-a）
 //
@@ -1468,7 +1552,7 @@ export function decideKeepalive(input) {
 }
 const DEFAULT_KEEPALIVE_DEPS = {
     capture: (site) => tmuxCapture(site),
-    heartbeat: (cfg, id) => sendHeartbeat(cfg, id),
+    heartbeat: (cfg, id, busy) => sendHeartbeat(cfg, id, busy === true),
     complete: (cfg, id, report) => patchStatus(cfg, id, 'done', report),
     centralStatus: (cfg, id) => fetchCommandStatus(cfg, id),
     now: () => Date.now(),
@@ -1503,11 +1587,15 @@ export async function keepaliveTick(cfg, state, deps = {}) {
     // ★見張りに入っている＝その指示は必ず着信済み（startKeepalive が delivered を要求する）。
     //   よってアンカーが流れて消えていても、画面全体を見てよい（ADR-020）。
     const below = cap === null ? null : sliceForDoneScan(cap, ka.anchor, true);
+    // ★「作業中です」の印は busy シグナルだけで決める（メニュー中は挙げない・shouldRaiseBusy）。
+    //   生存通知の可否(alive)は従来どおり busy ∪ メニュー＝1文字も変えない。
+    const kaBusySignal = cap !== null && hasBusySignalFor(cap, kindOf(cfg));
+    const kaMenu = cap !== null && hasChoiceMenuFor(cap, kindOf(cfg));
     const action = decideKeepalive({
         expired,
         capOk: cap !== null,
         doneSeen: ka.screenDoneUsable && below !== null && hasStandaloneDone(below, ka.site),
-        alive: cap !== null && (hasBusySignalFor(cap, kindOf(cfg)) || hasChoiceMenuFor(cap, kindOf(cfg))),
+        alive: cap !== null && (kaBusySignal || kaMenu),
         idle: cap !== null && looksIdleFor(cap, kindOf(cfg)),
         throttleOk: ka.lastHeartbeatAt === null || now - ka.lastHeartbeatAt >= RELAY_HEARTBEAT_INTERVAL_MS,
     });
@@ -1515,10 +1603,12 @@ export async function keepaliveTick(cfg, state, deps = {}) {
         return;
     if (action === 'heartbeat') {
         ka.lastHeartbeatAt = now;
+        const raise = shouldRaiseBusy(kaBusySignal, kaMenu);
+        noteBusyEdge(state, cfg.site, ka.id, raise, logLine);
         // ★継続のログ。出るのは最大でも RELAY_HEARTBEAT_INTERVAL_MS に1回（スロットルに相乗り）。
         logLine(`site=${cfg.site} id=${ka.id} 見張り継続: 職人は生きています→生存通知` +
             `（配達の追跡は解除済み・経過${Math.round((now - ka.startedAt) / 1000)}s）`);
-        await heartbeat(cfg, ka.id);
+        await heartbeat(cfg, ka.id, raise);
         return;
     }
     if (action === 'done') {
@@ -1527,6 +1617,8 @@ export async function keepaliveTick(cfg, state, deps = {}) {
         if (await complete(cfg, ka.id, report)) {
             logLine(`site=${cfg.site} id=${ka.id} 見張り終了: 画面のDONEを検出し完了を報告` +
                 `${report != null ? '（報告添付）' : ''}`);
+            // ★終わったら必ず手を下ろす（挙げっぱなしにすると現場が長くふさがる）。
+            noteBusyEdge(state, cfg.site, ka.id, false, logLine);
             state.keepalive = null;
         }
         // 報告に失敗したら畳まない（次tickで再試行。上限が最終的に打ち切る）。
@@ -1538,13 +1630,20 @@ export async function keepaliveTick(cfg, state, deps = {}) {
         // ★上限は無条件で畳む（無限に送り続けない）。中央の言い分はログに残すだけ。
         logLine(`site=${cfg.site} id=${ka.id} 見張り終了: 上限${Math.round(RELAY_KEEPALIVE_MAX_MS / 60000)}分に到達` +
             `（中央status=${centralStatus ?? '不明'}）`);
+        noteBusyEdge(state, cfg.site, ka.id, false, logLine);
         state.keepalive = null;
         return;
     }
     if (isCentralFinished(centralStatus)) {
         logLine(`site=${cfg.site} id=${ka.id} 見張り終了: 中央で終端(status=${centralStatus})を確認`);
+        noteBusyEdge(state, cfg.site, ka.id, false, logLine);
         state.keepalive = null;
     }
+    // ★'probe' で終端でなかった場合（職人が静止しているだけ）は生存通知を送らない＝
+    //   手も挙げない。ここで挙げっぱなしにすると「止まっている職人」で現場をふさぐ。
+    if (action === 'probe') {
+        noteBusyEdge(state, cfg.site, ka.id, false, logLine);
+    }
     // 終端でない（まだ生きている／中央不達）なら畳まない。職人が静止しているだけなので、
     // 生存通知は送らずに見張りだけ続ける＝中央は従来どおり stalled へ落とせる（誤魔化さない）。
 }
@@ -1651,6 +1750,15 @@ export async function relayTick(cfg, state) {
             state.restored = true;
             await restoreOrphans(cfg, state);
         }
+        // ── 手を挙げっぱなしを防ぐ最後の砦（★割り込みの根治・便2／3） ──
+        // 「作業中です」と手を挙げた指示が、もう追跡対象（pending でも keepalive でもない）で
+        // なくなっていたら、必ず下ろす。完了・中央での終端・放棄・再起動のどの道で抜けても、
+        // ここを通れば下りる＝★挙げっぱなしで現場が長時間ふさがることが構造的に起きない。
+        if (state.busyRaisedId !== null &&
+            state.pending?.id !== state.busyRaisedId &&
+            state.keepalive?.id !== state.busyRaisedId) {
+            noteBusyEdge(state, cfg.site, state.busyRaisedId, false, log);
+        }
         // ── 生存の見張り（keepalive・pending とは別の寿命） ──
         // pending の上限で「配達の追跡」を畳んだ指示について、職人が生きて見える限り中央へ
         // 生存通知を送り続ける（調査 176aebcf・案①-a）。★ここでは return しない＝この下の
@@ -1767,7 +1875,10 @@ export async function relayTick(cfg, state) {
             const nowMs = Date.now();
             const throttleOk = state.lastHeartbeatAt === null ||
                 nowMs - state.lastHeartbeatAt >= RELAY_HEARTBEAT_INTERVAL_MS;
-            const decision = decideHeartbeat(hasBusySignalFor(cap, kindOf(cfg)) || menu, throttleOk);
+            // ★「作業中です」の印は busy シグナルだけで決める（メニュー中は挙げない・shouldRaiseBusy）。
+            //   生存通知の可否は従来どおり busy ∪ メニュー＝1文字も変えない。
+            const busySignal = hasBusySignalFor(cap, kindOf(cfg));
+            const decision = decideHeartbeat(busySignal || menu, throttleOk);
             if (decision === 'bare') {
                 state.lastHeartbeatAt = nowMs;
                 // ★通らなかった理由を1行残す（PR#88 と同じ作法）: 撤去によって「黙って止まる」を作らない。
@@ -1780,7 +1891,9 @@ export async function relayTick(cfg, state) {
                         '（relayは答えない。PermissionRequestフックが管制へ渡しているか、' +
                         'フック未配線なら職人の端末で直接answerが必要）');
                 }
-                await sendHeartbeat(cfg, state.pending.id);
+                const raise = shouldRaiseBusy(busySignal, menu);
+                noteBusyEdge(state, cfg.site, state.pending.id, raise, log);
+                await sendHeartbeat(cfg, state.pending.id, raise);
             }
             // ── 生存中の自動再送(2-a)。DONE 未達のとき、未着信＋アイドルなら同一指示を再送する ──
             // 冪等性最優先: 着信判定(anchor可視)は cap から即わかる。アイドルの二重チェック

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyhld/conductor",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "采配くん管制の見守りアプリ（conductor-agent）。各PCで常駐し、中央(devlog-tracker)へ定期的に生存報告(heartbeat)を送る常駐CLI。",
   "type": "module",
   "bin": {