@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/lib/exec.d.ts

@@ -144,6 +144,15 @@ export interface ExecOptions {
      * (output is mirrored to the parent's stdout exactly like stdio:'inherit').
      */
     captureStdoutTail?: boolean;
+    /**
+     * Print the run's resolved session id to stdout as a one-line sentinel once the
+     * child exits (see hosts/session-marker.ts). Set by the `--host` dispatch so the
+     * LAUNCHER can relate the remote-created session back to itself — Claude's id is
+     * forced up front, but every other agent coins its own id on the remote box, and
+     * this marker is how that id rides the followed log home. Headless-only and inert
+     * for interactive runs (no combined log to parse).
+     */
+    emitSessionId?: boolean;
     /**
      * Escape hatch for the interactive tmux spawn-wrap (see shouldWrapInTmux):
      * when true, spawn the agent directly instead of inside a shared-socket tmux
@@ -188,6 +197,22 @@ export declare function inferredInteractiveWithoutTty(options: Pick<ExecOptions,
 export declare function shouldTapStdout(interactive: boolean, piped: boolean, capsActive: boolean, captureTail?: boolean): boolean;
 /** Parse an array of KEY=VALUE strings into an env record. Returns undefined for empty input. */
 export declare function parseExecEnv(entries: string[]): Record<string, string> | undefined;
+/**
+ * Resolve the launch id a run exports as `AGENT_LAUNCH_ID`.
+ *
+ * The launch id is the stable correlation key the SessionStart hook records
+ * alongside the agent's real session id (terminals/sessions/<pid>.json), so it
+ * is what maps a launch to its exact session even when the hook runs under a
+ * different pid (tmux pane leaf / cmd.exe wrapper) — and, across an SSH hop, what
+ * lets a `--host` launcher resolve the remote-coined id for agents that never
+ * accept a forced `--session-id`.
+ *
+ * ADOPT a caller-supplied `AGENT_LAUNCH_ID` (a `--host` launcher forwards one via
+ * `--env` so it controls the key end-to-end); MINT a fresh one otherwise (every
+ * local run, which passes none). A malformed inbound value is ignored in favour
+ * of a fresh mint — the key must be a real correlation id, never an empty string.
+ */
+export declare function resolveLaunchId(envLaunchId: string | undefined): string;
 /**
  * Build the process environment for an agent invocation.
  * Pins CLAUDE_CONFIG_DIR for Claude, CODEX_HOME for Codex, and COPILOT_HOME
@@ -339,6 +364,63 @@ export declare const BUDGET_KILL_EXIT_CODE = 7;
 export declare const RATE_LIMIT_PATTERNS: RegExp[];
 /** Return true if the text contains any known rate-limit or overload indicator. */
 export declare function detectRateLimit(text: string): boolean;
+/**
+ * Patterns that indicate an authentication failure — the agent is logged out,
+ * its token was revoked, or the session expired. These are the user-visible
+ * strings a logged-out agent surfaces (observed across the routine-run corpus).
+ * Unlike a rate limit, an auth failure is NOT self-healing by failover — every
+ * chain entry on the same account fails identically — so it is classified
+ * separately and never triggers a fallback attempt.
+ *
+ * The bare `401` is deliberately paired with an auth keyword: a plain "401" can
+ * appear in legitimate output (an HTTP-status table, a log line), so it only
+ * counts when it co-occurs with OAuth/authentication/credentials/Unauthorized.
+ */
+export declare const AUTH_FAILURE_PATTERNS: RegExp[];
+/**
+ * Return true if the text contains any known authentication-failure indicator.
+ * Agent-agnostic: matches the user-visible error string wherever it surfaces
+ * (stdout tail, a captured error message, a plain-text agent's output).
+ */
+export declare function detectAuthFailure(text: string): boolean;
+/**
+ * Return true if a stream-json log carries the structural markers of an auth
+ * failure. This is the authoritative signal for Claude: a logged-out run emits
+ *   {"type":"system","subtype":"api_retry","error":"authentication_failed",…}
+ *   {"type":"assistant",…,"error":"authentication_failed"}
+ *   {"type":"result","is_error":true,"result":"Failed to authenticate…"}
+ * Note `terminal_reason` is "completed" on such a run, so exit-code / terminal-
+ * reason logic can never catch it — the `error:"authentication_failed"` marker
+ * and the `result`+`is_error` text are the reliable signals.
+ *
+ * Gated on the Claude stream-json shape; other agents don't emit these fields,
+ * so callers pass their agent and this returns false for non-claude.
+ */
+export declare function detectAuthFailureEvent(logText: string, agent: AgentId): boolean;
+/**
+ * Return the first human-readable auth-failure phrase found in the text, for use
+ * as a stable, short run `errorMessage` reason. Falls back to null when the only
+ * signal was the structural `error:"authentication_failed"` marker with no
+ * user-visible string.
+ */
+export declare function authFailureReason(text: string): string | null;
+/**
+ * Decide whether a run's stream-json log is an authentication failure. The
+ * single source of truth for both the foreground and detached run paths.
+ *
+ * The structural marker (`detectAuthFailureEvent`, gated on `is_error:true`) is
+ * authoritative and safe on ANY exit — it catches a logged-out Claude that exits
+ * 0 (its `result` event carries `is_error:true` while `terminal_reason` is
+ * "completed"). The raw user-visible string (`detectAuthFailure`) is only
+ * consulted when the process actually FAILED, as a fallback for a run that died
+ * mid-stream before emitting a `result` event. That gate is what prevents a
+ * genuinely-completed run whose output merely *mentions* an auth phrase (e.g. a
+ * routine documenting a login flow) from being misclassified and having its
+ * legitimate report suppressed.
+ */
+export declare function isAuthFailureFromLog(logText: string, agent: AgentId, opts: {
+    processFailed: boolean;
+}): boolean;
 /** An agent (with optional pinned version) in a fallback chain. */
 export interface FallbackEntry {
     agent: AgentId;

package/dist/lib/exec.js

@@ -15,10 +15,13 @@ import { getBinaryPath, getVersionHomePath, isVersionInstalled, resolveVersion }
 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 { resolveCodexHome } from './codex-home.js';
 import { readCodexConfiguredModel } from './shims.js';
 import { writePidSessionEntry, extractSessionIdArg } from './session/pid-registry.js';
+import { loadHookSessionIndex, resolveHookSessionId } from './session/hook-sessions.js';
+import { sessionIdMarkerLine } from './hosts/session-marker.js';
 import { recordRunName } from './session/run-names.js';
 import { mailboxDir, isValidMailboxId } from './mailbox.js';
 import { composeWin32CommandLine } from './platform/index.js';
@@ -215,6 +218,25 @@ export function parseExecEnv(entries) {
     }
     return Object.fromEntries(entries.map(parseExecEnvEntry));
 }
+/**
+ * Resolve the launch id a run exports as `AGENT_LAUNCH_ID`.
+ *
+ * The launch id is the stable correlation key the SessionStart hook records
+ * alongside the agent's real session id (terminals/sessions/<pid>.json), so it
+ * is what maps a launch to its exact session even when the hook runs under a
+ * different pid (tmux pane leaf / cmd.exe wrapper) — and, across an SSH hop, what
+ * lets a `--host` launcher resolve the remote-coined id for agents that never
+ * accept a forced `--session-id`.
+ *
+ * ADOPT a caller-supplied `AGENT_LAUNCH_ID` (a `--host` launcher forwards one via
+ * `--env` so it controls the key end-to-end); MINT a fresh one otherwise (every
+ * local run, which passes none). A malformed inbound value is ignored in favour
+ * of a fresh mint — the key must be a real correlation id, never an empty string.
+ */
+export function resolveLaunchId(envLaunchId) {
+    const inbound = envLaunchId?.trim();
+    return inbound ? inbound : randomUUID();
+}
 /**
  * Build the process environment for an agent invocation.
  * Pins CLAUDE_CONFIG_DIR for Claude, CODEX_HOME for Codex, and COPILOT_HOME
@@ -312,14 +334,29 @@ export function buildExecEnv(options) {
     // iterations share one inbox.
     if (options.sessionId && isValidMailboxId(options.sessionId)) {
         result.AGENTS_MAILBOX_DIR = mailboxDir(options.sessionId);
+        // Full session id for agent-callable tools (`agents feed post`, etc.).
+        result.AGENT_SESSION_ID = options.sessionId;
+        result.AGENTS_SESSION_ID = options.sessionId;
     }
     result.AGENTS_RUNTIME = resolveInteractive(options) ? 'terminal' : 'headless';
+    // So activity / feed posts stamp the right harness without re-detecting.
+    if (options.agent) {
+        result.AGENTS_AGENT_NAME = options.agent;
+    }
+    if (options.cwd) {
+        result.AGENTS_CWD = options.cwd;
+    }
     // Export the run's durable name (companion to AGENT_SESSION_ID) so a
     // SessionStart hook / the agent can associate its transcript with the handle
     // the user gave the run. Only set when --name was passed.
     if (options.name) {
         result.AGENT_SESSION_NAME = options.name;
     }
+    // Actor provenance -- who initiated this run. Rides the env so the whole spawn
+    // tree shares one actor, and (for a resolved human) so the agent's own git
+    // commits are credited to the person instead of the shared account. options.env
+    // (spread last) overrides any of these keys a caller sets explicitly.
+    Object.assign(result, actorEnv(resolveActor()));
     return {
         ...result,
         ...options.env,
@@ -666,10 +703,16 @@ export function buildExecCommand(options) {
     else {
         cmd.push(...modeFlags);
     }
-    // Add print/headless flags only when a prompt is provided. Without a prompt
-    // the caller wants an interactive REPL -- passing --print would immediately
-    // wait on stdin and never render the TUI.
-    if (!interactive && options.headless && template.printFlags) {
+    // Add print/headless flags whenever the run RESOLVED headless -- gate on the
+    // resolved state (`!interactive`), not the raw `--headless` flag. Headless is
+    // inferred from prompt presence (resolveInteractive), and `--headless` defaults
+    // to `false` at the CLI layer, so gating on `options.headless` skipped these
+    // flags for a bare `agents run <agent> "prompt"`. For antigravity that meant
+    // `agy <prompt>` with no `--print`, launching the TUI and dying on `/dev/tty`
+    // in any non-terminal shell. `!interactive` is true for both an explicit
+    // `--headless` and a prompt-inferred headless run; an interactive run (no
+    // prompt, or `--interactive`) still skips them so the CLI opens its REPL.
+    if (!interactive && template.printFlags) {
         cmd.push(...template.printFlags);
     }
     // Resume vs. create. With `resume`, emit the agent's NATIVE resume reference:
@@ -842,9 +885,15 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
     }
     // The only flag the bash shim injects (codex); everything else is transparent.
     const launchArgs = agent === 'codex' ? ['-c', 'check_for_update_on_startup=false'] : [];
+    // Mint a launch id and export it as AGENT_LAUNCH_ID so the agent's SessionStart
+    // hook records the same id — the join key that maps this launch to its exact
+    // session even though the recorded pid here is the cmd.exe wrapper (Windows) or
+    // a shell, while the hook runs under the agent descendant. This is the primary
+    // attribution path on Windows (no lsof), so the launchId join matters most here.
+    const launchId = randomUUID();
     // mode/effort are required by ExecOptions but unused by buildExecEnv (which only
     // derives the per-version config-dir env); pass the agent's default to satisfy the type.
-    const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto' });
+    const env = buildExecEnv({ agent, version, cwd, mode: defaultModeFor(agent), effort: 'auto', env: { AGENT_LAUNCH_ID: launchId } });
     const { command, args, shell } = resolveShimSpawn(process.platform, binary, [...launchArgs, ...rawArgs]);
     return new Promise((resolve) => {
         const child = spawn(command, args, { cwd, stdio: 'inherit', env, shell });
@@ -860,6 +909,8 @@ export async function execShimPassthrough(agent, rawArgs, cwd, pinnedVersion) {
                 agent,
                 sessionId: extractSessionIdArg(rawArgs),
                 cwd,
+                launchId,
+                terminalId: process.env.AGENT_TERMINAL_ID,
                 startedAtMs: Date.now(),
             });
         }
@@ -1008,6 +1059,12 @@ async function runInTmux(options, executable, args) {
             agent: options.agent,
             sessionId: options.sessionId,
             cwd,
+            // 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,
+            // but the launchId join is robust even when it isn't.
+            launchId: options.env?.AGENT_LAUNCH_ID,
+            terminalId: process.env.AGENT_TERMINAL_ID,
             tmuxPane: pane,
             startedAtMs: Date.now(),
         });
@@ -1066,6 +1123,36 @@ async function runInTmux(options, executable, args) {
     // Pane still alive → the user detached; keep the session for `agents focus`.
     return { exitCode: 0, stderr: '', stdout: '' };
 }
+/**
+ * Print the run's resolved session id as a one-line stdout sentinel so a `--host`
+ * launcher can relate the remote-created session back to itself (see the
+ * `emitSessionId` option and hosts/session-marker.ts).
+ *
+ * For Claude the id was forced up front (`options.sessionId`, wired as
+ * `--session-id`), so it's authoritative with no lookup. Every other agent coined
+ * its OWN id, which its SessionStart hook recorded under this run's launchId — the
+ * exact join key `agents sessions --active` uses — so we read it back from the hook
+ * index by launchId (falling back to the child pid the hook may have recorded
+ * under). Nothing to emit when the hook hasn't landed an id (hookless harness):
+ * the launcher simply keeps the un-mapped task, never a fabricated id.
+ */
+function emitResolvedSessionId(options, launchId, childPid) {
+    let sessionId = options.sessionId;
+    if (!sessionId) {
+        try {
+            sessionId = resolveHookSessionId(loadHookSessionIndex(), {
+                pid: childPid ?? 0,
+                kind: options.agent,
+                launchId,
+            });
+        }
+        catch {
+            /* hook index unreadable — emit nothing rather than a guess */
+        }
+    }
+    if (sessionId)
+        process.stdout.write(sessionIdMarkerLine(sessionId));
+}
 /**
  * Spawn an agent process and return its exit code plus a tee'd copy of stderr.
  *
@@ -1104,7 +1191,21 @@ async function spawnAgent(options) {
     // timeout. Spend is recorded to the shared ledger in the close handler. The
     // watcher is dormant (and zero-cost) when no caps are configured.
     const cwd = options.cwd || process.cwd();
-    const runId = randomUUID();
+    // Resolve the launch id once. It doubles as the budget watcher's run id AND is
+    // exported to the child as AGENT_LAUNCH_ID, so the agent's SessionStart hook
+    // records the SAME id in its own state file (terminals/sessions/<pid>.json).
+    // That id is the join key that reconciles this launch's pid-registry entry
+    // with the hook's authoritative session id even when the hook runs under a
+    // different pid (tmux pane leaf / cmd.exe wrapper) — see pid-registry.ts and
+    // session/hook-sessions.ts. ADOPT a launch id a `--host` launcher already
+    // forwarded (via `--env AGENT_LAUNCH_ID=…`) so ONE correlation key spans the
+    // SSH hop and the launcher can resolve this run's real session id for every
+    // agent, not just Claude (RUSH-2034); mint a fresh one for every local run.
+    // Injected into options.env so every downstream env build (the bare spawn
+    // below AND the tmux env prefix in runInTmux) carries it.
+    const launchId = resolveLaunchId(options.env?.AGENT_LAUNCH_ID);
+    const runId = launchId;
+    options = { ...options, env: { ...options.env, AGENT_LAUNCH_ID: launchId } };
     const watcherState = await setupBudgetWatcher(options, cwd, runId);
     maybeRotate();
     const timer = createTimer('agent.run', {
@@ -1178,6 +1279,8 @@ async function spawnAgent(options) {
             agent: options.agent,
             sessionId: options.sessionId,
             cwd: options.cwd || process.cwd(),
+            launchId,
+            terminalId: process.env.AGENT_TERMINAL_ID,
             tmuxPane: process.env.TMUX_PANE,
             startedAtMs: Date.now(),
         });
@@ -1264,6 +1367,12 @@ async function spawnAgent(options) {
             // Budget kill resolves with a DISTINCT non-zero exit so CI/headless and
             // teams/cloud can tell a budget termination apart from a normal failure.
             const exitCode = budgetKilled ? BUDGET_KILL_EXIT_CODE : (code ?? 0);
+            // Relate the session id back to a `--host` launcher (see the emitSessionId
+            // doc). Claude's id is the one we forced; every other agent coined its own,
+            // which the SessionStart hook recorded under this run's launchId — resolve
+            // and print it as a one-line sentinel that rides the followed log home.
+            if (options.emitSessionId)
+                emitResolvedSessionId(options, launchId, child.pid);
             timer.end({ exitCode, status: budgetKilled ? 'budget_killed' : code === 0 ? 'success' : 'failed' });
             resolve({ exitCode, stderr: stderrBuffer, stdout: stdoutTail });
         });
@@ -1358,6 +1467,109 @@ export const RATE_LIMIT_PATTERNS = [
 export function detectRateLimit(text) {
     return RATE_LIMIT_PATTERNS.some(pattern => pattern.test(text));
 }
+/**
+ * Patterns that indicate an authentication failure — the agent is logged out,
+ * its token was revoked, or the session expired. These are the user-visible
+ * strings a logged-out agent surfaces (observed across the routine-run corpus).
+ * Unlike a rate limit, an auth failure is NOT self-healing by failover — every
+ * chain entry on the same account fails identically — so it is classified
+ * separately and never triggers a fallback attempt.
+ *
+ * The bare `401` is deliberately paired with an auth keyword: a plain "401" can
+ * appear in legitimate output (an HTTP-status table, a log line), so it only
+ * counts when it co-occurs with OAuth/authentication/credentials/Unauthorized.
+ */
+export const AUTH_FAILURE_PATTERNS = [
+    /OAuth (?:access token has been revoked|session expired)/i,
+    /(?:Please run|run) \/login/i,
+    /\bNot logged in\b/i,
+    /Invalid authentication credentials/i,
+    /Failed to authenticate/i,
+    /organization has (?:disabled|revoked) .*(?:subscription|access)/i,
+    /401\b[^\n]*(?:OAuth|authenticat|credential|Unauthorized)/i,
+];
+/**
+ * Return true if the text contains any known authentication-failure indicator.
+ * Agent-agnostic: matches the user-visible error string wherever it surfaces
+ * (stdout tail, a captured error message, a plain-text agent's output).
+ */
+export function detectAuthFailure(text) {
+    return AUTH_FAILURE_PATTERNS.some(pattern => pattern.test(text));
+}
+/**
+ * Return true if a stream-json log carries the structural markers of an auth
+ * failure. This is the authoritative signal for Claude: a logged-out run emits
+ *   {"type":"system","subtype":"api_retry","error":"authentication_failed",…}
+ *   {"type":"assistant",…,"error":"authentication_failed"}
+ *   {"type":"result","is_error":true,"result":"Failed to authenticate…"}
+ * Note `terminal_reason` is "completed" on such a run, so exit-code / terminal-
+ * reason logic can never catch it — the `error:"authentication_failed"` marker
+ * and the `result`+`is_error` text are the reliable signals.
+ *
+ * Gated on the Claude stream-json shape; other agents don't emit these fields,
+ * so callers pass their agent and this returns false for non-claude.
+ */
+export function detectAuthFailureEvent(logText, agent) {
+    if (agent !== 'claude')
+        return false;
+    const lines = logText.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed[0] !== '{')
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        if (parsed?.error === 'authentication_failed')
+            return true;
+        if (parsed?.type === 'result' &&
+            parsed?.is_error === true &&
+            typeof parsed?.result === 'string' &&
+            detectAuthFailure(parsed.result)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Return the first human-readable auth-failure phrase found in the text, for use
+ * as a stable, short run `errorMessage` reason. Falls back to null when the only
+ * signal was the structural `error:"authentication_failed"` marker with no
+ * user-visible string.
+ */
+export function authFailureReason(text) {
+    for (const pattern of AUTH_FAILURE_PATTERNS) {
+        const m = text.match(pattern);
+        if (m)
+            return m[0];
+    }
+    return null;
+}
+/**
+ * Decide whether a run's stream-json log is an authentication failure. The
+ * single source of truth for both the foreground and detached run paths.
+ *
+ * The structural marker (`detectAuthFailureEvent`, gated on `is_error:true`) is
+ * authoritative and safe on ANY exit — it catches a logged-out Claude that exits
+ * 0 (its `result` event carries `is_error:true` while `terminal_reason` is
+ * "completed"). The raw user-visible string (`detectAuthFailure`) is only
+ * consulted when the process actually FAILED, as a fallback for a run that died
+ * mid-stream before emitting a `result` event. That gate is what prevents a
+ * genuinely-completed run whose output merely *mentions* an auth phrase (e.g. a
+ * routine documenting a login flow) from being misclassified and having its
+ * legitimate report suppressed.
+ */
+export function isAuthFailureFromLog(logText, agent, opts) {
+    if (detectAuthFailureEvent(logText, agent))
+        return true;
+    if (opts.processFailed && detectAuthFailure(logText))
+        return true;
+    return false;
+}
 /**
  * Build the prompt handed to the fallback agent when the primary was stopped
  * mid-task by a rate limit.

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

@@ -0,0 +1,63 @@
+import { type ActivityEvent } 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;
+export interface FeedPostInput {
+    /** Human-readable progress text (required). Domain-agnostic free text. */
+    text: string;
+    /** Override session id (escape hatch for scripts/tests). Prefer auto-resolve. */
+    sessionId?: string;
+    /** Override activity root (tests). */
+    activityRoot?: string;
+    /** Override env for identity resolution (tests). */
+    env?: NodeJS.ProcessEnv;
+    /** Override cwd stamp (defaults to process.cwd() / env). */
+    cwd?: string;
+    /** Fixed timestamp (tests). */
+    ts?: string;
+    /**
+     * Starting pid for registry ancestor walk (defaults to process.ppid so the
+     * walk begins at the parent of this CLI process — usually the agent/shell).
+     * Tests inject a fake pid here.
+     */
+    startPid?: number;
+    /** Override parent-pid lookup (tests). */
+    getParentPid?: (pid: number) => number | undefined;
+    /** Override registry read (tests). */
+    readEntry?: (pid: number) => PidSessionEntry | undefined;
+    /** Override full registry list for launchId match (tests). */
+    listEntries?: () => PidSessionEntry[];
+}
+export interface FeedPostResult {
+    event: ActivityEvent;
+}
+export interface PostIdentity {
+    sessionId: string;
+    mailboxId: string;
+    host: string;
+    runtime: string;
+    agent?: string;
+    cwd?: string;
+    pid?: number;
+    launchId?: string;
+    terminalId?: string;
+    tmuxPane?: string;
+}
+/**
+ * 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
+ *  4. Walk parent PIDs from startPid (default process.ppid) through by-pid registry
+ */
+export declare function resolvePostIdentity(input: Pick<FeedPostInput, 'sessionId' | 'env' | 'cwd' | 'startPid' | 'getParentPid' | 'readEntry' | 'listEntries'>): PostIdentity | undefined;
+/** Walk up to 16 ancestors looking for a by-pid registry entry with a session. */
+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;
+export declare function normalizeStatusText(text: string): string;
+/**
+ * Append a `status.posted` milestone for the calling agent.
+ * Throws if text is empty or session identity cannot be resolved.
+ */
+export declare function postFeedStatus(input: FeedPostInput): FeedPostResult;