@phnx-labs/agents-cli 1.20.92 → 1.21.0

package/dist/commands/sync.d.ts

@@ -2,8 +2,8 @@
  * `agents sync` — synchronize central resources into an installed agent version.
  *
  * Forms:
- *   agents sync                                         # umbrella: fetch config repos -> reconcile all (secrets/sessions opt-in)
- *   agents sync --repos|--secrets|--sessions            # umbrella: fetch only those, then reconcile
+ *   agents sync                                         # umbrella: fetch config repos -> reconcile all (secrets opt-in)
+ *   agents sync --repos|--secrets                       # umbrella: fetch only those, then reconcile
  *   agents sync --cloud                                 # umbrella: fetch all, skip reconcile
  *   agents sync --local                                 # umbrella: reconcile all, no fetch
  *   agents sync system                                  # one repo: git pull --rebase (pull-only mirror)

package/dist/commands/sync.js

@@ -2,8 +2,8 @@
  * `agents sync` — synchronize central resources into an installed agent version.
  *
  * Forms:
- *   agents sync                                         # umbrella: fetch config repos -> reconcile all (secrets/sessions opt-in)
- *   agents sync --repos|--secrets|--sessions            # umbrella: fetch only those, then reconcile
+ *   agents sync                                         # umbrella: fetch config repos -> reconcile all (secrets opt-in)
+ *   agents sync --repos|--secrets                       # umbrella: fetch only those, then reconcile
  *   agents sync --cloud                                 # umbrella: fetch all, skip reconcile
  *   agents sync --local                                 # umbrella: reconcile all, no fetch
  *   agents sync system                                  # one repo: git pull --rebase (pull-only mirror)
@@ -37,6 +37,7 @@ import { capableAgents } from '../lib/capabilities.js';
 import { parseHookManifest, registerHooksToSettings } from '../lib/hooks.js';
 import { compileRulesForProject } from '../lib/rules/compile.js';
 import { runLaunchSync } from '../lib/project-launch.js';
+import { formatKeptProjectResources } from '../lib/project-resources.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
 import { runUmbrellaSync } from '../lib/sync-umbrella.js';
 import { addHostOption } from '../lib/hosts/option.js';
@@ -46,7 +47,7 @@ import { getSystemAgentsDir, getUserAgentsDir, getEnabledExtraRepos } from '../l
 export function registerSyncCommand(program) {
     addHostOption(program.command('sync [agentSpec] [repo]'))
         .summary('Make this machine current, or sync resources into one agent')
-        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude", "claude@2.1.142", a selector: @latest / @oldest / @pinned (= @default), or @all for every installed version.\n\nAppend a [repo] (or pass --repo) to scope the sync to a single DotAgent repo — system / user / project / <alias>. e.g. "agents sync claude@all system" reconciles only the system repo\'s resources into every installed Claude.\n\nGive a DotAgent repo name ALONE — "agents sync system" / "agents sync user" / "agents sync <alias>" — to git-sync that one repo: refuse if the tree is dirty, else git pull --rebase against origin. The user repo and extra aliases also push local commits up; the system repo is a pull-only mirror.\n\nWith NO agent, runs the umbrella verb: fetch the config repos then reconcile them into every installed agent. Secrets and sessions are opt-in — add --secrets to pull secret bundles or --sessions to sync transcripts (sessions are also queryable live via "agents sessions --host <machine>"). Also: --cloud (fetch only), --local (reconcile only).')
+        .description('With an [agentSpec], syncs resources (commands, skills, hooks, rules, MCPs, plugins, etc.) into that installed agent version — previews changes and lets you pick. e.g. "claude", "claude@2.1.142", a selector: @latest / @oldest / @pinned (= @default), or @all for every installed version.\n\nAppend a [repo] (or pass --repo) to scope the sync to a single DotAgent repo — system / user / project / <alias>. e.g. "agents sync claude@all system" reconciles only the system repo\'s resources into every installed Claude.\n\nGive a DotAgent repo name ALONE — "agents sync system" / "agents sync user" / "agents sync <alias>" — to git-sync that one repo: refuse if the tree is dirty, else git pull --rebase against origin. The user repo and extra aliases also push local commits up; the system repo is a pull-only mirror.\n\nWith NO agent, runs the umbrella verb: fetch the config repos then reconcile them into every installed agent. Secrets are opt-in — add --secrets to pull secret bundles. Session transcripts are queryable live via "agents sessions --host <machine>", or moved with "agents sessions export/import". Also: --cloud (fetch only), --local (reconcile only).')
         .option('--agent <agent>', 'Agent identifier (legacy form; prefer the positional spec)')
         .option('--agent-version <version>', 'Version to sync into (legacy form; prefer "agent@version")')
         .option('--repo <name>', 'Scope the sync to a single DotAgent repo: system / user / project / <alias> (also accepted as a positional)')
@@ -59,7 +60,6 @@ export function registerSyncCommand(program) {
         // Umbrella verb (no agent given): make this machine current.
         .option('--repos', 'Umbrella: git-pull ~/.agents + enabled ~/.agents-* extras', false)
         .option('--secrets', 'Umbrella: pull encrypted secret bundles from the remote', false)
-        .option('--sessions', 'Umbrella: sync session transcripts across machines', false)
         .option('--cloud', 'Umbrella: fetch all remote state but skip the local reconcile', false)
         .option('--local', "Umbrella: reconcile resources into installed agents only (no fetch)", false)
         .action(async (agentSpec, repo, opts) => {
@@ -205,7 +205,7 @@ async function runUmbrella(opts, quiet, outLog, errLog) {
     // Interactive bare `agents sync` (a TTY, no --yes, no scope flag) drops into
     // the two-checklist picker: which repos to sync from, which agents to sync
     // into. Any explicit flag or --yes keeps the non-interactive umbrella below.
-    const anyExplicitFlag = !!(opts.repos || opts.secrets || opts.sessions || opts.cloud || opts.local);
+    const anyExplicitFlag = !!(opts.repos || opts.secrets || opts.cloud || opts.local);
     if (!quiet && !opts.yes && !anyExplicitFlag && isInteractiveTerminal()) {
         await runInteractiveReconcile(opts, outLog, errLog);
         return;
@@ -213,7 +213,6 @@ async function runUmbrella(opts, quiet, outLog, errLog) {
     const flags = {
         repos: opts.repos,
         secrets: opts.secrets,
-        sessions: opts.sessions,
         cloud: opts.cloud,
         local: opts.local,
     };
@@ -237,9 +236,6 @@ async function runUmbrella(opts, quiet, outLog, errLog) {
             if (result.secrets) {
                 parts.push(result.secrets.skipped ? 'secrets skipped' : `secrets ${result.secrets.pulled} pulled`);
             }
-            if (result.sessions) {
-                parts.push(result.sessions.ran ? `sessions ${result.sessions.merged} merged` : 'sessions off');
-            }
             if (result.reconciled)
                 parts.push('reconciled');
             outLog(chalk.green(`✓ sync: ${parts.join(' · ') || 'nothing to do'}`));
@@ -516,8 +512,11 @@ function printSyncDetail(result, agent, version, cwd) {
         lines.push({ kind: 'plugins', items: result.plugins });
     if (result.workflows.length > 0)
         lines.push({ kind: 'workflows', items: result.workflows });
+    const kept = formatKeptProjectResources(result.projectSkipped);
     if (lines.length === 0) {
         console.log(chalk.gray(`Already in sync — ${agentLabel(agent)}@${version}`));
+        if (kept)
+            console.log(chalk.gray(kept));
         return;
     }
     console.log(chalk.green(`Synced to ${agentLabel(agent)}@${version}:`));
@@ -531,6 +530,8 @@ function printSyncDetail(result, agent, version, cwd) {
         const count = chalk.cyan(`(${sorted.length})`.padStart(5));
         console.log(`  ${chalk.bold(padded)}  ${count}  ${chalk.gray(preview)}${more}`);
     }
+    if (kept)
+        console.log(chalk.gray(kept));
 }
 function runLaunchMode(agent, version, cwd, quiet) {
     let result;
@@ -561,7 +562,7 @@ function runLaunchMode(agent, version, cwd, quiet) {
     else {
         console.log(chalk.green(`Launch sync: ${bits.join(', ')}`));
     }
-    if (result.workspaceSkipped.length > 0) {
-        console.log(chalk.yellow(`Skipped (user-owned, not overwritten): ${result.workspaceSkipped.join(', ')}`));
-    }
+    const kept = formatKeptProjectResources(result.workspaceSkipped);
+    if (kept)
+        console.log(chalk.gray(kept));
 }

package/dist/commands/view.js

@@ -11,6 +11,7 @@ import { authCacheKey, formatCheckedAge, readAuthHealthCache } from '../lib/auth
 import { agentReportsUsage, deriveUsageStatusFromSnapshot, formatUsageSection, formatUsageSummary, formatUsageStatusBadge, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
 import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, getAvailableResources, getActuallySyncedResources, getNewResources, getProjectOnlyResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, reconcileStaleLatestForAgent, isGlobalBinaryAgent, getLiveVersion, isVersionIsolated, getIsolatedDefault, } from '../lib/versions.js';
+import { formatKeptProjectResources } from '../lib/project-resources.js';
 import { ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { renderMergedResources } from '../lib/merged-resources.js';
@@ -722,6 +723,9 @@ async function showInstalledVersions(filterAgentId, viewOpts) {
                         if (synced.length > 0) {
                             console.log(chalk.green(`\nSynced to ${agentLabel(filterAgentId)}@${defaultVersion}: ${synced.join(', ')}`));
                         }
+                        const kept = formatKeptProjectResources(result.projectSkipped);
+                        if (kept)
+                            console.log(chalk.gray(kept));
                     }
                 }
                 catch (err) {

package/dist/commands/watchdog.js

@@ -24,6 +24,9 @@ import { setHelpSections } from '../lib/help.js';
 import { parseDuration } from '../lib/hooks/cache.js';
 import { getRuntimeStateDir } from '../lib/state.js';
 import { setJobEnabled } from '../lib/routines.js';
+import { getActiveSessions } from '../lib/session/active.js';
+import { mailboxIdForActiveSession } from '../lib/mailbox-target.js';
+import { gcMailbox } from '../lib/mailbox-gc.js';
 import { ensureWatchdogRoutine, isWatchdogRoutineEnabled, watchdogRoutineExists, WATCHDOG_ROUTINE_NAME, WATCHDOG_ROUTINE_SCHEDULE, } from '../lib/watchdog/routine.js';
 import { runWatchdogTick, writePolicySentinel, DEFAULT_THRESHOLDS, } from '../lib/watchdog/runner.js';
 /** Default state dir the runner and these subcommands share. */
@@ -58,6 +61,21 @@ function humanMs(ms) {
         return `${Math.round(ms / 60_000)}m`;
     return `${Math.round(ms / 1000)}s`;
 }
+/**
+ * Run the mailbox liveness sweep against the same session set the tick just used.
+ * Idempotent and cheap: archiving a message twice is a no-op, and GC only scans
+ * directories. Failures are swallowed so a mailbox-root problem cannot break the
+ * watchdog tick.
+ */
+async function runMailboxGc(sessions) {
+    const activeBoxIds = new Set(sessions.map(mailboxIdForActiveSession).filter((id) => !!id));
+    try {
+        gcMailbox(activeBoxIds);
+    }
+    catch {
+        // GC is best-effort housekeeping; the next tick will retry.
+    }
+}
 function colorForOutcome(o) {
     if (o.injected)
         return chalk.green;
@@ -118,7 +136,7 @@ export function registerWatchdogCommand(program) {
         // path is the daemon routine, which runs `agents watchdog --nudge` — so the
         // routine's enabled state IS the on/off switch, not a flag read here.
         const computeWillInject = () => opts.nudge === true;
-        const tickOnce = async (willInject) => runWatchdogTick({
+        const tickOnce = async (willInject, sessions) => runWatchdogTick({
             nudge: willInject,
             nudgeText: opts.text,
             smart: opts.smart === true,
@@ -126,10 +144,13 @@ export function registerWatchdogCommand(program) {
             thresholds,
             allowGhosttyFocus: opts.allowGhosttyFocus === true,
             stateDir: stateDir(),
+            sessions,
         });
         if (!opts.watch) {
             const willInject = computeWillInject();
-            const result = await tickOnce(willInject);
+            const sessions = await getActiveSessions();
+            const result = await tickOnce(willInject, sessions);
+            await runMailboxGc(sessions);
             if (opts.json)
                 console.log(JSON.stringify(result, null, 2));
             else
@@ -146,7 +167,9 @@ export function registerWatchdogCommand(program) {
         while (true) {
             // Re-evaluated each tick: picks up enable/disable flips mid-run.
             const willInject = computeWillInject();
-            const result = await tickOnce(willInject);
+            const sessions = await getActiveSessions();
+            const result = await tickOnce(willInject, sessions);
+            await runMailboxGc(sessions);
             if (opts.json)
                 console.log(JSON.stringify(result));
             else

package/dist/index.js

@@ -94,11 +94,12 @@ if (IS_DEV_BUILD) {
 // module on each invocation (which loaded the whole ~50-module tree before the
 // first byte of output), the registry maps a command name to a thunk that
 // imports only what that command needs. See src/lib/startup/command-registry.ts.
-import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadDrive, loadFactory, loadUsage, loadCost, loadPerf, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadHq, loadFeed, loadActivity, loadMailboxes, } from './lib/startup/command-registry.js';
+import { COMMAND_LOADERS, LAZY_COMMAND_NAMES, loadView, loadInspect, loadFeedback, loadCommands, loadHooks, loadSkills, loadRules, loadMemory, loadPermissions, loadMcp, loadCli, loadSubagents, loadPlugins, loadWorkflows, loadWorktree, loadVersions, loadImport, loadExport, loadPackages, loadRoutines, loadMonitors, loadProjects, loadRun, loadFork, loadDefaults, loadSet, loadModels, loadPrune, loadTrash, loadRestore, loadDoctor, loadApply, loadStatus, loadProfiles, loadHarness, loadSecrets, loadLogin, loadWallet, loadHelper, loadMenubar, loadBeta, loadSync, loadLock, loadRefreshRules, loadFactory, loadUsage, loadCost, loadPerf, loadOutput, loadBudget, loadAlias, loadMine, loadPty, loadTmux, loadWatchdog, loadBrowser, loadComputer, loadHosts, loadLogs, loadEvents, loadAudit, loadWebhook, loadFunnel, loadSsh, loadPull, loadPush, loadRepo, loadSetup, loadUninstall, loadShare, loadSend, loadFeed, loadActivity, loadMailboxes, } from './lib/startup/command-registry.js';
 import { applyGlobalHelpConventions } from './lib/help.js';
 import { renderWhatsNew } from './lib/whats-new.js';
 import { getCliLaunch } from './lib/cli-entry.js';
 import { emit, emitFriction, redactArgs } from './lib/events.js';
+import { die } from './lib/format.js';
 // Transparent shim delegate: the generated Windows `.cmd` shims invoke
 // `agents __shim <agent>[@version] <raw args>`. Intercept here, before commander
 // parses anything, so the agent's own flags (`--help`, `--version`, etc.) pass
@@ -147,11 +148,25 @@ function auditCommandPath(cmd) {
     return parts;
 }
 const auditStarts = new WeakMap();
+/**
+ * Commands that WRITE the event stream, so recording their own invocation would
+ * add records to the log they are writing into. `events emit` is batched — one
+ * flush every few seconds per open editor window — so auditing it would bury the
+ * real events under two `command.*` records per flush. `_internal friction`
+ * exists for the same reason (shell guards fire before any `agents` process
+ * exists, so they cannot emit in-process) and had the same self-logging bug.
+ */
+const AUDIT_EXEMPT_COMMANDS = new Set([
+    'events emit',
+    '_internal friction',
+]);
 program.hook('preAction', (_thisCommand, actionCommand) => {
     try {
         const parts = auditCommandPath(actionCommand);
         if (parts.length === 0)
             return;
+        if (AUDIT_EXEMPT_COMMANDS.has(parts.join(' ')))
+            return;
         auditStarts.set(actionCommand, Date.now());
         emit('command.start', {
             module: parts[0],
@@ -172,6 +187,8 @@ program.hook('postAction', (_thisCommand, actionCommand) => {
         const parts = auditCommandPath(actionCommand);
         if (parts.length === 0)
             return;
+        if (AUDIT_EXEMPT_COMMANDS.has(parts.join(' ')))
+            return;
         const started = auditStarts.get(actionCommand);
         const durationMs = started !== undefined ? Date.now() - started : undefined;
         const command = parts.join(' ');
@@ -265,7 +282,6 @@ Run and dispatch:
   run <agent|profile> [prompt]    Run an agent. Omit prompt for interactive mode.
   defaults                        Configure run defaults by agent/version selector
   teams                           Coordinate multiple agents on shared work
-  hq                              JSON bridge for the interactive Agents HQ floor
   routines                        Run agents on a cron schedule (scheduler auto-starts)
   webhook                         Receive signed GitHub/Linear webhooks for trigger routines
   funnel                          Expose a webhook receiver through Tailscale Funnel
@@ -285,14 +301,13 @@ Diagnostics:
   perf                            Latency rollups (hooks, commands, runs) from the disposable perf warehouse
 
 Config sync:
-  drive                           Sync session history across machines via rsync
   pull                            Clone or pull the system repo at ~/.agents/.system/
   repo init --path <dir>          Scaffold your own editable repo from a template
   repo add <path|gh:user/repo>    Merge an extra repo after the system repo
   lock [--frozen]                 Write/verify agents.lock (SHA-256 of resolved resources); --frozen fails on drift
 
 Beta features:
-  beta                            Enable preview features (factory, drive, and more)
+  beta                            Enable preview features (factory and more)
 
 Automation tips:
   Pass explicit names/IDs         Avoid pickers: agents sessions <id> --markdown
@@ -705,6 +720,21 @@ function registerResourcesTombstoneCommand(p) {
         await program.parseAsync(['node', 'agents', ...args]);
     });
 }
+/**
+ * Removed `hq` command — the JSON bridge for the interactive Agents HQ floor
+ * (`agents hq floor --json`). No UI ever consumed it (apps/factory has zero
+ * references) and it had no external users, so it is gone with no replacement.
+ * Kept as a hidden tombstone so a stale invocation gets a clear message and a
+ * non-zero exit instead of commander's raw "unknown command".
+ */
+function registerHqTombstoneCommand(p) {
+    p.command('hq', { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(() => {
+        die('"agents hq" was removed (internal Agents HQ floor bridge, no longer used).');
+    });
+}
 /**
  * Hidden `agents _internal <sub>` namespace for machine-to-machine calls that
  * are not user-facing. The first subcommand is `friction`, used by shell guard
@@ -824,6 +854,9 @@ async function registerEagerForRequest(name) {
             registerResourcesTombstoneCommand(program);
             await reg(loadView);
             return true;
+        case 'hq':
+            registerHqTombstoneCommand(program);
+            return true;
         case '_internal':
             registerInternalCommand(program);
             return true;
@@ -896,7 +929,6 @@ async function registerAllEagerCommands() {
     await reg(loadSync);
     await reg(loadLock);
     await reg(loadRefreshRules);
-    await reg(loadDrive);
     await reg(loadFactory);
     await reg(loadUsage);
     await reg(loadCost);
@@ -916,7 +948,7 @@ async function registerAllEagerCommands() {
     await reg(loadAudit);
     await reg(loadWebhook);
     await reg(loadFunnel);
-    await reg(loadHq);
+    registerHqTombstoneCommand(program);
     await reg(loadFeed);
     await reg(loadActivity);
     await reg(loadMailboxes);

package/dist/lib/activity.d.ts

@@ -1,3 +1,4 @@
+import type { ActorKind } from './actor.js';
 import type { EventRecord } from './events.js';
 /** Recognizable milestone events, ordered first in any activity lane. */
 export type MilestoneEvent = 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created'
@@ -5,6 +6,14 @@ export type MilestoneEvent = 'plan.created' | 'pr.opened' | 'pr.merged' | 'workt
  | 'video.rendered' | 'video.converted' | 'image.upscaled' | 'metadata.edited'
 /** Deliberate agent-authored progress post (`agents feed post`). */
  | 'status.posted'
+/**
+ * An agent terminal spawned from the Factory VS Code extension. A milestone
+ * because it is the BIRTH of a session — it carries the sessionId and the
+ * terminalId that every later event on that session joins through, the same
+ * way `subagent.spawned` roots a sub-agent. Written out of process by
+ * `agents events emit`; the other factory.* kinds are operational-only.
+ */
+ | 'factory.launch'
 /**
  * The same post, but the agent is STUCK (`agents feed post --blocked`).
  *
@@ -72,6 +81,10 @@ export interface ActivityEvent {
     project?: string;
     /** Agent that produced the event (claude, codex, ...). */
     agent?: string;
+    /** Resolved actor id shared with the operational event stream. */
+    actor?: string;
+    /** Resolved actor kind shared with the operational event stream. */
+    kind?: ActorKind | 'unknown';
     /** Tool that triggered the event (Bash, Task, ExitPlanMode, feed.post, ...). */
     tool?: string;
     /** One-line human summary (plan title, PR command, sub-agent role, status text). */
@@ -82,6 +95,8 @@ export interface ActivityEvent {
     pid?: number;
     /** Spawn-time join key (`AGENT_LAUNCH_ID`) when known. */
     launchId?: string;
+    /** Session that spawned this session (`AGENTS_PARENT_SESSION_ID`) when known. */
+    parentSessionId?: string;
     /** Factory terminal id when the launch inherited one. */
     terminalId?: string;
     /** `$TMUX_PANE` at launch when recorded. */

package/dist/lib/activity.js

@@ -25,6 +25,7 @@ import { relTime, truncate } from './format.js';
 import { getActivityDir, getUserAgentsDir } from './state.js';
 import { normalizeHost } from './machine-id.js';
 import { projectKeyFromCwd } from './project-key.js';
+import { stampProvenance } from './event-provenance.js';
 /** The set of milestone events, for tier classification and ordering. */
 export const MILESTONE_EVENTS = [
     'plan.created',
@@ -43,6 +44,12 @@ export const MILESTONE_EVENTS = [
     'image.upscaled',
     'metadata.edited',
     'status.posted',
+    // NOTE: intentionally absent from the Python hook's own MILESTONE_EVENTS copy
+    // (see ACTIVITY_LOG_HOOK_SCRIPT below) — that set only classifies events the
+    // hook itself writes from PreToolUse/PostToolUse, and the hook never writes
+    // this one. activity.test.ts pins the difference so the divergence stays
+    // deliberate rather than becoming drift.
+    'factory.launch',
     'status.blocked',
 ];
 const MILESTONE_SET = new Set(MILESTONE_EVENTS);
@@ -103,6 +110,7 @@ export function appendActivityEvent(event, root) {
     const dir = root ?? getActivityDir();
     fs.mkdirSync(dir, { recursive: true });
     const record = {
+        ...stampProvenance(),
         v: event.v ?? 1,
         tier: event.tier ?? tierForEvent(event.event),
         ...event,
@@ -129,11 +137,14 @@ function parseLine(line) {
             cwd: parsed.cwd,
             project: parsed.project,
             agent: parsed.agent,
+            actor: parsed.actor,
+            kind: parsed.kind,
             tool: parsed.tool,
             detail: parsed.detail,
             url: parsed.url,
             pid: typeof parsed.pid === 'number' ? parsed.pid : undefined,
             launchId: parsed.launchId,
+            parentSessionId: parsed.parentSessionId,
             terminalId: parsed.terminalId,
             tmuxPane: parsed.tmuxPane,
             category: typeof parsed.category === 'string' ? parsed.category : undefined,
@@ -262,10 +273,12 @@ export function activityEventToRecord(ev) {
         level: 'info',
         caller: ev.tool === 'feed.post' ? 'agent' : 'hook',
         session: ev.sessionId,
-        osUser: ev.agent ?? 'agent',
+        osUser: 'unknown',
         transport: 'local',
         // payload
         agent: ev.agent,
+        actor: ev.actor ?? 'unknown',
+        kind: ev.kind ?? 'unknown',
         sessionId: ev.sessionId,
         cwd: ev.cwd,
         module: 'activity',
@@ -275,6 +288,7 @@ export function activityEventToRecord(ev) {
         tier: ev.tier,
         ...(ev.project ? { project: ev.project } : {}),
         ...(ev.launchId ? { launchId: ev.launchId } : {}),
+        ...(ev.parentSessionId ? { parentSessionId: ev.parentSessionId } : {}),
         ...(ev.terminalId ? { terminalId: ev.terminalId } : {}),
         ...(ev.tmuxPane ? { tmuxPane: ev.tmuxPane } : {}),
         ...(ev.attachments?.length ? { attachments: ev.attachments } : {}),
@@ -302,6 +316,7 @@ export const EVENT_STYLE = {
     'checklist.created': { glyph: '☐', color: chalk.cyan, label: 'checklist created' },
     'status.posted': { glyph: '▸', color: chalk.white, label: 'status' },
     'file.edited': { glyph: '·', color: chalk.gray, label: 'file edited' },
+    'factory.launch': { glyph: '⌁', color: chalk.cyan, label: 'factory launch' },
     'bash.executed': { glyph: '$', color: chalk.gray, label: 'command run' },
 };
 export function styleForEvent(event) {
@@ -1514,8 +1529,17 @@ def main():
         cwd = payload.get("cwd") or os.environ.get("AGENTS_CWD")
         if cwd:
             record["cwd"] = cwd
-        agent = os.environ.get("AGENTS_AGENT_NAME") or "claude"
+        agent = os.environ.get("AGENTS_AGENT_NAME") or "unknown"
         record["agent"] = agent
+        record["actor"] = os.environ.get("AGENTS_ACTOR") or "unknown"
+        actor_kind = os.environ.get("AGENTS_ACTOR_KIND")
+        record["kind"] = actor_kind if actor_kind in ("human", "agent") else "unknown"
+        launch_id = os.environ.get("AGENT_LAUNCH_ID")
+        if launch_id:
+            record["launchId"] = launch_id
+        parent_session_id = os.environ.get("AGENTS_PARENT_SESSION_ID")
+        if parent_session_id:
+            record["parentSessionId"] = parent_session_id
 
     try:
         os.makedirs(activity_dir, exist_ok=True)

package/dist/lib/auto-dispatch.d.ts

@@ -43,7 +43,12 @@ export interface PlannedDispatch {
     title: string;
     delegateName: string;
 }
-/** Path to the shared factory project registry (written by the factory UI). */
+/**
+ * Path to the shared factory project registry (written by the factory UI).
+ * `AGENTS_FACTORY_PROJECTS_PATH` overrides it, mirroring `AGENTS_PROJECTS_DIR`
+ * (`state.ts`) — that seam is what lets `projects import --from-factory` be
+ * tested end-to-end against a real fixture file instead of a mock.
+ */
 export declare function factoryProjectsPath(): string;
 /** Read the project registry rows this module cares about. */
 export declare function readAutoDispatchProjects(): AutoDispatchProject[];

package/dist/lib/auto-dispatch.js

@@ -16,9 +16,14 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { homedir } from 'os';
-/** Path to the shared factory project registry (written by the factory UI). */
+/**
+ * Path to the shared factory project registry (written by the factory UI).
+ * `AGENTS_FACTORY_PROJECTS_PATH` overrides it, mirroring `AGENTS_PROJECTS_DIR`
+ * (`state.ts`) — that seam is what lets `projects import --from-factory` be
+ * tested end-to-end against a real fixture file instead of a mock.
+ */
 export function factoryProjectsPath() {
-    return path.join(homedir(), '.agents', 'factory', 'projects.json');
+    return process.env.AGENTS_FACTORY_PROJECTS_PATH ?? path.join(homedir(), '.agents', 'factory', 'projects.json');
 }
 /** Read the project registry rows this module cares about. */
 export function readAutoDispatchProjects() {

package/dist/lib/beta.d.ts

@@ -8,7 +8,7 @@
  * checks.
  */
 import type { BetaFeatureName } from './types.js';
-export declare const ALL_BETA_FEATURES: readonly ["drive", "factory", "session-sync", "projects"];
+export declare const ALL_BETA_FEATURES: readonly ["factory", "projects"];
 export declare function getEnabledBetaFeatures(): BetaFeatureName[];
 export declare function isBetaEnabled(feature: BetaFeatureName): boolean;
 export declare function getBetaConfigLocation(): {

package/dist/lib/beta.js

@@ -10,7 +10,7 @@
 import * as path from 'path';
 import { getAgentsDir, getOptionalUserAgentsDir, readMeta, writeMeta } from './state.js';
 import { readManifest, writeManifest } from './manifest.js';
-export const ALL_BETA_FEATURES = ['drive', 'factory', 'session-sync', 'projects'];
+export const ALL_BETA_FEATURES = ['factory', 'projects'];
 function isBetaFeatureName(value) {
     return typeof value === 'string' && ALL_BETA_FEATURES.includes(value);
 }

package/dist/lib/channels/send.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Delivery envelope for `agents send` / `agents notify`.
+ *
+ * One primitive: resolve a destination (channel + target), compose text + urls +
+ * attachments, hand off to a channel provider. `notify` is the same path with
+ * destination defaulted to `notify.owner` in agents.yaml — owner is an address
+ * alias (`--to owner`), not a separate stack.
+ *
+ * Agent control (`agents message`, `sessions inject`) stays outside this module.
+ */
+import type { Meta } from '../types.js';
+import type { SendResult } from './registry.js';
+/** Normalized delivery request after CLI/config resolution. */
+export interface SendEnvelope {
+    text: string;
+    channel: string;
+    to: string;
+    thread?: string;
+    attachments?: string[];
+    from?: string;
+    dryRun?: boolean;
+}
+export interface ResolveSendInput {
+    /**
+     * Body text. Prefer `--text`; positional `[text]` is accepted for compat and
+     * folded in when `--text` is omitted.
+     */
+    text?: string;
+    /** Positional `[text]` from commander (legacy). */
+    positionalText?: string;
+    /**
+     * Recipient. Channel-specific id, or the alias `owner` which expands to
+     * `notify.owner.{channel,to}`.
+     */
+    to?: string;
+    /** Provider/channel name. Required unless `to` is `owner` (or ownerMode). */
+    channel?: string;
+    thread?: string;
+    /** Local file paths. */
+    attachments?: string[];
+    /** Links / remote media refs — appended to the body so every provider sees them. */
+    urls?: string[];
+    from?: string;
+    dryRun?: boolean;
+    /**
+     * When true (`agents notify`), missing channel/to default to `notify.owner`.
+     * Explicit flags still win.
+     */
+    ownerMode?: boolean;
+}
+export type ResolveSendResult = {
+    ok: true;
+    envelope: SendEnvelope;
+} | {
+    ok: false;
+    error: string;
+};
+/** True when the destination token means “the configured owner”. */
+export declare function isOwnerAlias(to: string | undefined): boolean;
+/** Compose body + optional URL lines (skip urls already present in the body). */
+export declare function composeSendText(text: string, urls?: string[]): string;
+/** Read notify.owner; null when either field is missing. */
+export declare function readOwnerDest(meta: Meta): {
+    channel: string;
+    to: string;
+} | null;
+/**
+ * Resolve CLI/config into a send envelope. Pure except for reading `meta` —
+ * no I/O, no provider registration — so unit tests do not need a real PATH.
+ */
+export declare function resolveSendEnvelope(input: ResolveSendInput, meta: Meta): ResolveSendResult;
+/**
+ * Register providers, resolve transport, deliver. Used by the CLI and by any
+ * internal caller that already has a resolved envelope.
+ */
+export declare function deliverEnvelope(envelope: SendEnvelope, meta: Meta): Promise<SendResult>;
+/** Resolve + deliver in one step (CLI happy path). */
+export declare function sendMessage(input: ResolveSendInput, meta: Meta): Promise<{
+    result: SendResult;
+    envelope: SendEnvelope;
+} | {
+    error: string;
+}>;