@oxygen-agent/cli 1.627.4 → 1.632.1

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
 
-Version: 1.627.4
+Version: 1.632.1

package/dist/index.js

@@ -667,6 +667,10 @@ function writeMaxCreditsHint(error) {
             return;
         }
         case "approval_required": {
+            if (error.message.startsWith("Public replies require --approved")) {
+                process.stderr.write("hint: inspect the exact preview, then re-run with its --content-hash <sha256> and --approved\n");
+                return;
+            }
             // Free-but-irreversible gates (tables/columns delete --now) approve with
             // --yes and spend nothing — the spend-flag hint would name flags the
             // command does not take. The server message is the signal: it spells out
@@ -2035,6 +2039,30 @@ function buildPublishingAnalyticsPath(base, params) {
     const suffix = query.toString();
     return suffix ? `${base}?${suffix}` : base;
 }
+function buildPublishingCommentsListPath(options) {
+    return buildPublishingAnalyticsPath("/api/cli/publishing/comments", {
+        status: readOption(options.status),
+        post_id: readOption(options.post),
+        assignee: readOption(options.assignee),
+        channel: readOption(options.channel),
+        cursor: readOption(options.cursor),
+        limit: readOption(options.limit),
+    });
+}
+function readPublishingCommentText(text, file, label) {
+    if (readOption(text) && readOption(file)) {
+        throw new OxygenError("conflicting_flags", `Pass either --${label} or --${label}-file, not both.`, {
+            exitCode: 1,
+        });
+    }
+    const value = readOption(file)
+        ? readPublishingTextFile(readOption(file) ?? "", `--${label}-file`)
+        : readOption(text);
+    if (!value?.trim()) {
+        throw new OxygenError("invalid_request", `Pass --${label} or --${label}-file.`, { exitCode: 1 });
+    }
+    return value.trim();
+}
 // `--file` is the whole import: a .csv is posted verbatim as `csv` (the API owns
 // the parse, so the CLI and the web importer can never disagree about a quoted
 // comma); a .json is posted as `rows`. Dry-run is the DEFAULT — a bare
@@ -3288,7 +3316,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     }));
     program
         .command("publishing")
-        .description("Deterministic social post scheduling commands.")
+        .description("Social publishing, performance, and public-comment operations.")
         .addCommand(new Command("mentions")
         .description("Resolve LinkedIn identities for a publish-faithful post preview.")
         .addCommand(new Command("resolve")
@@ -3614,11 +3642,123 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             method: "POST",
             body: buildPublishingTagsBody(options),
         }));
+    })))
+        .addCommand(new Command("comments")
+        .description("Public comments on posts published through OXYGEN. These are network conversations, not workspace review notes. The local queue targets a six-hour background poll; provider quota/backoff can delay it, and list reports the exact freshness plus empty_queue_is_current. If that field is false, do not conclude there are no comments: wait for next_sync_at. The worker retries automatically; there is no manual retry by design because it could loop against LinkedIn quota. Queue reads use 0 credits and make no provider call; only explicit approval can post a public reply.")
+        .addCommand(new Command("list")
+        .description("List the local public-comment work queue, oldest first, with polling freshness/backoff even when empty. Defaults to LinkedIn comments needing a reply. Read-only: no provider call, 0 credits.")
+        .option("--status <status>", "Filter by needs_reply, draft, awaiting_approval, replied, resolved, ignored, spam, or action_unavailable.")
+        .option("--post <post_id>", "Only comments on one scheduled Publishing post.")
+        .option("--assignee <actor>", "Only one actor id; pass me for your own assignments.")
+        .option("--channel <channel>", "Social channel. Defaults to linkedin.")
+        .option("--cursor <cursor>", "Opaque next_cursor from the previous page.")
+        .option("--limit <n>", "Maximum comments to return. Defaults to 50; maximum 100.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing comments list", options, () => requestOxygen(buildPublishingCommentsListPath(options)));
+    }))
+        .addCommand(new Command("get")
+        .description("Get one stored public comment with its provider thread and immutable reply-action history. Read-only: no provider call, 0 credits.")
+        .argument("<comment_id>", "OXYGEN public comment id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (commentId, options) => {
+        await handleAsyncAction("publishing comments get", options, () => requestOxygen(`/api/cli/publishing/comments/${encodeURIComponent(commentId)}`));
+    }))
+        .addCommand(new Command("update")
+        .description("Save local draft, notes, assignment, or triage state. Nothing is posted publicly and no credits are used.")
+        .argument("<comment_id>", "OXYGEN public comment id.")
+        .option("--draft <text>", "Save a reply draft locally.")
+        .option("--draft-file <path>", "Read the local reply draft from a file.")
+        .option("--notes <text>", "Workspace-only operator notes.")
+        .option("--assignee <actor_id>", "Assign to a workspace actor id; pass an empty string to clear.")
+        .option("--status <status>", "Set needs_reply, draft, resolved, ignored, or spam.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (commentId, options) => {
+        await handleAsyncAction("publishing comments update", options, () => {
+            const hasDraft = Boolean(readOption(options.draft) || readOption(options.draftFile));
+            if (!hasDraft && options.notes === undefined && options.assignee === undefined && options.status === undefined) {
+                throw new OxygenError("invalid_request", "Pass --draft/--draft-file, --notes, --assignee, or --status.", { exitCode: 1 });
+            }
+            return requestOxygen(`/api/cli/publishing/comments/${encodeURIComponent(commentId)}`, {
+                method: "PATCH",
+                body: {
+                    ...(hasDraft
+                        ? { draft_body: readPublishingCommentText(options.draft, options.draftFile, "draft") }
+                        : {}),
+                    ...(options.notes !== undefined ? { notes: options.notes } : {}),
+                    ...(options.assignee !== undefined
+                        ? { assignee_actor_id: readOption(options.assignee) ?? null }
+                        : {}),
+                    ...(readOption(options.status) ? { status: readOption(options.status) } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("reply")
+        .description("Preview an exact public reply and return its action_id + content_hash. Makes no provider call, posts nothing, and uses 0 credits.")
+        .argument("<comment_id>", "OXYGEN public comment id.")
+        .option("--text <text>", "Reply text to preview.")
+        .option("--text-file <path>", "Read reply text from a file.")
+        .option("--idempotency-key <key>", "Stable key for safely recreating the same preview.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (commentId, options) => {
+        await handleAsyncAction("publishing comments reply preview", options, () => requestOxygen(`/api/cli/publishing/comments/${encodeURIComponent(commentId)}/reply-actions`, {
+            method: "POST",
+            body: {
+                body: readPublishingCommentText(options.text, options.textFile, "text"),
+                ...(readOption(options.idempotencyKey)
+                    ? { idempotency_key: readOption(options.idempotencyKey) }
+                    : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("approve")
+        .description("Post one exact previewed reply publicly. A REAL LinkedIn write; refused without --approved and the preview's content hash.")
+        .argument("<action_id>", "Reply action id returned by `publishing comments reply`.")
+        .requiredOption("--content-hash <sha256>", "Exact content_hash returned by the preview.")
+        .option("--approved", "Approve this exact public reply.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (actionId, options) => {
+        await handleAsyncAction("publishing comments reply approve", options, () => {
+            if (options.approved !== true) {
+                throw new OxygenError("approval_required", "Public replies require --approved after inspecting the exact preview.", { exitCode: 7 });
+            }
+            return requestOxygen(`/api/cli/publishing/comment-replies/${encodeURIComponent(actionId)}/approve`, {
+                method: "POST",
+                body: { content_hash: options.contentHash, approved: true },
+            });
+        });
+    }))
+        .addCommand(new Command("resolve")
+        .description("Resolve, ignore, mark spam, or reopen one local public-comment work item. No provider write, 0 credits.")
+        .argument("<comment_id>", "OXYGEN public comment id.")
+        .option("--resolution <status>", "resolved (default), ignored, spam, or needs_reply.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (commentId, options) => {
+        await handleAsyncAction("publishing comments resolve", options, () => requestOxygen(`/api/cli/publishing/comments/${encodeURIComponent(commentId)}/resolve`, {
+            method: "POST",
+            body: { resolution: readOption(options.resolution) ?? "resolved" },
+        }));
     })))
         .addCommand(new Command("analytics")
         .description("Engagement metrics the worker syncs back from the provider. Free reads. LinkedIn exposes reactions, comments, and reshares only — impressions, saves, and sends come back null, never zero.")
+        .addCommand(new Command("summary")
+        .description("Workspace LinkedIn performance for posts published through OXYGEN. Uses each post's latest stored snapshot; unsupported metrics stay null. Read-only: no provider call, 0 credits.")
+        .option("--range <range>", "Publication window: 7d, 30d (default), 90d, or 365d.")
+        .option("--from <date>", "Custom inclusive UTC start date.")
+        .option("--to <date>", "Custom inclusive UTC end date.")
+        .option("--limit <n>", "Top posts to return. Defaults to 10, maximum 50.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing analytics summary", options, () => requestOxygen(buildPublishingAnalyticsPath("/api/cli/publishing/analytics/summary", {
+            range: readOption(options.range),
+            from: readOption(options.from),
+            to: readOption(options.to),
+            limit: readOption(options.limit),
+        })));
+    }))
         .addCommand(new Command("post")
-        .description("One post's daily metric series, totals, and earned-media value. EMV is impressions-derived, so on LinkedIn it returns null with an unavailable_reason instead of a made-up number.")
+        .description("One post's stored daily metric series, totals, and earned-media value. EMV is impressions-derived, so on LinkedIn it returns null with an unavailable_reason instead of a made-up number. Read-only: no provider call, 0 credits.")
         .argument("<post_id>", "Scheduled post id.")
         .option("--since <date>", "ISO date to start the series from.")
         .option("--json", "Print a JSON envelope.")
@@ -3626,7 +3766,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         await handleAsyncAction("publishing analytics post", options, () => requestOxygen(buildPublishingAnalyticsPath(`/api/cli/publishing/analytics/posts/${encodeURIComponent(postId)}`, { since: readOption(options.since) })));
     }))
         .addCommand(new Command("account")
-        .description("Per-account metric series for the connected publishing accounts.")
+        .description("Stored per-account metric series for connected publishing accounts. Read-only: no provider call, 0 credits.")
         .option("--provider <provider>", "Provider to read. Defaults to linkedin.")
         .option("--since <date>", "ISO date to start the series from.")
         .option("--json", "Print a JSON envelope.")
@@ -4845,6 +4985,82 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 mode: options.live ? "live" : "dry_run",
             },
         }));
+    }))
+        .addCommand(new Command("relations")
+        .description("Inspect and manage native Tables-owned relation definitions.")
+        .addCommand(new Command("list")
+        .description("List the native relations visible from one table, including cardinality, target, and active link count.")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables relations list", options, () => {
+            const params = new URLSearchParams({ table });
+            return requestOxygen(`/api/cli/tables/relations?${params.toString()}`);
+        });
+    }))
+        .addCommand(new Command("update")
+        .description("Rename either side of a relation or change its cardinality. Endpoints and slugs stay immutable. Previews by default.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<relation>", "Relation slug as seen from this table.")
+        .option("--display-name <name>", "New display name on this table.")
+        .option("--inverse-display-name <name>", "New display name on the other table.")
+        .option("--cardinality <cardinality>", "one_to_one, one_to_many, many_to_one, or many_to_many from this table's perspective.")
+        .option("--approved", "Apply after inspecting the preview.")
+        .option("--dry-run", "Preview without writing. This is the default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, relation, options) => {
+        await handleAsyncAction("tables relations update", options, () => requestOxygen("/api/cli/tables/relations", {
+            method: "PATCH",
+            body: {
+                table,
+                relation,
+                ...(readOption(options.displayName) ? { display_name: readOption(options.displayName) } : {}),
+                ...(readOption(options.inverseDisplayName)
+                    ? { inverse_display_name: readOption(options.inverseDisplayName) }
+                    : {}),
+                ...(readOption(options.cardinality) ? { cardinality: readOption(options.cardinality) } : {}),
+                mode: options.approved && !options.dryRun ? "live" : "dry_run",
+            },
+        }));
+    }))
+        .addCommand(new Command("archive")
+        .description("Archive a native relation, its active links, and both relation columns while preserving history. Previews by default.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<relation>", "Relation slug as seen from this table.")
+        .option("--approved", "Apply after inspecting the preview.")
+        .option("--dry-run", "Preview without writing. This is the default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, relation, options) => {
+        await handleAsyncAction("tables relations archive", options, () => requestOxygen("/api/cli/tables/relations", {
+            method: "DELETE",
+            body: {
+                table,
+                relation,
+                mode: options.approved && !options.dryRun ? "live" : "dry_run",
+            },
+        }));
+    })))
+        .addCommand(new Command("unlink")
+        .description("Unlink one exact pair of rows by archiving their relation edge. The relation definition and both rows remain. Previews by default.")
+        .argument("<table>", "Source table id or slug.")
+        .argument("<row_id>", "Source row id.")
+        .requiredOption("--relation <slug>", "Relation slug as seen from the source table.")
+        .requiredOption("--target-row-id <row_id>", "Linked row id to remove.")
+        .option("--approved", "Apply after inspecting the preview.")
+        .option("--live", "Alias for --approved.")
+        .option("--dry-run", "Preview without writing. This is the default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, rowId, options) => {
+        await handleAsyncAction("tables unlink", options, () => requestOxygen("/api/cli/tables/relations/unlink", {
+            method: "POST",
+            body: {
+                table,
+                row_id: rowId,
+                relation: options.relation,
+                target_row_id: options.targetRowId,
+                mode: (options.approved || options.live) && !options.dryRun ? "live" : "dry_run",
+            },
+        }));
     }))
         .addCommand(new Command("link")
         .description("Link two tables: Oxygen finds the column that joins them, works out the direction, shows you how many rows will match, and on approval links every row. Free. Previews by default; --approved queues a background run and records each row's outcome in a system link_status_<relation> column. Wait for that run with `oxygen table-runs wait <run_id>`. (Also links one row to one row — see --relation.)")
@@ -9837,9 +10053,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     })));
     program.addCommand(new Command("posts")
-        .description("Read and publish LinkedIn posts through a connected account. `get` returns a post and the composite social_id that `comments`/`reactions` and `oxygen engagement harvest` need; `create` publishes a real post (approval-gated). Every command here addresses ONE post you already have an id for — Oxygen cannot enumerate an account's own LinkedIn history, so analytics only cover posts Oxygen itself published (`oxygen publishing ...`). All calls are metered against the sender account's daily quota.")
+        .description("Read and publish LinkedIn posts through a connected account. `get`, `comments`, and `reactions` are LIVE provider reads: they use 0 Oxygen credits but consume the sender's daily account-read allowance. Do not use them when a task forbids provider calls; use `publishing comments list` for the local cross-post queue. `create` publishes a real post (approval-gated). Every command here addresses ONE post you already have an id for — Oxygen cannot enumerate an account's own LinkedIn history, so analytics only cover posts Oxygen itself published (`oxygen publishing ...`).")
         .addCommand(new Command("get")
-        .description("Read a LinkedIn post. Returns the post and its composite social_id (reuse that social_id for `posts comments`, `posts reactions`, and `engagement harvest --source unipile` — NOT the raw activity URN). Metered as an account read.")
+        .description("LIVE provider read of one LinkedIn post. Uses 0 Oxygen credits but consumes the sender's metered account-read allowance; do not run it when the task forbids provider calls. Returns the post and its composite social_id (reuse that social_id for `posts comments`, `posts reactions`, and `engagement harvest --source unipile` — NOT the raw activity URN). This does not populate or refresh the durable `publishing comments` queue.")
         .requiredOption("--post <id>", "Numeric activity id, activity URL, or composite social_id. There is no way to LIST your own posts: take the id from the post's LinkedIn URL, or from a post you scheduled (`oxygen publishing posts get <post_id>` → provider_post_id).")
         .option("--account <ref>", "Sender account to read through (sender id, connection id, or Unipile account id). Omit for the org default.")
         .option("--json", "Print a JSON envelope.")
@@ -9854,7 +10070,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("comments")
-        .description("List a post's comments (or the replies to a comment with --comment-id). --post MUST be the composite social_id from `posts get`, not the activity URN. Metered as an account read.")
+        .description("Read one post's comments live from LinkedIn (or one comment's replies with --comment-id). This consumes the sender's metered account-read allowance, uses 0 Oxygen credits, and does not populate the durable queue. For the zero-provider-call cross-post work queue, use `publishing comments list`. --post MUST be the composite social_id from `posts get`, not the activity URN.")
         .requiredOption("--post <social_id>", "Composite post social_id from `posts get`.")
         .option("--comment-id <id>", "List replies to this comment instead of top-level comments.")
         .option("--sort-by <sort>", "Comment sort order (provider-defined, e.g. recent|relevant).")
@@ -10495,7 +10711,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     })));
     program.addCommand(new Command("inbox")
-        .description("Unified inbox (unibox): email + LinkedIn + WhatsApp conversations in one stream (--channel all), or a single channel. Scan, read threads, and reply.")
+        .description("Unified inbox (unibox): private email + LinkedIn DM + WhatsApp conversations in one stream (--channel all), or a single channel. Public comments on OXYGEN-published posts are not inbox messages; use `publishing comments`. Scan, read threads, and reply.")
         .addCommand(new Command("list")
         .description("List conversations newest first. --channel all merges email + LinkedIn + WhatsApp into one stream (narrow it with --channels); --channel email/linkedin/whatsapp lists a single channel. Primary excludes the negative tier (not_now, not_interested, lost, bounced); All includes every ordinary conversation.")
         .option("--channel <channel>", "Inbox channel: all (merged), linkedin (default), whatsapp, or email.")
@@ -12778,7 +12994,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .addCommand(new Command("warmup")
         .description("Mailbox warmup for the sending pool. Oxygen's native warmup runs on ONE rail: TrulyInbox, managed and credit-billed per warming-inbox-month. Oxygen enrolls the mailbox for you — preview first, then re-run with --approved to execute and bill. (Instantly and Warmforge remain BYOK integrations elsewhere in Oxygen; they are no longer warmup rails.)")
         .addCommand(new Command("enable")
-        .description("Enable warmup for sending mailboxes and stamp each mailbox's warmup state. Targets the whole pool unless --mailboxes is given. Without --approved this is a 0-credit, no-provider-write priced preview: nothing is enrolled or billed. Execute by echoing its --plan and --max-credits with --approved.")
+        .description("Enable warmup for sending mailboxes and stamp each mailbox's warmup state. Targets the whole pool unless --mailboxes is given. Without --approved this is a 0-credit, no-provider-write priced preview: nothing is enrolled or billed. Preview one inbox with `oxygen mailboxes warmup enable --mailboxes sender@example.com --json`. Execute by echoing its --plan and --max-credits with --approved.")
         .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses to warm. Omit to warm the whole pool.")
         .option("--approved", "Execute the PRICED enrollment. Without it the response is a priced preview and nothing is enrolled or billed.")
         .option("--plan <hash>", "Hash from the fresh preview (required with --approved).")

package/node_modules/@oxygen/shared/dist/capability-discovery.js

@@ -184,11 +184,11 @@ export const OXYGEN_CAPABILITY_ROUTES = [
         notFor: "One-to-one conversations, delivery scheduling, or generic public LinkedIn provider search.",
         execution: "Read or create the hosted Post artifact; Publishing owns scheduled delivery.",
         posture: "workspace_write",
-        gatewayTools: ["oxygen_posts_get", "oxygen_posts_comments_list", "oxygen_posts_reactions_list", "oxygen_posts_create"],
-        gatewayCommands: ["posts get", "posts comments", "posts reactions", "posts create"],
+        gatewayTools: ["oxygen_publishing_comments", "oxygen_publishing_analytics", "oxygen_posts_get", "oxygen_posts_create"],
+        gatewayCommands: ["publishing comments list", "publishing analytics summary", "posts get", "posts create"],
         skills: ["oxygen-linkedin-marketing"],
         endpointSections: [],
-        intentTerms: ["post artifact", "social post", "post comments", "post reactions", "post performance", "broadcast content"],
+        intentTerms: ["post artifact", "social post", "post comments", "public comments", "comments needing reply", "post reactions", "post performance", "posting analytics", "broadcast content"],
     },
     {
         id: "signals",
@@ -473,6 +473,8 @@ function normalizeIntent(query) {
 function explicitCapabilityIntent(query) {
     if (isHostedWorkflowIntent(query))
         return ROUTE_BY_PRIMITIVE.get("workflows") ?? null;
+    if (isOwnedPostCommentIntent(query))
+        return ROUTE_BY_PRIMITIVE.get("posts") ?? null;
     // A deferred acquisition motion starts with the public-data owner. This keeps
     // "find/qualify now, contact later" from skipping straight to the final write
     // step; the recommendation still hands the eventual initiation to Sequences.
@@ -550,6 +552,17 @@ function highestScoringRoute(query) {
     return best?.card ?? null;
 }
 function recommendationsFor(card, query) {
+    if (card.primitive === "posts" && isOwnedPostCommentIntent(query)) {
+        return {
+            tools: ["oxygen_publishing_comments", "oxygen_publishing_analytics"],
+            commands: [
+                "publishing comments list",
+                "publishing comments get",
+                "publishing comments reply",
+                "publishing analytics summary",
+            ],
+        };
+    }
     if (card.id === "linkedin-public-research" && isPublicLinkedInEngagerHarvest(query)) {
         const motion = isLinkedInEngagerMotion(query);
         return {
@@ -730,6 +743,14 @@ function isNetNewLinkedInInitiation(query) {
         return false;
     return !/\b(sequence|campaign|cadence|enroll|nurture|multi[ -]step|multi[ -]recipient|leads|contacts|recipients|audience|rotate senders?|stop on reply|day\s*\d+)\b/.test(query);
 }
+function isOwnedPostCommentIntent(query) {
+    if (!/\bcomments?\b/.test(query) || !/\b(linkedin|posts?|publishing)\b/.test(query))
+        return false;
+    const owned = /\b(my|our|own)\b|\boxygen[ -]published\b|\bpublished through oxygen\b/.test(query);
+    const operatorWork = /\b(needs?|needing|awaiting)\b.{0,20}\b(response|reply|answer)\b/.test(query)
+        || /\b(reply|respond|answer|triage|queue)\b/.test(query);
+    return owned || operatorWork;
+}
 function isHostedWorkflowIntent(query) {
     const strongWorkflowLanguage = /\b(workflow|automation|automate|automatically|webhook|cron|event trigger|branching?|retr(?:y|ies)|orchestrat(?:e|ion)|scheduled job|deterministic graph)\b/.test(query);
     const cadenceLanguage = /\b(sequence|campaign|cadence|day\s*\d+|multi[ -]step|rotate senders?|sender rotation|stop on reply|until (?:they )?reply)\b/.test(query);

package/node_modules/@oxygen/shared/dist/copilot-errors.d.ts

@@ -0,0 +1,15 @@
+export declare const COPILOT_TURN_TIMEOUT_CODE = "copilot_turn_timeout";
+export declare const COPILOT_TURN_TIMEOUT_MESSAGE = "This Copilot request timed out and stopped. Any completed actions are still saved\u2014review this session before trying again.";
+export type CustomerFacingCopilotError = {
+    code: string | null;
+    message: string | null;
+};
+/**
+ * Replace an internal worker deadline with the stable Copilot timeout contract.
+ * The message-pattern fallback heals rows written before the worker error code
+ * was persisted consistently. Other errors pass through byte-for-byte.
+ */
+export declare function customerFacingCopilotError(input: {
+    code?: string | null;
+    message?: string | null;
+}): CustomerFacingCopilotError;

package/node_modules/@oxygen/shared/dist/copilot-errors.js

@@ -0,0 +1,22 @@
+// Customer-facing Workspace Copilot error policy. Worker supervision details
+// belong in operational telemetry, never in the conversation timeline or turn
+// row every Control surface renders. Keep this mapping shared so new failures
+// and already-persisted failures serialize identically across web, CLI, and MCP.
+export const COPILOT_TURN_TIMEOUT_CODE = "copilot_turn_timeout";
+export const COPILOT_TURN_TIMEOUT_MESSAGE = "This Copilot request timed out and stopped. Any completed actions are still saved—review this session before trying again.";
+const WORKER_STEP_TIMEOUT_MESSAGE = /\bWorker step '[^']+' exceeded \d+ms deadline\.?/i;
+/**
+ * Replace an internal worker deadline with the stable Copilot timeout contract.
+ * The message-pattern fallback heals rows written before the worker error code
+ * was persisted consistently. Other errors pass through byte-for-byte.
+ */
+export function customerFacingCopilotError(input) {
+    const code = input.code ?? null;
+    const message = input.message ?? null;
+    const isTimeout = code === "worker_step_timeout" ||
+        code === COPILOT_TURN_TIMEOUT_CODE ||
+        (message !== null && WORKER_STEP_TIMEOUT_MESSAGE.test(message));
+    return isTimeout
+        ? { code: COPILOT_TURN_TIMEOUT_CODE, message: COPILOT_TURN_TIMEOUT_MESSAGE }
+        : { code, message };
+}

package/node_modules/@oxygen/shared/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from "./cli-result.js";
 export * from "./crm-reply-events.js";
 export * from "./crm-activity-events.js";
 export * from "./column-types.js";
+export * from "./copilot-errors.js";
 export * from "./copilot-journeys.js";
 export * from "./credit-guidance.js";
 export * from "./directory.js";
@@ -47,6 +48,7 @@ export * from "./log.js";
 export { sanitizeLogFields } from "./redaction.js";
 export * from "./provider-request-outcomes.js";
 export * from "./schedule-label.js";
+export * from "./social-capabilities.js";
 export * from "./signup-lead-deliveries.js";
 export * from "./sql-error.js";
 export * from "./tags.js";
@@ -56,6 +58,7 @@ export * from "./timing.js";
 export * from "./type-guards.js";
 export * from "./worker-failures-queue.js";
 export * from "./workflow-mcp-tools.js";
+export * from "./workflow-trigger-label.js";
 export * from "./workspace-event-catalog.js";
 export * from "./workspace-agents.js";
 export declare const MAX_ROW_LOOP_WRITE_ROWS = 500;

package/node_modules/@oxygen/shared/dist/index.js

@@ -14,6 +14,7 @@ export * from "./cli-result.js";
 export * from "./crm-reply-events.js";
 export * from "./crm-activity-events.js";
 export * from "./column-types.js";
+export * from "./copilot-errors.js";
 export * from "./copilot-journeys.js";
 export * from "./credit-guidance.js";
 export * from "./directory.js";
@@ -51,6 +52,7 @@ export * from "./log.js";
 export { sanitizeLogFields } from "./redaction.js";
 export * from "./provider-request-outcomes.js";
 export * from "./schedule-label.js";
+export * from "./social-capabilities.js";
 export * from "./signup-lead-deliveries.js";
 export * from "./sql-error.js";
 export * from "./tags.js";
@@ -60,6 +62,7 @@ export * from "./timing.js";
 export * from "./type-guards.js";
 export * from "./worker-failures-queue.js";
 export * from "./workflow-mcp-tools.js";
+export * from "./workflow-trigger-label.js";
 export * from "./workspace-event-catalog.js";
 export * from "./workspace-agents.js";
 // Maximum rows a single row-loop write (insert/upsert/preview) may process. The

package/node_modules/@oxygen/shared/dist/social-capabilities.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Social channel capability registry.
+ *
+ * Channel, provider rail, and operation support are deliberately independent.
+ * LinkedIn is the only registered channel today, but callers resolve capabilities
+ * through this contract instead of branching on `channel === "linkedin"`. Adding a
+ * channel later means registering a real adapter profile, not adding placeholder UI.
+ */
+export declare const SOCIAL_CHANNELS: readonly ["linkedin"];
+export type SocialChannel = (typeof SOCIAL_CHANNELS)[number];
+export declare const SOCIAL_PROVIDER_RAILS: readonly ["unipile"];
+export type SocialProviderRail = (typeof SOCIAL_PROVIDER_RAILS)[number];
+export declare const SOCIAL_OPERATIONS: readonly ["list_owned_posts", "read_post_metrics", "list_comments", "reply_to_comment"];
+export type SocialOperation = (typeof SOCIAL_OPERATIONS)[number];
+export declare const SOCIAL_POST_METRICS: readonly ["impressions", "reactions", "comments", "reposts", "saves", "sends", "clicks", "video_views"];
+export type SocialPostMetric = (typeof SOCIAL_POST_METRICS)[number];
+export type SocialCapabilityStatus = "available" | "limited" | "unavailable";
+export type SocialOperationCapability = {
+    status: SocialCapabilityStatus;
+    /** Local durable state or a provider operation. */
+    source: "oxygen_store" | "provider";
+    provider_operation: string | null;
+    external_write: boolean;
+    limitation: string | null;
+};
+export type SocialMetricCapability = {
+    status: "available" | "unavailable";
+    provider_field: string | null;
+    reason: string | null;
+};
+export type SocialCapabilityProfile = {
+    version: 1;
+    channel: SocialChannel;
+    provider_rail: SocialProviderRail;
+    operations: Record<SocialOperation, SocialOperationCapability>;
+    metrics: Record<SocialPostMetric, SocialMetricCapability>;
+    ingestion: {
+        polling: boolean;
+        webhooks: boolean;
+    };
+};
+export declare function listSocialCapabilityProfiles(): readonly SocialCapabilityProfile[];
+export declare function getSocialCapabilityProfile(channel: string, providerRail: string): SocialCapabilityProfile | null;

package/node_modules/@oxygen/shared/dist/social-capabilities.js

@@ -0,0 +1,85 @@
+/**
+ * Social channel capability registry.
+ *
+ * Channel, provider rail, and operation support are deliberately independent.
+ * LinkedIn is the only registered channel today, but callers resolve capabilities
+ * through this contract instead of branching on `channel === "linkedin"`. Adding a
+ * channel later means registering a real adapter profile, not adding placeholder UI.
+ */
+export const SOCIAL_CHANNELS = ["linkedin"];
+export const SOCIAL_PROVIDER_RAILS = ["unipile"];
+export const SOCIAL_OPERATIONS = [
+    "list_owned_posts",
+    "read_post_metrics",
+    "list_comments",
+    "reply_to_comment",
+];
+export const SOCIAL_POST_METRICS = [
+    "impressions",
+    "reactions",
+    "comments",
+    "reposts",
+    "saves",
+    "sends",
+    "clicks",
+    "video_views",
+];
+const NOT_EXPOSED_BY_UNIPILE = "not_exposed_by_current_provider_rail";
+const LINKEDIN_UNIPILE_CAPABILITIES = {
+    version: 1,
+    channel: "linkedin",
+    provider_rail: "unipile",
+    operations: {
+        list_owned_posts: {
+            status: "limited",
+            source: "oxygen_store",
+            provider_operation: null,
+            external_write: false,
+            limitation: "oxygen_published_posts_only",
+        },
+        read_post_metrics: {
+            status: "limited",
+            source: "provider",
+            provider_operation: "linkedin.posts_get",
+            external_write: false,
+            limitation: "coarse_public_counters_only",
+        },
+        list_comments: {
+            status: "available",
+            source: "provider",
+            provider_operation: "linkedin.posts_comments_list",
+            external_write: false,
+            limitation: null,
+        },
+        reply_to_comment: {
+            status: "available",
+            source: "provider",
+            provider_operation: "linkedin.posts_comment_create",
+            external_write: true,
+            limitation: null,
+        },
+    },
+    metrics: {
+        impressions: { status: "unavailable", provider_field: null, reason: NOT_EXPOSED_BY_UNIPILE },
+        reactions: { status: "available", provider_field: "reaction_count", reason: null },
+        comments: { status: "available", provider_field: "comment_count", reason: null },
+        reposts: { status: "available", provider_field: "repost_count", reason: null },
+        saves: { status: "unavailable", provider_field: null, reason: NOT_EXPOSED_BY_UNIPILE },
+        sends: { status: "unavailable", provider_field: null, reason: NOT_EXPOSED_BY_UNIPILE },
+        clicks: { status: "unavailable", provider_field: null, reason: NOT_EXPOSED_BY_UNIPILE },
+        video_views: { status: "unavailable", provider_field: null, reason: NOT_EXPOSED_BY_UNIPILE },
+    },
+    ingestion: {
+        polling: true,
+        webhooks: false,
+    },
+};
+const SOCIAL_CAPABILITY_PROFILES = [
+    LINKEDIN_UNIPILE_CAPABILITIES,
+];
+export function listSocialCapabilityProfiles() {
+    return SOCIAL_CAPABILITY_PROFILES;
+}
+export function getSocialCapabilityProfile(channel, providerRail) {
+    return SOCIAL_CAPABILITY_PROFILES.find((profile) => profile.channel === channel && profile.provider_rail === providerRail) ?? null;
+}

package/node_modules/@oxygen/shared/dist/version.d.ts

@@ -1,3 +1,3 @@
-export declare const OXYGEN_VERSION = "1.627.4";
+export declare const OXYGEN_VERSION = "1.632.1";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";
 export declare const MANAGED_INBOX_MINIMUM_CLI_VERSION = "1.326.2";

package/node_modules/@oxygen/shared/dist/version.js

@@ -1,4 +1,4 @@
-export const OXYGEN_VERSION = "1.627.4";
+export const OXYGEN_VERSION = "1.632.1";
 // The GLOBAL CLI compatibility floor: the oldest CLI allowed to call any
 // operational route. Raising it hard-rejects every older CLI from the entire
 // product, so it obeys one law, enforced by scripts/ci/cli-min-version-gate.mjs:

package/node_modules/@oxygen/shared/dist/workflow-trigger-label.d.ts

@@ -0,0 +1,63 @@
+import { type WorkspaceEventCatalogEntry } from "./workspace-event-catalog.js";
+/**
+ * A workflow event trigger's filter, loosely typed so callers can pass either
+ * the canonical `WorkflowEventFilter` (packages/workflows) or a trigger row's
+ * persisted `metadata.filters` JSON without this module depending on either
+ * shape's owning package.
+ */
+export type WorkflowTriggerFilterLike = {
+    path: string;
+    op: string;
+    value?: unknown;
+};
+/**
+ * Title-cased trigger-type label ("API", "Webhook", "Cron", "Event") so a
+ * trigger reads the same word on every surface that summarizes it. Falls back
+ * to a generic capitalization for a trigger type this list doesn't know about
+ * yet, never to the raw lowercase identifier — the bug this module fixes was
+ * exactly that fallback leaking "event" next to three title-cased siblings.
+ */
+export declare function workflowTriggerTypeLabel(type: string | null | undefined): string;
+/**
+ * Order-independent identity for a filter set.
+ *
+ * MIRRORED by `normalizedFilterSignature` in the visual editor's picker
+ * (apps/web/src/lib/workflow-builder/workspace-event-option.ts), which cannot
+ * import this one: that module reaches a client component, and client
+ * components must not pull the @oxygen/shared barrel into the page bundle.
+ * Both answer the same question — "are these the same preset?" — so a drift
+ * would let the editor treat a preset as selected while the list labels it as
+ * something else. workspace-event-option.test.ts pins them to equal output.
+ */
+export declare function workflowTriggerFilterSignature(filters: readonly WorkflowTriggerFilterLike[] | null | undefined): string;
+/**
+ * Match an event trigger's (source, event, filters) against the workspace
+ * event catalog. Filters are part of the identity on purpose: ~28 catalog
+ * presets share one (source, event) pair (e.g. `sequencer.contact_activity`)
+ * and differ ONLY by filters — "fires on a bounce" and "fires on a reply" must
+ * resolve to two different entries, never the same one.
+ */
+export declare function matchWorkspaceEventCatalogEntry(input: {
+    source: string;
+    event: string;
+    filters?: readonly WorkflowTriggerFilterLike[] | null | undefined;
+}): WorkspaceEventCatalogEntry | null;
+export type WorkflowEventTriggerLabel = {
+    /** The catalog's human label, or the raw "source · event" identifier when unmatched. Never blank. */
+    label: string;
+    /** True when a catalog entry matched — callers use this to style a human label differently from a raw identifier. */
+    matched: boolean;
+    /** The matched catalog entry's group (e.g. "Sequencer"), or null when unmatched. */
+    group: string | null;
+};
+/**
+ * Human label for an event trigger, resolved against the workspace event
+ * catalog. Falls back to the raw "source · event" identifier — never to a
+ * blank string — when no catalog entry matches: a generic integration
+ * subscription event, or a preset that predates the catalog.
+ */
+export declare function workflowEventTriggerLabel(input: {
+    source: string | null | undefined;
+    event: string | null | undefined;
+    filters?: readonly WorkflowTriggerFilterLike[] | null | undefined;
+}): WorkflowEventTriggerLabel;

package/node_modules/@oxygen/shared/dist/workflow-trigger-label.js

@@ -0,0 +1,85 @@
+// Human-facing trigger labels shared by every surface that lists workflows
+// OUTSIDE the visual editor: the web workflows table
+// (apps/web/src/components/workflows/workflows-table.tsx) and the MCP
+// `oxygen.workflow-overview` widget (packages/mcp-server/src/widgets/workflow-overview.ts).
+// Both render a trigger as a one-line summary and need the same two answers:
+// what does this TYPE of trigger call itself ("Webhook", not "webhook"), and —
+// for an event trigger — what does the workspace event catalog call this exact
+// (source, event, filters) combination.
+//
+// Dependency-free on purpose, like schedule-label.ts: consumed by web, CLI, and
+// the MCP widgets (packages/mcp-server depends only on @oxygen/shared).
+import { WORKSPACE_EVENT_CATALOG } from "./workspace-event-catalog.js";
+const WORKFLOW_TRIGGER_TYPE_LABELS = {
+    api: "API",
+    webhook: "Webhook",
+    cron: "Cron",
+    event: "Event",
+};
+/**
+ * Title-cased trigger-type label ("API", "Webhook", "Cron", "Event") so a
+ * trigger reads the same word on every surface that summarizes it. Falls back
+ * to a generic capitalization for a trigger type this list doesn't know about
+ * yet, never to the raw lowercase identifier — the bug this module fixes was
+ * exactly that fallback leaking "event" next to three title-cased siblings.
+ */
+export function workflowTriggerTypeLabel(type) {
+    if (!type)
+        return "—";
+    return WORKFLOW_TRIGGER_TYPE_LABELS[type] ?? `${type.charAt(0).toUpperCase()}${type.slice(1)}`;
+}
+/**
+ * Order-independent identity for a filter set.
+ *
+ * MIRRORED by `normalizedFilterSignature` in the visual editor's picker
+ * (apps/web/src/lib/workflow-builder/workspace-event-option.ts), which cannot
+ * import this one: that module reaches a client component, and client
+ * components must not pull the @oxygen/shared barrel into the page bundle.
+ * Both answer the same question — "are these the same preset?" — so a drift
+ * would let the editor treat a preset as selected while the list labels it as
+ * something else. workspace-event-option.test.ts pins them to equal output.
+ */
+export function workflowTriggerFilterSignature(filters) {
+    return (filters ?? [])
+        .map((filter) => JSON.stringify({
+        path: filter.path,
+        op: filter.op,
+        ...(filter.value !== undefined ? { value: filter.value } : {}),
+    }))
+        .sort()
+        .join("|");
+}
+/**
+ * Match an event trigger's (source, event, filters) against the workspace
+ * event catalog. Filters are part of the identity on purpose: ~28 catalog
+ * presets share one (source, event) pair (e.g. `sequencer.contact_activity`)
+ * and differ ONLY by filters — "fires on a bounce" and "fires on a reply" must
+ * resolve to two different entries, never the same one.
+ */
+export function matchWorkspaceEventCatalogEntry(input) {
+    const signature = workflowTriggerFilterSignature(input.filters);
+    return WORKSPACE_EVENT_CATALOG.find((entry) => entry.source === input.source
+        && entry.event === input.event
+        && workflowTriggerFilterSignature(entry.filters) === signature) ?? null;
+}
+/**
+ * Human label for an event trigger, resolved against the workspace event
+ * catalog. Falls back to the raw "source · event" identifier — never to a
+ * blank string — when no catalog entry matches: a generic integration
+ * subscription event, or a preset that predates the catalog.
+ */
+export function workflowEventTriggerLabel(input) {
+    const source = input.source?.trim() || null;
+    const event = input.event?.trim() || null;
+    const entry = source && event
+        ? matchWorkspaceEventCatalogEntry({ source, event, filters: input.filters })
+        : null;
+    const rawIdentifier = source && event
+        ? `${source} · ${event}`
+        : source ?? event ?? "event";
+    return {
+        label: entry?.label ?? rawIdentifier,
+        matched: entry !== null,
+        group: entry?.group ?? null,
+    };
+}

package/node_modules/@oxygen/workflows/dist/graph/lint.js

@@ -67,7 +67,11 @@ export function lintWorkflowGraphManifest(value, options = {}) {
     if (!isNonEmptyString(value.source_hash)) {
         add("$.source_hash", "missing_source_hash", "Manifest source_hash is required.");
     }
-    const nodesSound = lintNodes(value.nodes, add, options);
+    // Built once and threaded through every value-ref check below: the second
+    // segment of a `steps.` / `loop.` path names a NODE, and that id is the one
+    // part of a hand-typed path this linter can always check.
+    const scope = nodeScopeIndex(value.nodes);
+    const nodesSound = lintNodes(value.nodes, add, scope, options);
     const edgesSound = lintEdges(value.edges, value.nodes, add);
     // Graph-level analysis dereferences every node and edge, so it only runs once
     // the element shapes are known good. Reporting "unreachable" on a manifest
@@ -104,12 +108,21 @@ function lintWorkflowMetadata(workflow, add) {
         add("$.workflow.status", "invalid_workflow_status", "Workflow status must be active or disabled.");
     }
 }
-// ---------------------------------------------------------------------------
-// Nodes
-// ---------------------------------------------------------------------------
+function nodeScopeIndex(value) {
+    const ids = new Set();
+    const loops = new Set();
+    for (const node of asArray(value) ?? []) {
+        if (!isRecord(node) || !isNonEmptyString(node.id))
+            continue;
+        ids.add(node.id);
+        if (node.kind === "loop")
+            loops.add(node.id);
+    }
+    return { ids, loops };
+}
 /** Returns true when every node is shaped well enough for topology analysis. */
 function lintNodes(// skipcq: JS-R1005
-value, add, options) {
+value, add, scope, options) {
     const nodes = asArray(value);
     if (!nodes || nodes.length === 0) {
         add("$.nodes", "missing_nodes", "At least one workflow node is required.");
@@ -133,7 +146,7 @@ value, add, options) {
             add(`${path}.kind`, "invalid_node_kind", `Node kind must be one of ${[...NODE_KINDS].join(", ")}.`);
             return;
         }
-        lintNodeByKind(node, path, add, options);
+        lintNodeByKind(node, path, add, scope, options);
     });
     if (triggerCount === 0) {
         add("$.nodes", "missing_trigger_node", "A workflow graph requires exactly one trigger node.");
@@ -210,21 +223,21 @@ function lintNodeRetry(node, path, add) {
     }
 }
 function lintNodeByKind(// skipcq: JS-R1005
-node, path, add, options) {
+node, path, add, scope, options) {
     switch (node.kind) {
         case "trigger":
             return;
         case "tool":
-            lintToolNode(node, path, add, options);
+            lintToolNode(node, path, add, scope, options);
             return;
         case "filter":
-            validateCondition(node.when, `${path}.when`, add);
+            validateCondition(node.when, `${path}.when`, add, scope);
             return;
         case "switch":
-            lintSwitchNode(node, path, add);
+            lintSwitchNode(node, path, add, scope);
             return;
         case "loop":
-            lintLoopNode(node, path, add);
+            lintLoopNode(node, path, add, scope);
             return;
         case "merge":
             if (typeof node.strategy !== "string" || !MERGE_STRATEGIES.has(node.strategy)) {
@@ -232,13 +245,13 @@ node, path, add, options) {
             }
             return;
         case "set":
-            lintSetNode(node, path, add);
+            lintSetNode(node, path, add, scope);
             return;
         case "wait":
-            lintWaitNode(node, path, add);
+            lintWaitNode(node, path, add, scope);
             return;
         case "approval":
-            lintApprovalNode(node, path, add);
+            lintApprovalNode(node, path, add, scope);
             return;
         case "code":
             // v2 `code` nodes run through the same sandbox as v1 transform steps, so
@@ -254,7 +267,7 @@ node, path, add, options) {
             if (!isNonEmptyString(node.workflow_id)) {
                 add(`${path}.workflow_id`, "invalid_workflow_ref", "Workflow node workflow_id is required.");
             }
-            validateValueRefRecord(node.input, `${path}.input`, add);
+            validateValueRefRecord(node.input, `${path}.input`, add, scope);
             // Authoring-time refusal, not just a runtime one. A sub-workflow needs its
             // own durable run, lease, spend ceiling and cancellation semantics, none of
             // which exist yet — so the worker rejects the node terminally. Without this
@@ -267,7 +280,7 @@ node, path, add, options) {
             return;
     }
 }
-function lintToolNode(node, path, add, options) {
+function lintToolNode(node, path, add, scope, options) {
     if (!isNonEmptyString(node.tool)) {
         add(`${path}.tool`, "missing_tool", "Tool node tool id is required.");
     }
@@ -339,9 +352,9 @@ function lintToolNode(node, path, add, options) {
         add(`${path}.connection_id`, "invalid_connection_id", "Tool node connection_id must be a non-empty string.");
     }
     validateOptionalMaxCredits(node.max_credits, `${path}.max_credits`, add);
-    validateValueRefRecord(node.params, `${path}.params`, add);
+    validateValueRefRecord(node.params, `${path}.params`, add, scope);
 }
-function lintSwitchNode(node, path, add) {
+function lintSwitchNode(node, path, add, scope) {
     const cases = asArray(node.cases);
     if (!cases || cases.length === 0) {
         add(`${path}.cases`, "invalid_switch_case", "Switch node requires at least one case.");
@@ -374,11 +387,11 @@ function lintSwitchNode(node, path, add) {
         if (!isNonEmptyString(entry.label)) {
             add(`${casePath}.label`, "invalid_switch_case", "Switch case label is required.");
         }
-        validateCondition(entry.when, `${casePath}.when`, add);
+        validateCondition(entry.when, `${casePath}.when`, add, scope);
     });
 }
-function lintLoopNode(node, path, add) {
-    validateValueRef(node.over, `${path}.over`, add);
+function lintLoopNode(node, path, add, scope) {
+    validateValueRef(node.over, `${path}.over`, add, scope);
     if (node.item_name !== undefined && !isNonEmptyString(node.item_name)) {
         add(`${path}.item_name`, "invalid_value_ref", "Loop item_name must be a non-empty string.");
     }
@@ -398,7 +411,7 @@ function lintLoopNode(node, path, add) {
         add(`${path}.concurrency`, "invalid_loop_target", "Loop concurrency must be a positive integer.");
     }
 }
-function lintSetNode(node, path, add) {
+function lintSetNode(node, path, add, scope) {
     const fields = asArray(node.fields);
     if (!fields || fields.length === 0) {
         add(`${path}.fields`, "invalid_set_field", "Set node requires at least one field.");
@@ -416,16 +429,22 @@ function lintSetNode(node, path, add) {
         else if (RESERVED_NODE_IDS.has(field.key)) {
             add(`${fieldPath}.key`, "invalid_set_field", `Set field key '${field.key}' is reserved and would be dropped from the node output.`);
         }
-        validateValueRef(field.value, `${fieldPath}.value`, add);
+        validateValueRef(field.value, `${fieldPath}.value`, add, scope);
     });
 }
-function lintApprovalNode(node, path, add) {
+function lintApprovalNode(node, path, add, scope) {
+    // A blank `reason` is deliberately NOT refused here. It leaves the approver
+    // guessing, but it is legal and every gate saved to date is missing one — so
+    // the nudge lives in the editor's warning layer (graphWarnings in
+    // apps/web/src/lib/workflows/graph-ops.ts), where it can be said without
+    // making an existing workflow unsaveable.
     if (node.reason !== undefined)
-        validateValueRef(node.reason, `${path}.reason`, add);
-    if (node.request !== undefined)
-        validateValueRefRecord(node.request, `${path}.request`, add);
+        validateValueRef(node.reason, `${path}.reason`, add, scope);
+    if (node.request !== undefined) {
+        validateValueRefRecord(node.request, `${path}.request`, add, scope);
+    }
 }
-function lintWaitNode(node, path, add) {
+function lintWaitNode(node, path, add, scope) {
     const hasDuration = node.duration_seconds !== undefined;
     const hasUntil = node.until !== undefined;
     if (hasDuration === hasUntil) {
@@ -440,7 +459,7 @@ function lintWaitNode(node, path, add) {
         }
         return;
     }
-    validateValueRef(node.until, `${path}.until`, add);
+    validateValueRef(node.until, `${path}.until`, add, scope);
 }
 function isPositiveInteger(value) {
     return typeof value === "number" && Number.isInteger(value) && value > 0;
@@ -593,7 +612,7 @@ function lintGraphTopology(graph, add) {
 // ---------------------------------------------------------------------------
 // Value refs and conditions
 // ---------------------------------------------------------------------------
-function validateValueRefRecord(value, path, add) {
+function validateValueRefRecord(value, path, add, scope) {
     if (value === undefined) {
         add(path, "invalid_value_ref", "Node bindings are required.");
         return;
@@ -603,10 +622,11 @@ function validateValueRefRecord(value, path, add) {
         return;
     }
     for (const [key, entry] of Object.entries(value)) {
-        validateValueRef(entry, `${path}.${key}`, add);
+        validateValueRef(entry, `${path}.${key}`, add, scope);
     }
 }
-function validateValueRef(value, path, add) {
+function validateValueRef(// skipcq: JS-R1005
+value, path, add, scope) {
     if (!isRecord(value)) {
         add(path, "invalid_value_ref", "Value ref must be an object.");
         return;
@@ -626,21 +646,21 @@ function validateValueRef(value, path, add) {
             // Only OUR tokens are checked: `{{column}}`, `{{RANDOM|a|b}}` and other
             // foreign templating share the delimiters, travel inside these same
             // parameters, and are none of the linter's business.
-            validateStructuredLiteralPaths(value.value, `${path}.value`, add);
+            validateStructuredLiteralPaths(value.value, `${path}.value`, add, scope);
             return;
         case "template":
             if (typeof value.value !== "string") {
                 add(`${path}.value`, "invalid_value_ref", "Template value ref requires a string.");
                 return;
             }
-            validateTemplatePaths(value.value, `${path}.value`, add);
+            validateTemplatePaths(value.value, `${path}.value`, add, scope);
             return;
         case "ref":
             if (!isNonEmptyString(value.path)) {
                 add(`${path}.path`, "invalid_value_ref", "Ref value ref requires a path.");
                 return;
             }
-            validateScopePath(value.path, `${path}.path`, add);
+            validateScopePath(value.path, `${path}.path`, add, scope);
             return;
         case "formula":
             if (!isNonEmptyString(value.expression)) {
@@ -673,7 +693,7 @@ function validateValueRef(value, path, add) {
             add(`${path}.type`, "invalid_value_ref", "Value ref type is invalid.");
     }
 }
-function validateScopePath(path, issuePath, add) {
+function validateScopePath(path, issuePath, add, scope) {
     const segments = parseScopePath(path);
     if (!segments) {
         add(issuePath, "invalid_value_ref", `Path '${path}' is not a valid scope path (it is malformed or reaches a reserved key).`);
@@ -682,6 +702,49 @@ function validateScopePath(path, issuePath, add) {
     const root = segments[0] ?? "";
     if (!SCOPE_PATH_ROOTS.has(root)) {
         add(issuePath, "invalid_value_ref", `Path '${path}' must start with ${[...SCOPE_PATH_ROOTS].join(", ")}.`);
+        return;
+    }
+    validateScopeNodeId(path, segments, issuePath, add, scope);
+}
+/**
+ * The node a `steps.` / `loop.` path reads from must exist.
+ *
+ * Checking only the ROOT, as this linter did until this rule landed, let
+ * `steps.doesnotexist.output` and `steps.enrich.otuput` both save, publish, and
+ * resolve to `undefined` mid-run with nothing reported anywhere — a silent
+ * wrong-answer, since a missing binding is indistinguishable from a provider
+ * that returned nothing. Authors reach for the free-text path constantly,
+ * because most Oxygen tools publish no output schema and the guided picker can
+ * only offer "Whole output" until the workflow has run once.
+ *
+ * DELIBERATELY STOPS AT THE NODE ID. The field after it is not checked and must
+ * not be: the manifest carries no output schema for a tool, so
+ * `steps.enrich.output.anything` is a legitimate binding whose shape is only
+ * known once the tool answers. Flagging it would refuse correct workflows, which
+ * is strictly worse than the silence this rule removes. The id is the part that
+ * is always knowable, and it is where a typo is unrecoverable.
+ *
+ * Upstream-ness is deliberately NOT checked either. A ref to a node that has not
+ * run resolves to `undefined` just as surely, but "has run" is not a static
+ * property of the graph: a body node's outputs survive its loop under a keyed
+ * step id, a `fallthrough` switch runs several branches, and an author normally
+ * configures a node before wiring it in. Every one of those is a legitimate
+ * graph that a reachability rule would refuse.
+ */
+function validateScopeNodeId(path, segments, issuePath, add, scope) {
+    const root = segments[0];
+    if (root !== "steps" && root !== "loop")
+        return; // `trigger` names no node.
+    const id = segments[1];
+    // A bare `steps` / `loop` is the whole scope object, not a reference to a node.
+    if (id === undefined)
+        return;
+    if (!scope.ids.has(id)) {
+        add(issuePath, "unknown_node_ref", `Path '${path}' reads from node '${id}', which this workflow does not have. Check the node id.`);
+        return;
+    }
+    if (root === "loop" && !scope.loops.has(id)) {
+        add(issuePath, "unknown_node_ref", `Path '${path}' reads a loop item from node '${id}', which is not a loop node.`);
     }
 }
 /** Paths inside a context value have no scope root — only syntax to check. */
@@ -690,12 +753,12 @@ function validateOptionalRefPath(path, issuePath, add) {
         add(issuePath, "invalid_value_ref", "Context path is malformed or reaches a reserved key.");
     }
 }
-function validateTemplatePaths(template, issuePath, add) {
+function validateTemplatePaths(template, issuePath, add, scope) {
     for (const match of template.matchAll(/\{\{([^{}]*)\}\}/g)) {
         const path = (match[1] ?? "").trim();
         // "{{}}" is literal text by design, so it is not a binding to validate.
         if (path)
-            validateScopePath(path, issuePath, add);
+            validateScopePath(path, issuePath, add, scope);
     }
 }
 /**
@@ -718,7 +781,7 @@ function validateTemplatePaths(template, issuePath, add) {
  * empty string. Guessing which of `{{lop.x}}` and `{{company}}` was meant to be
  * ours is not something a linter can do correctly.
  */
-function validateStructuredLiteralPaths(value, issuePath, add, depth = 0) {
+function validateStructuredLiteralPaths(value, issuePath, add, scope, depth = 0) {
     if (depth > 12)
         return;
     if (typeof value === "string") {
@@ -731,24 +794,25 @@ function validateStructuredLiteralPaths(value, issuePath, add, depth = 0) {
                 continue;
             const root = path.split(/[.[]/, 1)[0];
             if (root !== undefined && SCOPE_PATH_ROOTS.has(root)) {
-                validateScopePath(path, issuePath, add);
+                validateScopePath(path, issuePath, add, scope);
             }
         }
         return;
     }
     if (Array.isArray(value)) {
-        for (const entry of value)
-            validateStructuredLiteralPaths(entry, issuePath, add, depth + 1);
+        for (const entry of value) {
+            validateStructuredLiteralPaths(entry, issuePath, add, scope, depth + 1);
+        }
         return;
     }
     if (isRecord(value)) {
         for (const entry of Object.values(value)) {
-            validateStructuredLiteralPaths(entry, issuePath, add, depth + 1);
+            validateStructuredLiteralPaths(entry, issuePath, add, scope, depth + 1);
         }
     }
 }
 function validateCondition(// skipcq: JS-R1005
-value, path, add, depth = 0) {
+value, path, add, scope, depth = 0) {
     if (!isRecord(value)) {
         add(path, "invalid_condition", "Condition must be an object.");
         return;
@@ -764,17 +828,33 @@ value, path, add, depth = 0) {
         if (value.not !== undefined && typeof value.not !== "boolean") {
             add(`${path}.not`, "invalid_condition", "Condition group not must be a boolean.");
         }
-        if (!Array.isArray(value.children) || value.children.length === 0) {
+        // An empty group is refused EXCEPT the one form that is vacuously TRUE:
+        // `all` with no children and no `not`, which evaluateCondition returns true
+        // for by the Array.every identity (expression.ts). That form is how a
+        // switch spells an "otherwise" arm — a final always-matching case which,
+        // because switch is first-match-wins, fires only when nothing above did.
+        //
+        // The other two empty shapes stay refused BECAUSE they are the opposite:
+        // empty `any` is vacuously false, and empty `all` inverted by `not` is
+        // false too, so either one is an arm that can never fire — the same silent
+        // dead end this rule exists to prevent, wearing different clothes.
+        if (!Array.isArray(value.children)) {
             add(`${path}.children`, "invalid_condition", "Condition group requires at least one child.");
             return;
         }
+        if (value.children.length === 0 && !(value.op === "all" && value.not !== true)) {
+            add(`${path}.children`, "invalid_condition", value.op === "any"
+                ? "An empty 'any' group never matches, so this arm could never run. Add a condition, or use an empty 'all' group as a catch-all."
+                : "An inverted empty group never matches, so this arm could never run. Remove the inversion to make it a catch-all.");
+            return;
+        }
         value.children.forEach((child, index) => {
-            validateCondition(child, `${path}.children.${index}`, add, depth + 1);
+            validateCondition(child, `${path}.children.${index}`, add, scope, depth + 1);
         });
         return;
     }
     if (value.type === "compare") {
-        validateValueRef(value.left, `${path}.left`, add);
+        validateValueRef(value.left, `${path}.left`, add, scope);
         if (!isCompareOp(value.op)) {
             add(`${path}.op`, "invalid_condition", "Condition compare op is invalid.");
             return;
@@ -789,7 +869,7 @@ value, path, add, depth = 0) {
             add(`${path}.right`, "invalid_condition", `Operator '${value.op}' requires a right operand.`);
             return;
         }
-        validateValueRef(value.right, `${path}.right`, add);
+        validateValueRef(value.right, `${path}.right`, add, scope);
         if (value.op === "matches")
             validateMatchPattern(value.right, `${path}.right`, add);
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxygen-agent/cli",
-  "version": "1.627.4",
+  "version": "1.632.1",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",