instar 1.3.618 → 1.3.620

package/dashboard/index.html

@@ -3397,6 +3397,10 @@
     <div id="subscriptionsPanel" class="ph-root" style="display:none;flex-direction:column;padding:28px;gap:24px;overflow-y:auto">
       <h2 class="ph-title">Subscriptions</h2>
       <p class="ph-intro">Your subscription accounts and how much of each is left before it resets — plus any logins waiting for you to approve on your phone.</p>
+      <!-- One-tap follow-me Approve card(s) — rendered only when another machine could use one of
+           your subscriptions (ws52-operator-tap-not-text Part A). Leads the panel as the primary
+           action when present; silent otherwise. -->
+      <div id="subFollowMe"></div>
       <section class="ph-section">
         <h3 class="ph-h">Accounts</h3>
         <p class="ph-h-sub">Each account’s live usage (5-hour and weekly) and when it resets.</p>
@@ -3429,6 +3433,14 @@
         <h3 class="ph-h">Issued mandates</h3>
         <div id="mndList"></div>
       </section>
+      <!-- operator-surface-power-user: this dashboard file contains DELIBERATELY-ADVANCED,
+           non-default surfaces that necessarily take raw technical values — the collapsed
+           "Advanced — author a mandate by hand" mandate form below (raw agent fingerprints +
+           the authorities the agents may use) and the Threadline bridge fingerprint/name inputs.
+           These are NOT the default operator path: account-follow-me is the one-tap Approve card
+           (Subscriptions tab) and general grants go through the Agent-Proposes/Operator-Approves
+           approval surface. (Marker is file-level by the gate's design; granular per-region marking
+           + redesigning this legacy raw form to a builder are tracked follow-ups.) -->
       <details class="ph-detail" id="mndIssueDetails">
         <summary class="ph-detail-summary">Advanced — author a mandate by hand (PIN required)</summary>
         <div class="mnd-issue-form">
@@ -9144,10 +9156,13 @@
         const els = {
           accounts: document.getElementById('subAccounts'),
           pending: document.getElementById('subPending'),
+          followMe: document.getElementById('subFollowMe'),
         };
+        // Pass opts through (method/body/signal) so the controller can POST the follow-me
+        // scan + the PIN-gated issue-for-machine, not just GET.
         const fetchImpl = (url, opts = {}) => fetch(url, {
+          ...opts,
           headers: { 'Authorization': `Bearer ${token}`, ...(opts.headers || {}) },
-          signal: opts.signal,
         });
         __subController = __subModule.createController({ doc: document, els, fetchImpl });
       }

package/dashboard/subscriptions.js

@@ -172,6 +172,80 @@ export function renderAccounts(doc, target, accounts, now = Date.now(), inUseAcc
   }
 }
 
+/**
+ * Account Follow-Me — the ONE-TAP Approve card (ws52-operator-tap-not-text Part A).
+ * Renders a scan consent-offer as a plain-language card the operator APPROVES with a
+ * single PIN tap — never a JSON/fingerprint paste (the 2026-06-17 operator feedback:
+ * "operators act in taps, not text"). All operator-facing values are sanitized TEXT;
+ * the only machine-readable data on the card are the NON-SENSITIVE account/target ids
+ * as data-* attributes (used to find the offer on Approve). The agent fingerprints
+ * (FD2) are NEVER placed in the DOM — they live in the controller's offer state and
+ * are sent server-side at POST time. By construction this card carries zero raw
+ * technical text, so it PASSES the arm-1 operator-surface gate.
+ */
+export function renderFollowMeApproveCard(doc, offer) {
+  const card = el(doc, 'div', 'sub-followme-offer');
+  // Non-sensitive identifiers, for the Approve handler to resolve the offer. NOT
+  // operator-facing text; never a fingerprint/JSON.
+  card.setAttribute('data-account-id', sanitizeForDisplay(offer && offer.accountId, 'label'));
+  card.setAttribute('data-target-machine-id', sanitizeForDisplay(offer && offer.targetMachineId, 'label'));
+
+  const machine = sanitizeForDisplay(offer && offer.machineNickname, 'label');
+  const account = sanitizeForDisplay(offer && offer.accountLabel, 'label');
+  card.appendChild(el(doc, 'div', 'sub-followme-headline',
+    `Let ${machine} use your ${account} subscription`));
+  card.appendChild(el(doc, 'div', 'sub-followme-sub',
+    sanitizeForDisplay(offer && offer.expiryText, 'summary') || 'Authorizes this one setup, then expires.'));
+
+  const pin = doc.createElement('input');
+  pin.setAttribute('type', 'password');
+  pin.setAttribute('class', 'sub-followme-pin');
+  pin.setAttribute('placeholder', 'Your PIN'); // a PIN box, not a technical value
+  pin.setAttribute('autocomplete', 'off');
+  card.appendChild(pin);
+
+  const approve = el(doc, 'button', 'sub-followme-approve', 'Approve');
+  approve.setAttribute('data-followme-approve', '1');
+  card.appendChild(approve);
+  return card;
+}
+
+/** Render the list of follow-me consent offers as one-tap Approve cards (or nothing if none). */
+export function renderFollowMeOffers(doc, target, offers) {
+  if (!target) return;
+  target.replaceChildren();
+  if (!Array.isArray(offers) || offers.length === 0) return; // silent when nothing to offer
+  target.appendChild(el(doc, 'div', 'sub-followme-title', 'Let another machine use a subscription'));
+  for (const offer of offers) target.appendChild(renderFollowMeApproveCard(doc, offer));
+}
+
+/**
+ * Build the /mandate/issue-for-machine payload from a tapped Approve card + the
+ * held offers + the operator's PIN (ws52-operator-tap-not-text Part A). Pure: the
+ * card carries only the non-sensitive account/target ids; the agent fingerprints
+ * (FD2) come from the matched offer in controller state — the operator never typed
+ * them. Returns the payload, or `{ error }` for a missing PIN, or null when the
+ * card has no matching offer / the offer lacks its FD2 agent pair (fail-closed —
+ * never POST an under-specified mandate request).
+ */
+export function buildFollowMeIssuePayload(card, offers, pinValue) {
+  if (!card || typeof card.getAttribute !== 'function') return null;
+  const accountId = card.getAttribute('data-account-id');
+  const targetMachineId = card.getAttribute('data-target-machine-id');
+  if (!accountId || !targetMachineId) return null;
+  const offer = (Array.isArray(offers) ? offers : []).find(
+    (o) => o && o.accountId === accountId && o.targetMachineId === targetMachineId,
+  );
+  if (!offer) return null; // unknown/stale card — never POST
+  if (!Array.isArray(offer.agents) || offer.agents.length !== 2
+      || offer.agents.some((a) => typeof a !== 'string' || !a)) {
+    return null; // FD2 agent pair missing — fail-closed
+  }
+  const pin = typeof pinValue === 'string' ? pinValue.trim() : '';
+  if (!pin) return { error: 'pin-required' };
+  return { pin, accountId, targetMachineId, agents: [offer.agents[0], offer.agents[1]] };
+}
+
 /** Pending Logins panel: device code / verification URL (as TEXT) + TTL + reissues. */
 export function renderPendingLogins(doc, target, logins, now = Date.now()) {
   if (!target) return;
@@ -219,6 +293,8 @@ const URLS = {
   accounts: '/subscription-pool',
   pending: '/subscription-pool/pending-logins',
   inUse: '/subscription-pool/in-use',
+  scan: '/subscription-pool/follow-me/scan', // POST — follow-me consent offers (one-tap card)
+  issue: '/mandate/issue-for-machine',       // POST (PIN-gated) — Approve issues the mandate
 };
 
 export function createController(opts) {
@@ -232,7 +308,7 @@ export function createController(opts) {
     cancel = (id) => clearTimeout(id),
   } = opts;
 
-  const state = { timerId: null, active: false, inFlight: null };
+  const state = { timerId: null, active: false, inFlight: null, offers: [], approveWired: false };
 
   async function fetchJson(url, controller) {
     const resp = await fetchImpl(url, { signal: controller.signal });
@@ -240,19 +316,34 @@ export function createController(opts) {
     return resp.json();
   }
 
+  // POST helper (follow-me scan + the PIN-gated issue both POST). Best-effort callers
+  // catch their own failures so a follow-me hiccup never blanks the accounts list.
+  async function postJson(url, body, controller) {
+    const resp = await fetchImpl(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: body == null ? undefined : JSON.stringify(body),
+      signal: controller && controller.signal,
+    });
+    let json = null;
+    try { json = await resp.json(); } catch { /* may be empty */ }
+    return { ok: resp.ok, status: resp.status, json };
+  }
+
   async function tick() {
     if (!state.active) return;
     if (state.inFlight) { try { state.inFlight.abort(); } catch { /* superseded */ } }
     const controller = typeof AbortController !== 'undefined' ? new AbortController() : { signal: undefined, abort() {} };
     state.inFlight = controller;
-    let accountsBody, pendingBody, inUseBody;
+    let accountsBody, pendingBody, inUseBody, scanBody;
     try {
-      // in-use is best-effort — its failure must not blank the accounts list, so
-      // it's caught independently and degrades to "unknown" (no badge).
-      [accountsBody, pendingBody, inUseBody] = await Promise.all([
+      // in-use AND the follow-me scan are best-effort — their failure must not blank the
+      // accounts list, so each is caught independently (in-use → "unknown"; scan → no card).
+      [accountsBody, pendingBody, inUseBody, scanBody] = await Promise.all([
         fetchJson(URLS.accounts, controller),
         fetchJson(URLS.pending, controller),
         fetchJson(URLS.inUse, controller).catch(() => null),
+        postJson(URLS.scan, {}, controller).then((r) => (r.ok ? r.json : null)).catch(() => null),
       ]);
     } catch {
       if (controller.signal && controller.signal.aborted) return;
@@ -268,6 +359,7 @@ export function createController(opts) {
       reschedule();
       return;
     }
+    state.offers = scanBody && Array.isArray(scanBody.offered) ? scanBody.offered : [];
     render(accountsBody, pendingBody, inUseBody);
     reschedule();
   }
@@ -278,6 +370,56 @@ export function createController(opts) {
     const inUseAccountId = inUseBody && inUseBody.activeAccountId ? inUseBody.activeAccountId : null;
     renderAccounts(doc, els.accounts, accounts, now(), inUseAccountId);
     renderPendingLogins(doc, els.pending, logins, now());
+    // The one-tap follow-me Approve card(s) — rendered into els.followMe from the scan offers
+    // (ws52-operator-tap-not-text Part A). Silent when there are none. The Approve click is wired
+    // once (delegated) so re-renders never stack listeners.
+    if (els.followMe) {
+      renderFollowMeOffers(doc, els.followMe, state.offers);
+      wireApprove();
+    }
+  }
+
+  // Delegated, wired ONCE: an Approve tap reads the card's PIN, builds the issue-for-machine
+  // payload from the held offers (FD2 agents resolved server-side — never typed), and POSTs the
+  // PIN-gated mandate. The card carries only non-sensitive ids; the PIN is sent once, never stored.
+  function wireApprove() {
+    if (state.approveWired || !els.followMe) return;
+    state.approveWired = true;
+    els.followMe.addEventListener('click', (ev) => {
+      const btn = ev.target && ev.target.closest ? ev.target.closest('[data-followme-approve]') : null;
+      if (!btn || !els.followMe.contains(btn)) return;
+      const card = btn.closest('.sub-followme-offer');
+      if (!card) return;
+      const pinInput = card.querySelector('.sub-followme-pin');
+      const pinVal = pinInput ? pinInput.value : '';
+      const payload = buildFollowMeIssuePayload(card, state.offers, pinVal);
+      if (payload === null) { setCardStatus(card, 'Couldn’t prepare this request — please refresh.'); return; }
+      if (payload.error === 'pin-required') { setCardStatus(card, 'Enter your PIN to approve.'); return; }
+      setCardStatus(card, 'Approving…');
+      btn.setAttribute('disabled', '1');
+      void (async () => {
+        try {
+          const r = await postJson(URLS.issue, payload);
+          if (r.ok) {
+            setCardStatus(card, 'Approved — the machine is logging in now. Watch the “Logins waiting” panel below for the link to tap.');
+            if (pinInput) pinInput.value = '';
+          } else {
+            const msg = r.json && (r.json.error || r.json.reason) ? (r.json.error || r.json.reason) : `failed (${r.status})`;
+            setCardStatus(card, `Couldn’t approve: ${msg}`);
+            btn.removeAttribute('disabled');
+          }
+        } catch (e) {
+          setCardStatus(card, 'Couldn’t reach the server — try again.');
+          btn.removeAttribute('disabled');
+        }
+      })();
+    });
+  }
+
+  function setCardStatus(card, text) {
+    let s = card.querySelector('.sub-followme-status');
+    if (!s) { s = el(doc, 'div', 'sub-followme-status', ''); card.appendChild(s); }
+    s.textContent = text;
   }
 
   function reschedule() {
@@ -299,5 +441,8 @@ export function createController(opts) {
 }
 
 if (typeof window !== 'undefined') {
-  window.Subscriptions = { createController, sanitizeForDisplay, renderAccounts, renderPendingLogins };
+  window.Subscriptions = {
+    createController, sanitizeForDisplay, renderAccounts, renderPendingLogins,
+    renderFollowMeOffers, renderFollowMeApproveCard, buildFollowMeIssuePayload,
+  };
 }

package/dist/coordination/AccountFollowMeOperatorOutbox.d.ts

@@ -0,0 +1,42 @@
+export interface OperatorOutboxRecord {
+    /** `${ledgerKey}::${state}` — the dedup unit (one message per ledger state). */
+    dedupKey: string;
+    /** The event that first emitted for this (ledgerKey,state) — audit + idempotency. */
+    eventId: string;
+    ledgerKey: string;
+    state: string;
+    emittedAt: string;
+}
+export interface OperatorOutboxDeps {
+    filePath: string;
+    now?: () => number;
+}
+export declare class AccountFollowMeOperatorOutbox {
+    private readonly d;
+    constructor(deps: OperatorOutboxDeps);
+    private now;
+    private dedupKey;
+    private readAll;
+    private writeAll;
+    /**
+     * Atomically decide whether to emit an operator message for this (ledgerKey,state).
+     * Returns `{ emit:true }` exactly once per (ledgerKey,state) — the FIRST caller
+     * records and emits; every subsequent caller (redelivery/restart/retry, regardless
+     * of eventId) gets `{ emit:false }`. This is the "at most one message per ledger
+     * state" guarantee.
+     */
+    claimEmit(args: {
+        ledgerKey: string;
+        state: string;
+        eventId: string;
+    }): {
+        emit: boolean;
+        firstEventId: string;
+    };
+    /** Has a message already been emitted for this (ledgerKey,state)? (read-only) */
+    hasEmitted(ledgerKey: string, state: string): boolean;
+    /** Drop all outbox records for a ledger key (e.g. when the pair is removed/revoked). Idempotent. */
+    clearLedger(ledgerKey: string): void;
+    list(): OperatorOutboxRecord[];
+}
+//# sourceMappingURL=AccountFollowMeOperatorOutbox.d.ts.map

package/dist/coordination/AccountFollowMeOperatorOutbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccountFollowMeOperatorOutbox.d.ts","sourceRoot":"","sources":["../../src/coordination/AccountFollowMeOperatorOutbox.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,qBAAa,6BAA6B;IACxC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAqB;gBAC3B,IAAI,EAAE,kBAAkB;IAIpC,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,QAAQ;IAIhB,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,QAAQ;IAKhB;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG;QACtE,IAAI,EAAE,OAAO,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;KACtB;IAkBD,iFAAiF;IACjF,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAIrD,oGAAoG;IACpG,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAMpC,IAAI,IAAI,oBAAoB,EAAE;CAG/B"}

package/dist/coordination/AccountFollowMeOperatorOutbox.js

@@ -0,0 +1,81 @@
+/**
+ * WS5.2 (ws52-operator-tap-not-text Part B, R3.3) — durable operator-message outbox.
+ *
+ * The cross-model pass (codex) flagged that "exactly one tappable link / one failure
+ * message" is unachievable across mesh redelivery, fronting-machine restart, and
+ * retry WITHOUT a durable, idempotent outbox. This store guarantees AT MOST ONE
+ * visible operator message PER LEDGER STATE: the first claim for a
+ * (ledgerKey, state) pair emits; every later claim for the SAME (ledgerKey, state)
+ * — a redelivery, a restart replay, a retry — is suppressed. A genuine state
+ * TRANSITION (enroll-in-flight → login-issued → failed) is a new (ledgerKey, state)
+ * key, so each distinct state surfaces its own single message.
+ *
+ * fs-backed (the DeliveredMandateStore pattern), pure + unit-testable.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export class AccountFollowMeOperatorOutbox {
+    d;
+    constructor(deps) {
+        this.d = deps;
+    }
+    now() {
+        return this.d.now ? this.d.now() : Date.now();
+    }
+    dedupKey(ledgerKey, state) {
+        return `${ledgerKey}::${state}`;
+    }
+    readAll() {
+        try {
+            const raw = JSON.parse(fs.readFileSync(this.d.filePath, 'utf8'));
+            return Array.isArray(raw) ? raw : [];
+        }
+        catch {
+            // @silent-fallback-ok — no outbox yet ⇒ nothing emitted ⇒ first claim should emit.
+            return [];
+        }
+    }
+    writeAll(records) {
+        fs.mkdirSync(path.dirname(this.d.filePath), { recursive: true });
+        fs.writeFileSync(this.d.filePath, JSON.stringify(records, null, 2));
+    }
+    /**
+     * Atomically decide whether to emit an operator message for this (ledgerKey,state).
+     * Returns `{ emit:true }` exactly once per (ledgerKey,state) — the FIRST caller
+     * records and emits; every subsequent caller (redelivery/restart/retry, regardless
+     * of eventId) gets `{ emit:false }`. This is the "at most one message per ledger
+     * state" guarantee.
+     */
+    claimEmit(args) {
+        const key = this.dedupKey(args.ledgerKey, args.state);
+        const all = this.readAll();
+        const existing = all.find((r) => r.dedupKey === key);
+        if (existing) {
+            return { emit: false, firstEventId: existing.eventId };
+        }
+        const record = {
+            dedupKey: key,
+            eventId: args.eventId,
+            ledgerKey: args.ledgerKey,
+            state: args.state,
+            emittedAt: new Date(this.now()).toISOString(),
+        };
+        this.writeAll([...all, record]);
+        return { emit: true, firstEventId: args.eventId };
+    }
+    /** Has a message already been emitted for this (ledgerKey,state)? (read-only) */
+    hasEmitted(ledgerKey, state) {
+        return this.readAll().some((r) => r.dedupKey === this.dedupKey(ledgerKey, state));
+    }
+    /** Drop all outbox records for a ledger key (e.g. when the pair is removed/revoked). Idempotent. */
+    clearLedger(ledgerKey) {
+        const all = this.readAll();
+        const next = all.filter((r) => r.ledgerKey !== ledgerKey);
+        if (next.length !== all.length)
+            this.writeAll(next);
+    }
+    list() {
+        return this.readAll();
+    }
+}
+//# sourceMappingURL=AccountFollowMeOperatorOutbox.js.map

package/dist/coordination/AccountFollowMeOperatorOutbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccountFollowMeOperatorOutbox.js","sourceRoot":"","sources":["../../src/coordination/AccountFollowMeOperatorOutbox.ts"],"names":[],"mappings":"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"}

package/dist/coordination/AccountFollowMeSingleFlight.d.ts

@@ -0,0 +1,68 @@
+export type SingleFlightState = 'enroll-in-flight' | 'login-issued' | 'completed' | 'failed';
+export interface SingleFlightRecord {
+    /** `${accountId}::${targetMachineId}` (canonical account id). */
+    key: string;
+    state: SingleFlightState;
+    /** The fronting machine that owns this enroll loop (provenance; this store is per-machine). */
+    frontingMachineId: string;
+    /** The mandate authorizing this enrollment. */
+    mandateId: string;
+    /** Opaque holder token (e.g. a process/run id) for dead-holder auto-heal. */
+    holder: string;
+    updatedAt: string;
+    /** While ACTIVE, the wall-clock (ms) past which the holder is presumed dead and the pair is reclaimable. */
+    ttlExpiresAt: number;
+}
+export interface SingleFlightDeps {
+    /** Absolute path to the ledger JSON file. */
+    filePath: string;
+    /** Injectable clock (ms) for tests. */
+    now?: () => number;
+}
+export declare function singleFlightKey(accountId: string, targetMachineId: string): string;
+export interface ClaimInput {
+    accountId: string;
+    targetMachineId: string;
+    frontingMachineId: string;
+    mandateId: string;
+    holder: string;
+    /** How long the enroll-in-flight claim is valid before a dead-holder reclaim is allowed. */
+    ttlMs: number;
+}
+export declare class AccountFollowMeSingleFlight {
+    private readonly d;
+    constructor(deps: SingleFlightDeps);
+    private now;
+    private readAll;
+    private writeAll;
+    get(key: string): SingleFlightRecord | undefined;
+    /** A pair is LIVE (refuse re-claim, suppress scan re-offer) iff it is in an active state AND not past its TTL. */
+    isActive(key: string): boolean;
+    /**
+     * The single-flight gate. Atomically claims (account,target) → `enroll-in-flight`
+     * iff no LIVE record exists. Returns `{ claimed:false }` while another enroll is
+     * genuinely in flight (the duplicate-login guard). A dead-holder (TTL lapsed) or a
+     * terminal record (completed/failed/absent) is re-claimable.
+     */
+    tryClaim(input: ClaimInput): {
+        claimed: boolean;
+        record: SingleFlightRecord;
+    };
+    /**
+     * Move a claimed pair to a new state. Refreshes the TTL for the still-active
+     * `login-issued` state (the operator now has a window to tap the link); terminal
+     * states clear the TTL window. Refuses to transition a key the caller does not
+     * hold (holder mismatch) so a stale actor can't stomp a live claim. No-op if absent.
+     */
+    transition(key: string, to: SingleFlightState, holder: string, opts?: {
+        ttlMs?: number;
+    }): {
+        ok: boolean;
+        reason?: string;
+        record?: SingleFlightRecord;
+    };
+    /** Drop a record entirely (e.g. on revocation of the pair's mandate). Idempotent. */
+    remove(key: string): void;
+    list(): SingleFlightRecord[];
+}
+//# sourceMappingURL=AccountFollowMeSingleFlight.d.ts.map

package/dist/coordination/AccountFollowMeSingleFlight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccountFollowMeSingleFlight.d.ts","sourceRoot":"","sources":["../../src/coordination/AccountFollowMeSingleFlight.ts"],"names":[],"mappings":"AAiCA,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,cAAc,GACd,WAAW,GACX,QAAQ,CAAC;AAKb,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,iBAAiB,CAAC;IACzB,+FAA+F;IAC/F,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,4GAA4G;IAC5G,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAElF;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,2BAA2B;IACtC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAmB;gBACzB,IAAI,EAAE,gBAAgB;IAIlC,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,QAAQ;IAKhB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAIhD,kHAAkH;IAClH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAM9B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,kBAAkB,CAAA;KAAE;IAsB7E;;;;;OAKG;IACH,UAAU,CACR,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,iBAAiB,EACrB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACxB;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,kBAAkB,CAAA;KAAE;IAoBhE,qFAAqF;IACrF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAMzB,IAAI,IAAI,kBAAkB,EAAE;CAG7B"}

package/dist/coordination/AccountFollowMeSingleFlight.js

@@ -0,0 +1,135 @@
+/**
+ * WS5.2 (ws52-operator-tap-not-text Part B) — DURABLE single-flight ledger for the
+ * account-follow-me cross-machine enroll connector.
+ *
+ * The convergence pass found that the live "single-flight per (account,target)"
+ * guarantee was wired as `inFlight: () => new Set()` — a fresh empty set every
+ * call, i.e. a NO-OP. A re-delivery, a restart, or a double-tap each spawned a new
+ * device-code login. This store is the real, durable, restart-surviving guarantee.
+ *
+ * It is a small state machine keyed `${accountId}::${targetMachineId}` (R3.1: the
+ * CANONICAL pool account id, owned within THIS fronting machine's ledger — the
+ * store is per-machine, so the frontingMachineId is recorded for provenance and a
+ * different fronting context cannot suppress this one's offers):
+ *
+ *   (absent) --tryClaim--> enroll-in-flight --markLoginIssued--> login-issued
+ *                                |                                    |
+ *                                v                                    v
+ *                              failed <----markFailed------------ completed
+ *
+ * `tryClaim` is the single-flight gate: it succeeds ONLY when there is no LIVE
+ * in-flight record (absent / completed / failed / a dead-holder whose TTL lapsed).
+ * While a pair is `enroll-in-flight` or `login-issued`, a second claim is REFUSED —
+ * so a re-delivery/restart/double-tap collapses to one login. A crash mid-enroll is
+ * self-healed: a claim past `ttlExpiresAt` reclaims the dead holder (PR-hand-lease
+ * pattern). `completed`/`failed` are terminal-but-re-armable: a genuinely fresh
+ * delivery can re-claim the pair (a new mandate, after the prior cycle closed).
+ *
+ * Pure + fs-backed (the DeliveredMandateStore pattern) so both sides of every
+ * transition are unit-testable without a server.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** The states in which a pair is LIVE — re-claim is refused and the scan must not re-offer. */
+const ACTIVE_STATES = new Set(['enroll-in-flight', 'login-issued']);
+export function singleFlightKey(accountId, targetMachineId) {
+    return `${accountId}::${targetMachineId}`;
+}
+export class AccountFollowMeSingleFlight {
+    d;
+    constructor(deps) {
+        this.d = deps;
+    }
+    now() {
+        return this.d.now ? this.d.now() : Date.now();
+    }
+    readAll() {
+        try {
+            const raw = JSON.parse(fs.readFileSync(this.d.filePath, 'utf8'));
+            return Array.isArray(raw) ? raw : [];
+        }
+        catch {
+            // @silent-fallback-ok — no ledger yet; an empty ledger means "nothing in flight" (safe).
+            return [];
+        }
+    }
+    writeAll(records) {
+        fs.mkdirSync(path.dirname(this.d.filePath), { recursive: true });
+        fs.writeFileSync(this.d.filePath, JSON.stringify(records, null, 2));
+    }
+    get(key) {
+        return this.readAll().find((r) => r.key === key);
+    }
+    /** A pair is LIVE (refuse re-claim, suppress scan re-offer) iff it is in an active state AND not past its TTL. */
+    isActive(key) {
+        const r = this.get(key);
+        if (!r || !ACTIVE_STATES.has(r.state))
+            return false;
+        return this.now() <= r.ttlExpiresAt; // a lapsed holder is NOT live (reclaimable)
+    }
+    /**
+     * The single-flight gate. Atomically claims (account,target) → `enroll-in-flight`
+     * iff no LIVE record exists. Returns `{ claimed:false }` while another enroll is
+     * genuinely in flight (the duplicate-login guard). A dead-holder (TTL lapsed) or a
+     * terminal record (completed/failed/absent) is re-claimable.
+     */
+    tryClaim(input) {
+        const key = singleFlightKey(input.accountId, input.targetMachineId);
+        const all = this.readAll();
+        const existing = all.find((r) => r.key === key);
+        const now = this.now();
+        const live = existing && ACTIVE_STATES.has(existing.state) && now <= existing.ttlExpiresAt;
+        if (live) {
+            return { claimed: false, record: existing };
+        }
+        const record = {
+            key,
+            state: 'enroll-in-flight',
+            frontingMachineId: input.frontingMachineId,
+            mandateId: input.mandateId,
+            holder: input.holder,
+            updatedAt: new Date(now).toISOString(),
+            ttlExpiresAt: now + Math.max(0, input.ttlMs),
+        };
+        this.writeAll([...all.filter((r) => r.key !== key), record]);
+        return { claimed: true, record };
+    }
+    /**
+     * Move a claimed pair to a new state. Refreshes the TTL for the still-active
+     * `login-issued` state (the operator now has a window to tap the link); terminal
+     * states clear the TTL window. Refuses to transition a key the caller does not
+     * hold (holder mismatch) so a stale actor can't stomp a live claim. No-op if absent.
+     */
+    transition(key, to, holder, opts) {
+        const all = this.readAll();
+        const idx = all.findIndex((r) => r.key === key);
+        if (idx < 0)
+            return { ok: false, reason: 'absent' };
+        if (all[idx].holder !== holder)
+            return { ok: false, reason: 'holder-mismatch' };
+        const now = this.now();
+        const ttlExpiresAt = ACTIVE_STATES.has(to)
+            ? now + Math.max(0, opts?.ttlMs ?? 0)
+            : 0;
+        const next = {
+            ...all[idx],
+            state: to,
+            updatedAt: new Date(now).toISOString(),
+            ttlExpiresAt,
+        };
+        all[idx] = next;
+        this.writeAll(all);
+        return { ok: true, record: next };
+    }
+    /** Drop a record entirely (e.g. on revocation of the pair's mandate). Idempotent. */
+    remove(key) {
+        const all = this.readAll();
+        const next = all.filter((r) => r.key !== key);
+        if (next.length !== all.length)
+            this.writeAll(next);
+    }
+    list() {
+        return this.readAll();
+    }
+}
+//# sourceMappingURL=AccountFollowMeSingleFlight.js.map

package/dist/coordination/AccountFollowMeSingleFlight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccountFollowMeSingleFlight.js","sourceRoot":"","sources":["../../src/coordination/AccountFollowMeSingleFlight.ts"],"names":[],"mappings":"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"}