agentic-workflow-manager 3.1.0 → 3.2.1

package/dist/tests/providers/hooks-config.test.js

@@ -1,25 +1,50 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
 const providers_1 = require("../../src/providers");
 describe('Hook configuration in providers', () => {
+    const originalHome = process.env.HOME;
+    const originalAwmHome = process.env.AWM_HOME;
+    let tmpHome;
+    let tmpWork;
+    beforeEach(() => {
+        tmpHome = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-hook-home-'));
+        tmpWork = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-hook-work-'));
+        process.env.HOME = tmpHome;
+        process.env.AWM_HOME = path_1.default.join(tmpWork, 'awm');
+    });
+    afterEach(() => {
+        if (originalHome === undefined)
+            delete process.env.HOME;
+        else
+            process.env.HOME = originalHome;
+        if (originalAwmHome === undefined)
+            delete process.env.AWM_HOME;
+        else
+            process.env.AWM_HOME = originalAwmHome;
+        fs_1.default.rmSync(tmpHome, { recursive: true, force: true });
+        fs_1.default.rmSync(tmpWork, { recursive: true, force: true });
+    });
     it('claude-code provider defines a HookConfig', () => {
-        const cc = providers_1.PROVIDERS['claude-code'];
+        const cc = (0, providers_1.providerFor)('claude-code');
         expect(cc.hooks).toBeDefined();
         expect(cc.hooks?.type).toBe('cc-settings-merge');
         expect(cc.hooks?.eventName).toBe('SessionStart');
         expect(cc.hooks?.matcher).toBe('startup|clear|compact');
     });
-    it('claude-code settingsPath resolves to ~/.claude/settings.json', () => {
-        const cc = providers_1.PROVIDERS['claude-code'];
-        expect(cc.hooks?.settingsPath).toMatch(/\.claude\/settings\.json$/);
+    it('preserves the legacy Claude Code AWM_HOME hooks directory', () => {
+        const cc = (0, providers_1.providerFor)('claude-code');
+        expect(cc.hooks?.settingsPath).toBe(path_1.default.join(tmpHome, '.claude/settings.json'));
+        expect(cc.hooks?.scriptsDir).toBe(path_1.default.join(process.env.AWM_HOME, 'hooks'));
     });
-    it('claude-code scriptsDir resolves to ~/.awm/hooks/', () => {
-        const cc = providers_1.PROVIDERS['claude-code'];
-        expect(cc.hooks?.scriptsDir).toMatch(/\.awm\/hooks$/);
-    });
-    it('antigravity and opencode have no hooks (single-harness scope)', () => {
-        expect(providers_1.PROVIDERS['antigravity'].hooks).toBeUndefined();
-        expect(providers_1.PROVIDERS['opencode'].hooks).toBeUndefined();
+    it('antigravity and opencode have no hooks', () => {
+        expect((0, providers_1.providerFor)('antigravity').hooks).toBeUndefined();
+        expect((0, providers_1.providerFor)('opencode').hooks).toBeUndefined();
     });
     it('getHookConfig returns config for supported target', () => {
         const config = (0, providers_1.getHookConfig)('claude-code');
@@ -27,19 +52,12 @@ describe('Hook configuration in providers', () => {
         expect(config?.type).toBe('cc-settings-merge');
     });
     it('getHookConfig returns undefined for unsupported target', () => {
-        const config = (0, providers_1.getHookConfig)('antigravity');
-        expect(config).toBeUndefined();
-    });
-    it('respects AWM_HOME env var override for scriptsDir', () => {
-        const originalEnv = process.env.AWM_HOME;
-        process.env.AWM_HOME = '/tmp/awm-test';
-        // Re-import to pick up env change
-        jest.resetModules();
-        const { PROVIDERS: P } = require('../../src/providers');
-        expect(P['claude-code'].hooks.scriptsDir).toBe('/tmp/awm-test/hooks');
-        if (originalEnv === undefined)
-            delete process.env.AWM_HOME;
-        else
-            process.env.AWM_HOME = originalEnv;
+        expect((0, providers_1.getHookConfig)('antigravity')).toBeUndefined();
+    });
+    it('respects AWM_HOME changes at call time', () => {
+        const nextAwmHome = path_1.default.join(tmpWork, 'next-awm');
+        process.env.AWM_HOME = nextAwmHome;
+        expect((0, providers_1.getHookConfig)('claude-code')?.scriptsDir)
+            .toBe(path_1.default.join(nextAwmHome, 'hooks'));
     });
 });

package/dist/tests/providers/index.test.js

@@ -3,56 +3,161 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-// tests/providers/index.test.ts
-const providers_1 = require("../../src/providers");
+const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const providers_1 = require("../../src/providers");
 describe('Providers Routing', () => {
-    // ── Existing Antigravity tests (preserved) ──
-    it('routes antigravity global skills correctly', () => {
-        const result = (0, providers_1.getTargetPath)('skill', 'antigravity', 'global');
-        expect(result).toBe(`${os_1.default.homedir()}/.gemini/antigravity/skills`);
+    const originalHome = process.env.HOME;
+    const originalAwmHome = process.env.AWM_HOME;
+    let tmpHome;
+    let tmpWork;
+    beforeEach(() => {
+        tmpHome = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-provider-home-'));
+        tmpWork = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-provider-work-'));
+        process.env.HOME = tmpHome;
+        process.env.AWM_HOME = path_1.default.join(tmpHome, '.awm-test');
     });
-    it('routes opencode local skills correctly', () => {
-        const result = (0, providers_1.getTargetPath)('skill', 'opencode', 'local');
-        expect(result).toBe('.agents/skills');
+    afterEach(() => {
+        if (originalHome === undefined)
+            delete process.env.HOME;
+        else
+            process.env.HOME = originalHome;
+        if (originalAwmHome === undefined)
+            delete process.env.AWM_HOME;
+        else
+            process.env.AWM_HOME = originalAwmHome;
+        fs_1.default.rmSync(tmpHome, { recursive: true, force: true });
+        fs_1.default.rmSync(tmpWork, { recursive: true, force: true });
     });
-    it('routes antigravity global workflows correctly', () => {
-        const result = (0, providers_1.getTargetPath)('workflow', 'antigravity', 'global');
-        expect(result).toBe(`${os_1.default.homedir()}/.gemini/antigravity/global_workflows`);
+    it('resolves Codex paths from the current HOME at call time', () => {
+        const first = fs_1.default.mkdtempSync(path_1.default.join(tmpWork, 'awm-home-a-'));
+        const second = fs_1.default.mkdtempSync(path_1.default.join(tmpWork, 'awm-home-b-'));
+        process.env.HOME = first;
+        expect((0, providers_1.getTargetPath)('skill', 'codex', 'global'))
+            .toBe(path_1.default.join(first, '.agents/skills'));
+        process.env.HOME = second;
+        expect((0, providers_1.getTargetPath)('agent', 'codex', 'global'))
+            .toBe(path_1.default.join(second, '.codex/agents'));
     });
-    it('throws on opencode workflow', () => {
-        expect(() => (0, providers_1.getTargetPath)('workflow', 'opencode', 'global')).toThrow('not supported');
+    it('returns a fresh provider graph using current HOME and AWM_HOME', () => {
+        const first = (0, providers_1.providers)();
+        const nextHome = path_1.default.join(tmpWork, 'next-home');
+        const nextAwmHome = path_1.default.join(tmpWork, 'next-awm');
+        process.env.HOME = nextHome;
+        process.env.AWM_HOME = nextAwmHome;
+        const second = (0, providers_1.providers)();
+        expect(second).not.toBe(first);
+        expect(second.codex.skill.global).toBe(path_1.default.join(nextHome, '.agents/skills'));
+        expect(second.codex.hooks?.scriptsDir).toBe(path_1.default.join(nextAwmHome, 'hooks/codex'));
+        expect(first.codex.skill.global).toBe(path_1.default.join(tmpHome, '.agents/skills'));
     });
-    // ── New Claude Code tests ──
-    it('routes claude-code global skills correctly', () => {
-        const result = (0, providers_1.getTargetPath)('skill', 'claude-code', 'global');
-        expect(result).toBe(`${os_1.default.homedir()}/.claude/skills`);
+    it('declares the complete Codex capability metadata', () => {
+        expect((0, providers_1.providerFor)('codex')).toEqual({
+            label: 'Codex',
+            minimumVersion: '0.145.0',
+            versionCommand: { command: 'codex', args: ['--version'] },
+            skill: {
+                global: path_1.default.join(tmpHome, '.agents/skills'),
+                local: '.agents/skills',
+                renderer: 'link',
+            },
+            workflow: null,
+            agent: {
+                global: path_1.default.join(tmpHome, '.codex/agents'),
+                local: '.codex/agents',
+                renderer: 'codex-agent-toml',
+            },
+            hooks: {
+                type: 'codex-hooks-json',
+                settingsPath: path_1.default.join(tmpHome, '.codex/hooks.json'),
+                scriptsDir: path_1.default.join(process.env.AWM_HOME, 'hooks/codex'),
+                matcher: 'startup|resume|clear|compact',
+                eventName: 'SessionStart',
+            },
+            injection: {
+                type: 'managed-agents-md',
+                globalPath: path_1.default.join(tmpHome, '.codex/AGENTS.md'),
+                localFile: 'AGENTS.md',
+            },
+        });
     });
-    it('routes claude-code local skills correctly', () => {
-        const result = (0, providers_1.getTargetPath)('skill', 'claude-code', 'local');
-        expect(result).toBe('.claude/skills');
+    it('keeps Claude Code, OpenCode, and Antigravity contracts unchanged', () => {
+        const graph = (0, providers_1.providers)();
+        expect(graph.antigravity).toEqual({
+            label: 'Antigravity',
+            skill: {
+                global: path_1.default.join(tmpHome, '.gemini/antigravity/skills'),
+                local: '.agent/skills',
+                renderer: 'link',
+            },
+            workflow: {
+                global: path_1.default.join(tmpHome, '.gemini/antigravity/global_workflows'),
+                local: '.agent/workflows',
+                renderer: 'link',
+            },
+            agent: null,
+        });
+        expect(graph.opencode).toEqual({
+            label: 'OpenCode',
+            skill: {
+                global: path_1.default.join(tmpHome, '.agents/skills'),
+                local: '.agents/skills',
+                renderer: 'link',
+            },
+            workflow: null,
+            agent: {
+                global: path_1.default.join(tmpHome, '.config/opencode/agents'),
+                local: '.agents/profiles',
+                renderer: 'link',
+            },
+            injection: {
+                type: 'config-instructions',
+                configPath: path_1.default.join(tmpHome, '.config/opencode/opencode.json'),
+                field: 'instructions',
+            },
+        });
+        expect(graph['claude-code']).toEqual({
+            label: 'Claude Code',
+            skill: {
+                global: path_1.default.join(tmpHome, '.claude/skills'),
+                local: '.claude/skills',
+                renderer: 'link',
+            },
+            workflow: null,
+            agent: {
+                global: path_1.default.join(tmpHome, '.claude/agents'),
+                local: '.claude/agents',
+                renderer: 'link',
+            },
+            hooks: {
+                type: 'cc-settings-merge',
+                settingsPath: path_1.default.join(tmpHome, '.claude/settings.json'),
+                scriptsDir: path_1.default.join(process.env.AWM_HOME, 'hooks'),
+                matcher: 'startup|clear|compact',
+                eventName: 'SessionStart',
+            },
+            injection: { type: 'cc-settings-merge' },
+        });
     });
-    it('routes claude-code global agents correctly', () => {
-        const result = (0, providers_1.getTargetPath)('agent', 'claude-code', 'global');
-        expect(result).toBe(`${os_1.default.homedir()}/.claude/agents`);
+    it('keeps Claude Code and OpenCode destinations unchanged', () => {
+        expect((0, providers_1.getTargetPath)('skill', 'claude-code', 'global'))
+            .toBe(path_1.default.join(process.env.HOME, '.claude/skills'));
+        expect((0, providers_1.getTargetPath)('skill', 'opencode', 'global'))
+            .toBe(path_1.default.join(process.env.HOME, '.agents/skills'));
     });
-    it('routes claude-code local agents correctly', () => {
-        const result = (0, providers_1.getTargetPath)('agent', 'claude-code', 'local');
-        expect(result).toBe('.claude/agents');
+    it('uses AGENT_TARGETS as the single iterable target catalog', () => {
+        expect(providers_1.AGENT_TARGETS).toEqual(['antigravity', 'opencode', 'claude-code', 'codex']);
+        expect(Object.keys((0, providers_1.providers)())).toEqual([...providers_1.AGENT_TARGETS]);
     });
-    it('throws on claude-code workflow', () => {
+    it('throws on unsupported artifacts', () => {
+        expect(() => (0, providers_1.getTargetPath)('workflow', 'opencode', 'global')).toThrow('not supported');
         expect(() => (0, providers_1.getTargetPath)('workflow', 'claude-code', 'global')).toThrow('not supported');
+        expect(() => (0, providers_1.getTargetPath)('agent', 'antigravity', 'local')).toThrow('not supported');
     });
-    it('throws on unknown agent target', () => {
-        expect(() => (0, providers_1.getTargetPath)('skill', 'unknown-agent', 'global')).toThrow('Unknown agent target');
-    });
-    // ── PROVIDERS map structure tests ──
-    it('exports PROVIDERS with all three targets', () => {
-        expect(Object.keys(providers_1.PROVIDERS)).toEqual(expect.arrayContaining(['antigravity', 'opencode', 'claude-code']));
-    });
-    it('marks unsupported artifact types as null', () => {
-        expect(providers_1.PROVIDERS['antigravity'].agent).toBeNull();
-        expect(providers_1.PROVIDERS['opencode'].workflow).toBeNull();
-        expect(providers_1.PROVIDERS['claude-code'].workflow).toBeNull();
+    it('fails loudly for invalid runtime provider input', () => {
+        expect(() => (0, providers_1.providerFor)('unknown-agent')).toThrow('Unknown agent target');
+        expect(() => (0, providers_1.getTargetPath)('skill', 'unknown-agent', 'global'))
+            .toThrow('Unknown agent target');
     });
 });

package/dist/tests/structural/codex-agent-escaping-completeness.test.js

@@ -0,0 +1,77 @@
+"use strict";
+// Structural regression guard for the recurring class of bug found across
+// multiple review rounds in this repo's history (harness-retro,
+// 2026-07-25 — codex-cli-provider-plan): the Codex TOML renderer's
+// character-escaping was fixed piecemeal, one control character at a time
+// (quote runs, then DEL, then the rest of the C0 range), because each fix
+// only tested the specific character it addressed rather than the full
+// class. This test exercises the ENTIRE character class the renderer must
+// escape in one pass, so a future partial regression (e.g. someone "fixing"
+// tomlMultiline for a new case and narrowing the character class by
+// accident) fails immediately instead of waiting for another review round
+// to notice one more missed code point.
+//
+// Deliberately does not import the renderer's private helpers (tomlString/
+// tomlMultiline aren't exported) — it drives the same public entry point
+// (`renderCodexAgent`) real callers use, and inspects the actual TOML text.
+Object.defineProperty(exports, "__esModule", { value: true });
+const codex_agent_1 = require("../../src/core/renderers/codex-agent");
+// Every C0 control character other than tab (0x09) and newline (0x0A), plus
+// DEL (0x7F) — the full set TOML requires escaping in both single-line and
+// multi-line basic strings.
+const REQUIRES_ESCAPE = [
+    ...Array.from({ length: 0x09 }, (_, i) => i), // 0x00-0x08
+    ...Array.from({ length: 0x1f - 0x0b + 1 }, (_, i) => 0x0b + i), // 0x0B-0x1F
+    0x7f,
+];
+function canonicalAgentWith(instructions, description = 'd') {
+    return `---\nname: test-agent\ndescription: ${description}\n---\n\n${instructions}\n`;
+}
+// A run of embedded quotes long enough to exercise the original critical bug
+// (a naive `/"""/g` replace mis-escaped runs whose length was >3 and not a
+// multiple of 3 — e.g. 4, 5, 7, 8 consecutive quotes).
+const QUOTE_RUN_LENGTHS = [1, 3, 4, 5, 7, 8];
+describe('codex-agent renderer — escaping completeness (structural)', () => {
+    it('escapes every C0-minus-tab/newline control character and DEL as \\uXXXX in developer_instructions', () => {
+        const body = REQUIRES_ESCAPE.map((code) => `x${String.fromCharCode(code)}y`).join('|');
+        const toml = (0, codex_agent_1.renderCodexAgent)(canonicalAgentWith(body));
+        for (const code of REQUIRES_ESCAPE) {
+            const raw = String.fromCharCode(code);
+            expect(toml).not.toContain(raw); // no literal control byte survives
+            const escape = `\\u${code.toString(16).padStart(4, '0')}`;
+            expect(toml).toContain(escape);
+        }
+    });
+    it('never leaves a run of 3+ unescaped double quotes for any embedded quote-run length', () => {
+        for (const length of QUOTE_RUN_LENGTHS) {
+            const body = `before ${'"'.repeat(length)} after`;
+            const toml = (0, codex_agent_1.renderCodexAgent)(canonicalAgentWith(body));
+            // Strip the legitimate opening/closing """ delimiters, then confirm
+            // no 3-consecutive-unescaped-quote run remains inside the body —
+            // that would prematurely close a TOML multi-line basic string.
+            const startMarker = 'developer_instructions = """\n';
+            const start = toml.indexOf(startMarker) + startMarker.length;
+            const end = toml.lastIndexOf('\n"""');
+            const rendered = toml.slice(start, end);
+            expect(rendered).not.toMatch(/(?<!\\)"""/);
+        }
+    });
+    it('tab and newline stay raw (legitimately unescaped in a TOML multi-line basic string)', () => {
+        const toml = (0, codex_agent_1.renderCodexAgent)(canonicalAgentWith('line one\twith tab\nline two'));
+        expect(toml).toContain('line one\twith tab\nline two');
+    });
+    it('produces output parseable as a TOML multi-line basic string boundary (no stray raw quote runs at all)', () => {
+        // Combine control chars + quotes + backslashes in one body — the
+        // realistic worst case, not just each hazard in isolation.
+        const body = `a\\b"""c${String.fromCharCode(0x00)}d${String.fromCharCode(0x1f)}e${String.fromCharCode(0x7f)}f`;
+        const toml = (0, codex_agent_1.renderCodexAgent)(canonicalAgentWith(body));
+        const startMarker = 'developer_instructions = """\n';
+        const start = toml.indexOf(startMarker) + startMarker.length;
+        const end = toml.lastIndexOf('\n"""');
+        const rendered = toml.slice(start, end);
+        expect(rendered).not.toMatch(/(?<!\\)"""/);
+        expect(rendered).not.toContain(String.fromCharCode(0x00));
+        expect(rendered).not.toContain(String.fromCharCode(0x1f));
+        expect(rendered).not.toContain(String.fromCharCode(0x7f));
+    });
+});

package/dist/tests/ui/provider-preflight.test.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const provider_preflight_1 = require("../../src/ui/provider-preflight");
+describe.each(['--all', 'regular'])('%s add preflight boundary', (flow) => {
+    it('reports the exact error and stops before install or preference writes', () => {
+        const error = jest.fn();
+        const exit = jest.fn();
+        const installArtifact = jest.fn();
+        const savePreferences = jest.fn();
+        const pairs = [
+            { agent: 'codex', artifact: { type: 'skill' } },
+            { agent: 'codex', artifact: { type: 'agent' } },
+        ];
+        const proceed = (0, provider_preflight_1.preflightLinkArtifactsForCli)(pairs, { error, exit });
+        if (proceed) {
+            installArtifact(flow);
+            savePreferences(flow);
+        }
+        expect(proceed).toBe(false);
+        expect(error).toHaveBeenCalledWith("Renderer 'codex-agent-toml' for codex agent artifacts is not implemented yet");
+        expect(exit).toHaveBeenCalledWith(1);
+        expect(installArtifact).not.toHaveBeenCalled();
+        expect(savePreferences).not.toHaveBeenCalled();
+    });
+});

package/dist/tests/utils/config.test.js

@@ -3,34 +3,194 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-// tests/utils/config.test.ts
-const config_1 = require("../../src/utils/config");
 const fs_1 = __importDefault(require("fs"));
-const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
 describe('Preferences Manager', () => {
-    let tmpDir;
+    let tmpHome;
+    let tmpWork;
+    let originalHome;
+    let originalAwmHome;
     beforeEach(() => {
-        tmpDir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-prefs-'));
-        process.env.AWM_HOME = tmpDir;
+        tmpHome = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-prefs-home-'));
+        tmpWork = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-prefs-work-'));
+        originalHome = process.env.HOME;
+        originalAwmHome = process.env.AWM_HOME;
+        process.env.HOME = tmpHome;
+        process.env.AWM_HOME = tmpHome;
+        jest.resetModules();
     });
     afterEach(() => {
-        delete process.env.AWM_HOME;
-        fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+        if (originalHome === undefined)
+            delete process.env.HOME;
+        else
+            process.env.HOME = originalHome;
+        if (originalAwmHome === undefined)
+            delete process.env.AWM_HOME;
+        else
+            process.env.AWM_HOME = originalAwmHome;
+        jest.resetModules();
+        fs_1.default.rmSync(tmpHome, { recursive: true, force: true });
+        fs_1.default.rmSync(tmpWork, { recursive: true, force: true });
     });
-    it('creates default preferences if none exist (default agent is claude-code)', () => {
-        const prefs = (0, config_1.getPreferences)();
-        expect(prefs.defaultAgent).toBe('claude-code');
+    it('creates default preferences if none exist', () => {
+        const { getPreferences } = require('../../src/utils/config');
+        expect(getPreferences()).toEqual({
+            defaultAgent: 'claude-code',
+            enabledAgents: ['claude-code'],
+            installMethod: 'symlink',
+            defaultScope: 'local',
+        });
     });
     it('preferencesExist reflects whether the file is on disk', () => {
-        expect((0, config_1.preferencesExist)()).toBe(false);
-        (0, config_1.getPreferences)(); // side-effect: persists defaults
-        expect((0, config_1.preferencesExist)()).toBe(true);
+        const { getPreferences, preferencesExist } = require('../../src/utils/config');
+        expect(preferencesExist()).toBe(false);
+        getPreferences();
+        expect(preferencesExist()).toBe(true);
     });
     it('saves and loads preferences correctly', () => {
-        (0, config_1.savePreferences)({ defaultAgent: 'opencode', installMethod: 'copy', defaultScope: 'local' });
-        const prefs = (0, config_1.getPreferences)();
-        expect(prefs.defaultAgent).toBe('opencode');
-        expect(prefs.installMethod).toBe('copy');
+        const { getPreferences, savePreferences } = require('../../src/utils/config');
+        savePreferences({
+            defaultAgent: 'opencode',
+            enabledAgents: ['opencode'],
+            installMethod: 'copy',
+            defaultScope: 'local',
+        });
+        expect(getPreferences()).toEqual({
+            defaultAgent: 'opencode',
+            enabledAgents: ['opencode'],
+            installMethod: 'copy',
+            defaultScope: 'local',
+        });
+    });
+    it('migrates defaultAgent without losing optional preferences', () => {
+        fs_1.default.writeFileSync(path_1.default.join(tmpHome, 'preferences.json'), JSON.stringify({
+            defaultAgent: 'claude-code',
+            installMethod: 'symlink',
+            defaultScope: 'local',
+            baseRemote: 'https://example.test/baseline.git',
+            channel: 'dev',
+            pins: { baseline: '1.4.0' },
+            futurePreference: { mode: 'preview' },
+        }));
+        const { getPreferences } = require('../../src/utils/config');
+        const prefs = getPreferences();
+        expect(prefs.enabledAgents).toEqual(['claude-code']);
+        expect(prefs.baseRemote).toBe('https://example.test/baseline.git');
+        expect(prefs.channel).toBe('dev');
+        expect(prefs.pins).toEqual({ baseline: '1.4.0' });
+        expect(prefs.futurePreference)
+            .toEqual({ mode: 'preview' });
+        expect(JSON.parse(fs_1.default.readFileSync(path_1.default.join(tmpHome, 'preferences.json'), 'utf8')))
+            .toEqual(prefs);
+    });
+    it('does not overwrite malformed preferences', () => {
+        const file = path_1.default.join(tmpHome, 'preferences.json');
+        fs_1.default.writeFileSync(file, '{"defaultAgent":');
+        const before = fs_1.default.readFileSync(file, 'utf8');
+        const { getPreferences } = require('../../src/utils/config');
+        expect(() => getPreferences()).toThrow('preferences.json is not valid JSON');
+        expect(fs_1.default.readFileSync(file, 'utf8')).toBe(before);
+    });
+    it('deduplicates enabled agents and requires the default to remain enabled', () => {
+        fs_1.default.writeFileSync(path_1.default.join(tmpHome, 'preferences.json'), JSON.stringify({
+            defaultAgent: 'claude-code',
+            enabledAgents: ['claude-code', 'codex', 'codex'],
+            installMethod: 'symlink',
+            defaultScope: 'local',
+        }));
+        const { getPreferences } = require('../../src/utils/config');
+        expect(getPreferences().enabledAgents).toEqual(['claude-code', 'codex']);
+    });
+    it('rejects preferences whose default agent is disabled', () => {
+        fs_1.default.writeFileSync(path_1.default.join(tmpHome, 'preferences.json'), JSON.stringify({
+            defaultAgent: 'claude-code',
+            enabledAgents: ['codex'],
+            installMethod: 'symlink',
+            defaultScope: 'local',
+        }));
+        const { getPreferences } = require('../../src/utils/config');
+        expect(() => getPreferences())
+            .toThrow('preferences.json defaultAgent must be included in enabledAgents');
+    });
+    it.each([
+        ['a non-object value', [], 'preferences.json must contain a JSON object'],
+        ['an invalid defaultAgent', {
+                defaultAgent: 'unknown',
+                installMethod: 'symlink',
+                defaultScope: 'local',
+            }, 'preferences.json has an invalid defaultAgent'],
+        ['an invalid installMethod', {
+                defaultAgent: 'claude-code',
+                installMethod: 'hardlink',
+                defaultScope: 'local',
+            }, 'preferences.json has an invalid installMethod'],
+        ['an invalid defaultScope', {
+                defaultAgent: 'claude-code',
+                installMethod: 'symlink',
+                defaultScope: 'workspace',
+            }, 'preferences.json has an invalid defaultScope'],
+        ['an invalid enabledAgents field', {
+                defaultAgent: 'claude-code',
+                enabledAgents: ['claude-code', 'unknown'],
+                installMethod: 'symlink',
+                defaultScope: 'local',
+            }, 'preferences.json has an invalid enabledAgents'],
+    ])('rejects %s', (_name, value, message) => {
+        fs_1.default.writeFileSync(path_1.default.join(tmpHome, 'preferences.json'), JSON.stringify(value));
+        const { getPreferences } = require('../../src/utils/config');
+        expect(() => getPreferences()).toThrow(message);
+    });
+    it.each([
+        ['an empty baseRemote', { baseRemote: '' }, 'preferences.json has an invalid baseRemote'],
+        ['a non-string baseRemote', { baseRemote: 42 }, 'preferences.json has an invalid baseRemote'],
+        ['an invalid channel', { channel: 'preview' }, 'preferences.json has an invalid channel'],
+        ['an array pins value', { pins: [] }, 'preferences.json has invalid pins'],
+        ['a null pins value', { pins: null }, 'preferences.json has invalid pins'],
+        ['an empty pin name', { pins: { '': '1.2.3' } }, 'preferences.json has invalid pins'],
+        ['an empty pin value', { pins: { baseline: '' } }, 'preferences.json has invalid pins'],
+        ['a non-string pin value', { pins: { baseline: 123 } }, 'preferences.json has invalid pins'],
+    ])('rejects %s without overwriting the file', (_name, invalidField, message) => {
+        const file = path_1.default.join(tmpHome, 'preferences.json');
+        const before = JSON.stringify({
+            defaultAgent: 'claude-code',
+            enabledAgents: ['claude-code'],
+            installMethod: 'symlink',
+            defaultScope: 'local',
+            ...invalidField,
+        });
+        fs_1.default.writeFileSync(file, before);
+        const { getPreferences } = require('../../src/utils/config');
+        expect(() => getPreferences()).toThrow(message);
+        expect(fs_1.default.readFileSync(file, 'utf8')).toBe(before);
+    });
+    it('rejects incomplete updates without dropping enabled agents', () => {
+        const config = require('../../src/utils/config');
+        config.savePreferences({
+            defaultAgent: 'claude-code',
+            enabledAgents: ['claude-code', 'codex'],
+            installMethod: 'symlink',
+            defaultScope: 'local',
+        });
+        const incomplete = {
+            defaultAgent: 'opencode',
+            installMethod: 'copy',
+            defaultScope: 'global',
+        };
+        expect(() => {
+            // @ts-expect-error enabledAgents is required for every preference update
+            config.savePreferences(incomplete);
+        }).toThrow('preferences.json has an invalid enabledAgents');
+        expect(config.getPreferences().enabledAgents).toEqual(['claude-code', 'codex']);
+    });
+    it('validates preferences before saving them', () => {
+        const { savePreferences } = require('../../src/utils/config');
+        expect(() => savePreferences({
+            defaultAgent: 'codex',
+            enabledAgents: ['claude-code'],
+            installMethod: 'symlink',
+            defaultScope: 'local',
+        })).toThrow('preferences.json defaultAgent must be included in enabledAgents');
+        expect(fs_1.default.existsSync(path_1.default.join(tmpHome, 'preferences.json'))).toBe(false);
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-workflow-manager",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "main": "dist/src/index.js",
   "bin": {
     "awm": "./dist/src/index.js"