@mmmbuto/nexuscrew 0.9.12 → 0.9.13

package/lib/fleet/managed.js

@@ -152,16 +152,26 @@ const ALIBABA_PI_MODELS = Object.freeze([
 //    Il catalogo live li pubblicizza comunque; qui non entrano.
 //  - grok-4.5 solo su Responses: su Chat risponde 503 e Messages lo rifiuta
 //    esplicitamente ("not supported for format anthropic").
+//  - deepseek-v4-flash-vision-exp: MISURATO 2026-08-24 sul gateway
+//    opencode.ai/zen/go -> 200 su tutti e tre i wire (Responses
+//    status=completed, Messages stop_reason=end_turn, Chat finish_reason=stop).
+//    E' l'unico id di questo provider che accetta IMMAGINI, quindi la misura
+//    che conta non e' il 200: e' stata fatta mandando un PNG e chiedendo il
+//    colore, due volte con due colori diversi (rosso -> "Rosso", verde ->
+//    "verde") e su tutte e tre le wire. Un solo colore non avrebbe distinto
+//    "ha visto l'immagine" da "ha indovinato". Formati immagine per wire:
+//    Messages `source.base64`, Chat `image_url` data URI, Responses
+//    `input_image`.
 const OPENCODE_GO_MESSAGES_MODELS = Object.freeze([
-  'deepseek-v4-flash', 'deepseek-v4-pro', 'glm-5.2', 'glm-5.1', 'glm-5',
+  'deepseek-v4-flash', 'deepseek-v4-flash-vision-exp', 'deepseek-v4-pro', 'glm-5.2', 'glm-5.1', 'glm-5',
   'minimax-m3', 'minimax-m2.7', 'minimax-m2.5',
   'qwen3.8-max', 'qwen3.7-max', 'qwen3.7-plus', 'qwen3.6-plus', 'qwen3.5-plus',
 ]);
 const OPENCODE_GO_RESPONSES_MODELS = Object.freeze([
-  'deepseek-v4-flash', 'deepseek-v4-pro', 'gpt-5.6-luna', 'grok-4.5', 'glm-5.2', 'glm-5.1', 'glm-5',
+  'deepseek-v4-flash', 'deepseek-v4-flash-vision-exp', 'deepseek-v4-pro', 'gpt-5.6-luna', 'grok-4.5', 'glm-5.2', 'glm-5.1', 'glm-5',
 ]);
 const OPENCODE_GO_CHAT_MODELS = Object.freeze([
-  'deepseek-v4-flash', 'deepseek-v4-pro', 'glm-5.2', 'glm-5.1', 'glm-5',
+  'deepseek-v4-flash', 'deepseek-v4-flash-vision-exp', 'deepseek-v4-pro', 'glm-5.2', 'glm-5.1', 'glm-5',
   'kimi-k3', 'kimi-k2.7-code', 'kimi-k2.6', 'kimi-k2.5',
   'minimax-m3', 'minimax-m2.7', 'minimax-m2.5',
   'qwen3.8-max', 'qwen3.7-max', 'qwen3.7-plus', 'qwen3.6-plus', 'qwen3.5-plus',
@@ -181,6 +191,7 @@ const OPENCODE_GO_API_BASE = 'https://opencode.ai/zen/go/v1';
 // come se ne avesse meno, il sospetto va qui prima che sul client.
 const OPENCODE_GO_LIMITS = Object.freeze({
   'deepseek-v4-flash': { context: 1000000, output: 384000 },
+  'deepseek-v4-flash-vision-exp': { context: 1000000, output: 384000 },
   'deepseek-v4-pro': { context: 1000000, output: 384000 },
   'glm-5.2': { context: 1000000, output: 131072 },
   'glm-5.1': { context: 202752, output: 32768 },
@@ -214,12 +225,17 @@ function opencodeGoContextFor(model) {
 // quindi e' riuso di una dichiarazione esistente. Sugli altri non c'e'
 // precedente e non si estrapola.
 const OPENCODE_GO_PI_COMPAT = Object.freeze(['glm-5.2', 'deepseek-v4-pro']);
+// Gli id di questo provider che accettano immagini. Vive qui e non dentro il
+// map perche' la stessa domanda la fa anche il catalogo JSON
+// (`input_modalities`): due copie che divergono in silenzio sarebbero una cella
+// che dichiara di vedere e un client che non gli manda mai un'immagine.
+const OPENCODE_GO_VISION = Object.freeze(new Set(['deepseek-v4-flash-vision-exp']));
 const OPENCODE_GO_PI_MODELS = Object.freeze(OPENCODE_GO_CHAT_MODELS.map((id) => Object.freeze({
   id,
   name: id,
   api: 'openai-completions',
   reasoning: false,
-  input: ['text'],
+  input: OPENCODE_GO_VISION.has(id) ? ['text', 'image'] : ['text'],
   contextWindow: OPENCODE_GO_LIMITS[id].context,
   maxTokens: OPENCODE_GO_LIMITS[id].output,
   cost: ZERO_COST,
@@ -325,14 +341,32 @@ const CATALOG = Object.freeze([
   // default 'standard'; unsafe -> --always-approve (flag reale di `grok`).
   { id: 'grok.native', client: 'grok', provider: 'native', label: 'Grok account (CLI login)', auth: 'login', protocol: 'grok_native', core: true },
 
-  // VL/Vivling (repository `vl`): runtime TUI locale. Auth propria del
-  // runtime (default local Ollama, o VL_API_KEY/--profile in config.toml):
-  // NexusCrew non legge ne' copia credenziali (auth 'none'). Il CLI non ha flag
-  // prompt, --model ne' di approvazione (`vl [OPTIONS]`): lancia la TUI senza
-  // argomenti, standard-only. Backfill idempotente pattern Kimi (NESSUN platform
-  // gate: musl-friendly ovunque); binario assente -> describeManaged non
-  // configurato. Non e' un default seed; nessun remote-control (rc assente).
+  // VL/Vivling (repository `vl`): runtime TUI locale. Auth propria del runtime
+  // in OGNI variante (config.toml / VL_API_KEY): NexusCrew non legge ne' copia
+  // credenziali (auth 'none') — la chiave, dove serve, sale per NOME via
+  // envPassthrough (D3), mai come valore, mai su argv. vl.native e' «usa la tua
+  // configurazione»: NESSUNA env provider/base_url, perche' i default interni del
+  // runtime sono gia' openai-compat + localhost:11434 e le VL_* ambientali
+  // sovrascrivono il config.toml (comporle qui cancellerebbe default_profile in
+  // silenzio). Le varianti remote compongono SEMPRE la coppia: la' la variante
+  // e' la scelta. Il modello scelto nella UI viaggia via VL_MODEL, il prompt di
+  // cella via VL_SYSTEM_APPEND_FILE (gate 0.3.1); `vl --profile` esiste ma resta
+  // dell'operatore. Backfill idempotente pattern Kimi (NESSUN platform gate);
+  // standard-only in ogni variante. Non e' un default seed; nessun remote-control.
   { id: 'vl.native', client: 'vl', provider: 'native', label: 'VL', auth: 'none', protocol: 'vl_native', core: true },
+  // Destinazione unica e sensata: l'API Anthropic vera. La chiave sale per nome:
+  // chi non ha VL_API_KEY in nessuna credential source vede la cella rifiutarsi
+  // col motivo che la nomina, non partire muta. (Il runtime rifiuta da solo anche
+  // i subscription token, fail-closed sul backend nativo.)
+  { id: 'vl.anthropic', client: 'vl', provider: 'anthropic', label: 'Anthropic', auth: 'none', endpoint: 'https://api.anthropic.com', protocol: 'vl_native', vlProvider: 'anthropic', envPassthrough: ['VL_API_KEY'], core: true },
+  // Endpoint dichiarato dall'operatore. I protocolli sono ESATTAMENTE i tre
+  // provider che il runtime parla (anthropic | anthropic-bearer | openai-compat,
+  // vivling config/mod.rs): una voce che porti a un dialetto inesistente e'
+  // peggio che non averla. Per anthropic-bearer l'endpoint e' obbligatorio per
+  // costruzione (baseUrl del custom): un default spedirebbe un bearer token
+  // all'API vera di Anthropic. La chiave resta opt-in per nome (envPassthrough):
+  // un custom verso Ollama remoto senza auth non dichiara nulla.
+  { id: 'vl.custom', client: 'vl', provider: 'custom', label: 'Custom endpoint', auth: 'dynamic', protocol: 'openai-compat', protocols: ['anthropic', 'anthropic-bearer', 'openai-compat'], custom: true, core: true },
 
   // Pi usa i suoi provider ID reali direttamente. I provider OAuth non
   // richiedono env key.
@@ -408,6 +442,23 @@ function profileFor(client, provider, credentialProfile) {
     && (p.credentialProfile || '') === (credentialProfile || '')) || null;
 }
 
+// D3: validazione unica dell'allowlist envPassthrough (nomi, mai valori): la
+// usano sia la dichiarazione dell'operatore sia il default portato dal profilo
+// del catalogo, cosi' i due percorsi non possono divergere sui vincoli.
+function sanitizeEnvPassthrough(list) {
+  if (!Array.isArray(list) || !list.length || list.length > MAX_ENV_PASSTHROUGH) return null;
+  const seen = new Set();
+  const names = [];
+  for (const raw of list) {
+    if (typeof raw !== 'string') return null;
+    const name = raw.trim();
+    if (!ENV_KEY_RE.test(name) || seen.has(name)) return null;
+    seen.add(name);
+    names.push(name);
+  }
+  return names;
+}
+
 function normalizeManagedSpec(value, { extraModels = null } = {}) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
   if (Object.keys(value).some((k) => !MANAGED_KEYS.has(k))) return null;
@@ -467,9 +518,14 @@ function normalizeManagedSpec(value, { extraModels = null } = {}) {
     const providerId = typeof value.providerId === 'string' && value.providerId ? value.providerId : 'nexuscrew-custom';
     if (!displayName || displayName.length > 64 || /[\x00-\x1f\x7f]/.test(displayName)) return null;
     if (!validBaseUrl(baseUrl)) return null;
-    if (!ENV_KEY_RE.test(envKey) || !PROVIDER_ID_RE.test(providerId)) return null;
+    // vl: la chiave NON viaggia come envKey copiata dallo store (pattern degli
+    // altri client) ma per NOME via envPassthrough (D3) — un custom vl verso un
+    // endpoint senza auth (Ollama remoto) non dichiara nessuna chiave, quindi
+    // envKey vuota e' legittima solo per vl. Se dichiarata, resta un nome valido.
+    if (profile.client === 'vl' ? (envKey !== '' && !ENV_KEY_RE.test(envKey)) : !ENV_KEY_RE.test(envKey)) return null;
+    if (!PROVIDER_ID_RE.test(providerId)) return null;
     if (!model || !(profile.protocols || [profile.protocol]).includes(protocol)) return null;
-    Object.assign(out, { displayName, baseUrl, envKey, protocol, providerId });
+    Object.assign(out, { displayName, baseUrl, ...(envKey ? { envKey } : {}), protocol, providerId });
   }
   // D3: envPassthrough e' un'allowlist di NOMI di variabili d'ambiente che il
   // child deve ricevere, risolti a runtime dalle credentialSources (dopo i rami
@@ -479,17 +535,16 @@ function normalizeManagedSpec(value, { extraModels = null } = {}) {
   // le variabili che il suo runtime legge: il nome non e' fisso nel codice vl
   // (vivling/src/main.rs), quindi lo dichiara l'operatore che conosce la sua config.
   if (value.envPassthrough !== undefined) {
-    if (!Array.isArray(value.envPassthrough) || !value.envPassthrough.length
-      || value.envPassthrough.length > MAX_ENV_PASSTHROUGH) return null;
-    const seen = new Set();
-    const names = [];
-    for (const raw of value.envPassthrough) {
-      if (typeof raw !== 'string') return null;
-      const name = raw.trim();
-      if (!ENV_KEY_RE.test(name) || seen.has(name)) return null;
-      seen.add(name);
-      names.push(name);
-    }
+    const names = sanitizeEnvPassthrough(value.envPassthrough);
+    if (!names) return null;
+    out.envPassthrough = names;
+  } else if (Array.isArray(profile.envPassthrough) && profile.envPassthrough.length) {
+    // Il profilo puo' portare NOMI di default (es. vl.anthropic dichiara
+    // VL_API_KEY): la dichiarazione dell'operatore vince, e il default passa
+    // per la stessa validazione — una voce di catalogo malformata si rifiuta
+    // da sola invece di partire con nomi spurii.
+    const names = sanitizeEnvPassthrough(profile.envPassthrough);
+    if (!names) return null;
     out.envPassthrough = names;
   }
   return out;
@@ -990,7 +1045,12 @@ function describeManaged(spec, cfg = {}) {
   // not inspect or copy that store; delegate native-provider auth to Pi.
   const delegatedPiAuth = profile.client === 'pi' && profile.provider !== 'custom'
     && profile.delegatePiAuth !== false;
-  const authConfigured = delegatedPiAuth || profile.auth === 'login' || profile.auth === 'none' || !!cred.value;
+  // vl: l'autenticazione e' del runtime in OGNI variante (auth 'none', o chiave
+  // che sale per NOME via envPassthrough/D3 quando il profilo la dichiara). Il
+  // verdetto configured non puo' dipendere da una credenziale che NexusCrew non
+  // possiede: il fail-closed giusto e' quello del D3, che NOMINA il nome mancante.
+  const authConfigured = delegatedPiAuth || profile.auth === 'login' || profile.auth === 'none'
+    || profile.client === 'vl' || !!cred.value;
   let configured = !!binary && authConfigured;
   let reason;
   if (!binary) {
@@ -1750,21 +1810,42 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
     // TUI interattivo nella cwd della cella.
     if (model) args.push('--model', model);
   } else if (spec.client === 'vl') {
-    // VL/Vivling runtime TUI: auth e modello gestiti dal runtime (config.toml /
-    // env VL_*), niente credenziali su argv. `vl [OPTIONS]` non accetta ne'
-    // --model ne' un prompt: lancia la TUI senza argomenti nella cwd della cella.
-    // V-69 — il modello scelto nella UI smette di essere inerte: la tripletta
-    // VL_MODEL/VL_PROVIDER/VL_BASE_URL esiste nel runtime da sempre, quindi si
-    // compone senza gate appena un modello e' scelto. vl.native e' il profilo
-    // Ollama locale del catalogo: la coppia provider/base_url esplicita segue
-    // quella scelta (127.0.0.1 come gli altri profili ollama), cosi' il modello
-    // scelto finisce dove vive e non dove punta un eventuale profilo del
-    // config.toml dell'operatore. Senza modello NESSUNA env modello: chi usa il
-    // proprio config.toml continua a comandarlo lui, come oggi.
-    if (model) {
-      env.VL_MODEL = model;
-      env.VL_PROVIDER = 'openai-compat';
-      env.VL_BASE_URL = 'http://127.0.0.1:11434';
+    // VL/Vivling runtime TUI: auth gestita dal runtime in ogni variante
+    // (config.toml / VL_API_KEY per nome via envPassthrough, D3), mai
+    // credenziali su argv. Il modello scelto nella UI viaggia via VL_MODEL
+    // (V-69), il prompt di cella via file sul system del runtime
+    // (VL_SYSTEM_APPEND_FILE, gate qui sotto); `vl --profile` esiste ma resta
+    // dell'operatore. Nessun --model su argv: la TUI parte senza argomenti.
+    if (model) env.VL_MODEL = model;
+    // vl.native e' «usa la tua configurazione»: NESSUNA env provider/base_url.
+    // I default interni del runtime sono gia' openai-compat + localhost:11434,
+    // e le VL_* ambientali battono il config.toml — comporle qui non aggiunge
+    // nulla e cancella in silenzio default_profile. Le varianti remote invece
+    // compongono SEMPRE la coppia, anche senza modello: la' la variante e' la
+    // scelta, e un fallback silenzioso manderebbe la cella altrove mentre la
+    // UI dice il contrario.
+    if (spec.provider === 'custom') {
+      // il protocollo scelto nel custom E' il provider wire: il ramo custom di
+      // normalizeManagedSpec ha gia' garantito che sia uno dei tre che il
+      // runtime parla e che baseUrl esista (endpoint obbligatorio: un default
+      // su anthropic-bearer spedirebbe un bearer all'API vera di Anthropic).
+      env.VL_PROVIDER = spec.protocol;
+      env.VL_BASE_URL = spec.baseUrl;
+    } else if (spec.provider !== 'native') {
+      // Variante remota: la coppia e' obbligatoria, non condizionale. Un profilo
+      // senza vlProvider o endpoint non e' «un caso in cui non componiamo
+      // nulla»: e' uno stato impossibile del catalogo che, degradando, manderebbe
+      // la cella sui default interni (Ollama locale) mentre la UI dice il
+      // contrario. Si rifiuta NOMINANDO il campo che manca — stessa forma del
+      // fail-closed delle chiavi, che dice quale variabile manca, non «errore».
+      if (!profile.vlProvider) {
+        return { ok: false, info, reason: `vl profile ${profile.id}: campo vlProvider mancante — variante remota rifiutata invece di ricadere sui default locali in silenzio` };
+      }
+      if (!profile.endpoint) {
+        return { ok: false, info, reason: `vl profile ${profile.id}: campo endpoint mancante — variante remota rifiutata invece di ricadere sui default locali in silenzio` };
+      }
+      env.VL_PROVIDER = profile.vlProvider;
+      env.VL_BASE_URL = profile.endpoint;
     }
     // V-69 — prompt per-cella: file composto sul system del runtime
     // (VL_SYSTEM_APPEND_FILE). Il gate di versione sta nel codice, non nella

package/lib/mcp/server.js

@@ -67,10 +67,19 @@ function companionInstructions() {
 }
 
 // --- identita' cella mittente ------------------------------------------------
-// Ordine (design §1, INVARIATO): $TMUX presente -> `tmux display-message -p '#S'`
-// (nome sessione reale); se fallisce/invalida -> fallback env NEXUSCREW_MCP_SESSION;
-// altrimenti null. I tool che RICHIEDONO la sessione restano fail-closed.
-// execFile argv diretto: mai shell.
+// Ordine delle sorgenti (design §1, INVARIATO): $TMUX presente -> tmux
+// display-message (nome sessione reale); se fallisce/invalida -> fallback env
+// NEXUSCREW_MCP_SESSION; altrimenti null. I tool che RICHIEDONO la sessione
+// restano fail-closed. execFile argv diretto: mai shell.
+//
+// P0: il nome da tmux si chiede con `-t $TMUX_PANE` — target esplicito al
+// PANE del chiamante, deterministico e indipendente dall'environ ereditato.
+// Senza `-t` il CLI tmux risolve il pane dall'ENVIRON DEL PROCESSO FIGLIO:
+// se quel pane è vivo risponde correttamente, ma se è morto (environ stale,
+// l'incidente di partenza) ricade sul CLIENT ATTACHED attivo e risponde rc=0
+// col nome di quel client — attribuzione errata con sembianze di successo.
+// Comportamento misurato su tmux 3.4 con `-t`: pane morto -> rc=0 e stdout
+// VUOTO (non un errore): il vuoto è il segnale dello stantio.
 //
 // `resolveIdentity` rende OSSERVABILE la sorgente della risoluzione (P0):
 // ritorna { session, source, code, envPresence, requiredEnvVars, remediation }
@@ -114,25 +123,60 @@ function resolveIdentity({ env, tmuxBin, execFileImpl }) {
     session: null, source: 'missing', code: codeWhenMissing(),
     envPresence, requiredEnvVars: IDENTITY_REQUIRED_ENV_VARS, remediation: IDENTITY_REMEDIATION,
   });
+  // P0: pane stantio o non verificabile -> NON attribuire. source 'stale-pane'
+  // nomina il problema; code STALE_PANE (tools.js).
+  const stalePane = () => ({
+    session: null, source: 'stale-pane', code: IDENTITY_CODE.STALE_PANE,
+    envPresence, requiredEnvVars: IDENTITY_REQUIRED_ENV_VARS, remediation: IDENTITY_REMEDIATION,
+  });
+  // P0/R2: tmux e fallback env dicono sessioni DIVERSE entrambe valide:
+  // identità ambigua -> NON attribuire (nemmeno il fallback: è parte del
+  // conflitto). Il code nomina il mismatch, che INVALID non direbbe.
+  const sessionMismatch = () => ({
+    session: null, source: 'session-mismatch', code: IDENTITY_CODE.SESSION_MISMATCH,
+    envPresence, requiredEnvVars: IDENTITY_REQUIRED_ENV_VARS, remediation: IDENTITY_REMEDIATION,
+  });
 
   return new Promise((resolve) => {
-    if (!tmuxPresent) {
+    // Precedenza preservata: prima il fallback env valido, poi l'esito negativo
+    // dato (`missing` storico o `stalePane` P0).
+    const settle = (otherwise) => {
       const fb = tryFallback();
-      return resolve(typeof fb === 'string' ? ok(fb, 'NEXUSCREW_MCP_SESSION') : missing());
-    }
+      resolve(typeof fb === 'string' ? ok(fb, 'NEXUSCREW_MCP_SESSION') : otherwise());
+    };
+
+    if (!tmuxPresent) return settle(missing);
+
+    // Formato del pane id tmux: `%` + cifre. Un TMUX_PANE malformato non viene
+    // MAI spedito a tmux (argv diretto, ma niente pattern inattesi) e il pane
+    // resta non verificabile -> fail-closed.
+    const rawPane = typeof e.TMUX_PANE === 'string' ? e.TMUX_PANE.trim() : '';
+    const paneId = /^%\d+$/.test(rawPane) ? rawPane : null;
+    if (!paneId) return settle(stalePane);
+
     try {
-      execFileImpl(tmuxBin, ['display-message', '-p', '#S'], { timeout: 3000 }, (err, stdout) => {
-        if (!err) {
-          const name = String(stdout || '').trim();
-          if (isValidSession(name)) return resolve(ok(name, 'tmux'));
+      execFileImpl(tmuxBin, ['display-message', '-t', paneId, '-p', '#S'], { timeout: 3000 }, (err, stdout) => {
+        if (err) {
+          // tmux irraggiungibile/rotto (rc!=0): NON è il percorso dello stantio
+          // (un pane morto risponde rc=0, vedi header). Comportamento storico.
+          return settle(missing);
+        }
+        const name = String(stdout || '').trim();
+        // tmux 3.4, misura dell'audit (probe A1/A2): pane morto con -t ->
+        // rc=0 e stdout VUOTO. Il vuoto è il segnale dello stantio.
+        if (!name) return settle(stalePane);
+        if (isValidSession(name)) {
+          // R2: se il fallback env è valido ma dice un'altra sessione, le due
+          // fonti si contraddicono -> ambiguo, non si attribuisce.
+          const fb = tryFallback();
+          if (typeof fb === 'string' && fb !== name) return resolve(sessionMismatch());
+          return resolve(ok(name, 'tmux'));
         }
-        // tmux fallito/invalido -> precedenza preservata: fallback env.
-        const fb = tryFallback();
-        resolve(typeof fb === 'string' ? ok(fb, 'NEXUSCREW_MCP_SESSION') : missing());
+        // nome non vuoto ma invalido: precedenza preservata, come da design §1.
+        settle(missing);
       });
     } catch (_) {
-      const fb = tryFallback();
-      resolve(typeof fb === 'string' ? ok(fb, 'NEXUSCREW_MCP_SESSION') : missing());
+      settle(missing);
     }
   });
 }

package/lib/mcp/tools.js

@@ -38,6 +38,12 @@ const IDENTITY_CODE = Object.freeze({
   OK: 'OK',
   MISSING: 'NEXUSCREW_MCP_IDENTITY_MISSING',
   INVALID: 'NEXUSCREW_MCP_IDENTITY_INVALID',
+  // P0: il pane del chiamante non esiste più (o TMUX_PANE è assente/malformato):
+  // l'identità non viene attribuita via tmux.
+  STALE_PANE: 'NEXUSCREW_MCP_IDENTITY_STALE_PANE',
+  // P0/R2: tmux e NEXUSCREW_MCP_SESSION sono entrambi validi ma dicono sessioni
+  // diverse: identità ambigua, non si attribuisce nessuna delle due.
+  SESSION_MISMATCH: 'NEXUSCREW_MCP_IDENTITY_SESSION_MISMATCH',
 });
 
 // Remediation senza segreti/valori: nomi soltanto, compatibile con

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.9.12",
+  "version": "0.9.13",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {

package/skills/cellforge/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: cellforge
+description: Use when creating, changing, auditing or retiring a NexusCrew cell — an AI working identity with its own engine, prompt, workspace, memory and lifecycle documents. Covers first-run setup on a fresh install ("set up a cell for marketing", "add a research assistant", "I need a cell that does X"), changing an existing cell (engine, model, internal prompt, permissions, working directory), and auditing cells against the standard. Use it even when the request sounds like a small edit — a cell lives in three places at once, and changing one of them alone is the most common way to end up with a cell that half-exists.
+---
+
+# CellForge — build a cell that actually exists
+
+A **cell** is a stable working identity: a name, an engine, a working directory,
+an internal prompt, a memory namespace and a set of documents that survive
+restarts. It is not a process and not a chat window.
+
+The single most useful thing to know before touching anything:
+
+> **A cell lives in three places at once, and a cell that exists in only two of
+> them is broken in a way nothing reports.**
+
+| where | what lives there | who writes it |
+|---|---|---|
+| **Definition** | the runtime record: id, engine, model, working directory, internal prompt, permissions | the NexusCrew API — never the file by hand |
+| **Runtime workspace** | `~/NexusFiles/<session>/` — inbox, outbox, links to the cell's documents | the service, plus the cell itself |
+| **Canonical documents** | the cell's prompt, checkpoint and history | the cell, following its own protocol |
+
+Where the canonical documents live is an **install convention, not a product
+rule** — ask, do not assume a repository exists.
+
+Create only the definition and the cell boots into an empty identity with no
+memory of what it is for. Create only the documents and nothing runs. Both
+failures look like "it sort of works" for a while.
+
+## Before you build: ask, don't assume
+
+A cell is cheap to create and expensive to live with, because a vague one
+produces vague work forever. Four questions decide everything else, and you
+should ask them in the user's own terms rather than presenting a form:
+
+1. **What is this cell for?** One sentence a stranger could act on. "Marketing"
+   is a department, not a purpose; "drafts and reviews campaign copy, owns the
+   content calendar" is a purpose.
+2. **What does it own, and what is off-limits?** Ownership is what makes a cell
+   different from a chat: a directory, a repository, a domain of documents. The
+   off-limits half matters as much — it is what keeps two cells from fighting.
+3. **What must it never do without asking?** Publishing, sending, deleting,
+   deploying, spending. Write these down now; they become the part of the prompt
+   that protects the user later.
+4. **Does it work alone, or with a reviewer?** A cell that implements and audits
+   its own work will approve it. If the work needs a verdict, plan a second cell
+   whose independence is structural, not a promise.
+
+If the user cannot answer (1) crisply, that is the finding — help them sharpen it
+before creating anything. A cell created around a fuzzy purpose is the most
+expensive thing in this skill.
+
+Then propose the engine, the tools and the MCP servers **as a recommendation
+with reasons**, and let the user correct you. See `references/choosing.md` for
+how to match a purpose to an engine and a toolset without over-fitting to the
+roles that already exist on the install.
+
+## Building it
+
+Work in this order. Each step is verifiable, and the order exists so that a
+failure leaves a cell that plainly does not exist, rather than one that
+half-does.
+
+**0. Look before you build.** One call to the fleet status gives you the
+existing cells (so you do not collide), the engine ids you need to fill the
+definition, and the capabilities you actually have. `references/operations.md`
+has this and every other "how do I observe it" answer — read it first if you
+are about to touch a real install.
+
+1. **Write the documents first.** Ask where they should live if the install has
+   no convention yet, and prefer somewhere version-controlled: the checkpoint's
+   value comes from its history. The prompt and the checkpoint are the cell's
+   identity; the definition just launches it. Templates in `assets/`. Adapt
+   them — a template pasted unchanged is how you get twelve cells that all
+   describe themselves the same way.
+2. **Choose the id carefully — it is immutable**, and it will appear in the
+   workspace path, in the memory namespaces and in every reference from another
+   cell. Name the function, not the moment: `Marketing` outlives
+   `Marketing-Q4-launch`.
+3. **Create the definition through the API**, never by editing the definitions
+   file. The API validates, enforces caps, and refuses states the file format
+   would happily hold. `references/definition.md` has the schema, the fields
+   that are immutable after creation, and the exact endpoints.
+4. **Sort out its memory** — state and journal are two different mechanisms,
+   not two files (`references/lifecycle.md`). How a namespace comes into being
+   depends on the memory server, so confirm the cell can write and read back
+   rather than assuming a creation step exists.
+5. **Boot it, then verify it is the cell you meant**: right engine, right
+   working directory, **prompt actually delivered**. That last one cannot be
+   read off the definition — the field is present either way — so check it the
+   way `operations.md` describes for the engine's delivery mode.
+
+## Changing a cell that already exists
+
+Two fields are **immutable after creation**: the cell's `id` and its tmux
+session. Everything else is patchable, but the interesting failures are not
+about what is allowed — they are about what changes underneath:
+
+- **Changing the engine can silently change the prompt delivery.** Engines
+  differ in how the internal prompt reaches the cell (command-line flag versus
+  typed into the session). A prompt that worked may simply stop arriving.
+  Verify delivery after an engine change; do not assume it carried over.
+- **Changing the working directory changes which instructions the cell loads**,
+  because per-directory instruction files are picked up by location. A cell can
+  keep its name and quietly become a different worker.
+- **Editing the internal prompt does not touch the documents**, and editing the
+  documents does not touch the internal prompt. They are separate stores. When
+  a cell's purpose changes, both change — otherwise the cell is told one thing
+  at boot and another by its own canon.
+
+Apply changes one at a time and confirm each. A batch patch that fails partway
+leaves you guessing which half landed.
+
+## Auditing
+
+Audit answers one question: **does this cell exist completely, and does it match
+the standard?** Run through `references/audit.md`, which is written as checks
+with an expected observation rather than a list of virtues.
+
+Two rules make an audit worth running:
+
+- **Report before you repair.** Show the findings and the proposed fixes, and
+  apply them only when the user says so. An audit that silently fixes things
+  teaches the user that the audit is the thing that changes their system, and
+  they stop running it.
+- **A check you have never seen fail proves nothing.** If a check passes on
+  every cell you point it at, break one deliberately — on a throwaway cell —
+  and confirm the check goes red. Checks that cannot fail are decoration, and
+  they are worse than no check because they are believed.
+
+## Rules that protect the user
+
+- **Never put a secret in the internal prompt.** With flag-style delivery the
+  prompt becomes a command-line argument, and command lines are readable by
+  other processes belonging to the same user. Reference credentials by the name
+  of the mechanism that holds them; never by value.
+- **Confirm before anything outward-facing or hard to undo** — removing a cell,
+  stopping one that is mid-task, overwriting a checkpoint. Creating is cheap;
+  removing throws away the identity and the history attached to it.
+- **A cell's checkpoint belongs to that cell.** Do not write another cell's
+  checkpoint even to be helpful: the owner will overwrite it, and both of you
+  will believe a state that no longer holds.
+- **Prefer portable forms.** Where a definition can express a path relative to
+  the user's home directory, use it: absolute paths bind the cell to one machine
+  and quietly break when the definition is restored on another.
+- **The running system wins over any document, including this one.** Check the
+  live listing and the tool surface actually exposed before acting on what you
+  remember.
+
+## Reference material
+
+Read the file that matches what you are doing; they are written to be read one
+at a time.
+
+- `references/operations.md` — **how to look and how to act**: the read calls,
+  what capabilities mean and why they are discovered rather than granted, how to
+  verify prompt delivery, and which parts depend on the install rather than the
+  product. Read this one before touching a real system.
+- `references/anatomy.md` — the three places, what is a real file and what is a
+  link, and how to tell a complete cell from a half one.
+- `references/definition.md` — the definition schema, validation limits,
+  immutable fields, and the endpoints that write it.
+- `references/lifecycle.md` — prompt, checkpoint, history and memory: who
+  writes what, when, and the difference between durable state and a bounded
+  journal.
+- `references/choosing.md` — matching purpose to engine, tools and MCP servers,
+  including how to handle a role the install has never seen before.
+- `references/audit.md` — the checks, each with what you should observe.
+- `assets/` — starting templates for the internal prompt and the checkpoint.

package/skills/cellforge/assets/checkpoint.template.md

@@ -0,0 +1,79 @@
+# Checkpoint — starting template
+
+The checkpoint answers one question: **if this session ended right now, what
+would the next one need in order to continue?**
+
+That question decides what belongs here better than any rule. It is a resume
+point, not a diary — finished work, transcripts and long output belong in the
+archived history, which the tooling creates for you every time you replace this
+file.
+
+Keep the section order: a reader must find the current task, the evidence, the
+blockers and the next step in the same place every time.
+
+---
+
+```markdown
+# {{CELL_ID}} — ACTIVE WORK
+
+**Status:** {{OPEN | CLOSED}} — {{date, time}}. {{One line: what is true right now.}}
+**Updated:** {{date, time, timezone}}
+
+**Execution node:** {{host}} — {{device identity}}
+**Sole owner:** cell {{CELL_ID}}
+
+## History
+
+{{Generated by the tooling — links to archived snapshots. Do not hand-edit.}}
+
+## Current task
+
+{{The task still authorised and unfinished. "None" is a valid and useful
+answer — write it rather than leaving the section stale.}}
+
+## Current state
+
+{{The reality needed to resume: what was done, what was decided, what changed
+underneath. Keep only what is still true — this is the section that rots.}}
+
+## Current evidence
+
+{{Measurements, versions, commit ids, command output that a resuming session
+would otherwise have to re-derive. Prefer a value you produced over one you
+remember.}}
+
+## Blockers
+
+| | what | who decides |
+|---|---|---|
+| ⏸ | {{what is blocked, and precisely what unblocks it}} | {{owner of the decision}} |
+
+## Next step
+
+{{The single next action. If it is "wait", say what for and how you will know
+it arrived.}}
+```
+
+---
+
+## The three ways checkpoints go wrong
+
+**It becomes a diary.** Every session appends, nothing is ever removed, and
+eventually it is too long to read at startup — so nobody reads it, and the
+checkpoint stops working while still being dutifully updated. Cure: when you
+update, delete what is no longer true. The history keeps it.
+
+**It is closed when it should be open.** A crash, a restart, a device change or
+running out of context are interruptions, not completions. Closing after one of
+those tells the next session there is nothing to resume, and the work is lost
+quietly. Only verified completion closes a task.
+
+**It records the plan instead of the result.** "Applied the fix" and "the fix is
+verified" are different states, and only one of them is safe to resume from.
+Where they differ, write which one you are in.
+
+## Write it even when nothing happened
+
+A session that starts, checks, finds nothing to do and updates the timestamp has
+produced real information: the state was verified at a known moment. That is not
+the same as no one having looked.