@phnx-labs/agents-cli 1.22.107 → 1.22.110

package/dist/lib/session/title.js

@@ -0,0 +1,312 @@
+/**
+ * Daemon-generated session TITLES (PHNX-3797).
+ *
+ * The headline on a session row answers "what is this session about?", so it has
+ * to be anchored in what the USER asked for. It used to be the agent's latest
+ * transcript line — verbose, rolling, and unrecognizable to the person who
+ * started the run. The fix is a two-rung answer:
+ *
+ *  1. INSTANT, free: the user's own first message (already in the index) is the
+ *     honest fallback shown from the moment the session appears.
+ *  2. UPGRADED, once: this module asks a CHEAP model (via a swappable
+ *     {@link SessionTitleProvider}; the default {@link CloudSessionTitleProvider}
+ *     uses the `cheap` tier — haiku on Claude — through the same
+ *     `agents run --model <tier>` resolution every other call uses) for a short
+ *     ACTION + OBJECT headline of what the session is doing, and persists it in
+ *     the session index.
+ *
+ * Generation happens ONCE per session, in the daemon, and is keyed by
+ * {@link sessionTitleSourceKey} — a hash of the user text the title was derived
+ * from — so a sweep that sees a stored key matching the row's current text skips
+ * it (the cache hit) and regenerates only when that first user message actually
+ * changed, or when an operator asks explicitly
+ * (`agents sessions backfill titles --refresh`). There is no per-tick model call
+ * and no per-client generation: the daemon writes one value, every consumer
+ * (local list, picker, `sessions watch --json`, the fleet mirror, AGI EXT) reads
+ * it off the row.
+ *
+ * Everything here except {@link runSessionTitleTick} is pure, and the tick takes
+ * an injectable runner seam, so the whole path is testable without spawning a
+ * harness.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * The phrase every generated-title prompt carries. Load-bearing twice over:
+ * `traces/sync.ts` classifies a session whose topic matches it as internal
+ * `utility` plumbing rather than agent work, and {@link isSessionTitlePrompt}
+ * uses it to keep the titler from titling its OWN spawned sessions — which
+ * would otherwise be a runaway loop, since each generation creates one more
+ * untitled session.
+ *
+ * It is a STABLE sentinel, not the human-readable instruction: keep it exact and
+ * keep `traces/sync.ts`'s matching regex in sync when it changes. The surrounding
+ * prompt (see {@link renderSessionTitlePrompt}) asks for an action+object headline
+ * of 4–8 words; the sentinel deliberately carries no word budget so the two never
+ * drift.
+ */
+export const SESSION_TITLE_PROMPT_MARKER = 'Generate a concise session headline';
+/** Hard ceiling on a stored title; the prompt asks for far less. */
+export const SESSION_TITLE_MAX_CHARS = 60;
+/** Hard ceiling on words kept from a model reply that ignored the word budget. */
+export const SESSION_TITLE_MAX_WORDS = 8;
+/** How much user text the prompt carries — enough to be specific, bounded for cost. */
+export const SESSION_TITLE_INPUT_MAX_CHARS = 2000;
+/** How many sessions one periodic sweep may generate for. */
+export const SESSION_TITLE_MAX_PER_TICK = 2;
+/** How many recent rows a sweep inspects before picking that batch. */
+export const SESSION_TITLE_CANDIDATE_SCAN = 200;
+/** Only sessions active within this window are titled — older rows are not shown. */
+export const SESSION_TITLE_MAX_AGE_MS = 14 * 24 * 60 * 60_000;
+/** Per-generation subprocess ceiling. A title is not worth waiting on. */
+export const SESSION_TITLE_TIMEOUT_MS = 45_000;
+/** The harnesses the titler will run as, best first. The first installed one wins. */
+export const SESSION_TITLE_AGENTS = ['claude', 'codex', 'grok', 'kimi', 'opencode'];
+/** The user text itself — the ONLY thing the source key is computed over. */
+export function sessionTitleSourceText(input) {
+    const raw = (input.firstUserMessage || input.topic || '').replace(/\s+/g, ' ').trim();
+    return raw.length > SESSION_TITLE_INPUT_MAX_CHARS ? raw.slice(0, SESSION_TITLE_INPUT_MAX_CHARS) : raw;
+}
+/**
+ * Stable identity of the text a title was generated from. Storing this beside
+ * the title is what makes "already titled" distinguishable from "the user's
+ * first message changed" without keeping a second copy of that text.
+ * Empty text yields `null`: there is nothing to title.
+ */
+export function sessionTitleSourceKey(input) {
+    const text = sessionTitleSourceText(input);
+    if (!text)
+        return null;
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+/**
+ * True when this text is one of the titler's OWN prompts. The titler runs a real
+ * harness, which writes a real transcript, which lands in the index as another
+ * untitled session — so without this guard every title generated would create
+ * work for the next sweep, forever.
+ */
+export function isSessionTitlePrompt(...values) {
+    return values.some((v) => typeof v === 'string' && v.includes(SESSION_TITLE_PROMPT_MARKER));
+}
+/**
+ * The one-shot prompt handed to the cheap model.
+ *
+ * It asks for a descriptive ACTION + OBJECT headline (a verb phrase naming the
+ * concrete task, "Triage the AGI board", "Rename browser profile — default
+ * confusion"), not a single terse noun ("Triage") and not a full sentence — the
+ * headline slot has to tell the person who started the run what the session is
+ * doing at a glance. The word budget is soft in the prompt and hard-enforced by
+ * {@link sanitizeGeneratedTitle}'s {@link SESSION_TITLE_MAX_WORDS} ceiling.
+ */
+export function renderSessionTitlePrompt(input) {
+    const text = sessionTitleSourceText(input);
+    const context = [
+        input.project ? `Repository: ${input.project}` : null,
+        input.ticketId ? `Ticket: ${input.ticketId}` : null,
+        input.gitBranch ? `Branch: ${input.gitBranch}` : null,
+    ].filter(Boolean);
+    return [
+        `${SESSION_TITLE_PROMPT_MARKER} naming what this coding session is working on.`,
+        'Write an ACTION + OBJECT headline of 4 to 8 words — a verb phrase naming the concrete task,',
+        'e.g. "Triage the AGI board" or "Rename browser profile — default confusion".',
+        'NOT a single noun, NOT a full sentence. Name the concrete feature, component, or fix —',
+        'not the person, not the pleasantries.',
+        'Respond IMMEDIATELY with only the headline. Do NOT investigate, do NOT read files, do NOT use any tools.',
+        'No quotes, no trailing punctuation, no explanation.',
+        ...(context.length ? ['', ...context] : []),
+        '',
+        "The user's request:",
+        '---',
+        text,
+        '---',
+    ].join('\n');
+}
+/**
+ * Reduce a model reply to a storable title, or `undefined` when it produced
+ * nothing usable. Takes the first non-empty line (a chatty model puts the title
+ * first), strips wrapping quotes/backticks and trailing punctuation, and applies
+ * the word + character ceilings. A reply that is really a refusal or an
+ * explanation fails the ceilings and is dropped rather than shown.
+ */
+export function sanitizeGeneratedTitle(raw) {
+    if (!raw)
+        return undefined;
+    const firstLine = raw.split('\n').map((l) => l.trim()).find((l) => l.length > 0);
+    if (!firstLine)
+        return undefined;
+    let title = firstLine
+        .replace(/^["'`*_\s]+/, '')
+        .replace(/["'`*_\s]+$/, '')
+        .replace(/[.!?,;:]+$/, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    if (!title)
+        return undefined;
+    // A model that ignored the budget gets truncated, not shown in full — a
+    // paragraph in the headline slot is the very failure this feature removes.
+    const words = title.split(' ');
+    if (words.length > SESSION_TITLE_MAX_WORDS)
+        title = words.slice(0, SESSION_TITLE_MAX_WORDS).join(' ');
+    if (title.length > SESSION_TITLE_MAX_CHARS)
+        title = title.slice(0, SESSION_TITLE_MAX_CHARS).trimEnd();
+    // Never store the prompt back as a title (a harness that echoed its input).
+    if (isSessionTitlePrompt(title))
+        return undefined;
+    return title || undefined;
+}
+/**
+ * The headline for an INDEXED session row, on the same ladder the live path uses
+ * (`deriveSessionRecap`, active.ts): `/rename` label → daemon-generated title →
+ * first-prompt topic. Every `agents sessions` surface that shows "what this
+ * session is" reads it from here, so the CLI and the watch stream can never
+ * disagree about a session's name (PHNX-3797).
+ *
+ * A caller whose row type does not carry `generatedTitle` fails to compile
+ * (see {@link CarriesTitleRung}) — fix the projection to carry the field rather
+ * than casting past this.
+ */
+export function sessionHeadline(row) {
+    return row.label || row.generatedTitle || row.topic || undefined;
+}
+/** The harness the titler runs as on this box, or null when none is installed. */
+export async function resolveSessionTitleAgent() {
+    // Lazy import: this module is also imported by render paths that must not pull
+    // the installation store (and its filesystem probes) into a hot listing.
+    const { listInstalledVersions } = await import('../installations/store.js');
+    for (const agent of SESSION_TITLE_AGENTS) {
+        try {
+            if (listInstalledVersions(agent).length > 0)
+                return agent;
+        }
+        catch {
+            // An unreadable store for one agent must not hide the others.
+        }
+    }
+    return null;
+}
+/**
+ * The real runner: ONE `agents run <agent> --mode plan --model cheap <prompt>`
+ * subprocess. `--mode plan` keeps it read-only (it must never touch a repo), and
+ * `--model cheap` goes through the same tier resolution every other run uses, so
+ * the box's own catalog picks haiku (or its per-harness equivalent) rather than
+ * this module hardcoding a model id that ages out.
+ */
+export async function defaultSessionTitleRunner(prompt, signal) {
+    const [{ getAgentsInvocation }, { execFile }, { promisify }] = await Promise.all([
+        import('../daemon/daemon.js'),
+        import('node:child_process'),
+        import('node:util'),
+    ]);
+    const agent = await resolveSessionTitleAgent();
+    if (!agent)
+        throw new Error('no installed harness can generate a session title');
+    const inv = getAgentsInvocation(['run', agent, '--mode', 'plan', '--model', 'cheap', prompt]);
+    const { stdout } = await promisify(execFile)(inv.command, inv.args, {
+        encoding: 'utf8',
+        maxBuffer: 1024 * 1024,
+        timeout: SESSION_TITLE_TIMEOUT_MS,
+        signal,
+    });
+    return stdout;
+}
+/**
+ * The default, shipped provider: render the shared prompt and run it through a
+ * {@link SessionTitleRunner} — by default {@link defaultSessionTitleRunner}, the
+ * one cheap `agents run --model cheap` subprocess. Tests inject a fake runner (or
+ * a whole fake provider) to exercise the tick without spawning a harness.
+ */
+export class CloudSessionTitleProvider {
+    runner;
+    name = 'cloud';
+    constructor(runner = defaultSessionTitleRunner) {
+        this.runner = runner;
+    }
+    generate(input, signal) {
+        return this.runner(renderSessionTitlePrompt(input), signal);
+    }
+}
+/** The provider used when a caller injects neither a `provider` nor a `run`. */
+export function defaultSessionTitleProvider() {
+    return new CloudSessionTitleProvider();
+}
+/**
+ * Decide what one sweep should do, without touching the model. Pure over its
+ * inputs so the "generate once, then cache-hit" property is directly testable:
+ * a candidate is work only when its user text yields a key AND that key differs
+ * from the one stored beside its title (or `force`).
+ */
+export function selectSessionsNeedingTitle(rows, opts = { limit: SESSION_TITLE_MAX_PER_TICK }) {
+    const pending = [];
+    let cached = 0;
+    for (const row of rows) {
+        // The titler's own runs are sessions too; titling them would spawn another.
+        if (isSessionTitlePrompt(row.firstUserMessage, row.topic))
+            continue;
+        const sourceKey = sessionTitleSourceKey(row);
+        if (!sourceKey)
+            continue;
+        if (!opts.force && row.generatedTitle && row.generatedTitleKey === sourceKey) {
+            cached++;
+            continue;
+        }
+        if (pending.length < opts.limit)
+            pending.push({ row, sourceKey });
+    }
+    return { pending, cached };
+}
+/**
+ * One titling sweep: pick the sessions whose headline is still the raw user
+ * message, generate a title for at most {@link SessionTitleTickOptions.limit} of
+ * them, and persist each. Best-effort by contract — a failed generation leaves
+ * the row untitled, which the ladder renders as the user's own first message.
+ *
+ * Throws only for an explicit {@link SessionTitleTickOptions.id} that matches no
+ * indexed session (a caller error); the periodic sweep never throws.
+ */
+export async function runSessionTitleTick(options = {}) {
+    const limit = options.limit ?? SESSION_TITLE_MAX_PER_TICK;
+    const now = options.nowMs ?? Date.now();
+    const result = { scanned: 0, cached: 0, generated: 0, failed: 0, titles: [] };
+    const { querySessionTitleCandidates, setSessionGeneratedTitle } = await import('./db.js');
+    const rows = querySessionTitleCandidates(options.id ? 1 : SESSION_TITLE_CANDIDATE_SCAN, options.id
+        ? { id: options.id }
+        : { sinceMs: now - (options.maxAgeMs ?? SESSION_TITLE_MAX_AGE_MS) });
+    result.scanned = rows.length;
+    // An explicitly requested session that has no indexed row is a caller error,
+    // not a quiet sweep outcome: reporting "0 generated" would read as "already
+    // current" for an id that was simply mistyped or not scanned yet.
+    if (options.id && rows.length === 0) {
+        throw new Error(`no indexed session matches "${options.id}" on this machine — ` +
+            `a session is titled after it is indexed (the daemon indexes within seconds), ` +
+            `and a peer's sessions are titled on the box that owns them`);
+    }
+    const { pending, cached } = selectSessionsNeedingTitle(rows, { limit, force: options.force });
+    result.cached = cached;
+    if (pending.length === 0)
+        return result;
+    // The provider is the ONLY thing that varies by model host; everything above
+    // (candidate selection, the source-key cache) and below (sanitize, persist) is
+    // shared. A local backend is dropped in here, not woven through the tick.
+    const provider = options.provider ?? new CloudSessionTitleProvider(options.run);
+    for (const { row, sourceKey } of pending) {
+        if (options.signal?.aborted)
+            break;
+        let title;
+        try {
+            title = sanitizeGeneratedTitle(await provider.generate(row, options.signal));
+        }
+        catch {
+            // Harness unavailable, signed out, or over its deadline. Best-effort: the
+            // row keeps showing the user's own words, and the caller backs off.
+            title = undefined;
+        }
+        if (!title) {
+            result.failed++;
+            continue;
+        }
+        if (setSessionGeneratedTitle(row.id, title, sourceKey, now)) {
+            result.generated++;
+            result.titles.push({ id: row.id, title });
+        }
+    }
+    return result;
+}

package/dist/lib/session/tool-calls.d.ts

@@ -10,7 +10,7 @@ export declare const TOOL_CHANGED_MAX_CALLS = 10000;
 export declare const TOOL_INDEX_LIMIT_ORDINAL: number;
 export declare const TOOL_TEXT_PROCESSING_MAX_BYTES: number;
 export declare const TOOL_SHELL_PARSE_MAX_BYTES: number;
-export declare const TOOL_INDEX_VERSION = 8;
+export declare const TOOL_INDEX_VERSION = 9;
 export type ToolCallOutcome = 'ok' | 'error' | 'unknown';
 export interface IndexedToolCall {
     ordinal: number;

package/dist/lib/session/tool-calls.js

@@ -12,10 +12,12 @@ export const TOOL_CHANGED_MAX_CALLS = 10_000;
 export const TOOL_INDEX_LIMIT_ORDINAL = Number.MAX_SAFE_INTEGER;
 export const TOOL_TEXT_PROCESSING_MAX_BYTES = 64 * 1024;
 export const TOOL_SHELL_PARSE_MAX_BYTES = 64 * 1024;
-// Bumped to 8 for the per-call end timestamp (PHNX-3437): the extractor now
-// records when a call's result arrived, so a re-index re-derives it for rows
-// stored by an older extractor.
-export const TOOL_INDEX_VERSION = 8;
+// Bumped to 9 for Codex tool-outcome classification (PHNX-3761): Codex results
+// arrive as a string or input_text[] rather than an object, so every one used to
+// store as 'unknown' and error rates read 0%. A re-index re-derives outcome for
+// rows stored by an older extractor.
+// (8 added the per-call end timestamp, PHNX-3437.)
+export const TOOL_INDEX_VERSION = 9;
 const BASE64_BLOCK = /(?:[A-Za-z0-9+/]{256,}={0,2})/g;
 const SECRET_FIELD = /(?:token|secret|password|authorization|cookie|api[_-]?key|private[_-]?key)$/i;
 const KNOWN_SECRET_VALUES = knownSecretValuesFromEnv();
@@ -258,9 +260,37 @@ function structuredString(source, name) {
     const value = structuredField(source, name);
     return typeof value === 'string' ? value : undefined;
 }
+// Codex tool results arrive as a plain string or an array of {type:'input_text',
+// text} blocks (never a plain object), so the text lives across the blocks and
+// the only outcome signal is the leading "Script completed"/"Script failed"
+// marker the exec harness prefixes onto the first block.
+function textSegments(value) {
+    if (typeof value === 'string')
+        return [value];
+    if (Array.isArray(value)) {
+        return value
+            .map((block) => block && typeof block === 'object' && typeof block.text === 'string'
+            ? block.text
+            : '')
+            .filter((text) => text.length > 0);
+    }
+    return [];
+}
+function codexScriptOutcome(value) {
+    const lead = textSegments(value)[0]?.trimStart();
+    if (!lead)
+        return undefined;
+    if (lead.startsWith('Script failed'))
+        return 'error';
+    if (lead.startsWith('Script completed'))
+        return 'ok';
+    return undefined;
+}
 function resultText(value) {
     if (typeof value === 'string')
         return value;
+    if (Array.isArray(value))
+        return textSegments(value).join('\n');
     const object = resultObject(value);
     if (object) {
         for (const key of ['output', 'stdout', 'content', 'text', 'message']) {
@@ -280,9 +310,14 @@ export function structuredToolResult(value) {
     const structured = resultObject(value);
     const success = structuredField(structured, 'success');
     const isError = success === false || structuredField(structured, 'is_error') === true;
+    const outcome = isError
+        ? 'error'
+        : success === true
+            ? 'ok'
+            : codexScriptOutcome(value) ?? 'unknown';
     return {
         text: resultText(value),
-        outcome: isError ? 'error' : success === true ? 'ok' : 'unknown',
+        outcome,
         exitCode: structuredNumber(structured, 'exit_code'),
         statusCode: structuredNumber(structured, 'status_code'),
         errorCode: structuredString(structured, 'error_code'),

package/dist/lib/session/tool-index.d.ts

@@ -31,6 +31,11 @@ export interface ToolSessionEvidence {
     cwd?: string;
     topic?: string;
     label?: string;
+    /** The daemon-generated headline (PHNX-3797). Carried so a consumer of this
+     * envelope names a session the same way every other surface does; a
+     * projection that drops it silently degrades `sessionHeadline` to
+     * `label || topic`. */
+    generatedTitle?: string;
     filePath?: string;
     calls: ToolCallEvidence[];
 }

package/dist/lib/session/tool-index.js

@@ -869,6 +869,7 @@ export function searchToolCalls(sessions, clauseSources, coverage, resultLimit =
             cwd: session.cwd,
             topic: session.topic,
             label: session.label,
+            generatedTitle: session.generatedTitle,
             calls: selected,
         });
         if (matched.length >= resultLimit)

package/dist/lib/session/types.d.ts

@@ -412,6 +412,17 @@ export interface SessionMeta {
      * single-turn session; absent for rows indexed before this field shipped.
      */
     lastUserMessage?: string;
+    /**
+     * The daemon-generated session TITLE (PHNX-3797) — a short, descriptive
+     * ACTION + OBJECT headline ("Triage the AGI board") for what the session is
+     * doing, produced ONCE per session by the `session-title` daemon service from
+     * the user's own first message (never from the agent's latest turn) and
+     * persisted in the index. It is the second rung of
+     * the headline ladder (`deriveSessionRecap`): an explicit `/rename` {@link label}
+     * still wins, and a session the titler has not reached yet falls back to
+     * `firstUserMessage`/`topic`, never to the agent's last line.
+     */
+    generatedTitle?: string;
     /**
      * The session's human-readable name — one field, several sources with a plain
      * priority: an agent-generated title / Claude `/rename` wins; else the launch

package/dist/lib/share/backend.d.ts

@@ -89,6 +89,29 @@ export declare function phoenixIdBaseForDeploy(opts?: {
     baseUrl?: string;
     domain?: string;
 }): string | undefined;
+/**
+ * Managed collaboration backend config to bind on a managed Worker deploy
+ * (PHNX-3835): `PRIX_ARTIFACT_COLLAB_BASE` (the Prix artifact-collaboration API
+ * base) and `ARTIFACT_COLLAB_SERVICE_TOKEN` (the service credential the Worker
+ * sends as `Authorization: Bearer`, NEVER surfaced to the browser). Both are read
+ * from the deploy environment.
+ *
+ * Deliberately dormant-by-default: the two secrets are applied ONLY when BOTH are
+ * present. Until the Prix API counterpart is live an operator leaves them unset,
+ * and the Worker fails `/__collab` closed (404) with the artifact page GET
+ * unaffected. A pure-BYO endpoint never gets them (it has no Phoenix identity).
+ * Unlike `phoenixIdBaseForDeploy` this never throws on absence — collaboration is
+ * additive, not required for a working managed deploy.
+ */
+export declare function collabConfigForDeploy(opts?: {
+    managed?: boolean;
+}, cfg?: {
+    baseUrl?: string;
+    domain?: string;
+}): {
+    collabBase?: string;
+    collabServiceToken?: string;
+};
 /**
  * Pick the principal via the shared selection policy. Signed-in AND no explicit
  * BYO override → managed; otherwise BYO.

package/dist/lib/share/backend.js

@@ -84,6 +84,30 @@ export function phoenixIdBaseForDeploy(opts = {}, cfg) {
     }
     return base;
 }
+/**
+ * Managed collaboration backend config to bind on a managed Worker deploy
+ * (PHNX-3835): `PRIX_ARTIFACT_COLLAB_BASE` (the Prix artifact-collaboration API
+ * base) and `ARTIFACT_COLLAB_SERVICE_TOKEN` (the service credential the Worker
+ * sends as `Authorization: Bearer`, NEVER surfaced to the browser). Both are read
+ * from the deploy environment.
+ *
+ * Deliberately dormant-by-default: the two secrets are applied ONLY when BOTH are
+ * present. Until the Prix API counterpart is live an operator leaves them unset,
+ * and the Worker fails `/__collab` closed (404) with the artifact page GET
+ * unaffected. A pure-BYO endpoint never gets them (it has no Phoenix identity).
+ * Unlike `phoenixIdBaseForDeploy` this never throws on absence — collaboration is
+ * additive, not required for a working managed deploy.
+ */
+export function collabConfigForDeploy(opts = {}, cfg) {
+    const managed = opts.managed === true || (cfg != null && isManagedShareEndpoint(cfg));
+    if (!managed)
+        return {};
+    const base = (process.env.PRIX_ARTIFACT_COLLAB_BASE || '').replace(/\/+$/, '').trim();
+    const token = (process.env.ARTIFACT_COLLAB_SERVICE_TOKEN || '').trim();
+    if (!base || !token)
+        return {};
+    return { collabBase: base, collabServiceToken: token };
+}
 /**
  * The share surface's BYO-override signals: an explicit `--byo`, a
  * caller-supplied static write token, or `AGENTS_SHARE_BACKEND=byo`. Detecting

package/dist/lib/share/provision.d.ts

@@ -64,6 +64,10 @@ export interface UpdateWorkerResult {
 }
 /** Cloudflare `secret_text` name the Worker reads as `env.PHOENIX_ID_BASE`. */
 export declare const WORKER_PHOENIX_ID_BASE_SECRET = "PHOENIX_ID_BASE";
+/** Cloudflare `secret_text` name the Worker reads as `env.PRIX_ARTIFACT_COLLAB_BASE`. */
+export declare const WORKER_COLLAB_BASE_SECRET = "PRIX_ARTIFACT_COLLAB_BASE";
+/** Cloudflare `secret_text` name the Worker reads as `env.ARTIFACT_COLLAB_SERVICE_TOKEN`. */
+export declare const WORKER_COLLAB_SERVICE_TOKEN_SECRET = "ARTIFACT_COLLAB_SERVICE_TOKEN";
 export type UpdateWorkerOpts = ProvisionOptions & {
     force?: boolean;
     /**
@@ -73,6 +77,14 @@ export type UpdateWorkerOpts = ProvisionOptions & {
      * fails loud — do not pass a blank to "skip".
      */
     phoenixIdBase?: string;
+    /**
+     * Managed collaboration backend (PHNX-3835). BOTH must be present to enable
+     * `/__collab`; pass neither to leave the surface disabled (the Worker fails it
+     * closed). The service token rides Cloudflare's Secrets API, never rendered
+     * HTML or browser JS. Applied like `phoenixIdBase` — only when defined.
+     */
+    collabBase?: string;
+    collabServiceToken?: string;
 };
 /**
  * Re-deploy the Worker script against an ALREADY-provisioned endpoint (same

package/dist/lib/share/provision.js

@@ -107,6 +107,10 @@ export function hashWorkerScript(script) {
 }
 /** Cloudflare `secret_text` name the Worker reads as `env.PHOENIX_ID_BASE`. */
 export const WORKER_PHOENIX_ID_BASE_SECRET = 'PHOENIX_ID_BASE';
+/** Cloudflare `secret_text` name the Worker reads as `env.PRIX_ARTIFACT_COLLAB_BASE`. */
+export const WORKER_COLLAB_BASE_SECRET = 'PRIX_ARTIFACT_COLLAB_BASE';
+/** Cloudflare `secret_text` name the Worker reads as `env.ARTIFACT_COLLAB_SERVICE_TOKEN`. */
+export const WORKER_COLLAB_SERVICE_TOKEN_SECRET = 'ARTIFACT_COLLAB_SERVICE_TOKEN';
 /**
  * Re-deploy the Worker script against an ALREADY-provisioned endpoint (same
  * account/worker/bucket `deployWorker` was first called with) and idempotently
@@ -145,6 +149,7 @@ export async function updateWorker(apiToken, accountId, workerName, bucketName,
         if (opts.phoenixIdBase !== undefined) {
             await applyPhoenixIdBaseSecret(apiToken, accountId, workerName, opts.phoenixIdBase, opts);
         }
+        await applyCollabSecrets(apiToken, accountId, workerName, opts);
         return { templateHash, skipped: true };
     }
     await deployWorker(apiToken, accountId, workerName, worker, bucketName, opts);
@@ -168,8 +173,33 @@ export async function updateWorker(apiToken, accountId, workerName, bucketName,
             throw new Error(`Worker deployed but PHOENIX_ID_BASE failed to re-apply — Phoenix-bearer publishes will 401 until you re-run \`agents artifacts share update\`. (${detail})`);
         }
     }
+    // The script upload wiped bindings/secrets (see JSDoc above), so re-apply the
+    // collaboration secrets too — but only when the caller provided them. An
+    // ordinary deploy with collaboration still dormant passes neither and the
+    // Worker keeps failing `/__collab` closed.
+    try {
+        await applyCollabSecrets(apiToken, accountId, workerName, opts);
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        throw new Error(`Worker deployed but the collaboration secrets failed to re-apply — \`/__collab\` stays disabled until you re-run \`agents artifacts share update\`. (${detail})`);
+    }
     return { templateHash, skipped: false };
 }
+/**
+ * Bind the managed collaboration secrets (PHNX-3835) — both or neither. A no-op
+ * when the caller passed neither (collaboration dormant), so a plain managed
+ * deploy never touches them; fails loud on a half-config (one without the other).
+ */
+async function applyCollabSecrets(apiToken, accountId, workerName, opts) {
+    if (opts.collabBase === undefined && opts.collabServiceToken === undefined)
+        return;
+    if (opts.collabBase === undefined || opts.collabServiceToken === undefined) {
+        throw new Error('Managed collaboration needs BOTH PRIX_ARTIFACT_COLLAB_BASE and ARTIFACT_COLLAB_SERVICE_TOKEN — set both or neither.');
+    }
+    await putWorkerSecret(apiToken, accountId, workerName, WORKER_COLLAB_BASE_SECRET, opts.collabBase, opts);
+    await putWorkerSecret(apiToken, accountId, workerName, WORKER_COLLAB_SERVICE_TOKEN_SECRET, opts.collabServiceToken, opts);
+}
 /** Add/update a secret_text binding using Cloudflare's Workers Secrets API. */
 export async function putWorkerSecret(apiToken, accountId, workerName, name, text, opts = {}) {
     const request = opts.request ?? defaultCloudflareRequester;