@phnx-labs/agents-cli 1.20.93 → 1.21.1

package/dist/lib/events.d.ts

@@ -11,7 +11,7 @@
  * - Permissions: logs dir is 0700, files are 0600 (owner-only)
  * - Performance tracking: withTiming() wrapper for any async function
  */
-import { type ActorKind } from './actor.js';
+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.unlocked' | 'secrets.create' | 'secrets.import' | 'secrets.export' | 'secrets.view' | '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' | 'webhook.received' | 'webhook.authorized' | 'webhook.rejected' | 'webhook.matched' | 'webhook.fired' | 'webhook.handler.start' | 'webhook.handler.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' | 'factory.command' | 'factory.action' | 'factory.uri' | 'factory.launch' | 'friction' | 'error' | 'warn' | 'info' | 'debug';
 /** Every known event kind. Derived from {@link EVENT_TYPE_TABLE}, never hand-listed. */
@@ -46,7 +46,7 @@ export interface EventMeta {
     /** Resolved actor id — which human/agent is behind this event (RUSH-2020). */
     actor?: string;
     /** Actor kind (`human`/`agent`). */
-    kind?: ActorKind;
+    kind?: ActorKind | 'unknown';
 }
 export interface EventPayload {
     agent?: string;

package/dist/lib/events.js

@@ -16,11 +16,9 @@ import * as path from 'path';
 import * as os from 'os';
 import { createHash } from 'node:crypto';
 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';
-import { machineId } from './machine-id.js';
+import { stampProvenance, resetEventProvenanceForTest } from './event-provenance.js';
 /** Lazy perf warehouse write — avoids a hard cycle at module load. */
 function recordPerfTiming(payload) {
     try {
@@ -329,51 +327,7 @@ export function detectCaller(env = process.env, stdoutIsTTY = Boolean(process.st
     }
     return { kind: stdoutIsTTY ? 'terminal' : 'script' };
 }
-/**
- * Who is running this process and from where. Derived once per process from the
- * OS user and $SSH_CONNECTION (via the same parser the sessions layer uses), then
- * cached — provenance can't change mid-process, so every emit() pays for it once.
- */
-let _origin;
-function auditOrigin() {
-    if (_origin)
-        return _origin;
-    let osUser = 'unknown';
-    try {
-        osUser = os.userInfo().username;
-    }
-    catch {
-        // 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;
-}
-/** This machine's normalized device id, resolved once — it can't change mid-process. */
-let _machineId;
-function cachedMachineId() {
-    return (_machineId ??= machineId());
-}
-function resolveProvenance(env = process.env) {
-    const p = {};
-    const sessionId = env.AGENT_SESSION_ID || env.AGENTS_SESSION_ID;
-    if (sessionId)
-        p.sessionId = sessionId;
-    if (env.AGENTS_AGENT_NAME)
-        p.agent = env.AGENTS_AGENT_NAME;
-    if (env.AGENT_LAUNCH_ID)
-        p.launchId = env.AGENT_LAUNCH_ID;
-    if (env.AGENTS_PARENT_SESSION_ID)
-        p.parentSessionId = env.AGENTS_PARENT_SESSION_ID;
-    return p;
-}
+// ─── Audit attribution ────────────────────────────────────────────────────────
 // ─── Core API ─────────────────────────────────────────────────────────────────
 /**
  * Emit a structured event to the append-only audit log.
@@ -396,13 +350,12 @@ export function emit(event, payload = {}, overrides = {}) {
         const safePayload = sanitizePayload(payload);
         const record = {
             // Provenance floor first: env-sourced defaults an explicit payload overrides.
-            ...resolveProvenance(),
+            ...stampProvenance(),
             ...safePayload,
             ts: overrides.ts ?? new Date().toISOString(),
             tz: getTimezoneOffset(),
             tzName: getTimezoneName(),
             hostname: os.hostname(),
-            machineId: cachedMachineId(),
             platform: os.platform(),
             arch: os.arch(),
             pid: process.pid,
@@ -411,7 +364,6 @@ export function emit(event, payload = {}, overrides = {}) {
             level: levelFor(event),
             caller: caller.kind,
             ...(caller.session ? { session: caller.session } : {}),
-            ...auditOrigin(),
         };
         const line = JSON.stringify(record) + '\n';
         const logPath = eventsPath();
@@ -919,8 +871,7 @@ export function getLogsPath() {
 }
 export function _resetForTest(overrideEventsPath) {
     _eventsPath = overrideEventsPath;
-    _origin = undefined;
-    _machineId = undefined;
+    resetEventProvenanceForTest();
     _chmoddedPath = undefined;
     lastRotationCheck = 0;
 }

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

@@ -16,7 +16,9 @@ export interface FeedSinkConfig {
 export type FeedBroadcastConfig = Record<string, FeedSinkConfig>;
 /** Everything a template may interpolate. Absent values skip templates that need them. */
 export interface FeedBroadcastContext {
-    /** The post text, verbatim. */
+    /** Short subject line (~4–5 words). Phone line 1. */
+    title?: string;
+    /** The post body, verbatim. Phone line after the blank line. */
     text: string;
     level: FeedPostLevel;
     /** Tracker id for the work, e.g. `RUSH-2081`. */
@@ -63,6 +65,8 @@ export declare function blockBroadcastContext(block: {
 }, extras?: {
     project?: string;
     agent?: string;
+    title?: string;
+    body?: string;
 }): FeedBroadcastContext;
 /**
  * Why a declared block reached nobody, or undefined when it got through.
@@ -87,10 +91,42 @@ export interface SinkOutcome {
     error?: string;
 }
 /**
- * A human-facing one-liner for a messaging sink: what project, what happened,
- * and the link to go read more. Leading with the project is deliberate — a
- * message that opens with an agent name tells the reader nothing about which of
- * their projects just moved.
+ * Short host label for a phone line — strip user@ and domain so
+ * `muqsit@mac-mini.tailnet.ts.net` reads as `mac-mini`.
+ */
+export declare function shortHost(host: string | undefined): string | undefined;
+/** First 8 hex chars of a session id for the footer (readable, not a full uuid). */
+export declare function shortSessionChunk(session: string | undefined): string | undefined;
+/**
+ * Scrub em/en dashes from outbound phone copy (house rule + iMessage readability).
+ * Collapses whitespace; does not invent meaning.
+ */
+export declare function scrubOutboundDashes(text: string): string;
+/**
+ * Footer like "Sent from my iPhone" — who posted, a session crumb, which box.
+ *
+ *   Sent from grok/a02da0e2 on mac-mini
+ *
+ * Agent name first; session chunk for disambiguation when many groks run;
+ * host last. Skip the uninformative default label `agent`.
+ */
+export declare function composeBroadcastFooter(ctx: FeedBroadcastContext): string | undefined;
+/**
+ * Human-facing body for a messaging sink (`{message}`).
+ *
+ * ```
+ * Title in a few words
+ *
+ * Body of what happened or the ask.
+ *
+ * Sent from grok/a02da0e2 on mac-mini
+ * agents focus a02da0e2          (blocks only)
+ * https://…                      (optional attach URL)
+ * ```
+ *
+ * Title first (scannable subject). Blank line. Body. Footer provenance so a
+ * fleet of agents is attributable without crowding the ask. Prefer `{message}`
+ * over bare `{text}` in messaging sinks.
  */
 export declare function composeBroadcastMessage(ctx: FeedBroadcastContext): string;
 /**

package/dist/lib/feed-broadcast.js

@@ -50,8 +50,12 @@ export function parseFeedPostLevel(raw) {
 export function blockBroadcastContext(block, extras = {}) {
     const ask = block.questions?.[0]?.text?.trim() || 'agent is blocked';
     const links = [block.pr].filter((l) => !!l && /^https?:\/\//i.test(l));
+    // Prefer explicit title/body from the feed post; fall back to the ask as body.
+    const title = extras.title?.trim() || undefined;
+    const text = extras.body?.trim() || ask;
     return {
-        text: ask,
+        ...(title ? { title } : {}),
+        text,
         level: 'important',
         ticket: block.ticket,
         project: extras.project,
@@ -92,24 +96,118 @@ export function blockDeliveryFailure(blocked, outcomes) {
 }
 const PLACEHOLDER = /\{([a-z]+)\}/g;
 /**
- * A human-facing one-liner for a messaging sink: what project, what happened,
- * and the link to go read more. Leading with the project is deliberate — a
- * message that opens with an agent name tells the reader nothing about which of
- * their projects just moved.
+ * Short host label for a phone line — strip user@ and domain so
+ * `muqsit@mac-mini.tailnet.ts.net` reads as `mac-mini`.
+ */
+export function shortHost(host) {
+    if (!host?.trim())
+        return undefined;
+    let h = host.trim();
+    const at = h.lastIndexOf('@');
+    if (at !== -1)
+        h = h.slice(at + 1);
+    const dot = h.indexOf('.');
+    if (dot > 0)
+        h = h.slice(0, dot);
+    return h || undefined;
+}
+/** First 8 hex chars of a session id for the footer (readable, not a full uuid). */
+export function shortSessionChunk(session) {
+    if (!session?.trim())
+        return undefined;
+    const hex = session.replace(/-/g, '').toLowerCase();
+    const chunk = hex.replace(/[^a-f0-9]/g, '').slice(0, 8);
+    return chunk || undefined;
+}
+/**
+ * Scrub em/en dashes from outbound phone copy (house rule + iMessage readability).
+ * Collapses whitespace; does not invent meaning.
+ */
+export function scrubOutboundDashes(text) {
+    return text
+        .replace(/\u2014/g, ' - ')
+        .replace(/\u2013/g, ' - ')
+        .replace(/[ \t]+\n/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .replace(/[ \t]{2,}/g, ' ')
+        .trim();
+}
+/**
+ * Footer like "Sent from my iPhone" — who posted, a session crumb, which box.
+ *
+ *   Sent from grok/a02da0e2 on mac-mini
+ *
+ * Agent name first; session chunk for disambiguation when many groks run;
+ * host last. Skip the uninformative default label `agent`.
+ */
+export function composeBroadcastFooter(ctx) {
+    const agent = ctx.agent?.trim();
+    const agentLabel = agent && agent !== 'agent' ? agent : undefined;
+    const session = shortSessionChunk(ctx.session);
+    const host = shortHost(ctx.host);
+    let who;
+    if (agentLabel && session)
+        who = `${agentLabel}/${session}`;
+    else if (agentLabel)
+        who = agentLabel;
+    else if (session)
+        who = session;
+    if (who && host)
+        return `Sent from ${who} on ${host}`;
+    if (who)
+        return `Sent from ${who}`;
+    if (host)
+        return `Sent from host ${host}`;
+    return undefined;
+}
+/**
+ * Human-facing body for a messaging sink (`{message}`).
+ *
+ * ```
+ * Title in a few words
+ *
+ * Body of what happened or the ask.
+ *
+ * Sent from grok/a02da0e2 on mac-mini
+ * agents focus a02da0e2          (blocks only)
+ * https://…                      (optional attach URL)
+ * ```
+ *
+ * Title first (scannable subject). Blank line. Body. Footer provenance so a
+ * fleet of agents is attributable without crowding the ask. Prefer `{message}`
+ * over bare `{text}` in messaging sinks.
  */
 export function composeBroadcastMessage(ctx) {
-    const head = ctx.project ? `${ctx.project} · ${ctx.text}` : ctx.text;
+    const title = scrubOutboundDashes(ctx.title ?? '');
+    const body = scrubOutboundDashes(ctx.text ?? '');
+    // Title preferred; if an older post has no title, body alone still sends.
+    const head = title || body;
+    const mid = title && body && title !== body ? body : undefined;
+    const footer = composeBroadcastFooter(ctx);
     const link = ctx.links?.find((l) => /^https?:\/\//i.test(l));
-    // A block's second line is the command that unblocks it. The operator reading
-    // this on a phone should not have to go find the session — the one action they
-    // must take travels with the ask. A status post has no such action, so it keeps
-    // the link there instead.
-    const tail = [ctx.focus, link].filter(Boolean);
-    return tail.length ? `${head}\n${tail.join('\n')}` : head;
+    // Block focus and link trail after the "Sent from" footer so the human
+    // sentence stays at the top and the action/link are still one glance away.
+    const trail = [footer, ctx.focus, link].filter(Boolean);
+    const parts = [];
+    if (head)
+        parts.push(head);
+    if (mid) {
+        // Blank line between subject and body (title, then space, then message).
+        parts.push('');
+        parts.push(mid);
+    }
+    if (trail.length) {
+        // Blank line before the footer block (iPhone "Sent from my iPhone" spacing).
+        if (parts.length)
+            parts.push('');
+        parts.push(trail.join('\n'));
+    }
+    return parts.join('\n').trim();
 }
 /** The values a template may reference, resolved once per post. */
 function templateVars(ctx) {
     return {
+        title: ctx.title,
         text: ctx.text,
         ticket: ctx.ticket,
         project: ctx.project,

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

@@ -2,8 +2,15 @@ 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;
+/** Title is a phone subject line - about four or five words, not a paragraph. */
+export declare const STATUS_TITLE_MAX_CHARS = 60;
 export interface FeedPostInput {
-    /** Human-readable progress text (required). Domain-agnostic free text. */
+    /**
+     * Short subject (required for new posts). ~4–5 words. Phone broadcasts put
+     * this on the first line so a scan names the topic before the body.
+     */
+    title: string;
+    /** Body text (required). Domain-agnostic free text — what happened / the ask. */
     text: string;
     /** Override session id (escape hatch for scripts/tests). Prefer auto-resolve. */
     sessionId?: string;
@@ -92,9 +99,16 @@ export declare function buildAttachments(tokens: string[] | undefined, ctx: {
     sessionId: string;
     updateId: string;
 }): Attachment[];
+/**
+ * Collapse whitespace and strip em/en dashes (house rule: no em-dashes in
+ * agent-authored outbound copy — phones and plain text render them poorly).
+ */
+export declare function scrubDashes(text: string): string;
 export declare function normalizeStatusText(text: string): string;
+/** Normalize a short subject line for a post. */
+export declare function normalizeStatusTitle(title: string): string;
 /**
  * Append a `status.posted` milestone for the calling agent.
- * Throws if text is empty or session identity cannot be resolved.
+ * Throws if title/text is empty or session identity cannot be resolved.
  */
 export declare function postFeedStatus(input: FeedPostInput): FeedPostResult;

package/dist/lib/feed-post.js

@@ -1,13 +1,14 @@
 /**
  * Agent status posts — deliberate progress messages into the activity stream.
  *
- * Surface: `agents feed post <text>` (agent-callable; humans watch via
- * `agents feed` / `agents activity` / `agents events --module activity`).
+ * Surface: `agents feed post --title <subject> <body>` (agent-callable; humans
+ * watch via `agents feed` / `agents activity` / `agents events --module activity`).
  *
  * Identity is automatic: session id, agent, cwd, launch/pid/tmux provenance
  * are resolved from the process environment and the per-pid launch registry
- * (`lib/session/pid-registry.ts`). The agent only authors free-form text —
- * no domain-specific flags (tickets, URLs, tracks).
+ * (`lib/session/pid-registry.ts`). The agent authors a short title + body —
+ * no domain-specific flags (tickets, URLs, tracks). Phone `{message}` ends with
+ * a "Sent from agent/session on host" footer.
  *
  * Storage: append-only activity log as a `status.posted` milestone. Does NOT
  * open a feed block (blocks remain "needs you" state only).
@@ -23,6 +24,8 @@ import { isValidMailboxId } from './mailbox.js';
 import { listPidSessionEntries, readPidSessionEntry, } from './session/pid-registry.js';
 /** Soft cap so a runaway agent can't flood the activity lane with essays. */
 export const STATUS_POST_MAX_CHARS = 500;
+/** Title is a phone subject line - about four or five words, not a paragraph. */
+export const STATUS_TITLE_MAX_CHARS = 60;
 /**
  * Resolve who is posting. Order:
  *  1. Explicit --session flag
@@ -241,22 +244,46 @@ export function buildAttachments(tokens, ctx) {
     }
     return out;
 }
+/**
+ * Collapse whitespace and strip em/en dashes (house rule: no em-dashes in
+ * agent-authored outbound copy — phones and plain text render them poorly).
+ */
+export function scrubDashes(text) {
+    return text
+        .replace(/\u2014/g, ' - ') // em dash —
+        .replace(/\u2013/g, ' - ') // en dash –
+        .replace(/\s+/g, ' ')
+        .trim();
+}
 export function normalizeStatusText(text) {
-    const collapsed = text.replace(/\s+/g, ' ').trim();
+    const collapsed = scrubDashes(text);
     if (!collapsed)
         return '';
     if (collapsed.length <= STATUS_POST_MAX_CHARS)
         return collapsed;
     return `${collapsed.slice(0, STATUS_POST_MAX_CHARS - 1)}…`;
 }
+/** Normalize a short subject line for a post. */
+export function normalizeStatusTitle(title) {
+    const collapsed = scrubDashes(title);
+    if (!collapsed)
+        return '';
+    if (collapsed.length <= STATUS_TITLE_MAX_CHARS)
+        return collapsed;
+    return `${collapsed.slice(0, STATUS_TITLE_MAX_CHARS - 1)}…`;
+}
 /**
  * Append a `status.posted` milestone for the calling agent.
- * Throws if text is empty or session identity cannot be resolved.
+ * Throws if title/text is empty or session identity cannot be resolved.
  */
 export function postFeedStatus(input) {
+    const title = normalizeStatusTitle(input.title ?? '');
     const detail = normalizeStatusText(input.text);
+    if (!title) {
+        throw new Error('Title is empty. Usage: agents feed post --title "Short subject" "what just happened"');
+    }
     if (!detail) {
-        throw new Error('Status text is empty. Usage: agents feed post "what just happened"');
+        throw new Error('Status text is empty. Usage: agents feed post --title "Short subject" "what just happened"');
     }
     const identity = resolvePostIdentity(input);
     if (!identity) {
@@ -285,6 +312,7 @@ export function postFeedStatus(input) {
         cwd: identity.cwd,
         agent: identity.agent,
         tool: 'feed.post',
+        title,
         detail,
         ...(project ? { project } : {}),
         ...(identity.pid !== undefined ? { pid: identity.pid } : {}),

package/dist/lib/feed.d.ts

@@ -12,7 +12,7 @@ export interface MessageReceipt {
     /** The message id this receipt describes. */
     msgId: string;
     /** Delivery lifecycle state. */
-    status: 'queued' | 'consumed' | 'continued';
+    status: 'queued' | 'consumed' | 'continued' | 'dropped' | 'expired';
     /** ISO-8601 timestamp of the state transition. */
     at: string;
     /** Optional sender label for the message. */

package/dist/lib/feed.js

@@ -153,6 +153,8 @@ const RECEIPT_STATUS_RANK = {
     queued: 0,
     consumed: 1,
     continued: 2,
+    dropped: 3,
+    expired: 3,
 };
 /**
  * Record a delivery-receipt transition for a message tied to a block.
@@ -253,7 +255,7 @@ export function clearBlockLifecycle(blockId, root) {
 export function buildDeclaredBlock(agent, input) {
     const text = input.text.trim().replace(/\s+/g, ' ');
     if (!text) {
-        throw new Error('Block text is empty. Usage: agents feed post "what you need from the user" --blocked');
+        throw new Error('Block text is empty. Usage: agents feed post --title "Short subject" "what you need from the user" --blocked');
     }
     const options = (input.options ?? [])
         .map((label) => label.trim())

package/dist/lib/git.d.ts

@@ -41,8 +41,12 @@ export declare function assertValidBranchName(branch: string): void;
  *
  * Prefer this over `git.push(remote, branch)` whenever the branch comes from
  * repo state rather than a hard-coded literal.
+ *
+ * Pass `targetBranch` to push the local `branch` to a differently-named remote
+ * branch (`git push origin <branch>:<targetBranch>`) — used when publishing the
+ * working tree to a branch other than the checked-out one.
  */
-export declare function pushOrigin(git: SimpleGit, branch: string): Promise<void>;
+export declare function pushOrigin(git: SimpleGit, branch: string, targetBranch?: string): Promise<void>;
 /** Parsed representation of a git source string (GitHub, generic URL, or local path). */
 export interface GitSource {
     type: 'github' | 'url' | 'local';
@@ -124,6 +128,8 @@ export declare function resolveGitHubUsername(): Promise<string | null>;
  * Get the remote URL for origin in a git repo.
  */
 export declare function getRemoteUrl(repoPath: string): Promise<string | null>;
+/** The repo's checked-out branch, or 'main' on a detached HEAD / read failure. */
+export declare function getCurrentBranch(repoPath: string): Promise<string>;
 /**
  * Canonical `host/owner/repo` form of a git remote, transport-agnostic, so the
  * same repo cloned over SSH vs HTTPS compares equal. Strips protocol, any
@@ -158,8 +164,13 @@ export type CommitAndPushResult = {
  * Clean tree + local ahead of origin still pushes — "nothing to commit" is not
  * "nothing to push". Reports "already up to date" only when `ahead === 0` and
  * there is nothing to commit.
+ *
+ * `targetBranch` pushes the working tree to a differently-named remote branch
+ * (`<current>:<targetBranch>`) and is reported back as the result `branch`, so
+ * callers that print a branch-scoped URL reference where the commit actually
+ * landed — not the checked-out branch.
  */
-export declare function commitAndPush(repoPath: string, message: string): Promise<CommitAndPushResult>;
+export declare function commitAndPush(repoPath: string, message: string, targetBranch?: string): Promise<CommitAndPushResult>;
 /**
  * Check if repo has uncommitted changes.
  */

package/dist/lib/git.js

@@ -77,9 +77,18 @@ export function assertValidBranchName(branch) {
  *
  * Prefer this over `git.push(remote, branch)` whenever the branch comes from
  * repo state rather than a hard-coded literal.
+ *
+ * Pass `targetBranch` to push the local `branch` to a differently-named remote
+ * branch (`git push origin <branch>:<targetBranch>`) — used when publishing the
+ * working tree to a branch other than the checked-out one.
  */
-export async function pushOrigin(git, branch) {
+export async function pushOrigin(git, branch, targetBranch) {
     assertValidBranchName(branch);
+    if (targetBranch && targetBranch !== branch) {
+        assertValidBranchName(targetBranch);
+        await git.raw(['push', '--', 'origin', `${branch}:${targetBranch}`]);
+        return;
+    }
     await git.raw(['push', '--', 'origin', branch]);
 }
 /**
@@ -435,6 +444,16 @@ export async function getRemoteUrl(repoPath) {
         return null;
     }
 }
+/** The repo's checked-out branch, or 'main' on a detached HEAD / read failure. */
+export async function getCurrentBranch(repoPath) {
+    try {
+        const status = await simpleGit(repoPath).status();
+        return status.current || 'main';
+    }
+    catch {
+        return 'main';
+    }
+}
 /**
  * Canonical `host/owner/repo` form of a git remote, transport-agnostic, so the
  * same repo cloned over SSH vs HTTPS compares equal. Strips protocol, any
@@ -494,13 +513,23 @@ export async function checkGitHubRepoExists(owner, repo) {
  * Clean tree + local ahead of origin still pushes — "nothing to commit" is not
  * "nothing to push". Reports "already up to date" only when `ahead === 0` and
  * there is nothing to commit.
+ *
+ * `targetBranch` pushes the working tree to a differently-named remote branch
+ * (`<current>:<targetBranch>`) and is reported back as the result `branch`, so
+ * callers that print a branch-scoped URL reference where the commit actually
+ * landed — not the checked-out branch.
  */
-export async function commitAndPush(repoPath, message) {
+export async function commitAndPush(repoPath, message, targetBranch) {
     try {
         const git = simpleGit(repoPath);
         let status = await git.status();
         const branch = status.current || 'main';
         assertValidBranchName(branch);
+        if (targetBranch)
+            assertValidBranchName(targetBranch);
+        // The branch the commit ends up on remotely — the checked-out branch unless
+        // an explicit target was requested.
+        const pushedBranch = targetBranch || branch;
         let committed = false;
         if (status.files.length > 0) {
             await git.add('-A');
@@ -509,7 +538,10 @@ export async function commitAndPush(repoPath, message) {
             status = await git.status();
         }
         const ahead = status.ahead ?? 0;
-        if (!committed && ahead === 0) {
+        // A same-branch push short-circuits when there is nothing new; a push to a
+        // different target branch must still run even from a clean, non-ahead tree,
+        // since the target may not carry these commits yet.
+        if (!committed && ahead === 0 && pushedBranch === branch) {
             return {
                 success: true,
                 detail: 'already up to date',
@@ -521,12 +553,12 @@ export async function commitAndPush(repoPath, message) {
         // Capture remote tip before push for a real ref range in the detail string.
         let before = '';
         try {
-            before = (await git.raw(['rev-parse', '--short=8', `origin/${branch}`])).trim();
+            before = (await git.raw(['rev-parse', '--short=8', `origin/${pushedBranch}`])).trim();
         }
         catch {
             /* origin/<branch> may not exist yet (first push) */
         }
-        await pushOrigin(git, branch);
+        await pushOrigin(git, branch, targetBranch);
         let after = '';
         try {
             after = (await git.raw(['rev-parse', '--short=8', 'HEAD'])).trim();
@@ -547,7 +579,7 @@ export async function commitAndPush(repoPath, message) {
         return {
             success: true,
             detail,
-            branch,
+            branch: pushedBranch,
             committed,
             pushed: true,
         };

package/dist/lib/hooks.d.ts

@@ -198,6 +198,19 @@ export declare function installHooksCentrally(source: string): Promise<{
  * User dir takes priority; deduplication preserves first occurrence.
  */
 export declare function listCentralHooks(): HookEntry[];
+/**
+ * Normalize a hook `timeout` from agents.yaml into a whole number of seconds.
+ *
+ * A bare number stays seconds (`timeout: 30` → 30) for backward compatibility.
+ * A Go-style duration string is parsed into seconds: `5s`, `2m`, `1h30m`,
+ * `90s`, `1h`. This intentionally does NOT reuse {@link parseTimeout} from
+ * routines.ts — that one returns milliseconds, has no seconds (`s`) unit, and
+ * floors at one minute, none of which fit hook timeouts (typically 5–600s).
+ *
+ * Returns the seconds value, or `null` when the input is not a positive number
+ * or a parseable duration string — the caller decides how to surface that.
+ */
+export declare function normalizeHookTimeoutSeconds(value: unknown): number | null;
 /**
  * Parse hook manifests. Reads system hooks from ~/.agents/.system/hooks.yaml
  * (npm-shipped defaults) and user hooks from the `hooks:` section of
@@ -205,7 +218,9 @@ export declare function listCentralHooks(): HookEntry[];
  * A user entry with `enabled: false` disables the system-shipped hook of
  * the same name without forking the system file.
  *
- * Hooks marked `enabled: false` are dropped from the returned map.
+ * Hooks marked `enabled: false` are dropped from the returned map. A hook
+ * `timeout` written as a duration string (`5s`, `2m`) is normalized to a
+ * seconds number here, so every downstream serializer keeps reading a number.
  */
 export declare function parseHookManifest(opts?: {
     warn?: boolean;