@knowttl/checkpoint-axi 0.1.2 → 0.1.4

package/README.md

@@ -59,6 +59,9 @@ Use the hook, the skill or both; neither is required for ordinary CLI use.
 Start investigations with the compact [agent guide](docs/agent-guide.md), linked from [SKILL.md](skills/checkpoint-axi/SKILL.md).
 Use the [command reference](docs/commands.md) for the full catalogue.
 
+Email search and event list support opt-in read-only detail expansion with `--expand`.
+See [bounded detail expansion](docs/reads.md#bounded-detail-expansion) for limits, shared budgets, partial results and examples.
+
 ## What it covers
 
 <!-- command-registry:start -->
@@ -73,7 +76,15 @@ Use the [command reference](docs/commands.md) for the full catalogue.
 | exception | Inspect eight kinds; preview or request supported rule changes | Read / gated write | [Guide](docs/writes.md) |
 | home | Show local profile context without resolving secrets | Local read | [Guide](docs/configuration.md) |
 | profile | List named file profiles | Local read | [Guide](docs/configuration.md) |
-| task | Inspect asynchronous action status without polling | Read | [Guide](docs/reads.md#event-and-task-reads) |
+| task | Inspect asynchronous action status once or with bounded read-only waiting | Read | [Guide](docs/reads.md#event-and-task-reads) |
+
+Task show reads once by default; use task show <id> --wait --timeout 30 for bounded read-only polling.
+--timeout is required with --wait (integer seconds, range 1-60); --poll-interval defaults to 2 seconds (range 1-10), and --wait-requests defaults to 10 total HTTP requests (range 2-10), including auth and retries.
+Wait stops on completed, failed or stopped; init, inprogress and paused remain non-terminal.
+The task snapshot contains the final status; wait reports terminal, polls (validated status snapshots) and reason (terminal, timeout or budget).
+A non-terminal stop exits 0 with the last snapshot and a read-only next-step hint; inspect wait even on exit 0 and include task,wait,help with --fields.
+Timeout covers auth, requests, retries and delays within the shared 8 MiB response cap; failures before any snapshot remain errors.
+Waiting never resubmits an action or changes remote state; a failed or stopped task is terminal, not successful execution.
 
 Email search --filter accepts a JSON array of {saasAttrName, saasAttrOp, saasAttrValue}.
 saasAttrName is a field path, not a closed enum (guide pages 19-20).

package/dist/src/catalogue.d.ts

@@ -1,7 +1,15 @@
+export declare const FILTER_OPERATORS: readonly ["is", "contains", "startsWith", "isEmpty", "isNot", "notContains", "isNotEmpty", "greaterThan", "lessThan"];
 export declare const DESCRIPTION = "Inspect Check Point Email Security through compact, guarded AXI commands";
 export declare const SETUP_GUIDANCE = "Run checkpoint-axi config path; configure a region, clientId and clientSecret env/file SecretRef";
+export declare const TASK_WAIT_GUIDANCE: string;
+export declare const DETAIL_EXPANSION_GUIDANCE: string;
 export declare const EMAIL_PAYLOAD_ATTRIBUTES: string[];
 export declare const EMAIL_FILTER_GUIDANCE: string;
+export declare const EVENT_STATES: readonly ["new", "detected", "pending", "remediated", "dismissed", "exception"];
+export declare const LIST_ROW_FIELDS: {
+    readonly "email search": readonly ["id", "subject", "state", "verdict"];
+    readonly "event list": readonly ["id", "type", "state", "severity"];
+};
 export declare const catalogue: {
     readonly "email download": {
         readonly description: "Download an email to a new private file with profile opt-in, a 50 MiB cap and mandatory SHA-256 verification; scopes and email hash availability are unverified (guide pages 131-132)";
@@ -187,13 +195,18 @@ export declare const catalogue: {
     readonly "event list": {
         readonly description: "List security events with bounded scroll continuation (API guide pages 37-42)";
         readonly flags: {
+            readonly fields: `Comma-separated row fields: ${string}; or top-level events,count,total,complete,reason,cursor,expansion,help; default all`;
             readonly saas: "Comma-separated SaaS overrides; default selected profile saas or office365_emails";
             readonly "event-types": "Comma-separated event types; default unfiltered";
-            readonly "event-states": "Comma-separated event states; default unfiltered";
-            readonly severities: "Comma-separated severities; default unfiltered";
+            readonly "event-states": `Comma-separated event states: ${string}; default unfiltered`;
+            readonly states: "Alias for --event-states; cannot combine with --event-states";
+            readonly severities: "Nonempty comma-separated severity strings; vendor documents no fixed severity list; unrecognised severities can return an empty result; default unfiltered";
             readonly "event-ids": "Comma-separated event IDs; default unfiltered";
             readonly "confidence-indicator": "Confidence indicator selector; default unfiltered";
             readonly description: "Description selector; default unfiltered";
+            readonly expand: string;
+            readonly "expand-limit": string;
+            readonly "expand-requests": string;
             readonly "start-date": string;
             readonly "end-date": string;
             readonly limit: string;
@@ -201,11 +214,10 @@ export declare const catalogue: {
             readonly cursor: string;
             readonly config: string;
             readonly profile: string;
-            readonly fields: string;
             readonly full: string;
             readonly help: string;
         };
-        readonly examples: readonly ["checkpoint-axi event list", "checkpoint-axi event list --all --event-types phishing", "checkpoint-axi event list --cursor <cursor>"];
+        readonly examples: readonly ["checkpoint-axi event list", "checkpoint-axi event list --limit 5 --expand --event-types phishing", "checkpoint-axi event list --cursor <cursor>"];
     };
     readonly "event show": {
         readonly description: "Show one event, actions taken and available actions (API guide pages 34-37)";
@@ -219,34 +231,41 @@ export declare const catalogue: {
         readonly examples: readonly ["checkpoint-axi event show <id>", "checkpoint-axi event show <id> --full"];
     };
     readonly "task show": {
-        readonly description: "Show asynchronous task status and per-action details (API guide pages 30-33)";
+        readonly description: "Show asynchronous task status and per-action details, optionally waiting within explicit bounds (API guide pages 30-33)";
         readonly flags: {
-            config: string;
-            profile: string;
-            fields: string;
-            full: string;
-            help: string;
+            readonly wait: "Poll existing task status only; default false; requires --timeout; terminal: completed, failed, stopped";
+            readonly timeout: "Total wait timeout in integer seconds, range 1-60; required with --wait; includes auth and retries";
+            readonly "poll-interval": "Seconds between status reads; default 2, range 1-10; requires --wait";
+            readonly "wait-requests": "Total HTTP request cap including auth and retries; default 10, range 2-10; requires --wait";
+            readonly config: string;
+            readonly profile: string;
+            readonly fields: string;
+            readonly full: string;
+            readonly help: string;
         };
-        readonly examples: readonly ["checkpoint-axi task show <id>", "checkpoint-axi task show <id> --full"];
+        readonly examples: readonly ["checkpoint-axi task show <id>", "checkpoint-axi task show <id> --wait --timeout 30 --fields task,wait,help", "checkpoint-axi task show <id> --full"];
     };
     readonly "email search": {
         readonly description: "Search emails with a bounded date window and scroll continuation (API guide pages 18-27)";
         readonly flags: {
             readonly filter: `JSON array of {saasAttrName, saasAttrOp, saasAttrValue} filters. ${string}`;
+            readonly expand: string;
+            readonly "expand-limit": string;
+            readonly "expand-requests": string;
             readonly "start-date": string;
             readonly "end-date": string;
             readonly limit: string;
             readonly all: string;
             readonly cursor: string;
+            readonly fields: `Comma-separated row fields: ${string}; or top-level emails,count,total,complete,reason,cursor,expansion,help; default all`;
             readonly saas: "SaaS override; default selected profile saas or office365_emails";
             readonly "saas-entity": "Optional SaaS entity type selector";
             readonly config: string;
             readonly profile: string;
-            readonly fields: string;
             readonly full: string;
             readonly help: string;
         };
-        readonly examples: readonly ["checkpoint-axi email search", "checkpoint-axi email search --all --saas office365_emails", "checkpoint-axi email search --cursor <cursor>"];
+        readonly examples: readonly ["checkpoint-axi email search", "checkpoint-axi email search --limit 5 --expand --saas office365_emails", "checkpoint-axi email search --cursor <cursor>"];
     };
     readonly "email show": {
         readonly description: "Show one email with verdicts, actions and available actions (API guide pages 10-18)";

package/dist/src/catalogue.js

@@ -1,11 +1,29 @@
 import { exceptionFamilies } from "./exceptions.js";
+export const FILTER_OPERATORS = ["is", "contains", "startsWith", "isEmpty", "isNot", "notContains", "isNotEmpty", "greaterThan", "lessThan"];
 export const DESCRIPTION = "Inspect Check Point Email Security through compact, guarded AXI commands";
 export const SETUP_GUIDANCE = "Run checkpoint-axi config path; configure a region, clientId and clientSecret env/file SecretRef";
+export const TASK_WAIT_GUIDANCE = "Task show reads once by default; use task show <id> --wait --timeout 30 for bounded read-only polling.\n"
+    + "--timeout is required with --wait (integer seconds, range 1-60); --poll-interval defaults to 2 seconds (range 1-10), and --wait-requests defaults to 10 total HTTP requests (range 2-10), including auth and retries.\n"
+    + "Wait stops on completed, failed or stopped; init, inprogress and paused remain non-terminal.\n"
+    + "The task snapshot contains the final status; wait reports terminal, polls (validated status snapshots) and reason (terminal, timeout or budget).\n"
+    + "A non-terminal stop exits 0 with the last snapshot and a read-only next-step hint; inspect wait even on exit 0 and include task,wait,help with --fields.\n"
+    + "Timeout covers auth, requests, retries and delays within the shared 8 MiB response cap; failures before any snapshot remain errors.\n"
+    + "Waiting never resubmits an action or changes remote state; a failed or stopped task is terminal, not successful execution.";
+export const DETAIL_EXPANSION_GUIDANCE = "Email search and event list accept --expand for read-only show details in each successful row's detail field.\n"
+    + "Expansion is off by default; --expand-limit caps detail attempts (default 5, range 1-8), and --expand-requests caps total HTTP requests (default 10, range 2-10), including auth, list pages and retries.\n"
+    + "Both limit flags require --expand; listing runs first and shares the 60-second and 8 MiB transport budgets with detail reads.\n"
+    + "Inspect the expansion object's expanded, complete and notExpanded fields for every unexpanded ID and its reason: item-cap-reached, request-cap-reached, budget-exhausted or per-item-error (with an error code).\n"
+    + "Partial expansion keeps every list row and successful detail; list complete/cursor describe pagination separately.\n"
+    + "Use --fields emails,expansion or --fields events,expansion to retain expansion status; --full restores full strings after redaction.\n"
+    + "With --all, list pages can consume the entire request budget before any detail is expanded; reduce the list limit or use individual show reads for remaining IDs.\n"
+    + "Expansion never downloads files, invokes available actions or changes remote state.";
 export const EMAIL_PAYLOAD_ATTRIBUTES = ["subject", "fromEmail", "attachmentCount", "internetMessageId", "received", "size", "emailLinks", "attachments", "mode", "recipients", "fromDomain", "fromUser", "fromName", "to", "toUser", "cc", "ccUser", "bcc", "bccUser", "replyToEmail", "replyToNickname", "isRead", "isDeleted", "isIncoming", "isInternal", "isOutgoing", "isQuarantined", "isQuarantineNotification", "isRestored", "isRestoreRequested", "isRestoreDeclined", "saasSpamVerdict", "SpfResult"].map((name) => `entityPayload.${name}`);
 export const EMAIL_FILTER_GUIDANCE = "saasAttrName is a field path, not a closed enum (guide pages 19-20). Documented examples: "
     + EMAIL_PAYLOAD_ATTRIBUTES.slice(0, 3).join(", ") + ". Other documented email payload paths (pages 15-16, 24-25): "
     + EMAIL_PAYLOAD_ATTRIBUTES.slice(3).join(", ")
-    + ". saasAttrOp: is, contains, startsWith, isEmpty, isNot, notContains, isNotEmpty, greaterThan, lessThan. The guide defines operators globally, without a per-field compatibility matrix; examples pair fromEmail with is and attachmentCount with greaterThan. saasAttrValue is a string.";
+    + `. saasAttrOp: ${FILTER_OPERATORS.join(", ")}. The guide defines operators globally, without a per-field compatibility matrix; examples pair fromEmail with is and attachmentCount with greaterThan. saasAttrValue is a string.`;
+export const EVENT_STATES = ["new", "detected", "pending", "remediated", "dismissed", "exception"];
+export const LIST_ROW_FIELDS = { "email search": ["id", "subject", "state", "verdict"], "event list": ["id", "type", "state", "severity"] };
 const common = {
     config: "Config path; default CHECKPOINT_AXI_CONFIG or platform path",
     profile: "Profile name; default CHECKPOINT_AXI_PROFILE, env profile, config default, or sole profile",
@@ -21,6 +39,11 @@ const paging = {
     cursor: "Opaque continuation bound to profile, region, operation and selectors; repeat original selectors",
 };
 const exceptionType = `Required for ${["malware", "url", "dlp"].map((kind) => `${kind}: ${exceptionFamilies[kind].types.join(",")}`).join("; ")}`;
+const expansion = {
+    expand: "Opt in to read-only show details on returned rows; default false; partial expansion is reported separately",
+    "expand-limit": "Maximum detail attempts; default 5, range 1-8; requires --expand",
+    "expand-requests": "Total HTTP request cap including auth, list pages, detail and retries; default 10, range 2-10; requires --expand",
+};
 const writeFlags = { ...common,
     ids: "Required comma-separated unique entity IDs; maximum 20",
     execute: "Send once after all write gates; default false (preview)",
@@ -70,25 +93,32 @@ export const catalogue = {
     "exception show": { description: "Show an exception by kind and ID/value; anomaly refuses ENDPOINT_UNVERIFIED pending commissioning (guide pages 52-123)",
         flags: { ...common, type: exceptionType, items: "Click-time item route instead of list route; default false" },
         examples: ["checkpoint-axi exception show phishing-block <id>", "checkpoint-axi exception show url <value> --type allow-url", "checkpoint-axi exception show click-time <id> --items --full"] },
-    "event list": { description: "List security events with bounded scroll continuation (API guide pages 37-42)", flags: { ...common, ...paging,
+    "event list": { description: "List security events with bounded scroll continuation (API guide pages 37-42)", flags: { ...common, ...paging, ...expansion,
+            fields: `Comma-separated row fields: ${LIST_ROW_FIELDS["event list"].join(",")}; or top-level events,count,total,complete,reason,cursor,expansion,help; default all`,
             saas: "Comma-separated SaaS overrides; default selected profile saas or office365_emails",
             "event-types": "Comma-separated event types; default unfiltered",
-            "event-states": "Comma-separated event states; default unfiltered",
-            severities: "Comma-separated severities; default unfiltered",
+            "event-states": `Comma-separated event states: ${EVENT_STATES.join(", ")}; default unfiltered`,
+            states: "Alias for --event-states; cannot combine with --event-states",
+            severities: "Nonempty comma-separated severity strings; vendor documents no fixed severity list; unrecognised severities can return an empty result; default unfiltered",
             "event-ids": "Comma-separated event IDs; default unfiltered",
             "confidence-indicator": "Confidence indicator selector; default unfiltered",
             description: "Description selector; default unfiltered",
-        }, examples: ["checkpoint-axi event list", "checkpoint-axi event list --all --event-types phishing", "checkpoint-axi event list --cursor <cursor>"] },
+        }, examples: ["checkpoint-axi event list", "checkpoint-axi event list --limit 5 --expand --event-types phishing", "checkpoint-axi event list --cursor <cursor>"] },
     "event show": { description: "Show one event, actions taken and available actions (API guide pages 34-37)", flags: common,
         examples: ["checkpoint-axi event show <id>", "checkpoint-axi event show <id> --full"] },
-    "task show": { description: "Show asynchronous task status and per-action details (API guide pages 30-33)", flags: common,
-        examples: ["checkpoint-axi task show <id>", "checkpoint-axi task show <id> --full"] },
+    "task show": { description: "Show asynchronous task status and per-action details, optionally waiting within explicit bounds (API guide pages 30-33)", flags: { ...common,
+            wait: "Poll existing task status only; default false; requires --timeout; terminal: completed, failed, stopped",
+            timeout: "Total wait timeout in integer seconds, range 1-60; required with --wait; includes auth and retries",
+            "poll-interval": "Seconds between status reads; default 2, range 1-10; requires --wait",
+            "wait-requests": "Total HTTP request cap including auth and retries; default 10, range 2-10; requires --wait",
+        }, examples: ["checkpoint-axi task show <id>", "checkpoint-axi task show <id> --wait --timeout 30 --fields task,wait,help", "checkpoint-axi task show <id> --full"] },
     "email search": { description: "Search emails with a bounded date window and scroll continuation (API guide pages 18-27)", flags: { ...common,
+            fields: `Comma-separated row fields: ${LIST_ROW_FIELDS["email search"].join(",")}; or top-level emails,count,total,complete,reason,cursor,expansion,help; default all`,
             saas: "SaaS override; default selected profile saas or office365_emails",
             "saas-entity": "Optional SaaS entity type selector",
-            ...paging,
+            ...paging, ...expansion,
             filter: `JSON array of {saasAttrName, saasAttrOp, saasAttrValue} filters. ${EMAIL_FILTER_GUIDANCE}`,
-        }, examples: ["checkpoint-axi email search", "checkpoint-axi email search --all --saas office365_emails", "checkpoint-axi email search --cursor <cursor>"] },
+        }, examples: ["checkpoint-axi email search", "checkpoint-axi email search --limit 5 --expand --saas office365_emails", "checkpoint-axi email search --cursor <cursor>"] },
     "email show": { description: "Show one email with verdicts, actions and available actions (API guide pages 10-18)", flags: common,
         examples: ["checkpoint-axi email show <id>", "checkpoint-axi email show <id> --full"] },
     doctor: { description: "Check regional API authentication and one bounded email search without printing tenant data", flags: { ...common, saas: "SaaS override; default selected profile saas or office365_emails" },

package/dist/src/local-commands.js

@@ -1,7 +1,7 @@
 import { AxiError } from "axi-sdk-js";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
-import { catalogue, DESCRIPTION, help, SETUP_GUIDANCE } from "./catalogue.js";
+import { catalogue, DESCRIPTION, help, LIST_ROW_FIELDS, SETUP_GUIDANCE } from "./catalogue.js";
 import { doctor } from "./doctor.js";
 import { readCommand } from "./reads.js";
 import { exceptionCommand } from "./exceptions.js";
@@ -38,7 +38,7 @@ export async function localCommand(argv, store, transport) {
             const label = flag.split("=")[0];
             usage(/^--[A-Za-z][A-Za-z0-9-]*$/.test(label) ? `Unknown or duplicate flag ${label}` : undefined);
         }
-        if (["--help", "--full", "--all", "--items", "--specific", "--original", "--execute", "--dry-run"].includes(flag))
+        if (["--help", "--full", "--all", "--expand", "--wait", "--items", "--specific", "--original", "--execute", "--dry-run"].includes(flag))
             flags.set(flag, "true");
         else {
             const value = argv[++index];
@@ -50,18 +50,25 @@ export async function localCommand(argv, store, transport) {
     if (flags.has("--help"))
         return { command: name, ...entry };
     const available = isException ? name === "exception list" ? ["exceptions", "count", "total", "complete", "reason", "responseSchema", "help"] : ["exception", "responseSchema"]
-        : name === "email search" || name === "event list" ? [name === "event list" ? "events" : "emails", "count", "total", "complete", "reason", "cursor", "help"] : name.endsWith(" show") ? [name.split(" ")[0]]
+        : name === "email search" || name === "event list" ? [name === "event list" ? "events" : "emails", "count", "total", "complete", "reason", "cursor", "expansion", "help"] : name.endsWith(" show") ? [name.split(" ")[0]]
             : name === "doctor" ? ["region", "saas", "checks", "pass", "help"] : name === "auth status" ? ["profile", "source", "region", "origin", "saas", "clientSecret", "readOnly"]
                 : name === "profile list" ? ["profiles", "count", "config"] : name === "config path" ? ["config", "state"]
                     : ["bin", "description", "status", "profiles", "count", "help"];
     const isWrite = name === "email quarantine" || name === "email restore" || name === "event action" || isExceptionWrite;
+    if (name === "task show")
+        available.push("wait", "help");
     if (isWrite)
         available.splice(0, available.length, "outcome", "preview", "auditId", "tasks", "response", "responseSchema", "help");
     if (isDownload)
         available.splice(0, available.length, "path", "size", "sha256");
-    const fields = flags.get("--fields")?.split(",") ?? available;
-    if (fields.some((field) => !available.includes(field)) || new Set(fields).size !== fields.length)
-        usage();
+    const rowFields = name === "email search" || name === "event list" ? LIST_ROW_FIELDS[name] : [];
+    const requested = flags.get("--fields")?.split(",") ?? available;
+    const columns = requested.filter((field) => rowFields.includes(field));
+    if (requested.some((field) => !available.includes(field) && !rowFields.includes(field)) || new Set(requested).size !== requested.length
+        || (columns.length > 0 && columns.length !== requested.length)) {
+        usage(`Invalid --fields; valid top-level fields: ${available.join(",")}${rowFields.length ? `; valid row fields: ${rowFields.join(",")}` : ""}`);
+    }
+    const fields = columns.length ? available : requested;
     const config = flags.get("--config");
     let result;
     if (isDownload)
@@ -103,6 +110,10 @@ export async function localCommand(argv, store, transport) {
             description: DESCRIPTION, status, profiles: listed.profiles, count: listed.count,
             help: [SETUP_GUIDANCE, "Run checkpoint-axi auth status to validate local credentials", "Run checkpoint-axi profile list to inspect configured profiles"] };
     }
+    if (columns.length) {
+        const key = name === "event list" ? "events" : "emails";
+        result[key] = result[key].map((row) => Object.fromEntries(columns.map((field) => [field, row[field]])));
+    }
     let truncated = false;
     const preview = (value) => {
         if (typeof value === "string" && value.length > 500 && !flags.has("--full")) {

package/dist/src/reads.js

@@ -1,22 +1,24 @@
 import { AxiError } from "axi-sdk-js";
 import { createHash } from "node:crypto";
+import { setTimeout as delay } from "node:timers/promises";
 import { z } from "zod";
 import { REGIONS } from "./regions.js";
 import { gateway, READ_LIMITS } from "./transport.js";
 import { responseInvalid } from "./response-invalid.js";
+import { EVENT_STATES, FILTER_OPERATORS } from "./catalogue.js";
 const day = 86_400_000;
 const timestamp = z.iso.datetime({ offset: true });
 const filters = z.array(z.strictObject({ saasAttrName: z.string().min(1),
-    saasAttrOp: z.enum(["is", "contains", "startsWith", "isEmpty", "isNot", "notContains", "isNotEmpty", "greaterThan", "lessThan"]),
+    saasAttrOp: z.enum(FILTER_OPERATORS),
     saasAttrValue: z.string() }));
 const continuation = z.strictObject({ version: z.literal(1), binding: z.string(), start: timestamp, end: timestamp,
     scroll: z.string().optional(), offset: z.number().int().nonnegative(), replayRisk: z.literal(true).optional() });
 // The guide's prose/table (pp.11,14) says security-result array; its JSON examples use an object.
 const securityResults = z.object({ combinedVerdict: z.unknown().optional() }).passthrough();
 // Entity schemas and SaaS-specific payloads: guide pages 11-15 and 21-24.
-const entity = z.object({ entityInfo: z.object({ entityId: z.string().min(1), entityActionState: z.string().optional() }).passthrough(),
+const entity = z.object({ entityInfo: z.object({ entityId: z.string().min(1), entityActionState: z.string().nullish().transform((value) => value ?? "unactioned") }).passthrough(),
     entityPayload: z.object({ subject: z.string().optional() }).passthrough(),
-    entitySecurityResults: z.union([securityResults, z.array(z.object({}).passthrough())]).optional(),
+    entitySecurityResults: z.union([securityResults, z.array(securityResults)]).optional(),
 }).passthrough();
 // Event and task fields: guide pages 31-32, 35-36 and 40-41.
 const event = z.object({ eventId: z.string().min(1), type: z.string(), state: z.string(), severity: z.string() }).passthrough();
@@ -30,12 +32,32 @@ export async function readCommand(name, id, flags, store, transport) {
     const isEvent = name.startsWith("event ");
     if (name.endsWith(" show") && (!id || !/^[A-Za-z0-9_-]+$/.test(id)))
         invalid(`${name} requires one ID containing letters, digits, underscores or hyphens`);
+    const waiting = flags.has("--wait");
+    if (!waiting && ["--timeout", "--poll-interval", "--wait-requests"].some((flag) => flags.has(flag)))
+        invalid("Wait limits require --wait");
+    const timeoutText = flags.get("--timeout") ?? "";
+    const intervalText = flags.get("--poll-interval") ?? "2";
+    const waitRequestsText = flags.get("--wait-requests") ?? "10";
+    if (waiting && (!/^[1-9][0-9]*$/.test(timeoutText) || Number(timeoutText) > 60))
+        invalid("--wait requires --timeout in integer seconds from 1 to 60");
+    if (!/^(?:[1-9]|10)$/.test(intervalText))
+        invalid("--poll-interval must be integer seconds from 1 to 10");
+    if (!/^(?:[2-9]|10)$/.test(waitRequestsText))
+        invalid("--wait-requests must be an integer from 2 to 10");
     const limitText = flags.get("--limit") ?? "50";
     if (!/^[1-9][0-9]*$/.test(limitText) || Number(limitText) > READ_LIMITS.rows)
         invalid("--limit must be an integer from 1 to 1000");
     if (flags.has("--all") && flags.has("--limit"))
         invalid("Use either --all or --limit");
     const limit = flags.has("--all") ? READ_LIMITS.rows : Number(limitText);
+    if (!flags.has("--expand") && (flags.has("--expand-limit") || flags.has("--expand-requests")))
+        invalid("Expansion limits require --expand");
+    const expandLimitText = flags.get("--expand-limit") ?? "5";
+    const expandRequestsText = flags.get("--expand-requests") ?? "10";
+    if (!/^[1-8]$/.test(expandLimitText))
+        invalid("--expand-limit must be an integer from 1 to 8");
+    if (!/^(?:[2-9]|10)$/.test(expandRequestsText))
+        invalid("--expand-requests must be an integer from 2 to 10");
     let extended;
     if (flags.has("--filter")) {
         let raw;
@@ -47,7 +69,7 @@ export async function readCommand(name, id, flags, store, transport) {
         }
         const parsed = filters.safeParse(raw);
         if (!parsed.success)
-            invalid("--filter must contain saasAttrName, a documented saasAttrOp and saasAttrValue");
+            invalid(`--filter must contain saasAttrName, saasAttrValue and saasAttrOp from: ${FILTER_OPERATORS.join(", ")}`);
         extended = parsed.data;
     }
     let cursor;
@@ -75,12 +97,19 @@ export async function readCommand(name, id, flags, store, transport) {
         if (flags.has(flag) && !flags.get(flag).trim())
             invalid(`${flag} must not be blank`);
     const eventSelectors = {};
+    if (flags.has("--states")) {
+        if (flags.has("--event-states"))
+            invalid("Use either --states or --event-states");
+        flags.set("--event-states", flags.get("--states"));
+    }
     for (const [flag, key] of [["event-types", "eventTypes"], ["event-states", "eventStates"], ["severities", "severities"], ["event-ids", "eventIds"], ["saas", "saas"]]) {
         if (!isEvent || !flags.has(`--${flag}`))
             continue;
         const values = flags.get(`--${flag}`).split(",").map((value) => value.trim());
         if (values.some((value) => !value))
-            invalid(`--${flag} must contain nonempty comma-separated values`);
+            invalid(`--${flag} must contain nonempty comma-separated ${flag === "severities" ? "severity strings" : "values"}`);
+        if (flag === "event-states" && values.some((value) => !EVENT_STATES.includes(value)))
+            invalid(`--event-states/--states must contain: ${EVENT_STATES.join(", ")}`);
         eventSelectors[key] = values;
     }
     for (const [flag, key] of [["confidence-indicator", "confidenceIndicator"], ["description", "description"]]) {
@@ -100,8 +129,14 @@ export async function readCommand(name, id, flags, store, transport) {
         origin: REGIONS[profile.region], operation: name, ...(isEvent ? { selectors } : { entityFilter, extended }) })).digest("hex");
     if (cursor && cursor.binding !== binding)
         invalid("Cursor does not match this profile, region or search selectors; repeat the original selectors");
-    const api = gateway(profile, store.credentials(profile, true), store.redactor, transport);
-    if (name.endsWith(" show")) {
+    const now = transport?.now ?? Date.now;
+    const wait = transport?.wait ?? delay;
+    const timeout = waiting ? Number(timeoutText) * 1_000 : READ_LIMITS.milliseconds;
+    const deadline = now() + timeout;
+    const api = gateway(profile, store.credentials(profile, true), store.redactor, transport, false, Number(waiting ? waitRequestsText : expandRequestsText), timeout);
+    async function detail(id) {
+        if (!/^[A-Za-z0-9_-]+$/.test(id))
+            throw new AxiError("Invalid detail ID", "RESPONSE_INVALID", []);
         const kind = name.split(" ")[0];
         const page = await api.read({ path: name === "task show" ? `/task/${id}` : isEvent ? `/event/${id}` : `/search/entity/${id}` });
         const response = { responseData: page.dataIsArray ? page.records : page.records[0] };
@@ -117,8 +152,43 @@ export async function readCommand(name, id, flags, store, transport) {
         const returnedId = name === "task show" ? String(record.id) : isEvent ? record.eventId : record.entityInfo?.entityId;
         if (returnedId !== id)
             throw responseInvalid(`Invalid ${kind} detail response`, response, [[...recordPath, ...(name === "task show" ? ["id"] : isEvent ? ["eventId"] : ["entityInfo", "entityId"])]]);
-        return { [kind]: parsed.data };
+        return parsed.data;
+    }
+    if (name === "task show" && waiting) {
+        let snapshot;
+        let polls = 0;
+        let reason;
+        for (;;) {
+            try {
+                snapshot = await detail(id);
+                polls++;
+            }
+            catch (error) {
+                if (!snapshot || !(error instanceof AxiError) || !["REQUEST_BUDGET", "TIME_BUDGET", "RESPONSE_TOO_LARGE"].includes(error.code))
+                    throw error;
+                reason = error.code === "TIME_BUDGET" ? "timeout" : "budget";
+                break;
+            }
+            if (["completed", "failed", "stopped"].includes(snapshot.status)) {
+                reason = "terminal";
+                break;
+            }
+            const remaining = deadline - now();
+            if (remaining <= 0) {
+                reason = "timeout";
+                break;
+            }
+            await wait(Math.min(Number(intervalText) * 1_000, remaining));
+            if (now() >= deadline) {
+                reason = "timeout";
+                break;
+            }
+        }
+        return { task: snapshot, wait: { terminal: reason === "terminal", polls, reason },
+            ...(reason === "terminal" ? {} : { help: [`Run checkpoint-axi task show ${id}${flags.has("--config") ? " --config <absolute-path>" : ""}${flags.has("--profile") ? " --profile <name>" : ""} to read status again; the task may still run, never resubmit its action to obtain status`] }) };
     }
+    if (name.endsWith(" show"))
+        return { [name.split(" ")[0]]: await detail(id) };
     const results = [];
     let scroll = cursor?.scroll;
     let offset = cursor?.offset ?? 0;
@@ -155,7 +225,9 @@ export async function readCommand(name, id, flags, store, transport) {
             }
             const value = entity.parse(record);
             return { id: value.entityInfo.entityId, subject: value.entityPayload.subject ?? "",
-                state: value.entityInfo.entityActionState ?? "", verdict: Array.isArray(value.entitySecurityResults) ? null : value.entitySecurityResults?.combinedVerdict ?? null };
+                state: value.entityInfo.entityActionState, verdict: Array.isArray(value.entitySecurityResults)
+                    ? value.entitySecurityResults.find((result) => result.combinedVerdict != null)?.combinedVerdict ?? null
+                    : value.entitySecurityResults?.combinedVerdict ?? null };
         }));
         offset += rows.length;
         if (offset < page.records.length) {
@@ -171,7 +243,43 @@ export async function readCommand(name, id, flags, store, transport) {
     }
     const next = exhausted ? undefined : Buffer.from(JSON.stringify({ version: 1, binding, start, end, scroll, offset,
         ...(replayRisk ? { replayRisk: true } : {}) })).toString("base64url");
+    let expansion;
+    if (flags.has("--expand")) {
+        let attempted = 0;
+        let expanded = 0;
+        let stopped;
+        const notExpanded = [];
+        for (const row of results) {
+            const itemId = row.id;
+            if (stopped) {
+                notExpanded.push({ id: itemId, ...stopped });
+                continue;
+            }
+            if (attempted >= Number(expandLimitText)) {
+                notExpanded.push({ id: itemId, reason: "item-cap-reached" });
+                continue;
+            }
+            attempted++;
+            try {
+                row.detail = await detail(itemId);
+                expanded++;
+            }
+            catch (error) {
+                if (!(error instanceof AxiError))
+                    throw error;
+                const code = error.code;
+                if (["REQUEST_BUDGET", "TIME_BUDGET", "RESPONSE_TOO_LARGE"].includes(code)) {
+                    stopped = { reason: code === "REQUEST_BUDGET" ? "request-cap-reached" : "budget-exhausted", code };
+                    notExpanded.push({ id: itemId, ...stopped });
+                }
+                else
+                    notExpanded.push({ id: itemId, reason: "per-item-error", code });
+            }
+        }
+        expansion = { expanded, attempted, itemLimit: Number(expandLimitText), requestLimit: Number(expandRequestsText), complete: notExpanded.length === 0, notExpanded };
+    }
     return { [isEvent ? "events" : "emails"]: results, count: results.length, ...(total === undefined ? {} : { total }), complete: exhausted && !replayRisk,
+        ...(expansion ? { expansion } : {}),
         ...(replayRisk ? { reason: "replay-may-skip-or-repeat" } : {}), ...(next ? { cursor: next } : {}),
         help: [...(results.length ? [isEvent ? "Run checkpoint-axi event show <id> for event details and available actions" : "Run checkpoint-axi email show <id> for verdicts, actions and available actions"] : [`No ${isEvent ? "events" : "emails"} matched this search window and selectors`]),
             ...(next ? ["Repeat this search with --cursor <cursor> and the original selectors to continue"] : []),

package/dist/src/transport.d.ts

@@ -72,7 +72,7 @@ export declare function decodePage(value: unknown, unverified?: boolean): Page;
 export declare function gateway(profile: SelectedProfile, credentials: {
     clientId: string;
     clientSecret: string;
-}, redactor: SecretRedactor, dependencies?: Dependencies, mutation?: boolean): {
+}, redactor: SecretRedactor, dependencies?: Dependencies, mutation?: boolean, requestLimit?: number, milliseconds?: number): {
     authenticate: () => Promise<void>;
     read: (query: ReadRequest) => Promise<Page>;
     download: (query: DownloadRequest) => Promise<{

package/dist/src/transport.js

@@ -66,10 +66,10 @@ function tokenFrom(value, redactor) {
         throw failure("AUTH_SHAPE_UNVERIFIED", "Unverified auth token response shape; owner commissioning is required (API guide page 8 does not specify the shape)");
     return [...tokens][0];
 }
-export function gateway(profile, credentials, redactor, dependencies = {}, mutation = false) {
+export function gateway(profile, credentials, redactor, dependencies = {}, mutation = false, requestLimit = READ_LIMITS.requests, milliseconds = READ_LIMITS.milliseconds) {
     const now = dependencies.now ?? Date.now;
     const wait = dependencies.wait ?? delay;
-    const deadline = now() + READ_LIMITS.milliseconds;
+    const deadline = now() + Math.min(milliseconds, READ_LIMITS.milliseconds);
     let bytes = 0;
     let requests = 0;
     let token;
@@ -86,7 +86,7 @@ export function gateway(profile, credentials, redactor, dependencies = {}, mutat
         const remaining = deadline - now();
         if (remaining <= 0)
             throw failure("TIME_BUDGET", "Read time budget exhausted");
-        if (++requests > (mutation ? 44 : READ_LIMITS.requests))
+        if (++requests > (mutation ? 44 : Math.min(requestLimit, READ_LIMITS.requests)))
             throw failure("REQUEST_BUDGET", "Request budget exhausted");
         const payload = body === undefined ? undefined : JSON.stringify(body);
         if (bearer)
@@ -179,6 +179,12 @@ export function gateway(profile, credentials, redactor, dependencies = {}, mutat
                 throw failure("AUTH_FAILED", "API rejected authentication after one re-exchange");
             if (response.status === 429)
                 throw failure("RATE_LIMITED", "API rate limit remains after two read retries");
+            if (response.status === 404)
+                throw new AxiError("Requested resource was not found", "NOT_FOUND", ["Check the requested ID"]);
+            if (response.status === 422 && query.body === undefined) {
+                const id = decodeURIComponent(query.path.slice(query.path.lastIndexOf("/") + 1));
+                throw new AxiError(`API rejected requested ID ${id} (HTTP 422)`, "VALIDATION_ERROR", ["Check the requested ID and its format"]);
+            }
             if (response.status < 200 || response.status >= 300)
                 throw failure("HTTP_ERROR", `Regional API returned HTTP ${response.status}`);
             return decodePage(response.value, /^\/(sectools|sectool-exceptions)\//.test(query.path));

package/docs/agent-guide.md

@@ -43,12 +43,13 @@ saasAttrOp: is, contains, startsWith, isEmpty, isNot, notContains, isNotEmpty, g
 The guide defines operators globally, without a per-field compatibility matrix; examples pair fromEmail with is and attachmentCount with greaterThan.
 saasAttrValue is a string.
 Event selectors include --event-types, --event-states, --severities, --event-ids (comma-separated), --confidence-indicator and --description; --saas accepts comma-separated SaaS values here.
-Event detail includes available actions; task detail reads status and per-action results once, without waiting or polling:
+Event detail includes available actions; task detail reads status and per-action results once by default:
 
 ```sh
 checkpoint-axi event list --all --event-types phishing --fields events,count,total,complete,reason,cursor
 checkpoint-axi event show synthetic-event-1 --fields event
 checkpoint-axi task show synthetic-task-1 --fields task
+checkpoint-axi task show synthetic-task-1 --wait --timeout 30 --fields task,wait,help
 ```
 
 Inspect exception rules with exception list <kind> or exception show <kind> <id-or-value>:
@@ -74,9 +75,30 @@ Inspect complete, reason and cursor even on exit 0; limits and page replay can l
 Resume with --cursor <returned-cursor> and the original selectors/profile; see [continuation limitations](reads.md#email-reads).
 Exception --all bounds returned rows at 1000 but cannot fetch additional pages: no continuation parameter is documented.
 Email/event detail already includes available actions, avoiding a separate action lookup.
-There is no bulk detail expansion, cross-resource pivot or task wait flag; use returned IDs for individual reads and never replay an action to obtain its status.
+Email search and event list accept --expand for read-only show details in each successful row's detail field.
+Expansion is off by default; --expand-limit caps detail attempts (default 5, range 1-8), and --expand-requests caps total HTTP requests (default 10, range 2-10), including auth, list pages and retries.
+Both limit flags require --expand; listing runs first and shares the 60-second and 8 MiB transport budgets with detail reads.
+Inspect the expansion object's expanded, complete and notExpanded fields for every unexpanded ID and its reason: item-cap-reached, request-cap-reached, budget-exhausted or per-item-error (with an error code).
+Partial expansion keeps every list row and successful detail; list complete/cursor describe pagination separately.
+Use --fields emails,expansion or --fields events,expansion to retain expansion status; --full restores full strings after redaction.
+With --all, list pages can consume the entire request budget before any detail is expanded; reduce the list limit or use individual show reads for remaining IDs.
+Expansion never downloads files, invokes available actions or changes remote state.
+Task show reads once by default; use task show <id> --wait --timeout 30 for bounded read-only polling.
+--timeout is required with --wait (integer seconds, range 1-60); --poll-interval defaults to 2 seconds (range 1-10), and --wait-requests defaults to 10 total HTTP requests (range 2-10), including auth and retries.
+Wait stops on completed, failed or stopped; init, inprogress and paused remain non-terminal.
+The task snapshot contains the final status; wait reports terminal, polls (validated status snapshots) and reason (terminal, timeout or budget).
+A non-terminal stop exits 0 with the last snapshot and a read-only next-step hint; inspect wait even on exit 0 and include task,wait,help with --fields.
+Timeout covers auth, requests, retries and delays within the shared 8 MiB response cap; failures before any snapshot remain errors.
+Waiting never resubmits an action or changes remote state; a failed or stopped task is terminal, not successful execution.
+There is no cross-resource pivot; use returned IDs for individual reads and never replay an action to obtain its status.
 
---fields selects top-level output keys, not nested row columns: request emails or events together with count,total,complete,reason,cursor for lists, and email,event,task or exception for details.
+```sh
+checkpoint-axi email search --limit 5 --expand --expand-limit 3 --expand-requests 6 --fields emails,count,complete,cursor,expansion
+checkpoint-axi event list --limit 5 --expand --fields events,count,complete,cursor,expansion
+```
+
+--fields selects top-level output keys: request emails or events together with count,total,complete,reason,cursor for lists, and email,event,task or exception for details.
+Email search also accepts row fields id,subject,state,verdict; event list accepts id,type,state,severity, retaining pagination metadata when selecting row fields.
 Email rows contain id,subject,state,verdict; event rows contain id,type,state,severity; documented exception rows contain id,sender,subject,comment.
 TOON strings preview at 500 characters; --full expands strings after redaction, while cursors are never truncated.
 

package/docs/commands.md

@@ -32,7 +32,7 @@ Run each command with `--help` for concise help.
 | `checkpoint-axi exception update` | Preview or replace one exception; phishing/spam/click-time require an ID; malware/url/dlp identify it in --input without an ID; anomaly unsupported (guide pages 64-67, 78-81, 94-96, 105-107, 116-117, 126-127) |
 | `checkpoint-axi home` | Show local profile context without resolving secrets or making API calls |
 | `checkpoint-axi profile list` | List file profiles without resolving secrets; --profile does not filter this list |
-| `checkpoint-axi task show` | Show asynchronous task status and per-action details (API guide pages 30-33) |
+| `checkpoint-axi task show` | Show asynchronous task status and per-action details, optionally waiting within explicit bounds (API guide pages 30-33) |
 
 ## attachment download
 
@@ -187,7 +187,7 @@ Search emails with a bounded date window and scroll continuation (API guide page
 |---|---|
 | `--config` | Config path; default CHECKPOINT_AXI_CONFIG or platform path |
 | `--profile` | Profile name; default CHECKPOINT_AXI_PROFILE, env profile, config default, or sole profile |
-| `--fields` | Comma-separated output fields; default all |
+| `--fields` | Comma-separated row fields: id,subject,state,verdict; or top-level emails,count,total,complete,reason,cursor,expansion,help; default all |
 | `--full` | Show full strings instead of 500-character previews; default false |
 | `--help` | Show concise command help; default false |
 | `--saas` | SaaS override; default selected profile saas or office365_emails |
@@ -197,11 +197,14 @@ Search emails with a bounded date window and scroll continuation (API guide page
 | `--limit` | Maximum rows; default 50, range 1-1000; cannot combine with --all |
 | `--all` | Read up to 1000 rows / 10 HTTP requests / 60 seconds / 8 MiB; default false |
 | `--cursor` | Opaque continuation bound to profile, region, operation and selectors; repeat original selectors |
+| `--expand` | Opt in to read-only show details on returned rows; default false; partial expansion is reported separately |
+| `--expand-limit` | Maximum detail attempts; default 5, range 1-8; requires --expand |
+| `--expand-requests` | Total HTTP request cap including auth, list pages, detail and retries; default 10, range 2-10; requires --expand |
 | `--filter` | JSON array of {saasAttrName, saasAttrOp, saasAttrValue} filters. saasAttrName is a field path, not a closed enum (guide pages 19-20). Documented examples: entityPayload.subject, entityPayload.fromEmail, entityPayload.attachmentCount. Other documented email payload paths (pages 15-16, 24-25): entityPayload.internetMessageId, entityPayload.received, entityPayload.size, entityPayload.emailLinks, entityPayload.attachments, entityPayload.mode, entityPayload.recipients, entityPayload.fromDomain, entityPayload.fromUser, entityPayload.fromName, entityPayload.to, entityPayload.toUser, entityPayload.cc, entityPayload.ccUser, entityPayload.bcc, entityPayload.bccUser, entityPayload.replyToEmail, entityPayload.replyToNickname, entityPayload.isRead, entityPayload.isDeleted, entityPayload.isIncoming, entityPayload.isInternal, entityPayload.isOutgoing, entityPayload.isQuarantined, entityPayload.isQuarantineNotification, entityPayload.isRestored, entityPayload.isRestoreRequested, entityPayload.isRestoreDeclined, entityPayload.saasSpamVerdict, entityPayload.SpfResult. saasAttrOp: is, contains, startsWith, isEmpty, isNot, notContains, isNotEmpty, greaterThan, lessThan. The guide defines operators globally, without a per-field compatibility matrix; examples pair fromEmail with is and attachmentCount with greaterThan. saasAttrValue is a string. |
 
 ```sh
 checkpoint-axi email search
-checkpoint-axi email search --all --saas office365_emails
+checkpoint-axi email search --limit 5 --expand --saas office365_emails
 checkpoint-axi email search --cursor <cursor>
 ```
 
@@ -252,7 +255,7 @@ List security events with bounded scroll continuation (API guide pages 37-42)
 |---|---|
 | `--config` | Config path; default CHECKPOINT_AXI_CONFIG or platform path |
 | `--profile` | Profile name; default CHECKPOINT_AXI_PROFILE, env profile, config default, or sole profile |
-| `--fields` | Comma-separated output fields; default all |
+| `--fields` | Comma-separated row fields: id,type,state,severity; or top-level events,count,total,complete,reason,cursor,expansion,help; default all |
 | `--full` | Show full strings instead of 500-character previews; default false |
 | `--help` | Show concise command help; default false |
 | `--start-date` | ISO timestamp with timezone; default 24 hours before end-date; maximum window 31 days |
@@ -260,17 +263,21 @@ List security events with bounded scroll continuation (API guide pages 37-42)
 | `--limit` | Maximum rows; default 50, range 1-1000; cannot combine with --all |
 | `--all` | Read up to 1000 rows / 10 HTTP requests / 60 seconds / 8 MiB; default false |
 | `--cursor` | Opaque continuation bound to profile, region, operation and selectors; repeat original selectors |
+| `--expand` | Opt in to read-only show details on returned rows; default false; partial expansion is reported separately |
+| `--expand-limit` | Maximum detail attempts; default 5, range 1-8; requires --expand |
+| `--expand-requests` | Total HTTP request cap including auth, list pages, detail and retries; default 10, range 2-10; requires --expand |
 | `--saas` | Comma-separated SaaS overrides; default selected profile saas or office365_emails |
 | `--event-types` | Comma-separated event types; default unfiltered |
-| `--event-states` | Comma-separated event states; default unfiltered |
-| `--severities` | Comma-separated severities; default unfiltered |
+| `--event-states` | Comma-separated event states: new, detected, pending, remediated, dismissed, exception; default unfiltered |
+| `--states` | Alias for --event-states; cannot combine with --event-states |
+| `--severities` | Nonempty comma-separated severity strings; vendor documents no fixed severity list; unrecognised severities can return an empty result; default unfiltered |
 | `--event-ids` | Comma-separated event IDs; default unfiltered |
 | `--confidence-indicator` | Confidence indicator selector; default unfiltered |
 | `--description` | Description selector; default unfiltered |
 
 ```sh
 checkpoint-axi event list
-checkpoint-axi event list --all --event-types phishing
+checkpoint-axi event list --limit 5 --expand --event-types phishing
 checkpoint-axi event list --cursor <cursor>
 ```
 
@@ -473,7 +480,7 @@ checkpoint-axi profile list --config /example/config.json
 
 ## task show
 
-Show asynchronous task status and per-action details (API guide pages 30-33)
+Show asynchronous task status and per-action details, optionally waiting within explicit bounds (API guide pages 30-33)
 
 | Flag | Meaning |
 |---|---|
@@ -482,8 +489,13 @@ Show asynchronous task status and per-action details (API guide pages 30-33)
 | `--fields` | Comma-separated output fields; default all |
 | `--full` | Show full strings instead of 500-character previews; default false |
 | `--help` | Show concise command help; default false |
+| `--wait` | Poll existing task status only; default false; requires --timeout; terminal: completed, failed, stopped |
+| `--timeout` | Total wait timeout in integer seconds, range 1-60; required with --wait; includes auth and retries |
+| `--poll-interval` | Seconds between status reads; default 2, range 1-10; requires --wait |
+| `--wait-requests` | Total HTTP request cap including auth and retries; default 10, range 2-10; requires --wait |
 
 ```sh
 checkpoint-axi task show <id>
+checkpoint-axi task show <id> --wait --timeout 30 --fields task,wait,help
 checkpoint-axi task show <id> --full
 ```

package/docs/reads.md

@@ -20,6 +20,7 @@ Read sessions allow at most 10 HTTP requests; write sessions allow at most 44.
 Both are bounded by 8 MiB of JSON response bytes and 60 seconds, including auth, re-exchange, read retries and delays.
 Download bodies have a separate 50 MiB cap per response within the same request/time budgets.
 Reads retry HTTP 429 at most twice, honoring numeric or HTTP-date `Retry-After` within that budget.
+HTTP 404 reads return `NOT_FOUND`; HTTP 422 detail reads return `VALIDATION_ERROR` and identify the requested ID without printing server response data.
 Exception reads and writes share separate 1 request/second Anti-Phishing and 10 requests/second other-exception spacers.
 
 ## Email reads
@@ -43,26 +44,76 @@ Cursor strings are never truncated; email text is redacted before 500-character
 See [downloads](downloads.md) for private file output.
 
 The vendor PDF describes `entitySecurityResults` as an array in its prose/table (pages 11 and 14), while its JSON examples use an object.
-Both documented forms are accepted; detail preserves them, and search reports `verdict: null` for an array because no combined verdict object is documented there.
-Other response constraints remain unchanged.
+Both forms are accepted; search uses `combinedVerdict` from the object or the first array entry containing one, and reports `verdict: null` when none is available.
+Null or missing `entityActionState` within `entityInfo` is rendered as `unactioned` in search and detail.
 `RESPONSE_INVALID` diagnostics for these reads name failing JSON paths and received types, including `missing`, without response values.
 Non-identifier path keys appear as `<key>`.
-These diagnostics support owner commissioning; the actual failing fields behind TD-049's live unfiltered-search and spam-detail failures remain unverified.
+The reported unfiltered-search and spam-detail failures identified null action states; synthetic clean and spam fixtures exercise that shape offline.
 
 ## Event and task reads
 
 `checkpoint-axi event list` returns compact ID, type, state and severity rows (guide pages 37-42).
 `checkpoint-axi event show <id>` preserves event details, action history and available actions (guide pages 34-37).
 `checkpoint-axi task show <id>` returns task status, progress and per-action details for asynchronous actions (guide pages 30-33).
-Task states are `init`, `inprogress`, `completed`, `failed`, `stopped` and `paused`; task show performs one read without polling.
+Task states are `init`, `inprogress`, `completed`, `failed`, `stopped` and `paused`; task show performs one read by default.
+Use `checkpoint-axi task show <id> --wait --timeout 30` to poll an already submitted task without resubmitting its action.
+`--wait` requires an explicit `--timeout` in integer seconds, from 1 to 60.
+`--poll-interval` defaults to 2 seconds, from 1 to 10; `--wait-requests` defaults to 10 total HTTP requests, from 2 to 10, including authentication, re-exchange and retries.
+These limits require `--wait` and invalid bounds fail before configuration or network access.
+The timeout includes authentication, requests, retries and delays, and the existing 8 MiB response cap remains shared across polls.
+The first read starts immediately; subsequent reads wait the configured interval after the preceding read, without starting another read at or after the deadline.
+`completed`, `failed` and `stopped` are terminal; `init`, `inprogress` and `paused` remain non-terminal.
+The final `task` snapshot retains status, progress and per-action details; the `wait` object reports `terminal`, `polls` (validated status snapshots, excluding authentication and retries), and `reason`: `terminal`, `timeout` or `budget`.
+Request or response-byte exhaustion reports `budget`; an exhausted deadline or a retry delay that cannot fit reports `timeout`.
+A non-terminal stop exits 0, preserves the last snapshot and includes a `help` hint for another status read.
+Inspect `wait` even on exit 0; terminal failure or stopping does not mean the submitted action succeeded.
+Failures before any snapshot and non-budget read failures remain structured errors rather than reporting stale data as current.
+Use `--fields task,wait,help` to retain wait metadata and recovery guidance when projecting output.
+Waiting only repeats the existing task status GET; it never invokes an available action, downloads a file or resubmits the original mutation.
 Event list accepts comma-separated `--event-types`, `--event-states`, `--severities`, `--event-ids` and `--saas`, plus `--confidence-indicator` and `--description` text selectors.
+`--states` is an alias for `--event-states`; use one of these flags per command.
+States must be `new`, `detected`, `pending`, `remediated`, `dismissed` or `exception`, as defined by the vendor Swagger 1.50 `EventState` schema.
+The vendor Swagger defines severities as an array of strings with no format, min/max constraints or fixed severity list, so the CLI validates nonempty comma-separated severity strings.
+Unrecognised severities can return an empty result.
 SaaS defaults to the selected profile's value or `office365_emails`; other event selectors default to unfiltered.
 Event list uses the same date windows, row and transport budgets, bound continuation and honest page replay flags as [email search](reads.md#email-reads).
 Repeat all original event selectors with `--cursor`; the cursor preserves the original date window.
 Event and task text is redacted before 500-character previews; use `--full` for full strings and `--fields` to select top-level fields.
+Email search also accepts row fields `id,subject,state,verdict`; event list accepts `id,type,state,severity`.
+For example, `email search --fields id,subject` narrows each email row while retaining pagination metadata.
+Existing top-level projections such as `--fields emails,count,cursor` remain supported; mixed row and top-level selections are rejected, and errors list both valid sets.
 For writes, see [event actions](writes.md#event-actions).
 These reads are verified offline with synthetic fixtures; authentication, token lifetime and live API behavior require manual verification.
 
+## Bounded detail expansion
+
+Email search and event list accept `--expand` to inspect returned items through the same validated read-only path as their individual show commands.
+Expansion is off by default; available actions are returned as data and are never invoked.
+
+```sh
+checkpoint-axi email search --limit 5 --expand --expand-limit 3 --expand-requests 6
+checkpoint-axi event list --limit 5 --expand --fields events,count,complete,cursor,expansion
+```
+
+`--expand-limit` caps detail attempts, including failed attempts: default 5, minimum 1, maximum 8.
+`--expand-requests` caps total HTTP requests for the invocation: default 10, minimum 2, maximum 10.
+Both limit flags require `--expand`; invalid bounds are rejected before configuration or network access.
+Authentication, token re-exchange, list pages, detail requests and read retries all consume this request cap.
+Listing runs first; detail reads reuse its token, deadline and response-byte accounting without resetting the 60-second or 8 MiB budgets.
+Using `--all` can therefore consume the entire budget before any detail is fetched.
+Use a smaller list limit to leave room for detail, or inspect remaining IDs with individual show commands.
+
+Each successfully expanded row gains `detail`, containing the same validated payload and actions as show, with normal secret redaction and 500-character string previews (`--full` restores full strings).
+Every list row and successful detail survives expansion failures; partial expansion exits 0.
+The `expansion` object reports `expanded`, `attempted`, `itemLimit`, `requestLimit`, `complete` and `notExpanded`.
+Each `notExpanded` entry includes the item `id` and `reason`: `item-cap-reached`, `request-cap-reached`, `budget-exhausted` or `per-item-error`.
+Budget and per-item failures also include a safe error `code`; raw upstream error bodies are never printed.
+Budget exhaustion stops further detail attempts; an individual HTTP, response-validation or other read failure records that item and continues within the caps.
+List `complete`, `reason` and `cursor` still describe pagination; `complete` inside `expansion` independently describes whether every returned row was expanded.
+With `--fields`, include `expansion` alongside `emails` or `events` so omissions remain visible.
+Row field selections retain expansion metadata but omit each row's `detail`; use a top-level projection to inspect expanded payloads.
+Expansion performs no writes, actions, downloads, cross-resource pivots or task waiting.
+
 ## Exception reads
 
 `checkpoint-axi exception list <kind>` and `exception show <kind> <id-or-value>` cover `phishing-allow`, `phishing-block`, `spam-allow`, `anomaly`, `click-time`, `malware`, `url` and `dlp` (guide pages 49-123).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowttl/checkpoint-axi",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Inspect Check Point Email Security through compact, guarded AXI commands",
   "license": "MIT",
   "type": "module",

package/skills/checkpoint-axi/SKILL.md

@@ -49,6 +49,14 @@ The guide defines operators globally, without a per-field compatibility matrix;
 saasAttrValue is a string.
 See [email-read guidance](../../docs/reads.md#email-reads) for continuation, completion status, cursor safety and page replay limitations.
 Email show <id> includes payload, verdicts, actions taken and available actions (guide pages 10-18).
+Email search and event list accept --expand for read-only show details in each successful row's detail field.
+Expansion is off by default; --expand-limit caps detail attempts (default 5, range 1-8), and --expand-requests caps total HTTP requests (default 10, range 2-10), including auth, list pages and retries.
+Both limit flags require --expand; listing runs first and shares the 60-second and 8 MiB transport budgets with detail reads.
+Inspect the expansion object's expanded, complete and notExpanded fields for every unexpanded ID and its reason: item-cap-reached, request-cap-reached, budget-exhausted or per-item-error (with an error code).
+Partial expansion keeps every list row and successful detail; list complete/cursor describe pagination separately.
+Use --fields emails,expansion or --fields events,expansion to retain expansion status; --full restores full strings after redaction.
+With --all, list pages can consume the entire request budget before any detail is expanded; reduce the list limit or use individual show reads for remaining IDs.
+Expansion never downloads files, invokes available actions or changes remote state.
 Use --full for strings truncated at 500 characters and --fields for top-level output projection.
 Cursor strings are never truncated; secret-derived strings are redacted before previews.
 Downloads require file-profile downloads.allow and an absolute new --out file, created exclusively with mode 0600 or a protected Windows DACL.
@@ -64,7 +72,14 @@ Event action --ids <ids> --name <action> previews by default and requires the ex
 Every target must offer the action on both reads; nonempty actionParameter objects or repeated action names refuse ENDPOINT_UNVERIFIED until live commissioning resolves the object/string contradiction (guide pages 36-37, 43).
 Use event show <id> to inspect all available actions, including deferred parameterized actions.
 Accepted actions return task IDs; use task show <taskId> to inspect asynchronous execution without replaying ambiguous outcomes.
-Event list supports documented selectors and shares email search bounds and continuation; event show preserves actions and task show reads asynchronous status without polling (guide pages 30-42).
+Event list supports documented selectors and shares email search bounds and continuation; event show preserves actions and task show reads asynchronous status (guide pages 30-42).
+Task show reads once by default; use task show <id> --wait --timeout 30 for bounded read-only polling.
+--timeout is required with --wait (integer seconds, range 1-60); --poll-interval defaults to 2 seconds (range 1-10), and --wait-requests defaults to 10 total HTTP requests (range 2-10), including auth and retries.
+Wait stops on completed, failed or stopped; init, inprogress and paused remain non-terminal.
+The task snapshot contains the final status; wait reports terminal, polls (validated status snapshots) and reason (terminal, timeout or budget).
+A non-terminal stop exits 0 with the last snapshot and a read-only next-step hint; inspect wait even on exit 0 and include task,wait,help with --fields.
+Timeout covers auth, requests, retries and delays within the shared 8 MiB response cap; failures before any snapshot remain errors.
+Waiting never resubmits an action or changes remote state; a failed or stopped task is terminal, not successful execution.
 Exception list/show accept phishing-allow, phishing-block, spam-allow, anomaly, click-time, malware, url and dlp (guide pages 49-123).
 For malware, url and dlp, --type is required; run exception list --help for the documented values.
 Click-time --items selects item routes; by default list routes are used.
@@ -105,4 +120,4 @@ All live-only facts remain unverified, including token response shape and lifeti
 | `npx -y @knowttl/checkpoint-axi exception update` | Preview or replace one exception; phishing/spam/click-time require an ID; malware/url/dlp identify it in --input without an ID; anomaly unsupported (guide pages 64-67, 78-81, 94-96, 105-107, 116-117, 126-127) |
 | `npx -y @knowttl/checkpoint-axi home` | Show local profile context without resolving secrets or making API calls |
 | `npx -y @knowttl/checkpoint-axi profile list` | List file profiles without resolving secrets; --profile does not filter this list |
-| `npx -y @knowttl/checkpoint-axi task show` | Show asynchronous task status and per-action details (API guide pages 30-33) |
+| `npx -y @knowttl/checkpoint-axi task show` | Show asynchronous task status and per-action details, optionally waiting within explicit bounds (API guide pages 30-33) |