@phnx-labs/agents-cli 1.20.93 → 1.21.0

package/dist/lib/device-config.js

@@ -0,0 +1,296 @@
+/**
+ * Device/user config keys — typed read/write over the two-tier agents.yaml store.
+ *
+ * One registry (`CONFIG_KEYS`) maps each CLI dotted name to where it lives:
+ *   - user scope   → central `~/.agents/agents.yaml` under `config:` (syncs
+ *                    fleet-wide via `agents repo push/pull`)
+ *   - device scope → `~/.agents/devices/<host>/agents.yaml` under `config:`
+ *                    (per-machine; mirrors how `defaultBrowserProfile` is routed)
+ *
+ * This machine's keys go through the readMeta/updateMeta funnel (state.ts) so the
+ * partition/overlay logic stays the single writer. Another device's doc is
+ * read/written in place — the devices/ tree syncs via the DotAgents repo, so
+ * editing `devices/mac-mini/agents.yaml` locally is how `configure`/`note`
+ * target a peer (`--device`-style).
+ *
+ * `browser.profile` is NOT a `config:` key — it is the existing
+ * `Meta.defaultBrowserProfile` field; the registry entry documents the mapping
+ * and set/get route to it so there is one source of truth (no duplicate key).
+ *
+ * Unset always means today's behavior.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+import { META_HEADER, getUserAgentsDir, readMeta, updateMeta } from './state.js';
+import { atomicWriteFileSync } from './fs-atomic.js';
+import { machineId } from './machine-id.js';
+import { assertValidDeviceName } from './devices/registry.js';
+export const CONFIG_KEYS = [
+    {
+        name: 'interactive.host',
+        yamlKey: 'interactiveHost',
+        scope: 'user',
+        type: 'string',
+        description: 'Device that shows the user artifacts (browser opens, dashboards) — the "online macOS box" skills should use instead of guessing.',
+        validate: (v) => {
+            try {
+                assertValidDeviceName(v);
+                return null;
+            }
+            catch (err) {
+                return err?.message ?? String(err);
+            }
+        },
+    },
+    {
+        name: 'browser.profile',
+        yamlKey: 'defaultBrowserProfile',
+        scope: 'device',
+        type: 'string',
+        field: 'defaultBrowserProfile',
+        description: 'Browser profile `agents browser start` resolves to without --profile (set via `agents browser profiles set-default`).',
+    },
+    {
+        name: 'agents.max-concurrent',
+        yamlKey: 'maxAgents',
+        scope: 'device',
+        type: 'int',
+        description: 'Cap on concurrent agents on this device. What counts toward it depends on the consumer: ' +
+            'Factory auto-launch counts device-wide running agents; teams placement counts the team’s own roster on the device.',
+        validate: (v) => (v >= 1 ? null : 'agents.max-concurrent must be >= 1.'),
+    },
+    {
+        name: 'scheduler.enabled',
+        yamlKey: 'schedulerEnabled',
+        scope: 'device',
+        type: 'bool',
+        description: 'Whether the routines scheduler (daemon) may fire on this device.',
+    },
+    {
+        name: 'notes',
+        yamlKey: 'notes',
+        scope: 'device',
+        type: 'string-list',
+        description: 'Free-form operator notes about this device (one entry per `agents devices note`).',
+    },
+];
+/** Look up a key spec by CLI dotted name, or throw listing the known keys. */
+export function configKeySpec(name) {
+    const spec = CONFIG_KEYS.find((k) => k.name === name);
+    if (!spec) {
+        throw new Error(`Unknown config key '${name}'. Known keys: ${CONFIG_KEYS.map((k) => k.name).join(', ')}.`);
+    }
+    return spec;
+}
+/** Throw when `value` does not match the key's declared type or validation. */
+function assertValidValue(spec, value) {
+    switch (spec.type) {
+        case 'string':
+            if (typeof value !== 'string' || value.length === 0) {
+                throw new Error(`Config key '${spec.name}' expects a non-empty string, got ${JSON.stringify(value)}.`);
+            }
+            break;
+        case 'int':
+            if (!Number.isInteger(value)) {
+                throw new Error(`Config key '${spec.name}' expects an integer, got ${JSON.stringify(value)}.`);
+            }
+            break;
+        case 'bool':
+            if (typeof value !== 'boolean') {
+                throw new Error(`Config key '${spec.name}' expects a boolean, got ${JSON.stringify(value)}.`);
+            }
+            break;
+        case 'string-list':
+            if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+                throw new Error(`Config key '${spec.name}' expects a list of strings, got ${JSON.stringify(value)}.`);
+            }
+            break;
+    }
+    const err = spec.validate?.(value);
+    if (err)
+        throw new Error(`Invalid value for '${spec.name}': ${err}`);
+}
+// ─── Sibling-device doc access ────────────────────────────────────────────────
+/** Path to any device's doc (self or a peer) under the synced devices/ tree. */
+function deviceDocPath(device) {
+    return path.join(getUserAgentsDir(), 'devices', device, 'agents.yaml');
+}
+/**
+ * Read a device doc directly. Returns null when the file does not exist. A
+ * malformed file is a hard error — silently returning null would let the next
+ * write wipe the device's pins/default (same contract as the device registry).
+ * A valid-but-non-map document (a bare string, a list) is the same kind of
+ * corruption: reject it here instead of failing later with a TypeError.
+ */
+function readDeviceDoc(device) {
+    const p = deviceDocPath(device);
+    let raw;
+    try {
+        raw = fs.readFileSync(p, 'utf-8');
+    }
+    catch (err) {
+        if (err && err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    const corrupted = (detail) => new Error(`Device config corrupted at ${p}: ${detail}. Inspect and restore from backup.`);
+    let parsed;
+    try {
+        parsed = yaml.parse(raw);
+    }
+    catch (err) {
+        throw corrupted(err?.message ?? String(err));
+    }
+    if (parsed === null || parsed === undefined)
+        return {};
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw corrupted(`expected a YAML map, got ${Array.isArray(parsed) ? 'a list' : JSON.stringify(parsed)}`);
+    }
+    return parsed;
+}
+/** Write a device doc in place (atomic). Only ever holds device-local fields. */
+function writeDeviceDoc(device, doc) {
+    const p = deviceDocPath(device);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const body = Object.keys(doc).length > 0 ? doc : { agents: {} };
+    atomicWriteFileSync(p, META_HEADER + yaml.stringify(body));
+}
+// ─── Reads ────────────────────────────────────────────────────────────────────
+function entryFromMeta(spec, meta) {
+    if (spec.field === 'defaultBrowserProfile') {
+        const value = meta.defaultBrowserProfile;
+        return { spec, value, layer: value !== undefined ? 'device' : undefined };
+    }
+    if (spec.scope === 'user') {
+        const value = meta.config?.[spec.yamlKey];
+        return { spec, value, layer: value !== undefined ? 'user' : undefined };
+    }
+    const value = meta.deviceConfig?.[spec.yamlKey];
+    return { spec, value, layer: value !== undefined ? 'device' : undefined };
+}
+/** True when `device` names this machine (case-insensitive, mirroring
+ * `isLocalDevice` in teams/scheduler.ts) — `configure ZION` on host zion must
+ * take the self path (readMeta/updateMeta funnel), not the peer-doc path. */
+function isSelfDevice(device) {
+    return device.toLowerCase() === machineId();
+}
+/** Get one config key's value and the layer that set it. */
+export function getConfigValue(name, opts) {
+    const spec = configKeySpec(name);
+    if (spec.scope === 'device' && opts?.device && !isSelfDevice(opts.device)) {
+        const doc = readDeviceDoc(opts.device) ?? {};
+        return entryFromMeta(spec, { deviceConfig: doc.config, defaultBrowserProfile: doc.defaultBrowserProfile });
+    }
+    return entryFromMeta(spec, readMeta());
+}
+/** List every known key with its value and the layer that set it. */
+export function listConfig(opts) {
+    return CONFIG_KEYS.map((spec) => getConfigValue(spec.name, opts));
+}
+// ─── Writes ───────────────────────────────────────────────────────────────────
+function setInMeta(spec, value) {
+    updateMeta((m) => {
+        if (spec.field === 'defaultBrowserProfile') {
+            return { ...m, defaultBrowserProfile: value };
+        }
+        if (spec.scope === 'user') {
+            return { ...m, config: { ...m.config, [spec.yamlKey]: value } };
+        }
+        return { ...m, deviceConfig: { ...m.deviceConfig, [spec.yamlKey]: value } };
+    });
+}
+function unsetInMeta(spec) {
+    updateMeta((m) => {
+        if (spec.field === 'defaultBrowserProfile') {
+            const { defaultBrowserProfile, ...rest } = m;
+            void defaultBrowserProfile;
+            return rest;
+        }
+        const block = spec.scope === 'user' ? m.config : m.deviceConfig;
+        if (!block || !(spec.yamlKey in block))
+            return m;
+        const next = { ...block };
+        delete next[spec.yamlKey];
+        const cleaned = Object.keys(next).length > 0 ? next : undefined;
+        return spec.scope === 'user' ? { ...m, config: cleaned } : { ...m, deviceConfig: cleaned };
+    });
+}
+function setInDeviceDoc(device, spec, value) {
+    const doc = readDeviceDoc(device) ?? {};
+    if (spec.field === 'defaultBrowserProfile') {
+        doc.defaultBrowserProfile = value;
+    }
+    else {
+        doc.config = { ...doc.config, [spec.yamlKey]: value };
+    }
+    writeDeviceDoc(device, doc);
+}
+function unsetInDeviceDoc(device, spec) {
+    const doc = readDeviceDoc(device);
+    if (!doc)
+        return; // nothing stored — unset is a no-op
+    if (spec.field === 'defaultBrowserProfile') {
+        delete doc.defaultBrowserProfile;
+    }
+    else if (doc.config && spec.yamlKey in doc.config) {
+        delete doc.config[spec.yamlKey];
+        if (Object.keys(doc.config).length === 0)
+            delete doc.config;
+    }
+    else {
+        return; // key not present — no write needed
+    }
+    writeDeviceDoc(device, doc);
+}
+/** Set a config key (validated). Device-scope keys target this machine unless `opts.device` names a peer. */
+export function setConfigValue(name, value, opts) {
+    const spec = configKeySpec(name);
+    assertValidValue(spec, value);
+    if (spec.scope === 'device' && opts?.device && !isSelfDevice(opts.device)) {
+        setInDeviceDoc(opts.device, spec, value);
+        return;
+    }
+    setInMeta(spec, value);
+}
+/** Unset a config key — restores default behavior. No-op when already unset. */
+export function unsetConfigValue(name, opts) {
+    const spec = configKeySpec(name);
+    if (spec.scope === 'device' && opts?.device && !isSelfDevice(opts.device)) {
+        unsetInDeviceDoc(opts.device, spec);
+        return;
+    }
+    unsetInMeta(spec);
+}
+// ─── Consumers' helpers ───────────────────────────────────────────────────────
+/** True unless this machine's device doc disables the routines scheduler. */
+export function isSchedulerEnabled() {
+    return getConfigValue('scheduler.enabled').value !== false;
+}
+/**
+ * Throw when the routines scheduler is disabled on this machine, naming the
+ * setting and the fix. The single message every scheduler-start surface
+ * (auto-start on `routines add`, manual `routines start`, the daemon's own
+ * scheduler init) refuses with.
+ */
+export function assertSchedulerEnabled() {
+    if (isSchedulerEnabled())
+        return;
+    throw new Error(`The routines scheduler is disabled on this device (scheduler.enabled=false in ~/.agents/devices/${machineId()}/agents.yaml). ` +
+        `Re-enable with: agents devices configure ${machineId()} --scheduler on`);
+}
+/**
+ * Read the `agents.max-concurrent` cap for each named device from its synced
+ * device doc (no SSH). Devices without a cap are omitted — uncapped is the
+ * default. Used as an input to host ranking (teams placement, Factory
+ * auto-launch), never as a remote probe.
+ */
+export function readMaxConcurrentCaps(devices) {
+    const caps = {};
+    for (const device of devices) {
+        const value = getConfigValue('agents.max-concurrent', { device }).value;
+        if (typeof value === 'number')
+            caps[device] = value;
+    }
+    return caps;
+}

package/dist/lib/event-provenance.d.ts

@@ -0,0 +1,19 @@
+import { type ActorKind } from './actor.js';
+export interface EventProvenance {
+    osUser: string;
+    transport: 'local' | 'ssh';
+    sshClientIp?: string;
+    actor: string;
+    kind: ActorKind;
+    machineId: string;
+    sessionId?: string;
+    agent?: string;
+    launchId?: string;
+    parentSessionId?: string;
+}
+/**
+ * Stamp the shared identity floor used by both operational and activity events.
+ * Explicit event payload fields may override these defaults at the call site.
+ */
+export declare function stampProvenance(env?: NodeJS.ProcessEnv): EventProvenance;
+export declare function resetEventProvenanceForTest(): void;

package/dist/lib/event-provenance.js

@@ -0,0 +1,48 @@
+import * as os from 'os';
+import { resolveActor } from './actor.js';
+import { machineId } from './machine-id.js';
+import { parseSshConnection } from './session/provenance.js';
+let cachedOrigin;
+let cachedDeviceId;
+/**
+ * Stamp the shared identity floor used by both operational and activity events.
+ * Explicit event payload fields may override these defaults at the call site.
+ */
+export function stampProvenance(env = process.env) {
+    if (!cachedOrigin) {
+        let osUser = 'unknown';
+        try {
+            osUser = os.userInfo().username;
+        }
+        catch {
+            // A uid without a passwd entry has no attributable OS user.
+        }
+        const ssh = env.SSH_CONNECTION ? parseSshConnection(env.SSH_CONNECTION) : undefined;
+        const actor = resolveActor();
+        cachedOrigin = {
+            osUser,
+            transport: ssh ? 'ssh' : 'local',
+            ...(ssh ? { sshClientIp: ssh.clientIp } : {}),
+            actor: actor.id,
+            kind: actor.kind,
+        };
+    }
+    const provenance = {
+        ...cachedOrigin,
+        machineId: (cachedDeviceId ??= machineId()),
+    };
+    const sessionId = env.AGENT_SESSION_ID || env.AGENTS_SESSION_ID;
+    if (sessionId)
+        provenance.sessionId = sessionId;
+    if (env.AGENTS_AGENT_NAME)
+        provenance.agent = env.AGENTS_AGENT_NAME;
+    if (env.AGENT_LAUNCH_ID)
+        provenance.launchId = env.AGENT_LAUNCH_ID;
+    if (env.AGENTS_PARENT_SESSION_ID)
+        provenance.parentSessionId = env.AGENTS_PARENT_SESSION_ID;
+    return provenance;
+}
+export function resetEventProvenanceForTest() {
+    cachedOrigin = undefined;
+    cachedDeviceId = undefined;
+}

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.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.

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,
         };