@phnx-labs/agents-cli 1.22.15 → 1.22.17

package/dist/lib/feed-post.js

@@ -16,7 +16,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
-import { appendActivityEvent, } from './activity.js';
+import { appendActivityEvent, readRecentActivity, } from './activity.js';
 import { resolveProjectNameForCwd, listProjectDefs } from './projects.js';
 import { getHistoryDir } from './state.js';
 import { machineId } from './machine-id.js';
@@ -30,7 +30,7 @@ export const STATUS_TITLE_MAX_CHARS = 60;
  * Resolve who is posting. Order:
  *  1. Explicit --session flag
  *  2. Env: AGENT_SESSION_ID / AGENTS_SESSION_ID / basename(AGENTS_MAILBOX_DIR)
- *  3. Env AGENT_LAUNCH_ID → match in pid registry
+ *  3. Env AGENT_LAUNCH_ID → match in pid registry or activity index
  *  4. Walk parent PIDs from startPid (default process.ppid) through by-pid registry
  */
 export function resolvePostIdentity(input) {
@@ -55,8 +55,12 @@ export function resolvePostIdentity(input) {
             registry = walkPidRegistry(start, getParent, readEntry);
         }
     }
+    const activity = launchId && !envSession && !registry?.sessionId
+        ? readRecentActivity({ root: input.activityRoot, maxBytesPerSession: 64 * 1024 })
+            .find((event) => event.launchId === launchId)
+        : undefined;
     // Prefer env session (explicit + managed run), fill gaps from registry.
-    const sessionId = envSession ?? registry?.sessionId;
+    const sessionId = envSession ?? registry?.sessionId ?? activity?.sessionId;
     if (!sessionId || !isValidMailboxId(sessionId))
         return undefined;
     const mailboxFromEnv = mailboxIdFromEnv(env);
@@ -66,17 +70,18 @@ export function resolvePostIdentity(input) {
     return {
         sessionId,
         mailboxId,
-        host: machineIdFromEnv(env),
-        runtime: env.AGENTS_RUNTIME?.trim() || 'headless',
+        host: activity?.host ?? machineIdFromEnv(env),
+        runtime: env.AGENTS_RUNTIME?.trim() || activity?.runtime || 'headless',
         agent: env.AGENTS_AGENT_NAME?.trim()
             || registry?.agent
+            || activity?.agent
             || detectAgentKind(env),
         cwd: input.cwd
-            ?? (env.AGENTS_CWD?.trim() || registry?.cwd || process.cwd()),
-        pid: registry?.pid,
-        launchId: launchId || registry?.launchId,
-        terminalId: env.AGENT_TERMINAL_ID?.trim() || registry?.terminalId,
-        tmuxPane: env.TMUX_PANE?.trim() || registry?.tmuxPane,
+            ?? (env.AGENTS_CWD?.trim() || registry?.cwd || activity?.cwd || process.cwd()),
+        pid: registry?.pid ?? activity?.pid,
+        launchId: launchId || registry?.launchId || activity?.launchId,
+        terminalId: env.AGENT_TERMINAL_ID?.trim() || registry?.terminalId || activity?.terminalId,
+        tmuxPane: env.TMUX_PANE?.trim() || registry?.tmuxPane || activity?.tmuxPane,
     };
 }
 function firstValidId(candidates) {

package/dist/lib/hooks.d.ts

@@ -58,8 +58,10 @@ export interface DuplicateVersionHook {
 export declare function inspectDuplicateVersionHooks(cwd?: string): DuplicateVersionHook[];
 /**
  * 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`.
+ * 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 declare function listHookEntriesFromDir(dir: string): HookEntry[];
 /**

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/hosts/remote-cmd.js

@@ -118,6 +118,14 @@ export const RUN_OPTION_FORWARDING = {
     bare: 'local-only', // skips the local setup-copy push; lease-only concern
     tailscale: 'local-only', // --tailscale/--no-tailscale gate the lease net mode; never forwarded
     copyCreds: 'local-only', // copies creds TO the host before dispatch — local concern only
+    // Cloud placement: chosen and dispatched from THIS machine via the provider
+    // registry; mutually exclusive with --host (placement conflict dies before
+    // dispatch), so these never have a remote argv to ride.
+    cloud: 'local-only',
+    provider: 'local-only',
+    repo: 'local-only',
+    branch: 'local-only',
+    cloudEnv: 'local-only',
     authCheck: 'local-only', // --no-auth-check gates the local interactive login preflight; --host runs skip that preflight entirely
     // The notification must land on the box the PERSON is at — the one that
     // dispatched — not on a headless worker with no desktop to post to. The local

package/dist/lib/humans.d.ts

@@ -0,0 +1,26 @@
+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 destination from humans.yaml.
+ * The owner's normal-severity policy selects the channel; when no normal
+ * policy is declared, the first addressable channel is the default.
+ */
+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,73 @@
+/**
+ * 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.
+ */
+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 destination from humans.yaml.
+ * The owner's normal-severity policy selects the channel; when no normal
+ * policy is declared, the first addressable channel is the default.
+ */
+export function getOwnerNotifyFromHumans() {
+    const owner = readHumans()?.owner;
+    const channels = owner?.channels ?? [];
+    const preferredIds = owner?.policy?.normal ?? [];
+    const preferred = preferredIds
+        .map((id) => channels.find((entry) => entry.id === id))
+        .find((entry) => entry?.to);
+    const selected = preferred ?? channels.find((entry) => entry.to);
+    if (selected?.id && selected.to)
+        return { channel: selected.id, to: selected.to };
+    const migrated = owner?.notify;
+    if (migrated?.channel && migrated.to)
+        return migrated;
+    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.js

@@ -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
@@ -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();

package/dist/lib/notify.d.ts

@@ -4,7 +4,7 @@
  * Every human-facing owner notification (feed urgent-block dispatch, monitor
  * `notify` action, `agents notify`) funnels through the single channel seam:
  * `lookupTransport(channel, meta).provider.send(text, opts)`. The recipient comes
- * from `notify.owner` in agents.yaml — never a hardcoded chat id — so changing the
+ * from `humans.yaml` — never a hardcoded chat id — so changing the
  * owner is honoured by every path at once. `notify.transports` picks the actual
  * provider per host (rush telegram on zion, openclaw-telegram on mac-mini).
  * Best-effort: a delivery failure is returned to the caller, never thrown, so a
@@ -19,9 +19,9 @@ import type { SendResult } from './channels/registry.js';
 export interface OwnerNotifyOptions {
     /** Config source (defaults to `readMeta()`); lets callers/tests inject it. */
     meta?: Meta;
-    /** Override the owner channel from `notify.owner.channel`. */
+    /** Override the owner channel resolved from humans.yaml. */
     channel?: string;
-    /** Override the owner target from `notify.owner.to`. */
+    /** Override the owner target resolved from humans.yaml. */
     target?: string;
     /** Resolve + build the delivery but do not actually send. */
     dryRun?: boolean;
@@ -44,7 +44,7 @@ export declare function buildOpenClawNotifyArgs(text: string, opts: {
 }): string[];
 /**
  * Deliver a message to the configured owner through the one channel seam.
- * `channel`/`target` default to `notify.owner.{channel,to}`; `notify.transports`
+ * `channel`/`target` default to the normal owner channel in humans.yaml; `notify.transports`
  * selects the provider per host. A missing owner config or a delivery failure
  * (e.g. openclaw not on PATH) returns a clean `SendResult` error — never a raw
  * ENOENT — so callers surface a consistent, best-effort failure.

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) {
@@ -33,14 +34,14 @@ export function buildOpenClawNotifyArgs(text, opts) {
 }
 /**
  * Deliver a message to the configured owner through the one channel seam.
- * `channel`/`target` default to `notify.owner.{channel,to}`; `notify.transports`
+ * `channel`/`target` default to the normal owner channel in humans.yaml; `notify.transports`
  * selects the provider per host. A missing owner config or a delivery failure
  * (e.g. openclaw not on PATH) returns a clean `SendResult` error — never a raw
  * ENOENT — so callers surface a consistent, best-effort failure.
  */
 export async function sendToOwner(text, options = {}) {
     const meta = options.meta ?? readMeta();
-    const owner = meta.notify?.owner;
+    const owner = getOwnerNotifyFromHumans() ?? meta.notify?.owner;
     const channel = options.channel ?? owner?.channel;
     const target = options.target ?? owner?.to;
     if (!channel || !target) {
@@ -48,7 +49,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: 'No addressable owner channel configured in humans.yaml or legacy notify.owner',
         };
     }
     registerBuiltinProviders();