@njeybe/nativ 2.3.0 → 2.4.0

package/dist/core/harness-integrity.js

@@ -0,0 +1,198 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseJsonLoose } from './enforcement.js';
+import { getTemplatesDir, planTemplateFile } from './setup-assets.js';
+import { canonicalRole, listLearnings, loadLearnings } from './learnings.js';
+/** Well-known credential shapes only; loose `password=` matches would flag every doc that mentions one. */
+const SECRET_SHAPES = [
+    { kind: 'private key', pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/, severity: 'fail' },
+    { kind: 'Anthropic or OpenAI key', pattern: /\bsk-(?:ant-)?[A-Za-z0-9_-]{20,}/, severity: 'fail' },
+    { kind: 'GitHub token', pattern: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/, severity: 'fail' },
+    { kind: 'AWS access key', pattern: /\bAKIA[0-9A-Z]{16}\b/, severity: 'fail' },
+    { kind: 'Google API key', pattern: /\bAIza[0-9A-Za-z_-]{35}\b/, severity: 'fail' },
+    { kind: 'JSON web token', pattern: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/, severity: 'fail' },
+    // A placeholder such as user:password@localhost also matches, so this one only warns.
+    {
+        kind: 'connection string with a password',
+        pattern: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@"']*:[^\s@"'$<{/]+@/i,
+        severity: 'warn',
+    },
+];
+const SETTINGS_FILES = ['.claude/settings.json', '.claude/settings.local.json'];
+const AGENT_READ_FILES = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', '.mcp.json', '.nativ/config.json', ...SETTINGS_FILES];
+const AGENT_READ_DIRS = ['.claude/agents', '.ai'];
+const SCANNED_EXT = new Set(['.md', '.json', '.html', '.txt', '.yaml', '.yml']);
+const MAX_SCAN_BYTES = 1_000_000;
+function readText(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function listFiles(dir, out = []) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory())
+            listFiles(full, out);
+        else if (e.isFile() && SCANNED_EXT.has(path.extname(e.name).toLowerCase()))
+            out.push(full);
+    }
+    return out;
+}
+function checkGuardrailOverrides(root) {
+    const findings = [];
+    const add = (id, status, message) => findings.push({ id, status, message, category: 'guardrail' });
+    for (const rel of SETTINGS_FILES) {
+        const text = readText(path.join(root, rel));
+        if (!text?.trim())
+            continue;
+        let settings;
+        try {
+            settings = parseJsonLoose(text);
+        }
+        catch {
+            const message = `${rel} is not valid JSON, so its guardrail settings could not be checked.`;
+            add(`guardrail:${rel}:unreadable`, 'warn', message);
+            continue;
+        }
+        if (settings?.disableAllHooks === true) {
+            const message = `${rel} sets disableAllHooks, so the enforcement hook never runs. Remove it.`;
+            add(`guardrail:${rel}:hooks`, 'fail', message);
+        }
+        if (settings?.permissions?.defaultMode === 'bypassPermissions') {
+            const message = `${rel} sets bypassPermissions, so writes under .ai/ and .nativ/ no longer ask a human first.`;
+            add(`guardrail:${rel}:bypass`, 'warn', message);
+        }
+    }
+    return findings;
+}
+function scanFile(root, file) {
+    try {
+        if (fs.statSync(file).size > MAX_SCAN_BYTES)
+            return [];
+    }
+    catch {
+        return [];
+    }
+    const lines = (readText(file) ?? '').split(/\r?\n/);
+    const rel = path.relative(root, file).split(path.sep).join('/');
+    const findings = [];
+    for (const shape of SECRET_SHAPES) {
+        const line = lines.findIndex((l) => shape.pattern.test(l));
+        if (line < 0)
+            continue;
+        findings.push({
+            id: `secret:${rel}:${shape.kind}`,
+            status: shape.severity,
+            category: 'secret',
+            message: `${rel}:${line + 1} looks like a ${shape.kind}. Agents read this file; `
+                + 'move the value to .env and reference it.',
+        });
+    }
+    return findings;
+}
+function checkSecrets(root) {
+    const files = [
+        ...AGENT_READ_FILES.map((rel) => path.join(root, rel)),
+        ...AGENT_READ_DIRS.flatMap((rel) => listFiles(path.join(root, rel))),
+    ];
+    return files.flatMap((file) => scanFile(root, file));
+}
+function plannedRoles(root) {
+    try {
+        const plan = parseJsonLoose(readText(path.join(root, '.ai', 'master_plan.json')) ?? '{}');
+        const roles = (plan.milestones ?? []).flatMap((m) => (Array.isArray(m?.tasks) ? m.tasks : []))
+            .map((t) => t?.assignedSubagent)
+            .filter((r) => typeof r === 'string');
+        return [...new Set(roles)];
+    }
+    catch {
+        return [];
+    }
+}
+function checkMissingRoleGuides(root) {
+    const guidesDir = path.join(root, '.ai', 'subagents');
+    const missing = plannedRoles(root).filter((role) => {
+        const guide = canonicalRole(role) ?? role;
+        return !/^[\w-]+$/.test(guide) || !fs.existsSync(path.join(guidesDir, `${guide}.md`));
+    });
+    if (!missing.length)
+        return [];
+    return [{
+            id: 'role-guides:missing',
+            status: 'warn',
+            category: 'roles',
+            message: `Tasks name roles with no guide in .ai/subagents/: ${missing.sort().join(', ')}. `
+                + 'Their workers start without one.',
+        }];
+}
+function checkEditedRoleGuides(root, templatesDir) {
+    const edited = [];
+    for (const file of listFiles(path.join(templatesDir, 'dot-ai', 'subagents'))) {
+        const name = path.basename(file);
+        const existing = readText(path.join(root, '.ai', 'subagents', name));
+        if (existing === null)
+            continue;
+        if (planTemplateFile(existing, readText(file) ?? '', `subagents/${name}`).action === 'skipped')
+            edited.push(name);
+    }
+    if (!edited.length)
+        return [];
+    const message = `Role guides edited by hand (nativ update keeps them as they are): ${edited.sort().join(', ')}`;
+    return [{ id: 'role-guides:edited', status: 'info', category: 'roles', message }];
+}
+function checkLearnings(root) {
+    const findings = [];
+    const waiting = listLearnings(root, { status: 'proposed' }).length;
+    if (waiting) {
+        const noun = waiting === 1 ? 'lesson waits' : 'lessons wait';
+        const message = `${waiting} proposed ${noun} for approval: nativ learn list --status proposed`;
+        findings.push({ id: 'learnings', status: 'info', category: 'learnings', message });
+    }
+    if (loadLearnings(root).unreadable) {
+        findings.push({
+            id: 'learnings:unreadable',
+            status: 'warn',
+            category: 'learnings',
+            message: '.ai/learnings.json cannot be read, so workers receive no lessons and new ones cannot be '
+                + 'proposed. Fix the JSON or move the file.',
+        });
+    }
+    return findings;
+}
+function checkUiSpecs(root) {
+    const specs = readText(path.join(root, '.ai', 'ui_specs.md'));
+    if (specs === null || /Marketing pages/i.test(specs))
+        return [];
+    return [{
+            id: 'specs:marketing',
+            status: 'info',
+            category: 'specs',
+            message: '.ai/ui_specs.md predates the Marketing pages checks. Ask the architect to add that part '
+                + 'of the Anti-Generic Checklist from the current nativ template.',
+        }];
+}
+export function checkHarnessIntegrity(root, options = {}) {
+    const findings = [
+        ...checkGuardrailOverrides(root),
+        ...checkSecrets(root),
+        ...checkMissingRoleGuides(root),
+        ...checkEditedRoleGuides(root, options.templatesDir ?? getTemplatesDir()),
+        ...checkLearnings(root),
+        ...checkUiSpecs(root),
+    ];
+    if (!findings.some((f) => f.category === 'guardrail' || f.category === 'secret')) {
+        const message = 'No guardrail overrides and no secrets in files agents read';
+        findings.unshift({ id: 'integrity', status: 'ok', category: 'guardrail', message });
+    }
+    return findings;
+}

package/dist/core/human-gate.d.ts

@@ -0,0 +1,7 @@
+/**
+ * nativ · Commands only a person may run. Agents run headless, so a missing terminal stops them even
+ * where no permission rule is installed. It is one layer, not a sandbox: the hook and ask rules are others.
+ */
+export declare function isInteractive(): boolean;
+/** Prints why and sets a failing exit code when there is no terminal. Returns true when refused. */
+export declare function refuseHeadless(command: string): boolean;

package/dist/core/human-gate.js

@@ -0,0 +1,16 @@
+import pc from 'picocolors';
+/**
+ * nativ · Commands only a person may run. Agents run headless, so a missing terminal stops them even
+ * where no permission rule is installed. It is one layer, not a sandbox: the hook and ask rules are others.
+ */
+export function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/** Prints why and sets a failing exit code when there is no terminal. Returns true when refused. */
+export function refuseHeadless(command) {
+    if (isInteractive())
+        return false;
+    console.error(pc.red(`✖ ${command} needs an interactive terminal; agents cannot run it.`));
+    process.exitCode = 1;
+    return true;
+}

package/dist/core/learnings.d.ts

@@ -0,0 +1,63 @@
+/**
+ * nativ · Project learnings in `.ai/learnings.json`. Agents propose; only a human approves, from an
+ * interactive terminal. The file is protected like the contracts, by the hook and the ask rules.
+ */
+export declare const LEARNING_STATUSES: readonly ["proposed", "approved", "rejected"];
+export type LearningStatus = (typeof LEARNING_STATUSES)[number];
+export type LearningDecision = Exclude<LearningStatus, 'proposed'>;
+export interface Learning {
+    id: string;
+    status: LearningStatus;
+    insight: string;
+    details?: string;
+    /** Applies to this role only; absent means every role. */
+    role?: string;
+    /** Applies when a task targets a matching file (exact, `dir/` or glob); absent means any file. */
+    files?: string[];
+    taskId?: string;
+    proposedBy?: string;
+    createdAt: string;
+    decidedAt?: string;
+    decisionNote?: string;
+}
+export interface LearningsFile {
+    version: '1.0.0';
+    updatedAt: string;
+    learnings: Learning[];
+}
+/** The most lessons one task carries, so a long list never crowds out the contracts. */
+export declare const MAX_TASK_LEARNINGS = 5;
+export declare function learningsPath(root: string): string;
+export declare function loadLearnings(root: string): LearningsFile & {
+    unreadable: boolean;
+};
+/** Maps role aliases (`backend-agent`, `qa`) to the role names tasks use, or null when unknown. */
+export declare function canonicalRole(role: string | null | undefined): string | null;
+export interface ProposeInput {
+    insight: string;
+    details?: string;
+    role?: string;
+    files?: string[];
+    taskId?: string;
+    proposedBy?: string;
+}
+export declare function proposeLearning(root: string, input: ProposeInput): Learning;
+/** What a worker receives from a lesson; a decision applies only if this is what the human saw. */
+export declare function lessonContent(l: Pick<Learning, 'insight' | 'details' | 'role' | 'files'>): string;
+/**
+ * Approves or rejects a lesson. Pass `seen` (from lessonContent) to refuse when the lesson changed
+ * after the human looked at it. Returns an error message, or the updated lesson.
+ */
+export declare function decideLearning(root: string, id: string, decision: LearningDecision, note?: string, seen?: string): Learning | string;
+export declare function listLearnings(root: string, filter?: {
+    status?: LearningStatus;
+    role?: string;
+}): Learning[];
+/**
+ * Approved lessons for one task: those scoped to its files first, then to its role, then
+ * project-wide ones, newest first within each, capped at MAX_TASK_LEARNINGS.
+ */
+export declare function learningsForTask(root: string, task: {
+    assignedSubagent?: string;
+    targetFiles?: string[];
+}): Learning[];

package/dist/core/learnings.js

@@ -0,0 +1,227 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { withFileLockSync, writeJsonAtomicSync } from './lock-manager.js';
+import { matchesTarget, parseJsonLoose } from './enforcement.js';
+import { SUBAGENT_TYPES } from '../scanner/types.js';
+/**
+ * nativ · Project learnings in `.ai/learnings.json`. Agents propose; only a human approves, from an
+ * interactive terminal. The file is protected like the contracts, by the hook and the ask rules.
+ */
+export const LEARNING_STATUSES = ['proposed', 'approved', 'rejected'];
+/** The most lessons one task carries, so a long list never crowds out the contracts. */
+export const MAX_TASK_LEARNINGS = 5;
+const MAX_INSIGHT = 300;
+const MAX_DETAILS = 500;
+const MAX_FILES = 10;
+const MAX_FILE_PATTERN = 200;
+const MAX_PENDING = 100;
+export function learningsPath(root) {
+    return path.join(root, '.ai', 'learnings.json');
+}
+function isLearning(l) {
+    if (!l || typeof l !== 'object')
+        return false;
+    const item = l;
+    if (typeof item.id !== 'string' || typeof item.insight !== 'string')
+        return false;
+    if (!LEARNING_STATUSES.includes(item.status))
+        return false;
+    if (item.files !== undefined && !(Array.isArray(item.files) && item.files.every((f) => typeof f === 'string'))) {
+        return false;
+    }
+    return item.role === undefined || item.role === null || typeof item.role === 'string';
+}
+function readRaw(root) {
+    const fresh = () => ({ doc: { version: '1.0.0' }, records: [], corrupt: false });
+    let raw;
+    try {
+        raw = fs.readFileSync(learningsPath(root), 'utf8');
+    }
+    catch {
+        return fresh();
+    }
+    if (!raw.trim())
+        return fresh();
+    try {
+        const doc = parseJsonLoose(raw);
+        if (!doc || typeof doc !== 'object' || !Array.isArray(doc.learnings))
+            return { ...fresh(), corrupt: true };
+        return { doc, records: doc.learnings, corrupt: false };
+    }
+    catch {
+        return { ...fresh(), corrupt: true };
+    }
+}
+export function loadLearnings(root) {
+    const { doc, records, corrupt } = readRaw(root);
+    return {
+        version: '1.0.0',
+        updatedAt: String(doc.updatedAt ?? ''),
+        learnings: records.filter(isLearning),
+        unreadable: corrupt,
+    };
+}
+function mutateLearnings(root, mutate) {
+    const file = learningsPath(root);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    return withFileLockSync(file, () => {
+        const { doc, records, corrupt } = readRaw(root);
+        if (corrupt) {
+            const rel = path.relative(root, file);
+            throw new Error(`${rel} cannot be read, so nothing was changed. Fix or move it, then retry.`);
+        }
+        const result = mutate(records);
+        writeJsonAtomicSync(file, { ...doc, version: '1.0.0', updatedAt: new Date().toISOString(), learnings: records });
+        return result;
+    });
+}
+/** Ids already used by any record, valid or not, so a new lesson never takes an old one's id. */
+function nextId(records) {
+    const max = records.reduce((m, r) => {
+        const id = r && typeof r === 'object' ? r.id : undefined;
+        return Math.max(m, Number(typeof id === 'string' ? /^learn-(\d+)$/.exec(id)?.[1] ?? 0 : 0));
+    }, 0);
+    return `learn-${String(max + 1).padStart(2, '0')}`;
+}
+// Control characters, bidi overrides, zero-width marks and line/paragraph separators can make the
+// text a human approves read differently from what a worker receives.
+const HIDDEN = /[\u0000-\u0009\u000b-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060-\u2069\ufeff]/g;
+const HIDDEN_AND_NEWLINE = /[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2060-\u2069\ufeff]/g;
+function clean(text, max, keepNewlines = false) {
+    const t = text?.replace(keepNewlines ? HIDDEN : HIDDEN_AND_NEWLINE, keepNewlines ? '' : ' ').trim();
+    if (!t)
+        return undefined;
+    return t.length > max ? t.slice(0, max) : t;
+}
+/** Maps role aliases (`backend-agent`, `qa`) to the role names tasks use, or null when unknown. */
+export function canonicalRole(role) {
+    const r = (role ?? '').trim().toLowerCase();
+    if (!r)
+        return null;
+    const known = SUBAGENT_TYPES;
+    const candidates = [r, r.replace(/-agent$/, ''), r === 'qa' || r === 'qa-agent' ? 'qa-tester' : '', `${r}-agent`];
+    const hit = candidates.find((c) => c && known.includes(c));
+    return hit ? hit.replace(/^(backend|frontend|database)-agent$/, '$1').replace(/^qa-agent$/, 'qa-tester') : null;
+}
+/** A lesson's role in canonical form, also for records saved before roles were normalised. */
+const roleOf = (l) => (l.role ? canonicalRole(l.role) ?? l.role.toLowerCase() : null);
+function normalizePattern(p) {
+    return p.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+}
+function cleanFiles(files) {
+    const out = [];
+    for (const f of files ?? []) {
+        const p = normalizePattern(f);
+        if (!p)
+            continue;
+        if (p.length > MAX_FILE_PATTERN) {
+            throw new Error(`File pattern is longer than ${MAX_FILE_PATTERN} characters: ${p.slice(0, 40)}...`);
+        }
+        if (p.startsWith('/') || /^[A-Za-z]:/.test(p) || /(^|\/)\.\.(\/|$)/.test(p)) {
+            throw new Error(`File patterns must be relative to the project: ${p}`);
+        }
+        out.push(p);
+    }
+    if (out.length > MAX_FILES)
+        throw new Error(`A lesson can name at most ${MAX_FILES} file patterns.`);
+    return out;
+}
+export function proposeLearning(root, input) {
+    const insight = clean(input.insight, MAX_INSIGHT);
+    if (!insight)
+        throw new Error('A learning needs a one-line insight.');
+    const details = clean(input.details, MAX_DETAILS, true);
+    const role = input.role?.trim() ? canonicalRole(input.role) : undefined;
+    if (role === null)
+        throw new Error(`Unknown role "${input.role}". Use one of: ${SUBAGENT_TYPES.join(', ')}.`);
+    const files = cleanFiles(input.files);
+    const taskId = clean(input.taskId, 64);
+    const proposedBy = clean(input.proposedBy, 64);
+    return mutateLearnings(root, (records) => {
+        const pending = records.filter((r) => isLearning(r) && r.status === 'proposed').length;
+        if (pending >= MAX_PENDING) {
+            throw new Error(`${pending} lessons already wait for approval. Approve or reject some before proposing more.`);
+        }
+        const item = {
+            id: nextId(records),
+            status: 'proposed',
+            insight,
+            ...(details ? { details } : {}),
+            ...(role ? { role } : {}),
+            ...(files.length ? { files } : {}),
+            ...(taskId ? { taskId } : {}),
+            ...(proposedBy ? { proposedBy } : {}),
+            createdAt: new Date().toISOString(),
+        };
+        records.push(item);
+        return item;
+    });
+}
+/** What a worker receives from a lesson; a decision applies only if this is what the human saw. */
+export function lessonContent(l) {
+    return JSON.stringify([l.insight, l.details ?? '', l.role ?? '', l.files ?? []]);
+}
+/**
+ * Approves or rejects a lesson. Pass `seen` (from lessonContent) to refuse when the lesson changed
+ * after the human looked at it. Returns an error message, or the updated lesson.
+ */
+export function decideLearning(root, id, decision, note, seen) {
+    return mutateLearnings(root, (records) => {
+        const item = records.find((r) => isLearning(r) && r.id === id);
+        if (!item)
+            return `No learning ${id}.`;
+        if (seen !== undefined && lessonContent(item) !== seen) {
+            return `${id} changed while you were reviewing it. Nothing was decided; run the command again.`;
+        }
+        if (item.status === decision)
+            return `${id} is already ${decision}.`;
+        item.status = decision;
+        item.decidedAt = new Date().toISOString();
+        const cleanNote = clean(note, MAX_DETAILS);
+        if (cleanNote)
+            item.decisionNote = cleanNote;
+        else
+            delete item.decisionNote;
+        return item;
+    });
+}
+export function listLearnings(root, filter = {}) {
+    const role = filter.role ? canonicalRole(filter.role) ?? filter.role.toLowerCase() : undefined;
+    return loadLearnings(root).learnings.filter((l) => (!filter.status || l.status === filter.status) && (!role || roleOf(l) === role));
+}
+const globBase = (p) => p.split(/[*?[{]/)[0];
+/** True when a task target and a lesson pattern overlap, whichever of them is the wider one. */
+function overlaps(target, pattern) {
+    const t = normalizePattern(target);
+    if (matchesTarget(t, pattern) || matchesTarget(pattern, t))
+        return true;
+    const [tb, pb] = [globBase(t).toLowerCase(), globBase(pattern).toLowerCase()];
+    const targetIsWide = t.endsWith('/') || t.length !== tb.length;
+    const patternIsWide = pattern.endsWith('/') || pattern.length !== pb.length;
+    return (targetIsWide && tb !== '' && pattern.toLowerCase().startsWith(tb))
+        || (patternIsWide && pb !== '' && t.toLowerCase().startsWith(pb));
+}
+/**
+ * Approved lessons for one task: those scoped to its files first, then to its role, then
+ * project-wide ones, newest first within each, capped at MAX_TASK_LEARNINGS.
+ */
+export function learningsForTask(root, task) {
+    const role = canonicalRole(task.assignedSubagent);
+    const targets = Array.isArray(task.targetFiles) ? task.targetFiles.filter((t) => typeof t === 'string') : [];
+    const scored = [];
+    loadLearnings(root).learnings.forEach((item, order) => {
+        if (item.status !== 'approved')
+            return;
+        const itemRole = roleOf(item);
+        if (itemRole && itemRole !== role)
+            return;
+        const fileMatch = item.files?.length ? targets.some((t) => item.files.some((p) => overlaps(t, p))) : null;
+        if (fileMatch === false)
+            return;
+        scored.push({ item, score: (fileMatch ? 2 : 0) + (itemRole ? 1 : 0), order });
+    });
+    return scored
+        .sort((a, b) => b.score - a.score || b.order - a.order)
+        .slice(0, MAX_TASK_LEARNINGS)
+        .map((s) => s.item);
+}

package/dist/core/root-resolver.d.ts

@@ -5,6 +5,11 @@
  * schemas remain accessible to sub-agents.
  */
 export declare function resolveProjectRoot(startDirArg?: string): string;
+/**
+ * The main checkout, also from inside a task worktree. Worktrees link `.ai/` but not `.nativ/`,
+ * so settings and keys must always come from here, never from the agent's own copy.
+ */
+export declare function resolveMainRoot(startDirArg?: string): string;
 /**
  * Creates a directory junction (Windows) or symlink (Unix) linking .ai/
  * from the main project root into the newly created worktree so path-relative

package/dist/core/root-resolver.js

@@ -57,6 +57,52 @@ export function resolveProjectRoot(startDirArg) {
     }
     return path.resolve(startDirArg || process.cwd());
 }
+/**
+ * The main checkout, also from inside a task worktree. Worktrees link `.ai/` but not `.nativ/`,
+ * so settings and keys must always come from here, never from the agent's own copy.
+ */
+export function resolveMainRoot(startDirArg) {
+    const start = path.resolve(startDirArg || process.cwd());
+    const marker = `${path.sep}.worktrees${path.sep}`;
+    const idx = `${start}${path.sep}`.indexOf(marker);
+    if (idx !== -1 && fs.existsSync(path.join(start.slice(0, idx), '.ai')))
+        return start.slice(0, idx);
+    const linked = linkedWorktreeMain(start);
+    return linked ?? resolveProjectRoot(start);
+}
+const isInside = (parent, child) => {
+    const rel = path.relative(parent, child);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+};
+/**
+ * For a git linked worktree, the main checkout from git's own `commondir` record. Only a checkout
+ * that contains the worktree counts, so an edited `.git` file cannot point somewhere else.
+ */
+function linkedWorktreeMain(start) {
+    let top = start;
+    while (!fs.existsSync(path.join(top, '.git'))) {
+        const up = path.dirname(top);
+        if (up === top)
+            return null;
+        top = up;
+    }
+    try {
+        const gitFile = path.join(top, '.git');
+        if (!fs.lstatSync(gitFile).isFile())
+            return null;
+        const gitDirRaw = /^gitdir:\s*(.+)$/im.exec(fs.readFileSync(gitFile, 'utf8'))?.[1]?.trim();
+        if (!gitDirRaw)
+            return null;
+        const gitDir = path.resolve(top, gitDirRaw);
+        const common = fs.readFileSync(path.join(gitDir, 'commondir'), 'utf8').trim();
+        const mainRepo = path.dirname(path.resolve(gitDir, common));
+        return isInside(mainRepo, top) && fs.existsSync(path.join(mainRepo, '.ai')) ? mainRepo : null;
+    }
+    catch {
+        // No commondir (a submodule, or not a worktree): not a linked worktree.
+        return null;
+    }
+}
 /**
  * Creates a directory junction (Windows) or symlink (Unix) linking .ai/
  * from the main project root into the newly created worktree so path-relative

package/dist/core/session-memory.d.ts

@@ -0,0 +1,42 @@
+export interface SessionCheckpoint {
+    sessionId: string;
+    timestamp: string;
+    role?: string;
+    taskId?: string;
+    summary: string;
+    decisions?: string[];
+    obstacles?: string[];
+    nextSteps?: string[];
+    activeFiles?: string[];
+}
+export interface SessionSummaryEntry {
+    sessionId: string;
+    timestamp: string;
+    role?: string;
+    taskId?: string;
+    summary: string;
+}
+export interface SessionIndex {
+    version: '1.0.0';
+    updatedAt: string;
+    latestSessionId?: string;
+    sessions: SessionSummaryEntry[];
+}
+export declare function getSessionMemoryDir(targetDir: string): string;
+export declare function getSessionIndexPath(targetDir: string): string;
+export declare function getLatestSessionPath(targetDir: string): string;
+export declare function loadSessionIndex(targetDir: string): SessionIndex;
+export declare function saveSessionIndex(targetDir: string, index: SessionIndex): void;
+export declare function saveSessionCheckpoint(targetDir: string, input: {
+    sessionId?: string;
+    role?: string;
+    taskId?: string;
+    summary: string;
+    decisions?: string[];
+    obstacles?: string[];
+    nextSteps?: string[];
+    activeFiles?: string[];
+}): SessionCheckpoint;
+export declare function getLatestSession(targetDir: string): SessionCheckpoint | null;
+export declare function getSession(targetDir: string, sessionId: string): SessionCheckpoint | null;
+export declare function listSessions(targetDir: string, limit?: number): SessionSummaryEntry[];