taskflow-core 0.2.6 → 0.2.8

package/dist/savings.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Incremental / recompute savings summary — one-line numbers users can see.
+ *
+ * Pure formatters over RecomputeReport and run phase states. No I/O.
+ */
+import type { PhaseState, RunState } from "./store.ts";
+/** Minimal recompute-shaped input (avoids circular import with runtime). */
+export interface SavingsRecomputeInput {
+    readonly dryRun?: boolean;
+    readonly seeds?: readonly string[];
+    readonly rerun: readonly string[];
+    readonly reused: readonly string[];
+    readonly cutoff: readonly string[];
+}
+export interface PhaseCountSummary {
+    total: number;
+    completed: number;
+    failed: number;
+    skipped: number;
+    /** Phases with cacheHit set (cross-run or run-only). */
+    cached: number;
+    running: number;
+    other: number;
+}
+/** Count phase outcomes from a run state map (status / cache hits). */
+export declare function countPhaseOutcomes(phases: Record<string, PhaseState> | undefined): PhaseCountSummary;
+/**
+ * One-line savings for recompute reports.
+ * Example: `reused 5 · rerun 2 · cutoff 1 · saved ~71% phases`
+ */
+export declare function formatSavingsLine(r: SavingsRecomputeInput): string;
+/** One-line run cache summary when any phase was a cache hit. */
+export declare function formatRunCacheLine(state: Pick<RunState, "phases">): string | undefined;
+/** Prefix block for recompute human output. */
+export declare function formatRecomputeSavingsHeader(r: SavingsRecomputeInput): string;
+//# sourceMappingURL=savings.d.ts.map

package/dist/savings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"savings.d.ts","sourceRoot":"","sources":["../src/savings.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEvD,4EAA4E;AAC5E,MAAM,WAAW,qBAAqB;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACd;AAED,uEAAuE;AACvE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,SAAS,GAAG,iBAAiB,CAiCpG;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAclE;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,MAAM,GAAG,SAAS,CAKtF;AAED,+CAA+C;AAC/C,wBAAgB,4BAA4B,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAI7E"}

package/dist/savings.js

@@ -0,0 +1,76 @@
+/**
+ * Incremental / recompute savings summary — one-line numbers users can see.
+ *
+ * Pure formatters over RecomputeReport and run phase states. No I/O.
+ */
+/** Count phase outcomes from a run state map (status / cache hits). */
+export function countPhaseOutcomes(phases) {
+    const out = {
+        total: 0,
+        completed: 0,
+        failed: 0,
+        skipped: 0,
+        cached: 0,
+        running: 0,
+        other: 0,
+    };
+    if (!phases)
+        return out;
+    for (const ps of Object.values(phases)) {
+        out.total++;
+        if (ps.cacheHit)
+            out.cached++;
+        switch (ps.status) {
+            case "done":
+                out.completed++;
+                break;
+            case "failed":
+                out.failed++;
+                break;
+            case "skipped":
+                out.skipped++;
+                break;
+            case "running":
+            case "pending":
+                out.running++;
+                break;
+            default:
+                out.other++;
+        }
+    }
+    return out;
+}
+/**
+ * One-line savings for recompute reports.
+ * Example: `reused 5 · rerun 2 · cutoff 1 · saved ~71% phases`
+ */
+export function formatSavingsLine(r) {
+    const reused = r.reused.length;
+    const rerun = r.rerun.length;
+    const cutoff = r.cutoff.length;
+    const total = reused + rerun + cutoff;
+    const saved = reused + cutoff;
+    const pct = total > 0 ? Math.round((saved / total) * 100) : 0;
+    const parts = [
+        `reused ${reused}`,
+        `rerun ${rerun}`,
+        ...(r.dryRun ? [] : [`cutoff ${cutoff}`]),
+        total > 0 ? `saved ~${pct}% phases` : "saved —",
+    ];
+    return parts.join(" · ");
+}
+/** One-line run cache summary when any phase was a cache hit. */
+export function formatRunCacheLine(state) {
+    const c = countPhaseOutcomes(state.phases);
+    if (c.cached === 0)
+        return undefined;
+    const pct = c.total > 0 ? Math.round((c.cached / c.total) * 100) : 0;
+    return `cache hits ${c.cached}/${c.total} (~${pct}%) · completed ${c.completed} · failed ${c.failed} · skipped ${c.skipped}`;
+}
+/** Prefix block for recompute human output. */
+export function formatRecomputeSavingsHeader(r) {
+    const mode = r.dryRun ? "DRY RUN" : "applied";
+    const seeds = r.seeds?.length ? r.seeds.join(", ") : "—";
+    return `Savings (${mode}, seed: ${seeds}): ${formatSavingsLine(r)}`;
+}
+//# sourceMappingURL=savings.js.map

package/dist/savings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"savings.js","sourceRoot":"","sources":["../src/savings.ts"],"names":[],"mappings":"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"}

package/dist/schema.d.ts

@@ -122,6 +122,8 @@ declare const PhaseSchema: Type.TObject<{
      * Overrides the flow-level `idleTimeout`. Absent → flow-level or host default.
      */
     idleTimeout: Type.TOptional<Type.TNumber>;
+    timeoutMs: Type.TOptional<Type.TNumber>;
+    onExpire: Type.TOptional<Type.TUnsafe<"approve" | "fail" | "reject">>;
     until: Type.TOptional<Type.TString>;
     maxIterations: Type.TOptional<Type.TNumber>;
     convergence: Type.TOptional<Type.TBoolean>;
@@ -249,6 +251,33 @@ export declare const TaskflowSchema: Type.TObject<{
      * flow can never hang forever. A per-phase `idleTimeout` overrides this.
      */
     idleTimeout: Type.TOptional<Type.TNumber>;
+    /**
+     * Fire-and-forget terminal notifications. Payload is summary-only
+     * (`taskflow.hook.v1`) — never transcripts. Hook failure does not change run status.
+     */
+    hooks: Type.TOptional<Type.TObject<{
+        onComplete: Type.TOptional<Type.TArray<Type.TObject<{
+            type: Type.TUnsafe<"command" | "file" | "webhook">;
+            url: Type.TOptional<Type.TString>;
+            timeoutMs: Type.TOptional<Type.TNumber>;
+            path: Type.TOptional<Type.TString>;
+            run: Type.TOptional<Type.TArray<Type.TString>>;
+        }>>>;
+        onFail: Type.TOptional<Type.TArray<Type.TObject<{
+            type: Type.TUnsafe<"command" | "file" | "webhook">;
+            url: Type.TOptional<Type.TString>;
+            timeoutMs: Type.TOptional<Type.TNumber>;
+            path: Type.TOptional<Type.TString>;
+            run: Type.TOptional<Type.TArray<Type.TString>>;
+        }>>>;
+        onBlocked: Type.TOptional<Type.TArray<Type.TObject<{
+            type: Type.TUnsafe<"command" | "file" | "webhook">;
+            url: Type.TOptional<Type.TString>;
+            timeoutMs: Type.TOptional<Type.TNumber>;
+            path: Type.TOptional<Type.TString>;
+            run: Type.TOptional<Type.TArray<Type.TString>>;
+        }>>>;
+    }>>;
     phases: Type.TArray<Type.TObject<{
         id: Type.TString;
         type: Type.TOptional<Type.TUnsafe<"agent" | "approval" | "expand" | "flow" | "gate" | "loop" | "map" | "parallel" | "race" | "reduce" | "script" | "tournament">>;
@@ -302,6 +331,8 @@ export declare const TaskflowSchema: Type.TObject<{
          * Overrides the flow-level `idleTimeout`. Absent → flow-level or host default.
          */
         idleTimeout: Type.TOptional<Type.TNumber>;
+        timeoutMs: Type.TOptional<Type.TNumber>;
+        onExpire: Type.TOptional<Type.TUnsafe<"approve" | "fail" | "reject">>;
         until: Type.TOptional<Type.TString>;
         maxIterations: Type.TOptional<Type.TNumber>;
         convergence: Type.TOptional<Type.TBoolean>;

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAS5C;2DAC2D;AAC3D,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,kFAAkF;AAClF,eAAO,MAAM,WAAW,YACvB,OAAO,EACP,UAAU,EACV,KAAK,EACL,MAAM,EACN,QAAQ,EACR,UAAU,EACV,MAAM,EACN,MAAM,EACN,YAAY,EACZ,QAAQ;AACR,+CAA+C;AAC/C,MAAM;AACN,iFAAiF;AACjF,QAAQ,CACC,CAAC;AACX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD;kFACkF;AAClF,eAAO,MAAM,yBAAyB,uFASG,CAAC;AAE1C,yFAAyF;AACzF,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAC9C,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C;;mFAEmF;AACnF,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;;gFAGgF;AAChF,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,oCAAoC;AACpC,eAAO,MAAM,2BAA2B,IAAI,CAAC;AAC7C,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAC/C,QAAA,MAAM,gBAAgB,YAAI,MAAM,EAAE,WAAW,CAAU,CAAC;AACxD,gBAAgB;AAChB,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAI/D,uFAAuF;AACvF,eAAO,MAAM,eAAe,YAAI,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAU,CAAC;AACrH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7D,QAAA,MAAM,YAAY,YAAI,UAAU,EAAE,WAAW,EAAE,KAAK,CAAU,CAAC;AAC/D,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAKvD,QAAA,MAAM,kBAAkB;;;;EAYvB,CAAC;AAEF,+DAA+D;AAC/D,QAAA,MAAM,WAAW;;;;EAShB,CAAC;AAEF;;;;GAIG;AACH,QAAA,MAAM,WAAW;;;;EAuBhB,CAAC;AAEF,4FAA4F;AAC5F,QAAA,MAAM,YAAY;;;EAQjB,CAAC;AAEF,QAAA,MAAM,WAAW;;;;;;;;;;;;IAmBf;;;;OAIG;;;IAOH;;;;;;;;;;OAUG;;IAOH;8EAC0E;;;IAO1E,sGAAsG;;IAQtG,wIAAwI;;IAOxI,kFAAkF;;;;;;IA2BlF;;;;;;OAMG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6IJ,CAAC;AAiEF,QAAA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAOjB,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA8BzB;;;;;;OAMG;;;;;;;;;;;;;;QA/UH;;;;WAIG;;;QAOH;;;;;;;;;;WAUG;;QAOH;kFAC0E;;;QAO1E,sGAAsG;;QAQtG,wIAAwI;;QAOxI,kFAAkF;;;;;;QA2BlF;;;;;;WAMG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqQJ,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAC7D,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAC/C,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AACrD,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AACnD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AACrD,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AACjD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAkBrD,MAAM,WAAW,aAAa;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;kFAE8E;IAC9E,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CASjD;AAuBD;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAgF9C;AAMD,gBAAgB;AAChB,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;qDAEiD;IACjD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASrD;AAED,MAAM,WAAW,iBAAiB;IACjC,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,yFAAyF;IACzF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;mEAG+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAqCD;;6DAE6D;AAC7D,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,EAAE,CAgB3G;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,GAAE,iBAAsB,GAAG,gBAAgB,CAktB7F;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAmC7E;AAgDD;;0EAE0E;AAC1E,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,GAAG,CAAC,EAAE,CAE1C;AAED,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,CAGrD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBjF;AAED,mFAAmF;AACnF,wBAAgB,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,EAAE,EAAE,CAkCrD;AAED,uDAAuD;AACvD,wBAAgB,UAAU,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQtG"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/schema.js

@@ -184,6 +184,14 @@ const PhaseSchema = Type.Object({
     idleTimeout: Type.Optional(Type.Number({
         description: "[agent-running] Idle watchdog in ms (>= 1000, or 0 to disable). 0 requires a finite wall 'timeout' >= 1000. Overrides the flow-level idleTimeout.",
     })),
+    // approval — HITL wait bound (distinct from agent wall `timeout`)
+    timeoutMs: Type.Optional(Type.Number({
+        description: "[approval] Max wait for a human decision in ms (>= 1000). On expiry, apply onExpire. Omit for infinite wait (current default).",
+    })),
+    onExpire: Type.Optional(StringEnum(["reject", "fail", "approve"], {
+        description: "[approval] Decision when timeoutMs elapses. Default 'reject'. 'approve' auto-continues without review (footgun — use deliberately).",
+        default: "reject",
+    })),
     // loop-until-done
     until: Type.Optional(Type.String({
         description: "[loop] Stop condition evaluated after each iteration. The iteration's output is exposed as {steps.<thisId>.output}/.json. Supports the same operators as `when`. The loop stops when this is truthy, on convergence, or at maxIterations. A parse error stops the loop (fail-safe).",
@@ -308,6 +316,16 @@ const ArgSpecSchema = Type.Union([
     BooleanArgSpecSchema,
     EnumArgSpecSchema,
 ]);
+/** Flow-level hook action (webhook | file | command). Validated further in validateTaskflow. */
+const HookActionSchema = Type.Object({
+    type: StringEnum(["webhook", "file", "command"]),
+    url: Type.Optional(Type.String({ description: "[webhook] Destination URL (https, or http://127.0.0.1|localhost)" })),
+    timeoutMs: Type.Optional(Type.Number({ description: "[webhook] Request timeout ms (default 5000)" })),
+    path: Type.Optional(Type.String({ description: "[file] Project-relative path for JSON payload" })),
+    run: Type.Optional(Type.Array(Type.String(), {
+        description: "[command] argv only (no shell string). Receives TASKFLOW_HOOK_* env vars.",
+    })),
+}, { additionalProperties: false });
 export const TaskflowSchema = Type.Object({
     name: Type.String({ minLength: 1, description: "Workflow name (becomes /tf:<name> command when saved)" }),
     description: Type.Optional(Type.String()),
@@ -336,6 +354,15 @@ export const TaskflowSchema = Type.Object({
     idleTimeout: Type.Optional(Type.Number({
         description: "Flow-level idle watchdog in ms (>= 1000, or 0 to disable). Per-phase idleTimeout overrides. 0 requires every agent-running phase to declare a finite wall 'timeout' >= 1000.",
     })),
+    /**
+     * Fire-and-forget terminal notifications. Payload is summary-only
+     * (`taskflow.hook.v1`) — never transcripts. Hook failure does not change run status.
+     */
+    hooks: Type.Optional(Type.Object({
+        onComplete: Type.Optional(Type.Array(HookActionSchema, { maxItems: 5 })),
+        onFail: Type.Optional(Type.Array(HookActionSchema, { maxItems: 5 })),
+        onBlocked: Type.Optional(Type.Array(HookActionSchema, { maxItems: 5 })),
+    }, { additionalProperties: false, description: "Terminal-run hooks (complete / fail / blocked)" })),
     phases: Type.Array(PhaseSchema, { minItems: 1, description: "Ordered phase definitions (DAG via dependsOn)" }),
 }, { additionalProperties: false });
 /** True when `def` is a shorthand spec (no `phases`, but a task/tasks/chain field). */
@@ -520,6 +547,76 @@ function typedArgValueErrors(name, spec, value, source) {
     }
     return [];
 }
+/** Inline hook validation (kept in schema to avoid schema↔hooks import cycles). */
+function validateFlowHooksInline(hooks) {
+    if (hooks === undefined)
+        return [];
+    if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+        return ["hooks must be an object"];
+    const h = hooks;
+    const errors = [];
+    const max = 5;
+    for (const event of ["onComplete", "onFail", "onBlocked"]) {
+        if (h[event] === undefined)
+            continue;
+        if (!Array.isArray(h[event])) {
+            errors.push(`hooks.${event} must be an array`);
+            continue;
+        }
+        if (h[event].length > max)
+            errors.push(`hooks.${event} allows at most ${max} actions`);
+        h[event].forEach((action, index) => {
+            if (!action || typeof action !== "object" || Array.isArray(action)) {
+                errors.push(`hooks.${event}[${index}] must be an object`);
+                return;
+            }
+            const a = action;
+            if (a.type === "webhook") {
+                if (typeof a.url !== "string" || !a.url.trim()) {
+                    errors.push(`hooks.${event}[${index}].url is required`);
+                    return;
+                }
+                try {
+                    const u = new URL(a.url.trim());
+                    const host = u.hostname.toLowerCase();
+                    const okHttpLocal = u.protocol === "http:" &&
+                        (host === "127.0.0.1" || host === "localhost" || host === "[::1]" || host === "::1");
+                    if (u.protocol !== "https:" && !okHttpLocal) {
+                        errors.push(`hooks.${event}[${index}]: URL must be https or http://127.0.0.1|localhost`);
+                    }
+                }
+                catch {
+                    errors.push(`hooks.${event}[${index}]: invalid URL`);
+                }
+                if (a.timeoutMs !== undefined &&
+                    (typeof a.timeoutMs !== "number" || a.timeoutMs < 100 || a.timeoutMs > 60_000)) {
+                    errors.push(`hooks.${event}[${index}].timeoutMs must be 100–60000`);
+                }
+            }
+            else if (a.type === "file") {
+                if (typeof a.path !== "string" || !a.path.trim()) {
+                    errors.push(`hooks.${event}[${index}].path is required`);
+                }
+                else if (path.isAbsolute(a.path) || a.path.split(/[/\\]/).includes("..")) {
+                    errors.push(`hooks.${event}[${index}].path must be project-relative without '..'`);
+                }
+            }
+            else if (a.type === "command") {
+                if (!Array.isArray(a.run) || a.run.length === 0 || !a.run.every((x) => typeof x === "string")) {
+                    errors.push(`hooks.${event}[${index}].run must be a non-empty string array (no shell string)`);
+                }
+            }
+            else {
+                errors.push(`hooks.${event}[${index}].type must be webhook|file|command`);
+            }
+        });
+    }
+    for (const k of Object.keys(h)) {
+        if (!["onComplete", "onFail", "onBlocked"].includes(k))
+            errors.push(`hooks: unknown key '${k}'`);
+    }
+    return errors;
+}
 /** Validate resolved invocation values independently of full flow structure.
  * Runtime calls this at the Core boundary so direct, resume, and detached
  * execution cannot bypass adapter-level typed-arg checks. */
@@ -605,6 +702,10 @@ export function validateTaskflow(def, opts = {}) {
                 warnings.push(`Invocation argument '${name}' is undeclared`);
         }
     }
+    // Flow-level hooks (summary-only terminal notifications).
+    if (flow.hooks !== undefined) {
+        errors.push(...validateFlowHooksInline(flow.hooks));
+    }
     // Flow-level idleTimeout: positive must be >= 1000; 0 is allowed (disables the
     // watchdog) but every agent-running phase must then declare a finite wall
     // `timeout` so the run can never hang forever (critical invariant #5).
@@ -869,6 +970,28 @@ export function validateTaskflow(def, opts = {}) {
                 errors.push(`Phase '${p.id}' (${type}): 'reflexion' is only valid for loop phases`);
             }
         }
+        // Approval wait bound (timeoutMs / onExpire) — approval-only.
+        if (p.timeoutMs !== undefined) {
+            const t = p.timeoutMs;
+            if (type !== "approval") {
+                errors.push(`Phase '${p.id}' (${type}): 'timeoutMs' is only valid for approval phases (use 'timeout' for agent wall caps)`);
+            }
+            else if (typeof t !== "number" || !Number.isFinite(t) || t < 1000) {
+                errors.push(`Phase '${p.id}' (approval): 'timeoutMs' must be a number >= 1000 ms`);
+            }
+        }
+        if (p.onExpire !== undefined) {
+            const o = p.onExpire;
+            if (type !== "approval") {
+                errors.push(`Phase '${p.id}' (${type}): 'onExpire' is only valid for approval phases`);
+            }
+            else if (o !== "reject" && o !== "fail" && o !== "approve") {
+                errors.push(`Phase '${p.id}' (approval): 'onExpire' must be reject|fail|approve`);
+            }
+            else if (p.timeoutMs === undefined) {
+                warnings.push(`Phase '${p.id}' (approval): 'onExpire' without 'timeoutMs' has no effect`);
+            }
+        }
         // Other loop-only fields on non-loop phases are silently ignored by the
         // runtime — warn so the author learns the field does nothing (a warning,
         // not an error, to avoid breaking pre-existing flows that carry them).