/** * The gstack-start hook (GST-718): opt-in OpenClaw and Hermes plugins that put gstack's start note on every user * turn. Harness CLIs are fake /bin/sh scripts on PATH that record their argv and environment and keep the * plugin state in the profile, so these cases run no harness and spend nothing. */ import { afterAll, afterEach, describe, expect, test } from 'bun:test'; import { spawnSync } from 'node:child_process'; import * as fs from 'node:fs'; import * as os from 'node:os'; import * as path from 'node:path'; import { TARGETS, readLedger, register, status, unregister, type RegisterOptions } from '../lib/harness-register'; import { HOOK_ID, START_NOTE, START_NOTE_MAX, hookChoice, hookFiles, inspectHook } from '../lib/harness-start-hook'; import { cleanupFixtures, cleanupSeed, makeFixture, makeSource, registryRows, runSetup } from './helpers/install-fixture'; const ROOT = path.resolve(import.meta.dir, '..'); const VERSION = fs.readFileSync(path.join(ROOT, 'VERSION'), 'utf8').trim(); const temps: string[] = []; const tmp = () => { const d = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-hook-test-'))); temps.push(d); return d; }; afterEach(() => { cleanupFixtures(); for (const d of temps.splice(0)) fs.rmSync(d, { recursive: true, force: true }); }); afterAll(cleanupSeed); const FAKE_OPENCLAW = String.raw`#!/bin/sh d="$OPENCLAW_STATE_DIR"; c="$d/fake-config" printf '%s|secret=%s|home=%s|cfg=%s\n' "$*" "$ANTHROPIC_API_KEY" "$HOME" "$OPENCLAW_CONFIG_PATH" >> "$d/fake-calls" [ -f "$d/fake-fail" ] && { echo "config write refused" >&2; exit 3; } [ -f "$d/fake-kill" ] && { rm -f "$d/fake-kill"; kill -9 "$PPID"; sleep 5; } [ -f "$d/fake-noisy" ] && echo "[plugins] gstack-start: cannot verify where this plugin came from" [ -f "$d/fake-hang" ] && [ "$1" = plugins ] && exec sleep 40 touch "$c" acc=false; grep -q '^plugins.entries.gstack-start.hooks.allowConversationAccess=true$' "$c" && acc=true en=$(grep '^plugins.entries.gstack-start.enabled=' "$c" | tail -1 | cut -d= -f2); enj=null; [ -n "$en" ] && enj=$en case "$1 $2" in "config set") echo "$3=$4" >> "$c" ;; "config unset") grep -v "^$3" "$c" > "$c.t"; mv "$c.t" "$c" ;; "config get") api=""; grep -q '^plugins.entries.gstack-start.hooks.allowPromptInjection=false$' "$c" && api=',"allowPromptInjection":false' printf '{"allow":%s,"deny":%s,"entries":{"gstack-start":{"enabled":%s,"hooks":{"allowConversationAccess":%s%s}}}}\n' "$(cat "$d/fake-allow" 2>/dev/null || echo null)" "$(cat "$d/fake-deny" 2>/dev/null || echo null)" "$enj" "$acc" "$api" ;; "plugins inspect") hooks=""; [ -d "$d/extensions/gstack-start" ] && [ "$acc" = true ] && [ "$en" != false ] && hooks='{"name":"before_prompt_build"}' printf '{"plugin":{"status":"loaded","enabled":%s},"typedHooks":[%s]}\n' "$([ "$en" = false ] && echo false || echo true)" "$hooks" ;; esac `; const FAKE_HERMES = String.raw`#!/bin/sh d="$HERMES_HOME" printf '%s|secret=%s|home=%s\n' "$*" "$ANTHROPIC_API_KEY" "$HOME" >> "$d/fake-calls" case "$1 $2" in "plugins enable") echo enabled > "$d/fake-state" ;; "plugins disable") echo disabled > "$d/fake-state" ;; "plugins remove") rm -rf "$d/plugins/$3" "$d/fake-state" ;; "plugins list") if [ -d "$d/plugins/gstack-start" ]; then printf '[{"name":"gstack-start","status":"%s"}]\n' "$(cat "$d/fake-state" 2>/dev/null || echo 'not enabled')"; else echo '[]'; fi ;; esac `; /** A temp home, state root and profile, with fake openclaw and hermes CLIs first on PATH. */ function rig(target: 'openclaw' | 'hermes', extra: { noCli?: boolean; env?: Record } = {}) { const d = tmp(); const bin = path.join(d, 'bin'); fs.mkdirSync(bin); fs.writeFileSync(path.join(bin, 'openclaw'), FAKE_OPENCLAW, { mode: 0o755 }); fs.writeFileSync(path.join(bin, 'hermes'), FAKE_HERMES, { mode: 0o755 }); const profile = path.join(d, target === 'openclaw' ? 'oc' : 'he'); fs.mkdirSync(profile, { recursive: true }); const env = { PATH: (extra.noCli ? '' : bin + path.delimiter) + '/usr/bin:/bin', ANTHROPIC_API_KEY: 'sekret', [target === 'openclaw' ? 'OPENCLAW_STATE_DIR' : 'HERMES_HOME']: profile, ...extra.env }; const o = (more: Partial = {}): RegisterOptions => ({ target: TARGETS[target], checkout: ROOT, stateRoot: path.join(d, 'state'), env, home: path.join(d, 'home'), version: VERSION, ...more }); const root = path.join(profile, target === 'openclaw' ? 'extensions' : 'plugins', HOOK_ID); const calls = () => fs.existsSync(path.join(profile, 'fake-calls')) ? fs.readFileSync(path.join(profile, 'fake-calls'), 'utf8').trim().split('\n') : []; return { d, bin, profile, env, o, root, calls }; } describe('start hook: the note and the plugin files', () => { test('the note fits its budget and names the helper every rendered preamble runs', () => { expect(START_NOTE.length).toBeLessThanOrEqual(START_NOTE_MAX); expect(START_NOTE).toContain('gstack-skill-start'); const review = fs.readFileSync(path.join(ROOT, 'review', 'SKILL.md'), 'utf8'); expect(review).toContain('## Preamble'); expect(review).toMatch(/bin\/gstack-skill-start --skill "review"/); }); test('plugin code is fixed text: no install path in it, and it reads note.txt from its own folder', () => { for (const t of ['openclaw', 'hermes'] as const) { const a = hookFiles(t, '/one/place/' + HOOK_ID); const b = hookFiles(t, '/an\'other "place"/' + HOOK_ID); expect([...a.values()].map(String)).toEqual([...b.values()].map(String)); for (const [p, bytes] of a) if (!p.endsWith('note.txt')) expect(String(bytes)).not.toContain('/one/place'); expect(String(a.get('/one/place/' + HOOK_ID + '/note.txt'))).toBe(START_NOTE + '\n'); } }); test('the OpenClaw plugin returns the note as prependContext, and nothing when note.txt is gone', async () => { const d = tmp(); for (const [p, b] of hookFiles('openclaw', d)) fs.writeFileSync(p, b); const load = async () => { let handler: (() => unknown) | undefined; const mod = await import(path.join(d, 'index.js') + '?' + Math.random()); mod.default.register({ on: (name: string, fn: () => unknown) => { expect(name).toBe('before_prompt_build'); handler = fn; } }); return handler!(); }; expect(await load()).toEqual({ prependContext: START_NOTE }); fs.rmSync(path.join(d, 'note.txt')); expect(await load()).toBeUndefined(); }); test('the Hermes plugin registers pre_llm_call and returns the note as context, and nothing when note.txt is gone', () => { const d = tmp(); const pkg = path.join(d, 'gstack_start'); fs.mkdirSync(pkg); for (const [p, b] of hookFiles('hermes', pkg)) fs.writeFileSync(p, b); const probe = 'import sys, json\nsys.path.insert(0, sys.argv[1])\nimport gstack_start as m\nseen = []\nclass Ctx:\n def register_hook(self, name, fn): seen.append((name, fn))\nm.register(Ctx())\nprint(json.dumps([seen[0][0], seen[0][1](session_id="s", user_message="hi")]))\n'; const run = () => spawnSync('python3', ['-B', '-c', probe, d], { encoding: 'utf8', timeout: 30_000 }); let r = run(); expect(r.status, r.stderr).toBe(0); expect(JSON.parse(r.stdout)).toEqual(['pre_llm_call', { context: START_NOTE }]); fs.rmSync(path.join(pkg, 'note.txt')); r = run(); expect(JSON.parse(r.stdout)).toEqual(['pre_llm_call', null]); }); }); describe('start hook: who decides', () => { test('flag, then GSTACK_HARNESS_START_HOOK, then gstack-config harness_start_hook, then the ledger', () => { const d = tmp(); const state = path.join(d, 'state'); fs.mkdirSync(state); expect(hookChoice(undefined, {}, state, undefined)).toEqual({ on: false, source: 'ledger' }); expect(hookChoice(undefined, {}, state, 'on')).toEqual({ on: true, source: 'ledger' }); fs.writeFileSync(path.join(state, 'config.yaml'), 'harness_start_hook: off\n'); expect(hookChoice(undefined, {}, state, 'on')).toEqual({ on: false, source: 'config' }); expect(hookChoice(undefined, { GSTACK_HARNESS_START_HOOK: '1' }, state, undefined)).toEqual({ on: true, source: 'env' }); expect(hookChoice(false, { GSTACK_HARNESS_START_HOOK: 'on' }, state, 'on')).toEqual({ on: false, source: 'flag' }); expect(hookChoice(undefined, { GSTACK_HARNESS_START_HOOK: 'maybe' }, state, undefined)).toEqual({ invalid: 'GSTACK_HARNESS_START_HOOK="maybe"' }); fs.writeFileSync(path.join(state, 'config.yaml'), 'harness_start_hook: sometimes\n'); expect(hookChoice(undefined, {}, state, undefined)).toEqual({ invalid: 'gstack-config harness_start_hook="sometimes"' }); }); test('gstack-config takes harness_start_hook on or off and refuses anything else', () => { const d = tmp(); const cfg = (...args: string[]) => spawnSync(path.join(ROOT, 'bin', 'gstack-config'), args, { env: { PATH: process.env.PATH, HOME: path.join(d, 'home'), GSTACK_STATE_ROOT: path.join(d, 'state') }, encoding: 'utf8', timeout: 30_000 }); expect(cfg('set', 'harness_start_hook', 'on').status).toBe(0); expect(cfg('get', 'harness_start_hook').stdout.trim()).toBe('on'); const bad = cfg('set', 'harness_start_hook', 'yes'); expect(bad.status).toBe(1); expect(bad.stderr).toContain("harness_start_hook 'yes' not recognized"); expect(cfg('get', 'harness_start_hook').stdout.trim()).toBe('on'); }); test('an invalid choice and a hook for a target or folder without one stop before anything is written', () => { const r = rig('openclaw', { env: { GSTACK_HARNESS_START_HOOK: 'maybe' } }); expect(() => register(r.o())).toThrow(expect.objectContaining({ code: 'HARNESS_HOOK_CHOICE_INVALID' })); const s = rig('openclaw'); expect(() => register(s.o({ skillsDir: path.join(s.d, 'custom', 'skills'), startHook: true }))).toThrow(expect.objectContaining({ code: 'HARNESS_HOOK_UNSUPPORTED' })); expect(() => register({ ...s.o({ startHook: true }), target: TARGETS.dots, skillsDir: path.join(s.d, 'dots') })).toThrow(expect.objectContaining({ code: 'HARNESS_HOOK_UNSUPPORTED' })); expect(() => register({ ...s.o({ startHook: true }), env: { ...s.env, OPENCLAW_CONFIG_PATH: '/elsewhere/openclaw.json' } })).toThrow(expect.objectContaining({ code: 'HARNESS_HOOK_UNSUPPORTED' })); for (const x of [r, s]) { expect(fs.existsSync(path.join(x.profile, 'skills'))).toBe(false); expect(x.calls()).toEqual([]); } expect(fs.existsSync(path.join(s.d, 'custom'))).toBe(false); }); test('a plugin folder gstack did not write, or a symlink on the way to it, stops an explicit --start-hook with nothing written, and turns an env or config opt-in into hook off', () => { const r = rig('openclaw'); fs.mkdirSync(r.root, { recursive: true }); fs.writeFileSync(path.join(r.root, 'index.js'), 'mine'); expect(() => register(r.o({ startHook: true }))).toThrow(expect.objectContaining({ code: 'HARNESS_HOOK_OWNED_ELSEWHERE' })); expect(fs.readFileSync(path.join(r.root, 'index.js'), 'utf8')).toBe('mine'); const s = rig('hermes'); fs.mkdirSync(path.join(s.d, 'elsewhere')); fs.symlinkSync(path.join(s.d, 'elsewhere'), path.join(s.profile, 'plugins')); expect(() => register(s.o({ startHook: true }))).toThrow(expect.objectContaining({ code: 'HARNESS_UNSAFE_DESTINATION' })); expect(fs.readdirSync(path.join(s.d, 'elsewhere'))).toEqual([]); const viaEnv = register({ ...s.o(), env: { ...s.env, GSTACK_HARNESS_START_HOOK: '1' } }); expect(viaEnv.hook?.state).toBe('off'); expect(viaEnv.hook?.detail).toContain('is a symlink (env asked for the hook'); expect(fs.existsSync(path.join(s.profile, 'skills', 'gstack'))).toBe(true); expect(fs.readdirSync(path.join(s.d, 'elsewhere'))).toEqual([]); expect(r.calls().concat(s.calls())).toEqual([]); }); test('a file, an empty folder or a folder with any non-kept file at the plugin path is still owned elsewhere', () => { for (const make of [(root: string) => fs.writeFileSync(root, 'x'), (root: string) => fs.mkdirSync(path.join(root, 'sub'), { recursive: true }), (root: string) => { fs.mkdirSync(root, { recursive: true }); fs.writeFileSync(path.join(root, 'note.txt.edited-2026-11-01T06-31-18-911Z'), 'kept'); fs.writeFileSync(path.join(root, 'plugin.yaml'), 'mine'); }]) { const r = rig('hermes'); fs.mkdirSync(path.dirname(r.root), { recursive: true }); make(r.root); expect(() => register(r.o({ startHook: true }))).toThrow(expect.objectContaining({ code: 'HARNESS_HOOK_OWNED_ELSEWHERE' })); expect(register({ ...r.o(), env: { ...r.env, GSTACK_HARNESS_START_HOOK: '1' } }).hook?.state).toBe('off'); } }, 300_000); test('a profile path with a trailing slash under a symlinked parent still takes the hook and is saved without the slash', () => { const r = rig('hermes'); const link = path.join(tmp(), 'ln'); fs.symlinkSync(r.d, link); const res = register({ ...r.o({ startHook: true }), env: { ...r.env, HERMES_HOME: path.join(link, 'he') + '/' } }); expect(res.hook?.state).toBe('active'); expect(readLedger(res.ledger)!.meta.hook_profile).toBe(path.join(link, 'he')); expect(fs.existsSync(path.join(r.root, 'plugin.yaml'))).toBe(true); }, 120_000); }); describe('start hook: OpenClaw lifecycle (fake CLI)', () => { test('default registration adds no plugin and runs no harness command', () => { const r = rig('openclaw'); const res = register(r.o()); expect(res.hook).toEqual({ state: 'off' }); expect(fs.existsSync(path.join(r.profile, 'extensions'))).toBe(false); expect(r.calls()).toEqual([]); expect(readLedger(res.ledger)!.files.every(f => f.path.startsWith(path.join(r.profile, 'skills') + path.sep))).toBe(true); }, 120_000); test('on, refreshed, disabled by the user, then off: activation runs once, a user disable sticks, opt-out cleans up', () => { const r = rig('openclaw'); const on = register(r.o({ startHook: true })); expect(on.hook).toMatchObject({ state: 'active', required: true, profile: r.profile, root: r.root }); expect(fs.readdirSync(r.root).sort()).toEqual(['index.js', 'note.txt', 'openclaw.plugin.json', 'package.json']); const meta = readLedger(on.ledger)!.meta; expect([meta.start_hook, meta.hook_profile, meta.hook_root]).toEqual(['on', r.profile, r.root]); const argv = r.calls().map(l => l.split('|')[0]); expect(argv).toEqual([ 'config set plugins.entries.gstack-start.hooks.allowConversationAccess true', 'config set plugins.entries.gstack-start.enabled true', 'config get plugins --json', 'plugins inspect gstack-start --runtime --json', ]); for (const l of r.calls()) expect(l).toContain('|secret=|home=' + path.join(r.d, 'home') + '|cfg='); const again = register(r.o()); expect(again.status).toBe('unchanged'); expect(again.hook?.state).toBe('unchecked'); expect(r.calls()).toHaveLength(4); fs.appendFileSync(path.join(r.profile, 'fake-config'), 'plugins.entries.gstack-start.enabled=false\n'); register(r.o()); expect(r.calls().filter(l => l.startsWith('config set'))).toHaveLength(2); expect(status(r.o().stateRoot, VERSION, r.env).find(s => s.target === 'openclaw')?.hook?.state).toBe('disabled'); const off = register(r.o({ startHook: false })); expect(off.hook?.state).toBe('off'); expect(r.calls().some(l => l.startsWith('config unset plugins.entries.gstack-start|'))).toBe(true); expect(fs.existsSync(path.join(r.profile, 'extensions'))).toBe(false); const after = readLedger(off.ledger)!.meta; expect(after.start_hook).toBe('off'); expect(after.hook_root).toBeUndefined(); }, 300_000); test('a failed or blocked activation reports written with the fix; the CLI exits 4 after registering the skills', () => { const r = rig('openclaw'); fs.writeFileSync(path.join(r.profile, 'fake-allow'), '["anthropic"]'); const res = register(r.o({ startHook: true })); expect(res.hook).toMatchObject({ state: 'written', required: true, detail: 'plugins.allow is set and does not list gstack-start' }); expect(res.hook?.fix).toContain('openclaw config set plugins.allow \'["anthropic","gstack-start"]\''); const s = rig('openclaw'); fs.writeFileSync(path.join(s.profile, 'fake-fail'), ''); const cli = spawnSync(process.execPath, ['--no-env-file', '--config=/dev/null', path.join(ROOT, 'bin', 'gstack-harness'), 'register', 'openclaw', '--start-hook'], { env: { ...s.env, PATH: s.env.PATH + path.delimiter + path.dirname(process.execPath), HOME: path.join(s.d, 'home'), GSTACK_STATE_ROOT: path.join(s.d, 'state') }, encoding: 'utf8', timeout: 240_000 }); expect(cli.status, cli.stderr).toBe(4); expect(cli.stdout).toContain('start hook: written'); expect(cli.stderr).toContain('config write refused'); expect(cli.stderr).toContain('(HARNESS_HOOK_INACTIVE; docs/troubleshooting.md#harness-hook-inactive)'); expect(fs.existsSync(path.join(s.profile, 'skills', 'gstack', 'SKILL.md'))).toBe(true); }, 300_000); test('a run killed during activation leaves the hook marked not active, so the next plain register activates it', () => { const r = rig('openclaw'); fs.writeFileSync(path.join(r.profile, 'fake-kill'), ''); const cli = spawnSync(process.execPath, ['--no-env-file', '--config=/dev/null', path.join(ROOT, 'bin', 'gstack-harness'), 'register', 'openclaw'], { env: { ...r.env, GSTACK_HARNESS_START_HOOK: '1', PATH: r.env.PATH + path.delimiter + path.dirname(process.execPath), HOME: path.join(r.d, 'home'), GSTACK_STATE_ROOT: path.join(r.d, 'state') }, encoding: 'utf8', timeout: 240_000 }); expect(cli.signal, cli.stderr).toBe('SIGKILL'); const dir = path.join(r.d, 'state', 'harness'); const lfile = fs.readdirSync(dir).find(f => f.endsWith('.ledger')); expect(readLedger(path.join(dir, lfile!))!.meta).toMatchObject({ start_hook: 'on', hook_active: 'no' }); const next = register(r.o()); expect(next.hook).toMatchObject({ state: 'active', retried: true }); expect(readLedger(next.ledger)!.meta.hook_active).toBe('yes'); }, 300_000); test('off with an edited plugin file keeps the edit, and the same registration can turn the hook back on', () => { const r = rig('openclaw'); expect(register(r.o({ startHook: true })).hook?.state).toBe('active'); fs.writeFileSync(path.join(r.root, 'note.txt'), 'my note\n'); const off = register(r.o({ startHook: false })); expect(off.kept).toHaveLength(1); expect(off.kept[0]).toMatch(/note\.txt\.edited-/); const on = register(r.o({ startHook: true })); expect(on.hook?.state).toBe('active'); expect(fs.readFileSync(path.join(r.root, 'note.txt'), 'utf8')).toBe(START_NOTE + '\n'); expect(fs.readFileSync(off.kept[0], 'utf8')).toBe('my note\n'); }, 300_000); test('an explicit --start-hook on an unchanged registration killed during activation is retried by the next run', () => { const r = rig('openclaw'); expect(register(r.o({ startHook: true })).hook?.state).toBe('active'); fs.writeFileSync(path.join(r.profile, 'fake-kill'), ''); const cli = spawnSync(process.execPath, ['--no-env-file', '--config=/dev/null', path.join(ROOT, 'bin', 'gstack-harness'), 'register', 'openclaw', '--start-hook'], { env: { ...r.env, PATH: r.env.PATH + path.delimiter + path.dirname(process.execPath), HOME: path.join(r.d, 'home'), GSTACK_STATE_ROOT: path.join(r.d, 'state') }, encoding: 'utf8', timeout: 240_000 }); expect(cli.signal, cli.stderr).toBe('SIGKILL'); const dir = path.join(r.d, 'state', 'harness'); expect(readLedger(path.join(dir, fs.readdirSync(dir).find(f => f.endsWith('.ledger'))!))!.meta.hook_active).toBe('no'); expect(register(r.o()).hook).toMatchObject({ state: 'active', retried: true }); }, 300_000); test('a log line in brackets before the harness JSON still reads back as active', () => { const r = rig('openclaw'); fs.writeFileSync(path.join(r.profile, 'fake-noisy'), ''); expect(register(r.o({ startHook: true })).hook?.state).toBe('active'); expect(inspectHook('openclaw', r.profile, r.env, path.join(r.d, 'home')).state).toBe('active'); }, 120_000); test('a hung harness read-back gives up after a short timeout', () => { const r = rig('openclaw'); expect(register(r.o({ startHook: true })).hook?.state).toBe('active'); fs.writeFileSync(path.join(r.profile, 'fake-hang'), ''); const t0 = Date.now(); expect(inspectHook('openclaw', r.profile, r.env, path.join(r.d, 'home')).state).toBe('written'); expect(Date.now() - t0).toBeLessThan(35_000); }, 120_000); test('without the harness on PATH the hook is written, not active, and names the commands to run', () => { const r = rig('openclaw', { noCli: true }); const res = register(r.o({ startHook: true })); expect(res.hook).toMatchObject({ state: 'written', detail: 'openclaw is not on PATH, so gstack could not turn the plugin on or check it' }); expect(res.hook?.fix).toBe('OPENCLAW_STATE_DIR=' + JSON.stringify(r.profile) + ' openclaw config set plugins.entries.gstack-start.hooks.allowConversationAccess true && OPENCLAW_STATE_DIR=' + JSON.stringify(r.profile) + ' openclaw config set plugins.entries.gstack-start.enabled true'); }, 120_000); }); describe('start hook: read back and retry (fake CLI)', () => { test('OpenClaw deny lists and allowPromptInjection false read back as written; a Hermes disable reads back as disabled', () => { const r = rig('openclaw'); fs.mkdirSync(r.root, { recursive: true }); const cfg = (line: string) => fs.appendFileSync(path.join(r.profile, 'fake-config'), line + '\n'); cfg('plugins.entries.gstack-start.hooks.allowConversationAccess=true'); expect(inspectHook('openclaw', r.profile, r.env, r.d).state).toBe('active'); fs.writeFileSync(path.join(r.profile, 'fake-deny'), '["gstack-start"]'); expect(inspectHook('openclaw', r.profile, r.env, r.d)).toMatchObject({ state: 'written', detail: 'plugins.deny lists gstack-start' }); fs.rmSync(path.join(r.profile, 'fake-deny')); cfg('plugins.entries.gstack-start.hooks.allowPromptInjection=false'); expect(inspectHook('openclaw', r.profile, r.env, r.d)).toMatchObject({ state: 'written', detail: 'plugins.entries.gstack-start.hooks.allowPromptInjection is false' }); const h = rig('hermes'); fs.mkdirSync(h.root, { recursive: true }); fs.writeFileSync(path.join(h.profile, 'fake-state'), 'disabled'); expect(inspectHook('hermes', h.profile, h.env, h.d)).toMatchObject({ state: 'disabled' }); }); test('after a failed opt-in, refresh retries without failing, and stops for good once the user disables the plugin', () => { const r = rig('openclaw'); fs.writeFileSync(path.join(r.profile, 'fake-allow'), '["anthropic"]'); expect(register(r.o({ startHook: true })).hook).toMatchObject({ state: 'written', required: true }); expect(readLedger(register(r.o()).ledger)!.meta.hook_active).toBe('no'); const retry = register(r.o()); expect(retry.hook).toMatchObject({ state: 'written', required: false, retried: true }); fs.rmSync(path.join(r.profile, 'fake-allow')); const fixed = register(r.o()); expect(fixed.hook).toMatchObject({ state: 'active', retried: true }); expect(readLedger(fixed.ledger)!.meta.hook_active).toBe('yes'); const sets = r.calls().filter(l => l.startsWith('config set')).length; expect(register(r.o()).hook?.state).toBe('unchecked'); expect(r.calls().filter(l => l.startsWith('config set')).length).toBe(sets); const s = rig('openclaw'); fs.writeFileSync(path.join(s.profile, 'fake-fail'), ''); expect(register(s.o({ startHook: true })).hook?.state).toBe('written'); fs.rmSync(path.join(s.profile, 'fake-fail')); fs.appendFileSync(path.join(s.profile, 'fake-config'), 'plugins.entries.gstack-start.enabled=false\n'); const before = s.calls().filter(l => l.startsWith('config set')).length; const left = register(s.o()); expect(left.hook).toMatchObject({ state: 'disabled', retried: true }); expect(readLedger(left.ledger)!.meta.hook_active).toBe('disabled'); register(s.o()); expect(s.calls().filter(l => l.startsWith('config set')).length).toBe(before); expect(fs.readFileSync(path.join(s.profile, 'fake-config'), 'utf8')).toContain('enabled=false'); }, 300_000); }); describe('start hook: Hermes lifecycle and the saved choice (fake CLI)', () => { test('a one-run env opt-in is saved; config off then refresh turns it off; unregister removes the plugin through Hermes', () => { const r = rig('hermes', { env: { GSTACK_HARNESS_START_HOOK: '1' } }); const on = register(r.o()); expect(on.hook?.state).toBe('active'); expect(r.calls().map(l => l.split('|')[0])).toEqual(['plugins enable gstack-start', 'plugins list --json']); const env = { ...r.env }; delete (env as Record).GSTACK_HARNESS_START_HOOK; const kept = register({ ...r.o(), env }); expect(kept.hook?.state).toBe('unchecked'); expect(fs.existsSync(path.join(r.root, '__init__.py'))).toBe(true); fs.writeFileSync(path.join(r.o().stateRoot, 'config.yaml'), 'harness_start_hook: off\n'); const off = register({ ...r.o(), env }); expect(off.hook?.state).toBe('off'); expect(r.calls().at(-1)!.split('|')[0]).toBe('plugins remove gstack-start'); expect(fs.existsSync(path.join(r.profile, 'plugins'))).toBe(false); fs.writeFileSync(path.join(r.o().stateRoot, 'config.yaml'), 'harness_start_hook: on\n'); const back = register({ ...r.o(), env }); expect(back.hook?.state).toBe('active'); fs.mkdirSync(path.join(r.root, '__pycache__')); fs.writeFileSync(path.join(r.root, '__pycache__', '__init__.cpython-312.pyc'), 'x'); unregister(r.o().stateRoot, ROOT, 'hermes', env); expect(r.calls().at(-1)!.split('|')[0]).toBe('plugins remove gstack-start'); expect(fs.existsSync(path.join(r.profile, 'plugins'))).toBe(false); }, 300_000); test('bash-only uninstall: an edited plugin file is kept and Hermes only disables it; without Hermes on PATH it prints the command', () => { const r = rig('hermes'); register(r.o({ startHook: true })); fs.appendFileSync(path.join(r.root, 'note.txt'), 'my edit\n'); const ledgerSh = path.join(ROOT, 'bin', 'gstack-harness-ledger.sh'); const run = (PATH: string) => spawnSync('bash', ['-c', '. "$0" && gstack_harness_unregister_all', ledgerSh], { env: { PATH, HOME: path.join(r.d, 'home'), GSTACK_STATE_ROOT: path.join(r.d, 'state') }, encoding: 'utf8', timeout: 60_000 }); const res = run(r.bin + path.delimiter + '/usr/bin:/bin'); expect(res.status, res.stderr).toBe(0); expect(r.calls().at(-1)!.split('|')[0]).toBe('plugins disable gstack-start'); expect(fs.readdirSync(r.root).filter(f => f.startsWith('note.txt.edited-'))).toHaveLength(1); expect(fs.existsSync(path.join(r.root, 'plugin.yaml'))).toBe(false); const s = rig('hermes'); register(s.o({ startHook: true })); const t = spawnSync('bash', ['-c', '. "$0" && gstack_harness_unregister_all', ledgerSh], { env: { PATH: '/usr/bin:/bin', HOME: path.join(s.d, 'home'), GSTACK_STATE_ROOT: path.join(s.d, 'state') }, encoding: 'utf8', timeout: 60_000 }); expect(t.status).toBe(0); expect(t.stdout).toContain('start hook: turn it off in Hermes yourself: HERMES_HOME="' + s.profile + '" hermes plugins disable gstack-start'); expect(fs.existsSync(path.join(s.profile, 'plugins'))).toBe(false); }, 300_000); }); describe('start hook: teardown keeps what gstack did not write (fake CLI)', () => { test('a kept copy of an edited Hermes plugin file survives unregister: Hermes only disables the plugin', () => { const r = rig('hermes'); expect(register(r.o({ startHook: true })).hook?.state).toBe('active'); fs.writeFileSync(path.join(r.root, 'note.txt'), 'my note\n'); const again = register(r.o()); expect(again.kept).toHaveLength(1); unregister(r.o().stateRoot, ROOT, 'hermes', r.env); expect(r.calls().at(-1)!.split('|')[0]).toBe('plugins disable gstack-start'); expect(fs.readFileSync(again.kept[0], 'utf8')).toBe('my note\n'); }, 300_000); test('a plugins folder swapped for a symlink after registration: off refuses, unregister deletes nothing through it', () => { const r = rig('hermes'); expect(register(r.o({ startHook: true })).hook?.state).toBe('active'); const elsewhere = path.join(r.d, 'elsewhere'); fs.renameSync(path.join(r.profile, 'plugins'), elsewhere); fs.symlinkSync(elsewhere, path.join(r.profile, 'plugins')); fs.writeFileSync(path.join(elsewhere, HOOK_ID, 'important.txt'), 'keep'); expect(() => register(r.o({ startHook: false }))).toThrow(expect.objectContaining({ code: 'HARNESS_UNSAFE_DESTINATION' })); unregister(r.o().stateRoot, ROOT, 'hermes', r.env); expect(r.calls().some(l => l.startsWith('plugins remove'))).toBe(false); expect(fs.readdirSync(path.join(elsewhere, HOOK_ID)).sort()).toEqual(['__init__.py', 'important.txt', 'note.txt', 'plugin.yaml']); }, 300_000); test.skipIf(process.platform === 'win32' || process.getuid?.() === 0)('an opt-out that fails to delete the plugin files can be run again', () => { const r = rig('openclaw'); const on = register(r.o({ startHook: true })); expect(on.hook?.state).toBe('active'); fs.chmodSync(r.root, 0o555); try { expect(() => register(r.o({ startHook: false }))).toThrow(/EACCES/); expect(readLedger(on.ledger)!.meta.hook_root).toBe(r.root); } finally { fs.chmodSync(r.root, 0o755); } const ext = path.join(r.profile, 'extensions'), moved = path.join(r.d, 'moved'); fs.renameSync(ext, moved); fs.symlinkSync(moved, ext); expect(() => register(r.o({ startHook: false }))).toThrow(expect.objectContaining({ code: 'HARNESS_UNSAFE_DESTINATION' })); expect(() => register({ ...r.o(), env: { ...r.env, GSTACK_HARNESS_START_HOOK: '1' } })).toThrow(expect.objectContaining({ code: 'HARNESS_UNSAFE_DESTINATION' })); expect(fs.existsSync(path.join(moved, HOOK_ID, 'index.js'))).toBe(true); fs.unlinkSync(ext); fs.renameSync(moved, ext); const off = register(r.o({ startHook: false })); expect(off.hook?.state).toBe('off'); expect(fs.existsSync(path.join(r.profile, 'extensions'))).toBe(false); expect(readLedger(off.ledger)!.meta.hook_root).toBeUndefined(); }, 300_000); test('unregister leaves an empty plugin folder alone when the folder above it was swapped for a symlink', () => { const r = rig('openclaw'); expect(register(r.o({ startHook: true })).hook?.state).toBe('active'); const ext = path.join(r.profile, 'extensions'), elsewhere = path.join(r.d, 'elsewhere'); fs.renameSync(ext, path.join(r.d, 'old')); fs.mkdirSync(path.join(elsewhere, HOOK_ID), { recursive: true }); fs.symlinkSync(elsewhere, ext); unregister(r.o().stateRoot, ROOT, 'openclaw', r.env); expect(fs.existsSync(path.join(elsewhere, HOOK_ID))).toBe(true); }, 300_000); test('a saved opt-in survives one run from a shell that sets OPENCLAW_CONFIG_PATH', () => { const r = rig('openclaw'); expect(register(r.o({ startHook: true })).hook?.state).toBe('active'); const res = register({ ...r.o(), env: { ...r.env, OPENCLAW_CONFIG_PATH: '/elsewhere/openclaw.json' } }); expect(res.hook?.state).not.toBe('off'); expect(r.calls().some(l => l.startsWith('config unset'))).toBe(false); expect(fs.existsSync(path.join(r.root, 'index.js'))).toBe(true); expect(readLedger(res.ledger)!.meta.start_hook).toBe('on'); }, 300_000); }); describe.skipIf(process.platform === 'win32')('start hook through ./setup --host', () => { test('exits 4 with the skills registered when the hook does not turn on, and the next run retries it', () => { const f = makeFixture(); const src = makeSource(f, path.join(f.dir, 'gstack')); const bin = path.join(f.dir, 'fakebin'); fs.mkdirSync(bin); fs.writeFileSync(path.join(bin, 'openclaw'), FAKE_OPENCLAW, { mode: 0o755 }); const profile = path.join(f.home, '.openclaw'); fs.mkdirSync(profile, { recursive: true }); fs.writeFileSync(path.join(profile, 'fake-fail'), ''); const PATH = bin + path.delimiter + f.env.PATH; const first = runSetup(f, path.join(src, 'setup'), ['--host', 'openclaw'], { env: { PATH, GSTACK_HARNESS_START_HOOK: '1' } }); expect(first.status, first.stdout + first.stderr).toBe(4); expect(first.stdout).toContain('start hook: written'); expect(first.stderr).toContain('(HARNESS_HOOK_INACTIVE; docs/troubleshooting.md#harness-hook-inactive)'); expect(fs.existsSync(path.join(profile, 'skills', 'gstack', 'SKILL.md'))).toBe(true); expect(registryRows(f).map(row => row[0])).toEqual(['openclaw']); const refreshed = runSetup(f, path.join(src, 'setup'), ['--refresh-registered'], { env: { PATH } }); expect(refreshed.status, refreshed.stdout + refreshed.stderr).toBe(0); expect(refreshed.stdout + refreshed.stderr).toContain('start hook: written'); fs.rmSync(path.join(profile, 'fake-fail')); const second = runSetup(f, path.join(src, 'setup'), ['--host', 'openclaw'], { env: { PATH } }); expect(second.status, second.stdout + second.stderr).toBe(0); expect(second.stdout).toContain('start hook: active'); }, 180_000); });