@phnx-labs/agents-cli 1.22.68 → 1.22.70

package/dist/commands/projects.js

@@ -35,16 +35,33 @@ export const PROJECTS_NO_FANOUT_ENV = 'AGENTS_PROJECTS_LOCAL';
 /** Max peers named in the skipped note before the rest collapse to `+N`. */
 const SKIPPED_NAME_LIMIT = 4;
 /**
- * Render `agents projects for-cwd`'s output for a resolved (or absent)
- * project name — `--json` always prints `{"name": ...}` even on no match, so
- * a scripted caller can distinguish "ran and found nothing" from a crash;
- * the plain-text form prints nothing on no match. Returns '' when nothing
- * should be printed.
+ * A path-shaped `agents projects view` argument — `.`, `..`, a `~`-prefixed
+ * value, or anything containing a path separator — means "auto-detect the
+ * project for this DIRECTORY", not "a project named literally this". A bare
+ * token (no separators) stays a project name, exactly as before.
  */
-export function formatForCwdOutput(name, json) {
-    if (json)
-        return JSON.stringify({ name: name ?? null });
-    return name ?? '';
+export function looksLikePath(token) {
+    return token === '.' || token === '..' || token.startsWith('~') || token.includes('/');
+}
+/**
+ * Best-effort cwd->project detection for `agents projects view <path>`. Delegates
+ * to the shared {@link projectNameForCwd} (def-root containment, longest wins),
+ * then reads the matched definition's Linear binding and root so ONE call yields
+ * the name AND the Linear projectId. Fail-open: an all-null shape when nothing
+ * contains the path — never throws, so a scripted caller stays unscoped rather
+ * than crashing. This subsumes the removed `agents projects for-cwd`.
+ */
+export function detectProjectForPath(cwd, defs) {
+    const name = projectNameForCwd(cwd, defs);
+    const def = name ? defs.find((d) => d.name === name) : undefined;
+    return {
+        name: name ?? null,
+        linear: {
+            name: def?.linear?.name ?? null,
+            projectId: def?.linear?.projectId ?? null,
+        },
+        root: def?.root ?? null,
+    };
 }
 /**
  * One compact trailing note for peers that didn't answer the `--fleet`
@@ -570,17 +587,6 @@ export function registerProjectsCommands(program) {
             console.log(`  ${chalk.bold(row.name.padEnd(w.name))} ${chalk.dim(row.path.padEnd(w.path))} ${chalk.cyan(row.repo.padEnd(w.repo))}${agentsSuffix}`);
         }
     });
-    // ---- for-cwd ----
-    projects
-        .command('for-cwd [cwd]')
-        .description('Resolve a directory to its defined project name (root or a repos[].path/subpath match). Defaults to the current directory.')
-        .option('--json', 'Machine-readable output: {"name": string | null}')
-        .action((cwdArg, opts) => {
-        const name = projectNameForCwd(cwdArg ?? process.cwd(), listProjectDefs());
-        const out = formatForCwdOutput(name, !!opts.json);
-        if (out)
-            console.log(out);
-    });
     // ---- add ----
     projects
         .command('add <name>')
@@ -763,15 +769,42 @@ export function registerProjectsCommands(program) {
             process.stdout.write(formatFleetSkippedNote(fleetSkipped));
     }
     projects
-        .command('status [name]')
+        .command('status [nameOrPath]')
         .alias('view')
-        .description('Progress card for every project across the whole fleet, or one named project (alias: view). Named form also prints every milestone and the stored definition.')
+        .description('Progress card for every project across the whole fleet, or one named project (alias: view). Named form also prints every milestone and the stored definition. A path argument (., .., a ~-prefixed value, a /-containing value, or --path) auto-detects the project that CONTAINS that directory.')
         .option('--json', 'Machine-readable output')
+        .option('--path [dir]', 'Treat the argument as a DIRECTORY and auto-detect the project that contains it (bare --path uses the cwd). With --json prints {name, linear:{name,projectId}, root}, all-null when nothing matches (fail-open, exit 0).')
         .option('--window <days>', 'Window for merged PRs, artifacts, and focus areas', '7')
         .option('--no-remote', 'Skip the GitHub and Linear lookups; faster, offline')
         .option('--device <name...>', 'Scope fleet status to one or more devices (repeatable)')
         .option('--devices <names>', 'Scope fleet status to a comma-separated list of devices')
         .action(async (name, rawOpts) => {
+        // Path mode: an explicit --path, or a path-shaped positional (., .., a
+        // ~-prefixed value, or a /-containing value) means "auto-detect the
+        // project for this DIRECTORY" rather than "a project named literally
+        // this". projectNameForCwd resolves the dir (expandLocalHome +
+        // path.resolve), so `.`, `~/…`, and relative paths all normalize. This
+        // subsumes the removed `agents projects for-cwd`.
+        let detectDir;
+        if (typeof rawOpts.path === 'string')
+            detectDir = rawOpts.path;
+        else if (rawOpts.path === true)
+            detectDir = process.cwd();
+        else if (name !== undefined && looksLikePath(name))
+            detectDir = name;
+        if (detectDir !== undefined) {
+            const detection = detectProjectForPath(detectDir, listProjectDefs());
+            if (rawOpts.json) {
+                console.log(JSON.stringify(detection));
+                return;
+            }
+            if (!detection.name) {
+                console.log(chalk.gray(`No defined project contains ${detectDir}`));
+                return;
+            }
+            // Non-JSON: fall through and render the full card for the detected project.
+            name = detection.name;
+        }
         // Named invocation = `view` depth (all milestones + definition). Unnamed
         // stays the scannable multi-project rollup. `view` is a commander alias
         // of this same command, so there is only one implementation.

package/dist/commands/rules.js

@@ -52,7 +52,7 @@ Project rules & @-imports:
   @path imports inside AGENTS.md/CLAUDE.md are resolved at session start by the agent
   itself, not by agents-cli. Support is per-agent:
     Inlined natively:  claude
-    Literal text:      codex, cursor, opencode, copilot, amp, kiro, goose
+    Literal text:      codex, cursor, opencode, copilot, amp, goose
 
   For rules that need to work across all agents, inline the content rather than using
   @-imports — the second group will load '@path/to/file.md' as a literal string.

package/dist/commands/send.js

@@ -2,7 +2,9 @@ import chalk from 'chalk';
 import { die } from '../lib/format.js';
 import { setHelpSections } from '../lib/help.js';
 import { readMeta } from '../lib/state.js';
-import { sendMessage } from '../lib/channels/send.js';
+import { sendMessage, isOwnerAlias } from '../lib/channels/send.js';
+import { ownerMessageComposer } from '../lib/owner-message.js';
+import { fireTraceSyncInBackground } from '../lib/run-trace-sync.js';
 function mergeAttachments(opts) {
     const list = [...(opts.attach ?? []), ...(opts.attachment ?? [])];
     return list.length ? list : undefined;
@@ -23,7 +25,34 @@ function toInput(positionalText, opts, ownerMode) {
 }
 async function runSend(positionalText, opts, ownerMode) {
     const meta = readMeta();
-    const out = await sendMessage(toInput(positionalText, opts, ownerMode), meta);
+    let input = toInput(positionalText, opts, ownerMode);
+    // An owner-bound ping (`agents notify`, `agents send --to owner`) goes through
+    // the SAME composer as an important `feed post` (PHNX-3698): short-shaped body,
+    // TEAM-N keys linkified, session crumb as a tappable console URL — instead of a
+    // raw dump. A non-owner send (explicit --channel/--to) is delivered verbatim.
+    let ownerCompose;
+    if (ownerMode || isOwnerAlias(opts.to)) {
+        const flagged = opts.text?.trim() ?? '';
+        const positional = (positionalText ?? '').trim();
+        const raw = flagged || positional;
+        // When both forms are given and disagree, leave it to sendMessage to fail
+        // loud with the "pass the message once" error rather than composing a guess.
+        const bothDiffer = flagged !== '' && positional !== '' && flagged !== positional;
+        if (raw && !bothDiffer) {
+            // Resolve the context once, then let each owner destination render its own
+            // format: the envelope carries the plain default (for --json and dry-run
+            // display), while ownerCompose hands sendToOwner the mrkdwn variant for a
+            // Slack owner destination and plain for iMessage (PHNX-3698).
+            ownerCompose = ownerMessageComposer(raw);
+            input = { ...input, text: ownerCompose('plain'), positionalText: undefined };
+            // The console URL in the composed body only resolves once this session's
+            // trace shard is uploaded; fire that now so the tapped link isn't a 404.
+            // A --dry-run resolves + composes but MUST NOT act (its documented contract),
+            // so it never spawns the sync — it just shows what would be sent.
+            fireTraceSyncInBackground({ disabled: Boolean(opts.dryRun) });
+        }
+    }
+    const out = await sendMessage(input, meta, ownerCompose);
     if ('error' in out) {
         die(out.error);
     }
@@ -127,6 +156,10 @@ export function registerSendCommand(program) {
       Set owner.channels + owner.policy.normal in humans.yaml once per fleet.
       Every channel listed in the normal policy receives an owner-addressed send.
 
+      Owner sends go through the same composer as "feed post": the body is
+      short-shaped, any TEAM-N key becomes a Linear URL, and the session crumb
+      becomes a tappable https://prix.dev/console/sessions/<id> link.
+
       ${SHARED_NOTES}
     `,
     });

package/dist/commands/sessions-inject.d.ts

@@ -13,5 +13,63 @@
  * `--pane`/`--pty` target a backend directly when the handle is already known.
  */
 import type { Command } from 'commander';
+import { type ActiveSession } from '../lib/session/active.js';
+interface InjectOptions {
+    pane?: string;
+    socket?: string;
+    pty?: string;
+    /**
+     * The remote device. A single `--device box` arrives here as `['box']` because
+     * the parent `sessions` command's variadic `-D, --device <target...>` shadows
+     * this subcommand's scalar option under `optsWithGlobals()` — normalize it with
+     * {@link normalizeInjectDevice} before use (PHNX-3688).
+     */
+    device?: string | string[];
+    enter?: boolean;
+    combined?: boolean;
+    json?: boolean;
+}
+/**
+ * Whether an active session is the one `sessions inject <token>` means. Matches
+ * a resolvable session id (exact or unique prefix) AND — for a tmux-hosted row
+ * whose full id never resolved (`sessionId` absent) — the `ag-<agent>-<shortid>`
+ * tmux name's `shortid` suffix (exact or prefix), the full tmux name, and the
+ * pane id. Those are the only selectors an id-less remote tmux row exposes, so
+ * without this an operator has no tool-native way to nudge it (PHNX-3688).
+ */
+export declare function matchInjectSelector(session: ActiveSession, token: string): boolean;
+/**
+ * The `--device` selector, normalized to a single host string. `optsWithGlobals()`
+ * merges the parent `sessions` command's variadic `-D, --device <target...>` over
+ * this subcommand's scalar `--device`, so a single `--device box` arrives as
+ * `['box']` — which flowed straight into `sshExec` and crashed on
+ * `host.startsWith` (PHNX-3688). Coerce the array to its one element; fail loud on
+ * several, since inject delivers to exactly one terminal (a fan-out spelling is a
+ * user error, not a first-of-list guess).
+ */
+export declare function normalizeInjectDevice(value: string | string[] | undefined): string | undefined;
+/**
+ * The `agents sessions inject` argv to re-run ON a device (its tmux panes live
+ * there, so resolution must happen there). Every flag rides along EXCEPT
+ * `--device`: the command runs on the device, resolving locally. Pure so the
+ * forwarded invocation is asserted without an SSH hop (PHNX-3688).
+ */
+export declare function buildRemoteInjectArgv(sessionId: string, text: string, options: InjectOptions): string[];
+/**
+ * Resolve `device` (registry alias or `user@host`) to an ssh target and re-run
+ * `agents sessions inject` there, so a bare session id + `--device` resolves on
+ * the box that actually holds the session's tmux panes. The tool-native form of
+ * the `agents ssh <device> "agents sessions inject <id> …"` workaround (PHNX-3688).
+ */
+/**
+ * Resolve `--device` to an ssh target. A registered device becomes its
+ * `user@dnsName`; a bare unknown name (an ad-hoc `user@host` or ssh_config alias)
+ * is handed to ssh verbatim (`resolveHost` returns null for it). A registered
+ * device we CANNOT dial — password-auth, addressless — throws its typed error and
+ * is NOT degraded to the raw name, which could ssh a coincidentally-matching but
+ * unrelated `~/.ssh/config` Host (PHNX-3688 review).
+ */
+export declare function resolveInjectSshTarget(device: string): Promise<string>;
 /** Attach the `inject` subcommand to an existing `sessions` command. */
 export declare function registerSessionsInjectCommand(sessionsCmd: Command): void;
+export {};

package/dist/commands/sessions-inject.js

@@ -13,14 +13,121 @@
  * `--pane`/`--pty` target a backend directly when the handle is already known.
  */
 import chalk from 'chalk';
-import { getActiveSessions } from '../lib/session/active.js';
+import { getActiveSessions, shortIdFromName } from '../lib/session/active.js';
 import { injectIntoTerminal, resolveInjectTargetForSession } from '../lib/terminal/index.js';
+import { sshExec, shellQuote } from '../lib/ssh-exec.js';
+import { resolveHost } from '../lib/hosts/registry.js';
+import { sshTargetFor } from '../lib/hosts/types.js';
 import { setHelpSections } from '../lib/help.js';
+/**
+ * Whether an active session is the one `sessions inject <token>` means. Matches
+ * a resolvable session id (exact or unique prefix) AND — for a tmux-hosted row
+ * whose full id never resolved (`sessionId` absent) — the `ag-<agent>-<shortid>`
+ * tmux name's `shortid` suffix (exact or prefix), the full tmux name, and the
+ * pane id. Those are the only selectors an id-less remote tmux row exposes, so
+ * without this an operator has no tool-native way to nudge it (PHNX-3688).
+ */
+export function matchInjectSelector(session, token) {
+    if (!token)
+        return false;
+    const sid = session.sessionId;
+    if (sid && (sid === token || sid.startsWith(token)))
+        return true;
+    const short = session.tmuxName ? shortIdFromName(session.tmuxName) : undefined;
+    if (short && (short === token || short.startsWith(token)))
+        return true;
+    if (session.tmuxName && session.tmuxName === token)
+        return true;
+    if (session.paneId && session.paneId === token)
+        return true;
+    return false;
+}
+/**
+ * The `--device` selector, normalized to a single host string. `optsWithGlobals()`
+ * merges the parent `sessions` command's variadic `-D, --device <target...>` over
+ * this subcommand's scalar `--device`, so a single `--device box` arrives as
+ * `['box']` — which flowed straight into `sshExec` and crashed on
+ * `host.startsWith` (PHNX-3688). Coerce the array to its one element; fail loud on
+ * several, since inject delivers to exactly one terminal (a fan-out spelling is a
+ * user error, not a first-of-list guess).
+ */
+export function normalizeInjectDevice(value) {
+    const list = value == null ? [] : Array.isArray(value) ? value : [value];
+    const hosts = list.map((v) => String(v).trim()).filter((v) => v.length > 0);
+    if (hosts.length === 0)
+        return undefined;
+    if (hosts.length > 1) {
+        throw new Error(`sessions inject targets a single device, but --device named ${hosts.length}: ${hosts.join(', ')}.`);
+    }
+    return hosts[0];
+}
+/**
+ * The `agents sessions inject` argv to re-run ON a device (its tmux panes live
+ * there, so resolution must happen there). Every flag rides along EXCEPT
+ * `--device`: the command runs on the device, resolving locally. Pure so the
+ * forwarded invocation is asserted without an SSH hop (PHNX-3688).
+ */
+export function buildRemoteInjectArgv(sessionId, text, options) {
+    const argv = ['agents', 'sessions', 'inject', sessionId, text];
+    if (options.enter === false)
+        argv.push('--no-enter');
+    if (options.combined)
+        argv.push('--combined');
+    if (options.socket)
+        argv.push('--socket', options.socket);
+    if (options.pty)
+        argv.push('--pty', options.pty);
+    if (options.pane)
+        argv.push('--pane', options.pane);
+    if (options.json)
+        argv.push('--json');
+    return argv;
+}
+/**
+ * Resolve `device` (registry alias or `user@host`) to an ssh target and re-run
+ * `agents sessions inject` there, so a bare session id + `--device` resolves on
+ * the box that actually holds the session's tmux panes. The tool-native form of
+ * the `agents ssh <device> "agents sessions inject <id> …"` workaround (PHNX-3688).
+ */
+/**
+ * Resolve `--device` to an ssh target. A registered device becomes its
+ * `user@dnsName`; a bare unknown name (an ad-hoc `user@host` or ssh_config alias)
+ * is handed to ssh verbatim (`resolveHost` returns null for it). A registered
+ * device we CANNOT dial — password-auth, addressless — throws its typed error and
+ * is NOT degraded to the raw name, which could ssh a coincidentally-matching but
+ * unrelated `~/.ssh/config` Host (PHNX-3688 review).
+ */
+export async function resolveInjectSshTarget(device) {
+    const host = await resolveHost(device);
+    return host ? sshTargetFor(host) : device;
+}
+async function injectOnDevice(sessionId, text, options, device) {
+    let target;
+    try {
+        target = await resolveInjectSshTarget(device);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (options.json)
+            console.log(JSON.stringify({ ok: false, error: message }));
+        else
+            console.error(chalk.red(message));
+        process.exit(1);
+    }
+    const remoteCmd = buildRemoteInjectArgv(sessionId, text, options).map(shellQuote).join(' ');
+    const res = sshExec(target, remoteCmd, { multiplex: true });
+    if (res.stdout)
+        process.stdout.write(res.stdout);
+    if (res.stderr)
+        process.stderr.write(res.stderr);
+    if (res.code !== 0)
+        process.exit(res.code ?? 1);
+}
 /** Resolve a session id (short or full) to an addressable terminal target, via the
  * same resolver the watchdog uses so both agree on what is reachable. */
 async function resolveTarget(sessionId) {
     const sessions = await getActiveSessions();
-    const match = sessions.find((s) => s.sessionId === sessionId || (s.sessionId != null && s.sessionId.startsWith(sessionId)));
+    const match = sessions.find((s) => matchInjectSelector(s, sessionId));
     if (!match)
         return { target: null, reason: `No active session matches "${sessionId}".` };
     const resolution = resolveInjectTargetForSession(match);
@@ -35,8 +142,21 @@ async function resolveTarget(sessionId) {
     return { target: resolution.target };
 }
 async function runInject(sessionId, text, options) {
+    let device;
+    try {
+        device = normalizeInjectDevice(options.device);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (options.json)
+            console.log(JSON.stringify({ ok: false, error: message }));
+        else
+            console.error(chalk.red(message));
+        process.exit(1);
+    }
     // Direct-target shortcuts skip the session lookup — the watchdog often already
-    // holds the pane id or pty session it wants to type into.
+    // holds the pane id or pty session it wants to type into. The pane's exact
+    // address is known, so it composes with --device (tmux send-keys over SSH).
     let target = null;
     if (options.pty) {
         target = { backend: 'pty', id: options.pty };
@@ -44,6 +164,12 @@ async function runInject(sessionId, text, options) {
     else if (options.pane) {
         target = { backend: 'tmux', pane: options.pane, socket: options.socket };
     }
+    else if (device) {
+        // A bare session id + a device: the session's tmux panes live ON that device,
+        // so getActiveSessions here can't see them. Resolve + deliver THERE by re-running
+        // inject over SSH (the same command, minus --device) — PHNX-3688.
+        return injectOnDevice(sessionId, text, options, device);
+    }
     else {
         const resolved = await resolveTarget(sessionId);
         if (!resolved.target) {
@@ -60,7 +186,7 @@ async function runInject(sessionId, text, options) {
         enter: options.enter !== false,
         combined: options.combined,
         socket: options.socket,
-        host: options.device,
+        host: device,
     });
     if (options.json) {
         console.log(JSON.stringify(res));
@@ -82,7 +208,7 @@ export function registerSessionsInjectCommand(sessionsCmd) {
         .option('--pane <id>', 'Target a tmux pane id directly (e.g. %3), skipping session lookup')
         .option('--pty <id>', 'Target an agents-pty session id directly, skipping session lookup')
         .option('--socket <path>', 'tmux socket path (defaults to the session/shared socket)')
-        .option('--device <target>', 'Deliver on a remote device over SSH (tmux/AppleScript backends)')
+        .option('--device <target>', 'Deliver on a remote device over SSH. With a bare session id, the session is resolved ON that device; with --pane, the pane is addressed there directly.')
         .option('--no-enter', 'Send only the text, without a trailing Enter')
         .option('--combined', 'Fuse text + Enter into ONE write (default: two writes, Ink-TUI safe)')
         .option('--json', 'Output the InjectResult as JSON');
@@ -96,6 +222,12 @@ export function registerSessionsInjectCommand(sessionsCmd) {
 
       # Type into an agents-pty session without submitting
       agents sessions inject _ "ls" --pty $SID --no-enter
+
+      # Nudge a live session on another box (resolved on the device)
+      agents sessions inject 214edaae "continue" --device yosemite-s0
+
+      # Address a known remote pane directly (skips lookup, sends over SSH)
+      agents sessions inject _ "continue" --pane %122 --socket $SOCK --device yosemite-s0
     `,
         notes: `
       - Ink-TUI Enter semantics: by default the text and Enter are two separate
@@ -103,8 +235,12 @@ export function registerSessionsInjectCommand(sessionsCmd) {
       - A session is addressable by id when it resolves to a precise split —
         tmux, iTerm, a VSCodium/Cursor/VS Code integrated terminal, or a pty
         (resolveInjectTargetForSession). Use --pane/--pty for direct targeting.
-      - Built on the Terminal Engine (src/lib/terminal): --device runs the tmux /
-        AppleScript spec over the same SSH transport the launch engine uses.
+      - The id may be the session id (short or full) OR the '<shortid>' suffix of
+        a tmux target (ag-<agent>-<shortid>) — the only selector a live tmux
+        session whose id column shows '-' exposes.
+      - Built on the Terminal Engine (src/lib/terminal): with --pane, --device
+        runs the tmux send-keys spec over SSH; with a bare id, --device re-runs
+        the lookup on that box (its tmux panes live there, not here).
     `,
     });
     // The parent `sessions` command also defines --json, so it binds there;

package/dist/commands/sessions-picker.js

@@ -104,6 +104,7 @@ function sanitizeMeta(s) {
         version: clean(s.version),
         account: clean(s.account),
         topic: clean(s.topic),
+        firstUserMessage: clean(s.firstUserMessage),
         label: clean(s.label),
         ticketId: clean(s.ticketId),
         prUrl: clean(s.prUrl),

package/dist/commands/share.js

@@ -11,11 +11,13 @@ import { Argument, Option } from 'commander';
 import chalk from 'chalk';
 import { DEFAULT_BUCKET_NAME, DEFAULT_CF_BUNDLE, DEFAULT_SHARE_DOMAIN, DEFAULT_WORKER_NAME, generateWriteToken, readCloudflareCreds, readShareConfig, readWriteToken, readWriteTokenEnv, readWriteTokenFromBundle, storeWriteToken, writeShareConfig, } from '../lib/share/config.js';
 import { addCustomDomain, configureBucketLifecycle, createBucket, deployWorker, enableWorkersDev, findZoneId, hashWorkerScript, putWorkerSecret, updateWorker, WORKER_PHOENIX_ID_BASE_SECRET, setWorkerSecret, } from '../lib/share/provision.js';
-import { publishFile, resolveShareUsername, parseMetaEntries, sanitizeLabel, resolveShareVisibility, scanShareContent, formatSensitiveContentError, unlistedNotPrivateWarning, SHARE_VISIBILITY_LEVELS, PUBLISH_VISIBILITY_LEVELS, } from '../lib/share/publish.js';
+import { publishFile, resolveShareUsername, parseMetaEntries, sanitizeLabel, scanShareContent, formatSensitiveContentError, unlistedNotPrivateWarning, SHARE_VISIBILITY_LEVELS, PUBLISH_VISIBILITY_LEVELS, } from '../lib/share/publish.js';
 import { deleteShare, resolveDeleteTarget } from '../lib/share/delete.js';
 import { renderWorkerBundle } from '../lib/share/worker-template.js';
 import { analyticsEnabled } from '../lib/share/analytics.js';
-import { phoenixIdBaseForDeploy, resolveShareBackend, } from '../lib/share/backend.js';
+import { extractShareHttpError, formatShareHttpErrorDetail } from '../lib/share/http-error.js';
+import { phoenixIdBaseForDeploy, resolveShareBackend, shouldUseManaged, } from '../lib/share/backend.js';
+import { publishVisibility } from '../lib/storage/visibility.js';
 import { resolveGitHubUsername } from '../lib/git.js';
 import { setHelpSections } from '../lib/help.js';
 import { showUrl } from '../lib/open-url.js';
@@ -245,7 +247,8 @@ export async function runShareList(opts = {}) {
         throw new Error(OUTDATED_TEMPLATE_HINT);
     }
     if (res.status !== 200) {
-        throw new Error(`Listing failed (${res.status}) for ${listUrl}. Check the endpoint is reachable, or that 'agents artifacts setup' / 'agents auth login' completed.`);
+        const detail = formatShareHttpErrorDetail(extractShareHttpError({ status: res.status, body: res.body }));
+        throw new Error(`Listing failed (${res.status}) for ${listUrl}${detail}. Check the endpoint is reachable, or that 'agents artifacts setup' / 'agents auth login' completed.`);
     }
     if (!/application\/json/i.test(res.contentType)) {
         // A 200 that isn't JSON means the old Worker ignored ?format=json and served
@@ -389,7 +392,8 @@ export async function runShareRevisions(target, opts = {}) {
     const fetchListing = opts.fetchListing ?? defaultListingFetch;
     const res = await fetchListing(revUrl);
     if (res.status !== 200) {
-        throw new Error(`Revisions lookup failed (${res.status}) for ${revUrl}. Check the endpoint is reachable, or that 'agents artifacts setup' / 'agents auth login' completed.`);
+        const detail = formatShareHttpErrorDetail(extractShareHttpError({ status: res.status, body: res.body }));
+        throw new Error(`Revisions lookup failed (${res.status}) for ${revUrl}${detail}. Check the endpoint is reachable, or that 'agents artifacts setup' / 'agents auth login' completed.`);
     }
     if (!/application\/json/i.test(res.contentType)) {
         if (backend.kind === 'managed') {
@@ -624,9 +628,8 @@ export function registerShareCommands(artifactsCmd) {
         .option('--slug <slug>', 'URL slug override (default: stable slug of the artifact title, then filename)')
         .option('--github-user <user>', 'GitHub username for the share namespace (default: resolved from gh/git config; ignored on the managed endpoint)')
         .option('--expire <spec>', "auto-expire (default 30d). e.g. 12h, 30d, 2026-08-01, or 'never'")
-        .addOption(new Option('--visibility <level>', 'public | unlisted | private | me | org (default public). unlisted is an UNAUTHENTICATED capability URL; private is token-gated (404 without the key); me/org require a Phoenix session. All but public are hidden from the gallery')
-        .choices([...PUBLISH_VISIBILITY_LEVELS])
-        .default('public'))
+        .addOption(new Option('--visibility <level>', 'public | unlisted | private | me | org. Default when signed in: me (owner-only, Phoenix-gated); use org for your whole email domain, public to opt into the gallery. unlisted is an UNAUTHENTICATED capability URL; private is token-gated (404 without the key). All but public are hidden from the gallery')
+        .choices([...PUBLISH_VISIBILITY_LEVELS]))
         .addOption(new Option('--protected', 'token-gated link (= --visibility private): the URL carries a secret key and returns 404 without it — the authenticated alternative to --unlisted'))
         .addOption(new Option('--unlisted', 'hidden alias of --visibility unlisted (obscurity, NOT authentication)').hideHelp())
         .addOption(new Option('--private', 'hidden alias of --visibility unlisted (obscurity, NOT authentication — for real read-auth use --protected)').hideHelp())
@@ -650,11 +653,16 @@ export function registerShareCommands(artifactsCmd) {
         }
         try {
             const meta = parseMetaEntries(opts.meta);
-            const visibility = resolveShareVisibility({
+            // Private by default: an explicit flag wins; otherwise the backend-aware
+            // product default — `me` (owner-only) when signed in to Phoenix, `public`
+            // for a BYO bucket (the Worker refuses `me`/`org` without a Phoenix owner).
+            // `shouldUseManaged` reads the same session/BYO signals `publishFile` will
+            // resolve, so the default matches the backend the publish actually uses.
+            const visibility = publishVisibility({
                 visibility: opts.visibility,
                 unlisted: opts.unlisted === true || opts.private === true,
                 protected: opts.protected === true,
-            });
+            }, shouldUseManaged({}) ? 'managed' : 'byo');
             // unlisted (incl. its --private alias) is obscurity, not read-auth — warn
             // loudly before the publish so a "private" link is never mistaken for a
             // gated one (PHNX-3654). Skipped for --json so machine output stays clean.
@@ -684,15 +692,25 @@ export function registerShareCommands(artifactsCmd) {
     });
     setHelpSections(shareCmd, {
         examples: `
-      # Signed in? Just publish — no Cloudflare setup (managed endpoint)
+      # Signed in? Just publish — no Cloudflare setup (managed endpoint).
+      # Default is private: an owner-only 'me' link, Phoenix-gated.
       agents auth login
       agents artifacts share ./out/plan.html
 
+      # Share with everyone at your email domain (no org setup — the domain is it)
+      agents artifacts share ./out/plan.html --visibility org
+
+      # Opt into the public gallery with an OG preview card
+      agents artifacts share ./out/landing.html --visibility public
+
       # Hide from the public gallery (direct URL still works, noindex) and expire sooner
       agents artifacts share ./out/report.html --visibility unlisted --expire 12h
 
+      # Token-gated link — GET returns 404 without the secret ?k= key
+      agents artifacts share ./out/secret.html --protected
+
       # Permanent public page (the slug is derived from its title)
-      agents artifacts share ./out/landing.html --expire never
+      agents artifacts share ./out/landing.html --visibility public --expire never
 
       # Optional slug override
       agents artifacts share ./out/report.html --slug q3-report --expire 7d
@@ -720,11 +738,21 @@ ${SHARE_DELETE_EXAMPLES}
   applies (setup / join). HTML is stored as one object: local images are inlined
   and Chrome-saved file:// TOC links become in-page hashes.
 
+  Private by default: signed in, a publish with no --visibility is 'me' —
+  owner-only, Phoenix-gated, not in the gallery. Pass --visibility org to share
+  with everyone at your email domain (no org to create — the domain is the whole
+  mechanism), or --visibility public to opt into the gallery with an OG card. A
+  BYO publish (no Phoenix session) still defaults to public, since me/org need a
+  Phoenix owner to gate on.
+
   Default expiry is 30d so an accidental publish decays. Pass --expire never for
   a permanent link. --visibility unlisted (hidden aliases: --unlisted / --private)
   hides the page from the public gallery and agents artifacts share list; the
   direct URL is still world-readable (unlisted, not secret) and GET sends
-  X-Robots-Tag: noindex. --visibility me requires a Phoenix session and is only
+  X-Robots-Tag: noindex. --protected (= --visibility private) is token-gated
+  read-auth: the published URL carries a secret ?k= key (Authorization: Bearer
+  is accepted too) and GET returns 404 without it — treat the whole link as a
+  secret. --visibility me requires a Phoenix session and is only
   visible to the signed-in owner; --visibility org requires the same and is
   visible to members of the same Phoenix organization. A pre-publish scan
   refuses emails and credential-shaped strings unless --force is passed.
@@ -956,7 +984,7 @@ Prefer to change visibility without a browser? Use 'agents artifacts share visib
         .addOption(new Option('--scope <level>', 'visibility filter: public (default), unlisted, private, me, org, or all')
         .choices(['public', 'unlisted', 'private', 'me', 'org', 'all'])
         .default('public'))
-        .option('--all', "list every page including hidden unlisted/me/org shares (alias for --scope all)")
+        .option('--all', "list every page including hidden unlisted/private/me/org shares (alias for --scope all)")
         .option('--agent <name>', 'filter to shares published by this agent/harness (case-insensitive)')
         .option('--session <id>', 'filter to shares published from this session id')
         // Named --label-contains, not --label: `share <file>` (the parent) already owns
@@ -988,10 +1016,11 @@ Prefer to change visibility without a browser? Use 'agents artifacts share visib
       # Everything you've published, newest first
       agents artifacts share list
 
-      # Include your hidden pages (unlisted / me / org) so you can see everything
+      # Include your hidden pages (unlisted / private / me / org) so you can see everything
       agents artifacts share list --all
       agents artifacts share list --scope me
       agents artifacts share list --scope unlisted
+      agents artifacts share list --scope private
 
       # Machine-readable — e.g. pull every still-public URL with jq
       agents artifacts share list --list-json | jq -r '.objects[].url'