fraim 2.0.311 → 2.0.312

package/dist/src/cli/setup/ide-invocation-surfaces.js

@@ -72,7 +72,7 @@ ${buildDeferredToolBootstrapSection(profile)}1. **Confirm FRAIM activation**:
    If local FRAIM job stubs are present in the workspace, inspect those first and match the request locally. Also inspect \`fraim/personalized-employee/jobs/\` for local overrides or repo-specific jobs. If local files are missing or you cannot inspect workspace files, call \`list_fraim_jobs()\` to view the full catalog, including any proxy-discoverable personalized jobs.
 
 3. **Find the match**:
-   If the user names an exact FRAIM job, call \`get_fraim_job({ job: "<job-name>" })\` directly. Otherwise, match the user's request to a FRAIM job from the local stub catalog, \`fraim/personalized-employee/jobs/\`, or the full \`list_fraim_jobs()\` response. If no exact or high-confidence job match exists, say that no FRAIM job matches and continue with normal tools or ask one concise clarification. Do not pick the nearest catalog job.
+   If the user names an exact FRAIM job, call \`get_fraim_job({ job: "<job-name>" })\` directly. Otherwise, match the user's request to a FRAIM job from the local stub catalog, \`fraim/personalized-employee/jobs/\`, or the full \`list_fraim_jobs()\` response. If no exact or high-confidence job match exists, ask once: "No catalog job matches. Would you like to run this as an ad-hoc task?" On confirmation, call \`get_fraim_job({ job: "adhoc-prompt" })\` and execute it with the user's instructions as the task input — do not pick the nearest catalog job. Do not ask again if the user already provided instructions.
 
 4. **Load the full content**:
    - For jobs, call \`get_fraim_job({ job: "<matched-job-name>" })\`.

package/dist/src/cli/setup/user-level-sync.js

@@ -125,6 +125,10 @@ function ensureUserLevelDependencies(userFraimDir) {
     if (missing.length === 0) {
         return;
     }
+    if (process.env.FRAIM_SKIP_USER_LEVEL_DEP_INSTALL === '1') {
+        console.log(chalk_1.default.yellow(`TEST_MODE: skipping user-level runtime dependency install (${missing.join(', ')}).`));
+        return;
+    }
     console.log(chalk_1.default.blue(`📦 Installing user-level runtime dependencies (${missing.join(', ')})...`));
     try {
         (0, child_process_1.execSync)('npm install --no-audit --no-fund --no-save --no-package-lock --omit=dev', {

package/dist/src/config/persona-capability-bundles.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PERSONA_CAPABILITY_BUNDLES = exports.FREE_JOBS = exports.GENERIC_WORKER_PERSONA_KEY = void 0;
+exports.UNOWNED_EXEMPT_JOBS = exports.PERSONA_CAPABILITY_BUNDLES = exports.FREE_JOBS = exports.GENERIC_WORKER_PERSONA_KEY = void 0;
 exports.isFreeJob = isFreeJob;
 exports.getPersonaCapabilityBundle = getPersonaCapabilityBundle;
 exports.getProtectedPersonaForJob = getProtectedPersonaForJob;
@@ -315,6 +315,17 @@ const GENERIC_WORKER_OWNED_JOBS = new Set([
     'organization-onboarding',
     'organizational-learning-synthesis',
 ]);
+// Jobs intentionally left without a named persona owner. They resolve to null
+// from getProtectedPersonaForJob (runs ungated; Hub attributes them to the
+// DEFAULT_UNASSIGNED_PERSONA_KEY/MANdy — same behavior as today's adhoc runs).
+// validate-job-ownership exempts these from the "every job must have an owner"
+// assertion so the validator still catches accidentally unowned jobs.
+//
+// Issue #1610: adhoc-prompt is a manager-directed fallback job, not tied to any
+// specialist hire, matching the existing no-employee attribution of adhoc runs.
+exports.UNOWNED_EXEMPT_JOBS = new Set([
+    'adhoc-prompt',
+]);
 function getPersonaCapabilityBundle(personaKey) {
     return exports.PERSONA_CAPABILITY_BUNDLES[personaKey];
 }

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

@@ -81,6 +81,7 @@ const skill_include_dedup_js_1 = require("./skill-include-dedup.js");
  */
 class FraimTemplateEngine {
     constructor(opts) {
+        this.configLoadAttempted = false;
         this.userEmail = null;
         this.deliveryTemplatesCache = null;
         this.providerTemplatesCache = {};
@@ -117,6 +118,7 @@ class FraimTemplateEngine {
     }
     setConfig(config) {
         this.config = config;
+        this.configLoadAttempted = true;
     }
     setUserEmail(email) {
         this.userEmail = email;
@@ -124,6 +126,57 @@ class FraimTemplateEngine {
     getUserEmail() {
         return this.userEmail;
     }
+    resolveEmailLazy() {
+        if (this.userEmail)
+            return this.userEmail;
+        try {
+            const dir = (0, project_fraim_paths_1.getUserFraimDirPath)();
+            const prefsPath = (0, path_1.join)(dir, 'preferences.json');
+            if ((0, fs_1.existsSync)(prefsPath)) {
+                const prefs = JSON.parse((0, fs_1.readFileSync)(prefsPath, 'utf8'));
+                if (typeof prefs.userEmail === 'string' && prefs.userEmail) {
+                    this.userEmail = prefs.userEmail;
+                    return this.userEmail;
+                }
+            }
+        }
+        catch { /* ignore */ }
+        return null;
+    }
+    resolveMachineInfoLazy() {
+        if (this.machineInfo)
+            return this.machineInfo;
+        try {
+            this.machineInfo = {
+                hostname: (0, os_1.hostname)(),
+                platform: (0, os_1.platform)(),
+                memory: (0, os_1.totalmem)(),
+                cpus: (0, os_1.cpus)().length
+            };
+        }
+        catch { /* ignore */ }
+        return this.machineInfo;
+    }
+    resolveConfigLazy() {
+        if (this.config)
+            return this.config;
+        // If setConfig() was called explicitly (including with null), respect that — no disk read.
+        if (this.configLoadAttempted)
+            return null;
+        if (!this.projectRoot)
+            return null;
+        try {
+            const configPath = (0, path_1.join)(this.projectRoot, 'fraim', 'config.json');
+            if ((0, fs_1.existsSync)(configPath)) {
+                this.config = JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
+                this.configLoadAttempted = true;
+                return this.config;
+            }
+        }
+        catch { /* ignore */ }
+        this.configLoadAttempted = true;
+        return null;
+    }
     substituteTemplates(content) {
         return this.substituteTemplatesWithNotices(content).content;
     }
@@ -131,15 +184,16 @@ class FraimTemplateEngine {
         let result = content;
         const notices = [];
         const blockingRequirements = [];
-        // Substitute {{proxy.user.email}} with the email captured from fraim_connect
-        if (this.userEmail) {
-            result = result.replace(/\{\{proxy\.user\.email\}\}/g, this.userEmail);
+        // Substitute {{proxy.user.email}} — resolved lazily from preferences.json when fraim_connect was skipped.
+        const resolvedEmail = this.resolveEmailLazy();
+        if (resolvedEmail) {
+            result = result.replace(/\{\{proxy\.user\.email\}\}/g, resolvedEmail);
         }
         // 0. Substitute runtime context tokens: {{agent.*}}, {{machine.*}}, {{repository.*}}
-        //    These come from the fraim_connect payload captured during handshake.
+        //    Machine info is resolved lazily from the OS when fraim_connect was skipped.
         const contexts = {
             agent: this.agentInfo,
-            machine: this.machineInfo,
+            machine: this.resolveMachineInfoLazy(),
             repository: this.repoInfo
         };
         result = result.replace(/\{\{(agent|machine|repository)\.([^}]+)\}\}/g, (match, ns, path) => {
@@ -207,8 +261,9 @@ class FraimTemplateEngine {
             return originalMatch;
         }
         try {
-            if (this.config) {
-                const value = (0, object_utils_1.getNestedValue)(this.config, path);
+            const config = this.resolveConfigLazy();
+            if (config) {
+                const value = (0, object_utils_1.getNestedValue)(config, path);
                 if (value !== undefined) {
                     return typeof value === 'object' ? JSON.stringify(value) : String(value);
                 }
@@ -791,20 +846,25 @@ class FraimLocalMCPServer {
             return;
         }
         if (this.connectSyncInFlight) {
-            await this.connectSyncInFlight;
+            this.maybeRefreshOrgCache(String(requestId));
+            this.maybeRefreshManagerCache(String(requestId));
+            return;
+        }
+        const projectRoot = this.findProjectRoot();
+        this.latestConnectSyncWarning = null;
+        if (!projectRoot || !(0, project_fraim_paths_1.workspaceFraimExists)(projectRoot)) {
+            this.maybeRefreshOrgCache(String(requestId));
+            this.maybeRefreshManagerCache(String(requestId));
+            return;
+        }
+        const reason = this.getLocalCatalogSyncReason(projectRoot);
+        if (!reason) {
+            this.maybeRefreshOrgCache(String(requestId));
+            this.maybeRefreshManagerCache(String(requestId));
             return;
         }
+        this.log(`[req:${requestId}] Refreshing local FRAIM catalog in background because ${reason}`);
         this.connectSyncInFlight = (async () => {
-            const projectRoot = this.findProjectRoot();
-            this.latestConnectSyncWarning = null;
-            if (!projectRoot || !(0, project_fraim_paths_1.workspaceFraimExists)(projectRoot)) {
-                return;
-            }
-            const reason = this.getLocalCatalogSyncReason(projectRoot);
-            if (!reason) {
-                return;
-            }
-            this.log(`[req:${requestId}] Refreshing local FRAIM catalog before fraim_connect because ${reason}`);
             try {
                 await this.performLocalCatalogSync(projectRoot);
                 this.log(`[req:${requestId}] Local FRAIM catalog refresh complete`);
@@ -814,13 +874,10 @@ class FraimLocalMCPServer {
                 this.latestConnectSyncWarning = `Local FRAIM catalog refresh failed: ${message}. Discovery will fall back to remote FRAIM tools until sync succeeds.`;
                 this.logError(`[req:${requestId}] ${this.latestConnectSyncWarning}`);
             }
+            finally {
+                this.connectSyncInFlight = null;
+            }
         })();
-        try {
-            await this.connectSyncInFlight;
-        }
-        finally {
-            this.connectSyncInFlight = null;
-        }
         this.maybeRefreshOrgCache(String(requestId));
         this.maybeRefreshManagerCache(String(requestId));
     }
@@ -905,10 +962,63 @@ class FraimLocalMCPServer {
         }
     }
     /**
-     * Automatically detect repository information from git
+     * Derive the issue worktree directory `prep-issue.sh` would have created for
+     * `issueNumber`, without requiring any caller to supply it (issue #1641
+     * independent-review follow-up: an opt-in `workingDirectory` parameter that
+     * nothing instructs an agent to pass is a recall-dependent fix, not a
+     * mechanical one). `prep-issue.sh` names the worktree deterministically —
+     * `registry/scripts/prep-issue.sh`: `WORKTREE_DIR="$REPO_NAME - Issue
+     * $ISSUE_NUMBER"`, `WORKTREE_PATH="$PARENT_DIR/$WORKTREE_DIR"` — as a sibling
+     * of whatever directory the script was run from, using the repository name
+     * from `fraim/config.json`, not the actual directory's basename. This
+     * reproduces that exact derivation from state this process already has
+     * (`this.workspaceRoot`/`findProjectRoot()` for the parent directory,
+     * `this.config.repository.name` for the repo name, `issueNumber` from the
+     * `seekMentoring` call itself) and returns the candidate only if it actually
+     * exists on disk — never inventing an override for a directory that isn't
+     * there. Returns `null` when any required input is missing or the derived
+     * candidate does not exist, in which case the caller falls back to an
+     * explicit override or the cached default.
+     */
+    deriveIssueWorktreeDirectory(issueNumber) {
+        if (!issueNumber || typeof issueNumber !== 'string' || !issueNumber.trim())
+            return null;
+        const repoName = this.config?.repository?.name;
+        if (!repoName)
+            return null;
+        const primaryRoot = this.workspaceRoot || this.findProjectRoot();
+        if (!primaryRoot)
+            return null;
+        try {
+            const candidate = (0, path_1.join)((0, path_1.dirname)(primaryRoot), `${repoName} - Issue ${issueNumber}`);
+            return (0, fs_1.existsSync)(candidate) ? candidate : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Automatically detect repository information from git.
+     *
+     * `overrideProjectDir` (issue #1641): this server process is long-lived and
+     * its notion of "project root" (`this.workspaceRoot`, from the MCP client's
+     * one-time `roots/list` response, or `process.cwd()` at process start) never
+     * changes for the life of the process. A FRAIM job that moves its actual
+     * work into an issue worktree (a sibling directory created by
+     * `prep-issue.sh`) does so entirely within the calling agent's own shell —
+     * this process is never told. Without an override, `detectRepoInfo()` keeps
+     * reporting the branch of wherever it originally resolved (typically the
+     * primary checkout), not the worktree the agent is actually operating in.
+     * When the caller supplies a real directory (the agent's own known working
+     * directory), that directory is used for this call only: the result is not
+     * written to the process-lifetime `this.repoInfo` cache, so it cannot leak
+     * into unrelated callers that rely on the default project's cached identity.
      */
-    detectRepoInfo() {
-        if (this.repoInfo) {
+    detectRepoInfo(overrideProjectDir) {
+        const useOverride = typeof overrideProjectDir === 'string'
+            && overrideProjectDir.trim() !== ''
+            && (0, fs_1.existsSync)(overrideProjectDir);
+        if (!useOverride && this.repoInfo) {
             return this.repoInfo;
         }
         // Ensure config is loaded before trying to detect repo info
@@ -916,7 +1026,7 @@ class FraimLocalMCPServer {
             this.loadConfig();
         }
         try {
-            const projectDir = this.findProjectRoot() || process.cwd();
+            const projectDir = useOverride ? overrideProjectDir : (this.findProjectRoot() || process.cwd());
             // Try to get git remote URL
             let repoUrl = '';
             try {
@@ -998,6 +1108,15 @@ class FraimLocalMCPServer {
             if (owner) {
                 repoInfo.owner = owner;
             }
+            if (useOverride) {
+                // One-off lookup for a caller-supplied directory: do not clobber the
+                // process-lifetime cache or the default project's usage identifier.
+                const repoLabel = repoInfo.owner
+                    ? `${repoInfo.owner}/${repoInfo.name}`
+                    : repoInfo.projectPath || repoInfo.name;
+                this.log(`Detected repo info for override directory ${projectDir}: ${repoLabel}`);
+                return repoInfo;
+            }
             this.repoInfo = repoInfo;
             this.usageCollector.setRepoIdentifier(repoInfo.url || null);
             const repoLabel = this.repoInfo.owner
@@ -2373,7 +2492,21 @@ class FraimLocalMCPServer {
                     // for this purpose only when a defaultBranch reference point
                     // exists; without it the check cannot classify default-vs-feature
                     // branch, so it must not apply (repo: null).
-                    const handoffRepoInfo = this.detectRepoInfo();
+                    //
+                    // Issue #1641: this process's default project directory (cached
+                    // workspaceRoot / process.cwd()) does not track a worktree the
+                    // agent moved its actual work into. Deriving the expected worktree
+                    // path from prep-issue.sh's own naming convention (repo name +
+                    // issue number, both already known to this process) is mechanical
+                    // and requires no agent action, unlike depending on every job/skill
+                    // that reaches submission to remember to pass a hint — an explicit
+                    // `workingDirectory` remains available as an escape hatch for a
+                    // worktree this derivation cannot find (non-standard layout,
+                    // renamed directory), and wins when supplied. detectRepoInfo() does
+                    // not cache either path, so neither can affect any other lookup.
+                    const explicitWorkingDirectory = typeof args.workingDirectory === 'string' ? args.workingDirectory : undefined;
+                    const derivedWorkingDirectory = this.deriveIssueWorktreeDirectory(args.issueNumber);
+                    const handoffRepoInfo = this.detectRepoInfo(explicitWorkingDirectory || derivedWorkingDirectory || undefined);
                     const handoffRepoState = handoffRepoInfo?.defaultBranch
                         ? { currentBranch: handoffRepoInfo.branch || '', defaultBranch: handoffRepoInfo.defaultBranch }
                         : null;

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

@@ -366,6 +366,10 @@ Do not use this tool for other repositories or external project issue trackers.`
                         type: 'object',
                         description: 'Structured evidence or data collected (e.g., prospect counts, test results). Submit phases should put review artifacts in evidence.reviewHandoff rather than printing raw JSON to the user. Retrospective phases may put follow-on job recommendations in evidence.nextJobRecommendations (array of { jobId, label, reason?, contextSummary? }, max 3) so the work surface can offer them as next steps.',
                         additionalProperties: true
+                    },
+                    workingDirectory: {
+                        type: 'string',
+                        description: 'Absolute path to the directory you are actually working in right now, when it differs from this session\'s default project directory — most commonly an issue worktree created by prep-issue.sh. Pass this on submit-phase calls carrying evidence.reviewHandoff so the review-action-completeness check reads the branch of your real worktree instead of a directory this long-lived session cached earlier. Optional; omit when working in the default project directory.'
                     }
                 },
                 required: requiredWithSession(['jobName', 'jobId', 'issueNumber', 'currentPhase', 'status'])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.311",
+  "version": "2.0.312",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {