@njeybe/nativ 2.5.1 → 2.7.0

package/dist/core/design-rules.js

@@ -0,0 +1,115 @@
+export const DESIGN_PROFILES = ['taste-v1', 'taste-v2'];
+const TASTE = ['taste-v1', 'taste-v2'];
+export const DESIGN_RULES = [
+    {
+        id: 'no-emoji', profiles: DESIGN_PROFILES, severity: 'error',
+        message: 'Emoji found; use an icon from the catalog',
+        pattern: /\p{Extended_Pictographic}/gu,
+    },
+    {
+        id: 'no-em-dash', profiles: ['taste-v2'], severity: 'error',
+        message: 'Em or en dash found; use a comma, colon or hyphen',
+        pattern: /[–—]/g,
+    },
+    {
+        id: 'no-h-screen', profiles: TASTE, severity: 'error',
+        message: 'h-screen found; use min-h-[100dvh]',
+        pattern: /(?<![\w-])h-screen(?![\w-])/g,
+    },
+    {
+        id: 'no-scroll-listener', profiles: TASTE, severity: 'error',
+        message: 'Scroll listener found; use IntersectionObserver or CSS',
+        pattern: /addEventListener\(\s*['"`]scroll['"`]/g,
+    },
+    {
+        id: 'no-pure-black', profiles: TASTE, severity: 'warning',
+        message: 'Pure black found; use an off-black token',
+        pattern: /#000(?:000)?(?![0-9a-fA-F])|rgba?\(\s*0\s*,\s*0\s*,\s*0\s*[,)]/g,
+    },
+    {
+        id: 'no-google-fonts-link', profiles: ['taste-v2'], severity: 'warning',
+        message: 'Google Fonts link found; self-host the font',
+        pattern: /fonts\.googleapis\.com/g,
+    },
+    {
+        id: 'no-custom-cursor', profiles: TASTE, severity: 'warning',
+        message: 'Custom cursor found',
+        pattern: /cursor:\s*url\(|cursor-\[url/g,
+    },
+    {
+        id: 'no-hand-rolled-icon', profiles: TASTE, severity: 'warning',
+        message: 'Inline svg with a path; use an icon from the catalog',
+        exts: ['.tsx', '.jsx'],
+    },
+];
+export const SCAN_EXTENSIONS = [
+    '.tsx', '.jsx', '.ts', '.js', '.html', '.vue', '.svelte', '.astro', '.mdx', '.css',
+];
+const PROFILE_LINE = /^- \*\*Profile:\*\*\s*(taste-v1|taste-v2)\s*$/m;
+export function readProfile(uiSpecsText) {
+    const m = PROFILE_LINE.exec(uiSpecsText);
+    return m ? m[1] : null;
+}
+export function isCommentLine(line) {
+    const t = line.trim();
+    return ['//', '/*', '*', '{/*', '<!--'].some((p) => t.startsWith(p));
+}
+function active(profile, ext) {
+    return DESIGN_RULES.filter((r) => r.profiles.includes(profile) && (!r.exts || r.exts.includes(ext)));
+}
+function lineStarts(text) {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++)
+        if (text[i] === '\n')
+            starts.push(i + 1);
+    return starts;
+}
+function locate(starts, index) {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (starts[mid] <= index)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return { line: lo + 1, column: index - starts[lo] + 1 };
+}
+function svgFindings(text, rule, starts, lines) {
+    const out = [];
+    const re = /<svg\b/g;
+    let m;
+    while ((m = re.exec(text))) {
+        const end = text.indexOf('</svg>', m.index);
+        const body = text.slice(m.index, end === -1 ? text.length : end);
+        const pos = locate(starts, m.index);
+        if (/<path\b/.test(body) && !isCommentLine(lines[pos.line - 1])) {
+            out.push({ ...pos, rule: rule.id, severity: rule.severity, message: rule.message });
+        }
+    }
+    return out;
+}
+export function checkText(text, ext, profile) {
+    const rules = active(profile, ext);
+    const lines = text.split('\n');
+    const starts = lineStarts(text);
+    const found = [];
+    for (const rule of rules) {
+        if (!rule.pattern) {
+            found.push(...svgFindings(text, rule, starts, lines));
+            continue;
+        }
+        lines.forEach((line, i) => {
+            if (isCommentLine(line))
+                return;
+            for (const m of line.matchAll(rule.pattern)) {
+                found.push({
+                    line: i + 1, column: (m.index ?? 0) + 1,
+                    rule: rule.id, severity: rule.severity, message: rule.message,
+                });
+            }
+        });
+    }
+    return found.sort((a, b) => a.line - b.line || a.column - b.column);
+}

package/dist/core/enforcement.js

@@ -13,6 +13,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { EXAMPLE_ENV_FILES } from '../db/env-parser.js';
 import { resolveMainRoot, resolveProjectRoot } from './root-resolver.js';
+import { mutateJsonFileSync } from './lock-manager.js';
 export const DEFAULT_ENFORCEMENT_MODE = 'warn';
 /** Roles other than these are treated as ordinary workers. The architect is the only role that may edit contracts. */
 export const ARCHITECT_ROLE = 'architect';
@@ -68,31 +69,31 @@ function readUnlocks(root) {
     }
     return { unlocks: [] };
 }
-function writeUnlocks(root, data) {
-    const file = path.join(root, UNLOCK_FILE);
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    const tmp = `${file}.${process.pid}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n', 'utf8');
-    fs.renameSync(tmp, file);
+/** Applies `change` to the unlock list under its lock; returns whether anything changed. */
+function mutateUnlocks(root, change) {
+    let changed = false;
+    mutateJsonFileSync(path.join(root, UNLOCK_FILE), (file) => {
+        const current = Array.isArray(file.unlocks) ? file.unlocks : [];
+        const next = change(current);
+        if (next) {
+            file.unlocks = next;
+            changed = true;
+        }
+        else {
+            file.unlocks = current;
+        }
+    });
+    return changed;
 }
 export function isTaskUnlocked(root, taskId) {
     return readUnlocks(root).unlocks.some((u) => u.taskId === taskId);
 }
 /** Lifts scope enforcement for one task until it is revoked or the task stops being in progress. */
 export function addTaskUnlock(root, taskId, reason) {
-    const data = readUnlocks(root);
-    if (data.unlocks.some((u) => u.taskId === taskId))
-        return;
-    data.unlocks.push({ taskId, at: new Date().toISOString(), ...(reason ? { reason } : {}) });
-    writeUnlocks(root, data);
+    mutateUnlocks(root, (unlocks) => unlocks.some((u) => u.taskId === taskId) ? null : [...unlocks, { taskId, at: new Date().toISOString(), ...(reason ? { reason } : {}) }]);
 }
 export function removeTaskUnlock(root, taskId) {
-    const data = readUnlocks(root);
-    const next = data.unlocks.filter((u) => u.taskId !== taskId);
-    if (next.length === data.unlocks.length)
-        return false;
-    writeUnlocks(root, { unlocks: next });
-    return true;
+    return mutateUnlocks(root, (unlocks) => (unlocks.some((u) => u.taskId === taskId) ? unlocks.filter((u) => u.taskId !== taskId) : null));
 }
 // ─── Path handling ─────────────────────────────────────────────────────────────────────────────────
 const CASE_INSENSITIVE = process.platform === 'win32' || process.platform === 'darwin';

package/dist/core/harness-integrity.js

@@ -169,18 +169,37 @@ function checkLearnings(root) {
     }
     return findings;
 }
-function checkUiSpecs(root) {
-    const specs = readText(path.join(root, '.ai', 'ui_specs.md'));
-    if (specs === null || /Marketing pages/i.test(specs))
+function checkDesignProfile(specs) {
+    if (specs === null || /^##\s+Design Profile\b/m.test(specs))
         return [];
     return [{
-            id: 'specs:marketing',
+            id: 'specs:design-profile',
             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.',
+            message: '.ai/ui_specs.md has no Design Profile section. Ask the architect to add it from the '
+                + 'current nativ template (templates/dot-ai/ui_specs.md).',
         }];
 }
+function checkTasteBundle(root, templatesDir) {
+    const mk = (message) => [{ id: 'design:taste-bundle', status: 'info', category: 'specs', message }];
+    const dir = path.join(root, '.ai', 'design', 'taste');
+    if (!fs.existsSync(dir)) {
+        return mk('The design bundle .ai/design/taste/ is missing. Run `nativ update` to install it.');
+    }
+    const differs = ['LICENSE', 'v1/SKILL.md', 'v2/SKILL.md'].filter((rel) => {
+        const want = readText(path.join(templatesDir, 'design', 'taste', rel));
+        const have = readText(path.join(dir, rel));
+        return want !== null && (have === null || have.replace(/\r/g, '') !== want.replace(/\r/g, ''));
+    });
+    if (!differs.length)
+        return [];
+    return mk(`Design bundle files differ from the nativ package: ${differs.join(', ')}. `
+        + 'Run `nativ update` (or `nativ update --force` to replace edited ones).');
+}
+function checkUiSpecs(root, templatesDir) {
+    const specs = readText(path.join(root, '.ai', 'ui_specs.md'));
+    return [...checkDesignProfile(specs), ...checkTasteBundle(root, templatesDir)];
+}
 export function checkHarnessIntegrity(root, options = {}) {
     const findings = [
         ...checkGuardrailOverrides(root),
@@ -188,7 +207,7 @@ export function checkHarnessIntegrity(root, options = {}) {
         ...checkMissingRoleGuides(root),
         ...checkEditedRoleGuides(root, options.templatesDir ?? getTemplatesDir()),
         ...checkLearnings(root),
-        ...checkUiSpecs(root),
+        ...checkUiSpecs(root, options.templatesDir ?? getTemplatesDir()),
     ];
     if (!findings.some((f) => f.category === 'guardrail' || f.category === 'secret')) {
         const message = 'No guardrail overrides and no secrets in files agents read';

package/dist/core/lock-manager.d.ts

@@ -48,6 +48,12 @@ export declare function withFileLockSync<T>(filePath: string, fn: () => T, optio
  * file. Retries the rename on Windows sharing violations, like savePlan().
  */
 export declare function writeJsonAtomicSync(filePath: string, data: unknown): void;
+/**
+ * Read-modify-write of a JSON object file under its lock, written atomically, so concurrent writers never drop
+ * each other's keys. A missing or empty file starts from `{}`; a file that does not parse is left alone and the
+ * write throws, because overwriting it would discard whatever a person wrote there.
+ */
+export declare function mutateJsonFileSync<T extends Record<string, unknown>>(filePath: string, mutator: (current: T) => void): void;
 /**
  * Synchronous variant of withPlanLock using proper-lockfile lockSync.
  */

package/dist/core/lock-manager.js

@@ -18,14 +18,7 @@ export const DEFAULT_LOCK_OPTIONS = {
  */
 export async function withFileLock(filePath, fn, options = {}) {
     const mergedOptions = { ...DEFAULT_LOCK_OPTIONS, ...options };
-    // proper-lockfile requires the target file to exist
-    if (!fs.existsSync(filePath)) {
-        const dir = path.dirname(filePath);
-        if (!fs.existsSync(dir)) {
-            fs.mkdirSync(dir, { recursive: true });
-        }
-        fs.writeFileSync(filePath, '', 'utf8');
-    }
+    ensureLockable(filePath, mergedOptions);
     const release = await lockfile.lock(filePath, mergedOptions);
     try {
         return await fn();
@@ -151,24 +144,8 @@ export async function withPlanLock(planPath, mutator, options = {}) {
  */
 export function withFileLockSync(filePath, fn, options = {}) {
     const { retries: _ignored, ...syncOptions } = { ...DEFAULT_LOCK_OPTIONS, ...options };
-    if (!fs.existsSync(filePath)) {
-        fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        fs.writeFileSync(filePath, '', 'utf8');
-    }
-    let release = null;
-    // ~5s of contention before giving up: parallel agents trip the breaker at the same moment.
-    const maxAttempts = 200;
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-        try {
-            release = lockfile.lockSync(filePath, syncOptions);
-            break;
-        }
-        catch (err) {
-            if (attempt === maxAttempts - 1 || err.code !== 'ELOCKED')
-                throw err;
-            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
-        }
-    }
+    ensureLockable(filePath, syncOptions);
+    const release = acquireLockSync(filePath, syncOptions);
     try {
         return fn();
     }
@@ -208,30 +185,62 @@ export function writeJsonAtomicSync(filePath, data) {
     }
 }
 /**
- * Synchronous variant of withPlanLock using proper-lockfile lockSync.
+ * With `realpath: false` (the default) the lock is a sibling `<file>.lock` directory, so the file itself need not
+ * exist; creating an empty one would leave JSON readers a file they cannot parse. Only the parent must exist.
  */
-export function withPlanLockSync(planPath, mutator, options = {}) {
-    if (!fs.existsSync(planPath)) {
-        return null;
-    }
-    const { retries: _ignored, ...syncOptions } = { ...DEFAULT_LOCK_OPTIONS, ...options };
-    let release = null;
-    const maxAttempts = 15;
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+function ensureLockable(filePath, options) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    if (options.realpath && !fs.existsSync(filePath))
+        fs.writeFileSync(filePath, '', 'utf8');
+}
+/** ~5s of contention before giving up: parallel agents finish, fail and trip the breaker at the same moments. */
+const SYNC_LOCK_ATTEMPTS = 200;
+function acquireLockSync(filePath, options) {
+    for (let attempt = 0;; attempt++) {
         try {
-            release = lockfile.lockSync(planPath, syncOptions);
-            break;
+            return lockfile.lockSync(filePath, options);
         }
         catch (err) {
-            if (attempt === maxAttempts - 1 || err.code !== 'ELOCKED') {
+            if (attempt >= SYNC_LOCK_ATTEMPTS - 1 || err.code !== 'ELOCKED')
                 throw err;
-            }
-            // Brief synchronous pause
             Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
         }
     }
-    if (!release)
+}
+/**
+ * Read-modify-write of a JSON object file under its lock, written atomically, so concurrent writers never drop
+ * each other's keys. A missing or empty file starts from `{}`; a file that does not parse is left alone and the
+ * write throws, because overwriting it would discard whatever a person wrote there.
+ */
+export function mutateJsonFileSync(filePath, mutator) {
+    withFileLockSync(filePath, () => {
+        let current = {};
+        const text = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8').replace(/^\uFEFF/, '') : '';
+        if (text.trim()) {
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch (err) {
+                throw new Error(`${filePath} is not valid JSON (${err.message}); fix or delete it, then retry.`);
+            }
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                throw new Error(`${filePath} must hold a JSON object.`);
+            current = parsed;
+        }
+        mutator(current);
+        writeJsonAtomicSync(filePath, current);
+    });
+}
+/**
+ * Synchronous variant of withPlanLock using proper-lockfile lockSync.
+ */
+export function withPlanLockSync(planPath, mutator, options = {}) {
+    if (!fs.existsSync(planPath)) {
         return null;
+    }
+    const { retries: _ignored, ...syncOptions } = { ...DEFAULT_LOCK_OPTIONS, ...options };
+    const release = acquireLockSync(planPath, syncOptions);
     try {
         const plan = loadPlan(planPath, { silent: true });
         if (!plan)

package/dist/core/notify.d.ts

@@ -0,0 +1,38 @@
+/**
+ * nativ · Tells a person when the workflow needs them, through a webhook (Slack, Discord, ntfy, any JSON
+ * endpoint) or a local command. Configured in `.nativ/config.json` (git-ignored, so a webhook secret stays
+ * local) as `"notify": { "webhook": "...", "command": "...", "events": [...] }`, or NATIV_NOTIFY_WEBHOOK /
+ * NATIV_NOTIFY_COMMAND. Delivery is best-effort and never fails the command that triggered it.
+ */
+export type NotifyEvent = 'human_decision' | 'circuit_breaker_tripped';
+export declare const NOTIFY_EVENTS: readonly NotifyEvent[];
+export interface NotifyConfig {
+    webhook?: string;
+    command?: string;
+    /** Set when a configured webhook was refused (not https, or plain http off this machine). */
+    rejectedWebhook?: string;
+    events: NotifyEvent[];
+}
+export interface NotifyInput {
+    event: NotifyEvent;
+    taskId: string;
+    escalationId?: string;
+    summary: string;
+    question?: string;
+    options?: string[];
+}
+export interface NotifyResult {
+    sent: boolean;
+    skipped?: 'not_configured' | 'event_disabled' | 'already_sent';
+    errors: string[];
+}
+export interface NotifyDeps {
+    fetch?: typeof fetch;
+    env?: NodeJS.ProcessEnv;
+    /** Resend even when this event was already delivered (used by `nativ notify test`). */
+    force?: boolean;
+}
+/** Plain http would send the payload, and often a token in the URL, in the clear; it is allowed only to this machine. */
+export declare function isAllowedWebhook(url: string): boolean;
+export declare function loadNotifyConfig(root: string, env?: NodeJS.ProcessEnv): NotifyConfig | null;
+export declare function notifyHuman(root: string, input: NotifyInput, deps?: NotifyDeps): Promise<NotifyResult>;

package/dist/core/notify.js

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { writeJsonAtomicSync } from './lock-manager.js';
+export const NOTIFY_EVENTS = ['human_decision', 'circuit_breaker_tripped'];
+const WEBHOOK_TIMEOUT_MS = 5_000;
+const COMMAND_TIMEOUT_MS = 10_000;
+const stateFile = (root) => path.join(root, '.nativ', 'notify-state.json');
+/** Plain http would send the payload, and often a token in the URL, in the clear; it is allowed only to this machine. */
+export function isAllowedWebhook(url) {
+    try {
+        const u = new URL(url);
+        return u.protocol === 'https:' || (u.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(u.hostname));
+    }
+    catch {
+        return false;
+    }
+}
+export function loadNotifyConfig(root, env = process.env) {
+    let file = {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(root, '.nativ', 'config.json'), 'utf8'));
+        if (parsed && typeof parsed.notify === 'object' && parsed.notify)
+            file = parsed.notify;
+    }
+    catch {
+        // No config file, or an unreadable one: notifications stay off unless the environment sets them.
+    }
+    const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
+    const webhook = str(env.NATIV_NOTIFY_WEBHOOK) ?? str(file.webhook);
+    const command = str(env.NATIV_NOTIFY_COMMAND) ?? str(file.command);
+    const listed = Array.isArray(file.events) ? file.events.filter((e) => NOTIFY_EVENTS.includes(e)) : [];
+    if (!webhook && !command)
+        return null;
+    return {
+        ...(webhook && isAllowedWebhook(webhook) ? { webhook } : {}),
+        ...(webhook && !isAllowedWebhook(webhook) ? { rejectedWebhook: webhook } : {}),
+        ...(command ? { command } : {}),
+        events: listed.length ? listed : [...NOTIFY_EVENTS],
+    };
+}
+function buildPayload(root, input) {
+    const project = path.basename(root);
+    const nextStep = input.escalationId ? `nativ triage ${input.escalationId}` : `nativ status`;
+    const lines = [`nativ [${project}] needs you: ${input.summary}`, `Task ${input.taskId}${input.escalationId ? `, ${input.escalationId}` : ''}.`];
+    if (input.question)
+        lines.push(input.question);
+    if (input.options?.length)
+        lines.push(`Options: ${input.options.join(' | ')}`);
+    lines.push(`Next: ${nextStep}`);
+    const text = lines.join('\n');
+    // `text` suits Slack and ntfy, `content` suits Discord; the structured fields suit everything else.
+    return { ...input, project, nextStep, at: new Date().toISOString(), text, content: text };
+}
+function readSent(root) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(stateFile(root), 'utf8'));
+        return parsed && typeof parsed.sent === 'object' ? parsed.sent : {};
+    }
+    catch {
+        return {};
+    }
+}
+function runCommand(command, payload) {
+    return new Promise((resolve) => {
+        const body = JSON.stringify(payload);
+        const child = spawn(command, {
+            shell: true,
+            stdio: ['pipe', 'ignore', 'ignore'],
+            env: { ...process.env, NATIV_NOTIFY_JSON: body },
+        });
+        const timer = setTimeout(() => {
+            child.kill();
+            resolve('command timed out');
+        }, COMMAND_TIMEOUT_MS);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolve(`command failed: ${err.message}`);
+        });
+        child.on('exit', (code) => {
+            clearTimeout(timer);
+            resolve(code === 0 ? null : `command exited with ${code}`);
+        });
+        child.stdin?.on('error', () => { });
+        child.stdin?.end(body);
+    });
+}
+export async function notifyHuman(root, input, deps = {}) {
+    const config = loadNotifyConfig(root, deps.env);
+    if (!config)
+        return { sent: false, skipped: 'not_configured', errors: [] };
+    if (!config.events.includes(input.event))
+        return { sent: false, skipped: 'event_disabled', errors: [] };
+    const key = `${input.event}:${input.escalationId ?? input.taskId}`;
+    const sent = readSent(root);
+    if (sent[key] && !deps.force)
+        return { sent: false, skipped: 'already_sent', errors: [] };
+    const payload = buildPayload(root, input);
+    const errors = config.rejectedWebhook ? ['webhook must be an https:// URL (plain http only to localhost)'] : [];
+    let delivered = false;
+    if (config.webhook) {
+        try {
+            const res = await (deps.fetch ?? fetch)(config.webhook, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS),
+            });
+            if (res.ok)
+                delivered = true;
+            else
+                errors.push(`webhook answered ${res.status}`);
+        }
+        catch (err) {
+            errors.push(`webhook failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (config.command) {
+        const error = await runCommand(config.command, payload);
+        if (error)
+            errors.push(error);
+        else
+            delivered = true;
+    }
+    try {
+        const next = { ...readSent(root), ...(delivered ? { [key]: payload.at } : {}) };
+        writeJsonAtomicSync(stateFile(root), { sent: next, ...(errors.length ? { lastError: { at: payload.at, errors } } : {}) });
+    }
+    catch {
+        // The state file only prevents repeats; failing to write it must not fail the caller.
+    }
+    return { sent: delivered, errors };
+}

package/dist/core/profiles.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { parseJsonLoose } from './enforcement.js';
+import { mutateJsonFileSync } from './lock-manager.js';
 export const PROFILE_DEFAULTS = {
     prototype: {
         profile: 'prototype',
@@ -61,22 +62,12 @@ export function resolveActiveProfileSettings(root) {
     return base;
 }
 export function setProfile(root, profile) {
-    const configPath = path.join(root, CONFIG_FILE);
-    fs.mkdirSync(path.dirname(configPath), { recursive: true });
-    let existing = {};
-    try {
-        existing = parseJsonLoose(fs.readFileSync(configPath, 'utf8')) || {};
-    }
-    catch {
-        existing = {};
-    }
     const profileSettings = PROFILE_DEFAULTS[profile];
-    existing.profile = profile;
-    existing.enforcement = profileSettings.enforcement;
-    existing.governorMode = profileSettings.governorMode;
-    existing.testIntegrity = profileSettings.testIntegrity;
-    const tmp = `${configPath}.${process.pid}.tmp`;
-    fs.writeFileSync(tmp, JSON.stringify(existing, null, 2) + '\n', 'utf8');
-    fs.renameSync(tmp, configPath);
+    mutateJsonFileSync(path.join(root, CONFIG_FILE), (config) => {
+        config.profile = profile;
+        config.enforcement = profileSettings.enforcement;
+        config.governorMode = profileSettings.governorMode;
+        config.testIntegrity = profileSettings.testIntegrity;
+    });
     return profileSettings;
 }

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[];