@tiangong-lca/cli 0.0.24 → 0.0.25

package/README.md

@@ -17,8 +17,8 @@ checkPaths:
   - bin/**
   - src/cli.ts
   - src/main.ts
-lastReviewedAt: 2026-07-14
-lastReviewedCommit: ce8c18f270725adad789ada8f4582ca0e97e4117
+lastReviewedAt: 2026-07-15
+lastReviewedCommit: ca0cdd7549cad9003d08fb338223ba74682955ae
 ---
 
 # TianGong LCA CLI
@@ -31,6 +31,8 @@ Review note, 2026-07-13: maintenance scans now prove exact-count pagination even
 
 Review note, 2026-07-14: maintenance now includes the protected derivative-only `rebuild-derivatives` operation. V1 plans exactly one current-owner state-0 process with `action=rebuild_derivatives`, `target_mode=owner_draft`, and components `extracted_md` plus `embedding_ft`. Apply only proves guarded-RPC admission (`accepted`/`queued`); independent verify reports `pending`, `passed`, or `failed`.
 
+Review note, 2026-07-15: `dataset maintenance run-protected` adds a production-only path for one sealed private alias execution and its exact 50-target derivative closure. The protected executor is server-dispatched and fenced by the authenticated owner plus exact actor/user_id/state_code=0 and plan-closure checks; RLS remains a defense on public and independent-read surfaces. It performs one server preflight, writes an immutable local attempt marker before one admission POST, and requires status-only recovery after any marker or ambiguous response. It has no dev, legacy-alias, publication, or state-code fallback.
+
 ## Run
 
 One-off published run:
@@ -283,6 +285,7 @@ tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operati
 tiangong-lca dataset maintenance plan --scope ./derivative-rebuild-scope.json --operation rebuild-derivatives --out-dir /abs/path/to/derivative-rebuild --json
 tiangong-lca dataset maintenance apply --plan /abs/path/to/dataset-maintenance/maintenance-plan.json --commit --approve-plan <sha256> --confirm <current-account-email> --timeout-ms 10000 --json
 tiangong-lca dataset maintenance verify --plan /abs/path/to/dataset-maintenance/maintenance-plan.json --out-dir /abs/path/to/dataset-maintenance/verify --page-size 1000 --timeout-ms 10000 --json
+tiangong-lca dataset maintenance run-protected --plan /abs/path/to/maintenance-plan.json --freeze /abs/path/to/protected-execution-seal.json --approval /abs/path/to/protected-approval.json --out-dir /abs/path/to/protected-run --status-only --json
 tiangong-lca lifecyclemodel auto-build --input ./examples/lifecyclemodel-auto-build.request.json --out-dir /abs/path/to/lifecyclemodel-run --json
 tiangong-lca lifecyclemodel validate-build --run-dir /abs/path/to/lifecyclemodel-run --json
 tiangong-lca lifecyclemodel publish-build --run-dir /abs/path/to/lifecyclemodel-run --json
@@ -327,12 +330,12 @@ For `dataset references rewrite`, `--commit` executes the state-aware save-draft
 
 ## Dataset Maintenance
 
-`dataset maintenance plan/apply/verify` is the row-level cleanup surface for bad imports, the fixed BAFU private alias rewrite, and one protected derivative-only process rebuild. It runs as the currently authenticated user and relies on RLS for visibility and ownership enforcement.
+`dataset maintenance plan/apply/run-protected/verify` is the row-level cleanup surface for bad imports, the fixed BAFU private alias rewrite, and protected derivative rebuilds. Ordinary planning, apply, and independent verification use the authenticated account and RLS. The protected executor is server-dispatched and additionally enforces the sealed actor, user_id, state_code=0, exact target set, and closure hashes on every write.
 
 ```bash
 tiangong-lca dataset maintenance plan \
   --scope ./maintenance-scope.json \
-  --operation merge-support-aliases \
+  --operation repair-references \
   --out-dir ./dataset-maintenance \
   --page-size 1000 \
   --timeout-ms 10000 \
@@ -352,8 +355,37 @@ tiangong-lca dataset maintenance verify \
   --page-size 1000 \
   --timeout-ms 10000 \
   --json
+
+tiangong-lca dataset maintenance run-protected \
+  --plan ./protected-step2/maintenance-plan.json \
+  --freeze ./protected-step2/protected-execution-seal.json \
+  --approval ./protected-step2/protected-approval.json \
+  --out-dir ./protected-step2/run \
+  --commit \
+  --approve-execution <approved-execution-sha256> \
+  --confirm <current-account-email> \
+  --wait-seconds 60 \
+  --poll-ms 10000 \
+  --page-size 1000 \
+  --timeout-ms 10000 \
+  --json
+
+tiangong-lca dataset maintenance run-protected \
+  --plan ./protected-step2/maintenance-plan.json \
+  --freeze ./protected-step2/protected-execution-seal.json \
+  --approval ./protected-step2/protected-approval.json \
+  --out-dir ./protected-step2/run \
+  --status-only \
+  --wait-seconds 60 \
+  --json
 ```
 
+`run-protected` is a separate one-shot path for an already reviewed and sealed production execution; it does not replace ordinary planning. Both modes require the exact plan, freeze/seal, approval artifact, and private output directory. Commit mode additionally requires `--commit`, the exact approved execution identity through `--approve-execution`, and the authenticated account email through `--confirm`. `--status-only` is mutually exclusive with `--commit` and performs no preflight or admission.
+
+Before requesting preflight, the command validates the sealed production project, full current-user RLS before-state, support closure, and exact derivative baseline. The server then returns the three expected gate digests and a token valid for at most 180 seconds; the CLI captures and compares the live gate receipts before admission. The server-dispatched write remains fenced to the authenticated actor's exact `user_id`, `state_code=0` rows and sealed plan/closure; independent readback still uses RLS. The CLI writes an immutable local submission marker and sends at most one admission POST. A marker, admission timeout, connection loss, or ambiguous admission response permanently switches that local run to status-only recovery; status-read failures may be polled only within the configured wait window and never cause a second admission or fallback to dev or the legacy whole-plan RPC. The default status polling interval is 10 seconds.
+
+Success requires the terminal database proof and independent RLS readback to agree on the approved execution, exact row/exchange/audit closure, and exactly 50 derivative targets split into 23 flows and 27 processes. `pending`, `failed`, and `indeterminate` all return a non-zero exit status. The protected operation keeps all affected rows private to their owner, changes no `state_code`, and does not publish data.
+
 For the derivative-only profile, use the same three commands with `--operation rebuild-derivatives`. Its scope must contain exactly one `processes` action with `action: "rebuild_derivatives"`, `target_mode: "owner_draft"`, expected current owner, expected `state_code: 0`, and the exact component set `extracted_md` plus `embedding_ft`.
 
 `--page-size` accepts `1-5000` and is only the requested maximum. PostgREST may enforce a lower server-side cap. The CLI requests `Prefer: count=exact`, validates the exact total and returned range from each `Content-Range`, advances the next offset by the number of rows actually returned, and requires strict `id`/`version` ordering without missing or duplicate identities. Each accepted scan records per-table requested/effective page size, page count, rows fetched, exact total, and aggregate entity counts.
@@ -373,7 +405,7 @@ The scope is intentionally narrow:
 
 `plan` accepts the account scan only after its exact-count proof is complete, then writes the frozen `maintenance-scope.json`, `rls-visible-snapshot.json`, `protected-rows.jsonl`, `reference-impact-report.json`, `maintenance-plan.json`, and `dry-run-report.json`. The snapshot, dry-run report, and newly generated plan carry the aggregate completeness proof, so it is bound into the plan SHA-256. Alias plans additionally write `exchange-rewrite-plan.jsonl`, freeze current-owner state-0 target FP, target UG, and source UG snapshots for each batch, derive schema-valid desired payloads with matching embedded UUID/version, and include the exact closure, `modified_at`, hashes, conversion evidence, and postconditions in the approved plan. A derivative rebuild plan additionally obtains a database-produced snapshot for only the exact target action and binds its primary and derivative preconditions into the plan; large markdown/vector fields are not added to the account-wide scan. The plan SHA-256 is the approval identity; do not edit or recompute the plan after review.
 
-`apply` is write-disabled unless all three commit guards are present: `--commit`, `--approve-plan <sha256>`, and `--confirm <current-account-email>`. Before approval is persisted or any write runs, it requires a fresh complete exact-count account scan and re-checks the whole plan for drift; the current completeness proof is recorded in `approval-record.json`. Ordinary draft updates/deletes use their platform paths. The ordered `time` plus `length_time` alias request is sent once to `cmd_dataset_alias_plan_guarded` with `target_visibility=owner_draft`; the CLI has neither a per-dimension fallback nor a 52-write sequential fallback. The RPC locks and validates the complete 52-row/59-exchange closure before both dimensions commit, so a second-dimension failure rolls back the first. It checks actor ownership, state 0, exact payload/timestamp locks and embedded UUID/version, rejects missing or phantom flow/exchange references, and returns one plan summary audit id plus both batch and per-row audit proofs. The CLI writes `alias-plan-progress.jsonl` together with plan-bound per-batch, per-row, and per-exchange ledgers. A lost response or incomplete derived ledger is repaired only by replaying the same whole plan and matching every returned plan and batch proof.
+`apply` is write-disabled unless all three commit guards are present: `--commit`, `--approve-plan <sha256>`, and `--confirm <current-account-email>`. Before approval is persisted or any write runs, it requires a fresh complete exact-count account scan and re-checks the whole plan for drift; the current completeness proof is recorded in `approval-record.json`. Ordinary draft updates/deletes use their platform paths. The original V1 alias adapter retains its frozen request and artifact contract for compatibility, but it is not an authorized execution or recovery fallback for a sealed production `merge-support-aliases` plan. That plan must use `run-protected`, whose database contract replaces replay with one durable attempt/admission identity.
 
 For `rebuild-derivatives`, apply submits the frozen single-action plan only to the authenticated guarded RPC. The database admission envelope must report `queued`; the CLI records that durable admission as an `accepted` action with queued proof. It does not mean markdown or embedding generation has completed. Replay must return the same durable request/proof rather than enqueueing a second rebuild. There is no fallback to a direct Edge call, `admin embedding-run`, a raw queue, SQL, service-role credentials, or raw REST mutation.
 

package/dist/src/cli.js

@@ -56,6 +56,7 @@ import { runDatasetClassificationApply, runDatasetClassificationAudit, runDatase
 import { runDatasetMaintenanceClearAccount, } from './lib/dataset-maintenance-clear-account.js';
 import { runDatasetMaintenancePlan } from './lib/dataset-maintenance-plan.js';
 import { runDatasetMaintenanceApply } from './lib/dataset-maintenance-apply.js';
+import { runDatasetMaintenanceProtected } from './lib/dataset-maintenance-protected-run.js';
 import { runDatasetMaintenanceVerify } from './lib/dataset-maintenance-verify.js';
 import { runDatasetSourceUploadAttachments, } from './lib/dataset-source-upload-attachments.js';
 function renderMainHelp(dotEnvStatus) {
@@ -131,6 +132,7 @@ Examples:
   tiangong-lca dataset references rewrite --input ./rows.jsonl --from flow:<old-id>@<old-version> --to flow:<new-id>@<new-version> --out-dir /abs/path/to/dataset-rewrite
   tiangong-lca dataset maintenance clear-account --out-dir /abs/path/to/account-clear --json
   tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir /abs/path/to/dataset-maintenance
+  tiangong-lca dataset maintenance run-protected --plan ./maintenance-plan.json --freeze ./protected-execution-seal.json --approval ./protected-approval.json --out-dir /abs/path/to/protected-run --status-only
   tiangong-lca lifecyclemodel auto-build --input ./lifecyclemodel-auto-build.request.json --out-dir /abs/path/to/lifecyclemodel-run
   tiangong-lca lifecyclemodel validate-build --run-dir /abs/path/to/lifecyclemodel-run
   tiangong-lca lifecyclemodel publish-build --run-dir /abs/path/to/lifecyclemodel-run
@@ -283,6 +285,7 @@ Implemented Subcommands:
   maintenance clear-account Dry-run or clear current authenticated account-owned dataset rows through RLS
   maintenance plan    Build an immutable, RLS-visible row-level maintenance plan
   maintenance apply   Execute an explicitly approved maintenance plan through current-user RLS
+  maintenance run-protected Run or inspect one sealed, one-shot production maintenance execution
   maintenance verify  Read back affected rows and references against the immutable plan
 
 Examples:
@@ -310,21 +313,25 @@ Examples:
   tiangong-lca dataset references refresh-remote --input ./rows.jsonl --out ./rows.refreshed.jsonl --out-dir ./dataset-reference-refresh --help
   tiangong-lca dataset maintenance clear-account --out-dir ./account-clear --json --help
   tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir ./dataset-maintenance --help
+  tiangong-lca dataset maintenance run-protected --help
 `.trim();
 }
 function renderDatasetMaintenanceHelp() {
     return `Usage:
-  tiangong-lca dataset maintenance <clear-account|plan|apply|verify> [options]
+  tiangong-lca dataset maintenance <clear-account|plan|apply|run-protected|verify> [options]
 
 Actions:
   clear-account Dry-run or delete current authenticated account-owned lifecyclemodels, processes, flows, sources, and contacts.
   plan    Build an immutable maintenance plan from a scope manifest, visible remote snapshot, dependency impact report, and intended operation.
-  apply   Execute or durably admit an approved plan through current-user RLS and platform dataset command paths; never bypass RLS.
+  apply   Execute or durably admit an ordinary approved plan through current-user RLS and platform dataset command paths.
+  run-protected Run or inspect one sealed production execution with one-shot admission and terminal derivative proof.
   verify  Re-fetch rows, references, or derivative request state and report passed, pending, or failed independently of apply.
 
 Safety:
   plan and verify are read-only.
   apply is commit-only and requires --commit, the exact plan SHA-256 via --approve-plan, and the current account email via --confirm.
+  A sealed production merge-support-aliases execution must use run-protected; apply is not its fallback.
+  run-protected is production-only: authenticated owner context plus server-side actor/user_id/state_code=0 and exact-plan closure fences protect writes; RLS remains a defense on public and independent-read surfaces. It never falls back to dev, a legacy alias RPC, or a second admission POST.
 
 Required Artifact Contract:
   - maintenance-plan.json
@@ -334,13 +341,15 @@ Required Artifact Contract:
   - dry-run-report.json
   - commit-report.json
   - readback-verify-report.json
+  run-protected uses a separate immutable protected-execution seal, submission marker, append-only status ledger, and terminal report.
 
 Examples:
   tiangong-lca dataset maintenance clear-account --out-dir ./account-clear --json
   tiangong-lca dataset maintenance clear-account --commit --confirm user@example.com --out-dir ./account-clear
-  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation merge-support-aliases --out-dir ./dataset-maintenance
+  tiangong-lca dataset maintenance plan --scope ./maintenance-scope.json --operation repair-references --out-dir ./dataset-maintenance
   tiangong-lca dataset maintenance plan --scope ./derivative-rebuild-scope.json --operation rebuild-derivatives --out-dir ./derivative-rebuild
   tiangong-lca dataset maintenance apply --plan ./dataset-maintenance/maintenance-plan.json --commit --approve-plan <sha256> --confirm user@example.com
+  tiangong-lca dataset maintenance run-protected --plan ./maintenance-plan.json --freeze ./protected-execution-seal.json --approval ./protected-approval.json --out-dir ./protected-run --status-only
   tiangong-lca dataset maintenance verify --plan ./dataset-maintenance/maintenance-plan.json --out-dir ./dataset-maintenance/verify
 `.trim();
 }
@@ -373,6 +382,7 @@ Behavior:
   Commit-only. The command rejects dry-run mode, a missing --commit flag, a plan hash mismatch,
   or a confirmation email that does not match the current authenticated account.
   For rebuild-derivatives, success means guarded admission is queued; it never means derivatives completed.
+  Sealed production merge-support-aliases executions must use run-protected; this command is not a fallback.
 
 Options:
   --plan <file>          Immutable maintenance-plan.json
@@ -386,6 +396,45 @@ Options:
 Outputs include approval-record.json and commit-report.json alongside an append-only action or admission ledger.
 `.trim();
 }
+function renderDatasetMaintenanceRunProtectedHelp() {
+    return `Usage:
+  tiangong-lca dataset maintenance run-protected --plan <file> --freeze <file> --approval <file> --out-dir <dir> --commit --approve-execution <sha256> --confirm <email> [options]
+  tiangong-lca dataset maintenance run-protected --plan <file> --freeze <file> --approval <file> --out-dir <dir> --status-only [options]
+
+Behavior:
+  Runs one sealed, server-dispatched production maintenance execution fenced to the authenticated actor's
+  exact owner-draft target set, or reads durable status through an auth.uid-, actor-, and plan-fenced RPC
+  without admitting work; only the independent table readback uses RLS.
+  Commit and status-only modes are mutually exclusive. The commit path validates the full private
+  before-state, accepts only server-derived gates within the 180-second preflight window, writes an immutable
+  local submission marker, and sends at most one admission POST. After a marker or ambiguous response,
+  use --status-only; the command never retries admission or falls back to dev or the legacy alias RPC.
+
+Required in both modes:
+  --plan <file>             Immutable maintenance-plan.json
+  --freeze <file>           Protected production execution seal/freeze artifact
+  --approval <file>         Exact human-approval binding artifact
+  --out-dir <dir>           Private protected-run artifact directory
+
+Commit-only guards:
+  --commit                  Submit the sealed execution exactly once
+  --approve-execution <sha256> Exact approved execution identity SHA-256
+  --confirm <email>         Current authenticated account email
+
+Recovery:
+  --status-only             Read/poll and independently verify the sealed request; never preflight or admit
+
+Options:
+  --wait-seconds <n>        Maximum terminal-status wait in seconds; 0 performs one status read
+  --poll-ms <n>             Positive polling interval in milliseconds; default 10000
+  --page-size <n>           Requested RLS readback page size, 1-5000
+  --timeout-ms <n>          Positive request timeout in milliseconds
+  --json                    Print compact JSON
+  -h, --help
+
+Only a terminal passed proof exits successfully. pending, failed, and indeterminate return non-zero.
+`.trim();
+}
 function renderDatasetMaintenanceVerifyHelp() {
     return `Usage:
   tiangong-lca dataset maintenance verify --plan <file> [options]
@@ -3040,6 +3089,19 @@ function parseDatasetMaintenancePositiveInteger(value, flagName) {
     }
     return Number.parseInt(value.trim(), 10);
 }
+function parseDatasetMaintenanceNonNegativeInteger(value, flagName) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    if (!/^\d+$/u.test(value.trim())) {
+        throw new CliError(`${flagName} must be a non-negative integer.`, {
+            code: 'DATASET_MAINTENANCE_INTEGER_INVALID',
+            exitCode: 2,
+            details: { flag: flagName, value },
+        });
+    }
+    return Number.parseInt(value.trim(), 10);
+}
 function parseDatasetMaintenancePlanFlags(args) {
     let values;
     try {
@@ -3126,6 +3188,54 @@ function parseDatasetMaintenanceApplyFlags(args) {
         dryRun: Boolean(values['dry-run']),
     };
 }
+function parseDatasetMaintenanceProtectedFlags(args) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args,
+            allowPositionals: false,
+            strict: true,
+            options: {
+                help: { type: 'boolean', short: 'h' },
+                json: { type: 'boolean' },
+                plan: { type: 'string' },
+                freeze: { type: 'string' },
+                approval: { type: 'string' },
+                'out-dir': { type: 'string' },
+                commit: { type: 'boolean' },
+                'status-only': { type: 'boolean' },
+                'approve-execution': { type: 'string' },
+                confirm: { type: 'string' },
+                'wait-seconds': { type: 'string' },
+                'poll-ms': { type: 'string' },
+                'page-size': { type: 'string' },
+                'timeout-ms': { type: 'string' },
+            },
+        }));
+    }
+    catch (error) {
+        throw new CliError(String(error), {
+            code: 'INVALID_ARGS',
+            exitCode: 2,
+        });
+    }
+    return {
+        help: Boolean(values.help),
+        json: Boolean(values.json),
+        planPath: typeof values.plan === 'string' ? values.plan : '',
+        freezePath: typeof values.freeze === 'string' ? values.freeze : '',
+        approvalPath: typeof values.approval === 'string' ? values.approval : '',
+        outDir: typeof values['out-dir'] === 'string' ? values['out-dir'] : '',
+        commit: Boolean(values.commit),
+        statusOnly: Boolean(values['status-only']),
+        approveExecution: typeof values['approve-execution'] === 'string' ? values['approve-execution'] : undefined,
+        confirm: typeof values.confirm === 'string' ? values.confirm : undefined,
+        waitSeconds: parseDatasetMaintenanceNonNegativeInteger(values['wait-seconds'], '--wait-seconds'),
+        pollMs: parseDatasetMaintenancePositiveInteger(values['poll-ms'], '--poll-ms'),
+        pageSize: parseDatasetMaintenancePositiveInteger(values['page-size'], '--page-size'),
+        timeoutMs: parseDatasetMaintenancePositiveInteger(values['timeout-ms'], '--timeout-ms'),
+    };
+}
 function parseDatasetMaintenanceVerifyFlags(args) {
     let values;
     try {
@@ -4905,6 +5015,7 @@ export async function executeCli(argv, deps) {
         const datasetMaintenanceClearAccountImpl = deps.runDatasetMaintenanceClearAccountImpl ?? runDatasetMaintenanceClearAccount;
         const datasetMaintenancePlanImpl = deps.runDatasetMaintenancePlanImpl ?? runDatasetMaintenancePlan;
         const datasetMaintenanceApplyImpl = deps.runDatasetMaintenanceApplyImpl ?? runDatasetMaintenanceApply;
+        const datasetMaintenanceProtectedImpl = deps.runDatasetMaintenanceProtectedImpl ?? runDatasetMaintenanceProtected;
         const datasetMaintenanceVerifyImpl = deps.runDatasetMaintenanceVerifyImpl ?? runDatasetMaintenanceVerify;
         const datasetSourceUploadAttachmentsImpl = deps.runDatasetSourceUploadAttachmentsImpl ?? runDatasetSourceUploadAttachments;
         if (flags.version) {
@@ -5617,6 +5728,85 @@ export async function executeCli(argv, deps) {
                     stderr: '',
                 };
             }
+            if (action === 'run-protected') {
+                const datasetFlags = parseDatasetMaintenanceProtectedFlags(commandArgs.slice(1));
+                if (datasetFlags.help) {
+                    return {
+                        exitCode: 0,
+                        stdout: `${renderDatasetMaintenanceRunProtectedHelp()}\n`,
+                        stderr: '',
+                    };
+                }
+                if (!datasetFlags.planPath) {
+                    throw new CliError('dataset maintenance run-protected requires --plan.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_PLAN_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.freezePath) {
+                    throw new CliError('dataset maintenance run-protected requires --freeze.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_FREEZE_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.approvalPath) {
+                    throw new CliError('dataset maintenance run-protected requires --approval.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_APPROVAL_FILE_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.outDir) {
+                    throw new CliError('dataset maintenance run-protected requires --out-dir.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_OUT_DIR_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (datasetFlags.commit && datasetFlags.statusOnly) {
+                    throw new CliError('Cannot pass both --commit and --status-only.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_MODE_CONFLICT',
+                        exitCode: 2,
+                    });
+                }
+                if (!datasetFlags.commit && !datasetFlags.statusOnly) {
+                    throw new CliError('dataset maintenance run-protected requires either --commit or --status-only.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_MODE_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (datasetFlags.commit && !datasetFlags.approveExecution) {
+                    throw new CliError('dataset maintenance run-protected requires --approve-execution <sha256> with --commit.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_APPROVAL_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                if (datasetFlags.commit && !datasetFlags.confirm) {
+                    throw new CliError('dataset maintenance run-protected requires --confirm <email> with --commit.', {
+                        code: 'DATASET_MAINTENANCE_PROTECTED_CONFIRM_REQUIRED',
+                        exitCode: 2,
+                    });
+                }
+                const report = await datasetMaintenanceProtectedImpl({
+                    planPath: datasetFlags.planPath,
+                    freezePath: datasetFlags.freezePath,
+                    approvalPath: datasetFlags.approvalPath,
+                    outDir: datasetFlags.outDir,
+                    commit: datasetFlags.commit,
+                    statusOnly: datasetFlags.statusOnly,
+                    approveExecution: datasetFlags.approveExecution,
+                    confirm: datasetFlags.confirm,
+                    waitSeconds: datasetFlags.waitSeconds,
+                    pollMs: datasetFlags.pollMs,
+                    pageSize: datasetFlags.pageSize,
+                    timeoutMs: datasetFlags.timeoutMs,
+                    env: deps.env,
+                    fetchImpl: deps.fetchImpl,
+                });
+                return {
+                    exitCode: report.status === 'passed' ? 0 : 1,
+                    stdout: stringifyJson(report, datasetFlags.json),
+                    stderr: '',
+                };
+            }
             if (action === 'verify') {
                 const datasetFlags = parseDatasetMaintenanceVerifyFlags(commandArgs.slice(1));
                 if (datasetFlags.help) {
@@ -5646,7 +5836,7 @@ export async function executeCli(argv, deps) {
                     stderr: '',
                 };
             }
-            throw new CliError("dataset maintenance action must be 'clear-account', 'plan', 'apply', or 'verify'.", {
+            throw new CliError("dataset maintenance action must be 'clear-account', 'plan', 'apply', 'run-protected', or 'verify'.", {
                 code: 'DATASET_MAINTENANCE_ACTION_INVALID',
                 exitCode: 2,
             });