sequant 2.9.0 → 2.11.0

package/dist/src/lib/assess/types.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Schema for `/assess` rendered output (#823).
+ *
+ * The `/assess` skill produces judgment (triage verdicts); this schema is the
+ * contract it hands to the renderer, which produces geometry. Splitting the two
+ * is the point of #823: the model stopped emitting the output block at all, and
+ * when it did emit one the columns drifted, because deterministic formatting was
+ * being done by hand in a prompt.
+ *
+ * Modeled on `src/lib/scope/types.ts` (the in-repo precedent for a zod schema
+ * module). Deliberately carries no rendering logic — see `./renderer.ts`.
+ */
+import { z } from "zod";
+/**
+ * The fixed action vocabulary from `skills/assess/SKILL.md`. Every assessed
+ * issue gets exactly one.
+ */
+export declare const AssessActionSchema: z.ZodEnum<{
+    PROCEED: "PROCEED";
+    CLOSE: "CLOSE";
+    MERGE: "MERGE";
+    REWRITE: "REWRITE";
+    CLARIFY: "CLARIFY";
+    PARK: "PARK";
+}>;
+export type AssessAction = z.infer<typeof AssessActionSchema>;
+/**
+ * A `sequant` invocation. `args` excludes the command prefix — the renderer
+ * prepends the single resolved `commandPrefix` so one assessment can never mix
+ * `sequant` and `npx sequant` (Commands Block Rule #9).
+ */
+export declare const AssessCommandSchema: z.ZodObject<{
+    args: z.ZodString;
+    comment: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type AssessCommand = z.infer<typeof AssessCommandSchema>;
+/**
+ * A `Cleanup:` entry. These are `git`/`gh` commands, not `sequant` ones, so
+ * they carry no prefix and are emitted verbatim.
+ */
+export declare const AssessCleanupSchema: z.ZodObject<{
+    command: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type AssessCleanup = z.infer<typeof AssessCleanupSchema>;
+/** A `Flags:` entry — one distinct flag plus its one-line justification. */
+export declare const AssessFlagSchema: z.ZodObject<{
+    flag: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strict>;
+export type AssessFlag = z.infer<typeof AssessFlagSchema>;
+/**
+ * A `Considered:` entry — a flag or topology (`--chain`, `--testgen`,
+ * `--security-review`, …) whose trigger was evaluated and **not** met, plus the
+ * one-line reason it was not applied. Restores the why-not reasoning the
+ * original `/solve` format carried ("Also consider:") that the v3.0 redesign
+ * dropped and #522 only partially restored.
+ */
+export declare const AssessConsideredSchema: z.ZodObject<{
+    flag: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strict>;
+export type AssessConsidered = z.infer<typeof AssessConsideredSchema>;
+/**
+ * A `⚠` warning. In batch mode `issue` scopes it to a row (`⚠ #458 ...`); in a
+ * posted single-mode comment the number is dropped because the comment is
+ * already scoped to that issue.
+ */
+export declare const AssessWarningSchema: z.ZodObject<{
+    issue: z.ZodOptional<z.ZodNumber>;
+    text: z.ZodString;
+}, z.core.$strict>;
+export type AssessWarning = z.infer<typeof AssessWarningSchema>;
+/**
+ * One assessed issue. Batch mode consumes the table fields; single mode
+ * consumes the detail fields. Cross-field requirements are enforced per-mode in
+ * {@link AssessResultSchema}'s refinement rather than by making fields
+ * unconditionally required, so a batch payload is not forced to carry titles it
+ * never renders.
+ */
+export declare const AssessIssueSchema: z.ZodObject<{
+    number: z.ZodNumber;
+    action: z.ZodEnum<{
+        PROCEED: "PROCEED";
+        CLOSE: "CLOSE";
+        MERGE: "MERGE";
+        REWRITE: "REWRITE";
+        CLARIFY: "CLARIFY";
+        PARK: "PARK";
+    }>;
+    reason: z.ZodString;
+    run: z.ZodOptional<z.ZodString>;
+    acCount: z.ZodOptional<z.ZodNumber>;
+    phases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    qualityLoop: z.ZodOptional<z.ZodBoolean>;
+    title: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    command: z.ZodOptional<z.ZodObject<{
+        args: z.ZodString;
+        comment: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    supersession: z.ZodOptional<z.ZodString>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    flags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        flag: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
+    considered: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        flag: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
+    cleanup: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    mergeTarget: z.ZodOptional<z.ZodNumber>;
+    scopeSelf: z.ZodOptional<z.ZodString>;
+    scopeTarget: z.ZodOptional<z.ZodString>;
+    need: z.ZodOptional<z.ZodString>;
+    needDetail: z.ZodOptional<z.ZodString>;
+    resumeAfter: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type AssessIssue = z.infer<typeof AssessIssueSchema>;
+/** `Chain:` suggestion — an alternative execution topology, never auto-applied. */
+export declare const AssessChainSchema: z.ZodObject<{
+    args: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strict>;
+export type AssessChain = z.infer<typeof AssessChainSchema>;
+/**
+ * The complete payload the `/assess` skill hands to the renderer.
+ *
+ * `.strict()` throughout is deliberate: a typo'd key is a silent data-loss bug
+ * in a hand-built JSON payload, and naming the unknown key is exactly the
+ * actionable error AC-2 asks for.
+ */
+export declare const AssessResultSchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        single: "single";
+        batch: "batch";
+    }>;
+    commandPrefix: z.ZodString;
+    issues: z.ZodArray<z.ZodObject<{
+        number: z.ZodNumber;
+        action: z.ZodEnum<{
+            PROCEED: "PROCEED";
+            CLOSE: "CLOSE";
+            MERGE: "MERGE";
+            REWRITE: "REWRITE";
+            CLARIFY: "CLARIFY";
+            PARK: "PARK";
+        }>;
+        reason: z.ZodString;
+        run: z.ZodOptional<z.ZodString>;
+        acCount: z.ZodOptional<z.ZodNumber>;
+        phases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        qualityLoop: z.ZodOptional<z.ZodBoolean>;
+        title: z.ZodOptional<z.ZodString>;
+        state: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        command: z.ZodOptional<z.ZodObject<{
+            args: z.ZodString;
+            comment: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        supersession: z.ZodOptional<z.ZodString>;
+        warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        flags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            flag: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$strict>>>;
+        considered: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            flag: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$strict>>>;
+        cleanup: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            command: z.ZodString;
+            reason: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        mergeTarget: z.ZodOptional<z.ZodNumber>;
+        scopeSelf: z.ZodOptional<z.ZodString>;
+        scopeTarget: z.ZodOptional<z.ZodString>;
+        need: z.ZodOptional<z.ZodString>;
+        needDetail: z.ZodOptional<z.ZodString>;
+        resumeAfter: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    commands: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        args: z.ZodString;
+        comment: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    orders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        issue: z.ZodOptional<z.ZodNumber>;
+        text: z.ZodString;
+    }, z.core.$strict>>>;
+    chain: z.ZodOptional<z.ZodObject<{
+        args: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>;
+    flags: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        flag: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
+    considered: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        flag: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strict>>>;
+    cleanup: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        command: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export type AssessResult = z.infer<typeof AssessResultSchema>;
+/** Raised by {@link parseAssessResult} when validation fails. */
+export declare class AssessResultValidationError extends Error {
+    readonly problems: string[];
+    constructor(message: string, problems: string[]);
+}
+/**
+ * Validate an untrusted payload against {@link AssessResultSchema}.
+ *
+ * @throws {AssessResultValidationError} naming every offending field.
+ */
+export declare function parseAssessResult(input: unknown): AssessResult;

package/dist/src/lib/assess/types.js

@@ -0,0 +1,241 @@
+/**
+ * Schema for `/assess` rendered output (#823).
+ *
+ * The `/assess` skill produces judgment (triage verdicts); this schema is the
+ * contract it hands to the renderer, which produces geometry. Splitting the two
+ * is the point of #823: the model stopped emitting the output block at all, and
+ * when it did emit one the columns drifted, because deterministic formatting was
+ * being done by hand in a prompt.
+ *
+ * Modeled on `src/lib/scope/types.ts` (the in-repo precedent for a zod schema
+ * module). Deliberately carries no rendering logic — see `./renderer.ts`.
+ */
+import { z } from "zod";
+/**
+ * The fixed action vocabulary from `skills/assess/SKILL.md`. Every assessed
+ * issue gets exactly one.
+ */
+export const AssessActionSchema = z.enum([
+    "PROCEED",
+    "CLOSE",
+    "MERGE",
+    "REWRITE",
+    "CLARIFY",
+    "PARK",
+]);
+/**
+ * A `sequant` invocation. `args` excludes the command prefix — the renderer
+ * prepends the single resolved `commandPrefix` so one assessment can never mix
+ * `sequant` and `npx sequant` (Commands Block Rule #9).
+ */
+export const AssessCommandSchema = z
+    .object({
+    /** Everything after the prefix, e.g. `run 820 819 -Q`. */
+    args: z.string().min(1),
+    /** Trailing `# ...` annotation, e.g. `resume`, `restart`, `fresh start`. */
+    comment: z.string().optional(),
+})
+    .strict();
+/**
+ * A `Cleanup:` entry. These are `git`/`gh` commands, not `sequant` ones, so
+ * they carry no prefix and are emitted verbatim.
+ */
+export const AssessCleanupSchema = z
+    .object({
+    command: z.string().min(1),
+    reason: z.string().optional(),
+})
+    .strict();
+/** A `Flags:` entry — one distinct flag plus its one-line justification. */
+export const AssessFlagSchema = z
+    .object({
+    flag: z.string().min(1),
+    reason: z.string().min(1),
+})
+    .strict();
+/**
+ * A `Considered:` entry — a flag or topology (`--chain`, `--testgen`,
+ * `--security-review`, …) whose trigger was evaluated and **not** met, plus the
+ * one-line reason it was not applied. Restores the why-not reasoning the
+ * original `/solve` format carried ("Also consider:") that the v3.0 redesign
+ * dropped and #522 only partially restored.
+ */
+export const AssessConsideredSchema = AssessFlagSchema;
+/**
+ * A `⚠` warning. In batch mode `issue` scopes it to a row (`⚠ #458 ...`); in a
+ * posted single-mode comment the number is dropped because the comment is
+ * already scoped to that issue.
+ */
+export const AssessWarningSchema = z
+    .object({
+    issue: z.number().int().positive().optional(),
+    text: z.string().min(1),
+})
+    .strict();
+/**
+ * One assessed issue. Batch mode consumes the table fields; single mode
+ * consumes the detail fields. Cross-field requirements are enforced per-mode in
+ * {@link AssessResultSchema}'s refinement rather than by making fields
+ * unconditionally required, so a batch payload is not forced to carry titles it
+ * never renders.
+ */
+export const AssessIssueSchema = z
+    .object({
+    number: z.number().int().positive(),
+    action: AssessActionSchema,
+    /** Short `Reason` column text. The only column the renderer truncates. */
+    reason: z.string().min(1),
+    /** `Run` column value — a workflow (`spec → exec → qa`) or a symbol (`‖`). */
+    run: z.string().min(1).optional(),
+    /** Drives the conditional `ACs` column; omit when the issue has no checkbox ACs. */
+    acCount: z.number().int().nonnegative().optional(),
+    /** Resolved workflow, recorded in the HTML marker regardless of shorthand flags. */
+    phases: z.array(z.string().min(1)).optional(),
+    qualityLoop: z.boolean().optional(),
+    // --- single mode / posted comment ---
+    title: z.string().min(1).optional(),
+    state: z.string().min(1).optional(),
+    labels: z.array(z.string().min(1)).optional(),
+    /** This issue's own single-issue invocation (PROCEED / REWRITE). */
+    command: AssessCommandSchema.optional(),
+    /** `buildSupersessionHeader(priors)` output, emitted above the verdict line. */
+    supersession: z.string().min(1).optional(),
+    /** Per-issue warnings with the leading `#N` already dropped. */
+    warnings: z.array(z.string().min(1)).optional(),
+    flags: z.array(AssessFlagSchema).optional(),
+    /** Flags evaluated but not applied, each with its why-not reason. */
+    considered: z.array(AssessConsideredSchema).optional(),
+    cleanup: z.array(AssessCleanupSchema).optional(),
+    // --- verdict-specific ---
+    /** MERGE: the issue absorbing this one. */
+    mergeTarget: z.number().int().positive().optional(),
+    /** MERGE: this issue's scope summary. */
+    scopeSelf: z.string().min(1).optional(),
+    /** MERGE: the target's scope summary. */
+    scopeTarget: z.string().min(1).optional(),
+    /** CLARIFY: the specific information required. */
+    need: z.string().min(1).optional(),
+    /** CLARIFY: why the gap blocks work. */
+    needDetail: z.string().min(1).optional(),
+    /** PARK: the condition that unblocks this issue. */
+    resumeAfter: z.string().min(1).optional(),
+})
+    .strict();
+/** `Chain:` suggestion — an alternative execution topology, never auto-applied. */
+export const AssessChainSchema = z
+    .object({
+    args: z.string().min(1),
+    reason: z.string().min(1),
+})
+    .strict();
+/**
+ * The complete payload the `/assess` skill hands to the renderer.
+ *
+ * `.strict()` throughout is deliberate: a typo'd key is a silent data-loss bug
+ * in a hand-built JSON payload, and naming the unknown key is exactly the
+ * actionable error AC-2 asks for.
+ */
+export const AssessResultSchema = z
+    .object({
+    mode: z.enum(["batch", "single"]),
+    /** Resolved in the skill's Step-1 probe: `sequant` or `npx sequant`. */
+    commandPrefix: z.string().min(1),
+    issues: z.array(AssessIssueSchema).min(1),
+    // --- batch-only sections ---
+    commands: z.array(AssessCommandSchema).optional(),
+    /** `Order:` annotations, each carrying dependency reasoning. */
+    orders: z.array(z.string().min(1)).optional(),
+    warnings: z.array(AssessWarningSchema).optional(),
+    chain: AssessChainSchema.optional(),
+    flags: z.array(AssessFlagSchema).optional(),
+    /** Flags evaluated but not applied, each with its why-not reason. */
+    considered: z.array(AssessConsideredSchema).optional(),
+    cleanup: z.array(AssessCleanupSchema).optional(),
+})
+    .strict()
+    .superRefine((result, ctx) => {
+    if (result.mode === "batch") {
+        result.issues.forEach((issue, i) => {
+            if (!issue.run) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["issues", i, "run"],
+                    message: `batch mode requires a Run column value for issue #${issue.number}`,
+                });
+            }
+        });
+        return;
+    }
+    if (result.issues.length !== 1) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["issues"],
+            message: `single mode renders exactly one issue, received ${result.issues.length}`,
+        });
+    }
+    result.issues.forEach((issue, i) => {
+        for (const field of ["title", "state"]) {
+            if (!issue[field]) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: ["issues", i, field],
+                    message: `single mode requires ${field} for the #${issue.number} header line`,
+                });
+            }
+        }
+        if (issue.action === "MERGE" && issue.mergeTarget === undefined) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["issues", i, "mergeTarget"],
+                message: "MERGE requires the target issue number",
+            });
+        }
+        if (issue.action === "PARK" && !issue.resumeAfter) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["issues", i, "resumeAfter"],
+                message: "PARK requires a resume condition",
+            });
+        }
+        if (issue.action === "CLARIFY" && !issue.need) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["issues", i, "need"],
+                message: "CLARIFY requires the specific information needed",
+            });
+        }
+    });
+});
+/** Raised by {@link parseAssessResult} when validation fails. */
+export class AssessResultValidationError extends Error {
+    problems;
+    constructor(message, problems) {
+        super(message);
+        this.problems = problems;
+        this.name = "AssessResultValidationError";
+    }
+}
+/**
+ * Render a zod path as a readable field reference: `issues[2].action`.
+ */
+function formatPath(path) {
+    if (path.length === 0)
+        return "(root)";
+    return path.reduce((acc, segment) => {
+        if (typeof segment === "number")
+            return `${acc}[${segment}]`;
+        return acc === "" ? String(segment) : `${acc}.${String(segment)}`;
+    }, "");
+}
+/**
+ * Validate an untrusted payload against {@link AssessResultSchema}.
+ *
+ * @throws {AssessResultValidationError} naming every offending field.
+ */
+export function parseAssessResult(input) {
+    const result = AssessResultSchema.safeParse(input);
+    if (result.success)
+        return result.data;
+    const problems = result.error.issues.map((issue) => `${formatPath(issue.path)}: ${issue.message}`);
+    throw new AssessResultValidationError(`Invalid AssessResult:\n  ${problems.join("\n  ")}`, problems);
+}

package/dist/src/lib/ci/outputs.d.ts

@@ -12,8 +12,15 @@ import type { ActionOutputs } from "./types.js";
 export declare function formatOutputs(result: IssueResult): ActionOutputs;
 /**
  * Format multiple issue results into combined outputs.
+ *
+ * @param wallClockDurationSeconds - The run's wall-clock duration, computed by
+ * whoever brackets the run (the orchestrator surfaces it as
+ * `RunResult.wallClockDurationSeconds`). It is a required argument rather than
+ * something derived here because the per-issue durations this function receives
+ * cannot express it: under `--parallel` they overlap, so summing them
+ * double-counts and over-reports by roughly the concurrency factor (#867).
  */
-export declare function formatMultiOutputs(results: IssueResult[]): ActionOutputs;
+export declare function formatMultiOutputs(results: IssueResult[], wallClockDurationSeconds: number): ActionOutputs;
 /**
  * Generate shell commands to set GitHub Actions outputs.
  * Each output is written to $GITHUB_OUTPUT file.
@@ -21,5 +28,11 @@ export declare function formatMultiOutputs(results: IssueResult[]): ActionOutput
 export declare function outputCommands(outputs: ActionOutputs): string[];
 /**
  * Generate a GitHub Actions step summary (Markdown).
+ *
+ * @param wallClockDurationSeconds - The run's wall-clock duration. Required for
+ * the same reason as in {@link formatMultiOutputs}: the per-issue durations
+ * below overlap under `--parallel`, so the "Total duration" line cannot be
+ * derived by summing them (#867). Per-*phase* durations in the tables are
+ * unaffected — phases within an issue run sequentially.
  */
-export declare function formatSummary(results: IssueResult[]): string;
+export declare function formatSummary(results: IssueResult[], wallClockDurationSeconds: number): string;

package/dist/src/lib/ci/outputs.js

@@ -18,10 +18,17 @@ export function formatOutputs(result) {
 }
 /**
  * Format multiple issue results into combined outputs.
+ *
+ * @param wallClockDurationSeconds - The run's wall-clock duration, computed by
+ * whoever brackets the run (the orchestrator surfaces it as
+ * `RunResult.wallClockDurationSeconds`). It is a required argument rather than
+ * something derived here because the per-issue durations this function receives
+ * cannot express it: under `--parallel` they overlap, so summing them
+ * double-counts and over-reports by roughly the concurrency factor (#867).
  */
-export function formatMultiOutputs(results) {
+export function formatMultiOutputs(results, wallClockDurationSeconds) {
     const allSuccess = results.every((r) => r.success);
-    const totalDuration = results.reduce((sum, r) => sum + (r.durationSeconds ?? 0), 0);
+    const totalDuration = wallClockDurationSeconds;
     const prUrls = results
         .map((r) => r.prUrl)
         .filter(Boolean)
@@ -54,8 +61,14 @@ export function outputCommands(outputs) {
 }
 /**
  * Generate a GitHub Actions step summary (Markdown).
+ *
+ * @param wallClockDurationSeconds - The run's wall-clock duration. Required for
+ * the same reason as in {@link formatMultiOutputs}: the per-issue durations
+ * below overlap under `--parallel`, so the "Total duration" line cannot be
+ * derived by summing them (#867). Per-*phase* durations in the tables are
+ * unaffected — phases within an issue run sequentially.
  */
-export function formatSummary(results) {
+export function formatSummary(results, wallClockDurationSeconds) {
     const lines = [];
     lines.push("## Sequant Workflow Results\n");
     for (const result of results) {
@@ -78,7 +91,6 @@ export function formatSummary(results) {
         }
         lines.push("");
     }
-    const total = results.reduce((sum, r) => sum + (r.durationSeconds ?? 0), 0);
-    lines.push(`**Total duration:** ${total}s`);
+    lines.push(`**Total duration:** ${wallClockDurationSeconds}s`);
     return lines.join("\n");
 }

package/dist/src/lib/cli-flags.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Commander argument coercions for numeric CLI flags.
+ *
+ * Lives here rather than inline in `bin/cli.ts` so it can be unit-tested
+ * directly — `bin/cli.ts` calls `program.parse()` at import time and cannot be
+ * imported from a test.
+ *
+ * @module
+ */
+/** Error-text shaping for a numeric flag. Affects messages only, not parsing. */
+export interface WholeNumberOptions {
+    /** Smallest accepted value. Use 0 where 0 is a meaningful "off" setting. */
+    min: number;
+    /** Plural unit, e.g. `"seconds"`. Omit for a flag that reads better bare. */
+    unit?: string;
+    /** Singular unit, used when `min` is 1 ("at least 1 second"). */
+    unitSingular?: string;
+}
+/**
+ * Build a commander coercion for a whole-number flag.
+ *
+ * A bare `parseInt` is unsafe for these: `parseInt("abc", 10)` is `NaN`, which
+ * is not nullish and so survives a `?? default`, and `parseInt("30m", 10)`
+ * silently yields `30` — the user asked for 30 minutes and got 30 seconds.
+ * Requiring the whole string to be digits rejects both instead of accepting a
+ * value that is unusable or quietly wrong (#818, #833).
+ */
+export declare function parseWholeNumber(flag: string, opts: WholeNumberOptions): (value: string) => number;
+/**
+ * A positive-integer *seconds* flag — the #831 shape, preserved verbatim so the
+ * `merge --watch` messages this originally shipped with do not change.
+ */
+export declare function parsePositiveSeconds(flag: string): (value: string) => number;
+/**
+ * Build a commander coercion for a `--models`/`--efforts`-shaped flag (#914).
+ *
+ * Validates the spec via `config-resolver.ts`'s `parsePhaseSpec` — a bare
+ * value applies to every phase, a comma list of `phase=value` pairs applies
+ * per phase, and a malformed spec (empty segment, mixed bare/pair form, or
+ * an unrecognized phase name) fails fast here rather than reaching
+ * `resolvePhasePolicies` silently. On success, returns the ORIGINAL raw spec
+ * string unchanged (not the parsed map) — `RunOptions.models`/`.efforts`
+ * stay plain strings, and `resolvePhasePolicies` re-parses for real when
+ * building `ExecutionConfig.phasePolicies`, so parsing has exactly one
+ * source of truth even though it runs twice.
+ *
+ * `allowedValues`, when given, additionally rejects any resolved value not
+ * in the set — used for `--efforts` (closed enum: `settings.ts:EFFORT_LEVELS`)
+ * so a typo like `--efforts exec=mediu` fails at the CLI boundary the same
+ * way it already does when set via `settings.json`, instead of only
+ * surfacing once the value reaches the SDK. `--models` passes no
+ * `allowedValues` — model aliases/IDs are intentionally unvalidated (they
+ * churn independently of sequant releases; the SDK errors clearly on a bad
+ * one).
+ */
+export declare function parsePhaseSpecFlag(flag: string, phaseNames: string[], allowedValues?: readonly string[]): (value: string) => string;

package/dist/src/lib/cli-flags.js

@@ -0,0 +1,89 @@
+/**
+ * Commander argument coercions for numeric CLI flags.
+ *
+ * Lives here rather than inline in `bin/cli.ts` so it can be unit-tested
+ * directly — `bin/cli.ts` calls `program.parse()` at import time and cannot be
+ * imported from a test.
+ *
+ * @module
+ */
+import { InvalidArgumentError } from "commander";
+import { parsePhaseSpec } from "./workflow/config-resolver.js";
+/**
+ * Build a commander coercion for a whole-number flag.
+ *
+ * A bare `parseInt` is unsafe for these: `parseInt("abc", 10)` is `NaN`, which
+ * is not nullish and so survives a `?? default`, and `parseInt("30m", 10)`
+ * silently yields `30` — the user asked for 30 minutes and got 30 seconds.
+ * Requiring the whole string to be digits rejects both instead of accepting a
+ * value that is unusable or quietly wrong (#818, #833).
+ */
+export function parseWholeNumber(flag, opts) {
+    const { min, unit, unitSingular } = opts;
+    const ofUnit = unit ? ` of ${unit}` : "";
+    const minUnit = min === 1 ? (unitSingular ?? unit) : unit;
+    const minSuffix = minUnit ? ` ${minUnit}` : "";
+    return (value) => {
+        if (!/^\d+$/.test(value.trim())) {
+            throw new InvalidArgumentError(`${flag} expects a whole number${ofUnit} (got '${value}').`);
+        }
+        const parsed = Number(value);
+        if (!Number.isSafeInteger(parsed) || parsed < min) {
+            throw new InvalidArgumentError(`${flag} must be at least ${min}${minSuffix} (got '${value}').`);
+        }
+        return parsed;
+    };
+}
+/**
+ * A positive-integer *seconds* flag — the #831 shape, preserved verbatim so the
+ * `merge --watch` messages this originally shipped with do not change.
+ */
+export function parsePositiveSeconds(flag) {
+    return parseWholeNumber(flag, {
+        min: 1,
+        unit: "seconds",
+        unitSingular: "second",
+    });
+}
+/**
+ * Build a commander coercion for a `--models`/`--efforts`-shaped flag (#914).
+ *
+ * Validates the spec via `config-resolver.ts`'s `parsePhaseSpec` — a bare
+ * value applies to every phase, a comma list of `phase=value` pairs applies
+ * per phase, and a malformed spec (empty segment, mixed bare/pair form, or
+ * an unrecognized phase name) fails fast here rather than reaching
+ * `resolvePhasePolicies` silently. On success, returns the ORIGINAL raw spec
+ * string unchanged (not the parsed map) — `RunOptions.models`/`.efforts`
+ * stay plain strings, and `resolvePhasePolicies` re-parses for real when
+ * building `ExecutionConfig.phasePolicies`, so parsing has exactly one
+ * source of truth even though it runs twice.
+ *
+ * `allowedValues`, when given, additionally rejects any resolved value not
+ * in the set — used for `--efforts` (closed enum: `settings.ts:EFFORT_LEVELS`)
+ * so a typo like `--efforts exec=mediu` fails at the CLI boundary the same
+ * way it already does when set via `settings.json`, instead of only
+ * surfacing once the value reaches the SDK. `--models` passes no
+ * `allowedValues` — model aliases/IDs are intentionally unvalidated (they
+ * churn independently of sequant releases; the SDK errors clearly on a bad
+ * one).
+ */
+export function parsePhaseSpecFlag(flag, phaseNames, allowedValues) {
+    return (value) => {
+        let parsed;
+        try {
+            parsed = parsePhaseSpec(value, phaseNames);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new InvalidArgumentError(`${flag}: ${message}`);
+        }
+        if (allowedValues) {
+            for (const v of Object.values(parsed)) {
+                if (!allowedValues.includes(v)) {
+                    throw new InvalidArgumentError(`${flag}: '${v}' is not one of ${allowedValues.join("|")}.`);
+                }
+            }
+        }
+        return value;
+    };
+}