npm - @mmmbuto/nexuscrew - Versions diffs - 0.8.46 → 0.8.47 - Mend

@mmmbuto/nexuscrew 0.8.46 → 0.8.47

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/CHANGELOG.md +24 -0
package/frontend/dist/assets/{index-DMG-rioF.js → index-Db2ivuxA.js} +28 -28
package/frontend/dist/index.html +1 -1
package/frontend/dist/version.json +1 -1
package/lib/fleet/cell-exec.js +126 -18
package/lib/fleet/launch.js +80 -23
package/lib/fleet/managed.js +10 -2
package/lib/fleet/prompt-delivery.js +275 -0
package/lib/fleet/runtime.js +49 -10
package/package.json +1 -1

package/frontend/dist/index.html CHANGED Viewed

@@ -11,7 +11,7 @@
   <meta name="apple-mobile-web-app-title" content="NexusCrew" />
   <link rel="manifest" href="/manifest.json" />
   <title>NexusCrew</title>
-  <script type="module" crossorigin src="/assets/index-DMG-rioF.js"></script>
+  <script type="module" crossorigin src="/assets/index-Db2ivuxA.js"></script>
   <link rel="stylesheet" crossorigin href="/assets/index-BAq6N1Md.css">
 </head>
 <body>

package/frontend/dist/version.json CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":"0.8.46"}
1	+ {"version":"0.8.47"}

package/lib/fleet/cell-exec.js CHANGED Viewed

@@ -65,12 +65,14 @@ function promptCharsOk(prompt) {
 function validRestartPrompt(value) {
   if (value === undefined) return true;
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
-  if (Object.keys(value).some((key) => !['tmuxBin', 'tmuxSession', 'prompt', 'readyMs'].includes(key))) return false;
+  if (Object.keys(value).some((key) => !['tmuxBin', 'tmuxSession', 'prompt', 'readyMs', 'client', 'readyWaitMs'].includes(key))) return false;
   return typeof value.tmuxBin === 'string' && value.tmuxBin.length > 0 && value.tmuxBin.length <= 4096
     && !/[\0\r\n]/.test(value.tmuxBin)
     && typeof value.tmuxSession === 'string' && /^[\w.@%:+-]{1,128}$/.test(value.tmuxSession)
     && promptCharsOk(value.prompt)
-    && (value.readyMs === undefined || validInteger(value.readyMs, 0, 30000));
+    && (value.readyMs === undefined || validInteger(value.readyMs, 0, 30000))
+    && (value.client === undefined || value.client === '' || value.client === 'kimi' || value.client === 'claude')
+    && (value.readyWaitMs === undefined || validInteger(value.readyWaitMs, 0, 120000));
 }
 function validPayload(payload) {
@@ -138,24 +140,117 @@ function waitChild(child) {
   });
 }
-function scheduleRestartPrompt(config, childState, seams = {}) {
-  if (!config) return { cancel() {} };
-  let timer = null; let cancelled = false;
+// Delivery del bootstrap prompt per generazione (0.8.47, R2/R3).
+//
+// OWNER UNICO: per gli engine managed Kimi (client 'kimi'/'claude') il
+// supervisore consegna il prompt per TUTTE le generazioni, gen0 compresa —
+// il runtime non esegue MAI paste/Enter per questi engine (legge solo l'esito
+// bounded via opzione di pane @nc_delivery). Cosi' non esiste doppio writer
+// cross-generation: se gen0 muore durante l'attesa readiness, la sua delivery
+// viene cancellata e attesa PRIMA dello spawn di gen1, che ricevera' al
+// massimo una nuova consegna. Engine custom send-keys: contratto legacy
+// invariato (gen0 = runtime.injectPrompt; qui solo gen>0, paste senza Enter).
+//
+// CANCELLAZIONE (R3): cancel() ferma il timer E il polling in volo tramite
+// isCancelled valutato dentro deliverBootstrapPrompt (ogni poll, pre-paste,
+// pre-Enter); il chiamante fa cancel() + await settled prima dello spawn
+// della generazione successiva: zero paste/Enter da un task della generazione
+// precedente.
+//
+// REPORT: esito pubblicato con set-option -p @nc_delivery '<state>[:notReady]'
+// (solo enum chiusi; l'opzione muore col pane, nessuno state file). Best
+// effort: un set-option fallito lascia up() in report-timeout (onesto), la
+// consegna resta fatta.
+// CANCELLAZIONE (R3+R8): cancel() ferma il timer E il polling in volo tramite
+// isCancelled valutato dentro deliverBootstrapPrompt (ogni poll, pre-paste,
+// pre-Enter, post-Enter); il chiamante fa cancel() + await settled prima dello
+// spawn della generazione successiva. cancel() con timer ANCORA PENDENTE
+// (child uscito prima di readyMs, caso early-exit) risolve settled SUBITO:
+// mai deadlock (R8). settled risolve con l'esito della delivery: null se
+// nessun paste incerto, {state} se la generazione e' terminata con un
+// post-paste incerto (delivery-unknown / staged-not-submitted) — il main loop
+// NON auto-restarta in quel caso (R9: byte potenzialmente residui nel PTY del
+// pane riusato; fermo bounded + restart operatore).
+function startGenerationPrompt(config, generation, childState, seams = {}) {
+  if (!config) return null;
+  const classified = config.client === 'kimi' || config.client === 'claude';
+  if (!classified && generation === 0) return null;  // legacy: gen0 resta al runtime
   const setTimer = seams.setTimeout || setTimeout;
   const clearTimer = seams.clearTimeout || clearTimeout;
+  const runTmux = seams.tmuxExec || ((bin, args, opts = {}) => new Promise((resolve) => {
+    require('node:child_process').execFile(bin, args, { env: opts.env, timeout: opts.timeoutMs || 10000 },
+      (err, stdout, stderr) => resolve({ err, stdout: String(stdout || ''), stderr: String(stderr || ''), code: err ? (typeof err.code === 'number' ? err.code : 1) : 0 }));
+  }));
+  const paneTarget = process.env.TMUX_PANE || `=${config.tmuxSession}`;
+  const markDelivery = async (value) => {
+    if (!classified) return;
+    try { await runTmux(config.tmuxBin, ['set-option', '-p', '-t', paneTarget, '@nc_delivery', value], {}); }
+    catch (_) { /* best-effort: il report timeout di up() resta onesto */ }
+  };
+  let timer = null; let cancelled = false;
+  let settledDone = false; let settleResolve = null;
+  const settled = new Promise((resolve) => { settleResolve = resolve; });
+  const settle = (value) => {
+    if (settledDone) return;
+    settledDone = true;
+    settleResolve(value);
+  };
+  const isCancelled = () => cancelled || childState.exited === true;
   timer = setTimer(async () => {
     timer = null;
-    if (cancelled || childState.exited) return;
-    try {
-      const inject = seams.injectPrompt || require('./launch.js').injectPrompt;
-      await inject(config.tmuxBin, config.tmuxSession, config.prompt, {
-        target: process.env.TMUX_PANE || `=${config.tmuxSession}`,
-        readyMs: 0,
-      });
-    } catch (_) { /* keepalive must not die because prompt reinjection failed */ }
+    if (isCancelled()) { settle(null); return; }
+    const task = (async () => {
+      try {
+        if (classified) {
+          await markDelivery('');
+          const deliver = seams.deliverBootstrapPrompt
+            || require('./prompt-delivery.js').deliverBootstrapPrompt;
+          const result = await deliver({
+            tmuxBin: config.tmuxBin,
+            session: config.tmuxSession,
+            prompt: config.prompt,
+            client: config.client,
+            paneTarget: process.env.TMUX_PANE || undefined,
+            readyWaitMs: config.readyWaitMs,
+            isCancelled,
+          });
+          const state = result && typeof result.state === 'string' ? result.state : '';
+          const uncertain = state === 'delivery-unknown' || state === 'staged-not-submitted';
+          if (isCancelled()) {
+            // R9: la generazione e' finita. Propago SOLO gli esiti post-paste
+            // incerti (residuo PTY possibile); cancelled pre-paste e' pulito.
+            return uncertain ? { state } : null;
+          }
+          if (state) {
+            const kind = state === 'skipped-not-ready' && result.notReady ? `:${result.notReady}` : '';
+            await markDelivery(`${state}${kind}`);
+          }
+          // R12: l'esito post-paste incerto va conservato ANCHE se il child
+          // era vivo al ritorno di deliver: i byte possono restare nel PTY del
+          // pane e sommarsi al bootstrap della generazione successiva. Al
+          // prossimo child exit il main ferma il supervisor (no auto-restart).
+          return uncertain ? { state } : null;
+        }
+        const inject = seams.injectPrompt || require('./launch.js').injectPrompt;
+        await inject(config.tmuxBin, config.tmuxSession, config.prompt, {
+          target: paneTarget,
+          readyMs: 0,
+        });
+        return null;
+      } catch (_) { return null; /* keepalive must not die because prompt reinjection failed */ }
+    })();
+    settle(await task);
   }, config.readyMs ?? 400);
   timer.unref?.();
-  return { cancel() { cancelled = true; if (timer) clearTimer(timer); timer = null; } };
+  return {
+    settled,
+    // R8: timer ancora pendente -> settle IMMEDIATO (idempotente): il main
+    // loop non resta mai appeso su un child uscito prima di readyMs.
+    cancel() {
+      cancelled = true;
+      if (timer) { clearTimer(timer); timer = null; settle(null); }
+    },
+  };
 }
 async function main(argv = process.argv.slice(2), seams = {}) {
@@ -195,13 +290,26 @@ async function main(argv = process.argv.slice(2), seams = {}) {
     for (;;) {
       if (stopping) return 0;
       const startedAt = now();
-      current = spawnImpl(payload.command, payload.args, { env: childEnv, stdio: 'inherit' });
       const childState = { exited: false };
-      const prompt = generation > 0 ? scheduleRestartPrompt(payload.restartPrompt, childState, seams) : null;
+      const promptCtl = startGenerationPrompt(payload.restartPrompt, generation, childState, seams);
+      current = spawnImpl(payload.command, payload.args, { env: childEnv, stdio: 'inherit' });
       const result = await waitChild(current);
       childState.exited = true;
-      prompt?.cancel();
       current = null;
+      // R2/R3: la generazione e' finita. Cancella la delivery in volo e ATTESA
+      // del suo termine PRIMA di qualunque nuovo spawn. R9: se l'esito e' un
+      // post-paste incerto (delivery-unknown / staged-not-submitted) i byte del
+      // prompt possono essere residui nel PTY del pane riusato: NIENTE auto-
+      // restart — fermo bounded del supervisor, restart esplicito operatore.
+      if (promptCtl) {
+        promptCtl.cancel();
+        const promptOutcome = await promptCtl.settled;
+        if (promptOutcome && (promptOutcome.state === 'delivery-unknown'
+          || promptOutcome.state === 'staged-not-submitted')) {
+          writeError('nexuscrew cell supervisor stopped: uncertain prompt delivery (operator restart required)\n');
+          return result.signal ? 128 : (result.code || 1);
+        }
+      }
       if (result.error) {
         writeError(`${sanitizeSpawnError(result.error, payload.command)}\n`);
         return 1;
@@ -246,5 +354,5 @@ if (require.main === module) {
 module.exports = {
   DEFAULT_SUPERVISE, parseArgs, validSupervise, validRestartPrompt, validPayload,
-  receivePayload, sanitizeSpawnError, normalizeSupervise, waitChild, scheduleRestartPrompt, main,
+  receivePayload, sanitizeSpawnError, normalizeSupervise, waitChild, startGenerationPrompt, main,
 };

package/lib/fleet/launch.js CHANGED Viewed

@@ -20,6 +20,7 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
+const crypto = require('node:crypto');
 const { execFile } = require('node:child_process');
 const { minimalRuntimeEnv } = require('../runtime/env.js');
 const { codeOf, phaseOf } = require('./causes.js');
@@ -355,34 +356,88 @@ async function waitStablePane(tmuxBin, target, { env, readyMs }) {
   }
 }
-// Iniezione prompt send-keys via bracketed paste (come skills/.../nc-send):
-// load-buffer del prompt in un buffer nominato + paste-buffer -p (bracketed),
-// poi cleanup. Readiness best-effort: se la sessione non e' viva quando paste-iamo
-// (command gia' uscito) NON digita (design §9e). Ritorna {injected, reason}.
+// Risolve il pane id (%N) esatto della sessione, o verifica un %N gia' noto.
+// Contratto submitToSession (R5): output session_name + pane_dead + pane_id,
+// parsing ESATTO per campi (mai regex %N libera), session verificata uguale
+// a quella attesa prima di qualunque paste/Enter. Ritorna null se il pane non
+// e' risolvibile, morto, di un'altra sessione o diverso dal %N atteso.
+async function resolveSessionPane(tmuxBin, session, { env, exec, target } = {}) {
+  const run = exec || tmuxExec;
+  const to = target || `=${session}`;
+  const r = await run(tmuxBin,
+    ['display-message', '-p', '-t', to, '#{session_name}\t#{pane_dead}\t#{pane_id}'],
+    { env, timeoutMs: 2000 });
+  if (r.err) return null;
+  const fields = r.stdout.trim().split('\t');
+  if (fields.length !== 3) return null;
+  const [sess, dead, pane] = fields;
+  if (dead !== '0') return null;                     // morto o non bounded
+  if (!/^%[0-9]+$/.test(pane)) return null;
+  if (typeof session === 'string' && session && sess !== session) return null;
+  if (target && target.startsWith('%') && pane !== target) return null;
+  return pane;
+}
+// Stadio sicuro del testo nel composer del TUI (0.8.47): temp file wx/0600 con
+// nome random + buffer tmux random per invio + bracketed paste sul %N esatto
+// risolto subito prima. NESSUN Enter: la sottomissione e' una decisione
+// separata del chiamante (solo deliverBootstrapPrompt, per kimi.native e
+// claude.kimi-code). Niente buffer condiviso 'ncsend': due celle concorrenti
+// non possono piu' sovrascriversi il buffer a vicenda.
+// Ritorna { ok, stage, paneId?, reason } con reason costante (mai stderr/pane).
+async function securePaste(tmuxBin, session, text, { env, exec, tmpdir, target, fsImpl } = {}) {
+  const run = exec || tmuxExec;
+  const fsx = fsImpl || fs;
+  if (!promptCharsOk(text)) {
+    return { ok: false, stage: 'validate', reason: 'prompt contiene byte di controllo (rifiutato)' };
+  }
+  const paneId = await resolveSessionPane(tmuxBin, session, { env, exec: run, target });
+  if (!paneId) return { ok: false, stage: 'resolve', reason: 'pane non risolvibile' };
+  const nonce = crypto.randomBytes(8).toString('hex');
+  const buffer = `ncstage-${nonce}`;
+  const tmp = path.join(tmpdir || os.tmpdir(), `.ncstage-${process.pid}-${nonce}.txt`);
+  let loaded = false;
+  try {
+    fsx.writeFileSync(tmp, text, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    try { fsx.chmodSync(tmp, 0o600); } catch (_) { /* best-effort */ }
+    const load = await run(tmuxBin, ['load-buffer', '-b', buffer, tmp], { env });
+    if (load.err) return { ok: false, stage: 'load', reason: 'buffer non disponibile' };
+    loaded = true;
+    // R4: da qui in poi il paste e' stato TENTATO: qualunque throw/rejection
+    // dell'executor e' post-paste (stage 'paste'), mai classificato come
+    // pre-paste 'load' — il composer potrebbe contenere testo parziale o
+    // completo e un retry duplicherebbe il prompt (G1).
+    try {
+      const paste = await run(tmuxBin, ['paste-buffer', '-p', '-t', paneId, '-b', buffer], { env });
+      if (paste.err) return { ok: false, stage: 'paste', reason: 'paste-buffer failed' };
+      return { ok: true, stage: 'pasted', paneId };
+    } catch (_) {
+      return { ok: false, stage: 'paste', reason: 'paste-buffer failed' };
+    }
+  } catch (_) {
+    return { ok: false, stage: 'load', reason: 'buffer non disponibile' };
+  } finally {
+    try { fsx.unlinkSync(tmp); } catch (_) { /* best-effort */ }
+    if (loaded) { try { await run(tmuxBin, ['delete-buffer', '-b', buffer], { env }); } catch (_) { /* best-effort */ } }
+  }
+}
+// Iniezione prompt send-keys via bracketed paste (contratto legacy per engine
+// custom promptMode 'send-keys': paste SENZA Enter, invariato — 0.8.47 G4).
+// Readiness best-effort: se la sessione non e' viva quando paste-iamo (command
+// gia' uscito) NON digita (design §9e). Ritorna {injected, reason}.
+// Trasporto backportato su securePaste: buffer random, temp wx/0600, pane %N.
 async function injectPrompt(tmuxBin, session, prompt, { env, readyMs = 400, target, engine, cell } = {}) {
   if (!promptCharsOk(prompt)) {
     return { injected: false, reason: 'prompt contiene byte di controllo (rifiutato)' };
   }
-  let tmp = null;
-  try {
-    tmp = path.join(os.tmpdir(), `.ncsend.${session}.${process.pid}.txt`);
-    fs.writeFileSync(tmp, prompt, { mode: 0o600 });
-    fs.chmodSync(tmp, 0o600);
-    const alive = await waitAlive(tmuxBin, session, { env, readyMs });
-    if (!alive) return { injected: false, reason: 'sessione non viva (command uscito?): nessuna digitazione' };
-    // Target esatto: pane id (%N) se disponibile, altrimenti '=sessione' (match
-    // esatto, mai prefix-match) — audit impl #5.
-    const to = target || `=${session}`;
-    await tmuxExec(tmuxBin, ['load-buffer', '-b', 'ncsend', tmp], { env });
-    const paste = await tmuxExec(tmuxBin, ['paste-buffer', '-p', '-t', to, '-b', 'ncsend'], { env });
-    if (paste.err) return { injected: false, reason: redactSecrets(`paste-buffer failed: ${paste.stderr.trim()}`, engine, cell) };
-    return { injected: true, reason: 'bracketed paste (load-buffer + paste-buffer -p)' };
-  } finally {
-    try { if (tmp) fs.unlinkSync(tmp); } catch (_) { /* best-effort */ }
-    try { await tmuxExec(tmuxBin, ['delete-buffer', '-b', 'ncsend'], { env }); } catch (_) { /* best-effort */ }
+  const alive = await waitAlive(tmuxBin, session, { env, readyMs });
+  if (!alive) return { injected: false, reason: 'sessione non viva (command uscito?): nessuna digitazione' };
+  const stage = await securePaste(tmuxBin, session, prompt, { env, target });
+  if (!stage.ok) {
+    return { injected: false, reason: redactSecrets(stage.reason, engine, cell) };
   }
+  return { injected: true, reason: 'bracketed paste (load-buffer + paste-buffer -p)' };
 }
 module.exports = {
@@ -400,6 +455,8 @@ module.exports = {
   waitAlive,
   waitStablePane,
   injectPrompt,
+  resolveSessionPane,
+  securePaste,
   redactSecrets,
   sanitizeEarlyDiagnostic,
 };

package/lib/fleet/managed.js CHANGED Viewed

@@ -921,7 +921,15 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
     // TUI interattivo nella cwd della cella.
     if (model) args.push('--model', model);
   }
-  if (spec.client !== 'shell' && spec.client !== 'kimi' && cell?.prompt) args.push(cell.prompt);
+  // Prompt su argv (0.8.47): SOLO i client che non hanno un percorso classified
+  // delivery. kimi.native e claude.kimi-code usano promptMode 'send-keys' con
+  // deliverBootstrapPrompt (readiness classificata + at-most-once): il prompt
+  // NON deve mai comparire nel loro argv (visibile in ps / perso dietro
+  // consenso/onboarding). Gli altri managed conservano il contratto argv
+  // (finding separato, fuori da questa patch).
+  const promptViaDelivery = spec.client === 'kimi'
+    || (spec.client === 'claude' && spec.provider === 'kimi-code');
+  if (spec.client !== 'shell' && !promptViaDelivery && cell?.prompt) args.push(cell.prompt);
   // nexuscrew-store source: neutralize the profile's env set in the composed
   // child env (unset, never empty), so the runtime cannot leak credentials that
   // the local store is meant to own.
@@ -933,7 +941,7 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
   }
   return { ok: true, info, engine: {
     ...engine, command, args, env,
-    promptMode: spec.client === 'kimi' ? 'send-keys' : 'managed-argv', clientBinary: info.binary,
+    promptMode: promptViaDelivery ? 'send-keys' : 'managed-argv', clientBinary: info.binary,
     ...(spec.client === 'shell' ? { shellOneShot } : {}),
   } };
 }

package/lib/fleet/prompt-delivery.js ADDED Viewed

@@ -0,0 +1,275 @@
+'use strict';
+// Delivery del bootstrap prompt per gli engine managed Kimi (kimi.native e
+// claude.kimi-code) — NexusCrew 0.8.47. SOLO questi due engine: gli altri
+// managed conservano il prompt su argv (finding separato) e i custom send-keys
+// conservano injectPrompt legacy senza Enter.
+//
+// Contratto (design audit 0.8.47):
+//  - Readiness REALE prima della consegna: il pane viene classificato sul SOLO
+//    viewport visibile (capture-pane -p, mai scrollback -S: su generation>0 lo
+//    scrollback puo' contenere vecchi prompt e marker stale). Auth, consenso
+//    custom API key e onboarding/trust sono NOT_READY: nessun paste, nessun
+//    Enter, la sessione resta viva e utilizzabile dall'operatore. UNKNOWN a
+//    timeout NON diventa mai READY: la consegna viene saltata.
+//  - AT-MOST-ONCE per generazione: UNA sola sequenza paste+Enter. Retry
+//    automatico ammesso SOLO su fallimento certo PRE-paste (resolve pane o
+//    load-buffer falliti): mai un secondo paste — dopo QUALUNQUE tentativo di
+//    paste-buffer il composer potrebbe contenere testo parziale/completo e lo
+//    stato e' DELIVERY_UNKNOWN/STAGED_NOT_SUBMITTED con zero secondo paste.
+//    Dopo un Enter OK l'esito e' 'submitted' e non esiste replay.
+//  - Classifier enum-only: il testo catturato non viene MAI loggato,
+//    persistito o incluso in risposte; esce solo lo stato bounded.
+//  - Recovery da catalogo costante; mai suggerire /login Anthropic per
+//    claude.kimi-code (il recovery corretto e' il consenso Kimi in /config).
+const { tmuxExec, securePaste, resolveSessionPane, promptCharsOk, sleep } = require('./launch.js');
+// Stati bounded del classifier pane. Output unico esposto all'esterno.
+const PANE_STATES = Object.freeze([
+  'ready', 'busy', 'not-ready-auth', 'not-ready-consent', 'not-ready-onboarding', 'unknown',
+]);
+// Esiti bounded della consegna (prompt.reason in API: closed enum, G5).
+const DELIVERY_STATES = Object.freeze([
+  'submitted',             // paste ok + pane riverificato + Enter ok
+  'staged-not-submitted',  // paste ok, Enter fallito: testo forse nel composer
+  'delivery-unknown',      // paste tentato con esito incerto / pane sparito dopo il paste
+  'failed-pre-paste',      // resolve/load certamente falliti (anche dopo 1 retry)
+  'skipped-not-ready',     // classifier not-ready a fine attesa bounded (kind in notReady)
+  'skipped-unknown',       // classifier mai ready entro il timeout
+  'prompt-rejected',       // byte di controllo nel prompt (policy §9e)
+  'cancelled',             // generazione terminata durante l'attesa/consegna (R3)
+  'report-timeout',        // up() non ha ricevuto l'esito del launcher entro il bound
+]);
+// Codici bounded actionRequired (G5). Nessuna inferenza "rifiutato": il marker
+// TUI prova solo che serve un'azione nel terminale della cella.
+const ACTION_CODES = Object.freeze(['KIMI_AUTH_ACTION_REQUIRED', 'CLIENT_INTERACTION_REQUIRED']);
+// Slug recovery bounded (R10): l'API trasporta SOLO {code, recovery}; il testo
+// e' mappato localmente dalla PWA via i18n (fleet-recovery-<slug>), mai inviato
+// dal server (un nodo remoto federato non deve poter iniettare testo libero).
+const RECOVERY_SLUGS = Object.freeze([
+  'kimi-code-consent-yes',
+  'kimi-code-config-custom-api-key',
+  'kimi-cli-login',
+  'client-terminal-dialog',
+]);
+// Marker di dialoghi MODALI full-screen: occupano la viewport, valgono su
+// tutto il catturato visibile (non solo la coda).
+// Live-verificati: claude 2.1.220 (consent custom API key, trust dialog).
+const MODAL_NOT_READY = Object.freeze([
+  ['not-ready-consent', /Detected a custom API key in your environment|Do you want to use this API key\?/],
+  ['not-ready-onboarding', /Yes, I trust this folder|Quick safety check/],
+]);
+// Marker ancorati alla CODA visibile (status bar / righe finali): lo stesso
+// testo in scrollback, nel corpo conversazione o in forma diversa non deve
+// classificare (R7: il marker auth e' la stringa ESATTA di status bar, non un
+// "Not logged in" qualunque). Live-verificati: claude 2.1.220 (status bar
+// "Not logged in · Run /login"), kimi 0.31.1 (welcome "Run /login or
+// /provider", "Model: not set").
+const TAIL_NOT_READY = Object.freeze([
+  ['not-ready-auth', /Not logged in · (?:Please run|Run) \/login\b/],
+  ['not-ready-auth', /Run \/login or \/provider|Model:\s+not set\b/],
+]);
+// TUI occupata a processare (restart durante lavoro residuo): si attende.
+const BUSY_TAIL = /esc to interrupt/i;
+const TAIL_LINES = 14;
+function tailOf(text) {
+  const lines = String(text).split('\n');
+  const nonEmpty = [];
+  for (let i = lines.length - 1; i >= 0 && nonEmpty.length < TAIL_LINES; i -= 1) {
+    if (lines[i].trim() !== '') nonEmpty.unshift(lines[i]);
+  }
+  return nonEmpty.join('\n');
+}
+// classifyPane(captured, client) -> PANE_STATES enum. Pura, senza dipendenze:
+// il testo resta dentro la funzione, fuori esce solo lo stato bounded.
+// client: 'kimi' | 'claude' (gli altri non passano mai di qui: 'unknown').
+function classifyPane(captured, client) {
+  const text = typeof captured === 'string' ? captured : '';
+  if (!text.trim()) return 'unknown';
+  for (const [state, re] of MODAL_NOT_READY) if (re.test(text)) return state;
+  const tail = tailOf(text);
+  for (const [state, re] of TAIL_NOT_READY) if (re.test(tail)) return state;
+  if (BUSY_TAIL.test(tail)) return 'busy';
+  if (client === 'kimi') {
+    // READY positivo Kimi: box di input corrente E modello configurato (G2).
+    // Il solo "Model:" non basta; la sola box non basta (presente anche da
+    // logged-out). Il welcome logged-out e' gia' intercettato dai marker
+    // not-ready qui sopra; se scrolla via senza login resta 'unknown' (safe).
+    const box = /^\s*│\s*>/m.test(text);
+    const model = /! to run a shell command/.test(tail) || /Model:\s+(?!not set\b)\S/.test(text);
+    return box && model ? 'ready' : 'unknown';
+  }
+  if (client === 'claude') {
+    // READY positivo Claude: riga prompt "❯" in coda, assenza dei marker
+    // not-ready (gia' valutati sopra: il cursore ❯ dei dialoghi non inganna).
+    return /^\s*❯/m.test(tail) ? 'ready' : 'unknown';
+  }
+  return 'unknown';
+}
+function clampInt(value, dflt, min, max) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return dflt;
+  return Math.max(min, Math.min(max, Math.trunc(n)));
+}
+// deliverBootstrapPrompt(opts) -> { delivered, state, notReady, attempts, reason }
+//   opts: { tmuxBin, session, prompt, client ('kimi'|'claude'), env,
+//           paneTarget (%N opzionale), readyWaitMs, pollMs, settleMs, tmpdir,
+//           tmuxExecImpl, captureImpl, sleepImpl, nowImpl, fsImpl, isCancelled }
+// reason e' SEMPRE lo state (closed enum); notReady e' il kind bounded o ''.
+// isCancelled() (R3): valutato ad OGNI poll, prima del paste e prima dell'
+// Enter; se true la consegna si ferma subito ('cancelled') senza paste/Enter —
+// cell-exec cancella la delivery quando la generazione termina, cosi' un
+// polling in volo non puo' mai iniettare nella generazione successiva.
+async function deliverBootstrapPrompt(opts = {}) {
+  const { tmuxBin, session, prompt } = opts;
+  const client = typeof opts.client === 'string' ? opts.client : '';
+  const env = opts.env;
+  const exec = opts.tmuxExecImpl || tmuxExec;
+  const sleepImpl = opts.sleepImpl || sleep;
+  const now = opts.nowImpl || Date.now;
+  const cancelled = typeof opts.isCancelled === 'function' ? opts.isCancelled : () => false;
+  const target = opts.paneTarget || `=${session}`;
+  const readyWaitMs = clampInt(opts.readyWaitMs, 15000, 0, 120000);
+  const pollMs = clampInt(opts.pollMs, 400, 50, 5000);
+  const settleMs = clampInt(opts.settleMs, 150, 0, 5000);
+  const done = (delivered, state, notReady, attempts) => ({
+    delivered, state, notReady, attempts, reason: state,
+  });
+  if (!promptCharsOk(prompt)) return done(false, 'prompt-rejected', '', 0);
+  const capture = opts.captureImpl || (async () => {
+    const r = await exec(tmuxBin, ['capture-pane', '-p', '-t', target], { env, timeoutMs: 2000 });
+    return r.err ? null : r.stdout;
+  });
+  // (1) Attesa readiness bounded: solo 'ready' positivo sblocca la consegna.
+  let paneState = 'unknown';
+  const deadline = now() + readyWaitMs;
+  for (;;) {
+    if (cancelled()) return done(false, 'cancelled', '', 0);
+    const text = await capture();
+    if (cancelled()) return done(false, 'cancelled', '', 0);
+    paneState = text === null ? 'unknown' : classifyPane(text, client);
+    if (paneState === 'ready') break;
+    if (now() >= deadline) {
+      return paneState === 'unknown'
+        ? done(false, 'skipped-unknown', '', 0)
+        : done(false, 'skipped-not-ready', paneState, 0);
+    }
+    await sleepImpl(pollMs);
+  }
+  // (2) Consegna AT-MOST-ONCE: un solo paste per generazione. Il retry copre
+  // SOLO fallimenti certi pre-paste (resolve/load); dopo qualsiasi tentativo
+  // di paste-buffer non esiste retry automatico (G1).
+  let attempts = 0;
+  for (;;) {
+    if (cancelled()) return done(false, 'cancelled', '', attempts);
+    attempts += 1;
+    const stage = await securePaste(tmuxBin, session, prompt, {
+      env, exec, target, tmpdir: opts.tmpdir, fsImpl: opts.fsImpl,
+    });
+    if (cancelled()) {
+      // Il paste potrebbe essere avvenuto: mai riprovare, mai Enter.
+      return done(false, stage.ok ? 'delivery-unknown' : 'cancelled', '', attempts);
+    }
+    if (stage.ok) {
+      await sleepImpl(settleMs);
+      if (cancelled()) return done(false, 'delivery-unknown', '', attempts);
+      // Riverifica dello stesso %N sulla stessa sessione prima dell'Enter.
+      const paneAgain = await resolveSessionPane(tmuxBin, session, { env, exec, target });
+      if (paneAgain !== stage.paneId) return done(false, 'delivery-unknown', '', attempts);
+      if (cancelled()) return done(false, 'delivery-unknown', '', attempts);
+      const enter = await exec(tmuxBin, ['send-keys', '-t', stage.paneId, 'Enter'], { env });
+      if (enter.err) return done(false, 'staged-not-submitted', '', attempts);
+      // R9: cancel con Enter appena partito -> la generazione e' morta con un
+      // submit in volo: esito incerto (residuo PTY possibile), mai 'submitted'.
+      if (cancelled()) return done(false, 'delivery-unknown', '', attempts);
+      return done(true, 'submitted', '', attempts);
+    }
+    if (stage.stage === 'paste' || stage.stage === 'validate') {
+      // Paste tentato (esito incerto) o input rifiutato: zero secondo paste.
+      return done(false, stage.stage === 'validate' ? 'prompt-rejected' : 'delivery-unknown', '', attempts);
+    }
+    if (attempts >= 2) return done(false, 'failed-pre-paste', '', attempts);
+    // Fallimento certo PRE-paste: un solo retry, readiness riverificata prima.
+    await sleepImpl(pollMs);
+    if (cancelled()) return done(false, 'cancelled', '', attempts);
+    const text = await capture();
+    const again = text === null ? 'unknown' : classifyPane(text, client);
+    if (again !== 'ready') return done(false, 'failed-pre-paste', '', attempts);
+  }
+}
+// waitDeliveryReport(tmuxBin, target, opts) -> delivery-like | null (R2).
+// Il launcher supervisionato (cell-exec) e' l'UNICO owner della consegna per
+// TUTTE le generazioni degli engine Kimi e pubblica l'esito bounded sull'
+// opzione tmux di pane @nc_delivery ('<state>' o '<state>:<notReady>', solo
+// enum chiusi; muore col pane, nessuno state file). up() la legge con attesa
+// bounded: niente paste dal runtime, niente doppio writer cross-generation.
+async function waitDeliveryReport(tmuxBin, target, { env, exec, sleepImpl, nowImpl, timeoutMs, pollMs } = {}) {
+  const run = exec || tmuxExec;
+  const sleepFn = sleepImpl || sleep;
+  const now = nowImpl || Date.now;
+  const deadline = now() + clampInt(timeoutMs, 18000, 100, 150000);
+  const step = clampInt(pollMs, 300, 50, 5000);
+  for (;;) {
+    const r = await run(tmuxBin,
+      ['display-message', '-p', '-t', target, '#{@nc_delivery}'],
+      { env, timeoutMs: 2000 });
+    const raw = r.err ? '' : r.stdout.trim();
+    if (raw) {
+      const [state, notReady = ''] = raw.split(':');
+      if (!DELIVERY_STATES.includes(state)) return null;   // valore non bounded: mai fidarsi
+      const kind = PANE_STATES.includes(notReady) ? notReady : '';
+      return {
+        delivered: state === 'submitted',
+        state, notReady: state === 'skipped-not-ready' ? kind : '',
+        attempts: 0, reason: state,
+      };
+    }
+    if (now() >= deadline) return null;
+    await sleepFn(step);
+  }
+}
+// actionRequiredFor(client, provider, delivery) -> null | { code, recovery }
+// Mappa bounded delivery -> azione operatore. Solo skip per not-ready/unknown
+// producono actionRequired; i fallimenti di trasporto restano nel prompt.state.
+// R10: SOLO {code, recovery} closed enum/slug — il testo e' i18n locale PWA.
+function actionRequiredFor(client, provider, delivery) {
+  if (!delivery || delivery.delivered) return null;
+  if (delivery.state !== 'skipped-not-ready' && delivery.state !== 'skipped-unknown') return null;
+  const kind = delivery.notReady;
+  let recovery = 'client-terminal-dialog';
+  let code = 'CLIENT_INTERACTION_REQUIRED';
+  if (provider === 'kimi-code') {
+    code = kind === 'not-ready-consent' || kind === 'not-ready-auth'
+      ? 'KIMI_AUTH_ACTION_REQUIRED' : 'CLIENT_INTERACTION_REQUIRED';
+    recovery = kind === 'not-ready-consent' ? 'kimi-code-consent-yes'
+      : kind === 'not-ready-auth' ? 'kimi-code-config-custom-api-key'
+        : 'client-terminal-dialog';
+  } else if (client === 'kimi') {
+    if (kind === 'not-ready-auth') {
+      code = 'KIMI_AUTH_ACTION_REQUIRED';
+      recovery = 'kimi-cli-login';
+    }
+  }
+  if (!ACTION_CODES.includes(code) || !RECOVERY_SLUGS.includes(recovery)) return null;
+  return { code, recovery };
+}
+module.exports = {
+  PANE_STATES, DELIVERY_STATES, ACTION_CODES, RECOVERY_SLUGS,
+  classifyPane, deliverBootstrapPrompt, waitDeliveryReport, actionRequiredFor,
+};