fraim 2.0.280 → 2.0.283

package/dist/src/core/utils/stub-generator.js

@@ -50,71 +50,71 @@ function generateJobStub(jobName, _jobPath, intent, outcome, steps, displayName)
     const metadata = displayName
         ? `---\n${JSON.stringify({ name: jobName, displayName }, null, 2)}\n---\n`
         : '';
-    return `${STUB_MARKER}
-${metadata}
-# FRAIM Job: ${jobName}
-
-## Intent
-${intent}
-
-## Outcome
-${outcome}
-
-## Steps
-${steps}
-
----
-
-> [!IMPORTANT]
-> **For AI Agents:** Do NOT attempt to execute this job based on the Intent/Outcome above.
-> This stub is for discoverability only. The actual job has multiple phases with
-> detailed steps, validation criteria, and required skills.
->
-> To get full phase-by-phase instructions, call:
-> \`get_fraim_job({ job: "${jobName}" })\`
->
-> Then follow all phases using \`seekMentoring\` at each phase transition.
+    return `${STUB_MARKER}
+${metadata}
+# FRAIM Job: ${jobName}
+
+## Intent
+${intent}
+
+## Outcome
+${outcome}
+
+## Steps
+${steps}
+
+---
+
+> [!IMPORTANT]
+> **For AI Agents:** Do NOT attempt to execute this job based on the Intent/Outcome above.
+> This stub is for discoverability only. The actual job has multiple phases with
+> detailed steps, validation criteria, and required skills.
+>
+> To get full phase-by-phase instructions, call:
+> \`get_fraim_job({ job: "${jobName}" })\`
+>
+> Then follow all phases using \`seekMentoring\` at each phase transition.
 `;
 }
 /**
  * Generates a lightweight markdown stub for a skill.
  */
 function generateSkillStub(skillName, skillPath, skillInput, skillOutput) {
-    return `${STUB_MARKER}
-# FRAIM Skill: ${skillName}
-
-## Skill Input
-${skillInput}
-
-## Skill Output
-${skillOutput}
-
----
-
-> [!IMPORTANT]
-> **For AI Agents:** This is a discoverability stub for the skill.
-> All execution details must be fetched from MCP before use.
-> To retrieve the complete skill instructions, call:
-> \`get_fraim_file({ path: "skills/${skillPath}" })\`
+    return `${STUB_MARKER}
+# FRAIM Skill: ${skillName}
+
+## Skill Input
+${skillInput}
+
+## Skill Output
+${skillOutput}
+
+---
+
+> [!IMPORTANT]
+> **For AI Agents:** This is a discoverability stub for the skill.
+> All execution details must be fetched from MCP before use.
+> To retrieve the complete skill instructions, call:
+> \`get_fraim_file({ path: "skills/${skillPath}" })\`
 `;
 }
 /**
  * Generates a lightweight markdown stub for a rule.
  */
 function generateRuleStub(ruleName, rulePath, intent) {
-    return `${STUB_MARKER}
-# FRAIM Rule: ${ruleName}
-
-## Intent
-${intent}
-
----
-
-> [!IMPORTANT]
-> **For AI Agents:** This is a discoverability stub for the rule.
-> All rule details must be fetched from MCP before use.
-> To retrieve the complete rule instructions, call:
-> \`get_fraim_file({ path: "rules/${rulePath}" })\`
+    return `${STUB_MARKER}
+# FRAIM Rule: ${ruleName}
+
+## Intent
+${intent}
+
+---
+
+> [!IMPORTANT]
+> **For AI Agents:** This is a discoverability stub for the rule.
+> All rule details must be fetched from MCP before use.
+> To retrieve the complete rule instructions, call:
+> \`get_fraim_file({ path: "rules/${rulePath}" })\`
 `;
 }
 /**

package/dist/src/first-run/server.js

@@ -121,6 +121,7 @@ class FirstRunServer {
     constructor(options) {
         this.app = (0, express_1.default)();
         this.sessionService = options.sessionService;
+        this.onOpenHub = options.onOpenHub;
         this.finishPromise = new Promise((resolve) => {
             this.finishResolver = resolve;
         });
@@ -299,13 +300,16 @@ class FirstRunServer {
         // a durable launcher binary that survives independently.
         this.app.post('/api/first-run/open-hub', async (_req, res) => {
             try {
-                const result = await this.sessionService.openHub();
+                let result = await this.sessionService.openHub();
                 // Write the next-prompt artifact as a side effect of opening the
                 // Hub so the client doesn't need a separate /finish call. We
                 // intentionally do NOT resolve the finishPromise - see /finish
                 // handler comment above.
                 if (result.ok) {
                     this.sessionService.finish();
+                    if (this.onOpenHub) {
+                        result = { ...result, ...(await this.onOpenHub()) };
+                    }
                 }
                 return res.json(result);
             }

package/dist/src/first-run/session-service.js

@@ -48,6 +48,7 @@ const ide_detector_1 = require("../cli/setup/ide-detector");
 const ide_global_integration_1 = require("../cli/setup/ide-global-integration");
 const auto_mcp_setup_1 = require("../cli/setup/auto-mcp-setup");
 const setup_1 = require("../cli/commands/setup");
+const fraim_mcp_latest_launcher_1 = require("../cli/mcp/fraim-mcp-latest-launcher");
 const script_sync_utils_1 = require("../cli/utils/script-sync-utils");
 const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
 const managed_agent_install_1 = require("../cli/utils/managed-agent-install");
@@ -118,13 +119,18 @@ function buildPersistShellPathWindowsCommand(bins) {
         `[Environment]::SetEnvironmentVariable('PATH', $cur, 'User')`,
     ].join('; ');
 }
-function persistShellPath() {
+function persistShellPath(includePackagedFraimBin = false) {
     const marker = '# FRAIM managed binaries';
     const legacyExportLine = 'export PATH="$HOME/.fraim/node/bin:$PATH"';
-    const exportLine = 'export PATH="$PATH:$HOME/.fraim/node/bin"';
+    const exportLine = includePackagedFraimBin
+        ? 'export PATH="$PATH:$HOME/.fraim/bin:$HOME/.fraim/node/bin"'
+        : 'export PATH="$PATH:$HOME/.fraim/node/bin"';
     const stanza = `\n${marker}\n${exportLine}\n`;
     if (process.platform === 'win32') {
-        const psCmd = buildPersistShellPathWindowsCommand((0, managed_agent_paths_1.getManagedAgentBinDirs)());
+        const bins = includePackagedFraimBin
+            ? [path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'bin'), ...(0, managed_agent_paths_1.getManagedAgentBinDirs)()]
+            : (0, managed_agent_paths_1.getManagedAgentBinDirs)();
+        const psCmd = buildPersistShellPathWindowsCommand(bins);
         (0, child_process_1.spawnSync)('powershell', ['-NoProfile', '-NonInteractive', '-Command', psCmd], { encoding: 'utf8' });
         return;
     }
@@ -146,8 +152,12 @@ function persistShellPath() {
                 fs_1.default.writeFileSync(profile, content.replace(legacyExportLine, exportLine), 'utf8');
                 continue;
             }
-            if (content.includes(marker))
+            if (content.includes(marker)) {
+                if (includePackagedFraimBin && !content.includes('$HOME/.fraim/bin')) {
+                    fs_1.default.writeFileSync(profile, content.replace(exportLine.replace(':$HOME/.fraim/bin', ''), exportLine), 'utf8');
+                }
                 continue;
+            }
             fs_1.default.appendFileSync(profile, stanza, 'utf8');
         }
         catch {
@@ -246,6 +256,7 @@ class FirstRunSessionService {
         // wizard prompts the user to paste their key (see setKey / needsKey).
         this.key = options.key || '';
         this.headless = options.headless === true;
+        this.embeddedDesktop = options.embeddedDesktop === true;
         this.fakeMode = getFakeStateMode();
         this.fakeStderr =
             process.env.FRAIM_FIRST_RUN_FAKE_STDERR ??
@@ -310,10 +321,10 @@ class FirstRunSessionService {
         }
         // Real detection — populate row statuses from `command -v` style probes.
         const nodeRow = this.getRow('node');
-        const nodeVer = commandVersion('node');
+        const nodeVer = this.embeddedDesktop ? process.version : commandVersion('node');
         if (nodeVer) {
             nodeRow.status = 'ok';
-            nodeRow.verb = `${nodeVer} detected`;
+            nodeRow.verb = this.embeddedDesktop ? `${nodeVer} bundled with FRAIM` : `${nodeVer} detected`;
         }
         else {
             nodeRow.status = 'pending';
@@ -330,7 +341,7 @@ class FirstRunSessionService {
             gitRow.verb = 'optional — only needed for code delivery workflows';
         }
         const fraimRow = this.getRow('fraim');
-        if (commandVersion('npx') !== null) {
+        if (this.embeddedDesktop || commandVersion('npx') !== null) {
             // Only mark ok if setup has previously completed (config.json is written after autoConfigureMCP).
             // Without this, the wizard skips runFraimRow entirely and autoConfigureMCP never runs for IDEs.
             const globalConfigPath = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'config.json');
@@ -342,7 +353,7 @@ class FirstRunSessionService {
                 fraimRow.status = 'pending';
                 fraimRow.verb = "we'll configure your IDEs";
             }
-            persistShellPath();
+            persistShellPath(this.embeddedDesktop);
         }
         else {
             fraimRow.status = 'pending';
@@ -570,6 +581,12 @@ class FirstRunSessionService {
     }
     async runNodeRow() {
         const row = this.getRow('node');
+        if (this.embeddedDesktop) {
+            row.status = 'ok';
+            row.verb = `${process.version} bundled with FRAIM`;
+            this.persist();
+            return this.respond(`FRAIM includes its own runtime (${process.version}).`, true);
+        }
         // Node is bootstrapped by the install template before the wizard starts.
         // If node is missing here something is severely wrong; fall through to error.
         const ver = commandVersion('node');
@@ -631,7 +648,10 @@ class FirstRunSessionService {
             return this.respond('FRAIM configured.', true);
         }
         try {
-            if (!forceConfigure && !commandVersion('fraim')) {
+            if (this.embeddedDesktop) {
+                (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
+            }
+            else if (!forceConfigure && !commandVersion('fraim')) {
                 const prefix = path_1.default.join((0, script_sync_utils_1.getUserFraimDir)(), 'node');
                 fs_1.default.mkdirSync(prefix, { recursive: true });
                 row.streamOutput = 'Installing FRAIM on this machine...';
@@ -645,7 +665,7 @@ class FirstRunSessionService {
                 this.persist();
                 await runProcess('npm', ['install', '-g', 'fraim@latest'], { npm_config_prefix: prefix });
             }
-            persistShellPath();
+            persistShellPath(this.embeddedDesktop);
             const detectedIDEs = (0, ide_detector_1.detectInstalledIDEs)();
             if (detectedIDEs.length > 0) {
                 await (0, auto_mcp_setup_1.autoConfigureMCP)(this.key, detectedIDEs.map((ide) => ide.name));
@@ -660,7 +680,9 @@ class FirstRunSessionService {
             await installSlashCommands();
             await installGlobalRules();
             row.status = 'ok';
-            row.verb = 'Ready — open a new terminal before running fraim commands.';
+            row.verb = this.embeddedDesktop
+                ? 'Ready — bundled with FRAIM Hub.'
+                : 'Ready — open a new terminal before running fraim commands.';
             delete row.streamOutput;
             const surfaces = this.getConfiguredAgentSurfaces();
             this.state.setupResult = {
@@ -671,7 +693,9 @@ class FirstRunSessionService {
                 completedAt: new Date().toISOString(),
             };
             this.persist();
-            return this.respond('FRAIM is ready. Open a new terminal window so your PATH update takes effect before running fraim commands.', true);
+            return this.respond(this.embeddedDesktop
+                ? 'FRAIM and FRAIM Hub are ready in this installed application.'
+                : 'FRAIM is ready. Open a new terminal window so your PATH update takes effect before running fraim commands.', true);
         }
         catch (error) {
             const detail = error instanceof Error ? error.message : 'Unknown error';
@@ -931,6 +955,18 @@ class FirstRunSessionService {
                 message: "No AI agent (Claude Code or Codex) found on this machine. Let's install one first.",
             };
         }
+        if (this.embeddedDesktop) {
+            (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
+            if (!fs_1.default.existsSync((0, fraim_mcp_latest_launcher_1.getFraimCliShimPath)())) {
+                return {
+                    ok: false,
+                    needsAgentSetup: true,
+                    message: 'FRAIM CLI was not installed into the packaged desktop profile. Re-run FRAIM setup before opening Hub.',
+                };
+            }
+            appendInstallLog('hub-opened embedded-desktop');
+            return { ok: true, desktop: true, message: 'Opening FRAIM Hub in this app.' };
+        }
         try {
             const npxBinary = process.platform === 'win32' ? 'npx.cmd' : 'npx';
             // Issue #866 R1/R2: launch the FRAIM Hub desktop (Electron) app, not a

package/dist/src/fraim/issues.js

@@ -45,8 +45,8 @@ async function fileFraimIssue(params) {
         if (!token) {
             return {
                 success: false,
-                message: `GitHub integration requires GITHUB_TOKEN environment variable.
-                
+                message: `GitHub integration requires GITHUB_TOKEN environment variable.
+                
 Please set GITHUB_TOKEN environment variable to file issues in ${owner}/${repo}.`
             };
         }
@@ -102,8 +102,8 @@ async function listFraimIssuesByReporter(params) {
     if (!token) {
         return {
             success: false,
-            message: `GitHub integration requires GITHUB_TOKEN environment variable.
-                
+            message: `GitHub integration requires GITHUB_TOKEN environment variable.
+                
 Please set GITHUB_TOKEN environment variable to query issues in ${FRAIM_REPO_OWNER}/${FRAIM_REPO_NAME}.`
         };
     }

package/dist/src/local-mcp-server/stdio-server.js

@@ -2209,19 +2209,58 @@ class FraimLocalMCPServer {
                     // nextJobRecommendations, and delegationLedger evidence fields.
                     // The Hub cannot render review bars, next-job chips, or the
                     // delegation board when these fields are absent.
+                    const handoffPhaseMap = await mentor.getJobPhaseMap(args.jobName);
                     const handoffErrors = (0, handoff_contracts_1.validateHandoffContracts)({
                         jobName: args.jobName,
                         currentPhase: args.currentPhase,
                         status: args.status,
                         evidence: args.evidence,
+                        findings: args.findings,
+                        phases: handoffPhaseMap,
                     });
                     if (handoffErrors.length > 0) {
                         const missingField = handoffErrors[0].includes('reviewHandoff') ? 'reviewHandoff'
                             : handoffErrors[0].includes('nextJobRecommendations') ? 'nextJobRecommendations'
-                                : 'delegationLedger';
-                        this.log(`⚠️ Handoff contract enforcement rejected seekMentoring for ${args.jobName}:${args.currentPhase}: ${handoffErrors.join('; ')}`);
-                        const rejection = (0, handoff_contracts_1.buildHandoffRejectionMessage)(args.currentPhase, missingField, handoffErrors);
-                        return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, rejection);
+                                : handoffErrors[0].includes('evidence.approved') ? 'approved'
+                                    : 'delegationLedger';
+                        // Content-scoped applicability (issue #1318 follow-up on #1276): not every
+                        // job's submission phase promises evidence.reviewHandoff. Jobs built on
+                        // rich-review-artifact-contract.md, author-docx.md, or reporting-standards.md
+                        // (analysis reports, DOCX deliverables, operational setup jobs) use a
+                        // different, legitimate completion contract and never instruct the field.
+                        // Enforcing the gate on them would reject a call their own phase text never
+                        // told the agent to satisfy — a genuine stuck-agent risk, not a hypothetical
+                        // one (grep-verified against the registry: ~16 of 183 reviewable jobs). This
+                        // is not a violation at all when the phase never promised the field, so it is
+                        // skipped entirely rather than logged. Escape hatch for the promised case:
+                        // FRAIM_HANDOFF_ENFORCEMENT_MODE=off disables rejection (still logs);
+                        // =warn logs without rejecting; default is unconditional rejection, matching
+                        // how the other three handoff contracts already behave.
+                        const isReviewHandoffField = missingField === 'reviewHandoff';
+                        const reviewHandoffApplies = !isReviewHandoffField
+                            || await mentor.phasePromisesReviewHandoff(args.jobName, args.currentPhase);
+                        // Escape hatch scoped to reviewHandoff only: the other three contracts
+                        // (nextJobRecommendations, delegationLedger, approved) have shipped
+                        // unconditional, uncapped enforcement since #916/#1157 with no reported
+                        // issue, so they keep that behavior — FRAIM_HANDOFF_ENFORCEMENT_MODE never
+                        // relaxes them.
+                        const enforcementMode = isReviewHandoffField
+                            ? (process.env.FRAIM_HANDOFF_ENFORCEMENT_MODE || 'enforce')
+                            : 'enforce';
+                        if (!reviewHandoffApplies) {
+                            // Not gated: this job's submission phase never promised reviewHandoff.
+                        }
+                        else if (enforcementMode === 'off') {
+                            this.log(`⚠️ [reviewHandoff enforcement: off] seekMentoring for ${args.jobName}:${args.currentPhase} would be rejected: ${handoffErrors.join('; ')}`);
+                        }
+                        else if (enforcementMode === 'warn') {
+                            this.log(`⚠️ [reviewHandoff enforcement: warn-only] seekMentoring for ${args.jobName}:${args.currentPhase} would be rejected: ${handoffErrors.join('; ')}`);
+                        }
+                        else {
+                            this.log(`⚠️ Handoff contract enforcement rejected seekMentoring for ${args.jobName}:${args.currentPhase}: ${handoffErrors.join('; ')}`);
+                            const rejection = (0, handoff_contracts_1.buildHandoffRejectionMessage)(args.currentPhase, missingField, handoffErrors);
+                            return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, rejection);
+                        }
                     }
                     return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, tutoringResponse.message);
                 }

package/dist/src/mcp/tool-schemas.js

@@ -42,19 +42,19 @@ const getToolDefinitions = (options = {}) => {
         ? ['sessionId', ...fields]
         : fields;
     const fraimConnectDescription = isLocalProxySurface
-        ? `Bootstrap and initialize a FRAIM session and obtain the sessionId used by active FRAIM workflow tools. Use this after explicit FRAIM activation: the user invoked FRAIM, named a FRAIM job, asked for FRAIM job recommendations, or the active surface selected a FRAIM job. Must be called before any FRAIM workflow tool calls. For ordinary requests, do not start a FRAIM session or scan the catalog.
-
-Example:
-{
-  "agent": {"name": "Claude", "model": "claude-3.5-sonnet"}
+        ? `Bootstrap and initialize a FRAIM session and obtain the sessionId used by active FRAIM workflow tools. Use this after explicit FRAIM activation: the user invoked FRAIM, named a FRAIM job, asked for FRAIM job recommendations, or the active surface selected a FRAIM job. Must be called before any FRAIM workflow tool calls. For ordinary requests, do not start a FRAIM session or scan the catalog.
+
+Example:
+{
+  "agent": {"name": "Claude", "model": "claude-3.5-sonnet"}
 }`
-        : `Bootstrap and initialize a FRAIM session and obtain the sessionId used by active FRAIM workflow tools. Use this after explicit FRAIM activation: the user invoked FRAIM, named a FRAIM job, asked for FRAIM job recommendations, or the active surface selected a FRAIM job. Must be called before any FRAIM workflow tool calls. For ordinary requests, do not start a FRAIM session or scan the catalog.
-
-Hosted marketplace clients may call this with only agent information. If machine or repository context is omitted, FRAIM creates a hosted marketplace session context automatically.
-
-Example:
-{
-  "agent": {"name": "ChatGPT", "model": "gpt-5"}
+        : `Bootstrap and initialize a FRAIM session and obtain the sessionId used by active FRAIM workflow tools. Use this after explicit FRAIM activation: the user invoked FRAIM, named a FRAIM job, asked for FRAIM job recommendations, or the active surface selected a FRAIM job. Must be called before any FRAIM workflow tool calls. For ordinary requests, do not start a FRAIM session or scan the catalog.
+
+Hosted marketplace clients may call this with only agent information. If machine or repository context is omitted, FRAIM creates a hosted marketplace session context automatically.
+
+Example:
+{
+  "agent": {"name": "ChatGPT", "model": "gpt-5"}
 }`;
     return [
         {
@@ -198,12 +198,12 @@ Example:
         },
         {
             name: 'get_fraim_file',
-            description: `Get a specific skill, rule, or reference file from the FRAIM registry by path.
-
-For running FRAIM jobs, use get_fraim_job instead — do NOT call get_fraim_file for job execution.
-
-Examples:
-- get_fraim_file({ path: "skills/communication/active-listening.md" })
+            description: `Get a specific skill, rule, or reference file from the FRAIM registry by path.
+
+For running FRAIM jobs, use get_fraim_job instead — do NOT call get_fraim_file for job execution.
+
+Examples:
+- get_fraim_file({ path: "skills/communication/active-listening.md" })
 - get_fraim_file({ path: "rules/local-development.md" })`,
             annotations: readOnlyClosedWorldAnnotations,
             inputSchema: {
@@ -224,13 +224,13 @@ Examples:
         },
         {
             name: 'get_fraim_job',
-            description: `Execute a named FRAIM job after explicit FRAIM activation. Call this tool whenever the user asks to run, start, or execute a named FRAIM job. Returns phased instructions — follow each phase and call seekMentoring to advance phases.
-
-Do NOT use get_fraim_file to load job content. Always use get_fraim_job for job execution.
-
-Examples:
-- get_fraim_job({ job: "feature-specification" })
-- get_fraim_job({ job: "technical-design" })
+            description: `Execute a named FRAIM job after explicit FRAIM activation. Call this tool whenever the user asks to run, start, or execute a named FRAIM job. Returns phased instructions — follow each phase and call seekMentoring to advance phases.
+
+Do NOT use get_fraim_file to load job content. Always use get_fraim_job for job execution.
+
+Examples:
+- get_fraim_job({ job: "feature-specification" })
+- get_fraim_job({ job: "technical-design" })
 - get_fraim_job({ job: "feature-implementation" })`,
             annotations: readOnlyClosedWorldAnnotations,
             inputSchema: {
@@ -263,11 +263,11 @@ Examples:
         },
         {
             name: 'file_fraim_github_issue',
-            description: `Create a GitHub issue in the FRAIM repository.
-      
-Use this tool when you need to report a bug, request a feature from FRAIM. Do not use this tool to file issues in other repositories.
-Supports dry-run mode to preview the operation.
-
+            description: `Create a GitHub issue in the FRAIM repository.
+      
+Use this tool when you need to report a bug, request a feature from FRAIM. Do not use this tool to file issues in other repositories.
+Supports dry-run mode to preview the operation.
+
 This tool accepts text only. If visual evidence is needed, upload images to a stable shared HTTPS URL first and include those URLs in the issue body as markdown images or plain links. Do not include local file paths or base64-encoded image data in the issue body.`,
             annotations: writeOpenWorldAnnotations,
             inputSchema: {
@@ -297,16 +297,16 @@ This tool accepts text only. If visual evidence is needed, upload images to a st
         },
         {
             name: 'list_my_fraim_github_issues',
-            description: `List issues the current FRAIM user filed into the FRAIM GitHub repository.
-
-This tool is the read-side companion to file_fraim_github_issue. Use it when you need a simple list of issues filed by the current FRAIM user into the FRAIM repository.
-
-Returns only:
-- issue number
-- title
-- status
-- created date
-
+            description: `List issues the current FRAIM user filed into the FRAIM GitHub repository.
+
+This tool is the read-side companion to file_fraim_github_issue. Use it when you need a simple list of issues filed by the current FRAIM user into the FRAIM repository.
+
+Returns only:
+- issue number
+- title
+- status
+- created date
+
 Do not use this tool for other repositories or external project issue trackers.`,
             annotations: readOnlyOpenWorldAnnotations,
             inputSchema: {

package/dist/src/middleware/telemetry.js

@@ -84,9 +84,9 @@ class TelemetryMiddleware {
                     jsonrpc: '2.0',
                     error: {
                         code: -32600,
-                        message: `Missing Session ID. REQUIRED ACTION:
-1. Call 'fraim_connect' first
-2. Capture the returned sessionId
+                        message: `Missing Session ID. REQUIRED ACTION:
+1. Call 'fraim_connect' first
+2. Capture the returned sessionId
 3. Include that sessionId on every subsequent FRAIM tool call (params.sessionId or params.arguments.sessionId).`
                     },
                     id: req.body?.id || null
@@ -97,24 +97,24 @@ class TelemetryMiddleware {
             if (!isActive) {
                 const sessionStartGuidance = isProxiedAgentCall
                     ? `Session Not Started. REQUIRED ACTION: Call 'fraim_connect' tool first, then include the returned sessionId on every subsequent FRAIM tool call.`
-                    : `Session Not Started. REQUIRED ACTION: Call 'fraim_connect' tool first with these parameters:
-
-{
-  "agent": {
-    "name": "YourAgentName",
-    "model": "your-model-name"
-  },
-  "machine": {
-    "hostname": "use os.hostname()",
-    "platform": "use process.platform"
-  },
-  "repo": {
-    "url": "git remote URL",
-    "owner": "repo owner",
-    "name": "repo name"
-  }
-}
-
+                    : `Session Not Started. REQUIRED ACTION: Call 'fraim_connect' tool first with these parameters:
+
+{
+  "agent": {
+    "name": "YourAgentName",
+    "model": "your-model-name"
+  },
+  "machine": {
+    "hostname": "use os.hostname()",
+    "platform": "use process.platform"
+  },
+  "repo": {
+    "url": "git remote URL",
+    "owner": "repo owner",
+    "name": "repo name"
+  }
+}
+
 After successful fraim_connect, all other FRAIM tools will work. This is required for telemetry and session management.`;
                 return res.status(400).json({
                     jsonrpc: '2.0',