@phnx-labs/agents-cli 1.22.14 → 1.22.16

package/dist/lib/hooks.js

@@ -32,12 +32,77 @@ function resolveContainedHookPath(hooksRoot, script) {
         return null;
     return resolved;
 }
+/**
+ * Subdirectories under hooks/ that group event families (e.g. session-starts/).
+ * Scripts one level down are first-class hooks; their install name remains the
+ * file basename so version-home copies stay flat and doctor/diff keep matching.
+ */
+const HOOK_GROUP_SKIP_DIRS = new Set(['node_modules', '.git', '.cache']);
 export function resolveHookScriptPath(script) {
     const extraDirs = getEnabledExtraRepos().map(e => e.dir);
     for (const root of [getUserAgentsDir(), ...extraDirs, getSystemAgentsDir()]) {
-        const resolved = resolveContainedHookPath(path.join(root, 'hooks'), script);
+        const hooksRoot = path.join(root, 'hooks');
+        const resolved = resolveContainedHookPath(hooksRoot, script);
         if (resolved)
             return resolved;
+        // Basename fallback: manifests may say `session-starts/foo.sh` or just
+        // `foo.sh` while the file lives under a one-level group dir.
+        const base = path.basename(script);
+        const nested = findHookScriptInGroupDirs(hooksRoot, base);
+        if (nested)
+            return nested;
+    }
+    return null;
+}
+/**
+ * Find `basename` under hooks/<group>/ (one level). Skips known non-group dirs.
+ * Returns the first match in sorted group order for stability.
+ */
+function findHookScriptInGroupDirs(hooksRoot, basename) {
+    if (!fs.existsSync(hooksRoot))
+        return null;
+    let entries;
+    try {
+        entries = fs.readdirSync(hooksRoot).sort();
+    }
+    catch {
+        return null;
+    }
+    for (const name of entries) {
+        if (name.startsWith('.') || HOOK_GROUP_SKIP_DIRS.has(name))
+            continue;
+        const groupDir = path.join(hooksRoot, name);
+        let st;
+        try {
+            st = fs.lstatSync(groupDir);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isDirectory() || st.isSymbolicLink())
+            continue;
+        // Only treat dirs that themselves contain scripts as groups (session-starts/),
+        // not fixture-only directory bundles (tests/).
+        let hasScript = false;
+        try {
+            for (const child of fs.readdirSync(groupDir)) {
+                if (SCRIPT_EXTENSIONS.has(path.extname(child).toLowerCase())) {
+                    const cp = path.join(groupDir, child);
+                    if (fs.existsSync(cp) && fs.statSync(cp).isFile()) {
+                        hasScript = true;
+                        break;
+                    }
+                }
+            }
+        }
+        catch {
+            continue;
+        }
+        if (!hasScript)
+            continue;
+        const candidate = path.join(groupDir, basename);
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile())
+            return candidate;
     }
     return null;
 }
@@ -383,38 +448,120 @@ function removeHookFiles(dir, name) {
     }
 }
 /**
- * List hook entries in a single directory, grouping script + data files by
- * basename. Exported so doctor-diff can reuse the same grouping the sync path
- * applies; without this, doctor would double-count `foo.sh` and `foo.yaml`.
+ * Collect hook-adjacent files from a hooks root: top-level files plus files in
+ * one-level group subdirs (e.g. hooks/session-starts/*.sh). Group dirs exist
+ * only for layout; the install/list name stays the file basename so sync and
+ * doctor keep a flat version-home model.
  */
-export function listHookEntriesFromDir(dir) {
-    if (!fs.existsSync(dir)) {
-        return [];
-    }
+function collectHookFilesFromRoot(dir) {
     const files = [];
-    for (const file of fs.readdirSync(dir)) {
-        const fullPath = path.join(dir, file);
-        const stat = fs.statSync(fullPath);
-        if (!stat.isFile())
-            continue;
-        const ext = path.extname(file);
-        const base = path.basename(file, ext);
+    const pushFile = (fullPath, fileName, mode) => {
+        const ext = path.extname(fileName);
+        const base = path.basename(fileName, ext);
         files.push({
-            name: file,
+            name: fileName,
             base,
             ext,
             fullPath,
-            isExec: isExecutable(stat.mode),
+            isExec: isExecutable(mode),
         });
+    };
+    let top;
+    try {
+        top = fs.readdirSync(dir);
+    }
+    catch {
+        return files;
+    }
+    for (const file of top) {
+        if (file.startsWith('.'))
+            continue;
+        const fullPath = path.join(dir, file);
+        let stat;
+        try {
+            stat = fs.lstatSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isSymbolicLink())
+            continue;
+        if (stat.isFile()) {
+            pushFile(fullPath, file, stat.mode);
+            continue;
+        }
+        if (!stat.isDirectory() || HOOK_GROUP_SKIP_DIRS.has(file))
+            continue;
+        // One-level event-group layout: hooks/<group>/<script>. Only dirs that
+        // contain top-level scripts are groups; fixture-only dirs (tests/) are not.
+        let nested;
+        try {
+            nested = fs.readdirSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        const nestedFiles = [];
+        let hasScript = false;
+        for (const nestedName of nested) {
+            if (nestedName.startsWith('.'))
+                continue;
+            const nestedPath = path.join(fullPath, nestedName);
+            let nstat;
+            try {
+                nstat = fs.lstatSync(nestedPath);
+            }
+            catch {
+                continue;
+            }
+            if (nstat.isSymbolicLink() || !nstat.isFile())
+                continue;
+            nestedFiles.push({ nestedName, nestedPath, mode: nstat.mode });
+            if (SCRIPT_EXTENSIONS.has(path.extname(nestedName).toLowerCase()))
+                hasScript = true;
+        }
+        if (!hasScript)
+            continue;
+        for (const n of nestedFiles)
+            pushFile(n.nestedPath, n.nestedName, n.mode);
     }
-    const grouped = new Map();
+    return files;
+}
+/**
+ * List hook entries in a single directory, grouping script + data files by
+ * basename. Also discovers scripts in one-level group subdirs
+ * (hooks/session-starts/). Exported so doctor-diff can reuse the same grouping
+ * the sync path applies; without this, doctor would double-count `foo.sh` and
+ * `foo.yaml`. On basename collision, the top-level file wins over a nested one.
+ */
+export function listHookEntriesFromDir(dir) {
+    if (!fs.existsSync(dir)) {
+        return [];
+    }
+    const files = collectHookFilesFromRoot(dir);
+    // Prefer top-level over nested when basenames collide (stable install name).
+    const byBase = new Map();
     for (const file of files) {
-        const list = grouped.get(file.base) || [];
-        list.push(file);
-        grouped.set(file.base, list);
+        const list = byBase.get(file.base) || [];
+        // Top-level files sit directly under dir; nested have an extra path segment.
+        const isTop = path.dirname(file.fullPath) === path.resolve(dir);
+        if (isTop)
+            list.unshift(file);
+        else
+            list.push(file);
+        byBase.set(file.base, list);
     }
     const entries = [];
-    for (const [base, group] of grouped) {
+    for (const [base, groupAll] of byBase) {
+        // Keep only files that share the winning script's directory so a nested
+        // data sidecar next to a nested script still pairs, and a top-level
+        // winner is not paired with a nested yaml of the same basename.
+        const winnerScript = groupAll.find((f) => SCRIPT_EXTENSIONS.has(f.ext.toLowerCase())) ||
+            groupAll.find((f) => f.isExec && !NON_SCRIPT_EXTENSIONS.has(f.ext.toLowerCase()));
+        if (!winnerScript)
+            continue;
+        const groupDir = path.dirname(winnerScript.fullPath);
+        const group = groupAll.filter((f) => path.dirname(f.fullPath) === groupDir);
         group.sort((a, b) => a.name.localeCompare(b.name));
         // A group is a hook only if it has an actual script: a script extension,
         // OR an executable bit on a file whose extension is not a known data /
@@ -1268,7 +1415,10 @@ export function registerHooksToSettings(agentId, versionHome, hookManifest, agen
             return resolveContainedHookPath(path.join(overrideRoots[0], 'hooks'), script);
         }
         if (localHooksDir) {
-            const local = resolveContainedHookPath(localHooksDir, script);
+            // Prefer the exact relative path, then a flat basename copy (sync flattens
+            // group-dir scripts into the version-home hooks/ root).
+            const local = resolveContainedHookPath(localHooksDir, script) ||
+                resolveContainedHookPath(localHooksDir, path.basename(script));
             if (local)
                 return local;
         }

package/dist/lib/humans.d.ts

@@ -0,0 +1,25 @@
+import type { HumansConfig, HumanOwner } from './types.js';
+export declare const HUMANS_VERSION: 1;
+export declare const HUMANS_HEADER = "# humans.yaml \u2014 owner identity and notification channels\n# Managed by agents-cli. See: agents humans --help\n";
+/**
+ * Read and parse humans.yaml. Returns null when the file does not exist or
+ * is not a valid v1 config — never throws.
+ */
+export declare function readHumans(): HumansConfig | null;
+/**
+ * Write a HumansConfig to ~/.agents/humans.yaml. Creates the file with the
+ * canonical header. Overwrites any existing content.
+ */
+export declare function writeHumans(config: HumansConfig): void;
+/**
+ * Return the effective owner notification config from humans.yaml if
+ * available, otherwise return null (caller falls back to agents.yaml).
+ */
+export declare function getOwnerNotifyFromHumans(): {
+    channel: string;
+    to: string;
+} | null;
+/**
+ * Read the owner block from humans.yaml. Returns null if missing.
+ */
+export declare function getOwnerFromHumans(): HumanOwner | null;

package/dist/lib/humans.js

@@ -0,0 +1,65 @@
+/**
+ * humans.yaml — owner identity, channels, and notification policy.
+ *
+ * Canonical file: ~/.agents/humans.yaml
+ * Schema version: 1
+ *
+ * This module is the single read/write seam for humans.yaml. All channel/
+ * notify consumers should read owner config from here (with a fallback to
+ * the legacy notify.owner in agents.yaml during the migration window).
+ */
+import * as fs from 'fs';
+import * as yaml from 'yaml';
+import { getHumansFilePath } from './state.js';
+export const HUMANS_VERSION = 1;
+export const HUMANS_HEADER = `# humans.yaml — owner identity and notification channels
+# Managed by agents-cli. See: agents humans --help
+`;
+/**
+ * Read and parse humans.yaml. Returns null when the file does not exist or
+ * is not a valid v1 config — never throws.
+ */
+export function readHumans() {
+    const filePath = getHumansFilePath();
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const parsed = yaml.parse(raw);
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        const doc = parsed;
+        if (doc['version'] !== HUMANS_VERSION)
+            return null;
+        return doc;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write a HumansConfig to ~/.agents/humans.yaml. Creates the file with the
+ * canonical header. Overwrites any existing content.
+ */
+export function writeHumans(config) {
+    const filePath = getHumansFilePath();
+    const body = yaml.stringify(config, { lineWidth: 120 });
+    fs.writeFileSync(filePath, HUMANS_HEADER + body, { encoding: 'utf-8', mode: 0o600 });
+}
+/**
+ * Return the effective owner notification config from humans.yaml if
+ * available, otherwise return null (caller falls back to agents.yaml).
+ */
+export function getOwnerNotifyFromHumans() {
+    const humans = readHumans();
+    const notify = humans?.owner?.notify;
+    if (notify?.channel && notify?.to)
+        return notify;
+    return null;
+}
+/**
+ * Read the owner block from humans.yaml. Returns null if missing.
+ */
+export function getOwnerFromHumans() {
+    return readHumans()?.owner ?? null;
+}

package/dist/lib/memory.js

@@ -46,8 +46,9 @@ export function ensureUserMemoryDir() {
     }
     return dir;
 }
+const RULE_FILE_NAMES = new Set(['memory.md', 'agents.md', 'claude.md', 'gemini.md', 'readme.md']);
 function isFactFile(name) {
-    return name.endsWith('.md') && name.toLowerCase() !== 'memory.md';
+    return name.endsWith('.md') && !RULE_FILE_NAMES.has(name.toLowerCase());
 }
 function slugify(name) {
     return name

package/dist/lib/migrate.d.ts

@@ -132,7 +132,7 @@ export declare function migrateRoutineDeviceToDevices(routinesDir?: string): voi
  * Both seams are injectable so the migration is unit-testable without touching the
  * real routines dir (and without racing the routine module's own tests).
  */
-export declare function migrateWatchdogSentinelToRoutine(sentinelPath?: string, ensure?: (enabled: boolean) => void): void;
+export declare function migrateWatchdogSentinelToRoutine(sentinelPath?: string, enable?: (name: string, enabled: boolean) => void): void;
 /**
  * Rename cli/ → clis/ in each of the given `.agents/` directories.
  *

package/dist/lib/migrate.js

@@ -13,7 +13,7 @@ import { atomicWriteFileSync } from './fs-atomic.js';
 import { machineId } from './machine-id.js';
 import { AGENTS, agentConfigDirName, findInPath } from './agents.js';
 import { createLink } from './platform/index.js';
-import { ensureWatchdogRoutine } from './watchdog/routine.js';
+import { migrateLegacyRoutineActivation, setJobEnabled } from './routines.js';
 const HOME = process.env.HOME ?? os.homedir();
 const USER_DIR = path.join(HOME, '.agents');
 /** Canonical system-repo location (post-fold). */
@@ -1106,9 +1106,7 @@ function migrateRuntimeToCache() {
     // releases moved into ~/.agents/.cache/plugins/. See issue #20.
     moveDirOnce(path.join(USER_DIR, 'cloud'), path.join(CACHE_DIR, 'cloud'));
     moveDirOnce(path.join(USER_DIR, 'drive'), path.join(CACHE_DIR, 'drive'));
-    // terminals/ stays at the top level: the agents-cli IDE extension publishes
-    // ~/.agents/terminals/live-terminals.json and would race with the move on
-    // VS Code restart. Leave the path where the extension expects it.
+    moveDirOnce(path.join(USER_DIR, 'terminals'), path.join(CACHE_DIR, 'terminals'));
     moveDirOnce(path.join(USER_DIR, 'logs'), path.join(CACHE_DIR, 'logs'));
     moveDirOnce(path.join(USER_DIR, 'companion'), path.join(CACHE_DIR, 'companion'));
     moveDirOnce(path.join(USER_DIR, 'runtime'), path.join(CACHE_DIR, 'state'));
@@ -1633,7 +1631,7 @@ function containsOnlyDsStore(dir) {
 function warnSystemOrphans() {
     const SHIPPED_ALLOWLIST = new Set([
         // resource directories shipped by the npm package
-        'commands', 'hooks', 'skills', 'rules', 'mcp', 'clis', 'permissions', 'subagents', 'profiles', 'agents', 'routines',
+        'commands', 'hooks', 'skills', 'rules', 'mcp', 'clis', 'permissions', 'subagents', 'profiles', 'agents', 'routines', 'webhooks',
         // top-level metadata files
         'agents.yaml', 'hooks.yaml', 'README.md', 'CHANGELOG.md',
         // git + repo metadata
@@ -1997,11 +1995,11 @@ export function migrateRoutineDeviceToDevices(routinesDir) {
  * Both seams are injectable so the migration is unit-testable without touching the
  * real routines dir (and without racing the routine module's own tests).
  */
-export function migrateWatchdogSentinelToRoutine(sentinelPath = path.join(CACHE_DIR, 'state', 'watchdog', 'enabled'), ensure = ensureWatchdogRoutine) {
+export function migrateWatchdogSentinelToRoutine(sentinelPath = path.join(CACHE_DIR, 'state', 'watchdog', 'enabled'), enable = setJobEnabled) {
     if (!fs.existsSync(sentinelPath))
         return;
     try {
-        ensure(true);
+        enable('watchdog', true);
     }
     catch (err) {
         console.error(`watchdog sentinel migration: could not create the routine (${err.message}); leaving the sentinel for a later retry`);
@@ -2033,6 +2031,115 @@ export function migrateCliDirToClis(agentsDirs) {
         fs.renameSync(src, dest);
     }
 }
+/**
+ * Migrate owner identity into humans.yaml.
+ *
+ * Sources (both are optional; migration is a no-op when neither exists):
+ *   1. ~/.agents/agents.yaml notify.owner.{channel,to} — short-form notify config.
+ *   2. ~/.agents/owner.md  — YAML frontmatter with name/timezone/quiet_hours/channels/policy.
+ *
+ * Writes ~/.agents/humans.yaml (version: 1) when at least one source is
+ * present, then removes the migrated keys. Idempotent: exits immediately when
+ * humans.yaml already exists.
+ */
+function migrateHumans() {
+    const humansFile = path.join(USER_DIR, 'humans.yaml');
+    if (fs.existsSync(humansFile))
+        return;
+    const agentsYamlPath = path.join(USER_DIR, 'agents.yaml');
+    const ownerMdPath = path.join(USER_DIR, 'owner.md');
+    let notifyOwner;
+    let ownerName;
+    let ownerTimezone;
+    let ownerQuietHours;
+    let ownerDefaultSeverity;
+    let ownerChannels;
+    let ownerPolicy;
+    // 1. Read notify.owner from agents.yaml.
+    if (fs.existsSync(agentsYamlPath)) {
+        try {
+            const raw = fs.readFileSync(agentsYamlPath, 'utf-8');
+            const doc = yaml.parse(raw);
+            const notify = doc?.['notify'];
+            const owner = notify?.['owner'];
+            const channel = typeof owner?.['channel'] === 'string' ? owner['channel'] : undefined;
+            const to = typeof owner?.['to'] === 'string' ? owner['to'] : undefined;
+            if (channel && to) {
+                notifyOwner = { channel, to };
+            }
+        }
+        catch { /* best-effort */ }
+    }
+    // 2. Read YAML frontmatter from owner.md.
+    if (fs.existsSync(ownerMdPath)) {
+        try {
+            const raw = fs.readFileSync(ownerMdPath, 'utf-8');
+            const fmMatch = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+            if (fmMatch) {
+                const fm = yaml.parse(fmMatch[1]);
+                if (fm && typeof fm === 'object') {
+                    if (typeof fm['name'] === 'string')
+                        ownerName = fm['name'];
+                    if (typeof fm['timezone'] === 'string')
+                        ownerTimezone = fm['timezone'];
+                    if (typeof fm['quiet_hours'] === 'string')
+                        ownerQuietHours = fm['quiet_hours'];
+                    if (typeof fm['default_severity'] === 'string')
+                        ownerDefaultSeverity = fm['default_severity'];
+                    if (Array.isArray(fm['channels']))
+                        ownerChannels = fm['channels'];
+                    if (fm['policy'] && typeof fm['policy'] === 'object')
+                        ownerPolicy = fm['policy'];
+                }
+            }
+        }
+        catch { /* best-effort */ }
+    }
+    // Only write if we have at least one piece of owner data.
+    if (!notifyOwner && !ownerName && !ownerTimezone && !ownerQuietHours && !ownerDefaultSeverity && !ownerChannels && !ownerPolicy)
+        return;
+    const humansDoc = { version: 1 };
+    const ownerDoc = {};
+    if (ownerName)
+        ownerDoc['name'] = ownerName;
+    if (ownerTimezone)
+        ownerDoc['timezone'] = ownerTimezone;
+    if (ownerQuietHours)
+        ownerDoc['quiet_hours'] = ownerQuietHours;
+    if (ownerDefaultSeverity)
+        ownerDoc['default_severity'] = ownerDefaultSeverity;
+    if (notifyOwner)
+        ownerDoc['notify'] = notifyOwner;
+    if (ownerChannels)
+        ownerDoc['channels'] = ownerChannels;
+    if (ownerPolicy)
+        ownerDoc['policy'] = ownerPolicy;
+    humansDoc['owner'] = ownerDoc;
+    try {
+        const header = '# humans.yaml — owner identity and notification channels\n# Managed by agents-cli. See: agents humans --help\n';
+        fs.writeFileSync(humansFile, header + yaml.stringify(humansDoc, { lineWidth: 120 }), { encoding: 'utf-8', mode: 0o600 });
+        console.error('Migrated owner config to humans.yaml');
+    }
+    catch (err) {
+        console.error(`humans.yaml migration: could not write (${err.message})`);
+        return;
+    }
+    // Remove notify.owner from agents.yaml after successful migration.
+    if (notifyOwner && fs.existsSync(agentsYamlPath)) {
+        try {
+            const raw = fs.readFileSync(agentsYamlPath, 'utf-8');
+            const doc = yaml.parseDocument(raw);
+            const notifyNode = doc.get('notify');
+            if (notifyNode instanceof yaml.YAMLMap) {
+                notifyNode.delete('owner');
+                if (notifyNode.items.length === 0)
+                    doc.delete('notify');
+            }
+            fs.writeFileSync(agentsYamlPath, String(doc), 'utf-8');
+        }
+        catch { /* best-effort — leave the old key if we can't rewrite */ }
+    }
+}
 /** Run all idempotent migrations. Safe to call multiple times. */
 export async function runMigration() {
     // MUST run first: every other migrator reads SYSTEM_DIR (the new path).
@@ -2043,6 +2150,7 @@ export async function runMigration() {
         cliMigrateDirs.push(projectDotAgents);
     migrateCliDirToClis(cliMigrateDirs);
     migrateAgentsYaml();
+    migrateHumans();
     deleteSystemPromptsJson();
     migrateSystemConfigJson();
     migratePromptcutsIntoHooks();
@@ -2096,6 +2204,7 @@ export async function runMigration() {
     migrateExtrasExtrasToAgentsExtras();
     // Rewrite routine YAML files: singular `device:` -> plural `devices: []`.
     migrateRoutineDeviceToDevices();
+    migrateLegacyRoutineActivation();
     // Fold the legacy watchdog enable sentinel into the watchdog routine so a user
     // who opted in under the old build stays opted in after upgrading. After the
     // routine rewrites above so the routines dir is in its canonical shape.

package/dist/lib/notify.js

@@ -1,4 +1,5 @@
 import { readMeta } from './state.js';
+import { getOwnerNotifyFromHumans } from './humans.js';
 import { registerBuiltinProviders } from './channels/providers/index.js';
 import { lookupTransport } from './channels/resolve.js';
 export function formatUrgentBlockMessage(block) {
@@ -40,7 +41,10 @@ export function buildOpenClawNotifyArgs(text, opts) {
  */
 export async function sendToOwner(text, options = {}) {
     const meta = options.meta ?? readMeta();
-    const owner = meta.notify?.owner;
+    // humans.yaml is the primary source; agents.yaml notify.owner is the fallback.
+    const humansOwner = getOwnerNotifyFromHumans();
+    const legacyOwner = meta.notify?.owner;
+    const owner = humansOwner ?? legacyOwner;
     const channel = options.channel ?? owner?.channel;
     const target = options.target ?? owner?.to;
     if (!channel || !target) {
@@ -48,7 +52,7 @@ export async function sendToOwner(text, options = {}) {
             ok: false,
             channel: channel ?? 'unknown',
             id: target ?? '',
-            error: 'notify.owner.{channel,to} not set in agents.yaml',
+            error: 'notify.owner.{channel,to} not set in humans.yaml or agents.yaml',
         };
     }
     registerBuiltinProviders();

package/dist/lib/permissions.js

@@ -122,9 +122,9 @@ export function convertDenyToCodexRules(deny) {
  * Ensure central permissions directory exists.
  */
 function ensurePermissionsDir() {
-    const dir = getUserPermissionsDir();
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
+    const groupsDir = path.join(getUserPermissionsDir(), 'groups');
+    if (!fs.existsSync(groupsDir)) {
+        fs.mkdirSync(groupsDir, { recursive: true });
     }
 }
 /**
@@ -350,7 +350,8 @@ export function listInstalledPermissions() {
     ensureAgentsDir();
     const seen = new Set();
     const results = [];
-    for (const dir of [getUserPermissionsDir(), getPermissionsDir()]) {
+    for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
+        const dir = path.join(baseDir, 'groups');
         if (!fs.existsSync(dir))
             continue;
         try {
@@ -377,10 +378,11 @@ export function listInstalledPermissions() {
     return results;
 }
 /**
- * Get a specific permission set by name. Searches user dir first, then system.
+ * Get a specific permission set by name. Searches user groups/ dir first, then system groups/.
  */
 function getPermissionSet(name) {
-    for (const dir of [getUserPermissionsDir(), getPermissionsDir()]) {
+    for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
+        const dir = path.join(baseDir, 'groups');
         for (const ext of ['.yml', '.yaml']) {
             const filePath = safeJoin(dir, name + ext);
             if (fs.existsSync(filePath)) {
@@ -402,7 +404,7 @@ export function installPermissionSet(sourcePath, name) {
     if (!set) {
         return { success: false, error: 'Invalid permission file' };
     }
-    const targetPath = safeJoin(getUserPermissionsDir(), name + '.yml');
+    const targetPath = safeJoin(path.join(getUserPermissionsDir(), 'groups'), name + '.yml');
     try {
         fs.copyFileSync(sourcePath, targetPath);
         return { success: true };
@@ -416,9 +418,9 @@ export function installPermissionSet(sourcePath, name) {
  * sets are intentionally not deletable from user commands.
  */
 export function removePermissionSet(name) {
-    const dir = getUserPermissionsDir();
+    const groupsDir = path.join(getUserPermissionsDir(), 'groups');
     for (const ext of ['.yml', '.yaml']) {
-        const filePath = safeJoin(dir, name + ext);
+        const filePath = safeJoin(groupsDir, name + ext);
         if (fs.existsSync(filePath)) {
             try {
                 fs.unlinkSync(filePath);
@@ -2025,7 +2027,7 @@ export function exportPermissionsFromPath(filePath) {
  */
 function savePermissionSet(set) {
     ensurePermissionsDir();
-    const filePath = safeJoin(getUserPermissionsDir(), set.name + '.yml');
+    const filePath = safeJoin(path.join(getUserPermissionsDir(), 'groups'), set.name + '.yml');
     try {
         const content = yaml.stringify({
             name: set.name,