instar 1.3.800 → 1.3.802

package/dist/server/routes.js

@@ -7,6 +7,7 @@
 import { Router } from 'express';
 import { execFileSync } from 'node:child_process';
 import { createHash, timingSafeEqual, randomUUID } from 'node:crypto';
+import { governor as selfActionGovernorSurface } from '../monitoring/selfaction/governor.js';
 import { classifyActionClaim } from '../core/action-claim.js';
 import { sharedG3SoakLedger, decideLeaseGatedSpawn } from '../core/leaseGatedSpawn.js';
 import { getHostSpawnSemaphore, configuredSpawnAcquireMs, configuredSpawnWaitersMax } from '../core/hostSpawnSemaphore.js';
@@ -6058,9 +6059,24 @@ export function createRoutes(ctx) {
     router.get('/sessions', async (req, res) => {
         const status = req.query.status;
         const validStatuses = ['starting', 'running', 'completed', 'failed', 'killed'];
-        const sessions = status && validStatuses.includes(status)
-            ? ctx.state.listSessions({ status: status })
+        // Session-listing hygiene (CMT-1936): the DEFAULT listing is ACTIVE
+        // sessions only (starting/running). Finished runs (completed/failed/
+        // killed) stay fully readable behind an explicit opt-in — `?include=all`
+        // for the whole registry, or `?status=<terminal>` for one class — so the
+        // ~50 retained finished mentor/job records never read as "50 running
+        // sessions" on the dashboard / pool / agent surfaces (the 2026-07-05
+        // "duplicate sessions" operator misread).
+        const explicitStatus = status && validStatuses.includes(status)
+            ? status
+            : undefined;
+        const includeAll = req.query.include === 'all';
+        const isActiveStatus = (s) => s === 'running' || s === 'starting';
+        let sessions = explicitStatus
+            ? ctx.state.listSessions({ status: explicitStatus })
             : ctx.state.listSessions();
+        if (!explicitStatus && !includeAll) {
+            sessions = sessions.filter((s) => isActiveStatus(s.status));
+        }
         // Which machine answered — so a session row can say where it runs. Absent
         // on single-machine installs (no pool wired), so the dashboard hides the badge.
         const selfMachineId = ctx.meshSelfId ?? null;
@@ -6138,9 +6154,14 @@ export function createRoutes(ctx) {
             // classifier so an idle peer reads "online — no active sessions" but a
             // dark peer reads "unreachable", never a fabricated state).
             const peerFetchReason = new Map();
+            // Forward the caller's visibility opt-in to each peer so the pool view
+            // keeps ONE semantic (active-only by default, everything on include=all,
+            // one class on ?status=). explicitStatus comes from the validated
+            // allowlist above, so it is URL-safe by construction.
+            const peerQuery = includeAll ? '?include=all' : explicitStatus ? `?status=${explicitStatus}` : '';
             await Promise.all(peers.map(async (p) => {
                 try {
-                    const r = await fetch(`${p.url}/sessions`, {
+                    const r = await fetch(`${p.url}/sessions${peerQuery}`, {
                         headers: { Authorization: `Bearer ${ctx.config.authToken}` },
                         signal: AbortSignal.timeout(5000),
                     });
@@ -6153,6 +6174,16 @@ export function createRoutes(ctx) {
                     peerFetchReason.set(p.machineId, null);
                     const nickname = ctx.machinePoolRegistry?.getCapacity(p.machineId)?.nickname ?? null;
                     for (const s of list) {
+                        // Defensive mirror of the default-visibility filter for OLDER
+                        // peers that still answer the plain route with their FULL registry
+                        // (the exact client-side filter dashboard/index.html carries for
+                        // the same reason — 2026-06-11: five closed Mac Mini sessions
+                        // reappeared as live tiles). Without this, one stale peer
+                        // re-introduces the finished-session wall into the pool view.
+                        if (!includeAll && !explicitStatus && !isActiveStatus(s.status))
+                            continue;
+                        if (explicitStatus && s.status !== explicitStatus)
+                            continue;
                         remote.push({
                             ...s,
                             machineId: s.machineId ?? p.machineId,
@@ -6218,6 +6249,55 @@ export function createRoutes(ctx) {
                 }
                 machines.push(entry);
             }
+            // GENUINE cross-machine duplicate detection (CMT-1936 part c): the SAME
+            // conversation (platform + platformId) with a LIVE session on two or
+            // more machines at once is the real incoherency. Each machine running
+            // its OWN copy of a recurring job is benign, BY DESIGN, and never flags
+            // here — job/headless sessions carry no platform binding (they enrich as
+            // platform:'headless', which is excluded), so identical `job-*` names on
+            // two machines stay unflagged. Only ACTIVE rows count: a finished record
+            // on one machine + a live session on another is the normal topic-move
+            // case, not a duplicate.
+            const byConversation = new Map();
+            for (const s of allSessionsMerged) {
+                if (!isActiveStatus(s.status))
+                    continue;
+                const platform = typeof s.platform === 'string' ? s.platform : '';
+                const platformId = s.platformId;
+                if (!platform || platform === 'headless' || platformId == null)
+                    continue;
+                const key = `${platform}:${String(platformId)}`;
+                const mid = typeof s.machineId === 'string' ? s.machineId : (selfMachineId ?? '__local__');
+                const entry = byConversation.get(key)
+                    ?? { platform, platformId: platformId, machineIds: new Set(), sessions: [] };
+                entry.machineIds.add(mid);
+                entry.sessions.push(String(s.name ?? s.tmuxSession ?? s.id ?? ''));
+                byConversation.set(key, entry);
+            }
+            const duplicateTopics = [];
+            const duplicateKeys = new Set();
+            for (const [key, e] of byConversation) {
+                if (e.machineIds.size >= 2) {
+                    duplicateKeys.add(key);
+                    duplicateTopics.push({
+                        platform: e.platform,
+                        platformId: e.platformId,
+                        machineIds: [...e.machineIds],
+                        sessions: e.sessions,
+                    });
+                }
+            }
+            if (duplicateKeys.size > 0) {
+                for (const s of allSessionsMerged) {
+                    if (!isActiveStatus(s.status))
+                        continue;
+                    const platform = typeof s.platform === 'string' ? s.platform : '';
+                    if (!platform || s.platformId == null)
+                        continue;
+                    if (duplicateKeys.has(`${platform}:${String(s.platformId)}`))
+                        s.duplicateTopic = true;
+                }
+            }
             res.json({
                 sessions: allSessionsMerged,
                 pool: {
@@ -6232,6 +6312,9 @@ export function createRoutes(ctx) {
                     // multi-machine case the dashboard renders; single-machine installs
                     // still get the (lone) self row, harmlessly.
                     machines,
+                    // Always an array (usually empty) — additive, never breaking. Each
+                    // entry is one conversation with a live session on >=2 machines.
+                    duplicateTopics,
                 },
             });
             return;
@@ -6818,6 +6901,25 @@ export function createRoutes(ctx) {
             }, 500 + i * STAGGER_MS);
         });
     });
+    /** FD13 (unified-self-action-backpressure §4): verify the optional
+     *  `x-instar-principal-pin` proof and — when it is the operator's dashboard
+     *  PIN — record the principal admission on the ALWAYS-ALLOW audited lane.
+     *  Never blocks; never throws (a throwing principalAdmit resolves OPEN). */
+    const recordPrincipalKillProvenance = (req, target) => {
+        try {
+            const proof = req.headers['x-instar-principal-pin'];
+            if (typeof proof !== 'string' || !ctx.config.dashboardPin)
+                return;
+            const ha = createHash('sha256').update(proof).digest();
+            const hb = createHash('sha256').update(ctx.config.dashboardPin).digest();
+            if (ha.length === hb.length && timingSafeEqual(ha, hb)) {
+                selfActionGovernorSurface.principalAdmit('dashboard-pin-session', { actionVerb: 'session-kill', target });
+            }
+        }
+        catch {
+            /* provenance recording is observability — never blocks the kill */
+        }
+    };
     router.delete('/sessions/:id', async (req, res) => {
         if (!SESSION_NAME_RE.test(req.params.id)) {
             res.status(400).json({ error: 'Invalid session ID format' });
@@ -6846,6 +6948,14 @@ export function createRoutes(ctx) {
             // those read the route-stamped `origin` below. Sanitized + bounded.
             const viaHeader = req.headers['x-instar-close-via'];
             const via = typeof viaHeader === 'string' && /^[a-z0-9-]{1,40}$/.test(viaHeader) ? viaHeader : undefined;
+            // FD13 principal provenance (unified-self-action-backpressure §4): a
+            // PIN-proof header distinguishes the OPERATOR's dashboard session from a
+            // bare Bearer call (the agent itself holds Bearer, so Bearer alone is
+            // structurally insufficient — Know Your Principal). A valid proof rides
+            // the ALWAYS-ALLOW, always-audited principal lane; absent/invalid stays
+            // agent-origin ('self') and rides the normal governor ceilings once the
+            // kill sink enforces.
+            recordPrincipalKillProvenance(req, req.params.id);
             const result = await ctx.sessionManager.terminateSession(target.id, 'operator-kill', {
                 origin: 'operator',
                 finalStatus: 'killed',
@@ -6901,6 +7011,9 @@ export function createRoutes(ctx) {
             res.status(502).json({ error: 'url-rejected', machineId });
             return;
         }
+        // FD13 principal provenance (same PIN-proof distinguishability as the
+        // local DELETE route — a bare Bearer relay stays agent-origin 'self').
+        recordPrincipalKillProvenance(req, sessionUuid);
         try {
             // The peer's PLAIN local close — no relay params forwarded (single-hop
             // by construction, §2.1); UUID-targeted (the peer's existing route is
@@ -7598,6 +7711,97 @@ export function createRoutes(ctx) {
         }
         return out;
     };
+    // ── SelfActionGovernor (unified-self-action-backpressure Increment B) ──
+    // LOCK-FREE + WRITE-FREE pure read of the in-memory aggregates (the
+    // /test-runner-limiter PURE-read precedent — never /spawn-limiter's
+    // lock-taking status()). Projection is SCRUBBED: aggregate per-class counts
+    // + verdict/breaker state ONLY — no target identities (account ids,
+    // session/topic names) and no absolute quota values (spec SEC6).
+    // `?scope=pool` merges pool-shared class counters from online peers
+    // (dark-peer-tolerant: a failed peer is a named row, never a 500).
+    const selfActionPoolLimiter = rateLimiter(60_000, 6);
+    router.get('/self-action-governor', (req, res) => {
+        const gov = ctx.selfActionGovernor;
+        if (!gov) {
+            res.status(503).json({ error: 'self-action governor unavailable (not initialized on this build)' });
+            return;
+        }
+        let posture;
+        try {
+            posture = gov.getPosture();
+        }
+        catch (err) {
+            res.status(500).json({ error: `self-action governor read failed: ${err instanceof Error ? err.message : String(err)}` });
+            return;
+        }
+        const selfMachineId = ctx.meshSelfId ?? null;
+        const body = {
+            machineId: selfMachineId,
+            generatedAt: new Date().toISOString(),
+            emergencyDisable: posture.emergencyDisable,
+            initialized: posture.initialized,
+            classes: posture.classes,
+        };
+        if (req.query.scope !== 'pool') {
+            res.json(body);
+            return;
+        }
+        // Pool scope: pool-shared class counters are answerable POOL-WIDE (the
+        // observability boundary matches the resource boundary); hardware-bound
+        // counters stay machine-local. Non-recursive (peers get the plain route),
+        // rate-limited (anti-amplification).
+        selfActionPoolLimiter(req, res, async () => {
+            const known = (ctx.listPoolMachines?.() ?? []).filter((m) => m.machineId !== selfMachineId);
+            const machines = [];
+            const failed = [];
+            let peersQueried = 0;
+            await Promise.all(known.map(async (m) => {
+                const capacity = ctx.machinePoolRegistry?.getCapacity(m.machineId) ?? null;
+                if (!m.lastKnownUrl) {
+                    failed.push({ machineId: m.machineId, reason: 'no-known-url' });
+                    return;
+                }
+                if (capacity && capacity.online === false) {
+                    failed.push({ machineId: m.machineId, reason: 'offline' });
+                    return;
+                }
+                const extraAllowlist = ctx.config.multiMachine?.peerUrlAllowlist;
+                const verdict = isPeerUrlAllowedForCredentials(m.lastKnownUrl, extraAllowlist);
+                if (!verdict.ok) {
+                    failed.push({ machineId: m.machineId, reason: 'url-rejected' });
+                    return;
+                }
+                peersQueried++;
+                try {
+                    const r = await fetch(`${m.lastKnownUrl}/self-action-governor`, {
+                        headers: { Authorization: `Bearer ${ctx.config.authToken}` },
+                        signal: AbortSignal.timeout(5000),
+                    });
+                    if (r.status === 404) {
+                        failed.push({ machineId: m.machineId, reason: 'route-missing' });
+                        return;
+                    }
+                    if (!r.ok) {
+                        failed.push({ machineId: m.machineId, reason: r.status === 401 || r.status === 403 ? 'unauthorized' : 'error' });
+                        return;
+                    }
+                    const peerBody = (await r.json());
+                    machines.push({
+                        machineId: m.machineId,
+                        nickname: capacity?.nickname ?? m.nickname,
+                        emergencyDisable: peerBody.emergencyDisable ?? null,
+                        // Pool-shared classes ONLY (the resource boundary IS the
+                        // observability boundary — hardware-bound stays machine-local).
+                        classes: (peerBody.classes ?? []).filter((c) => c.resource === 'pool-shared'),
+                    });
+                }
+                catch {
+                    failed.push({ machineId: m.machineId, reason: 'unreachable' });
+                }
+            }));
+            res.json({ ...body, scope: 'pool', pool: { selfMachineId, peersQueried, peersOk: machines.length, machines, failed } });
+        });
+    });
     router.get('/test-runner-limiter', (_req, res) => {
         try {
             const status = getHostTestRunnerSemaphore().status();
@@ -20667,6 +20871,41 @@ document.getElementById('mcpForm').addEventListener('submit', async function (e)
         // Single source of truth (module-scope export) so the enableAction-validity
         // test stays in lock-step with what the API actually accepts.
         const allowedKeys = PATCHABLE_CONFIG_KEYS;
+        // ── NESTED-PATH validator for the SelfActionGovernor subtree
+        // (unified-self-action-backpressure INT9-1): top-level `intelligence` is
+        // deliberately NOT allowlisted (that would Bearer-expose spawnCap etc.);
+        // EXACTLY `intelligence.selfActionGovernor` is patchable, with DEEP merge
+        // for this subtree (the generic one-level-deep merge would clobber
+        // sibling per-class overrides — the full-block hazard). The DISABLE
+        // direction (`emergencyDisable: true`) on this API path is
+        // dashboard-PIN-gated (ADV9-4 — two verifier-independent valves remain:
+        // the conversational config edit and the raw file edit, so this costs no
+        // emergency availability); re-enable is Bearer-OK.
+        let sagPatch = null;
+        if ('intelligence' in patch) {
+            const intel = patch.intelligence;
+            const intelKeys = intel && typeof intel === 'object' && !Array.isArray(intel) ? Object.keys(intel) : null;
+            if (!intelKeys || intelKeys.some((k) => k !== 'selfActionGovernor')) {
+                res.status(400).json({
+                    error: 'Only intelligence.selfActionGovernor is patchable under `intelligence` via API (nested-path validator; other intelligence.* keys are not Bearer-exposed)',
+                });
+                return;
+            }
+            const sag = intel.selfActionGovernor;
+            if (!sag || typeof sag !== 'object' || Array.isArray(sag)) {
+                res.status(400).json({ error: 'intelligence.selfActionGovernor must be an object' });
+                return;
+            }
+            if (sag.emergencyDisable === true) {
+                // Know Your Principal: disarming the flood brake over the API needs
+                // the operator's PIN — a Bearer token is structurally insufficient.
+                if (!checkMandatePin(req, res))
+                    return; // response already sent
+            }
+            sagPatch = sag;
+            delete patch.intelligence;
+            delete patch.pin; // PIN is auth, never config
+        }
         const disallowed = Object.keys(patch).filter(k => !allowedKeys.has(k));
         if (disallowed.length > 0) {
             res.status(400).json({
@@ -20681,6 +20920,35 @@ document.getElementById('mcpForm').addEventListener('submit', async function (e)
             if (fs.existsSync(configPath)) {
                 fileConfig = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
             }
+            // Deep merge for the validated selfActionGovernor subtree (multi-level
+            // by design — INT9-1's one-level-deep-merge hazard note).
+            if (sagPatch) {
+                const deepMerge = (base, overlay) => {
+                    for (const [k, v] of Object.entries(overlay)) {
+                        if (v && typeof v === 'object' && !Array.isArray(v) && base[k] && typeof base[k] === 'object' && !Array.isArray(base[k])) {
+                            deepMerge(base[k], v);
+                        }
+                        else {
+                            base[k] = v;
+                        }
+                    }
+                    return base;
+                };
+                fileConfig.intelligence = fileConfig.intelligence && typeof fileConfig.intelligence === 'object' ? fileConfig.intelligence : {};
+                fileConfig.intelligence.selfActionGovernor = deepMerge(fileConfig.intelligence.selfActionGovernor && typeof fileConfig.intelligence.selfActionGovernor === 'object'
+                    ? fileConfig.intelligence.selfActionGovernor
+                    : {}, sagPatch);
+                const rt = ctx.config;
+                rt.intelligence = rt.intelligence && typeof rt.intelligence === 'object' ? rt.intelligence : {};
+                rt.intelligence.selfActionGovernor = deepMerge(rt.intelligence.selfActionGovernor && typeof rt.intelligence.selfActionGovernor === 'object'
+                    ? rt.intelligence.selfActionGovernor
+                    : {}, sagPatch);
+                if (Object.keys(patch).length === 0) {
+                    fs.writeFileSync(configPath, JSON.stringify(fileConfig, null, 2) + '\n');
+                    res.json({ success: true, patched: ['intelligence.selfActionGovernor'], note: 'emergencyDisable is read live by the governor; per-class overrides apply on its next slow tick.' });
+                    return;
+                }
+            }
             // Deep merge (one level deep — sufficient for feature toggles)
             for (const [key, value] of Object.entries(patch)) {
                 if (typeof value === 'object' && value !== null && !Array.isArray(value) &&