@groundnuty/macf-channel-server 0.2.38 → 0.2.41

package/dist/shutdown.js

@@ -1,26 +1,95 @@
 /**
- * Registers SIGTERM and SIGINT handlers that clean up the agent's
- * registry variable and stop the HTTPS server.
+ * Registers SIGTERM, SIGINT, and MCP-stdin-close handlers that clean up
+ * the agent's registry variable and stop the HTTPS server.
+ *
+ * The channel-server runs as the Claude TUI's MCP stdio child. A normal TUI
+ * exit (`/exit`, or SIGTERM-to-the-TUI) does NOT deliver a SIGTERM/SIGINT to
+ * this process — it only sees its stdin reach EOF as the parent goes away.
+ * So the stdin `'end'`/`'close'` wiring (macf#627) is the graceful-deregister
+ * trigger on a normal TUI exit; the signal handlers cover direct kills; the
+ * DR-031 TTL heartbeat (#589) remains the backstop for hard kills (SIGKILL /
+ * OOM / power loss) where no handler runs at all.
  *
  * Returns a cleanup function that can also be called directly.
  */
 export function registerShutdownHandler(config) {
-    const { agentName, registry, httpsServer, logger } = config;
+    const { agentName, registry, instanceId, httpsServer, healthState, registryHeartbeat, logger } = config;
     let shuttingDown = false;
     let lastResult = true;
-    async function cleanup() {
+    async function cleanup(trigger) {
         if (shuttingDown)
             return lastResult;
         shuttingDown = true;
-        logger.info('shutdown_start', { agent: agentName });
+        logger.info('shutdown_start', {
+            agent: agentName,
+            ...(trigger !== undefined ? { trigger } : {}),
+        });
         let ok = true;
+        // Release the background OTLP-reachability probe interval (DR-030). Best-
+        // effort + never flips `ok`: a probe-cleanup hiccup must not mask a real
+        // deregister/stop failure.
+        try {
+            healthState?.dispose?.();
+        }
+        catch {
+            // ignore — the interval is unref()'d, so a missed clear can't pin exit
+        }
+        // Clear the registry-heartbeat interval (DR-031, groundnuty/macf#568). Same
+        // best-effort posture as the otel probe above — the interval is unref()'d, so
+        // a missed clear can't pin exit, and a hiccup must not mask a real failure.
+        try {
+            registryHeartbeat?.stop?.();
+        }
+        catch {
+            // ignore — unref()'d interval; a missed clear can't pin exit
+        }
+        // Instance-id-guarded deregister (DR-031, groundnuty/macf#553 root-cause):
+        // remove our registry slot ONLY if it is still ours. `deregisterConditional`
+        // is contracted never to throw — a registry hiccup surfaces as reason:'error'
+        // — but we still wrap it so a future contract slip can't crash shutdown.
         try {
-            await registry.remove(agentName);
-            logger.info('shutdown_deregistered', { agent: agentName });
+            const result = await registry.deregisterConditional(agentName, instanceId);
+            if (result.deregistered) {
+                logger.info('shutdown_deregistered', { agent: agentName, instance_id: instanceId });
+            }
+            else if (result.reason === 'not-ours') {
+                // A newer instance took over our slot (groundnuty/macf#424) while we ran.
+                // Leaving its registration intact is CORRECT — deleting it would re-
+                // introduce the missing/stale-entry bug (#553) for a live peer. Not a
+                // failure: keep `ok` true.
+                logger.info('shutdown_deregister_skipped', {
+                    agent: agentName,
+                    instance_id: instanceId,
+                    reason: result.reason,
+                    detail: 'registry slot held by a different instance — not ours to delete (DR-031, #424)',
+                });
+            }
+            else if (result.reason === 'absent') {
+                // Slot already gone (or unreadable) — nothing to deregister. Not a failure.
+                logger.info('shutdown_deregister_skipped', {
+                    agent: agentName,
+                    instance_id: instanceId,
+                    reason: result.reason,
+                    detail: 'registry slot already empty',
+                });
+            }
+            else {
+                // reason === 'error': a registry read/delete failed. Surface it loud and
+                // flip `ok` so external monitors (systemd, macf-actions heartbeat) see
+                // the degraded exit rather than absorbing a possibly-stale slot into a
+                // clean exit (#103 R2). Shutdown still proceeds — fail-open, not crash.
+                logger.error('shutdown_deregister_failed', {
+                    agent: agentName,
+                    instance_id: instanceId,
+                    reason: result.reason,
+                });
+                ok = false;
+            }
         }
         catch (err) {
             logger.error('shutdown_deregister_failed', {
                 agent: agentName,
+                instance_id: instanceId,
                 error: err instanceof Error ? err.message : String(err),
             });
             ok = false;
@@ -42,12 +111,27 @@ export function registerShutdownHandler(config) {
     }
     // Exit 1 when any cleanup step failed so external monitors (systemd,
     // macf-actions heartbeat) surface the degraded state instead of
-    // silently absorbing it into a clean exit (#103 R2).
-    const handler = () => {
-        cleanup().then(ok => process.exit(ok ? 0 : 1), () => process.exit(1));
+    // silently absorbing it into a clean exit (#103 R2). The `trigger` is
+    // recorded once (in `shutdown_start`) by whichever path wins the once-guard.
+    const handlerFor = (trigger) => () => {
+        cleanup(trigger).then(ok => process.exit(ok ? 0 : 1), () => process.exit(1));
     };
-    process.on('SIGTERM', handler);
-    process.on('SIGINT', handler);
+    process.on('SIGTERM', handlerFor('SIGTERM'));
+    process.on('SIGINT', handlerFor('SIGINT'));
+    // macf#627: a normal Claude-TUI exit does NOT signal this MCP-stdio child —
+    // it only sees stdin reach EOF ('end') / be destroyed ('close') as the parent
+    // departs. Wire the SAME deregister handler to both events so a graceful TUI
+    // exit deregisters rather than stranding the registry slot until the DR-031
+    // TTL backstop (#589). `cleanup()`'s once-guard (set synchronously before any
+    // await) makes a stdin-close racing a SIGTERM — or 'end' then 'close' — run
+    // the deregister exactly once. The child lingers ~8s after TUI exit
+    // (devops-observed), ample for the async deregister: the in-flight `cleanup()`
+    // promise plus the still-bound HTTPS server keep the event loop alive, and we
+    // exit only from `cleanup()`'s `.then()` — never mid-deregister.
+    const stdin = config.stdin ?? process.stdin;
+    const stdinCloseHandler = handlerFor('mcp-stdin-close');
+    stdin.on('end', stdinCloseHandler);
+    stdin.on('close', stdinCloseHandler);
     return cleanup;
 }
 //# sourceMappingURL=shutdown.js.map

package/dist/shutdown.js.map

@@ -1 +1 @@
-{"version":3,"file":"shutdown.js","sourceRoot":"","sources":["../src/shutdown.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAKvC;IACC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAC5D,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,IAAI,UAAU,GAAG,IAAI,CAAC;IAEtB,KAAK,UAAU,OAAO;QACpB,IAAI,YAAY;YAAE,OAAO,UAAU,CAAC;QACpC,YAAY,GAAG,IAAI,CAAC;QAEpB,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QACpD,IAAI,EAAE,GAAG,IAAI,CAAC;QAEd,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACjC,MAAM,CAAC,IAAI,CAAC,uBAAuB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QAC7D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,KAAK,CAAC,4BAA4B,EAAE;gBACzC,KAAK,EAAE,SAAS;gBAChB,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC,CAAC;YACH,EAAE,GAAG,KAAK,CAAC;QACb,CAAC;QAED,IAAI,CAAC;YACH,MAAM,WAAW,CAAC,IAAI,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,CAAC,KAAK,CAAC,6BAA6B,EAAE;gBAC1C,KAAK,EAAE,SAAS;gBAChB,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC,CAAC;YACH,EAAE,GAAG,KAAK,CAAC;QACb,CAAC;QAED,MAAM,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;QAC3D,UAAU,GAAG,EAAE,CAAC;QAChB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,qEAAqE;IACrE,gEAAgE;IAChE,qDAAqD;IACrD,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,OAAO,EAAE,CAAC,IAAI,CACZ,EAAE,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAC9B,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CACtB,CAAC;IACJ,CAAC,CAAC;IAEF,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAE9B,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"shutdown.js","sourceRoot":"","sources":["../src/shutdown.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundnuty/macf-channel-server",
-  "version": "0.2.38",
+  "version": "0.2.41",
   "description": "MCP channel server for the Multi-Agent Coordination Framework. HTTPS + mTLS endpoint agents connect to for inter-agent messaging (notify), CI-completion routing, and /sign certificate issuance. Invoked by Claude Code's plugin via `npx -y @groundnuty/macf-channel-server` per DR-022.",
   "type": "module",
   "main": "dist/index.js",
@@ -33,7 +33,7 @@
     "test:integration": "vitest run --config vitest.integration.config.ts"
   },
   "dependencies": {
-    "@groundnuty/macf-core": "0.2.38",
+    "@groundnuty/macf-core": "0.2.41",
     "@modelcontextprotocol/sdk": "~1.29.0",
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/core": "2.7.0",