engineering-memory 1.11.3 → 1.11.5

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

@@ -0,0 +1,392 @@
+import * as z from 'zod/v4';
+import { branchChoices } from '../runtime/branch-preferences.js';
+import { sha256, stableStringify } from '../utilities/hash.js';
+import { askQuestionnaire } from './questionnaire-tools.js';
+const repo = z.string().min(1);
+const branch = z.string().min(1).max(255);
+const remote = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/);
+const output = (r) => ({
+    content: [{ type: 'text', text: JSON.stringify(r) }],
+    ...(!r.ok ? { isError: true } : {}),
+});
+const json = (value) => JSON.parse(JSON.stringify(value));
+const preference = z.strictObject({
+    answered: z.boolean(),
+    branch: branch.nullable(),
+    remote: remote.nullable(),
+});
+const policy = {
+    expectedVersion: z.number().int().min(1),
+    maxWorktrees: z.number().int().min(1).max(500),
+    heartbeatSeconds: z.number().int().min(5).max(300),
+    inactivitySeconds: z.number().int().min(60).max(86400),
+};
+const baseSchema = z.discriminatedUnion('kind', [
+    z.strictObject({
+        kind: z.literal('current'),
+        commit: z
+            .string()
+            .regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/)
+            .optional(),
+    }),
+    z.strictObject({ kind: z.enum(['development', 'production', 'test']) }),
+    z.strictObject({ kind: z.literal('remote'), remote, branch }),
+    z.strictObject({ kind: z.literal('local'), ref: branch }),
+]);
+export function registerWorktreeTools(server, service) {
+    server.registerTool('project.git_preferences', {
+        description: 'Read the project development/production/test branch preferences and which questions remain unanswered. Only canManage actors may change shared choices; other members may select a task-specific base.',
+        inputSchema: z.strictObject({
+            repoRoot: repo.optional(),
+            projectId: z.string().uuid().optional(),
+        }),
+    }, async (input) => output(await service.projectGitPreferences(input)));
+    server.registerTool('project.set_git_preferences', {
+        description: 'Confirm each supplied shared branch choice with a separate durable native questionnaire, then save against expectedVersion. Explicitly absent production/test branches stay answered. Reconsider a deferred choice with a new decisionAttempt; retries keep the same attempt. Requires project owner/maintainer or organization administrator. Branches are creation preferences, never memory environment labels.',
+        inputSchema: z.strictObject({
+            repoRoot: repo,
+            projectId: z.string().uuid(),
+            expectedVersion: z.number().int().min(0),
+            decisionAttempt: z.number().int().min(1).max(10000).optional(),
+            development: preference.optional(),
+            production: preference.optional(),
+            test: preference.optional(),
+            language: z.enum(['tr', 'en']).default('en'),
+        }),
+    }, async (input, context) => {
+        const current = await service.projectGitPreferences(input);
+        if (!current.ok)
+            return output(current);
+        const prefs = current.data;
+        if (!prefs.canManage)
+            return output({
+                ok: false,
+                error: {
+                    kind: 'bridge_error',
+                    message: 'Choose a base for your own task with task.branch. Shared preferences require a project or organization administrator.',
+                    retryable: false,
+                    recovery: 'task.branch',
+                },
+            });
+        const changes = { expectedVersion: input.expectedVersion };
+        for (const role of ['development', 'production', 'test']) {
+            const value = input[role];
+            if (!value)
+                continue;
+            const digest = sha256(stableStringify({
+                projectId: input.projectId,
+                version: input.expectedVersion,
+                role,
+                value,
+                ...(input.decisionAttempt ? { decisionAttempt: input.decisionAttempt } : {}),
+            }));
+            const question = {
+                repoRoot: input.repoRoot,
+                questionnaireId: 'project-branch-' + digest,
+                message: input.language === 'tr'
+                    ? role +
+                        ' dal tercihi: ' +
+                        (value.branch ? value.remote + '/' + value.branch : 'henüz yok') +
+                        '. Ortak proje ayarını kaydedelim mi?'
+                    : 'Save the shared ' +
+                        role +
+                        ' branch preference: ' +
+                        (value.branch ? value.remote + '/' + value.branch : 'none yet') +
+                        '?',
+                language: input.language,
+                allowFreeText: false,
+                options: [
+                    {
+                        id: 'approve',
+                        label: input.language === 'tr' ? 'Bu tercihi kaydet' : 'Save this choice',
+                    },
+                    {
+                        id: 'defer',
+                        label: input.language === 'tr' ? 'Şimdilik değiştirme' : 'Leave unchanged',
+                    },
+                ],
+            };
+            const form = await askQuestionnaire(server, service, question, context);
+            const record = await service.questionnaireResume({
+                repoRoot: input.repoRoot,
+                questionnaireId: question.questionnaireId,
+            });
+            if (record.status !== 'answered' || record.answer?.choice !== 'approve')
+                return form;
+            changes[role] = json(value);
+        }
+        if (Object.keys(changes).length === 1)
+            return output({ ok: true, data: { unchanged: true } });
+        return output(await service.setProjectGitPreferences(input.projectId, changes));
+    });
+    server.registerTool('worktree.policy', {
+        description: 'Read and cache the backend worktree policy for this client. No environment variable controls the pool limit.',
+        inputSchema: z.strictObject({}),
+    }, async () => output(await service.worktreePolicy()));
+    server.registerTool('worktree.set_policy', {
+        description: 'Update the versioned product worktree policy. Only a global administrator may change these values.',
+        inputSchema: z.strictObject(policy),
+    }, async (input) => output(await service.worktreePolicy(json(input))));
+    server.registerTool('task.branch', {
+        description: 'Choose the task base with durable native forms and allocate a separate managed worktree for every new branch. Configured remote branches are fetched and the exact commit is pinned. Retry/resume preserves the allocation. For an explicitly reconsidered deferred answer supply a new decisionAttempt; retries keep the same attempt. Use the returned repoRoot for ALL commands; keepCurrent is allowed only in a free checkout. A read-only task allocates only when transitioning to write.',
+        inputSchema: z.strictObject({
+            repoRoot: repo,
+            externalTaskId: z.string().min(2).max(160),
+            decisionAttempt: z.number().int().min(1).max(10000).optional(),
+            name: branch.optional(),
+            base: baseSchema.optional(),
+            keepCurrent: z.boolean().optional(),
+            language: z.enum(['tr', 'en']).default('en'),
+        }),
+    }, async (input, context) => {
+        const existing = await service.worktreeTaskAllocation(input);
+        if (existing.ok && existing.data.allocation)
+            return output(await service.taskBranch(input));
+        if (!existing.ok)
+            return output(existing);
+        const current = await service.projectGitPreferences(input);
+        if (!current.ok)
+            return output(current);
+        const prefs = current.data;
+        let base = input.base;
+        let keepCurrent = input.keepCurrent === true;
+        let name = input.name;
+        const taskKey = sha256(input.externalTaskId + (input.decisionAttempt ? ':' + input.decisionAttempt : ''));
+        if (!base && !keepCurrent) {
+            const definition = {
+                repoRoot: input.repoRoot,
+                questionnaireId: 'task-base-select-' + taskKey + '-' + prefs.version,
+                message: input.language === 'tr'
+                    ? 'Bu görev için başlangıç dalını seç.'
+                    : 'Choose the starting branch for this task.',
+                language: input.language,
+                allowFreeText: false,
+                options: branchChoices(prefs, prefs.currentBranch),
+            };
+            const form = await askQuestionnaire(server, service, definition, context);
+            const record = await service.questionnaireResume({
+                repoRoot: input.repoRoot,
+                questionnaireId: definition.questionnaireId,
+            });
+            if (record.status !== 'answered')
+                return form;
+            const choice = record.answer?.choice;
+            if (choice === 'keep') {
+                keepCurrent = true;
+                base = { kind: 'current' };
+            }
+            else if (choice === 'other') {
+                const next = await askText(server, service, input, context, 'other-base', input.language === 'tr'
+                    ? 'Başlangıç için uzak dalın adını seç. origin remote kullanılacak.'
+                    : 'Choose the remote base branch name. The origin remote will be used.');
+                if (!next.value)
+                    return next.form;
+                base = { kind: 'remote', remote: 'origin', branch: next.value };
+            }
+            else if (choice === 'current' ||
+                choice === 'development' ||
+                choice === 'production' ||
+                choice === 'test')
+                base = { kind: choice };
+            else
+                return form;
+        }
+        if (keepCurrent) {
+            base = { kind: 'current' };
+            name = undefined;
+        }
+        base ??= { kind: 'current' };
+        if (base.kind === 'current')
+            base = { kind: 'current', commit: base.commit ?? prefs.currentCommit ?? undefined };
+        if (base.kind === 'development' || base.kind === 'production' || base.kind === 'test') {
+            const selected = prefs.branches[base.kind];
+            if (!selected.answered || !selected.remote || !selected.branch)
+                return output({
+                    ok: false,
+                    error: {
+                        kind: 'bridge_error',
+                        retryable: false,
+                        message: 'Choose a configured or task-specific base branch.',
+                        recovery: 'task.branch',
+                    },
+                });
+            base = { kind: 'remote', remote: selected.remote, branch: selected.branch };
+        }
+        if (!keepCurrent && !name) {
+            const next = await askText(server, service, input, context, 'branch-name', input.language === 'tr'
+                ? 'Yeni görev branch’inin adı ne olsun?'
+                : 'Name the new task branch.');
+            if (!next.value)
+                return next.form;
+            name = next.value;
+        }
+        const signature = sha256(stableStringify({
+            externalTaskId: input.externalTaskId,
+            base,
+            name: name ?? null,
+            keepCurrent,
+            ...(input.decisionAttempt ? { decisionAttempt: input.decisionAttempt } : {}),
+        }));
+        const sourceLabel = base.kind === 'remote'
+            ? base.remote + '/' + base.branch
+            : base.kind === 'local'
+                ? base.ref
+                : base.kind === 'current'
+                    ? (prefs.currentBranch ?? 'HEAD')
+                    : prefs.branches[base.kind].remote + '/' + prefs.branches[base.kind].branch;
+        const definition = {
+            repoRoot: input.repoRoot,
+            questionnaireId: 'task-branch-confirm-' + signature,
+            language: input.language,
+            allowFreeText: false,
+            message: input.language === 'tr'
+                ? keepCurrent
+                    ? 'Bu klasörde mevcut branch üzerinde devam edilsin mi?'
+                    : sourceLabel + ' kaynağından ' + name + ' branch’i ayrı worktree’de açılsın mı?'
+                : keepCurrent
+                    ? 'Continue in this checkout on its current branch?'
+                    : 'Create ' + name + ' from ' + sourceLabel + ' in a separate worktree?',
+            options: [
+                { id: 'approve', label: input.language === 'tr' ? 'Devam et' : 'Continue' },
+                { id: 'defer', label: input.language === 'tr' ? 'Şimdilik başlatma' : 'Not now' },
+            ],
+        };
+        const form = await askQuestionnaire(server, service, definition, context);
+        const record = await service.questionnaireResume({
+            repoRoot: input.repoRoot,
+            questionnaireId: definition.questionnaireId,
+        });
+        if (record.status !== 'answered' || record.answer?.choice !== 'approve')
+            return form;
+        const fallbackBase = { kind: 'current', commit: prefs.currentCommit ?? undefined };
+        const fallbackSignature = sha256(stableStringify({
+            externalTaskId: input.externalTaskId,
+            base: fallbackBase,
+            name: name ?? null,
+            keepCurrent,
+            ...(input.decisionAttempt ? { decisionAttempt: input.decisionAttempt } : {}),
+        }));
+        const fallbackDefinition = {
+            ...definition,
+            questionnaireId: 'task-branch-fallback-' + fallbackSignature,
+            message: input.language === 'tr'
+                ? sourceLabel +
+                    ' uzak dalına ulaşılamadı. Yereldeki ' +
+                    (prefs.currentBranch ?? 'HEAD') +
+                    ' commit’i ' +
+                    (prefs.currentCommit?.slice(0, 12) ?? 'unborn HEAD') +
+                    ' üzerinden ayrı worktree ile devam edilsin mi?'
+                : 'The remote ' +
+                    sourceLabel +
+                    ' is unavailable. Continue from local ' +
+                    (prefs.currentBranch ?? 'HEAD') +
+                    ' commit ' +
+                    (prefs.currentCommit?.slice(0, 12) ?? 'unborn HEAD') +
+                    ' in a separate worktree?',
+        };
+        const fallback = async () => {
+            const form = await askQuestionnaire(server, service, fallbackDefinition, context);
+            const record = await service.questionnaireResume({
+                repoRoot: input.repoRoot,
+                questionnaireId: fallbackDefinition.questionnaireId,
+            });
+            if (record.status !== 'answered' || record.answer?.choice !== 'approve')
+                return form;
+            return output(await service.taskBranch({
+                repoRoot: input.repoRoot,
+                externalTaskId: input.externalTaskId,
+                name,
+                keepCurrent,
+                base: fallbackBase,
+                decisionId: fallbackDefinition.questionnaireId,
+                decisionAttempt: input.decisionAttempt,
+            }));
+        };
+        if (base.kind === 'remote') {
+            let recorded = false;
+            try {
+                await service.questionnaireResume({
+                    repoRoot: input.repoRoot,
+                    questionnaireId: fallbackDefinition.questionnaireId,
+                });
+                recorded = true;
+            }
+            catch { }
+            if (recorded)
+                return fallback();
+        }
+        const attempt = await service.taskBranch({
+            repoRoot: input.repoRoot,
+            externalTaskId: input.externalTaskId,
+            name,
+            keepCurrent,
+            base,
+            decisionId: definition.questionnaireId,
+            decisionAttempt: input.decisionAttempt,
+        });
+        if (base.kind === 'remote' &&
+            !attempt.ok &&
+            attempt.error?.message.startsWith('The selected remote branch could not be fetched.'))
+            return fallback();
+        return output(attempt);
+    });
+    const locationSchema = z.strictObject({ repoRoot: repo });
+    const ownershipSchema = z.strictObject({
+        repoRoot: repo,
+        externalTaskId: z.string().min(2).max(160),
+        generation: z.string().uuid(),
+        delivered: z.boolean().optional(),
+    });
+    server.registerTool('worktree.list', {
+        description: 'List task checkouts, activity and reasons each directory is protected.',
+        inputSchema: locationSchema,
+    }, async (input) => output(await service.worktreeOperation('list', input)));
+    server.registerTool('worktree.reconcile', {
+        description: 'Reconcile Git with the local registry and recover interrupted allocations or a validated backup, without deleting files or resetting branches.',
+        inputSchema: locationSchema,
+    }, async (input) => output(await service.worktreeOperation('reconcile', input)));
+    server.registerTool('task.heartbeat', {
+        description: 'Renew this exact task ownership during real activity. Never run an idle timer to keep an abandoned task active.',
+        inputSchema: ownershipSchema,
+    }, async (input) => output(await service.worktreeOperation('heartbeat', input)));
+    server.registerTool('task.pause', {
+        description: 'Pause without abandoning or deleting work. Stop writing until session.resume returns the new ownership generation.',
+        inputSchema: ownershipSchema,
+    }, async (input) => output(await service.worktreeOperation('pause', input)));
+    server.registerTool('worktree.release', {
+        description: 'Safely release this generation only when the checkout is clean and authorized delivery is complete. Never force cleanup.',
+        inputSchema: ownershipSchema,
+    }, async (input) => output(await service.worktreeOperation('release', input)));
+}
+async function askText(server, service, input, context, purpose, message) {
+    const definition = {
+        repoRoot: input.repoRoot,
+        questionnaireId: purpose +
+            '-' +
+            sha256(input.externalTaskId + (input.decisionAttempt ? ':' + input.decisionAttempt : '')),
+        language: input.language,
+        message,
+        allowFreeText: false,
+        options: [
+            { id: 'set', label: input.language === 'tr' ? 'Bu adı kullan' : 'Use this name' },
+            { id: 'defer', label: input.language === 'tr' ? 'Şimdilik başlatma' : 'Not now' },
+        ],
+        textField: {
+            requiredForChoice: 'set',
+            title: input.language === 'tr' ? 'Branch adı' : 'Branch name',
+            maxLength: 255,
+        },
+    };
+    const form = await askQuestionnaire(server, service, definition, context);
+    const record = await service.questionnaireResume({
+        repoRoot: input.repoRoot,
+        questionnaireId: definition.questionnaireId,
+    });
+    return {
+        form,
+        value: record.status === 'answered' && record.answer?.choice === 'set'
+            ? record.answer.text
+            : undefined,
+    };
+}
+//# sourceMappingURL=worktree-tools.js.map

package/runtime/dist/src/project/project-intake.js

@@ -77,7 +77,7 @@ export class ProjectIntake {
                         ];
         return { repoPath: root, recommendation, reasons, stacks, evidence, inventory };
     }
-    async initialize(repoPath) {
+    async initialize(repoPath, initialBranch) {
         const requested = resolve(repoPath);
         await assertNoRepositoryAncestor(requested, this.runner);
         let exists = true;
@@ -112,7 +112,14 @@ export class ProjectIntake {
         }, (error) => (error.code === 'ENOENT' ? false : Promise.reject(error)));
         if (existingGit)
             return { repoPath: root, initialized: false };
-        const result = await this.runner.run('git', ['init', '--quiet', '--'], { cwd: root });
+        if (initialBranch) {
+            const valid = await this.runner.run('git', ['check-ref-format', '--branch', initialBranch], {
+                cwd: root,
+            });
+            if (valid.exitCode !== 0 || valid.stdout.trim() !== initialBranch)
+                throw new Error('Select a valid literal initial development branch with project.initialize');
+        }
+        const result = await this.runner.run('git', ['init', '--quiet', ...(initialBranch ? ['--initial-branch=' + initialBranch] : []), '--'], { cwd: root });
         if (result.exitCode !== 0)
             throw new Error(`Git initialization failed: ${result.stderr.trim()}`);
         return { repoPath: root, initialized: true };

package/runtime/dist/src/runtime/api-client.js

@@ -1,5 +1,9 @@
 import { sha256, stableStringify } from '../utilities/hash.js';
 export const backendRecoveryOperationNames = [
+    'project.git_preferences',
+    'project.set_git_preferences',
+    'worktree.policy',
+    'worktree.set_policy',
     'auth.signin_browser',
     'auth.web_csrf',
     'auth.web_signin',

package/runtime/dist/src/runtime/branch-preferences.js

@@ -0,0 +1,53 @@
+import { sha256, stableStringify } from '../utilities/hash.js';
+import { BridgeRecoveryError } from './recovery-error.js';
+export function branchDecisionId(externalTaskId, base, name, keepCurrent) {
+    return ('task-base-' +
+        sha256(stableStringify({ externalTaskId, base, name: name ?? null, keepCurrent })));
+}
+export function branchChoices(preferences, current) {
+    const options = [];
+    for (const role of ['development', 'production', 'test']) {
+        const choice = preferences.branches[role];
+        if (choice.answered && choice.branch)
+            options.push({ id: role, label: role + ': ' + choice.remote + '/' + choice.branch });
+    }
+    options.splice(Math.min(1, options.length), 0, {
+        id: 'current',
+        label: 'Current branch: ' + (current ?? 'detached HEAD'),
+    });
+    options.push({ id: 'other', label: 'Another branch' }, { id: 'keep', label: 'Continue on this branch without creating a new branch' });
+    return options;
+}
+export async function resolveTaskBase(git, repoRoot, base, preferences) {
+    if (base.kind === 'current' || base.kind === 'local') {
+        const source = await git.sourceIdentity(repoRoot, base.kind === 'current' ? (base.commit ?? 'HEAD') : base.ref);
+        if (!source && base.kind === 'current' && !base.commit)
+            return { sourceCommit: null, base };
+        if (!source)
+            throw new BridgeRecoveryError('The selected local source has no commit. Choose a valid base or finish initial project setup.', 'task.branch');
+        return { ...source, base };
+    }
+    let remote;
+    let branch;
+    if (base.kind === 'remote') {
+        remote = base.remote;
+        branch = base.branch;
+    }
+    else {
+        const choice = preferences.branches[base.kind];
+        if (!choice.answered || !choice.branch || !choice.remote)
+            throw new BridgeRecoveryError('That project branch has not been configured. Select a task-specific base through task.branch.', 'task.branch');
+        remote = choice.remote;
+        branch = choice.branch;
+    }
+    try {
+        return { ...(await git.fetchBranchCommit(repoRoot, remote, branch)), base, remote, branch };
+    }
+    catch {
+        throw new BridgeRecoveryError('The selected remote branch could not be fetched. Retry task.branch, or ask a new native question to select an explicit local ref. No cached commit was selected.', 'task.branch');
+    }
+}
+export function preferencesJson(preferences) {
+    return JSON.parse(JSON.stringify(preferences));
+}
+//# sourceMappingURL=branch-preferences.js.map