akm-cli 0.9.2-alpha.4 → 0.9.2

package/dist/commands/tasks/explain.js

@@ -0,0 +1,304 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `akm task explain <ref> [input flags]` — read-only task introspection
+ * (spec docs/plans/specs/p2b-input-bindings.md §4.5, §1.7 B-N4).
+ *
+ * Prints the task source path and owning bundle, its input declarations with
+ * defaults, the supplied values WITH PROVENANCE (`default` | `flag` |
+ * `schedule-binding`), the resolved target kind + ref, effective execution
+ * settings with field-level provenance, and schedule bindings.
+ *
+ * Read-only, by construction: this module never reserves a durable attempt
+ * (`src/tasks/run/attempt-lifecycle.ts` is never imported here), never writes
+ * history or a log (`src/tasks/run/task-history.ts` /
+ * `src/tasks/run/task-log.ts` are never imported here), never touches the
+ * scheduler (`src/tasks/scheduler-*.ts` are never imported here), and never
+ * resolves a composed command/persona REF against the local index
+ * (`src/tasks/prepare/prepare.ts`'s own command branch always does, via
+ * `prepareCommandInvocation`'s default `sourceLoader` — an unindexed bundle
+ * would otherwise make a read-only introspection command fail with "Run `akm
+ * index` to build it", which is the wrong shape of dependency for a command
+ * whose whole point is to work on a task the caller just wrote).
+ *
+ * SECRET-FREE BY CONSTRUCTION for the structural bans below — these hold
+ * regardless of any value's shape, because the excluded data never reaches
+ * this module in the first place:
+ *
+ *   - a resolved `env:` value never reaches this module at all — the task's
+ *     OWN `env:` map is deliberately never read from the parsed document;
+ *   - the composed target's ref is read STRUCTURALLY from the already-parsed
+ *     document (`document.target.uses.ref` / `"akm/command"`), never from a
+ *     rendered command/persona source — so a `run:` command string,
+ *     `with.content`, an inline `akm/command` prompt body, or a stored
+ *     command's own rendered content is never read, let alone printed;
+ *   - effective execution settings (engine/model/timeout) reuse
+ *     `prepareResolvedExecution` (`src/integrations/agent/execution-preparation.ts`)
+ *     — the SAME cascade-composition entry point `prepareCommandInvocation`
+ *     itself calls once a command/persona source is already rendered — fed a
+ *     BLANK inline placeholder command (`createInlineResolvedCommand`) and an
+ *     EMPTY command-layer values map, instead of the task's real referenced
+ *     command source. This is a deliberate, documented trade-off: a
+ *     referenced command's OWN frontmatter overrides (its own `engine:`/
+ *     `model:`, if any) do not contribute a layer here, in exchange for never
+ *     needing the index, never reading the referenced file's bytes, and never
+ *     risking a leaked `runtime.environment` value (the cascade's own
+ *     "current" layer, built here from the TASK's own `execution` overrides
+ *     ONLY — engine/model/inference/outputSchema/tools/timeout, deliberately
+ *     never `environment`/`workspace`/`agent`, so a portable persona selector
+ *     can never demand a persona this module never loads). Only
+ *     `engine`/`model`/`runtime.timeoutMs` and the cascade's own
+ *     `{layer,kind,via}` provenance map are read back — never
+ *     `request.command`, `request.persona`, `request.conversation`, or
+ *     `request.runtime.environment`/`.workspace`.
+ *
+ * BEST-EFFORT, NOT A GUARANTEE, for input VALUES: a secret-shaped input
+ * value is redacted only when `detectSecretShapedParams`
+ * (`src/workflows/exec/param-secrets.ts`) recognizes its shape, and that
+ * detector is an explicitly best-effort heuristic — its own doc comment
+ * acknowledges expected false negatives (a short, low-entropy, or
+ * unusually-named credential prints unredacted). A recognized value prints
+ * as the literal string `"<redacted>"`, with its row marked
+ * `redacted: true`, instead of the real value — applied uniformly across
+ * every place a declared or supplied VALUE can appear in this envelope: a
+ * declaration's own `default`, each entry of a declaration's own `enum`
+ * list (checked per-entry, not as one blanked list — code-review finding,
+ * explain.ts:184), a `suppliedInputs` entry regardless of provenance, and a
+ * `schedule[].inputs` entry (code-review finding: the declaration row alone
+ * left the identical value printed verbatim one section over, in
+ * `suppliedInputs`). Do not paste this command's output into an untrusted
+ * place on the assumption that it can never contain a credential.
+ *
+ * Field-level execution provenance is READ from `planExecutionCascade`'s own
+ * `ResolvedExecutionPlanV1.provenance` (via `prepareResolvedExecution`) —
+ * this module is a CONSUMER of the one common cascade resolver, never a
+ * second resolver: it never re-derives engine/model precedence itself.
+ */
+import fs from "node:fs";
+import { detectAdapterId } from "../../core/adapter/detect-adapter.js";
+import { loadConfig } from "../../core/config/config.js";
+import { NotFoundError } from "../../core/errors.js";
+import { applyInputDefaults, materializeInputFlags, } from "../../execution/input-contract.js";
+import { createInlineResolvedCommand } from "../../execution/resolved-request.js";
+import { resolveAdapterConceptOwner } from "../../indexer/lookup/adapter-concept-owner.js";
+import { prepareResolvedExecution } from "../../integrations/agent/execution-preparation.js";
+import { parseTaskSource } from "../../tasks/source/parse-task-source.js";
+import { projectTaskSourceV4 } from "../../tasks/source/project-v4.js";
+import { TASK_INPUT_DIAGNOSTICS } from "../../tasks/source/task-input-diagnostics.js";
+import { validateTaskConceptId, validateTaskId } from "../../tasks/task-id.js";
+import { detectSecretShapedParams } from "../../workflows/exec/param-secrets.js";
+import { parseTaskRef, resolveTaskReadBundle, taskIdForAdapter } from "./tasks.js";
+function isSecretShapedValue(name, value) {
+    return detectSecretShapedParams({ [name]: value }).length > 0;
+}
+/**
+ * Code-review finding (explain.ts:175, B-N4): `buildInputDeclarations`
+ * already redacted a secret-shaped DEFAULT, but `buildSuppliedInputs` (and
+ * a v4 schedule entry's own `inputs`, printed verbatim from the source)
+ * echoed the identical value unredacted in the same envelope — a
+ * `sk-live-…` default appeared in full in both output formats. Applied to
+ * every supplied/schedule-binding row regardless of provenance, so the same
+ * best-effort redaction (see this file's header) applies uniformly across
+ * the whole envelope, not just the declaration row.
+ */
+function redactIfSecretShaped(name, value) {
+    if (!isSecretShapedValue(name, value))
+        return { value };
+    return { value: "<redacted>", redacted: true };
+}
+function declarationType(schema) {
+    return typeof schema.type === "string" ? schema.type : undefined;
+}
+function declarationEnum(schema) {
+    return Array.isArray(schema.enum) ? schema.enum : undefined;
+}
+/**
+ * Code-review finding (explain.ts:184, B-N4): `buildInputDeclarations`
+ * already redacted a secret-shaped `default`, via {@link redactIfSecretShaped}
+ * applied to the WHOLE default value, but the identical value appearing in
+ * that same declaration's JSON-Schema `enum:` list printed unredacted one
+ * key over — an `enum: [..., "sk-live-…"]` list echoed the credential in
+ * full even though the matching `default:` on the same declaration was
+ * already redacted. Fixed by applying the SAME per-value check
+ * ({@link isSecretShapedValue}) to each entry independently, replacing only
+ * the secret-shaped ones with `"<redacted>"` — deliberately NOT collapsing
+ * the whole list to one `"<redacted>"` sentinel the way a single `default`
+ * value is, since an `enum` list's non-secret alternatives are useful
+ * provenance in their own right and dropping them would over-redact.
+ */
+function redactEnum(name, values) {
+    let redacted = false;
+    const out = values.map((value) => {
+        if (!isSecretShapedValue(name, value))
+            return value;
+        redacted = true;
+        return "<redacted>";
+    });
+    return { enum: out, redacted };
+}
+function buildInputDeclarations(contract) {
+    const out = {};
+    for (const [name, declaration] of Object.entries(contract)) {
+        const typedDeclaration = declaration;
+        const hasDefault = Object.hasOwn(typedDeclaration, "default");
+        const secretDefault = hasDefault && isSecretShapedValue(name, typedDeclaration.default);
+        const enumValues = declarationEnum(typedDeclaration.schema);
+        const enumRedaction = enumValues !== undefined ? redactEnum(name, enumValues) : undefined;
+        out[name] = {
+            ...(declarationType(typedDeclaration.schema) !== undefined
+                ? { type: declarationType(typedDeclaration.schema) }
+                : {}),
+            ...(enumRedaction !== undefined ? { enum: enumRedaction.enum } : {}),
+            required: typedDeclaration.required,
+            ...(hasDefault ? { default: secretDefault ? "<redacted>" : typedDeclaration.default } : {}),
+            ...(secretDefault || enumRedaction?.redacted ? { redacted: true } : {}),
+        };
+    }
+    return out;
+}
+function buildSuppliedInputs(defaultedInputs, materializedInputs) {
+    const out = {};
+    for (const [name, value] of Object.entries(defaultedInputs)) {
+        const provenance = Object.hasOwn(materializedInputs, name) ? "flag" : "default";
+        const redaction = redactIfSecretShaped(name, value);
+        out[name] = { value: redaction.value, provenance, ...(redaction.redacted ? { redacted: true } : {}) };
+    }
+    return out;
+}
+/** The composed target's kind + ref, read STRUCTURALLY off the already-parsed document — never from a rendered command/persona source. */
+function targetSection(document) {
+    if (document.target.kind === "run")
+        return { kind: "shell" };
+    const uses = document.target.uses;
+    return { kind: uses.kind, ref: uses.ref };
+}
+/** True only for the two `uses:` kinds an execution cascade (engine/model resolution) actually applies to. */
+function isCommandTarget(document) {
+    return (document.target.kind === "uses" &&
+        (document.target.uses.kind === "builtin-command" || document.target.uses.kind === "command"));
+}
+/**
+ * The task's own top-level execution overrides (`document.akm`, D2-N7's
+ * home for both a v3 document's authored `akm.*` and a v4 document's
+ * projected `execution` block) as a cascade "current" layer — the exact
+ * non-secret subset `src/tasks/prepare/prepare-support.ts`'s
+ * `currentExecutionValues` also forwards, minus `agent`/`workspace`/
+ * `environment` (this module never loads a persona and never reads `env:`,
+ * see this file's header).
+ */
+function currentExecutionValues(document) {
+    const akm = document.akm;
+    if (!akm)
+        return {};
+    const out = {};
+    for (const key of ["engine", "model", "inference", "outputSchema", "tools", "timeout"]) {
+        if (Object.hasOwn(akm, key))
+            out[key] = akm[key];
+    }
+    return out;
+}
+/**
+ * Effective execution settings + field-level provenance for a command-kind
+ * target — see this file's header for why this is a BLANK-command cascade
+ * call rather than a real command/persona load.
+ */
+function resolveExecutionSettings(document) {
+    if (!isCommandTarget(document))
+        return { provenance: {} };
+    const current = currentExecutionValues(document);
+    const prepared = prepareResolvedExecution({
+        command: createInlineResolvedCommand({ template: "", content: "" }),
+        config: loadConfig(),
+        invocationKind: "task",
+        commandLayer: { id: "task-explain", values: {} },
+        ...(Object.keys(current).length > 0 ? { current } : {}),
+    });
+    const engine = prepared.request.engine;
+    return {
+        engine: {
+            name: engine.name,
+            kind: engine.kind,
+            ...(Object.hasOwn(engine, "platform") ? { platform: engine.platform } : {}),
+        },
+        ...(prepared.request.model !== undefined ? { model: prepared.request.model } : {}),
+        ...(prepared.request.runtime.timeoutMs !== undefined ? { timeoutMs: prepared.request.runtime.timeoutMs } : {}),
+        provenance: prepared.plan.provenance,
+    };
+}
+/**
+ * Resolve, parse, and project one task asset into an explain envelope with
+ * every secret-shaped value redacted on a best-effort basis (see this
+ * file's header). Read-only: no history write, no scheduler touch, no
+ * execution spawn.
+ */
+export async function akmTaskExplain(ref, options = {}) {
+    const parsedRef = parseTaskRef(ref);
+    const bundle = resolveTaskReadBundle(parsedRef.bundle, options.target);
+    const adapterId = bundle.source.adapterId ?? detectAdapterId(bundle.source.path);
+    const id = taskIdForAdapter(parsedRef.id, adapterId);
+    if (adapterId === "akm-task")
+        validateTaskConceptId(id);
+    else
+        validateTaskId(id);
+    const taskConceptId = adapterId === "akm" ? `tasks/${id}` : id;
+    const owner = resolveAdapterConceptOwner(bundle.source.path, adapterId, taskConceptId);
+    if (!owner) {
+        throw new NotFoundError(`Task ${JSON.stringify(ref)} was not found in the configured ${JSON.stringify(adapterId)} component.`, "ASSET_NOT_FOUND");
+    }
+    const sourcePath = owner.path;
+    const yaml = fs.readFileSync(sourcePath, "utf8");
+    const parsed = parseTaskSource({ yaml, filePath: sourcePath, workspaceRoot: bundle.source.path });
+    const inputContract = parsed.v4.inputs ?? {};
+    // Code-review finding (explain.ts:299, B-N4): `akm task run`'s
+    // load-task.ts copies this same materialize -> applyInputDefaults ->
+    // validateInputs ladder, but its own trailing `validateInputs` +
+    // `contractViolation` throw is load-task's OWN enforcement that a task
+    // about to actually EXECUTE never dispatches with a required input still
+    // unmet. `explain` never dispatches anything (this file's header) — it is
+    // read-only introspection, and a task's declared-but-unsupplied required
+    // input is exactly the fact `explain` exists to surface, not a condition
+    // that should make the command refuse to print. Deliberately NOT calling
+    // `validateInputs` here: `materializeInputFlags` above still runs its own
+    // per-flag validation (an unknown flag name still fails UNKNOWN_FLAG,
+    // B-55; a supplied value failing its own declared schema still fails
+    // here), so only the "required and never supplied at all" case is left
+    // unenforced. `buildSuppliedInputs` below naturally renders that case as a
+    // declaration row (always present, carrying `required: true`) with no
+    // corresponding `suppliedInputs` entry, since `defaultedInputs` has no key
+    // for an input with neither a default nor a supplied value.
+    const materializedInputs = materializeInputFlags(inputContract, options.inputFlags ?? [], TASK_INPUT_DIAGNOSTICS);
+    const defaultedInputs = applyInputDefaults(inputContract, materializedInputs);
+    const document = projectTaskSourceV4(parsed.v4);
+    const schedule = parsed.v4.schedule.map((entry) => ({
+        ordinal: entry.ordinal,
+        cron: entry.cron,
+        enabled: entry.enabled,
+        source: entry.source,
+        inputs: Object.fromEntries(Object.entries(entry.inputs).map(([name, value]) => {
+            const redaction = redactIfSecretShaped(name, value);
+            return [
+                name,
+                {
+                    value: redaction.value,
+                    provenance: "schedule-binding",
+                    ...(redaction.redacted ? { redacted: true } : {}),
+                },
+            ];
+        })),
+    }));
+    return {
+        ref,
+        taskId: id,
+        bundleName: bundle.source.name,
+        sourcePath,
+        sourceVersion: parsed.version,
+        ...(parsed.v4.name !== undefined ? { name: parsed.v4.name } : {}),
+        ...(parsed.v4.description !== undefined ? { description: parsed.v4.description } : {}),
+        target: targetSection(document),
+        inputDeclarations: buildInputDeclarations(inputContract),
+        suppliedInputs: buildSuppliedInputs(defaultedInputs, materializedInputs),
+        execution: resolveExecutionSettings(document),
+        schedule,
+    };
+}

package/dist/commands/tasks/tasks-cli.js

@@ -29,6 +29,8 @@ import { getParsedInvocation } from "../../cli/invocation.js";
 import { parsePositiveIntFlag } from "../../cli/parse-args.js";
 import { defineGroupCommand, defineJsonCommand, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
 import { UsageError } from "../../core/errors.js";
+import { TASK_RUN_BOOLEAN_FLAGS, TASK_RUN_VALUE_FLAGS } from "../../tasks/task-run-reserved-flags.js";
+import { akmTaskExplain } from "./explain.js";
 import { akmTasksAdd, akmTasksDoctor, akmTasksHistory, akmTasksRun, akmTasksSync } from "./tasks.js";
 /** Shared `--bundle <bundle>` arg wired onto every task subcommand. */
 const bundleArg = {
@@ -37,17 +39,163 @@ const bundleArg = {
         description: "Bundle to operate on (defaults to the primary/default bundle)",
     },
 };
+/**
+ * True when argv carries a `--<name>` flag in ANY spelling — bare,
+ * `--<name>=<value>` for any value, or a trailing `=` — stopping at a literal
+ * `--` separator exactly as `hasFlagIn` (`../../cli/invocation.ts`) does.
+ *
+ * `ParsedInvocation.hasFlag` cannot be used for the rejections below: it
+ * compares WHOLE tokens against `--<name>` and `--<name>=true` only, so every
+ * other value spelling (`--<name>=false`, `--<name>=1`, `--<name>=`) walks
+ * straight past it and is then absorbed downstream — by citty's non-strict
+ * parser, or by `parseTaskInputFlags`' reserved-name skip — exactly the
+ * silent-discard defect these rejecters exist to close (review round 1). The
+ * name is taken as everything before the FIRST `=`, which is
+ * `parseTaskInputFlags`' own split (see its `body.indexOf("=")` below), so the
+ * rejecter and the scanner can never disagree about what a token names.
+ */
+function hasFlagNamed(name) {
+    for (const token of getParsedInvocation().argv) {
+        if (token === "--")
+            return false;
+        if (!token.startsWith("--"))
+            continue;
+        const body = token.slice(2);
+        const equalsAt = body.indexOf("=");
+        if ((equalsAt === -1 ? body : body.slice(0, equalsAt)) === name)
+            return true;
+    }
+    return false;
+}
 /**
  * `--target` was renamed to `--bundle` on `task` in 0.9 (S8.4). citty is
  * non-strict, so the retired spelling is silently absorbed rather than
  * rejected — reject it explicitly instead (mirrors improve-cli.ts /
- * remember-cli.ts).
+ * remember-cli.ts). The generic pre-dispatch gate cannot catch it either: it
+ * exempts `target` on every `task` subcommand precisely so this handler can
+ * answer with the rename (`../../cli/unknown-flags`'s `SELF_DIAGNOSED_FLAGS`),
+ * and that exemption is keyed on the flag NAME — so `--target=team` must be
+ * rejected here by name too, or nothing rejects it at all.
+ *
+ * Rejecting by NAME means `--target=<value>` can no longer carry a declared
+ * task input named `target` either (0.9.2 review round 2). That is settled on
+ * the DECLARATION side, not by narrowing this rejecter back to whole-token
+ * matching: `target` is listed in `TASK_RUN_SELF_DIAGNOSED_FLAGS`
+ * (`../../tasks/task-run-reserved-flags.ts`), so `parseInputDeclarations`
+ * refuses `inputs: {target: …}` with TASK_SOURCE_INVALID at authoring time and
+ * no task can reach `akm task run` needing the flag this throws on. Do not
+ * re-narrow the match here — the silently-ignored `--target=team` that round 1
+ * closed would come straight back.
  */
 function rejectRetiredTaskTargetFlag() {
-    if (!getParsedInvocation().hasFlag("--target"))
+    if (!hasFlagNamed("target"))
         return;
     throw new UsageError("`akm task --target` was renamed to `--bundle` in 0.9. Use `--bundle <name>` instead.", "INVALID_FLAG_VALUE");
 }
+/**
+ * `--scheduled` is `akm task run`'s own declared flag (an internal marker for
+ * scheduler-generated runs) — `task explain` declares no such flag. Because
+ * `explain` reuses `parseTaskInputFlags` (the same exact-name scanner `task
+ * run` uses, see that function's docstring below) to capture input flags, and
+ * `scheduled` is one of that scanner's reserved boolean-flag names
+ * (`TASK_RUN_BOOLEAN_FLAG_SET`, from `../../tasks/task-run-reserved-flags`),
+ * the scanner silently skips over `--scheduled` rather than ever surfacing it
+ * as an input flag — so it reached neither `materializeInputFlags`' own
+ * unknown-flag diagnostic nor the generic pre-dispatch flag gate (which
+ * exempts `task explain`'s whole dynamic namespace, `../../cli/unknown-flags`
+ * §`dynamicNamedFlagCommands`). The net effect: `akm task explain <ref>
+ * --scheduled` silently accepted and discarded the flag instead of rejecting
+ * it (finding F7) — `scheduled` can never be a declared input name either
+ * (same reserved-name module), so this can never reject a flag that was ever
+ * a valid input binding. Reject it explicitly, before the shared scanner ever
+ * sees it — same UNKNOWN_FLAG diagnostic family the generic gate uses.
+ *
+ * Rejection is keyed on the flag NAME (`hasFlagNamed` above), not on a literal
+ * token: `parseTaskInputFlags` splits on the first `=` BEFORE its reserved-name
+ * check, so `--scheduled=false` and `--scheduled=1` are swallowed by that skip
+ * just as the bare token is. A whole-token test would leave every spelling but
+ * `--scheduled` / `--scheduled=true` in the hole this exists to close.
+ */
+function rejectExplainScheduledFlag() {
+    if (!hasFlagNamed("scheduled"))
+        return;
+    throw new UsageError('Unknown flag "--scheduled".', "UNKNOWN_FLAG");
+}
+// ── `akm task run` input flags — Stage 1: capture (spec §5.1) ──────────────
+//
+// Mirrors `parseWorkflowParameterFlags` (src/commands/workflow-cli.ts:232-289)
+// exactly: the CLI carries RAW string/boolean flag values to the boundary
+// that knows the task's declared contract (Stage 2, src/tasks/run/load-task.ts)
+// — coercion happens once, there. `akm task run`'s own declared flags
+// (GLOBAL_OUTPUT_ARGS, --bundle, --scheduled) are excluded so they are never
+// mistaken for inputs (B-33); `--target` is excluded too, but only because
+// `rejectRetiredTaskTargetFlag()` above always runs first and throws before
+// this is ever reached (B-32) — it is not itself special-cased below.
+// `TASK_RUN_VALUE_FLAGS` / `TASK_RUN_BOOLEAN_FLAGS` are re-exported here
+// (unchanged in name, location, and value) from a dependency-free leaf module
+// so `src/tasks/source/task-source-v4.ts` can reject a declared `inputs:`
+// name that collides with one of them without importing this CLI file —
+// which would cycle back through `./tasks` -> `../../tasks/source/*` into the
+// parser (code-review finding, docs/plans/specs/p2b-input-bindings.md review
+// round 2; see `../../tasks/task-run-reserved-flags.ts`'s own header).
+export { TASK_RUN_BOOLEAN_FLAGS, TASK_RUN_VALUE_FLAGS };
+const TASK_RUN_VALUE_FLAG_SET = new Set(TASK_RUN_VALUE_FLAGS);
+const TASK_RUN_BOOLEAN_FLAG_SET = new Set(TASK_RUN_BOOLEAN_FLAGS);
+/**
+ * Scan `akm task run`'s raw argv for exact-name input flags, excluding the
+ * task id and every declared flag above. Input flags must come after the
+ * task id (mirrors `parseWorkflowParameterFlags`'s positional rule); a bare
+ * `--` is rejected, matching `workflow run`.
+ */
+export function parseTaskInputFlags(rawArgs, id) {
+    const flags = [];
+    let idSeen = false;
+    for (let index = 0; index < rawArgs.length; index += 1) {
+        const token = rawArgs[index];
+        if (token === "--") {
+            throw new UsageError("`akm task run` does not accept positional arguments after `--`.", "INVALID_FLAG_VALUE");
+        }
+        if (!token.startsWith("-") || token === "-" || /^-\d/.test(token)) {
+            if (!idSeen) {
+                if (token !== id) {
+                    throw new UsageError("Task input flags must come after the task id.", "INVALID_FLAG_VALUE");
+                }
+                idSeen = true;
+                continue;
+            }
+            throw new UsageError(`Unexpected positional task argument "${token}".`, "INVALID_FLAG_VALUE");
+        }
+        if (!token.startsWith("--"))
+            continue;
+        const body = token.slice(2);
+        const equalsAt = body.indexOf("=");
+        const name = equalsAt === -1 ? body : body.slice(0, equalsAt);
+        const inlineValue = equalsAt === -1 ? undefined : body.slice(equalsAt + 1);
+        if (TASK_RUN_VALUE_FLAG_SET.has(name)) {
+            if (inlineValue === undefined)
+                index += 1;
+            continue;
+        }
+        if (TASK_RUN_BOOLEAN_FLAG_SET.has(name))
+            continue;
+        if (!idSeen) {
+            throw new UsageError("Task input flags must come after the task id.", "INVALID_FLAG_VALUE");
+        }
+        if (inlineValue !== undefined) {
+            flags.push({ name, value: inlineValue });
+            continue;
+        }
+        const next = rawArgs[index + 1];
+        if (next !== undefined && (!next.startsWith("-") || /^-\d/.test(next))) {
+            flags.push({ name, value: next });
+            index += 1;
+        }
+        else {
+            flags.push({ name, value: true });
+        }
+    }
+    return flags;
+}
 const tasksAddCommand = defineJsonCommand({
     meta: { name: "add", description: "Register a new scheduled task and install it in the OS scheduler" },
     args: {
@@ -121,12 +269,14 @@ const tasksRunCommand = defineCommand({
         ...bundleArg,
         scheduled: { type: "boolean", description: "Internal marker for scheduler-generated runs", default: false },
     },
-    async run({ args }) {
+    async run({ args, rawArgs }) {
         await runWithJsonErrors(async () => {
             rejectRetiredTaskTargetFlag();
+            const inputFlags = parseTaskInputFlags(rawArgs, args.id);
             const envelope = await akmTasksRun(args.id, {
                 scheduled: args.scheduled === true,
                 ...(args.bundle !== undefined ? { target: args.bundle } : {}),
+                inputFlags,
             });
             output("task-run", envelope);
             // F4: was `process.exit(envelope.exitCode)`, terminating synchronously
@@ -172,6 +322,37 @@ const tasksSyncCommand = defineJsonCommand({
         output("task-sync", result);
     },
 });
+// ── `akm task explain` — read-only introspection (P2b Lane B, spec
+// docs/plans/specs/p2b-input-bindings.md §4.5, §1.7 B-N4) ──────────────────
+const tasksExplainCommand = defineJsonCommand({
+    meta: {
+        name: "explain",
+        description: "Print a task's source, declared inputs (with provenance), resolved target, execution settings, and " +
+            "schedule bindings — read-only and secret-free; never spawns anything",
+    },
+    args: {
+        ref: { type: "positional", description: "Task ref or id", required: true },
+        ...bundleArg,
+    },
+    async run({ args, rawArgs }) {
+        rejectRetiredTaskTargetFlag();
+        // `--scheduled` must be rejected BEFORE the shared scanner below ever
+        // sees it — the scanner treats it as `task run`'s own reserved flag
+        // (silently skipped, never surfaced as unknown) rather than explain's,
+        // since it has no way to know which command called it (F7 fix).
+        rejectExplainScheduledFlag();
+        // Stage 1 (capture): the SAME exact-name flag scanner `akm task run`
+        // uses (`parseTaskInputFlags` above) — `explain` never declares
+        // `--scheduled`, but reusing the identical scanner is deliberate: one
+        // implementation of "which argv tokens are task input flags", not two.
+        const inputFlags = parseTaskInputFlags(rawArgs, args.ref);
+        const result = await akmTaskExplain(args.ref, {
+            ...(args.bundle !== undefined ? { target: args.bundle } : {}),
+            inputFlags,
+        });
+        output("task-explain", result);
+    },
+});
 const tasksDoctorCommand = defineJsonCommand({
     meta: {
         name: "doctor",
@@ -191,6 +372,7 @@ export const taskCommand = defineGroupCommand({
     subCommands: {
         add: tasksAddCommand,
         run: tasksRunCommand,
+        explain: tasksExplainCommand,
         history: tasksHistoryCommand,
         sync: tasksSyncCommand,
         doctor: tasksDoctorCommand,