clawmini 0.0.8 → 0.0.9

package/e2e/cli/auto-update.test.ts

@@ -0,0 +1,741 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import path from 'node:path';
+import fs from 'node:fs';
+import { TestEnvironment } from '../_helpers/test-environment.js';
+import {
+  readEnvironment,
+  getEnvironmentSearchDirs,
+  substituteLayeredEnvDir,
+  readEnvironmentPoliciesForPath,
+  writeSettings,
+  getAgent,
+  getAgentOverlay,
+  writeAgentSettings,
+} from '../../src/shared/workspace.js';
+
+describe('E2E Auto-update: lite refresh on `up`', () => {
+  let env: TestEnvironment;
+
+  beforeEach(async () => {
+    env = new TestEnvironment('e2e-au-lite');
+    await env.setup();
+    await env.init();
+  }, 30000);
+
+  afterEach(() => env.teardown(), 30000);
+
+  async function enableMacos() {
+    const { code } = await env.runCli(['environments', 'enable', 'macos']);
+    expect(code).toBe(0);
+  }
+
+  it('up refreshes clawmini-lite.js for active environments', async () => {
+    await enableMacos();
+    const { code } = await env.up();
+    expect(code).toBe(0);
+
+    const litePath = path.join(env.e2eDir, '.local', 'bin', 'clawmini-lite.js');
+    expect(fs.existsSync(litePath)).toBe(true);
+
+    const content = fs.readFileSync(litePath, 'utf8');
+    expect(content).toContain('clawmini-lite - A standalone client');
+    expect(content.startsWith('#!')).toBe(true);
+  });
+
+  it('up skips lite write when content matches (no mtime touch)', async () => {
+    await enableMacos();
+    await env.up();
+    const litePath = path.join(env.e2eDir, '.local', 'bin', 'clawmini-lite.js');
+    const firstMtime = fs.statSync(litePath).mtimeMs;
+
+    // Small wait to ensure mtime resolution could advance if we did rewrite
+    await new Promise((r) => setTimeout(r, 50));
+
+    await env.down();
+    await env.up();
+    const secondMtime = fs.statSync(litePath).mtimeMs;
+    expect(secondMtime).toBe(firstMtime);
+  });
+
+  it('up refuses to overwrite a non-clawmini file at the export path', async () => {
+    await enableMacos();
+    const litePath = path.join(env.e2eDir, '.local', 'bin', 'clawmini-lite.js');
+    fs.mkdirSync(path.dirname(litePath), { recursive: true });
+    const sentinel = 'totally not a lite script\n';
+    fs.writeFileSync(litePath, sentinel);
+
+    const { stderr } = await env.up();
+    expect(fs.readFileSync(litePath, 'utf8')).toBe(sentinel);
+    expect(stderr).toContain('Refusing to overwrite');
+  });
+
+  it('environments enable writes a thin overlay by default', async () => {
+    const { code } = await env.runCli(['environments', 'enable', 'macos']);
+    expect(code).toBe(0);
+    const envDir = env.getClawminiPath('environments', 'macos');
+    const envJson = JSON.parse(fs.readFileSync(path.join(envDir, 'env.json'), 'utf8'));
+    expect(envJson).toEqual({ extends: 'macos' });
+    // Built-in files are not cloned into the overlay dir.
+    expect(fs.existsSync(path.join(envDir, 'sandbox.sb'))).toBe(false);
+  });
+
+  it('environments enable --fork clones the built-in template directory', async () => {
+    const { code } = await env.runCli(['environments', 'enable', 'macos', '--fork']);
+    expect(code).toBe(0);
+    const envDir = env.getClawminiPath('environments', 'macos');
+    const envJson = JSON.parse(fs.readFileSync(path.join(envDir, 'env.json'), 'utf8'));
+    expect(envJson.extends).toBeUndefined();
+    expect(envJson.prefix).toContain('sandbox-exec');
+    expect(fs.existsSync(path.join(envDir, 'sandbox.sb'))).toBe(true);
+  });
+
+  it('overlay with self-extends resolves through the built-in', async () => {
+    const { code } = await env.runCli(['environments', 'enable', 'macos']);
+    expect(code).toBe(0);
+    const resolved = await readEnvironment('macos', env.e2eDir);
+    expect(resolved).toBeTruthy();
+    expect(resolved!.prefix).toContain('sandbox-exec');
+    expect(resolved!.exportLiteTo).toBe('.local/bin/clawmini-lite.js');
+    expect(typeof resolved!.env?.PATH).toBe('string');
+  });
+
+  it('up does not place a default lite shim when no environment is active', async () => {
+    const { code } = await env.up();
+    expect(code).toBe(0);
+
+    // Nothing should place clawmini-lite.js anywhere outside .clawmini
+    const walk = (dir: string): string[] => {
+      const result: string[] = [];
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === '.clawmini' || entry.name === '.git' || entry.name === 'node_modules') {
+          continue;
+        }
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          result.push(...walk(full));
+        } else {
+          result.push(full);
+        }
+      }
+      return result;
+    };
+    const files = walk(env.e2eDir);
+    const stray = files.filter((p) => path.basename(p) === 'clawmini-lite.js');
+    expect(stray).toEqual([]);
+  });
+});
+
+describe('E2E Auto-update: environment overlay (`extends`)', () => {
+  let env: TestEnvironment;
+
+  beforeEach(async () => {
+    env = new TestEnvironment('e2e-au-env');
+    await env.setup();
+    await env.init();
+  }, 30000);
+
+  afterEach(() => env.teardown(), 30000);
+
+  function writeOverlayEnv(name: string, data: Record<string, unknown>) {
+    const overlayDir = env.getClawminiPath('environments', name);
+    fs.mkdirSync(overlayDir, { recursive: true });
+    fs.writeFileSync(path.join(overlayDir, 'env.json'), JSON.stringify(data, null, 2));
+    return overlayDir;
+  }
+
+  it('environment with extends inherits built-in env.json fields', async () => {
+    writeOverlayEnv('my-macos', {
+      extends: 'macos',
+      env: { MY_VAR: 'v' },
+    });
+    await writeSettings({ environments: { './': 'my-macos' } }, env.e2eDir);
+
+    const resolved = await readEnvironment('my-macos', env.e2eDir);
+    expect(resolved).toBeTruthy();
+    // `prefix` and `exportLiteTo` from the built-in macos flow through.
+    expect(resolved!.prefix).toContain('sandbox-exec');
+    expect(resolved!.exportLiteTo).toBe('.local/bin/clawmini-lite.js');
+    // `env` is deep-merged at one level — MY_VAR added without dropping PATH.
+    expect(resolved!.env?.MY_VAR).toBe('v');
+    expect(typeof resolved!.env?.PATH).toBe('string');
+  });
+
+  it('{ENV_DIR} resolution falls back to built-in for missing local files', async () => {
+    const overlayDir = writeOverlayEnv('my-macos', { extends: 'macos' });
+    await writeSettings({ environments: { './': 'my-macos' } }, env.e2eDir);
+
+    const searchDirs = await getEnvironmentSearchDirs('my-macos', env.e2eDir);
+    expect(searchDirs[0]).toBe(overlayDir);
+    // The built-in macos template dir should come second.
+    const builtinDir = searchDirs.find((d) => d.includes('templates/environments/macos'));
+    expect(builtinDir).toBeTruthy();
+
+    const resolved = substituteLayeredEnvDir('{ENV_DIR}/sandbox.sb', searchDirs);
+    expect(resolved).toBe(path.join(builtinDir!, 'sandbox.sb'));
+
+    // Dropping a local sandbox.sb makes the overlay win.
+    fs.writeFileSync(path.join(overlayDir, 'sandbox.sb'), '; local\n');
+    const resolvedLocal = substituteLayeredEnvDir('{ENV_DIR}/sandbox.sb', searchDirs);
+    expect(resolvedLocal).toBe(path.join(overlayDir, 'sandbox.sb'));
+  });
+
+  it('layered resolution picks overlay policy script when it exists', async () => {
+    const overlayDir = writeOverlayEnv('my-cladding', {
+      extends: 'cladding',
+      policies: {
+        'allowlist-domain': { command: './allowlist-domain.mjs' },
+      },
+    });
+    fs.writeFileSync(path.join(overlayDir, 'allowlist-domain.mjs'), '#!/usr/bin/env node\n');
+    await writeSettings({ environments: { './': 'my-cladding' } }, env.e2eDir);
+
+    const policies = await readEnvironmentPoliciesForPath('./', env.e2eDir);
+    expect(policies['allowlist-domain']?.command).toBe(
+      path.join(overlayDir, 'allowlist-domain.mjs')
+    );
+  });
+
+  it('layered resolution falls back to built-in policy script', async () => {
+    writeOverlayEnv('my-cladding', { extends: 'cladding' });
+    await writeSettings({ environments: { './': 'my-cladding' } }, env.e2eDir);
+
+    const policies = await readEnvironmentPoliciesForPath('./', env.e2eDir);
+    const cmd = policies['allowlist-domain']?.command;
+    expect(cmd).toBeTruthy();
+    expect(cmd).toContain('templates/environments/cladding/allowlist-domain.mjs');
+  });
+});
+
+describe('E2E Auto-update: agent overlay (`extends`)', () => {
+  let env: TestEnvironment;
+
+  beforeEach(async () => {
+    env = new TestEnvironment('e2e-au-agent');
+    await env.setup();
+    await env.init();
+  }, 30000);
+
+  afterEach(() => env.teardown(), 30000);
+
+  it('agents add --template writes overlay shape with extends', async () => {
+    const { code } = await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    expect(code).toBe(0);
+
+    const overlay = env.getAgentSettings('bob');
+    expect(overlay.extends).toBe('gemini-claw');
+    // The overlay should not contain merged-in template fields like
+    // `commands`, `apiTokenEnvVar`, etc.
+    expect(overlay.commands).toBeUndefined();
+    expect(overlay.apiTokenEnvVar).toBeUndefined();
+  });
+
+  it('getAgent merges template fields into local fields', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const resolved = await getAgent('bob', env.e2eDir);
+    expect(resolved).toBeTruthy();
+    expect(resolved!.apiTokenEnvVar).toBe('GEMINI_CLI_CLAW_API_TOKEN');
+    expect(resolved!.commands?.new).toContain('gemini');
+    expect(resolved!.skillsDir).toBe('.gemini/skills/');
+    expect(resolved!.fallbacks?.length).toBeGreaterThan(0);
+  });
+
+  it('local field overrides template field shallowly', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const overlay = (await getAgentOverlay('bob', env.e2eDir)) || {};
+    overlay.commands = { new: 'echo local-command' };
+    await writeAgentSettings('bob', overlay, env.e2eDir);
+
+    const resolved = await getAgent('bob', env.e2eDir);
+    expect(resolved!.commands?.new).toBe('echo local-command');
+    // Shallow override — template's `append` is also replaced.
+    expect(resolved!.commands?.append).toBeUndefined();
+  });
+
+  it('env deep-merges one level', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const overlay = (await getAgentOverlay('bob', env.e2eDir)) || {};
+    overlay.env = { MODEL: 'gemini-custom' };
+    await writeAgentSettings('bob', overlay, env.e2eDir);
+
+    const resolved = await getAgent('bob', env.e2eDir);
+    expect(resolved!.env?.MODEL).toBe('gemini-custom');
+    // Template entries flow through (GEMINI_SYSTEM_MD, GEMINI_API_KEY).
+    expect(resolved!.env?.GEMINI_SYSTEM_MD).toBe('true');
+    expect(resolved!.env?.GEMINI_API_KEY).toBe(true);
+  });
+
+  it('agents add --fork copies everything and writes no extends', async () => {
+    const { code } = await env.runCli([
+      'agents',
+      'add',
+      'bob',
+      '--template',
+      'gemini-claw',
+      '--fork',
+    ]);
+    expect(code).toBe(0);
+    const overlay = env.getAgentSettings('bob');
+    expect(overlay.extends).toBeUndefined();
+    // Fork mode merges template fields into the local file.
+    expect(overlay.apiTokenEnvVar).toBe('GEMINI_CLI_CLAW_API_TOKEN');
+    expect(overlay.skillsDir).toBe('.gemini/skills/');
+  });
+
+  it('agents add --fork records skill SHAs in installed-files.json', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw', '--fork']);
+    const installed = JSON.parse(
+      fs.readFileSync(env.getAgentPath('bob', 'installed-files.json'), 'utf8')
+    );
+    expect(installed.files['.gemini/skills/skill-creator/SKILL.md']).toBeTruthy();
+    expect(typeof installed.files['.gemini/skills/skill-creator/SKILL.md'].sha).toBe('string');
+  });
+
+  it('existing agent without extends is unchanged after up when skillsDir is null', async () => {
+    // skillsDir: null is the explicit opt-out from the universal skill-track
+    // refresh — without it, `up` installs skills into the agent's workdir.
+    fs.mkdirSync(path.join(env.e2eDir, 'legacy'), { recursive: true });
+    env.writeAgentSettings('legacy', {
+      directory: './legacy',
+      commands: { new: 'echo legacy' },
+      skillsDir: null,
+    });
+    const before = JSON.stringify(env.getAgentSettings('legacy'));
+
+    const { code } = await env.up();
+    expect(code).toBe(0);
+    const after = JSON.stringify(env.getAgentSettings('legacy'));
+    expect(after).toBe(before);
+    // Confirms the workdir wasn't seeded with skills either.
+    expect(fs.existsSync(path.join(env.e2eDir, 'legacy', '.agents'))).toBe(false);
+  }, 30000);
+
+  it('hand-written agent without extends gets skills installed on up', async () => {
+    fs.mkdirSync(path.join(env.e2eDir, 'legacy'), { recursive: true });
+    env.writeAgentSettings('legacy', {
+      directory: './legacy',
+      commands: { new: 'echo legacy' },
+    });
+
+    const { code } = await env.up();
+    expect(code).toBe(0);
+    const skill = path.join(
+      env.e2eDir,
+      'legacy',
+      '.agents',
+      'skills',
+      'skill-creator',
+      'SKILL.md'
+    );
+    expect(fs.existsSync(skill)).toBe(true);
+    const installed = JSON.parse(
+      fs.readFileSync(env.getAgentPath('legacy', 'installed-files.json'), 'utf8')
+    );
+    expect(installed.files['.agents/skills/skill-creator/SKILL.md']).toBeTruthy();
+  }, 30000);
+
+  it('template.json and settings.json are not copied into the agent workdir', async () => {
+    const { code } = await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    expect(code).toBe(0);
+    expect(fs.existsSync(path.join(env.e2eDir, 'bob', 'settings.json'))).toBe(false);
+    expect(fs.existsSync(path.join(env.e2eDir, 'bob', 'template.json'))).toBe(false);
+  });
+
+  it('agents add refuses to overwrite a colliding file without --force', async () => {
+    const workdir = path.join(env.e2eDir, 'bob');
+    fs.mkdirSync(path.join(workdir, '.gemini'), { recursive: true });
+    const systemPath = path.join(workdir, '.gemini', 'system.md');
+    fs.writeFileSync(systemPath, 'user content');
+
+    const { code, stderr } = await env.runCli([
+      'agents',
+      'add',
+      'bob',
+      '--template',
+      'gemini-claw',
+    ]);
+    expect(code).not.toBe(0);
+    expect(stderr).toContain('.gemini/system.md');
+    expect(stderr).toContain('--force');
+    expect(fs.readFileSync(systemPath, 'utf-8')).toBe('user content');
+  });
+
+  it('agents add --force overwrites colliding files', async () => {
+    const workdir = path.join(env.e2eDir, 'bob');
+    fs.mkdirSync(path.join(workdir, '.gemini'), { recursive: true });
+    const systemPath = path.join(workdir, '.gemini', 'system.md');
+    fs.writeFileSync(systemPath, 'user content');
+
+    const { code } = await env.runCli([
+      'agents',
+      'add',
+      'bob',
+      '--template',
+      'gemini-claw',
+      '--force',
+    ]);
+    expect(code).toBe(0);
+    expect(fs.readFileSync(systemPath, 'utf-8')).not.toBe('user content');
+  });
+
+  it('agents add leaves unrelated workdir files alone', async () => {
+    const workdir = path.join(env.e2eDir, 'bob');
+    fs.mkdirSync(workdir, { recursive: true });
+    const unrelated = path.join(workdir, 'README.md');
+    fs.writeFileSync(unrelated, 'project readme');
+
+    const { code } = await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    expect(code).toBe(0);
+    expect(fs.readFileSync(unrelated, 'utf-8')).toBe('project readme');
+  });
+
+  it('skillsDir: null opts out of skill refresh on up', async () => {
+    const { code: addCode } = await env.runCli([
+      'agents',
+      'add',
+      'bob',
+      '--template',
+      'gemini-claw',
+    ]);
+    expect(addCode).toBe(0);
+    const skillsDir = path.join(env.e2eDir, 'bob', '.gemini', 'skills');
+    expect(fs.existsSync(skillsDir)).toBe(true);
+
+    // User opts out and removes the installed skills.
+    const overlay = (await getAgentOverlay('bob', env.e2eDir)) || {};
+    overlay.skillsDir = null;
+    await writeAgentSettings('bob', overlay, env.e2eDir);
+    fs.rmSync(skillsDir, { recursive: true, force: true });
+
+    const { code: upCode } = await env.up();
+    expect(upCode).toBe(0);
+    // Skills directory stays removed — refresh skipped the opted-out agent.
+    expect(fs.existsSync(skillsDir)).toBe(false);
+  }, 30000);
+});
+
+describe('E2E Auto-update: template.json + SHA tracking', () => {
+  let env: TestEnvironment;
+
+  beforeEach(async () => {
+    env = new TestEnvironment('e2e-au-sha');
+    await env.setup();
+    await env.init();
+  }, 30000);
+
+  afterEach(() => env.teardown(), 30000);
+
+  it('new agent with --template records SHAs and creates installed-files.json', async () => {
+    const { code } = await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    expect(code).toBe(0);
+
+    const installedPath = env.getAgentPath('bob', 'installed-files.json');
+    expect(fs.existsSync(installedPath)).toBe(true);
+    const installed = JSON.parse(fs.readFileSync(installedPath, 'utf8'));
+    // Manifest declares GEMINI.md as track; an entry must exist.
+    expect(installed.files['GEMINI.md']).toBeTruthy();
+    expect(typeof installed.files['GEMINI.md'].sha).toBe('string');
+    // Seed-once files are also recorded at first install.
+    expect(installed.files['SOUL.md']).toBeTruthy();
+  });
+
+  it('recorded SHAs match the template content at create time', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+
+    const installedPath = env.getAgentPath('bob', 'installed-files.json');
+    const installed = JSON.parse(fs.readFileSync(installedPath, 'utf8'));
+
+    const workspaceRoot = path.resolve(__dirname, '..', '..');
+    const templateGemini = path.join(workspaceRoot, 'templates', 'gemini-claw', 'GEMINI.md');
+    const templateContent = fs.readFileSync(templateGemini);
+    const { createHash } = await import('node:crypto');
+    const expected = createHash('sha256').update(templateContent).digest('hex');
+    expect(installed.files['GEMINI.md'].sha).toBe(expected);
+  });
+
+  it('up does not copy template.json to the destination', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    expect(fs.existsSync(path.join(env.e2eDir, 'bob', 'template.json'))).toBe(false);
+    const { code } = await env.up();
+    expect(code).toBe(0);
+    expect(fs.existsSync(path.join(env.e2eDir, 'bob', 'template.json'))).toBe(false);
+  });
+
+  it('directory entries in the manifest apply recursively', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const installedPath = env.getAgentPath('bob', 'installed-files.json');
+    const installed = JSON.parse(fs.readFileSync(installedPath, 'utf8'));
+    // Everything under .gemini/ is 'track' per the manifest.
+    const gemini = Object.keys(installed.files).filter((k) => k.startsWith('.gemini/'));
+    expect(gemini.length).toBeGreaterThan(0);
+  });
+});
+
+describe('E2E Auto-update: agent refresh on `up`', () => {
+  let env: TestEnvironment;
+
+  beforeEach(async () => {
+    env = new TestEnvironment('e2e-au-up');
+    await env.setup();
+    await env.init();
+  }, 30000);
+
+  afterEach(() => env.teardown(), 30000);
+
+  it('up skips a track file when the agent edited it', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const tracked = path.join(env.e2eDir, 'bob', '.gemini', 'system.md');
+    const original = fs.readFileSync(tracked, 'utf8');
+    fs.writeFileSync(tracked, original + '\n<!-- agent edit -->');
+
+    const { stderr, code } = await env.up();
+    expect(code).toBe(0);
+    expect(stderr).toContain('differs from template');
+    expect(fs.readFileSync(tracked, 'utf8')).toContain('<!-- agent edit -->');
+  });
+
+  it('up never touches seed-once files', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const memory = path.join(env.e2eDir, 'bob', 'MEMORY.md');
+    fs.writeFileSync(memory, 'agent memory content\n');
+    const { code } = await env.up();
+    expect(code).toBe(0);
+    expect(fs.readFileSync(memory, 'utf8')).toBe('agent memory content\n');
+  });
+
+  it('up never touches files outside the manifest in the agent dir', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const extra = path.join(env.e2eDir, 'bob', 'agent-notes.txt');
+    fs.writeFileSync(extra, 'notes\n');
+    const { code } = await env.up();
+    expect(code).toBe(0);
+    expect(fs.readFileSync(extra, 'utf8')).toBe('notes\n');
+  });
+
+  it('up re-creates a track file that was deleted', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const tracked = path.join(env.e2eDir, 'bob', '.gemini', 'system.md');
+    fs.unlinkSync(tracked);
+
+    const { code } = await env.up();
+    expect(code).toBe(0);
+    expect(fs.existsSync(tracked)).toBe(true);
+  });
+
+  it('up does not re-create a seed-once file that was deleted', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const bootstrap = path.join(env.e2eDir, 'bob', 'BOOTSTRAP.md');
+    expect(fs.existsSync(bootstrap)).toBe(true);
+    fs.unlinkSync(bootstrap);
+
+    const { code } = await env.up();
+    expect(code).toBe(0);
+    expect(fs.existsSync(bootstrap)).toBe(false);
+  });
+
+  it('agents refresh --accept overwrites diverged files', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const tracked = path.join(env.e2eDir, 'bob', '.gemini', 'system.md');
+    fs.writeFileSync(tracked, 'diverged content\n');
+
+    const { code, stdout } = await env.runCli(['agents', 'refresh', 'bob', '--accept']);
+    expect(code).toBe(0);
+    expect(stdout).toContain('refresh');
+    expect(fs.readFileSync(tracked, 'utf8')).not.toBe('diverged content\n');
+  });
+
+  it('agents refresh scoped to a single agent leaves other agents alone', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    await env.runCli(['agents', 'add', 'alice', '--template', 'gemini-claw']);
+
+    const aliceGemini = path.join(env.e2eDir, 'alice', 'GEMINI.md');
+    fs.writeFileSync(aliceGemini, 'alice edited\n');
+
+    const { code } = await env.runCli(['agents', 'refresh', 'bob', '--accept']);
+    expect(code).toBe(0);
+    expect(fs.readFileSync(aliceGemini, 'utf8')).toBe('alice edited\n');
+  });
+
+  it('pre-existing agent without recorded SHAs gets strict skip + hint', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    // Simulate an old workspace: remove installed-files.json.
+    fs.unlinkSync(env.getAgentPath('bob', 'installed-files.json'));
+
+    const { stderr, code } = await env.up();
+    expect(code).toBe(0);
+    expect(stderr).toContain('no recorded SHA');
+  });
+});
+
+describe('E2E Auto-update: skills refresh on `up`', () => {
+  let env: TestEnvironment;
+
+  beforeEach(async () => {
+    env = new TestEnvironment('e2e-au-skill');
+    await env.setup();
+    await env.init();
+  }, 30000);
+
+  afterEach(() => env.teardown(), 30000);
+
+  function skillPath(agentId: string, skillName: string, file: string): string {
+    // gemini-claw's skillsDir is `.gemini/skills/`
+    return path.join(env.e2eDir, agentId, '.gemini', 'skills', skillName, file);
+  }
+
+  it('agents add --template installs skills and records SHAs under full paths', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const skill = skillPath('bob', 'skill-creator', 'SKILL.md');
+    expect(fs.existsSync(skill)).toBe(true);
+
+    const installed = JSON.parse(
+      fs.readFileSync(env.getAgentPath('bob', 'installed-files.json'), 'utf8')
+    );
+    expect(installed.files['.gemini/skills/skill-creator/SKILL.md']).toBeTruthy();
+  });
+
+  it('up refreshes all skill files when no template.json is present in the skill', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const skill = skillPath('bob', 'skill-creator', 'SKILL.md');
+    // Delete the file; up should re-seed it (track default).
+    fs.unlinkSync(skill);
+    const { code } = await env.up();
+    expect(code).toBe(0);
+    expect(fs.existsSync(skill)).toBe(true);
+  });
+
+  it('up skips diverged skill files', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const skill = skillPath('bob', 'skill-creator', 'SKILL.md');
+    fs.writeFileSync(skill, 'edited skill content\n');
+
+    const { stderr, code } = await env.up();
+    expect(code).toBe(0);
+    expect(stderr).toContain('differs from template');
+    expect(fs.readFileSync(skill, 'utf8')).toBe('edited skill content\n');
+  });
+
+  it('agents refresh --accept overwrites diverged skill files', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const skill = skillPath('bob', 'skill-creator', 'SKILL.md');
+    fs.writeFileSync(skill, 'edited\n');
+
+    const { code } = await env.runCli(['agents', 'refresh', 'bob', '--accept']);
+    expect(code).toBe(0);
+    expect(fs.readFileSync(skill, 'utf8')).not.toBe('edited\n');
+  });
+
+  it('skill template.json is never copied to the destination', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const tmpl = skillPath('bob', 'skill-creator', 'template.json');
+    expect(fs.existsSync(tmpl)).toBe(false);
+  });
+});
+
+describe('E2E Auto-update: --dry-run', () => {
+  let env: TestEnvironment;
+
+  beforeEach(async () => {
+    env = new TestEnvironment('e2e-au-dry');
+    await env.setup();
+    await env.init();
+  }, 30000);
+
+  afterEach(() => env.teardown(), 30000);
+
+  it('up --dry-run prints a plan and writes nothing', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    // Divergence + unchanged mix.
+    const gemini = path.join(env.e2eDir, 'bob', 'GEMINI.md');
+    fs.writeFileSync(gemini, 'edited\n');
+
+    const installedBefore = fs.readFileSync(
+      env.getAgentPath('bob', 'installed-files.json'),
+      'utf8'
+    );
+
+    const { stdout, code } = await env.runCli(['up', '--dry-run']);
+    expect(code).toBe(0);
+    expect(stdout).toMatch(/\[bob\]/);
+
+    // Nothing written back.
+    expect(fs.readFileSync(gemini, 'utf8')).toBe('edited\n');
+    const installedAfter = fs.readFileSync(env.getAgentPath('bob', 'installed-files.json'), 'utf8');
+    expect(installedAfter).toBe(installedBefore);
+  });
+
+  it('agents refresh --dry-run prints scoped plan and writes nothing', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    await env.runCli(['agents', 'add', 'alice', '--template', 'gemini-claw']);
+    const aliceGemini = path.join(env.e2eDir, 'alice', 'GEMINI.md');
+    fs.writeFileSync(aliceGemini, 'alice edit\n');
+    const bobGemini = path.join(env.e2eDir, 'bob', 'GEMINI.md');
+    fs.writeFileSync(bobGemini, 'bob edit\n');
+
+    const { stdout, code } = await env.runCli(['agents', 'refresh', 'bob', '--dry-run']);
+    expect(code).toBe(0);
+    // Output has entries (unchanged/diverged/seed-once).
+    expect(stdout.length).toBeGreaterThan(0);
+    // Neither file mutated.
+    expect(fs.readFileSync(bobGemini, 'utf8')).toBe('bob edit\n');
+    expect(fs.readFileSync(aliceGemini, 'utf8')).toBe('alice edit\n');
+  });
+
+  it('up --dry-run reports skill file changes for an extends-template agent', async () => {
+    await env.runCli(['agents', 'add', 'bob', '--template', 'gemini-claw']);
+    const skill = path.join(
+      env.e2eDir,
+      'bob',
+      '.gemini',
+      'skills',
+      'skill-creator',
+      'SKILL.md'
+    );
+    fs.writeFileSync(skill, 'edited skill\n');
+
+    const { stdout, code } = await env.runCli(['up', '--dry-run']);
+    expect(code).toBe(0);
+    expect(stdout).toContain('[bob] diverged .gemini/skills/skill-creator/SKILL.md');
+    // Nothing written back.
+    expect(fs.readFileSync(skill, 'utf8')).toBe('edited skill\n');
+  });
+
+  it('up --dry-run reports skill file changes for a custom (non-extends) agent', async () => {
+    // Forked agents have no `extends`, but skills are still tracked: dry-run
+    // must report skill plan actions for them just like extends agents.
+    await env.runCli(['agents', 'add', 'custom', '--template', 'gemini-claw', '--fork']);
+    const overlay = env.getAgentSettings('custom');
+    expect(overlay.extends).toBeUndefined();
+    const skill = path.join(
+      env.e2eDir,
+      'custom',
+      '.gemini',
+      'skills',
+      'skill-creator',
+      'SKILL.md'
+    );
+    expect(fs.existsSync(skill)).toBe(true);
+    fs.writeFileSync(skill, 'edited skill\n');
+
+    const { stdout, code } = await env.runCli(['up', '--dry-run']);
+    expect(code).toBe(0);
+    expect(stdout).toContain('[custom] diverged .gemini/skills/skill-creator/SKILL.md');
+    expect(fs.readFileSync(skill, 'utf8')).toBe('edited skill\n');
+  });
+
+  it('up --dry-run skips skill changes for a custom agent with skillsDir: null', async () => {
+    await env.runCli(['agents', 'add', 'custom', '--template', 'gemini-claw', '--fork']);
+    const skillsDir = path.join(env.e2eDir, 'custom', '.gemini', 'skills');
+    expect(fs.existsSync(skillsDir)).toBe(true);
+    // User opts out and removes the installed skills.
+    env.updateAgentSettings('custom', { skillsDir: null });
+    fs.rmSync(skillsDir, { recursive: true, force: true });
+
+    const { stdout, code } = await env.runCli(['up', '--dry-run']);
+    expect(code).toBe(0);
+    expect(stdout).not.toContain('[custom]');
+    expect(stdout).not.toContain('skill-creator');
+    expect(stdout).toContain('Dry run: no agents to refresh.');
+    // And the skills directory remains absent — dry-run wrote nothing.
+    expect(fs.existsSync(skillsDir)).toBe(false);
+  });
+});