@phnx-labs/agents-cli 1.20.78 → 1.20.83

package/dist/lib/drift.d.ts

@@ -1,21 +1,27 @@
 /**
  * Shared drift-detection internals for `agents doctor` (overview mode) and
- * `agents check` (the scriptable, CI-friendly gate).
+ * `agents doctor --check` (the scriptable, CI-friendly gate).
  *
  * This is the single source of truth for "is the install out of sync?": the
  * per-version sync status (fresh / stale / never-synced) and the orphan census.
- * `agents doctor` renders it as a human report; `agents check` reduces it to an
- * exit code. Neither reimplements the diagnostic — both call `computeDrift`.
+ * `agents doctor` renders it as a human report; `agents doctor --check` reduces it
+ * to an exit code. Neither reimplements the diagnostic — both call `computeDrift`.
  */
 import type { AgentId } from './types.js';
-import { type VersionResourceReport } from './doctor-diff.js';
+import { type VersionResourceReport, type SourceLayerBehind } from './doctor-diff.js';
 export interface SyncStatusRow {
     agent: AgentId;
     version: string;
     status: 'fresh' | 'stale' | 'never-synced';
     isDefault: boolean;
-    /** For stale rows: prioritized lines naming exactly what diverged (plugins first). */
+    /** For stale rows: prioritized lines naming exactly what diverged (plugins first).
+     *  Also carries hook-wiring divergence for a version whose hooks are present but
+     *  not wired into settings.json — independent of manifest staleness. */
     divergence?: string[];
+    /** Count of hooks present on disk but NOT wired into the version's settings.json
+     *  (claude/droid). A non-zero value makes the version out-of-sync even when the
+     *  manifest reads fresh — the yosemite-s1 blind spot the CI gate must catch. */
+    unwiredHooks?: number;
 }
 export interface OrphanRow {
     agent: AgentId;
@@ -27,6 +33,14 @@ export interface OrphanRow {
 export declare function divergenceLines(report: VersionResourceReport): string[];
 export declare function checkSyncStatus(cwd: string): SyncStatusRow[];
 export declare function countOrphans(): OrphanRow[];
+/**
+ * Probe each source layer (user, system, enabled extras) for how far it trails
+ * its upstream, from the LAST-FETCHED remote-tracking ref (no network). A layer
+ * behind origin means every version home is reconciled against stale truth — a
+ * drift signal `agents doctor --check` must fail on, not a buried preamble. Returns
+ * only the behind layers. Canonical home for both `agents doctor` and `agents doctor --check`.
+ */
+export declare function computeSourceBehind(): SourceLayerBehind[];
 export interface DriftSummary {
     syncRows: SyncStatusRow[];
     orphanRows: OrphanRow[];
@@ -36,17 +50,23 @@ export interface DriftSummary {
     neverSyncedCount: number;
     /** Versions carrying orphan resources (informational — not a drift signal). */
     orphanVersionCount: number;
+    /** Versions with hooks present on disk but not wired into settings.json. */
+    unwiredHookVersions: number;
+    /** Source layers behind their upstream (reconciled against stale truth). */
+    sourceBehind: SourceLayerBehind[];
     /**
-     * True when any installed version is stale or never-synced — the exact signal
-     * `agents doctor` surfaces as "run `agents status` to review what has drifted".
-     * Orphans are a `prune` concern, not sync drift, so they do NOT set this flag
-     * (mirrors the sync-status engine: an orphan alone never flags needsSync).
+     * True when the install is out of sync: any installed version is stale,
+     * never-synced, or carries unwired hooks, OR a source layer is behind origin.
+     * `agents doctor` surfaces it as "run `agents status`"; `agents doctor --check`
+     * maps it to a non-zero exit. Orphans are a `prune` concern, not sync drift, so they do
+     * NOT set this flag (mirrors the sync-status engine: an orphan alone never
+     * flags needsSync).
      */
     hasDrift: boolean;
 }
 /**
  * Compute the same drift/divergence diagnostic `agents doctor` prints, reduced
- * to a summary with a single `hasDrift` boolean. The gate `agents check` maps
- * to an exit code; the readout `agents doctor` renders in full.
+ * to a summary with a single `hasDrift` boolean. The gate `agents doctor --check`
+ * maps to an exit code; the readout `agents doctor` renders in full.
  */
 export declare function computeDrift(cwd: string): DriftSummary;

package/dist/lib/drift.js

@@ -4,7 +4,9 @@ import { loadManifest, isStale } from './staleness/index.js';
 import { diffVersionResources } from './doctor-diff.js';
 import { diffVersionCommands, iterCommandsCapableVersions } from './commands.js';
 import { diffVersionSkills, iterSkillsCapableVersions } from './skills.js';
-import { iterHooksCapableVersions, listUnmanagedHooksInVersionHome } from './hooks.js';
+import { iterHooksCapableVersions, listUnmanagedHooksInVersionHome, checkVersionHookWiring } from './hooks.js';
+import { commitsBehindUpstream } from './git.js';
+import { getUserAgentsDir, getSystemAgentsDir, getEnabledExtraRepos } from './state.js';
 // Lines naming exactly what's out of sync for a version, plugins prioritized:
 // each divergent plugin gets its own line with specifics (stale mirror version,
 // invalid manifest, or the bundled skills/commands missing from the mirror —
@@ -46,14 +48,37 @@ export function checkSyncStatus(cwd) {
                 ? 'never-synced'
                 : isStale(manifest, agent, version, cwd) ? 'stale' : 'fresh';
             const row = { agent, version, status, isDefault: version === def };
+            const divergence = [];
             if (status === 'stale') {
                 // Resolve the specifics against non-project layers (the global home is
                 // never reconciled against per-cwd project resources).
                 const report = diffVersionResources(agent, version, { cwd, excludeProject: true });
-                const lines = divergenceLines(report);
-                if (lines.length)
-                    row.divergence = lines;
+                divergence.push(...divergenceLines(report));
             }
+            // Hook WIRING is independent of manifest staleness: a hook file can be
+            // byte-identical to source (fresh) yet absent from settings.json, so it
+            // never fires. Surface that for every version, fresh or stale, so overview
+            // AND `agents doctor --check` flag it (claude/droid; other agents report unsupported).
+            const wiring = checkVersionHookWiring(agent, version);
+            if (wiring.supported) {
+                const expected = wiring.expected ?? 0;
+                if (wiring.settingsMissing && expected > 0) {
+                    row.unwiredHooks = expected;
+                    divergence.push(`hooks       settings.json missing — ${expected} declared hook(s) never fire`);
+                }
+                else if (wiring.settingsUnparseable) {
+                    row.unwiredHooks = Math.max(1, expected);
+                    divergence.push(`hooks       settings.json unparseable — wiring cannot be verified`);
+                }
+                else if (wiring.unwired.length > 0) {
+                    row.unwiredHooks = wiring.unwired.length;
+                    const names = wiring.unwired.map((u) => u.name);
+                    const shown = names.slice(0, 3).join(', ');
+                    divergence.push(`hooks       ${wiring.unwired.length} unwired (${shown}${names.length > 3 ? ', …' : ''})`);
+                }
+            }
+            if (divergence.length)
+                row.divergence = divergence;
             rows.push(row);
         }
     }
@@ -91,22 +116,48 @@ export function countOrphans() {
     }
     return Array.from(byKey.values()).filter((r) => r.commands + r.skills + r.hooks > 0);
 }
+/**
+ * Probe each source layer (user, system, enabled extras) for how far it trails
+ * its upstream, from the LAST-FETCHED remote-tracking ref (no network). A layer
+ * behind origin means every version home is reconciled against stale truth — a
+ * drift signal `agents doctor --check` must fail on, not a buried preamble. Returns
+ * only the behind layers. Canonical home for both `agents doctor` and `agents doctor --check`.
+ */
+export function computeSourceBehind() {
+    const out = [];
+    const probe = (layer, dir, label, alias) => {
+        const r = commitsBehindUpstream(dir);
+        if (r && r.behind > 0)
+            out.push({ layer, label, alias, behind: r.behind, branch: r.branch });
+    };
+    probe('user', getUserAgentsDir(), '~/.agents', 'user');
+    probe('system', getSystemAgentsDir(), '~/.agents/.system', 'system');
+    for (const e of getEnabledExtraRepos())
+        probe('extra', e.dir, e.alias, e.alias);
+    return out;
+}
 /**
  * Compute the same drift/divergence diagnostic `agents doctor` prints, reduced
- * to a summary with a single `hasDrift` boolean. The gate `agents check` maps
- * to an exit code; the readout `agents doctor` renders in full.
+ * to a summary with a single `hasDrift` boolean. The gate `agents doctor --check`
+ * maps to an exit code; the readout `agents doctor` renders in full.
  */
 export function computeDrift(cwd) {
     const syncRows = checkSyncStatus(cwd);
     const orphanRows = countOrphans();
     const staleCount = syncRows.filter((r) => r.status === 'stale').length;
     const neverSyncedCount = syncRows.filter((r) => r.status === 'never-synced').length;
+    const unwiredHookVersions = syncRows.filter((r) => (r.unwiredHooks ?? 0) > 0).length;
+    const sourceBehind = computeSourceBehind();
     return {
         syncRows,
         orphanRows,
         staleCount,
         neverSyncedCount,
         orphanVersionCount: orphanRows.length,
-        hasDrift: syncRows.some((r) => r.status !== 'fresh'),
+        unwiredHookVersions,
+        sourceBehind,
+        hasDrift: syncRows.some((r) => r.status !== 'fresh') ||
+            unwiredHookVersions > 0 ||
+            sourceBehind.length > 0,
     };
 }

package/dist/lib/events.d.ts

@@ -11,8 +11,9 @@
  * - Permissions: logs dir is 0700, files are 0600 (owner-only)
  * - Performance tracking: withTiming() wrapper for any async function
  */
+import { type ActorKind } from './actor.js';
 export type EventLevel = 'audit' | 'warn' | 'info' | 'debug';
-export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'error' | 'warn' | 'info' | 'debug';
+export type EventType = 'agent.run.start' | 'agent.run.end' | 'agent.spawn.start' | 'agent.spawn.end' | 'version.install' | 'version.switch' | 'version.remove' | 'skill.install' | 'skill.remove' | 'browser.launch' | 'browser.close' | 'browser.navigate' | 'browser.screenshot' | 'secrets.get' | 'secrets.unlocked' | 'secrets.set' | 'secrets.delete' | 'secrets.rename' | 'cloud.dispatch' | 'cloud.complete' | 'cloud.cancel' | 'cloud.message' | 'teams.create' | 'teams.add' | 'teams.start' | 'teams.complete' | 'teams.disband' | 'hook.fire' | 'hook.complete' | 'hook.error' | 'mcp.add' | 'mcp.remove' | 'mcp.register' | 'resource.sync' | 'rotation.resolved' | 'command.start' | 'command.end' | 'perf.timing' | 'session.start' | 'session.end' | 'plan.created' | 'pr.opened' | 'pr.merged' | 'worktree.created' | 'worktree.removed' | 'commit.created' | 'pushed' | 'subagent.spawned' | 'artifact.created' | 'task.completed' | 'checklist.created' | 'status.posted' | 'file.edited' | 'error' | 'warn' | 'info' | 'debug';
 export declare function levelFor(event: EventType): EventLevel;
 export interface EventMeta {
     ts: string;
@@ -30,6 +31,10 @@ export interface EventMeta {
     osUser: string;
     transport: 'local' | 'ssh';
     sshClientIp?: string;
+    /** Resolved actor id — which human/agent is behind this event (RUSH-2020). */
+    actor?: string;
+    /** Actor kind (`human`/`agent`). */
+    kind?: ActorKind;
 }
 export interface EventPayload {
     agent?: string;
@@ -196,6 +201,8 @@ export interface EventStats {
     byEvent: Record<string, number>;
     byModule: Record<string, number>;
     byUser: Record<string, number>;
+    /** Event counts grouped by resolved actor id (the human/agent behind them). */
+    byActor: Record<string, number>;
     fileCount: number;
     totalBytes: number;
 }

package/dist/lib/events.js

@@ -19,6 +19,7 @@ import { gzipSync, gunzipSync } from 'node:zlib';
 import { parseSshConnection } from './session/provenance.js';
 import { ensureLockTarget, withFileLock } from './fs-atomic.js';
 import { getUserAgentsDir } from './state.js';
+import { resolveActor } from './actor.js';
 // ─── Constants ────────────────────────────────────────────────────────────────
 // Resolved lazily: events.ts is imported transitively by most CLI surfaces, and
 // import itself must stay side-effect free. Tests may override the exact path.
@@ -51,7 +52,7 @@ const DIR_MODE = 0o700;
 const FILE_MODE = 0o600;
 const AUDIT_EVENTS = new Set([
     'command.start', 'command.end',
-    'secrets.get', 'secrets.set', 'secrets.delete', 'secrets.rename',
+    'secrets.get', 'secrets.unlocked', 'secrets.set', 'secrets.delete', 'secrets.rename',
     'teams.create', 'teams.add', 'teams.start', 'teams.complete', 'teams.disband',
     'cloud.dispatch', 'cloud.complete', 'cloud.cancel', 'cloud.message',
     'version.install', 'version.switch', 'version.remove',
@@ -119,6 +120,7 @@ const SENSITIVE_PAYLOAD_KEY = /password|secret|token|api[-_]?key|auth/i;
 const RESERVED_META_KEYS = new Set([
     'ts', 'tz', 'tzName', 'hostname', 'platform', 'arch', 'pid', 'ppid',
     'event', 'level', 'caller', 'session', 'osUser', 'transport', 'sshClientIp',
+    'actor', 'kind',
 ]);
 function promptMarker(value) {
     const { prompt_length, prompt_sha256 } = redactPrompt(value);
@@ -276,10 +278,13 @@ function auditOrigin() {
         // Container/edge cases where the uid has no passwd entry.
     }
     const ssh = process.env.SSH_CONNECTION ? parseSshConnection(process.env.SSH_CONNECTION) : undefined;
+    const actor = resolveActor();
     _origin = {
         osUser,
         transport: ssh ? 'ssh' : 'local',
         ...(ssh ? { sshClientIp: ssh.clientIp } : {}),
+        actor: actor.id,
+        kind: actor.kind,
     };
     return _origin;
 }
@@ -693,6 +698,7 @@ export function stats(options = {}) {
     const byEvent = {};
     const byModule = {};
     const byUser = {};
+    const byActor = {};
     for (const r of records) {
         const lvl = r.level ?? levelFor(r.event);
         byLevel[lvl] = (byLevel[lvl] ?? 0) + 1;
@@ -701,6 +707,8 @@ export function stats(options = {}) {
             byModule[r.module] = (byModule[r.module] ?? 0) + 1;
         const user = `${r.osUser ?? '?'}@${r.hostname}`;
         byUser[user] = (byUser[user] ?? 0) + 1;
+        if (r.actor)
+            byActor[r.actor] = (byActor[r.actor] ?? 0) + 1;
     }
     let fileCount = 0;
     let totalBytes = 0;
@@ -723,6 +731,7 @@ export function stats(options = {}) {
         byEvent,
         byModule,
         byUser,
+        byActor,
         fileCount,
         totalBytes,
     };

package/dist/lib/exec.d.ts

@@ -262,6 +262,13 @@ export declare const AGENT_COMMANDS: Record<AgentId, AgentCommandTemplate>;
  * return false resume via the universal Tier-2 `/continue` replay instead.
  */
 export declare function nativeResume(agent: AgentId): boolean;
+/**
+ * Build the `-c` value that adds `dir` to codex's workspace-write writable
+ * roots. Codex parses the value as TOML, so it's a single-element TOML array of
+ * one quoted string. Used on codex resume forms, which reject `--add-dir` and
+ * only accept `-c` config overrides.
+ */
+export declare function codexWritableRootsConfig(dir: string): string;
 /** Assemble the full CLI argument array for an agent invocation. */
 export declare function buildExecCommand(options: ExecOptions): string[];
 /** Spawn an agent and return its exit code. Convenience wrapper over spawnAgent. */

package/dist/lib/exec.js

@@ -16,10 +16,11 @@ import { resolveModel, buildReasoningFlags } from './models.js';
 import { maybeRotate, createTimer, redactPrompt, redactArgs } from './events.js';
 import { sanitizeProcessEnv } from './secrets/bundles.js';
 import { resolveActor, actorEnv } from './actor.js';
-import { getShimsDir, getHistoryDir } from './state.js';
+import { getShimsDir, getHistoryDir, getUserAgentsDir } from './state.js';
 import { resolveCodexHome } from './codex-home.js';
 import { readCodexConfiguredModel } from './shims.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
+import { writeSessionActorRecord } from './session/actor-sidecar.js';
 import { loadHookSessionIndex, resolveHookSessionId } from './session/hook-sessions.js';
 import { sessionIdMarkerLine } from './hosts/session-marker.js';
 import { recordRunName } from './session/run-names.js';
@@ -563,13 +564,6 @@ export const AGENT_COMMANDS = {
         },
         modelFlag: '--model',
     },
-    forge: {
-        base: ['forge'],
-        promptFlag: 'positional',
-        modeFlags: {
-            edit: [],
-        },
-    },
 };
 /**
  * Whether `agent` has a native resume form (Tier 1). Derived solely from the
@@ -579,6 +573,15 @@ export const AGENT_COMMANDS = {
 export function nativeResume(agent) {
     return AGENT_COMMANDS[agent]?.resume !== undefined;
 }
+/**
+ * Build the `-c` value that adds `dir` to codex's workspace-write writable
+ * roots. Codex parses the value as TOML, so it's a single-element TOML array of
+ * one quoted string. Used on codex resume forms, which reject `--add-dir` and
+ * only accept `-c` config overrides.
+ */
+export function codexWritableRootsConfig(dir) {
+    return `sandbox_workspace_write.writable_roots=[${JSON.stringify(dir)}]`;
+}
 /** Assemble the full CLI argument array for an agent invocation. */
 export function buildExecCommand(options) {
     const template = AGENT_COMMANDS[options.agent];
@@ -664,6 +667,18 @@ export function buildExecCommand(options) {
         // AGENT_COMMANDS.modeFlags drifted apart. Tests assert they agree.
         throw new Error(`Internal error: ${options.agent} declares '${resolvedMode}' in capabilities.modes but has no entry in AGENT_COMMANDS.modeFlags.${resolvedMode}.`);
     }
+    // Codex's workspace-write sandbox blocks $HOME (verified against the live CLI
+    // and OpenAI's sandbox docs: writable roots extend scope "without removing the
+    // sandbox entirely"). But the model routinely shells out to `agents ...`, whose
+    // runtime state lives under ~/.agents — the SSH askpass shim
+    // (~/.agents/.cache/devices/askpass.sh), the device/stats cache, secrets,
+    // session writes, config tunings. Without ~/.agents as a writable root those
+    // inner writes fail with EROFS (e.g. `agents ssh` dies before connecting),
+    // which is why a remote `agents run codex` couldn't reach the fleet. Grant it
+    // implicitly whenever codex runs workspace-write — far narrower than --mode skip
+    // (danger-full-access). Fresh runs take --add-dir (below); resume forms reject
+    // --add-dir, so they take the same root via -c writable_roots here.
+    const codexWorkspaceWrite = options.agent === 'codex' && resolvedMode === 'edit';
     if (resumeSpec && 'subcommand' in resumeSpec) {
         if (resolvedMode === 'skip') {
             // skip = yolo on resume too; both `codex resume` (TUI) and
@@ -673,6 +688,8 @@ export function buildExecCommand(options) {
         else if (interactive) {
             // `codex resume` (TUI) accepts the same -s/--sandbox flags as a fresh run.
             cmd.push(...modeFlags);
+            if (codexWorkspaceWrite)
+                cmd.push('-c', codexWritableRootsConfig(getUserAgentsDir()));
         }
         else {
             // `codex exec resume` rejects `--sandbox <mode>` (verified against
@@ -682,6 +699,7 @@ export function buildExecCommand(options) {
             cmd.push('-c', `sandbox_mode=${resolvedMode === 'plan' ? 'read-only' : 'workspace-write'}`);
             if (resolvedMode !== 'plan') {
                 cmd.push('-c', 'sandbox_workspace_write.network_access=true');
+                cmd.push('-c', codexWritableRootsConfig(getUserAgentsDir()));
             }
         }
     }
@@ -785,9 +803,16 @@ export function buildExecCommand(options) {
     // claude-only, silently dropped for codex and masked by edit mode carrying
     // the approval/sandbox bypass. Codex's resume forms reject --add-dir, so
     // skip it there (claude's flag-based resume accepts it).
-    if (options.addDirs &&
+    //
+    // On top of any user-supplied dirs, a fresh codex workspace-write run
+    // implicitly gets ~/.agents (deduped) so the CLI's own tooling — askpass,
+    // secrets, sessions, tunings — can write from inside the sandbox. Resume forms
+    // get the same root via -c writable_roots above (see codexWorkspaceWrite).
+    const codexImplicitDirs = codexWorkspaceWrite && !options.resume ? [getUserAgentsDir()] : [];
+    const addDirs = [...new Set([...(options.addDirs ?? []), ...codexImplicitDirs])];
+    if (addDirs.length > 0 &&
         (options.agent === 'claude' || (options.agent === 'codex' && !options.resume))) {
-        for (const dir of options.addDirs) {
+        for (const dir of addDirs) {
             cmd.push('--add-dir', dir);
         }
     }
@@ -904,15 +929,28 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
         // wrapper, not the agent binary — the active scan resolves that by
         // walking the candidate's ancestors (readAncestorSessionEntry).
         if (child.pid) {
+            const passthroughSessionId = extractSessionIdArg(rawArgs);
             writePidSessionEntry({
                 pid: child.pid,
                 agent,
-                sessionId: extractSessionIdArg(rawArgs),
+                sessionId: passthroughSessionId,
                 cwd,
+                actor: resolveActor().id,
+                initiatedBy: resolveActor().kind,
                 launchId,
                 terminalId: process.env.AGENT_TERMINAL_ID,
                 startedAtMs: Date.now(),
             });
+            // Durable sessionId -> actor record (RUSH-2019) so the scanner can attribute
+            // this session to a person after the pid dies. Best-effort; no-ops without id.
+            if (passthroughSessionId) {
+                writeSessionActorRecord({
+                    sessionId: passthroughSessionId,
+                    actor: resolveActor().id,
+                    initiatedBy: resolveActor().kind,
+                    startedAtMs: Date.now(),
+                });
+            }
         }
         child.on('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
         child.on('error', (err) => {
@@ -1059,6 +1097,8 @@ async function runInTmux(options, executable, args) {
             agent: options.agent,
             sessionId: options.sessionId,
             cwd,
+            actor: resolveActor().id,
+            initiatedBy: resolveActor().kind,
             // spawnAgent injected AGENT_LAUNCH_ID into options.env before delegating
             // here; record the same id so the hook (running under the pane-leaf agent
             // pid) reconciles by launchId. This pane's pid usually IS the agent pid,
@@ -1068,6 +1108,14 @@ async function runInTmux(options, executable, args) {
             tmuxPane: pane,
             startedAtMs: Date.now(),
         });
+        if (options.sessionId) {
+            writeSessionActorRecord({
+                sessionId: options.sessionId,
+                actor: resolveActor().id,
+                initiatedBy: resolveActor().kind,
+                startedAtMs: Date.now(),
+            });
+        }
     }
     // Recap a dead pane's tail into THIS shell's stderr. The pane-died hook
     // detaches the client the instant the agent exits, so a fast failure (a
@@ -1279,11 +1327,21 @@ async function spawnAgent(options) {
             agent: options.agent,
             sessionId: options.sessionId,
             cwd: options.cwd || process.cwd(),
+            actor: resolveActor().id,
+            initiatedBy: resolveActor().kind,
             launchId,
             terminalId: process.env.AGENT_TERMINAL_ID,
             tmuxPane: process.env.TMUX_PANE,
             startedAtMs: Date.now(),
         });
+        if (options.sessionId) {
+            writeSessionActorRecord({
+                sessionId: options.sessionId,
+                actor: resolveActor().id,
+                initiatedBy: resolveActor().kind,
+                startedAtMs: Date.now(),
+            });
+        }
         // Mark startup time (time from function call to process spawn)
         timer.mark('startup');
         let budgetKilled = false;

package/dist/lib/feed-post.d.ts

@@ -1,4 +1,4 @@
-import { type ActivityEvent } from './activity.js';
+import { type ActivityEvent, type Attachment } from './activity.js';
 import { type PidSessionEntry } from './session/pid-registry.js';
 /** Soft cap so a runaway agent can't flood the activity lane with essays. */
 export declare const STATUS_POST_MAX_CHARS = 500;
@@ -7,8 +7,16 @@ export interface FeedPostInput {
     text: string;
     /** Override session id (escape hatch for scripts/tests). Prefer auto-resolve. */
     sessionId?: string;
+    /** Generic artifacts to attach: local paths (copied for durability) or URLs. */
+    attach?: string[];
     /** Override activity root (tests). */
     activityRoot?: string;
+    /**
+     * Override the attachments store root (tests). Local files are copied under
+     * `<attachmentsRoot>/<sessionId>/<updateId>/`. Defaults to
+     * `~/.agents/.history/attachments`.
+     */
+    attachmentsRoot?: string;
     /** Override env for identity resolution (tests). */
     env?: NodeJS.ProcessEnv;
     /** Override cwd stamp (defaults to process.cwd() / env). */
@@ -55,6 +63,25 @@ export declare function resolvePostIdentity(input: Pick<FeedPostInput, 'sessionI
 export declare function walkPidRegistry(startPid: number, getParent: (pid: number) => number | undefined, readEntry: (pid: number) => PidSessionEntry | undefined): PidSessionEntry | undefined;
 /** Best-effort parent pid of `pid` (Linux /proc, else `ps`). */
 export declare function parentPidOf(pid: number): number | undefined;
+/**
+ * Turn one `--attach` token into an {@link Attachment}. Remote URLs become
+ * `link` (or a media kind when the extension is unambiguous). Local files are
+ * classified by extension and, when `copyRoot` is set, copied under
+ * `<copyRoot>/<sessionId>/<updateId>/<basename>` so the link survives a worktree
+ * delete — the stored `href` then points at the durable copy. A missing local
+ * file is dropped (fail-open) rather than throwing.
+ */
+export declare function buildAttachment(token: string, ctx: {
+    copyRoot?: string;
+    sessionId: string;
+    updateId: string;
+}): Attachment | undefined;
+/** Classify + store every `--attach` token; empty/failed tokens are dropped. */
+export declare function buildAttachments(tokens: string[] | undefined, ctx: {
+    copyRoot?: string;
+    sessionId: string;
+    updateId: string;
+}): Attachment[];
 export declare function normalizeStatusText(text: string): string;
 /**
  * Append a `status.posted` milestone for the calling agent.

package/dist/lib/feed-post.js

@@ -15,7 +15,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { spawnSync } from 'child_process';
-import { appendActivityEvent, } from './activity.js';
+import { appendActivityEvent, projectFromCwd, } from './activity.js';
+import { getHistoryDir } from './state.js';
 import { machineId } from './machine-id.js';
 import { isValidMailboxId } from './mailbox.js';
 import { listPidSessionEntries, readPidSessionEntry, } from './session/pid-registry.js';
@@ -141,6 +142,104 @@ export function parentPidOf(pid) {
     }
     return undefined;
 }
+/** Extension → (kind, mediaType) for attachment classification. */
+const MEDIA_BY_EXT = {
+    '.png': { kind: 'image', mediaType: 'image/png' },
+    '.jpg': { kind: 'image', mediaType: 'image/jpeg' },
+    '.jpeg': { kind: 'image', mediaType: 'image/jpeg' },
+    '.gif': { kind: 'image', mediaType: 'image/gif' },
+    '.svg': { kind: 'image', mediaType: 'image/svg+xml' },
+    '.webp': { kind: 'image', mediaType: 'image/webp' },
+    '.wav': { kind: 'audio', mediaType: 'audio/wav' },
+    '.mp3': { kind: 'audio', mediaType: 'audio/mpeg' },
+    '.m4a': { kind: 'audio', mediaType: 'audio/mp4' },
+    '.aac': { kind: 'audio', mediaType: 'audio/aac' },
+    '.ogg': { kind: 'audio', mediaType: 'audio/ogg' },
+    '.flac': { kind: 'audio', mediaType: 'audio/flac' },
+    '.mp4': { kind: 'video', mediaType: 'video/mp4' },
+    '.mov': { kind: 'video', mediaType: 'video/quicktime' },
+    '.webm': { kind: 'video', mediaType: 'video/webm' },
+    '.mkv': { kind: 'video', mediaType: 'video/x-matroska' },
+};
+/** True when the token is an http(s) URL (a remote attachment / link). */
+function isRemoteUrl(token) {
+    return /^https?:\/\//i.test(token.trim());
+}
+function mediaForExt(ext) {
+    const hit = MEDIA_BY_EXT[ext.toLowerCase()];
+    return hit ? { kind: hit.kind, mediaType: hit.mediaType } : { kind: 'file' };
+}
+/** A short, filesystem-safe id grouping one post's copied attachments. */
+function newUpdateId(ts) {
+    const rand = Math.random().toString(36).slice(2, 8);
+    const stamp = ts.replace(/[^0-9]/g, '').slice(0, 14) || 'post';
+    return `${stamp}-${rand}`;
+}
+/**
+ * Turn one `--attach` token into an {@link Attachment}. Remote URLs become
+ * `link` (or a media kind when the extension is unambiguous). Local files are
+ * classified by extension and, when `copyRoot` is set, copied under
+ * `<copyRoot>/<sessionId>/<updateId>/<basename>` so the link survives a worktree
+ * delete — the stored `href` then points at the durable copy. A missing local
+ * file is dropped (fail-open) rather than throwing.
+ */
+export function buildAttachment(token, ctx) {
+    const value = token.trim();
+    if (!value)
+        return undefined;
+    if (isRemoteUrl(value)) {
+        const ext = path.extname(new URL(value).pathname);
+        const media = mediaForExt(ext);
+        const att = { kind: media.kind === 'file' ? 'link' : media.kind, href: value };
+        const name = path.basename(new URL(value).pathname);
+        if (name)
+            att.name = name;
+        if (media.mediaType)
+            att.mediaType = media.mediaType;
+        return att;
+    }
+    const abs = path.resolve(value);
+    let stat;
+    try {
+        stat = fs.statSync(abs);
+    }
+    catch {
+        return undefined; // dropped: local file does not exist
+    }
+    if (!stat.isFile())
+        return undefined;
+    const media = mediaForExt(path.extname(abs));
+    const name = path.basename(abs);
+    let href = abs;
+    if (ctx.copyRoot) {
+        try {
+            const destDir = path.join(ctx.copyRoot, ctx.sessionId, ctx.updateId);
+            fs.mkdirSync(destDir, { recursive: true });
+            const dest = path.join(destDir, name);
+            fs.copyFileSync(abs, dest);
+            href = dest;
+        }
+        catch {
+            href = abs; // copy failed: fall back to the original path
+        }
+    }
+    const att = { kind: media.kind, href, name, bytes: stat.size };
+    if (media.mediaType)
+        att.mediaType = media.mediaType;
+    return att;
+}
+/** Classify + store every `--attach` token; empty/failed tokens are dropped. */
+export function buildAttachments(tokens, ctx) {
+    if (!tokens?.length)
+        return [];
+    const out = [];
+    for (const token of tokens) {
+        const att = buildAttachment(token, ctx);
+        if (att)
+            out.push(att);
+    }
+    return out;
+}
 export function normalizeStatusText(text) {
     const collapsed = text.replace(/\s+/g, ' ').trim();
     if (!collapsed)
@@ -163,8 +262,15 @@ export function postFeedStatus(input) {
         throw new Error('No session id. Run from an agents-cli session '
             + '(AGENT_SESSION_ID / AGENTS_MAILBOX_DIR / pid registry), or pass --session <id>.');
     }
+    const ts = input.ts ?? new Date().toISOString();
+    const project = projectFromCwd(identity.cwd);
+    const attachments = buildAttachments(input.attach, {
+        copyRoot: input.attachmentsRoot ?? path.join(getHistoryDir(), 'attachments'),
+        sessionId: identity.sessionId,
+        updateId: newUpdateId(ts),
+    });
     const event = {
-        ts: input.ts ?? new Date().toISOString(),
+        ts,
         event: 'status.posted',
         sessionId: identity.sessionId,
         mailboxId: identity.mailboxId,
@@ -174,10 +280,12 @@ export function postFeedStatus(input) {
         agent: identity.agent,
         tool: 'feed.post',
         detail,
+        ...(project ? { project } : {}),
         ...(identity.pid !== undefined ? { pid: identity.pid } : {}),
         ...(identity.launchId ? { launchId: identity.launchId } : {}),
         ...(identity.terminalId ? { terminalId: identity.terminalId } : {}),
         ...(identity.tmuxPane ? { tmuxPane: identity.tmuxPane } : {}),
+        ...(attachments.length ? { attachments } : {}),
     };
     appendActivityEvent(event, input.activityRoot);
     return {