engineering-memory 1.11.6 → 1.11.8

package/dispatcher/sections.mjs

@@ -27,6 +27,8 @@ Do not block independent task work on \`memory.propose_revision\` drafting, subm
 
 Use the host's native questionnaire for every question to the user, including implementation choices, names, clarification, branch/worktree decisions and delivery. For a required decision, use \`questionnaire.ask\` to open a durable native MCP form and \`questionnaire.resume\` to return to the same unanswered question. Read the skill's questionnaires reference first. Never use request_user_input_async for a required decision: it does not wait for an answer. When the durable form is unavailable, use a blocking native control only where the host permits it: request_user_input in Codex or AskUserQuestion in Claude. Never replace the questionnaire with a chat instruction such as 'type this', 'reply yes', or 'write X if you want Y'. Do not open a survey web page. If the required native control is unavailable or prohibited for that kind of question, follow the host's tool restrictions, explain the limitation, and continue only work already authorized; do not fabricate a survey or silently choose an answer. A timeout, dismissed form, empty response or ended turn is not an answer. Keep the decision pending and resume it; do not start dependent work or report it as resolved. Existing answers remain valid through retries and handoffs.
 
+When a durable MCP form cannot be displayed, read its \`hostFallback\` or call \`questionnaire.resume\` with \`presentation: host_native\` to get the original question without reopening the MCP form. Display the same question, all choices and notices through a blocking native control only if the host permits that control for this decision. After an actual native answer, call \`questionnaire.answer_from_host\` with the unchanged questionnaireId, requestKey and contentHash, the hostTool name and the returned choice/text. This is an agent-reported relay, not MCP transport attestation. Then retry the owning operation; its authority, content and version checks still apply. Never relay prose consent, a default, an asynchronous response or a cancelled/declined/missing answer. Decline alone is not proof that the host cannot display forms. Keep the decision pending if no permitted native control can represent it.
+
 When the repository is unbound, use the native questionnaire required by the skill. Do not silently create or bind a project. Do not open a survey web page.
 
 For project creation or adoption, read the skill's project-onboarding reference. Use read-only maturity evidence, then native selection of greenfield, exhaustive adoption or phased rework. A missing folder or Git repository uses preparation:true questionnaires before project.initialize. Recognize later memory-refresh intent semantically and confirm its scope natively; never trigger it from a fixed word list. Adoption and refresh cover architecture, state, services, network, data, screens and cross-module flows, not just page logic.`;

package/package.json

@@ -1,29 +1,29 @@
-{
-  "name": "engineering-memory",
-  "version": "1.11.6",
-  "description": "Installs the Engineering Memory skill and its local MCP bridge. Sign in after installing; your organization and project are resolved from your account.",
-  "license": "UNLICENSED",
-  "type": "module",
-  "engines": {
-    "node": ">=20"
-  },
-  "bin": {
-    "engineering-memory": "bin/engineering-memory.mjs"
-  },
-  "files": [
-    "bin",
-    "dispatcher",
-    "lib",
-    "install",
-    "skill",
-    "runtime"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/server": "2.0.0",
-    "minimatch": "10.2.6",
-    "zod": "4.4.3"
-  },
-  "engineeringMemory": {
-    "apiUrl": "https://coral-app-zqmj6.ondigitalocean.app"
-  }
-}
+{
+  "name": "engineering-memory",
+  "version": "1.11.8",
+  "description": "Installs the Engineering Memory skill and its local MCP bridge. Sign in after installing; your organization and project are resolved from your account.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "engineering-memory": "bin/engineering-memory.mjs"
+  },
+  "files": [
+    "bin",
+    "dispatcher",
+    "lib",
+    "install",
+    "skill",
+    "runtime"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "minimatch": "10.2.6",
+    "zod": "4.4.3"
+  },
+  "engineeringMemory": {
+    "apiUrl": "https://coral-app-zqmj6.ondigitalocean.app"
+  }
+}

package/runtime/build.json

@@ -0,0 +1,3 @@
+{
+  "gitHead": "eefcf3aac9c83ba9d0126d05309ca100947317d3"
+}

package/runtime/dist/src/git/verification-gate.js

@@ -50,9 +50,9 @@ export class VerificationGate {
         }, this.root);
     }
     async rebindWorktreeOwnership(repoRoot, taskId, previous, generation) {
-        const fingerprint = await this.git.fingerprint(repoRoot);
-        const identity = worktreeIdentity(await this.git.findRoot(repoRoot));
-        const path = this.pathFor(fingerprint, identity, taskId);
+        const repository = await this.repositories.resolve(repoRoot);
+        const identity = worktreeIdentity(repository.repoRoot);
+        const path = this.pathFor(repository.repoFingerprint, identity, taskId);
         const receipt = await readJson(path, this.root);
         if (!receipt || receipt.taskId !== taskId || receipt.worktreeGeneration !== previous)
             return;

package/runtime/dist/src/mcp/questionnaire-tools.js

@@ -10,13 +10,22 @@ export async function askQuestionnaire(server, service, input, context, previous
 }
 export async function resumeQuestionnaire(server, service, input, context) {
     try {
-        return await present(server, service, await service.questionnaireResume(input), input.repoRoot, context, input.preparation);
+        return await present(server, service, await service.questionnaireResume(input), input.repoRoot, context, input.preparation, input.presentation);
     }
     catch (error) {
         return failure(error);
     }
 }
-async function present(server, service, record, repoRoot, context, preparation) {
+export async function answerQuestionnaireFromHost(service, input) {
+    try {
+        const resolved = await service.questionnaireAnswerFromHost(input);
+        return answered(resolved.record, resolved.answer, resolved.replayed);
+    }
+    catch (error) {
+        return failure(error);
+    }
+}
+async function present(server, service, record, repoRoot, context, preparation, presentation) {
     if (record.status === 'withdrawn')
         return result({
             questionnaireId: record.questionnaireId,
@@ -28,6 +37,8 @@ async function present(server, service, record, repoRoot, context, preparation)
         return answered(record, record.answer, true);
     if (context.mcpReq.signal.aborted)
         return pending(record, 'interrupted');
+    if (presentation === 'host_native')
+        return pending(record, 'host_native_requested');
     const responses = context.mcpReq.inputResponses;
     const response = inputResponse(responses, record.requestKey);
     if (response.kind === 'elicit' && response.action === 'accept') {
@@ -53,15 +64,12 @@ async function present(server, service, record, repoRoot, context, preparation)
     const elicitation = capabilities?.elicitation;
     if (!elicitation || (!elicitation.form && elicitation.url !== undefined))
         return pending(record, 'native_form_unavailable');
-    const presentationNotice = /^memory-batch-[a-f0-9]{64}-[0-9]+$/.test(record.questionnaireId)
-        ? 'For an unversioned project proposal, approval updates legacy memory only. Source-aware tasks cannot read it until an inspection explicitly retains it. Check each sourceApplicabilityNotice in memory.list_proposals before approving.'
-        : undefined;
     const copy = questionnaireCopy[record.language ?? 'en'];
     return inputRequired({
         inputRequests: {
             [record.requestKey]: inputRequired.elicit({
                 mode: 'form',
-                message: `${record.message}${presentationNotice ? `\n\n${presentationNotice}` : ''}\n\n${copy.pending}${record.allowFreeText ? copy.freeText : ''}${record.textField ? copy.storedText : ''}`,
+                message: presentationMessage(record),
                 requestedSchema: {
                     type: 'object',
                     properties: {
@@ -122,14 +130,33 @@ const questionnaireCopy = {
         otherAnswer: 'Diğer yanıt',
     },
 };
+function presentationMessage(record) {
+    const notice = /^memory-batch-[a-f0-9]{64}-[0-9]+$/.test(record.questionnaireId)
+        ? 'For an unversioned project proposal, approval updates legacy memory only. Source-aware tasks cannot read it until an inspection explicitly retains it. Check each sourceApplicabilityNotice in memory.list_proposals before approving.'
+        : undefined;
+    const copy = questionnaireCopy[record.language ?? 'en'];
+    return `${record.message}${notice ? `\n\n${notice}` : ''}\n\n${copy.pending}${record.allowFreeText ? copy.freeText : ''}${record.textField ? copy.storedText : ''}`;
+}
 function pending(record, reason) {
     return result({
         questionnaireId: record.questionnaireId,
         status: 'pending',
         reason,
         answerAvailable: false,
+        hostFallback: {
+            operation: 'questionnaire.answer_from_host',
+            questionnaireId: record.questionnaireId,
+            requestKey: record.requestKey,
+            contentHash: record.contentHash,
+            message: presentationMessage(record),
+            options: record.options,
+            language: record.language ?? 'en',
+            allowFreeText: record.allowFreeText,
+            ...(record.textField ? { textField: record.textField } : {}),
+            instructions: 'Only if the host permits a blocking native control for this decision, display this exact question, all options and notices in AskUserQuestion or request_user_input. Relay only the actual returned answer with these unchanged bindings. Closing, declining, timeout, prose consent and missing answers are not native answers. Do not reopen a dismissed question in a loop or label decline as proof of host incompatibility. The relay records agent-reported provenance, not MCP transport attestation. Retry the owning operation after acceptance; its authority and version checks still apply.',
+        },
         nextAction: reason === 'native_form_unavailable'
-            ? 'This host does not advertise native MCP forms. The decision remains pending. Explain the limitation and continue only independently authorized work. Use a supported native host and questionnaire.resume to answer; do not silently substitute an asynchronous question.'
+            ? 'This host does not advertise native MCP forms. The decision remains pending. Explain the limitation and continue only independently authorized work. Use hostFallback only with a permitted blocking native control; otherwise keep pending. Never substitute an asynchronous question.'
             : 'The decision remains pending without expiry. Call questionnaire.resume with this questionnaireId to show the same question again. Do not infer an answer or continue dependent work.',
     });
 }
@@ -140,6 +167,7 @@ function answered(record, answer, replayed) {
         answerAvailable: answer !== undefined,
         ...(answer ? { answer } : {}),
         replayed,
+        ...(record.answerSource ? { answerSource: record.answerSource } : {}),
         ...(!answer
             ? {
                 nextAction: 'The free-text answer was accepted earlier but was not stored for privacy. It cannot be recovered or inferred. Use the original answer if still present in this conversation; otherwise collect it again through a new questionnaire or supported native input before dependent work.',

package/runtime/dist/src/mcp/tool-definitions.js

@@ -1,7 +1,7 @@
 import * as z from 'zod/v4';
 import { validationIds } from '../runtime/bridge-service.js';
-import { questionnaireDefinitionSchema } from '../runtime/questionnaire-store.js';
-import { askQuestionnaire, resumeQuestionnaire } from './questionnaire-tools.js';
+import { hostAnswerSchema, questionnaireDefinitionSchema } from '../runtime/questionnaire-store.js';
+import { answerQuestionnaireFromHost, askQuestionnaire, resumeQuestionnaire, } from './questionnaire-tools.js';
 const optionalRepoRoot = z.string().min(1).optional();
 const stringList = z.array(z.string().min(1));
 const jsonValue = z.lazy(() => z.union([
@@ -58,6 +58,7 @@ export const engineeringMemoryToolNames = [
     'audit.list',
     'questionnaire.ask',
     'questionnaire.resume',
+    'questionnaire.answer_from_host',
     'questionnaire.withdraw',
     'session.entry',
     'session.set_decision',
@@ -152,6 +153,13 @@ const reconciliationEntry = z.object({
     reason: z.string().optional(),
 });
 export function registerQuestionnaireTools(server, service) {
+    server.registerTool('questionnaire.answer_from_host', {
+        description: 'Relay an actual answer from a host-permitted blocking native AskUserQuestion or request_user_input control to the exact durable question. First read hostFallback from the pending operation or questionnaire.resume with presentation host_native, display its unchanged question/options/notices and await the real native result. Never infer answers, use chat consent, asynchronous controls, defaults or a declined/dismissed form. The hostTool field is agent-reported provenance, not transport-verified attestation. Bind requestKey and contentHash exactly; changed scope, withdrawn questions, invalid or conflicting answers are refused. This only saves the answer; retry the owning operation for current authority and version checks.',
+        inputSchema: hostAnswerSchema.extend({
+            repoRoot: optionalRepoRoot,
+            preparation: z.boolean().optional(),
+        }),
+    }, async (input) => answerQuestionnaireFromHost(service, input));
     server.registerTool('questionnaire.withdraw', {
         description: 'Withdraw a pending decision only when the user explicitly cancels that decision or its owning workflow. This is not approval. An answered decision is immutable. Interruption, timeout and dismissal alone never authorize withdrawal.',
         inputSchema: z.strictObject({
@@ -183,18 +191,19 @@ export function registerQuestionnaireTools(server, service) {
         }
     });
     server.registerTool('questionnaire.ask', {
-        description: 'Persist a required decision before displaying a native questionnaire. Write the message and labels in the conversation language and set language (tr or en) for the native form help. Use a questionnaireId unique to this decision occurrence or task, and reuse it only for identical retries. A later decision or changed wording/options requires a new id. Only a schema-validated native acceptance answers it. Dismissal, timeout and missing replies remain pending without expiry. Never supply answers in tool arguments. Do not put personal information or secrets in the question or options. Free text is returned once and never stored; use explicit options for replayable decisions.',
+        description: 'Persist a required decision before displaying a native questionnaire. Write the message and labels in the conversation language and set language (tr or en) for the native form help. Use a questionnaireId unique to this decision occurrence or task, and reuse it only for identical retries. A later decision or changed wording/options requires a new id. Only a schema-validated native acceptance answers it. Dismissal, timeout and missing replies remain pending without expiry. Never supply answers in questionnaire.ask arguments; use questionnaire.answer_from_host only after an actual permitted blocking native answer. Do not put personal information or secrets in the question or options. Free text is returned once and never stored; use explicit options for replayable decisions.',
         inputSchema: questionnaireDefinitionSchema.extend({
             repoRoot: optionalRepoRoot,
             preparation: z.boolean().optional(),
         }),
     }, async (input, context) => await askQuestionnaire(server, service, input, context));
     server.registerTool('questionnaire.resume', {
-        description: 'Display the original durable questionnaire after interruption or return its saved accepted choice. No timeout or dismissal resolves a pending question. A saved free-text receipt cannot replay the text and must never be treated as a recovered answer.',
+        description: 'Display the original durable questionnaire after interruption or return its saved accepted choice. No timeout or dismissal resolves a pending question. A saved free-text receipt cannot replay the text and must never be treated as a recovered answer. presentation host_native returns the original question and bindings for a permitted blocking host control without reopening the MCP form.',
         inputSchema: z.strictObject({
             repoRoot: optionalRepoRoot,
             questionnaireId: z.string().regex(/^[A-Za-z0-9_-]{1,100}$/),
             preparation: z.boolean().optional(),
+            presentation: z.literal('host_native').optional(),
         }),
     }, async (input, context) => await resumeQuestionnaire(server, service, input, context));
 }

package/runtime/dist/src/runtime/bridge-service.js

@@ -66,7 +66,18 @@ export class BridgeService {
         if (stableStringify(scope) !== stableStringify(input.scope)) {
             throw refuse('The account or repository binding changed while the questionnaire was open.', 'session.entry');
         }
-        return await this.dependencies.questionnaires.accept(scope, input.questionnaireId, input.requestKey, input.answer);
+        return await this.dependencies.questionnaires.accept(scope, input.questionnaireId, input.requestKey, input.answer, input.answerSource);
+    }
+    async questionnaireAnswerFromHost(input) {
+        const record = await this.questionnaireResume(input);
+        if (record.requestKey !== input.requestKey || record.contentHash !== input.contentHash) {
+            throw refuse('The host answer belongs to a different question or content. Read the original with questionnaire.resume; do not reuse this answer for a changed decision.', 'questionnaire.resume');
+        }
+        return this.questionnaireAccept({
+            ...input,
+            scope: record.scope,
+            answerSource: { kind: 'host_native_relay', hostTool: input.hostTool },
+        });
     }
     async questionnaireScope(repoRoot, preparation = false) {
         await this.dependencies.principalState?.ensure();
@@ -388,9 +399,15 @@ export class BridgeService {
                 (repository.projectId && repository.projectId !== projectId)) {
                 throw refuse('The live task belongs to a different project than the one this repository is bound to.', 'project.resolve');
             }
-            if (pointer?.worktreeGeneration && this.dependencies.worktreePool) {
+            const adoptable = pointer &&
+                !pointer.worktreeGeneration &&
+                normalizeTaskMode(pointer.mode) !== 'read_only' &&
+                this.dependencies.worktreePool
+                ? await this.dependencies.worktreePool.find(projectId, taskSlug, repository.repoRoot)
+                : null;
+            if (pointer && this.dependencies.worktreePool && (pointer.worktreeGeneration || adoptable)) {
                 const pool = this.dependencies.worktreePool;
-                const previous = await pool.find(projectId, taskSlug, repository.repoRoot);
+                const previous = adoptable ?? (await pool.find(projectId, taskSlug, repository.repoRoot));
                 if (previous && previous.repoRoot !== repository.repoRoot)
                     return asJsonValue({
                         worktreeResumeRequired: true,
@@ -400,8 +417,11 @@ export class BridgeService {
                         nextAction: 'Call session.resume from this returned repoRoot and use it for every subsequent command.',
                     });
                 const sourceCommit = previous?.baseCommit ?? pointer.source?.sourceCommit;
+                const branch = pointer.worktreeGeneration
+                    ? pointer.branch
+                    : (previous?.branch ?? pointer.branch);
                 if ((!sourceCommit && !(previous && previous.baseCommit === null && !previous.managed)) ||
-                    pointer.branch === undefined)
+                    branch === undefined)
                     throw refuse('The task branch and base must be restored before resuming its worktree.', 'worktree.reconcile');
                 const allocation = await pool.allocate({
                     projectId,
@@ -409,7 +429,7 @@ export class BridgeService {
                     repoFingerprint: repository.repoFingerprint,
                     repoRoot: repository.repoRoot,
                     externalTaskId: taskSlug,
-                    branch: pointer.branch,
+                    branch,
                     baseCommit: sourceCommit ?? null,
                     keepCurrent: previous ? !previous.managed : false,
                     resume: true,
@@ -422,6 +442,7 @@ export class BridgeService {
                     ...pointer,
                     worktreeId: sha256(allocation.repoRoot),
                     worktreeGeneration: allocation.generation,
+                    ...(branch !== undefined ? { branch } : {}),
                 };
                 await this.dependencies.activeContexts.save(pointer);
                 if (allocation.repoRoot !== repository.repoRoot)
@@ -643,7 +664,10 @@ export class BridgeService {
                     localPendingDeliveryCount: localJournal.pendingDeliveryCount,
                     conflicts,
                     requiresAttention: conflicts.length > 0,
-                    editLeaseAllowed: conflicts.length === 0 || offlineDevelopmentAllowed,
+                    editLeaseAllowed: backendTask.status !== 'closed' &&
+                        backendTask.status !== 'abandoned' &&
+                        backendSession.status !== 'closed' &&
+                        (conflicts.length === 0 || offlineDevelopmentAllowed),
                     offlineDevelopmentOnly: offlineDevelopmentAllowed,
                     recoveredVerification,
                 },
@@ -1870,11 +1894,26 @@ export class BridgeService {
             const pool = this.dependencies.worktreePool;
             if (!projectId || !pool)
                 throw refuse('Resolve the project with a pool-capable client.', 'project.resolve');
-            if (operation === 'list' || operation === 'reconcile')
+            if (operation === 'list' || operation === 'reconcile') {
+                const managedRoot = await pool.managedRoot();
                 return asJsonValue({
                     items: await pool.reconcile(projectId, repository.repoRoot, await this.poolPolicy()),
                     selected: await pool.forPath(projectId, repository.repoRoot),
+                    managedRoot,
+                    ...(managedRoot.problem || managedRoot.synced
+                        ? {
+                            notice: [
+                                ...(managedRoot.problem ? [managedRoot.problem] : []),
+                                ...(managedRoot.synced
+                                    ? [
+                                        `Managed worktrees are created under ${managedRoot.root}, which a cloud sync client watches, so every Git operation there is re-scanned and uploaded. To create new worktrees elsewhere, write {"root": "<absolute directory>"} to ${managedRoot.override}; it takes effect for the next allocation, and existing worktrees keep working where they are.`,
+                                    ]
+                                    : []),
+                            ].join(' '),
+                        }
+                        : {}),
                 });
+            }
             if (operation === 'release_unowned') {
                 const entry = await pool.forPath(projectId, repository.repoRoot);
                 if (!entry || !input.sourceCommit || !input.generation || !input.decisionId)
@@ -1960,6 +1999,21 @@ export class BridgeService {
             resume: Boolean(existing),
         }, await this.poolPolicy(true));
         this.poolAllocations.set(allocation.repoRoot, allocation);
+        if (existing && allocation.repoRoot === repository.repoRoot) {
+            const current = await this.dependencies.activeContexts.loadForSlug(repository.repoFingerprint, input.externalTaskId);
+            if (current &&
+                current.taskSlug === input.externalTaskId &&
+                !current.worktreeGeneration &&
+                normalizeTaskMode(current.mode) !== 'read_only')
+                await this.dependencies.activeContexts.save({
+                    ...current,
+                    worktreeId: sha256(allocation.repoRoot),
+                    worktreeGeneration: allocation.generation,
+                    ...(current.branch === undefined && allocation.branch !== null
+                        ? { branch: allocation.branch }
+                        : {}),
+                });
+        }
         return asJsonValue({
             ...allocation,
             kept: !allocation.managed,
@@ -1973,11 +2027,10 @@ export class BridgeService {
         const entry = await pool.forPath(pointer.projectId, repository.repoRoot);
         if (!entry && !pointer.worktreeGeneration)
             return; // existing unmanaged tasks retain their legacy reservation
+        if (entry && entry.externalTaskId !== pointer.taskSlug)
+            throw refuse(`This directory is allocated to task ${entry.externalTaskId}. Resume this task from its own worktree, or reconcile the pool to release the directory.`, 'worktree.reconcile');
         const owned = this.poolAllocations.get(repository.repoRoot);
-        if (!entry ||
-            !owned ||
-            owned.generation !== pointer.worktreeGeneration ||
-            entry.externalTaskId !== pointer.taskSlug)
+        if (!entry || !owned || owned.generation !== pointer.worktreeGeneration)
             throw refuse('Resume this task to acquire its worktree before writing or delivering.', 'session.resume');
         await pool.assertOwnership(pointer.projectId, repository.repoRoot, owned.generation);
     }

package/runtime/dist/src/runtime/questionnaire-store.js

@@ -49,11 +49,26 @@ const storedQuestionSchema = questionnaireDefinitionSchema.extend({
     requestKey: z.string().regex(/^questionnaire_[0-9a-f]{64}$/),
     createdAt: z.string().datetime(),
 });
+export const hostAnswerSchema = z.strictObject({
+    questionnaireId: identifier,
+    requestKey: z.string().regex(/^questionnaire_[0-9a-f]{64}$/),
+    contentHash: z.string().regex(/^[0-9a-f]{64}$/),
+    hostTool: z.enum(['AskUserQuestion', 'request_user_input']),
+    answer: z.strictObject({
+        choice: z.string().min(1).max(80),
+        text: z.string().max(2000).optional(),
+    }),
+});
+const answerSourceSchema = z.strictObject({
+    kind: z.literal('host_native_relay'),
+    hostTool: z.enum(['AskUserQuestion', 'request_user_input']),
+});
 const storedAnswerSchema = z.strictObject({
     requestKey: z.string().regex(/^questionnaire_[0-9a-f]{64}$/),
     answeredAt: z.string().datetime(),
     answerAvailable: z.boolean(),
     withdrawn: z.literal(true).optional(),
+    answerSource: answerSourceSchema.optional(),
     answer: z.strictObject({ choice: z.string(), text: z.string().optional() }).optional(),
 });
 export function questionnaireAnswerSchema(record) {
@@ -194,7 +209,9 @@ export class QuestionnaireStore {
         }
         return records.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
     }
-    async accept(scope, questionnaireId, requestKey, input) {
+    async accept(scope, questionnaireId, requestKey, input, answerSource) {
+        if (answerSource)
+            answerSourceSchema.parse(answerSource);
         const record = await this.get(scope, questionnaireId);
         if (!record || record.requestKey !== requestKey)
             throw new Error('Questionnaire response is stale or belongs to a different scope.');
@@ -209,6 +226,7 @@ export class QuestionnaireStore {
         }
         const receipt = {
             requestKey,
+            ...(answerSource ? { answerSource } : {}),
             answeredAt: new Date().toISOString(),
             answerAvailable: answer.choice !== '__other__',
             ...(answer.choice !== '__other__'

package/runtime/dist/src/runtime/worktree-pool.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { mkdir, readFile, readdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import * as z from 'zod/v4';
 import { GitInspector } from '../git/git-inspector.js';
 import { atomicWrite, assertManagedPath, canonicalPath, ensureManagedDirectory, pathExists, readJson, removeFile, safeSegment, } from '../utilities/files.js';
@@ -37,11 +37,29 @@ const allocationSchema = z.object({
     pendingDelivery: z.boolean(),
     recoveredWithoutReservation: z.boolean().optional(),
     reason: z.string().optional(),
+    root: z.string().optional(),
+    layout: z.union([z.literal(1), z.literal(2)]).optional(),
 });
 const registrySchema = z.object({
     schemaVersion: z.literal(1),
     projects: z.record(z.string(), z.object({ folder: z.string().regex(/^[a-zA-Z0-9._-]+$/), entries: z.array(allocationSchema) })),
 });
+export function managedBase(root, layout) {
+    return layout === 1
+        ? join(root, 'engineeringmemory')
+        : join(root, 'engineering_memory', 'worktrees');
+}
+function projectDirectory(root, folder, layout) {
+    return layout === 1
+        ? join(root, 'engineeringmemory', folder, 'worktrees')
+        : join(root, 'engineering_memory', 'worktrees', folder);
+}
+function worktreeName(folder, slot, layout) {
+    return folder + (layout === 1 ? '-worktree' : '_worktree') + slot;
+}
+function managedPath(root, folder, slot, layout) {
+    return join(projectDirectory(root, folder, layout), worktreeName(folder, slot, layout));
+}
 export class WorktreePool {
     stateRoot;
     ownerId;
@@ -53,6 +71,9 @@ export class WorktreePool {
     startTimes = new Map();
     ownStart;
     documents;
+    legacyDocuments;
+    overrideDocuments;
+    overrideProblem;
     before = new Map();
     pendingWork;
     constructor(stateRoot, options = {}) {
@@ -63,6 +84,7 @@ export class WorktreePool {
         this.now = options.now ?? Date.now;
         this.alive = options.processAlive ?? processAlive;
         this.documents = options.documentsRoot;
+        this.legacyDocuments = options.legacyDocumentsRoot ?? options.documentsRoot;
         this.pendingWork = options.pendingWork ?? (async () => false);
         this.registryPath = join(stateRoot, 'worktree-pool.json');
     }
@@ -79,8 +101,12 @@ export class WorktreePool {
         const commonDir = await this.commonDirectory(input.repoRoot);
         return this.transaction(async (registry) => {
             if (!registry.projects[input.projectId]) {
-                const managedRoot = key(join(await this.documentsDirectory(), 'engineeringmemory'));
-                const orphan = (await this.gitPaths(input.repoRoot)).find((p) => key(p.path).startsWith(managedRoot + (process.platform === 'win32' ? '\\' : '/')));
+                const separator = process.platform === 'win32' ? '\\' : '/';
+                const bases = [];
+                for (const root of await this.scanRoots())
+                    for (const layout of [1, 2])
+                        bases.push(key(managedBase(root, layout)) + separator);
+                const orphan = (await this.gitPaths(input.repoRoot)).find((p) => bases.some((base) => key(p.path).startsWith(base)));
                 if (orphan)
                     throw refuse('Existing managed Git worktrees have no project index. Run worktree.reconcile before allocating more directories.');
             }
@@ -107,7 +133,7 @@ export class WorktreePool {
                     if (paths.some((p) => p.branch === entry.branch && key(p.path) !== key(entry.repoRoot)))
                         throw refuse('The recorded branch is checked out at another location. Reconcile the moved worktree before resuming.');
                     if (paths.some((p) => key(p.path) === key(entry.repoRoot))) {
-                        await assertManagedPath(await this.documentsDirectory(), entry.repoRoot, true);
+                        await assertManagedPath(entry.root ?? (await this.legacyDocumentsDirectory()), entry.repoRoot, true);
                         if (await pathExists(entry.repoRoot))
                             throw refuse('The missing worktree reappeared; reconcile before recovery.');
                         await this.command(input.repoRoot, ['worktree', 'remove', entry.repoRoot]);
@@ -151,8 +177,10 @@ export class WorktreePool {
             if (checkout)
                 throw refuse('This branch already has a checkout. Resume its task instead of creating or resetting the branch.');
             let reusable;
+            const activeRoot = key(await this.documentsDirectory());
+            const legacyRoot = await this.legacyDocumentsDirectory();
             for (const candidate of project.entries
-                .filter((e) => e.managed && e.commonDir === commonDir)
+                .filter((e) => e.managed && e.commonDir === commonDir && key(e.root ?? legacyRoot) === activeRoot)
                 .sort((a, b) => a.slot - b.slot)) {
                 if (candidate.pendingDelivery ||
                     ['creating', 'quarantined'].includes(candidate.phase) ||
@@ -168,7 +196,7 @@ export class WorktreePool {
             if (entry) {
                 const old = structuredClone(entry);
                 await this.releaseReservation(old);
-                const next = await this.entry(input, commonDir, old.repoRoot, old.slot, true);
+                const next = await this.entry(input, commonDir, old.repoRoot, old.slot, true, old.root ?? (await this.legacyDocumentsDirectory()), old.layout ?? 1);
                 project.entries[project.entries.indexOf(entry)] = next;
                 entry = next;
                 await this.save(registry);
@@ -179,14 +207,15 @@ export class WorktreePool {
                 if (project.entries.filter((e) => e.managed).length >= policy.maxWorktrees)
                     throw refuse('The managed worktree limit is full. worktree.list explains protected directories; finish delivery or safely release a clean task. No files were deleted.');
                 let slot = 1;
-                const root = join(await this.documentsDirectory(), 'engineeringmemory', project.folder, 'worktrees');
-                await ensureManagedDirectory(await this.documentsDirectory(), root);
+                const active = await this.documentsDirectory();
+                const root = projectDirectory(active, project.folder, 2);
+                await ensureManagedDirectory(active, root);
                 while (project.entries.some((e) => e.slot === slot) ||
-                    (await pathExists(join(root, project.folder + '-worktree' + slot))))
+                    (await pathExists(join(root, worktreeName(project.folder, slot, 2)))))
                     slot++;
-                const path = join(root, project.folder + '-worktree' + slot);
+                const path = join(root, worktreeName(project.folder, slot, 2));
                 await assertManagedPath(root, path, true);
-                entry = await this.entry(input, commonDir, path, slot, true);
+                entry = await this.entry(input, commonDir, path, slot, true, await this.documentsDirectory(), 2);
                 project.entries.push(entry);
                 await this.save(registry);
                 await this.git.createWorktree(input.repoRoot, input.branch, path, input.baseCommit);
@@ -326,24 +355,19 @@ export class WorktreePool {
             let project = registry.projects[projectId];
             const locations = await this.gitPaths(repoRoot);
             const candidates = [];
-            const managedRoot = join(await this.documentsDirectory(), 'engineeringmemory');
+            const managedRoots = await this.scanRoots();
             for (const location of locations) {
                 if (project?.entries.some((entry) => key(entry.repoRoot) === key(location.path)))
                     continue;
                 if (!(await pathExists(location.path)))
                     continue;
                 const parent = dirname(location.path);
-                const folder = dirname(parent).split(/[\\/]/).pop();
                 const name = location.path.split(/[\\/]/).pop();
-                if (key(parent) !== key(join(managedRoot, folder, 'worktrees')))
-                    continue;
-                const prefix = folder + '-worktree';
-                const slot = Number(name.slice(prefix.length));
-                if (!name.startsWith(prefix) ||
-                    !Number.isSafeInteger(slot) ||
-                    slot < 1 ||
-                    name !== prefix + slot)
+                const placement = this.placement(managedRoots, parent, name);
+                if (!placement)
                     continue;
+                const { documents, folder, slot, layout } = placement;
+                const managedRoot = managedBase(documents, layout);
                 try {
                     await assertManagedPath(managedRoot, location.path, false);
                     if ((await this.commonDirectory(location.path)) !== commonDir)
@@ -357,7 +381,7 @@ export class WorktreePool {
                     continue;
                 if (Object.entries(registry.projects).some(([id, value]) => id !== projectId && key(value.folder) === key(folder)))
                     continue;
-                candidates.push({ path: location.path, folder, slot });
+                candidates.push({ path: location.path, folder, slot, root: documents, layout });
             }
             if (!project) {
                 const folders = [...new Set(candidates.map((candidate) => candidate.folder))];
@@ -405,6 +429,8 @@ export class WorktreePool {
                     repoRoot: await canonicalPath(location.path),
                     slot: location.slot,
                     managed: true,
+                    root: resolve(location.root),
+                    layout: location.layout,
                     externalTaskId: reservation?.decision.externalTaskId ??
                         'unregistered-' + sha256(key(location.path)).slice(0, 20),
                     taskId: reservation?.decision.taskId,
@@ -451,9 +477,11 @@ export class WorktreePool {
         });
         return discoverOnly ? [] : this.list(projectId, policy);
     }
-    async entry(input, commonDir, repoRoot, slot, managed) {
+    async entry(input, commonDir, repoRoot, slot, managed, root, layout) {
         const generation = randomUUID();
         return {
+            ...(root ? { root: resolve(root) } : {}),
+            ...(layout ? { layout } : {}),
             projectId: input.projectId,
             repoFingerprint: input.repoFingerprint,
             commonDir,
@@ -626,9 +654,9 @@ export class WorktreePool {
             .slice(0, 70);
         if (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])$/i.test(folder))
             folder = 'project-' + folder;
-        const root = join(await this.documentsDirectory(), 'engineeringmemory');
         if (Object.values(registry.projects).some((p) => key(p.folder) === key(folder)) ||
-            (await pathExists(join(root, folder))))
+            (await pathExists(projectDirectory(await this.documentsDirectory(), folder, 2))) ||
+            (await pathExists(join(managedBase(await this.legacyDocumentsDirectory(), 1), folder))))
             folder += '-' + sha256(projectId).slice(0, 8);
         if (Object.values(registry.projects).some((p) => key(p.folder) === key(folder)))
             throw refuse('The managed project folder identity conflicts with another project.');
@@ -697,9 +725,87 @@ export class WorktreePool {
             return null;
         }
     }
+    async managedRoot() {
+        const root = managedBase(await this.documentsDirectory(), 2);
+        return {
+            root,
+            override: join(this.stateRoot, 'worktree-root.json'),
+            synced: /onedrive|dropbox|icloud|mobile documents|google\s?drive/i.test(root),
+            ...(this.overrideProblem ? { problem: this.overrideProblem } : {}),
+        };
+    }
     async documentsDirectory() {
+        if (this.overrideDocuments)
+            return this.overrideDocuments;
+        const overridePath = join(this.stateRoot, 'worktree-root.json');
+        this.overrideProblem = undefined;
+        let override = null;
+        try {
+            override = await readJson(overridePath);
+        }
+        catch (error) {
+            this.overrideProblem = `${overridePath} could not be read and is ignored: ${error instanceof Error ? error.message : String(error)}`;
+        }
+        if (override && typeof override.root === 'string' && isAbsolute(override.root)) {
+            try {
+                await mkdir(override.root, { recursive: true }).catch((error) => {
+                    if (!['EEXIST', 'EPERM'].includes(error.code ?? ''))
+                        throw error;
+                });
+                this.overrideDocuments = resolve(override.root);
+                return this.overrideDocuments;
+            }
+            catch (error) {
+                this.overrideProblem = `${overridePath} names ${override.root}, which could not be created and is ignored: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        else if (override) {
+            this.overrideProblem = `${overridePath} must contain {"root": "<absolute directory>"} and is ignored.`;
+        }
+        return this.defaultDocumentsDirectory();
+    }
+    async defaultDocumentsDirectory() {
         if (this.documents)
             return resolve(this.documents);
+        this.documents =
+            process.platform === 'win32' ? (process.env.SystemDrive ?? 'C:') + '\\' : homedir();
+        return resolve(this.documents);
+    }
+    async scanRoots() {
+        return [
+            ...new Map([
+                await this.documentsDirectory(),
+                await this.defaultDocumentsDirectory(),
+                await this.legacyDocumentsDirectory(),
+            ].map((root) => [key(root), root])).values(),
+        ];
+    }
+    placement(roots, parent, name) {
+        for (const documents of roots) {
+            const parentName = parent.split(/[\\/]/).pop() ?? '';
+            const grandParent = dirname(parent);
+            const legacyFolder = grandParent.split(/[\\/]/).pop() ?? '';
+            const attempts = [
+                { folder: parentName, layout: 2 },
+                { folder: legacyFolder, layout: 1 },
+            ];
+            for (const { folder, layout } of attempts) {
+                if (!folder || key(parent) !== key(projectDirectory(documents, folder, layout)))
+                    continue;
+                const prefix = folder + (layout === 1 ? '-worktree' : '_worktree');
+                const slot = Number(name.slice(prefix.length));
+                if (name.startsWith(prefix) &&
+                    Number.isSafeInteger(slot) &&
+                    slot >= 1 &&
+                    name === prefix + slot)
+                    return { documents, folder, slot, layout };
+            }
+        }
+        return null;
+    }
+    async legacyDocumentsDirectory() {
+        if (this.legacyDocuments)
+            return resolve(this.legacyDocuments);
         if (process.platform === 'win32') {
             const result = await this.runner.run('powershell.exe', [
                 '-NoProfile',
@@ -709,19 +815,18 @@ export class WorktreePool {
             ], {});
             if (result.exitCode !== 0 || !result.stdout.trim())
                 throw refuse('The Windows Documents folder could not be resolved.');
-            this.documents = result.stdout.trim();
+            this.legacyDocuments = result.stdout.trim();
         }
         else if (process.platform === 'linux') {
             const result = await this.runner.run('xdg-user-dir', ['DOCUMENTS'], {}).catch(() => null);
-            this.documents =
+            this.legacyDocuments =
                 result?.exitCode === 0 && result.stdout.trim()
                     ? result.stdout.trim()
                     : join(homedir(), 'Documents');
         }
         else
-            this.documents = join(homedir(), 'Documents');
-        await mkdir(this.documents, { recursive: true });
-        return resolve(this.documents);
+            this.legacyDocuments = join(homedir(), 'Documents');
+        return resolve(this.legacyDocuments);
     }
     async transaction(work) {
         await mkdir(this.stateRoot, { recursive: true });
@@ -764,8 +869,10 @@ export class WorktreePool {
                     throw refuse('The registry contains conflicting task ownership. Restore a validated backup with worktree.reconcile.');
                 paths.add(key(entry.repoRoot));
                 if (entry.managed) {
-                    const documents = await this.documentsDirectory();
-                    const expected = join(documents, 'engineeringmemory', project.folder, 'worktrees', project.folder + '-worktree' + entry.slot);
+                    const documents = entry.root ?? (await this.legacyDocumentsDirectory());
+                    const expected = entry.slot
+                        ? managedPath(documents, project.folder, entry.slot, entry.layout ?? 1)
+                        : '';
                     if (!entry.slot || key(entry.repoRoot) !== key(expected))
                         throw refuse('A managed worktree path does not match its project Documents directory. Reconcile before continuing.');
                     await assertManagedPath(documents, entry.repoRoot, true);

package/runtime/dist/src/utilities/files.js

@@ -118,7 +118,10 @@ export async function assertManagedPath(root, target, allowMissingTarget) {
 export async function ensureManagedDirectory(root, directory) {
     const resolvedRoot = resolve(root);
     const resolvedDirectory = ensureWithinRoot(resolvedRoot, directory);
-    await mkdir(resolvedRoot, { recursive: true });
+    await mkdir(resolvedRoot, { recursive: true }).catch((error) => {
+        if (!isNodeError(error) || !['EEXIST', 'EPERM'].includes(error.code ?? ''))
+            throw error;
+    });
     const rootStat = await lstat(resolvedRoot);
     if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) {
         throw new Error(`Managed root must be a real directory: ${resolvedRoot}`);

package/skill/SKILL.md

@@ -13,6 +13,8 @@ Mandatory behavior:
 
 Use the host's native questionnaire for every question to the user, including implementation choices, names, clarification, branch/worktree decisions and delivery. For a required decision, read [questionnaires.md](references/questionnaires.md), then use `questionnaire.ask` to open a durable native MCP form and `questionnaire.resume` to return to the same unanswered question. Never use request_user_input_async for a required decision: it does not wait for an answer. When the durable form is unavailable, use a blocking native control only where the host permits it: request_user_input in Codex or AskUserQuestion in Claude. Never replace the questionnaire with a chat instruction such as 'type this', 'reply yes', or 'write X if you want Y'. Do not open a survey web page. If the required native control is unavailable or prohibited for that kind of question, follow the host's tool restrictions, explain the limitation, and continue only work already authorized; do not fabricate a survey or silently choose an answer. A timeout, dismissed form, empty response or ended turn is not an answer. Keep the decision pending and resume it; do not start dependent work or report it as resolved. Existing answers remain valid through retries and handoffs.
 
+When a durable MCP form cannot be displayed, read its `hostFallback` or call `questionnaire.resume` with `presentation: host_native` to get the original question without reopening the MCP form. Display the same question, all choices and notices through a blocking native control only if the host permits that control for this decision. After an actual native answer, call `questionnaire.answer_from_host` with the unchanged questionnaireId, requestKey and contentHash, the hostTool name and the returned choice/text. This is an agent-reported relay, not MCP transport attestation. Then retry the owning operation; its authority, content and version checks still apply. Never relay prose consent, a default, an asynchronous response or a cancelled/declined/missing answer. Decline alone is not proof that the host cannot display forms. Keep the decision pending if no permitted native control can represent it.
+
 Do not block independent task work on `memory.propose_revision` drafting, submission or approval. Follow [memory-updates.md](references/memory-updates.md): use background agents or concurrent tools when the host permits them and continue useful work; without concurrency, checkpoint the pending draft and defer submission until needed. Wait only at the operation that depends on the proposal or revision. This scheduling rule applies to every project and AI host, while native approval and required task verification remain in force. Apply the same dependency rule to reconciliation, self-review, scaffold receipts, inventory upload, completed-unit evidence and test-result reporting. A bridge result with deliveryStatus pending means durable local recording, so continue independent work without polling or resending. Keep claim acquisition, required approval, edit leases and final verification as real dependencies.
 
 1. Discover the repository binding through `session.entry`. Bindings live in the user-level Engineering Memory state directory, outside the repository and installed runtime. No project settings file is required. For a bound repository, the project's knowledge is in the backend, so answer nothing about it before bootstrapping; the absence of local design files or records says nothing about its stored knowledge.

package/skill/references/lifecycle.md

@@ -14,7 +14,7 @@ Before a new write or scaffold task, read `session.entry` and the project Git pr
 
 Call `task.branch` with the stable `externalTaskId` and `repoRoot`. Its native forms show configured branch names, the current commit, another branch, and the explicit keep-current option. New branches always use a separate managed worktree. Configured remote bases are fetched and their exact commits pinned; after a fetch failure select an explicit local source through a new native decision, never silently use a cached branch. Existing task decisions survive retries and restarts. Resume their recorded branch rather than recreating or resetting it.
 
-Use the returned `repoRoot` for **every** file read/write, terminal, context, validation and Git/delivery operation. The user-local pool is shared by Codex and Claude. Managed directories live in the OS Documents folder under `engineeringmemory/<stable-project-folder>/worktrees/<folder>-worktreeN`; do not supply arbitrary `worktreePath` values or create ad-hoc siblings. Independent clones cannot reuse each other's worktrees. `worktree.list` explains which slots are active, inactive but protected, or safely reusable. The versioned backend policy defaults to 50 directories per project/computer, 30-second heartbeats and 10-minute inactivity. Protected inactive directories still count toward the limit. Only a global admin changes `worktree.set_policy`; it is not an environment setting.
+Use the returned `repoRoot` for **every** file read/write, terminal, context, validation and Git/delivery operation. The user-local pool is shared by Codex and Claude. Managed directories live under `engineering_memory/worktrees/<stable-project-folder>/<folder>_worktreeN`, at the root of the system drive on Windows (`C:\engineering_memory\worktrees\...`) and in the home directory elsewhere, or under the absolute directory named by `worktree-root.json` in the user-level API state directory when that file exists; `worktree.list` reports the effective root, and worktrees created by earlier clients under the Documents folder keep working where they are. Do not supply arbitrary `worktreePath` values or create ad-hoc siblings. Independent clones cannot reuse each other's worktrees. `worktree.list` explains which slots are active, inactive but protected, or safely reusable. The versioned backend policy defaults to 50 directories per project/computer, 30-second heartbeats and 10-minute inactivity. Protected inactive directories still count toward the limit. Only a global admin changes `worktree.set_policy`; it is not an environment setting.
 
 Renew `task.heartbeat` using the exact returned task, path and ownership generation during actual work and at approximately the cached heartbeat interval during long local commands. The bridge renews while its own task operation is running. Never run a perpetual heartbeat for an idle chat or MCP process. Inactivity never authorizes takeover of a live owner or deletion of files. Before writing after interruption, use `session.resume`; follow any returned worktree redirect and resume there. A stale generation cannot renew, release, verify or commit another owner's work.
 

package/skill/references/questionnaires.md

@@ -20,6 +20,30 @@ The host owns the visible form and may impose a transport deadline or close it w
 
 Never replace the questionnaire with a chat instruction such as 'type this', 'reply yes', or 'write X if you want Y'. Do not open a survey web page. Questions and saved answers must not contain credentials, personal data or production payloads. Authentication secrets belong in the existing browser authentication flow. Use an appropriate permitted native control for information that cannot be persisted; do not put it into a durable question's title, options or stored answer.
 
+## Host-native answer relay
+
+When a durable MCP form cannot be displayed, read its `hostFallback` or call `questionnaire.resume` with `presentation: host_native` to get the original question without reopening the MCP form. Display the same question, all choices and notices through a blocking native control only if the host permits that control for this decision. After an actual native answer, call `questionnaire.answer_from_host` with the unchanged questionnaireId, requestKey and contentHash, the hostTool name and the returned choice/text. This is an agent-reported relay, not MCP transport attestation. Then retry the owning operation; its authority, content and version checks still apply. Never relay prose consent, a default, an asynchronous response or a cancelled/declined/missing answer. Decline alone is not proof that the host cannot display forms. Keep the decision pending if no permitted native control can represent it.
+
+For branch preferences, each role remains a separate decision bound to the exact preference
+value and expectedVersion. A combined "yes to all branches" from a different question cannot
+be relayed into three independent forms. Finish each original role question, then retry
+project.set_git_preferences with its original arguments. The backend applies the group only
+when every supplied role is approved and the version and authority still match. A concurrent
+edit requires reading current preferences and fresh decisions for the new version.
+
+Map the native result to the original option id only when the selected label identifies it
+unambiguously; never substitute or omit choices to fit a host limit. If all choices and required
+text cannot be represented by a permitted blocking control, leave the original question pending.
+Do not use this relay to evade host approval restrictions or a user declining the owning action.
+With a saved explicit defer, use a new decisionAttempt only after the user chooses to reconsider.
+
+The relay stores host-native provenance beside the atomic answer. It does not store transcripts,
+personal identities or host tool-call logs. Bounded decision text follows the existing privacy
+checks; unrestricted Other text is returned once and cannot be recovered after restart. Installed
+clients must restart after an upgrade to read the new relay receipt field; old receipts remain
+readable by the new client. No server or SDK can independently prove an agent's claim that a
+host-native form was shown; agents must use only the actual native result they observed.
+
 ## Authentication
 
 When no Engineering Memory session exists, ask whether to sign in, create an account, or skip Engineering Memory for this task. Explain that skip is permitted only for an unbound repository. After sign in or sign up is selected, let the bridge open the browser authentication flow. Never ask for a password in the native questionnaire or chat. If a browser link is expired, rejected, already used, or otherwise unusable, call `auth.signin_browser` with `restart: true` and present only the newly returned URL.