wyrm-mcp 7.3.2 → 7.3.3

package/dist/handlers/session.js

@@ -1,40 +1,652 @@
-import{basename as X}from"path";import{createHash as Z}from"crypto";import{blockText as G}from"./types.js";import{TOOL_ANNOTATIONS as T}from"../tool-annotations.js";import{renderResult as x,withGlyph as O,cacheKeyFor as N}from"../render.js";import{computeStaleness as ee}from"../intelligence.js";import{ValidationError as te,asInt as se,asString as ne}from"../validate.js";import{sanitizeActorId as oe}from"./boundary.js";import{makeEstimator as ie}from"../token-budget.js";function J(e){return!e||!e.thread.trim()?null:`### \u{1F9F5} Where We Left Off _(the living thread \u2014 what we were working on and thinking about)_
-`+`_updated ${e.updated_at}${e.updated_by?" \xB7 "+e.updated_by:""} \xB7 ${e.turn_count} turn(s)_`+`
-
-`+e.thread.slice(-1800)}const re={tech_stack:"\u{1F6E0}\uFE0F Tech Stack",architecture:"\u{1F3D7}\uFE0F Architecture",constraint:"\u{1F6A7} Constraints",decision:"\u{1F4CB} Decisions",contact:"\u{1F464} Contacts",other:"\u{1F4CC} Other Facts"};function Q(e,t){let n=`### \u{1F4DA} Project Ground Truths _(treat as authoritative \u2014 do not infer or contradict)_
-`;const s=new Map;for(const o of e)s.has(o.category)||s.set(o.category,[]),s.get(o.category).push(o);for(const[o,i]of s){n+=`**${re[o]??o}:**
-`;for(const c of i){let p="";if(t){const u=ee(c);u!==null&&u>.7&&(p="[\u26A0\uFE0F STALE] ")}n+=`- ${p}**${c.key}:** ${c.value}${c.rationale?` _(${c.rationale})_`:""}
-`}}return n}const V=`
+/**
+ * Session domain — ToolSpec contract v2 (v7 F3 T026, hot-path extraction).
+ *
+ * wyrm_session_start / wyrm_session_update / wyrm_session_rehydrate /
+ * wyrm_session_prime, moved VERBATIM from the index.ts dispatch switch +
+ * buildAllTools(). The wyrm_session noun shim keeps routing action=start|
+ * update|rehydrate onto these names (registry checked before switch — zero
+ * shim changes), and wyrm_session_prime stays the first-class survivor.
+ *
+ * session_prime: the five 6.x sections (truths / scaffold / memory brief /
+ * quests / vault advisory) are now the canonical structured body
+ * (`sections[]` + the count fields the summary derives from); the text
+ * channel is the same joined brief. Section CONTENT is institutional 6.x
+ * prose built by the subsystems (incl. their emoji headers) — that is body
+ * DATA, not renderer decoration, so it is byte-identical to 6.x; only the
+ * summary line's brand glyph moved behind WYRM_FANCY (T019 policy).
+ *
+ * v7 F3 (T028) — FLEET MODE (spec FR-5, §7 criterion 8): when `run_id` is
+ * given, the FIRST prime of a (run_id, role) compiles a byte-stable
+ * role-sliced brief under a token budget (default 1,200; approx-4cpt, the
+ * token-budget.ts convention) and CAS-caches it in the run_briefs table
+ * (migration 23: INSERT OR IGNORE, then EVERY caller reads the row back), so
+ * 12 simultaneous primes — across processes — return the byte-identical
+ * cached prefix. Nondeterminism sources are pinned at compile time:
+ *   - NO staleness prefixes (computeStaleness reads Date.now());
+ *   - NO vault advisory section (vaultAdvisory reads host vault state);
+ *   - quest ordering carries an explicit `id` tiebreak;
+ *   - truth ordering is getCurrent's ORDER BY category, key (already stable).
+ * Sections beyond the budget are STUBBED as plain-text `wyrm://` references —
+ * the T034 resource layer will turn those into real resource links (the seam
+ * is the STUB_REFS map below); 7.0 deliberately ships them as text only.
+ *
+ * FEATHERWEIGHT opt #2 — DISTRIBUTE-ONCE (`for_spawn:true`, advances T038 in
+ * spirit: the role brief is RENDERED ONCE for OUT-OF-BAND delivery instead of
+ * being re-sent to every agent over the wire). The orchestrator primes one
+ * (run_id, role) with for_spawn:true and gets the brief back as clean
+ * embeddable markdown (`brief`, byte-EQUAL to the agent-side prime's
+ * content[0].text — same CAS compile, same primeTemplate render, just packaged
+ * for embedding) + a `brief_hash` + the (run_id, role) cache key. It embeds
+ * that brief in the spawn-prompt PREFIX of every same-role agent (where they
+ * genuinely share a cacheable prefix), so those agents never call prime — the
+ * cacheable share of the fleet's prime cost becomes NEVER-SENT bytes. A
+ * forgetful orchestrator that skips for_spawn degrades to today's per-agent
+ * prime against the SAME CAS row (the byte-stable fallback) — never below the
+ * S3 floor. for_spawn is purely additive: same compile, alternate envelope.
+ *
+ * @copyright 2026 Ghost Protocol (Pvt) Ltd.
+ * @license Proprietary — (c) 2026 Ghost Protocol (Pvt) Ltd. All rights reserved. See LICENSE.
+ */
+import { basename } from 'path';
+import { createHash } from 'crypto';
+import { blockText } from './types.js';
+import { TOOL_ANNOTATIONS } from '../tool-annotations.js';
+import { renderResult, withGlyph, cacheKeyFor } from '../render.js';
+import { computeStaleness } from '../intelligence.js';
+import { ValidationError, asInt, asString } from '../validate.js';
+import { sanitizeActorId } from './boundary.js';
+import { makeEstimator } from '../token-budget.js';
+/**
+ * The Continuity section — the living thread ("where we left off / what we were working on and
+ * thinking about"), restored FIRST so any fresh chat or surface (phone, Hermes, Ember, Gemini)
+ * re-opens warm. Returns null when there's no thread yet.
+ */
+function buildContinuitySectionText(c) {
+    if (!c || !c.thread.trim())
+        return null;
+    const meta = `_updated ${c.updated_at}${c.updated_by ? ' · ' + c.updated_by : ''} · ${c.turn_count} turn(s)_`;
+    return ('### 🧵 Where We Left Off _(the living thread — what we were working on and thinking about)_\n' +
+        meta +
+        '\n\n' +
+        c.thread.slice(-1800));
+}
+const CATEGORY_LABELS_SP = {
+    tech_stack: '🛠️ Tech Stack', architecture: '🏗️ Architecture',
+    constraint: '🚧 Constraints', decision: '📋 Decisions',
+    contact: '👤 Contacts', other: '📌 Other Facts',
+};
+/** Section 1 — ground truths. `includeStaleness:false` is the T028 fleet pin:
+ * computeStaleness() reads Date.now(), which would make the compiled brief
+ * time-dependent. Output is byte-identical to 6.x when true. */
+function buildTruthsSectionText(currentTruths, includeStaleness) {
+    let spTruthsText = '### 📚 Project Ground Truths _(treat as authoritative — do not infer or contradict)_\n';
+    const spByCategory = new Map();
+    for (const t of currentTruths) {
+        if (!spByCategory.has(t.category))
+            spByCategory.set(t.category, []);
+        spByCategory.get(t.category).push(t);
+    }
+    for (const [cat, items] of spByCategory) {
+        spTruthsText += `**${CATEGORY_LABELS_SP[cat] ?? cat}:**\n`;
+        for (const t of items) {
+            let stalePrefix = '';
+            if (includeStaleness) {
+                const staleness = computeStaleness(t);
+                if (staleness !== null && staleness > 0.7)
+                    stalePrefix = '[⚠️ STALE] ';
+            }
+            spTruthsText += `- ${stalePrefix}**${t.key}:** ${t.value}${t.rationale ? ` _(${t.rationale})_` : ''}\n`;
+        }
+    }
+    return spTruthsText;
+}
+// T028: explicit `id` tiebreak appended to the 6.x priority ordering — same
+// priority buckets, but ties are now deterministic (a fleet-brief pin that is
+// strictly-stable for the default path too; no consumer locks quest order).
+const ACTIVE_QUESTS_SQL = `
         SELECT * FROM quests
         WHERE project_id = ? AND status = 'pending'
         ORDER BY
           CASE priority WHEN 'critical' THEN 1 WHEN 'high' THEN 2 WHEN 'medium' THEN 3 ELSE 4 END,
           id
         LIMIT 5
-      `;function Y(e){const t={critical:"\u{1F534}",high:"\u{1F7E0}",medium:"\u{1F7E1}",low:"\u{1F7E2}"};let n=`### \u{1F3AF} Active Quests
-`;for(const s of e)n+=`- ${t[s.priority]??"\u2022"} #${s.id}: ${s.title}
-`;return n}function q(e,t,n,s){return n?e.getProjectById(n):s?t.prepare("SELECT * FROM projects WHERE LOWER(name) LIKE LOWER(?) LIMIT 1").get(`%${s}%`):t.prepare(`
+      `;
+/** Section 4 — active quests (byte-identical to the 6.x block). */
+function buildQuestsSectionText(activeQuests) {
+    const priorityEmoji = { critical: '🔴', high: '🟠', medium: '🟡', low: '🟢' };
+    let questsBlock = '### 🎯 Active Quests\n';
+    for (const q of activeQuests) {
+        questsBlock += `- ${priorityEmoji[q.priority] ?? '•'} #${q.id}: ${q.title}\n`;
+    }
+    return questsBlock;
+}
+/** The 6.x three-branch project resolution (by_id / by_name / latest-active),
+ * shared verbatim by the default and fleet paths. */
+function resolvePrimeProject(store, db, spId, spName) {
+    if (spId)
+        return store.getProjectById(spId);
+    if (spName) {
+        return db.prepare('SELECT * FROM projects WHERE LOWER(name) LIKE LOWER(?) LIMIT 1').get(`%${spName}%`);
+    }
+    return db.prepare(`
           SELECT p.* FROM projects p
           JOIN sessions s ON s.project_id = p.id
           ORDER BY s.created_at DESC LIMIT 1
-        `).get()}function P(e){const t=e.getAllProjects(20);return t.length===0?{content:[{type:"text",text:"No projects found. Run `wyrm_scan_projects` first."}],isError:!0}:{content:[{type:"text",text:`Project not found. Available projects:
-${t.map(s=>`- ${s.name} (ID: ${s.id})`).join(`
-`)}`}],isError:!0}}const K=(e,t)=>{const n=e.session_id!==null?`
-Session logged: #${e.session_id}`:"";return O(t.brand,`Wyrm primed for **${e.project_name}** | ${e.truth_count} truth${e.truth_count!==1?"s":""} - ${e.quest_count} quest${e.quest_count!==1?"s":""} - ${e.memory_count} memor${e.memory_count!==1?"ies":"y"}${n}`)},L=(e,t)=>{const n=K(e,t);return e.sections.length>0?e.sections.map(s=>s.text).join(`
-
----
-
-`)+`
-
-`+n:n+`
-
-_No memory stored yet -- start working and Wyrm will learn._`},A={summary:K};async function D(e,t,n){try{const{logSavings:s}=await import("../statusline.js"),o=G(n.content[0]).length,i=Math.round(o/4),c=e.prepare("SELECT id FROM sessions WHERE project_id = ? ORDER BY created_at DESC LIMIT 1").get(t);s(e,"wyrm_session_prime","recovered_context",i,c?.id)}catch{}}const ce={continuity:{path:"continuity",tool:"wyrm_session_prime"},truths:{path:"truths",tool:"wyrm_truth_get"},scaffold:{path:"scaffolds",tool:"wyrm_context_build"},memory:{path:"memory",tool:"wyrm_recall"},quests:{path:"quests",tool:"wyrm_all_quests"}},ae=48,de=1200;async function pe(e,{store:t,raw:n,memory:s,truths:o,scaffolds:i,cache:c}){const{project_id:p,project_name:u,task:a,log_session:f}=e,r=oe(e.run_id);if(r===null)throw new te("run_id",'must be <=64 printable-ASCII chars (no ";")');const m=ne("role",e.role,{maxLen:200})??"",j=se("token_budget",e.token_budget,{min:1})??de,_=n(),$=()=>_.prepare("SELECT body_json FROM run_briefs WHERE run_id = ? AND role = ?").get(r,m),y=p||u?q(t,_,p,u):void 0;if((p||u)&&!y)return P(t);let g=$();if(g&&y){const d=JSON.parse(g.body_json);if(d.project_id!==y.id)return{content:[{type:"text",text:`Fleet brief for (run ${r}, role '${m}') is pinned to project '${d.project_name}' (ID: ${d.project_id}) \u2014 refusing to serve it for requested project '${y.name}' (ID: ${y.id}). Use a distinct role for a second project, or prime without run_id.`}],isError:!0}}if(!g){const d=y??q(t,_,p,u);if(!d)return P(t);const l=[],k=J(t.getContinuity(d.id));k&&l.push({kind:"continuity",text:k});const v=o.getCurrent(d.id);v.length>0&&l.push({kind:"truths",text:Q(v,!1).slice(0,1200)});const w=a??(m||void 0);if(w){const S=i.findBest(w,d.id,.3);S&&l.push({kind:"scaffold",text:i.formatForContext(S,1500)})}const B=s.buildContextBrief(d.id,w??"general",{maxItems:10,minConfidence:.3});B.text&&l.push({kind:"memory",text:B.text.slice(0,2e3)});const I=_.prepare(V).all(d.id);I.length>0&&l.push({kind:"quests",text:Y(I).slice(0,800)});const M=ie(),R=[];let C=ae;for(const S of l){const W=M.count(S.text)+2;if(C+W<=j)R.push(S),C+=W;else{const H=ce[S.kind]??{path:S.kind,tool:"wyrm_search"},U=`[beyond token_budget] wyrm://project/${d.id}/${H.path} -- fetch via ${H.tool}`;R.push({kind:S.kind,text:U}),C+=M.count(U)+2}}let F=null;f&&(F=t.createSession(d.id,{objectives:a??"Session started via wyrm_session_prime",summary:""}).id);const z={project_id:d.id,project_name:d.name,truth_count:o.getStats(d.id).current,quest_count:I.length,memory_count:s.getStats(d.id).total,session_id:F,sections:R,run_id:r,role:m,token_budget:j};_.prepare("INSERT OR IGNORE INTO run_briefs (run_id, role, body_json, token_budget) VALUES (?, ?, ?, ?)").run(r,m,JSON.stringify(z),j),g=$()}const h=JSON.parse(g.body_json),b=x(h,L,A);if(e.for_spawn===!0){const d=x(h,L,{...A,exemptStructured:!0}),l=G(d.content[0]),k=Z("sha256").update(l,"utf8").digest("hex"),v={project_id:h.project_id,project_name:h.project_name,session_id:h.session_id??null,sections:h.sections,for_spawn:!0,run_id:r,role:m,brief:l,brief_hash:k,brief_chars:l.length,cache_key:{table:"run_briefs",run_id:r,role:m}};await D(_,h.project_id,d);const w={content:[{type:"text",text:l}],structuredContent:v};return c.set(N("wyrm_session_prime",JSON.stringify(e)),w,3e4),w}return await D(_,h.project_id,b),c.set(N("wyrm_session_prime",JSON.stringify(e)),b,3e4),b}const Se=[{name:"wyrm_session_start",description:"Start or continue a session for a project",inputSchema:{type:"object",properties:{projectPath:{type:"string",description:"Project path"},objectives:{type:"string",description:"Session objectives"}},required:["projectPath"]},outputSchema:{type:"object",properties:{session_id:{type:"integer"},project:{type:"string"},date:{type:"string"},objectives:{type:["string","null"]}},required:["session_id","project","date","objectives"]},annotations:T.wyrm_session_start,aliases:[],handler:(e,{store:t})=>{const{projectPath:n,objectives:s}=e;let o=t.getProject(n);o||(o=t.registerProject(X(n),n));let i=t.getTodaySession(o.id);i?s&&(i=t.updateSession(i.id,{objectives:i.objectives?`${i.objectives}
-${s}`:s})):i=t.createSession(o.id,{objectives:s||""}),t.archiveOldSessions(o.id,10);const c={session_id:i.id,project:o.name,date:i.date,objectives:i.objectives||null};return x(c,(p,u)=>O(u.brand,`Session ${p.session_id} for ${p.project}`)+`
-**Date:** ${p.date}
-**Objectives:** ${p.objectives??"None set"}`)}},{name:"wyrm_session_update",description:"Update the current session with completed work, issues, or notes",inputSchema:{type:"object",properties:{projectPath:{type:"string"},completed:{type:"string",description:"What was completed"},issues:{type:"string"},commits:{type:"string",description:"Git commits made"},notes:{type:"string"}},required:["projectPath"]},outputSchema:{type:"object",properties:{session_id:{type:"integer"},project:{type:"string"},updated:{type:"array",items:{type:"string",enum:["completed","issues","commits","notes"]}}},required:["session_id","project","updated"]},annotations:T.wyrm_session_update,aliases:[],handler:(e,{store:t,indexing:n})=>{const{projectPath:s,completed:o,issues:i,commits:c,notes:p}=e,u=t.getProject(s);if(!u)return{content:[{type:"text",text:"Project not found"}],isError:!0};let a=t.getTodaySession(u.id);a||(a=t.createSession(u.id,{}));const f={};o&&(f.completed=a.completed?`${a.completed}
-${o}`:o),i&&(f.issues=a.issues?`${a.issues}
-${i}`:i),c&&(f.commits=a.commits?`${a.commits}
-${c}`:c),p&&(f.notes=a.notes?`${a.notes}
-${p}`:p),a=t.updateSession(a.id,f);const r=[o,i,p].filter(Boolean).join(" \xB7 ");r&&t.updateContinuity(u.id,r,"session_update"),n()?.enqueue("session",a.id,u.id);const m={session_id:a.id,project:u.name,updated:Object.keys(f)};return x(m,(j,_)=>O(_.brand,`Session updated for ${j.project}`))}},{name:"wyrm_session_rehydrate",description:"Lossless session rehydration. Given a past session ID, returns a complete briefing markdown a fresh AI agent can ingest to inherit prior state: objectives, completed work, notes, summary, current ground truths, open quests, validated patterns (artifacts), unresolved failure patterns. Cross-session continuity no other AI memory tool offers.",inputSchema:{type:"object",properties:{session_id:{type:"number",description:"ID of the session to rehydrate"},include_artifacts:{type:"boolean",description:"Include memory artifacts (default true)"},include_failures:{type:"boolean",description:"Include unresolved failure patterns (default true)"},max_truth_chars:{type:"number",description:"Cap on chars used for ground truths (default 2000)"}},required:["session_id"]},outputSchema:{type:"object",properties:{session_id:{type:"integer"},project_name:{type:"string"},project_path:{type:"string"},briefing_markdown:{type:"string"},context_chars:{type:"integer"},attached:{type:"object",properties:{quests:{type:"integer"},truths:{type:"integer"},artifacts:{type:"integer"},failures:{type:"integer"}},required:["quests","truths","artifacts","failures"]}},required:["session_id","project_name","project_path","briefing_markdown","context_chars","attached"]},annotations:T.wyrm_session_rehydrate,aliases:[],handler:(e,{rehydration:t})=>{const{session_id:n,include_artifacts:s,include_failures:o,max_truth_chars:i}=e,c=t.rehydrate(n,{include_artifacts:s,include_failures:o,max_truth_chars:i});return c?x({...c},p=>p.briefing_markdown,{exemptStructured:!0}):{content:[{type:"text",text:`Session #${n} not found.`}],isError:!0}}},{name:"wyrm_session_prime",description:"Use first at session start - load everything you need to know before starting work, and catch me up on where we left off last time: ground truths, memory brief, reasoning scaffold, and active quests in one call. First call every agent makes in a run.",inputSchema:{type:"object",properties:{project_id:{type:"number"},project_name:{type:"string"},task:{type:"string",description:"Drives scaffold + memory selection"},log_session:{type:"boolean",description:"Also log a session row"},run_id:{type:"string",description:"Fleet: brief cached per (run_id, role)"},role:{type:"string"},token_budget:{type:"number"},for_spawn:{type:"boolean"}}},outputSchema:{type:"object",properties:{project_id:{type:"integer"},project_name:{type:"string"},session_id:{type:["integer","null"]},sections:{type:"array",items:{type:"object",properties:{kind:{type:"string"},text:{type:"string"}},required:["kind","text"]}}},required:["project_id","project_name","session_id","sections"]},annotations:T.wyrm_session_prime,aliases:[],handler:async(e,{store:t,raw:n,memory:s,truths:o,scaffolds:i,cache:c})=>{const{project_id:p,project_name:u,task:a,log_session:f}=e;if(e.run_id!==void 0&&e.run_id!==null)return pe(e,{store:t,raw:n,memory:s,truths:o,scaffolds:i,cache:c});const r=q(t,n(),p,u);if(!r)return P(t);const m=[],j=J(t.getContinuity(r.id));j&&m.push({kind:"continuity",text:j});const _=o.getCurrent(r.id);if(_.length>0&&m.push({kind:"truths",text:Q(_,!0).slice(0,1200)}),a){const E=i.findBest(a,r.id,.3);E&&m.push({kind:"scaffold",text:i.formatForContext(E,1500)})}const $=s.buildContextBrief(r.id,a??"general",{maxItems:10,minConfidence:.3});$.text&&m.push({kind:"memory",text:$.text.slice(0,2e3)});const y=n().prepare(V).all(r.id);y.length>0&&m.push({kind:"quests",text:Y(y).slice(0,800)});try{const{vaultAdvisory:E}=await import("../vault.js"),d=E();d.length>0&&m.push({kind:"vault",text:`### \u{1F510} Credential Vault
-`+d.map(l=>`- ${l}`).join(`
-`)})}catch{}let g=null;f&&(g=t.createSession(r.id,{objectives:a??"Session started via wyrm_session_prime",summary:""}).id);const h={project_id:r.id,project_name:r.name,truth_count:o.getStats(r.id).current,quest_count:y.length,memory_count:s.getStats(r.id).total,session_id:g,sections:m},b=x(h,L,A);return await D(n(),r.id,b),c.set(N("wyrm_session_prime",JSON.stringify(e)),b,3e4),b}}];export{Se as sessionToolSpecs};
+        `).get();
+}
+/** The 6.x not-found advisory (isError per the T026 goals precedent). */
+function primeProjectNotFound(store) {
+    const allProjects = store.getAllProjects(20);
+    if (allProjects.length === 0) {
+        return { content: [{ type: "text", text: `No projects found. Run \`wyrm_scan_projects\` first.` }], isError: true };
+    }
+    const candidates = allProjects.map(p => `- ${p.name} (ID: ${p.id})`).join('\n');
+    return { content: [{ type: "text", text: `Project not found. Available projects:\n${candidates}` }], isError: true };
+}
+/** The session_prime summary line — the one-line roll-up the WYRM_CHANNEL=
+ * structured seam keeps on the text channel; the section bodies (the actual
+ * knowledge) ride structuredContent (`body.sections`) unchanged. */
+const primeSummary = (b, g) => {
+    const sessionNote = b.session_id !== null ? `\nSession logged: #${b.session_id}` : '';
+    return withGlyph(g.brand, `Wyrm primed for **${b.project_name}** | ${b.truth_count} truth${b.truth_count !== 1 ? 's' : ''} - ` +
+        `${b.quest_count} quest${b.quest_count !== 1 ? 's' : ''} - ` +
+        `${b.memory_count} memor${b.memory_count !== 1 ? 'ies' : 'y'}${sessionNote}`);
+};
+/** The session_prime text template — pure (body, glyphs), shared by both
+ * paths so cached fleet bodies re-render to the exact same text channel. */
+const primeTemplate = (b, g) => {
+    const summaryLine = primeSummary(b, g);
+    return b.sections.length > 0
+        ? b.sections.map((s) => s.text).join('\n\n---\n\n') + '\n\n' + summaryLine
+        : summaryLine + '\n\n_No memory stored yet -- start working and Wyrm will learn._';
+};
+/** Shared render-options for both session_prime emit paths. */
+const PRIME_RENDER_OPTS = { summary: primeSummary };
+/** Spec 018 recovered-context savings accounting (both paths, best-effort). */
+async function logPrimeSavings(db, projectId, response) {
+    try {
+        const { logSavings } = await import('../statusline.js');
+        const recoveredChars = blockText(response.content[0]).length;
+        // ~4 chars/token is a conservative English estimate.
+        const recoveredTokens = Math.round(recoveredChars / 4);
+        // Use last active session for this project if available.
+        const lastSession = db.prepare(`SELECT id FROM sessions WHERE project_id = ? ORDER BY created_at DESC LIMIT 1`).get(projectId);
+        logSavings(db, 'wyrm_session_prime', 'recovered_context', recoveredTokens, lastSession?.id);
+    }
+    catch { /* best-effort */ }
+}
+// ── T028 fleet mode ─────────────────────────────────────────────────────────
+/** Over-budget sections collapse to a plain-text `wyrm://` reference naming
+ * the follow-on tool. THE T034 SEAM: when the resource layer lands, these
+ * become real `resourceLink` returns — 7.0 ships them as text on purpose. */
+const STUB_REFS = {
+    continuity: { path: 'continuity', tool: 'wyrm_session_prime' },
+    truths: { path: 'truths', tool: 'wyrm_truth_get' },
+    scaffold: { path: 'scaffolds', tool: 'wyrm_context_build' },
+    memory: { path: 'memory', tool: 'wyrm_recall' },
+    quests: { path: 'quests', tool: 'wyrm_all_quests' },
+};
+/** Tokens reserved for the summary line + section separators before any
+ * section is admitted (measured worst-case summary ≈40 tokens at 4cpt). */
+const PRIME_SUMMARY_RESERVE = 48;
+const DEFAULT_PRIME_BUDGET = 1200;
+/**
+ * Fleet-mode session_prime (T028). Compile-once, CAS-insert, read-back-winner:
+ * byte-equality across N concurrent primes of one (run_id, role) holds even
+ * across processes, because every caller renders the row that WON the
+ * INSERT OR IGNORE — a loser's own compile is discarded, never returned.
+ * First-caller-wins applies to the args too (task/project/log_session/
+ * token_budget shape only the compiled brief); later callers with different
+ * args still receive the cached prefix — that IS the stability contract.
+ */
+async function fleetPrime(args, { store, raw, memory, truths, scaffolds, cache }) {
+    const { project_id: spId, project_name: spName, task: spTask, log_session: spLog } = args;
+    const runId = sanitizeActorId(args.run_id);
+    if (runId === null)
+        throw new ValidationError('run_id', 'must be <=64 printable-ASCII chars (no ";")');
+    // role is half the cache key — '' is the role-less slice.
+    const role = asString('role', args.role, { maxLen: 200 }) ?? '';
+    const budget = asInt('token_budget', args.token_budget, { min: 1 }) ?? DEFAULT_PRIME_BUDGET;
+    const db = raw();
+    const readBrief = () => db.prepare('SELECT body_json FROM run_briefs WHERE run_id = ? AND role = ?').get(runId, role);
+    // Security pass #1 (confirmed finding): the cache key is (run_id, role) —
+    // a cache hit previously skipped project resolution ENTIRELY, so a prime
+    // naming a DIFFERENT project under the same key silently received the
+    // first project's ground truths, memory, and quests. An EXPLICITLY
+    // requested project is now resolved BEFORE the cache read and checked
+    // against the project_id the winning compile baked into body_json; a
+    // mismatch is a visible error, never a cross-project leak. Project-LESS
+    // primes still take the cached row untouched — first-caller-wins applies
+    // to the args (incl. the project), which IS the byte-stability contract,
+    // and resolving the latest-active-session branch on a hit would itself
+    // be a mid-run nondeterminism source.
+    const requested = (spId || spName) ? resolvePrimeProject(store, db, spId, spName) : undefined;
+    if ((spId || spName) && !requested)
+        return primeProjectNotFound(store);
+    let row = readBrief();
+    if (row && requested) {
+        const cached = JSON.parse(row.body_json);
+        if (cached.project_id !== requested.id) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Fleet brief for (run ${runId}, role '${role}') is pinned to project '${cached.project_name}' (ID: ${cached.project_id}) — refusing to serve it for requested project '${requested.name}' (ID: ${requested.id}). Use a distinct role for a second project, or prime without run_id.`,
+                    }],
+                isError: true,
+            };
+        }
+    }
+    if (!row) {
+        const project = requested ?? resolvePrimeProject(store, db, spId, spName);
+        if (!project)
+            return primeProjectNotFound(store); // never cached — a later prime may resolve
+        // Same section compilation as the default path, nondeterminism pinned
+        // (no staleness prefixes, no vault advisory — see the module header).
+        const compiled = [];
+        // Section 0 — Continuity: the living thread, restored FIRST (where we left off).
+        const contText = buildContinuitySectionText(store.getContinuity(project.id));
+        if (contText)
+            compiled.push({ kind: 'continuity', text: contText });
+        const currentTruths = truths.getCurrent(project.id);
+        if (currentTruths.length > 0) {
+            compiled.push({ kind: 'truths', text: buildTruthsSectionText(currentTruths, false).slice(0, 1200) });
+        }
+        // The ROLE SLICE: role drives scaffold + memory selection when the
+        // orchestrator didn't pass an explicit task.
+        const fleetTask = spTask ?? (role || undefined);
+        if (fleetTask) {
+            const scaffoldMatch = scaffolds.findBest(fleetTask, project.id, 0.3);
+            if (scaffoldMatch)
+                compiled.push({ kind: 'scaffold', text: scaffolds.formatForContext(scaffoldMatch, 1500) });
+        }
+        const spBrief = memory.buildContextBrief(project.id, fleetTask ?? 'general', { maxItems: 10, minConfidence: 0.3 });
+        if (spBrief.text)
+            compiled.push({ kind: 'memory', text: spBrief.text.slice(0, 2000) });
+        const activeQuests = db.prepare(ACTIVE_QUESTS_SQL).all(project.id);
+        if (activeQuests.length > 0) {
+            compiled.push({ kind: 'quests', text: buildQuestsSectionText(activeQuests).slice(0, 800) });
+        }
+        // Token budget (approx-4cpt, the token-budget.ts convention): greedy
+        // in section order; an over-budget section becomes its wyrm:// stub.
+        // Stubs always emit (a pathological budget floors at stubs + summary —
+        // the brief never silently loses a whole section).
+        const est = makeEstimator();
+        const sections = [];
+        let used = PRIME_SUMMARY_RESERVE;
+        for (const s of compiled) {
+            const cost = est.count(s.text) + 2; // +2 ≈ the '\n\n---\n\n' separator
+            if (used + cost <= budget) {
+                sections.push(s);
+                used += cost;
+            }
+            else {
+                const ref = STUB_REFS[s.kind] ?? { path: s.kind, tool: 'wyrm_search' };
+                const stub = `[beyond token_budget] wyrm://project/${project.id}/${ref.path} -- fetch via ${ref.tool}`;
+                sections.push({ kind: s.kind, text: stub });
+                used += est.count(stub) + 2;
+            }
+        }
+        // log_session fires on the COMPILING call only — the logged session_id is
+        // baked into the cached body; cache hits never insert another row.
+        let sessionId = null;
+        if (spLog) {
+            sessionId = store.createSession(project.id, {
+                objectives: spTask ?? 'Session started via wyrm_session_prime',
+                summary: '',
+            }).id;
+        }
+        const body = {
+            project_id: project.id,
+            project_name: project.name,
+            truth_count: truths.getStats(project.id).current,
+            quest_count: activeQuests.length,
+            memory_count: memory.getStats(project.id).total,
+            session_id: sessionId,
+            sections,
+            run_id: runId,
+            role,
+            token_budget: budget,
+        };
+        db.prepare('INSERT OR IGNORE INTO run_briefs (run_id, role, body_json, token_budget) VALUES (?, ?, ?, ?)').run(runId, role, JSON.stringify(body), budget);
+        row = readBrief();
+    }
+    // Render the WINNER's body — text re-derives through the shared template,
+    // so the text channel is byte-identical for every caller too.
+    const winner = JSON.parse(row.body_json);
+    const response = renderResult(winner, primeTemplate, PRIME_RENDER_OPTS);
+    // FEATHERWEIGHT opt #2 — for_spawn: same CAS row, same compile, packaged for
+    // OUT-OF-BAND embedding (advances T038 in spirit). The brief is the payload
+    // the orchestrator embeds RAW into each same-role agent's spawn prefix —
+    // there is NO structuredContent channel in a spawn prompt, so the brief MUST
+    // carry the FULL prime (truths/scaffold/memory/quests), never the renderer's
+    // WYRM_CHANNEL=structured summary collapse. We therefore render a dedicated
+    // exemptStructured response for the brief (mirroring session_rehydrate, whose
+    // text IS its payload): under WYRM_CHANNEL=both this is byte-identical to the
+    // agent-side prime's content[0].text (the distribute-once == fallback
+    // guarantee); under WYRM_CHANNEL=structured the agent-side fallback collapses
+    // its text channel but still ships the full body on structuredContent, while
+    // the embedded brief — which has no such body to fall back on — stays full.
+    const forSpawn = args.for_spawn === true;
+    if (forSpawn) {
+        const briefResponse = renderResult(winner, primeTemplate, { ...PRIME_RENDER_OPTS, exemptStructured: true });
+        const brief = blockText(briefResponse.content[0]);
+        const briefHash = createHash('sha256').update(brief, 'utf8').digest('hex');
+        // The for_spawn envelope is a SUPERSET of the declared session_prime
+        // outputSchema (project_id/project_name/session_id/sections required) — the
+        // schema-required fields stay so a strict client validates it, and the
+        // distribute-once extras (brief / brief_hash / cache_key) ride alongside
+        // per the T022 lean-union rule (undeclared extras on structuredContent).
+        const spawnBody = {
+            project_id: winner.project_id,
+            project_name: winner.project_name,
+            session_id: winner.session_id ?? null,
+            sections: winner.sections,
+            for_spawn: true,
+            run_id: runId,
+            role,
+            brief,
+            brief_hash: briefHash,
+            brief_chars: brief.length,
+            cache_key: { table: 'run_briefs', run_id: runId, role },
+        };
+        await logPrimeSavings(db, winner.project_id, briefResponse);
+        // The for_spawn envelope is per-(args) like any read; publish under the
+        // same dispatcher key convention so a repeat for_spawn read is cache-hot.
+        const spawnResult = {
+            content: [{ type: 'text', text: brief }],
+            structuredContent: spawnBody,
+        };
+        cache.set(cacheKeyFor('wyrm_session_prime', JSON.stringify(args)), spawnResult, 30000);
+        return spawnResult;
+    }
+    await logPrimeSavings(db, winner.project_id, response);
+    // READ_ONLY_TOOLS cache publish — dispatcher key convention.
+    cache.set(cacheKeyFor('wyrm_session_prime', JSON.stringify(args)), response, 30000);
+    return response;
+}
+export const sessionToolSpecs = [
+    {
+        name: "wyrm_session_start",
+        description: "Start or continue a session for a project",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectPath: { type: "string", description: "Project path" },
+                objectives: { type: "string", description: "Session objectives" },
+            },
+            required: ["projectPath"],
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "integer" },
+                project: { type: "string" },
+                date: { type: "string" },
+                objectives: { type: ["string", "null"] },
+            },
+            required: ["session_id", "project", "date", "objectives"],
+        },
+        annotations: TOOL_ANNOTATIONS.wyrm_session_start,
+        aliases: [],
+        handler: (args, { store }) => {
+            const { projectPath, objectives } = args;
+            let project = store.getProject(projectPath);
+            if (!project) {
+                // Auto-register project
+                project = store.registerProject(basename(projectPath), projectPath);
+            }
+            let session = store.getTodaySession(project.id);
+            if (!session) {
+                session = store.createSession(project.id, { objectives: objectives || '' });
+            }
+            else if (objectives) {
+                session = store.updateSession(session.id, {
+                    objectives: session.objectives ? `${session.objectives}\n${objectives}` : objectives,
+                });
+            }
+            // Archive old sessions
+            store.archiveOldSessions(project.id, 10);
+            const body = {
+                session_id: session.id,
+                project: project.name,
+                date: session.date,
+                objectives: session.objectives || null,
+            };
+            return renderResult(body, (b, g) => withGlyph(g.brand, `Session ${b.session_id} for ${b.project}`) + '\n' +
+                `**Date:** ${b.date}\n` +
+                `**Objectives:** ${b.objectives ?? 'None set'}`);
+        },
+    },
+    {
+        name: "wyrm_session_update",
+        description: "Update the current session with completed work, issues, or notes",
+        inputSchema: {
+            type: "object",
+            properties: {
+                projectPath: { type: "string" },
+                completed: { type: "string", description: "What was completed" },
+                issues: { type: "string" },
+                commits: { type: "string", description: "Git commits made" },
+                notes: { type: "string" },
+            },
+            required: ["projectPath"],
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "integer" },
+                project: { type: "string" },
+                updated: { type: "array", items: { type: "string", enum: ["completed", "issues", "commits", "notes"] } },
+            },
+            required: ["session_id", "project", "updated"],
+        },
+        annotations: TOOL_ANNOTATIONS.wyrm_session_update,
+        aliases: [],
+        handler: (args, { store, indexing }) => {
+            const { projectPath, completed, issues, commits, notes } = args;
+            const project = store.getProject(projectPath);
+            if (!project) {
+                // T026: was a non-error "Project not found" text in 6.x — domain
+                // not-founds are isError per the goals precedent (schema-exempt).
+                return { content: [{ type: "text", text: "Project not found" }], isError: true };
+            }
+            let session = store.getTodaySession(project.id);
+            if (!session) {
+                session = store.createSession(project.id, {});
+            }
+            const updates = {};
+            if (completed)
+                updates.completed = session.completed ? `${session.completed}\n${completed}` : completed;
+            if (issues)
+                updates.issues = session.issues ? `${session.issues}\n${issues}` : issues;
+            if (commits)
+                updates.commits = session.commits ? `${session.commits}\n${commits}` : commits;
+            if (notes)
+                updates.notes = session.notes ? `${session.notes}\n${notes}` : notes;
+            session = store.updateSession(session.id, updates);
+            // Feed the living thread (Continuity Layer) — what we just worked on, so the next session
+            // or surface (phone, Hermes, Ember, Gemini) re-opens already knowing it.
+            const threadNote = [completed, issues, notes].filter(Boolean).join(' · ');
+            if (threadNote)
+                store.updateContinuity(project.id, threadNote, 'session_update');
+            indexing()?.enqueue('session', session.id, project.id);
+            const body = { session_id: session.id, project: project.name, updated: Object.keys(updates) };
+            return renderResult(body, (b, g) => withGlyph(g.brand, `Session updated for ${b.project}`));
+        },
+    },
+    {
+        name: "wyrm_session_rehydrate",
+        description: "Lossless session rehydration. Given a past session ID, returns a complete briefing markdown a fresh AI agent can ingest to inherit prior state: objectives, completed work, notes, summary, current ground truths, open quests, validated patterns (artifacts), unresolved failure patterns. Cross-session continuity no other AI memory tool offers.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "number", description: "ID of the session to rehydrate" },
+                include_artifacts: { type: "boolean", description: "Include memory artifacts (default true)" },
+                include_failures: { type: "boolean", description: "Include unresolved failure patterns (default true)" },
+                max_truth_chars: { type: "number", description: "Cap on chars used for ground truths (default 2000)" },
+            },
+            required: ["session_id"],
+        },
+        outputSchema: {
+            type: "object",
+            properties: {
+                session_id: { type: "integer" },
+                project_name: { type: "string" },
+                project_path: { type: "string" },
+                briefing_markdown: { type: "string" },
+                context_chars: { type: "integer" },
+                attached: {
+                    type: "object",
+                    properties: {
+                        quests: { type: "integer" },
+                        truths: { type: "integer" },
+                        artifacts: { type: "integer" },
+                        failures: { type: "integer" },
+                    },
+                    required: ["quests", "truths", "artifacts", "failures"],
+                },
+            },
+            required: ["session_id", "project_name", "project_path", "briefing_markdown", "context_chars", "attached"],
+        },
+        annotations: TOOL_ANNOTATIONS.wyrm_session_rehydrate,
+        aliases: [],
+        handler: (args, { rehydration }) => {
+            const { session_id, include_artifacts, include_failures, max_truth_chars } = args;
+            const brief = rehydration.rehydrate(session_id, {
+                include_artifacts, include_failures, max_truth_chars,
+            });
+            if (!brief) {
+                return { content: [{ type: "text", text: `Session #${session_id} not found.` }], isError: true };
+            }
+            // The briefing markdown IS the text channel (6.x behavior, byte-
+            // identical); the body carries it plus the structured brief identity.
+            // EXEMPT from WYRM_CHANNEL=structured shrink: the text channel here is
+            // the payload (the body just wraps the same markdown), so collapsing it
+            // to a summary line would drop the knowledge the model reads.
+            return renderResult({ ...brief }, (b) => b.briefing_markdown, { exemptStructured: true });
+        },
+    },
+    {
+        name: "wyrm_session_prime",
+        description: "Use first at session start - load everything you need to know before starting work, and catch me up on where we left off last time: ground truths, memory brief, reasoning scaffold, and active quests in one call. First call every agent makes in a run.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "number" },
+                project_name: { type: "string" },
+                task: { type: "string", description: "Drives scaffold + memory selection" },
+                log_session: { type: "boolean", description: "Also log a session row" },
+                // T028 fleet mode (descriptions omitted under the 8K default-surface
+                // pin — semantics in the tool description + run_id's frozen meaning).
+                run_id: { type: "string", description: "Fleet: brief cached per (run_id, role)" },
+                role: { type: "string" },
+                token_budget: { type: "number" },
+                for_spawn: { type: "boolean" },
+            },
+        },
+        // T028: the truth/quest/memory count properties were dropped from the
+        // DECLARED schema to fund the fleet-mode input params under the 8K pin
+        // (the T027 handoff earmarked them); the body still carries the counts —
+        // undeclared extras ride structuredContent (the T022 lean-union rule).
+        outputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "integer" },
+                project_name: { type: "string" },
+                session_id: { type: ["integer", "null"] },
+                sections: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            kind: { type: "string" },
+                            text: { type: "string" },
+                        },
+                        required: ["kind", "text"],
+                    },
+                },
+            },
+            required: ["project_id", "project_name", "session_id", "sections"],
+        },
+        annotations: TOOL_ANNOTATIONS.wyrm_session_prime,
+        aliases: [],
+        handler: async (args, { store, raw, memory, truths, scaffolds, cache }) => {
+            const { project_id: spId, project_name: spName, task: spTask, log_session: spLog } = args;
+            // T028 fleet mode: run_id present → the byte-stable cached-brief path.
+            if (args.run_id !== undefined && args.run_id !== null) {
+                return fleetPrime(args, { store, raw, memory, truths, scaffolds, cache });
+            }
+            // Project resolution (shared 3-branch helper — T028 hoist, verbatim).
+            const spProject = resolvePrimeProject(store, raw(), spId, spName);
+            if (!spProject) {
+                // T026: not-found paths are isError (goals precedent; was non-error
+                // prose in 6.x — recorded deviation).
+                return primeProjectNotFound(store);
+            }
+            const sections = [];
+            // Section 0 — Continuity: the living thread, restored FIRST (where we left off).
+            const spContText = buildContinuitySectionText(store.getContinuity(spProject.id));
+            if (spContText)
+                sections.push({ kind: 'continuity', text: spContText });
+            // Section 1 — Ground Truths (up to 1200 chars), prefix stale truths
+            const spCurrentTruths = truths.getCurrent(spProject.id);
+            if (spCurrentTruths.length > 0) {
+                sections.push({ kind: 'truths', text: buildTruthsSectionText(spCurrentTruths, true).slice(0, 1200) });
+            }
+            // Section 2 — Reasoning Scaffold (up to 1500 chars)
+            if (spTask) {
+                const scaffoldMatchSP = scaffolds.findBest(spTask, spProject.id, 0.3);
+                if (scaffoldMatchSP) {
+                    sections.push({ kind: 'scaffold', text: scaffolds.formatForContext(scaffoldMatchSP, 1500) });
+                }
+            }
+            // Section 3 — Memory Brief (up to 2000 chars)
+            const spBrief = memory.buildContextBrief(spProject.id, spTask ?? 'general', { maxItems: 10, minConfidence: 0.3 });
+            if (spBrief.text)
+                sections.push({ kind: 'memory', text: spBrief.text.slice(0, 2000) });
+            // Section 4 — Active Quests (up to 800 chars)
+            const spActiveQuests = raw().prepare(ACTIVE_QUESTS_SQL).all(spProject.id);
+            if (spActiveQuests.length > 0) {
+                sections.push({ kind: 'quests', text: buildQuestsSectionText(spActiveQuests).slice(0, 800) });
+            }
+            // Section 5 — Credential vault advisory (global; only when actionable, so it
+            // self-resolves once `wyrm vault setup` has been run). Lets Wyrm AUTOMATICALLY
+            // guide the connecting AI to set credential storage up properly.
+            try {
+                const { vaultAdvisory } = await import('../vault.js');
+                const vaultLines = vaultAdvisory();
+                if (vaultLines.length > 0) {
+                    sections.push({ kind: 'vault', text: '### 🔐 Credential Vault\n' + vaultLines.map(l => `- ${l}`).join('\n') });
+                }
+            }
+            catch { /* vault optional */ }
+            // Optionally log session
+            let sessionId = null;
+            if (spLog) {
+                const session = store.createSession(spProject.id, {
+                    objectives: spTask ?? 'Session started via wyrm_session_prime',
+                    summary: '',
+                });
+                sessionId = session.id;
+            }
+            const body = {
+                project_id: spProject.id,
+                project_name: spProject.name,
+                truth_count: truths.getStats(spProject.id).current,
+                quest_count: spActiveQuests.length,
+                memory_count: memory.getStats(spProject.id).total,
+                session_id: sessionId,
+                sections,
+            };
+            const spResponse = renderResult(body, primeTemplate, PRIME_RENDER_OPTS);
+            // Spec 018: log recovered-context savings. The text we just assembled
+            // is context the AI would have had to re-elicit from the operator
+            // turn by turn — counting it as ~recovered tokens (conservative).
+            await logPrimeSavings(raw(), spProject.id, spResponse);
+            // READ_ONLY_TOOLS cache publish — dispatcher key convention.
+            cache.set(cacheKeyFor('wyrm_session_prime', JSON.stringify(args)), spResponse, 30000);
+            return spResponse;
+        },
+    },
+];
+//# sourceMappingURL=session.js.map