instar 1.3.313 → 1.3.314

package/dashboard/index.html

@@ -808,11 +808,16 @@
     .mnd-btn-danger { color: #f85149; }
     .mnd-dead-note { font-size: 13px; color: var(--text-dim); font-style: italic; }
     .mnd-notice { min-height: 20px; font-size: 14px; color: #3fb950; }
-    .mnd-notice-err { color: #f85149; }
-    .mnd-issue-form { display: flex; flex-direction: column; gap: 10px; max-width: 640px; padding: 12px 0; }
-    .mnd-issue-form label { display: flex; flex-direction: column; gap: 4px; font-size: 13px; color: var(--text-dim); }
-    .mnd-issue-form input, .mnd-issue-form textarea { font: inherit; padding: 6px 8px; }
-    .mnd-issue-form textarea { font-family: ui-monospace, monospace; font-size: 12px; }
+    .mnd-issue-form { display: flex; flex-direction: column; gap: 14px; max-width: 640px; padding: 12px 0; }
+    .mnd-issue-form label { display: flex; flex-direction: column; gap: 4px; font-size: 15px; color: var(--text-bright); }
+    .mnd-issue-form input, .mnd-issue-form textarea { font: inherit; padding: 8px 10px; border-radius: 6px; }
+    .mnd-issue-form textarea { font-family: ui-monospace, monospace; font-size: 13px; }
+    .mnd-hint { font-size: 13px; color: var(--text-dim); font-weight: 400; line-height: 1.45; }
+    .mnd-prefilled { font-size: 12px; color: var(--ph-accent, #4ade80); }
+    /* Issue-form feedback: PERSISTENT, not a transient toast. A failed issuance
+       the operator never sees (the 2026-06-05 incident) is worse than no form. */
+    .mnd-notice-err { border: 1px solid #b91c1c; background: rgba(185, 28, 28, 0.12); color: #fca5a5; padding: 12px 14px; border-radius: 8px; font-size: 15px; line-height: 1.5; white-space: pre-line; }
+    .mnd-notice-ok { border: 1px solid #15803d; background: rgba(21, 128, 61, 0.12); color: #86efac; padding: 12px 14px; border-radius: 8px; font-size: 17px; font-weight: 600; line-height: 1.5; }
     .mnd-table { width: 100%; border-collapse: collapse; font-size: 13px; }
     .mnd-table th, .mnd-table td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--border); vertical-align: top; }
     .mnd-reason-cell { color: var(--text-dim); max-width: 420px; }
@@ -826,7 +831,13 @@
        maturation "you're here" marker. */
     .ph-root {
       --ph-accent: #4ade80;
+      /* These panels are declared after </main>, making them direct .app grid
+         children. switchTab() hides the sidebar too, so without explicit
+         placement the lone visible panel auto-places into the 280px sidebar
+         COLUMN — the "squashed to the side" bug. Span the full grid. */
+      grid-column: 1 / -1;
       max-width: 760px;
+      width: 100%;
       font-size: 18px;
       line-height: 1.55;
       color: var(--text-bright);
@@ -3242,15 +3253,34 @@
         <h3 class="ph-h">Issued mandates</h3>
         <div id="mndList"></div>
       </section>
-      <details class="ph-detail">
+      <details class="ph-detail" id="mndIssueDetails">
         <summary class="ph-detail-summary">Issue a new mandate (PIN required)</summary>
         <div class="mnd-issue-form">
-          <label>Scope <input type="text" id="mndIssueScope" value="feedback-migration" /></label>
-          <label>Agent A fingerprint <input type="text" id="mndIssueAgentA" placeholder="full routing fingerprint" /></label>
-          <label>Agent B fingerprint <input type="text" id="mndIssueAgentB" placeholder="full routing fingerprint" /></label>
-          <label>Authorities (JSON) <textarea id="mndIssueAuthorities" rows="9" spellcheck="false"></textarea></label>
-          <label>Expires <input type="datetime-local" id="mndIssueExpires" /></label>
-          <label>Your dashboard PIN <input type="password" id="mndIssuePin" autocomplete="off" placeholder="typed at issuance, never stored" /></label>
+          <label>What is this permission slip for?
+            <span class="mnd-hint">A short name for the project the two agents may work on together, e.g. feedback-migration.</span>
+            <input type="text" id="mndIssueScope" value="feedback-migration" />
+          </label>
+          <label>This agent (Agent A)
+            <span class="mnd-hint">Pre-filled with this agent's own routing fingerprint — you normally don't need to touch it.</span>
+            <input type="text" id="mndIssueAgentA" placeholder="filling in automatically…" />
+            <span class="mnd-prefilled" id="mndAgentAPrefillNote"></span>
+          </label>
+          <label>The other agent (Agent B)
+            <span class="mnd-hint">The peer agent's routing fingerprint — find it on that agent's Threadline tab, or ask the agent "what's your routing fingerprint?".</span>
+            <input type="text" id="mndIssueAgentB" placeholder="e.g. 8c7928aa9f04fbda947172a2f9b2d81a" />
+          </label>
+          <label>What exactly may they do? (the authorities)
+            <span class="mnd-hint">Each entry is one delegated action with its bounds. The template below covers the standard credential-handoff + code-review pair — edit only if you know you need different bounds.</span>
+            <textarea id="mndIssueAuthorities" rows="9" spellcheck="false"></textarea>
+          </label>
+          <label>When does it expire?
+            <span class="mnd-hint">Pre-filled to one week from now. Every mandate expires; expired means denied.</span>
+            <input type="datetime-local" id="mndIssueExpires" />
+          </label>
+          <label>Your dashboard PIN
+            <span class="mnd-hint">Issuing is a human action — only your PIN can do it. Sent once, never stored.</span>
+            <input type="password" id="mndIssuePin" autocomplete="off" placeholder="typed at issuance, never stored" />
+          </label>
           <button id="mndIssueBtn" class="mnd-btn">Issue mandate</button>
         </div>
       </details>
@@ -8565,6 +8595,8 @@
           issueExpires: document.getElementById('mndIssueExpires'),
           issuePin: document.getElementById('mndIssuePin'),
           issueBtn: document.getElementById('mndIssueBtn'),
+          issueDetails: document.getElementById('mndIssueDetails'),
+          agentAPrefillNote: document.getElementById('mndAgentAPrefillNote'),
         };
         const fetchImpl = (url, opts = {}) => fetch(url, {
           ...opts,

package/dashboard/mandates.js

@@ -106,13 +106,30 @@ export function createController({ doc, els, fetchImpl }) {
     return { status: res.status, body };
   }
 
-  function note(msg, isError) {
+  // kind: 'error' | 'success' are PERSISTENT (cleared only by the next note or
+  // an explicit clearNote) — a transient toast the operator never sees is how
+  // the 2026-06-05 silent-issuance-failure happened. 'info' stays transient.
+  function note(msg, kind) {
     if (!els.notice) return;
+    const isError = kind === true || kind === 'error'; // boolean kept for back-compat
     els.notice.textContent = msg;
-    els.notice.className = isError ? 'mnd-notice mnd-notice-err' : 'mnd-notice';
-    if (msg) setTimeout(() => { if (els.notice.textContent === msg) els.notice.textContent = ''; }, 8000);
+    els.notice.className = isError ? 'mnd-notice mnd-notice-err'
+      : kind === 'success' ? 'mnd-notice mnd-notice-ok'
+      : 'mnd-notice';
+    if (msg && !isError && kind !== 'success') {
+      setTimeout(() => { if (els.notice.textContent === msg) els.notice.textContent = ''; }, 8000);
+    }
   }
 
+  function clearNote() {
+    if (!els.notice) return;
+    els.notice.textContent = '';
+    els.notice.className = 'mnd-notice';
+  }
+
+  let refreshErrorShown = false;
+  let autoOpenedIssueForm = false;
+
   async function refresh() {
     try {
       const [mand, audit] = await Promise.all([
@@ -125,12 +142,22 @@ export function createController({ doc, els, fetchImpl }) {
         if (els.stamp) els.stamp.textContent = '';
         return;
       }
-      els.list.innerHTML = renderMandates(mand.body?.mandates);
+      const mandates = mand.body?.mandates;
+      els.list.innerHTML = renderMandates(mandates);
       els.audit.innerHTML = renderAudit(audit.body);
       if (els.stamp) els.stamp.textContent = 'updated ' + new Date().toLocaleTimeString();
+      // Nothing issued yet → the issue form IS the page's call to action;
+      // open it once rather than hiding it behind a collapsed <details>.
+      if (!autoOpenedIssueForm && els.issueDetails && (!Array.isArray(mandates) || mandates.length === 0)) {
+        els.issueDetails.open = true;
+        autoOpenedIssueForm = true;
+      }
+      // A persistent refresh error from a server restart-gap heals itself.
+      if (refreshErrorShown) { clearNote(); refreshErrorShown = false; }
       wireRevokeButtons();
     } catch (e) {
-      note('refresh failed: ' + (e?.message ?? e), true);
+      refreshErrorShown = true;
+      note('refresh failed: ' + (e?.message ?? e) + ' — retrying automatically.', 'error');
     }
   }
 
@@ -150,25 +177,54 @@ export function createController({ doc, els, fetchImpl }) {
             body: JSON.stringify({ pin, reason: reasonEl?.value || 'operator revocation (dashboard)' }),
           });
           if (pinEl) pinEl.value = ''; // never retain the PIN
-          if (status === 200) { note(`Mandate ${id} revoked.`); await refresh(); }
-          else note(body?.error ?? `revoke failed (${status})`, true);
+          if (status === 200) { note(`✓ Mandate ${id} revoked — the gate now denies its actions.`, 'success'); await refresh(); }
+          else note(`Not revoked — the server refused: ${body?.error ?? `HTTP ${status}`}`, 'error');
         } finally { btn.disabled = false; }
       };
     });
   }
 
+  // Validate EVERYTHING client-side and report every problem at once —
+  // never POST a request we know the server will refuse, and never let the
+  // operator discover a missing field one transient error at a time.
+  function validateIssueForm() {
+    const problems = [];
+    if (!els.issueScope?.value?.trim()) problems.push('• Scope is empty — give the permission slip a short name.');
+    if (!els.issueAgentA?.value?.trim()) problems.push('• Agent A is empty — this agent’s own fingerprint (normally pre-filled).');
+    if (!els.issueAgentB?.value?.trim()) problems.push('• Agent B is empty — paste the other agent’s routing fingerprint.');
+    let authorities = null;
+    const rawAuth = els.issueAuthorities?.value ?? '';
+    try {
+      authorities = JSON.parse(rawAuth || '[]');
+      if (!Array.isArray(authorities) || authorities.length === 0) {
+        problems.push('• Authorities is empty — the mandate must delegate at least one action.');
+        authorities = null;
+      }
+    } catch {
+      problems.push('• Authorities is not valid JSON — it must be an array of { action, bounds }.');
+    }
+    const expiresRaw = els.issueExpires?.value ?? '';
+    if (!expiresRaw) {
+      problems.push('• Expiry is empty — every mandate must expire (normally pre-filled to a week out).');
+    } else if (!(Date.parse(expiresRaw) > Date.now())) {
+      problems.push('• Expiry is in the past — pick a future date.');
+    }
+    if (!els.issuePin?.value) problems.push('• Your dashboard PIN is missing — issuing is a human action; agent credentials are refused.');
+    return { problems, authorities };
+  }
+
   async function issue() {
-    const pin = els.issuePin?.value ?? '';
-    if (!pin) { note('Type your dashboard PIN — issuance is a human action; agent credentials are refused.', true); return; }
-    let authorities;
-    try { authorities = JSON.parse(els.issueAuthorities?.value || '[]'); }
-    catch { note('Authorities must be valid JSON (array of { action, bounds }).', true); return; }
+    const { problems, authorities } = validateIssueForm();
+    if (problems.length > 0) {
+      note('Not issued — fix the following first:\n' + problems.join('\n'), 'error');
+      return;
+    }
     const payload = {
-      pin,
+      pin: els.issuePin.value,
       scope: els.issueScope?.value?.trim(),
       agents: [els.issueAgentA?.value?.trim(), els.issueAgentB?.value?.trim()],
       authorities,
-      expiresAt: els.issueExpires?.value ? new Date(els.issueExpires.value).toISOString() : '',
+      expiresAt: new Date(els.issueExpires.value).toISOString(),
     };
     els.issueBtn.disabled = true;
     try {
@@ -179,19 +235,51 @@ export function createController({ doc, els, fetchImpl }) {
       });
       if (els.issuePin) els.issuePin.value = ''; // never retain the PIN
       if (status === 201) {
-        note(`Mandate ${body?.mandate?.id ?? ''} issued.`);
+        note(`✓ Mandate ${body?.mandate?.id ?? ''} issued — it is active and listed above. The agents can now act within its bounds.`, 'success');
+        if (els.issueDetails) els.issueDetails.open = false;
         await refresh();
       } else {
-        note(body?.error ?? `issue failed (${status})`, true);
+        note(`Not issued — the server refused: ${body?.error ?? `HTTP ${status}`}`, 'error');
       }
     } finally { els.issueBtn.disabled = false; }
   }
 
+  // datetime-local wants local "YYYY-MM-DDTHH:MM" — toISOString() (UTC, with
+  // seconds + Z) renders as blank in the picker.
+  function defaultExpiryLocal() {
+    const d = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000);
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+  }
+
+  // The system KNOWS this agent's fingerprint — asking the operator to paste a
+  // 32-hex string the dashboard can fetch itself is exactly the UX failure
+  // Justin flagged. /threadline/health reads the canonical identity.json (works
+  // even when the relay is disconnected); /threadline/status is the fallback.
+  async function prefillAgentA() {
+    if (!els.issueAgentA || els.issueAgentA.value) return;
+    try {
+      let fp = null;
+      const health = await fetchJson('/threadline/health');
+      if (health.status === 200) fp = health.body?.fingerprint ?? null;
+      if (!fp) {
+        const status = await fetchJson('/threadline/status');
+        fp = status.body?.relay?.fingerprint ?? null;
+      }
+      if (fp && els.issueAgentA && !els.issueAgentA.value) {
+        els.issueAgentA.value = fp;
+        if (els.agentAPrefillNote) els.agentAPrefillNote.textContent = '✓ pre-filled — this agent’s own fingerprint';
+      }
+    } catch { /* leave blank; validation reports it plainly */ }
+  }
+
   function start() {
     if (running) return;
     running = true;
     if (els.issueAuthorities && !els.issueAuthorities.value) els.issueAuthorities.value = AUTHORITIES_TEMPLATE;
+    if (els.issueExpires && !els.issueExpires.value) els.issueExpires.value = defaultExpiryLocal();
     if (els.issueBtn) els.issueBtn.onclick = issue;
+    prefillAgentA();
     refresh();
     timer = setInterval(refresh, REFRESH_MS);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.313",
+  "version": "1.3.314",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-05T18:12:41.393Z",
-  "instarVersion": "1.3.313",
+  "generatedAt": "2026-06-05T18:49:31.951Z",
+  "instarVersion": "1.3.314",
   "entryCount": 199,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.314.md

@@ -0,0 +1,89 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The Mandates dashboard tab was overhauled after a real operator failed to
+issue a mandate through it (2026-06-05). Four fixes:
+
+1. **Layout**: the panel (and the Process Health / Machines / Preferences
+   panels, which shared the bug) rendered squashed into the 280px sidebar
+   grid column. All `.ph-root` panels now span the full grid.
+2. **Pre-fills**: Agent A is pre-filled with this agent's own routing
+   fingerprint (fetched from `/threadline/health`); expiry is pre-filled to
+   one week out. The operator no longer pastes hex strings the system
+   already knows.
+3. **Validation**: clicking Issue with missing/invalid fields now reports
+   EVERY problem at once in plain English, client-side, before anything is
+   sent. Previously an empty form POSTed, the server refused, and the only
+   feedback was a transient toast.
+4. **Persistent feedback**: errors and the "✓ Mandate issued" confirmation
+   are persistent banners, not 8-second toasts. A silent failure is no
+   longer possible; success is unmissable.
+
+The last knowingly-stale entry from the 2026-06-05 test-debt triage is
+resolved: the TunnelManager unit suite — parked in the CI skip-list because it
+predated the tunnel provider/tier rewrite (22 of its 29 tests could never
+pass) — has been rewritten against the current architecture and turned back
+on. The tunnel layer's core lifecycle is now gated in CI at the manager level:
+provider-pool fallback, the reachability probe, the owner-consent flow for
+backup relays (including the single-use nonce and the decline cooldown), the
+self-heal stability gate, and mandatory credential rotation after a relay
+episode.
+
+## What to Tell Your User
+
+If you ever tried to issue a coordination mandate from the dashboard and
+nothing seemed to happen, that flow is fixed: the form now fills in
+everything the system already knows, tells you exactly what is missing
+before submitting, and shows an unmissable confirmation when the mandate is
+issued. The Mandates, Process Health, Machines, and Preferences tabs also
+now use the full width of the page instead of a narrow column.
+
+Nothing user-visible. This hardens the safety net around the tunnel/backup-
+relay machinery your dashboard links depend on — regressions in that
+machinery now fail PRs instead of shipping.
+
+## Summary of New Capabilities
+
+- Mandates tab: pre-filled Agent A fingerprint + default one-week expiry,
+  all-at-once client-side validation, persistent success/error banners,
+  plain-English field hints, and the issue form auto-opens when no mandates
+  exist yet.
+- Layout fix for all `.ph-root` dashboard panels (Mandates, Process Health,
+  Machines, Preferences Learning): full-grid width instead of the sidebar
+  column.
+- Maturity: stable (UI-only change over the existing PIN-gated issuance
+  API; no server surface changed).
+
+- `tests/unit/TunnelManager.test.ts` runs in CI again (removed from the
+  vitest.push.config.ts quarantine): 51 deterministic tests driven entirely
+  through the constructor injection seams (`injections.providers`,
+  `injections.fetch`) and the public deterministic drivers
+  (`runSelfHealCheck()`, `grantConsent()`, `declineConsent()`) — no real
+  timers, processes, or network.
+- Maturity: stable (test-only change + quarantine re-arm; no production code
+  touched).
+
+## Evidence
+
+Born from a live operator report (2026-06-05): "I clicked 'Issue Mandate'
+after entering my PIN… this UI/UX is TERRIBLE. Very confusing, unclear, and
+squashed to the side" — the mandate never registered server-side and the
+failure was invisible. 24 tests green in the mandates tab suite (squash
+regression pin, every-problem-at-once validation, persistence under fake
+timers, prefill + never-overwrite, auto-open); 80 green across all dashboard
+suites; tsc clean.
+
+Three consecutive green runs (51/51, ~0.8s each), including under the push
+config; the full 11-file tunnel test family passes together (165/165);
+`npx tsc --noEmit` clean. The rewrite-era sibling suites
+(tunnel-manager-rewrite / tunnel-self-heal / tunnel-consent-state-machine /
+tunnel-credential-rotation) already covered parts of this surface — this
+suite consolidates the manager-level coverage, adds the previously-untested
+edge paths (persisted-state restore, corrupted state file, nonce replay,
+cooldown suppression across restart, rotation-failure flag retention,
+probe-handle release), and retires the stale file that occupied the
+canonical TunnelManager.test.ts name.

package/upgrades/side-effects/tunnelmanager-suite-rearm.md

@@ -0,0 +1,53 @@
+# Side-effects review — TunnelManager unit-suite rewrite + quarantine re-arm
+
+Closes the durable commitment "Rewrite TunnelManager unit suite" opened during
+the 2026-06-05 full-suite triage (the one knowingly-stale entry left parked by
+the test-debt re-arm PR #837).
+
+## 1. The change
+
+- **`tests/unit/TunnelManager.test.ts`** — full rewrite. The old suite
+  predated the tunnel provider/tier rewrite: it mocked the `cloudflared`
+  module directly, while production drives a provider pool with a REAL
+  reachability probe (`driveTier1` → `probeReachability` fetches
+  `<url>/health` and requires 2xx), so 22/29 tests could never pass. The new
+  suite uses the constructor injection seams exclusively
+  (`injections.providers`, `injections.fetch`) plus the public deterministic
+  drivers (`runSelfHealCheck()`, `grantConsent()`, `declineConsent()`):
+  51 tests covering constructor/persisted-state restore, the happy start
+  path, provider-pool fallback (unavailable / start-throw / probe-fail /
+  fetch-throw), Tier-2-never-auto-started, exhaustion + relaysEnabled /
+  relayConsent config gates, the consent flow (nonce issuance, wrong-nonce
+  rejection, single-use replay, decline cooldown, timeout, cooldown
+  suppression across restart, post-grant probe/start failure), the self-heal
+  stability gate (reset / progress / switched, counter reset on flap,
+  throwaway-probe release, self-healed event), stop semantics (relay-stop
+  rotates credentials, plain stop doesn't, pending consent cleared), and
+  credential rotation (no-op when not pending, failure retains the flag +
+  emits rotation-failed, boot recovery, unwired-rotator loud-clear).
+- **`vitest.push.config.ts`** — `tests/unit/TunnelManager.test.ts` REMOVED
+  from FLAKY_TESTS (re-armed) with a dated comment. No other entries touched.
+
+## 2. Blast radius
+
+- Zero production code changed — test + CI-config only.
+- CI runs 51 additional deterministic tests (~0.8s, no network/timers/
+  processes). Risk is future-positive: tunnel-lifecycle regressions now fail
+  PRs instead of rotting behind the quarantine.
+- Honest overlap note: the rewrite-era sibling suites
+  (tunnel-manager-rewrite.test.ts, tunnel-self-heal.test.ts,
+  tunnel-consent-state-machine.test.ts, tunnel-credential-rotation.test.ts —
+  39 tests, already in CI) cover parts of this surface. The new suite
+  consolidates manager-level coverage under the canonical filename and adds
+  edge paths they don't exercise (persisted-state restore + corrupted state
+  file, concurrent-start coalescing, start-after-exhaustion semantics, nonce
+  replay, cooldown suppression across construction, rotation-failure flag
+  retention, probe-handle release). Redundancy between them is cheap and
+  deliberate.
+
+## 3. Test coverage
+
+- New suite: 51/51 green across three consecutive runs (including under the
+  push config — proving the re-arm actually executes it).
+- Full tunnel family (11 files incl. the 4 rewrite-era siblings): 165/165.
+- `npx tsc --noEmit` clean.