@deftai/directive-core 0.94.0 → 0.96.0

package/dist/init-deposit/init-deposit.js

@@ -13,8 +13,10 @@ import { copyTree } from "../deposit/copy-tree.js";
 import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { readCorePackageVersion } from "../engine-version.js";
+import { stampLiveGeneration } from "../freshness/generation.js";
 import { renderProjectDefinition } from "../render/project-render.js";
 import { depositOpenClawL2ProductCommands } from "../slash/openclaw-deposit.js";
+import { agentHookReadinessJson, evaluateAgentHookReadiness, evaluateAgentHookReadinessSafely, } from "../verify-env/agent-hook-readiness.js";
 import { removeStaleMigratedFrameworkNarrative } from "../xbrief-migrate/migrate-project.js";
 import { writeAgentHookDeposit } from "./agent-hooks.js";
 import { ensureInitGitignoreLines, reconstituteDepositFromContent } from "./gitignore.js";
@@ -81,9 +83,12 @@ function readContentVersion(contentRoot, readVersion = readCorePackageVersion) {
     }
     return readVersion();
 }
-export function buildInstallSummaryJson(result, options) {
+export function buildInstallSummaryJson(input) {
+    const { result, options, readiness } = input;
     return {
-        success: true,
+        success: readiness ? readiness.code === 0 : true,
+        deposit_completed: true,
+        ...(readiness ? { agent_hook_readiness: agentHookReadinessJson(readiness) } : {}),
         action: "install",
         version: readCorePackageVersion(),
         project_dir: result.projectDir,
@@ -210,6 +215,14 @@ export async function runInitDeposit(args, io, seams = {}) {
         includeTaskfile: taskfileWired,
     });
     printCommitGuidance(io, stagePaths, staged);
+    // #3117: stamp live generation only after required init projections succeed.
+    // Stamping earlier would advance authority for a failed/partial init (Greptile).
+    stampLiveGeneration(projectDir, {
+        contentVersion: version,
+        stampedBy: "directive-init",
+        increment: true,
+        nowIso: nowIso(),
+    });
     return {
         projectDir,
         deftDir,
@@ -234,14 +247,21 @@ export async function runInitDepositCli(options) {
     };
     try {
         const result = await runInitDeposit(options, io, options.seams);
+        const readiness = evaluateAgentHookReadinessSafely(result.projectDir, options.seams?.evaluateAgentHookReadiness ?? evaluateAgentHookReadiness);
         if (options.jsonOut) {
-            options.writeOut(`${JSON.stringify(buildInstallSummaryJson(result, options), null, 2)}\n`);
+            options.writeOut(`${JSON.stringify(buildInstallSummaryJson({ result, options, readiness }), null, 2)}\n`);
             printNextSteps(result, { printf: options.writeErr });
         }
         else {
             printNextSteps(result, io);
         }
-        return 0;
+        const readinessOut = options.jsonOut
+            ? options.writeErr
+            : readiness.stream === "stderr"
+                ? options.writeErr
+                : options.writeOut;
+        readinessOut(`\n${readiness.message}\n`);
+        return readiness.code;
     }
     catch (cause) {
         if (cause instanceof LegacyLayoutRefusedError) {

package/dist/init-deposit/refresh.d.ts

@@ -9,6 +9,7 @@
  */
 import type { ResolutionFacts, ResolutionPlan } from "@deftai/directive-types";
 import { type ClassifySeams, type EngineInstallRunner, type EngineResolution, type LadderFacts, type ReprojectRunner } from "../resolution/index.js";
+import { type AgentHookReadinessResult } from "../verify-env/agent-hook-readiness.js";
 import { type GitLsFiles } from "./gitignore.js";
 import { type InitDepositArgs } from "./init-deposit.js";
 import { type LegacyLayoutDetection } from "./legacy-detect.js";
@@ -49,6 +50,8 @@ export interface RefreshDepositSeams {
     gitHooks?: GitHooksSeams;
     /** #2822: optional seam for trusted-org policy force-on migration. */
     runOrgForceOn?: (projectRoot: string) => void;
+    /** Post-deposit functional readiness gate (#3100). */
+    evaluateAgentHookReadiness?: (projectRoot: string) => AgentHookReadinessResult;
 }
 /**
  * The four states `directive update` classifies an EXISTING install into BEFORE
@@ -123,7 +126,12 @@ export interface RefreshSideEffects {
 export declare function frameworkRefreshSideEffects(projectDir: string, options?: FrameworkRefreshSideEffectsOptions): RefreshSideEffects;
 export declare function printRefreshSideEffects(io: InitDepositIo, effects: RefreshSideEffects): void;
 export declare function buildVersionSkewNotice(engineVersion: string, contentVersion: string, previousDepositVersion: string | null): string | null;
-export declare function buildUpdateSummaryJson(result: RefreshDepositResult, options: RefreshDepositArgs, updateState?: UpdateState): Record<string, unknown>;
+export declare function buildUpdateSummaryJson(input: {
+    result: RefreshDepositResult;
+    options: RefreshDepositArgs;
+    updateState: UpdateState | undefined;
+    readiness: AgentHookReadinessResult | undefined;
+}): Record<string, unknown>;
 export declare function printUpdateComplete(result: RefreshDepositResult, io: InitDepositIo, updateState?: UpdateState): void;
 export declare function runRefreshDeposit(args: RefreshDepositArgs, io: InitDepositIo, seams?: RefreshDepositSeams): Promise<RefreshDepositResult>;
 export interface RunRefreshDepositCliOptions extends RefreshDepositArgs {

package/dist/init-deposit/refresh.js

@@ -17,12 +17,14 @@ import { prunePythonArtifactsFromDeposit } from "../deposit/python-free.js";
 import { resolveInstalledContentRoot } from "../deposit/resolve-content.js";
 import { manifestTagToVersion, parseInstallManifest } from "../doctor/manifest.js";
 import { readCorePackageVersion } from "../engine-version.js";
+import { readLiveGeneration, stampLiveGeneration } from "../freshness/generation.js";
 import { resolveLifecycleRoot } from "../layout/resolve.js";
 import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_FLAG_NAME, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_POLICY, } from "../policy/no-deft-directive.js";
 import { runOrgForceOnMigration } from "../policy/org-force-on-migration.js";
 import { checkLocalEngineIntegrity, classify, ENGINE_PACKAGE, plan, renderGlobalInstall, resolveEngine, } from "../resolution/index.js";
 import { depositOpenClawL2ProductCommands } from "../slash/openclaw-deposit.js";
 import { gitPorcelain } from "../story-ready/git.js";
+import { agentHookReadinessJson, evaluateAgentHookReadiness, evaluateAgentHookReadinessSafely, } from "../verify-env/agent-hook-readiness.js";
 import { removeStaleMigratedFrameworkNarrative } from "../xbrief-migrate/migrate-project.js";
 import { writeAgentHookDeposit } from "./agent-hooks.js";
 import { ensureInitGitignoreLines, isDepositTrackedInGit } from "./gitignore.js";
@@ -332,9 +334,12 @@ export function buildVersionSkewNotice(engineVersion, contentVersion, previousDe
     }
     return null;
 }
-export function buildUpdateSummaryJson(result, options, updateState) {
+export function buildUpdateSummaryJson(input) {
+    const { result, options, updateState, readiness } = input;
     return {
-        success: true,
+        success: readiness ? readiness.code === 0 : true,
+        deposit_completed: true,
+        ...(readiness ? { agent_hook_readiness: agentHookReadinessJson(readiness) } : {}),
         action: "upgrade",
         ...(updateState ? { update_state: updateState } : {}),
         version: result.engineVersion,
@@ -416,6 +421,27 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         // VERSION already matches (e.g. pre-#2804 additive deposits). Does not re-stamp.
         await reconcileDepositToContentPackage(deftDir, contentRoot, io);
         migrateLegacyInstallManifest(projectDir, join(deftDir, "VERSION"));
+        // #3117: ensure a readable live generation token exists without advancing
+        // when the payload did not swap (already-current). stampLiveGeneration is a
+        // no-op write when the token already matches (keeps git clean under #2118).
+        // If generation is missing or behind VERSION (e.g. prior stamp failed after
+        // VERSION rewrite), fail closed — do not report success with a stale token.
+        const priorGen = readLiveGeneration(projectDir);
+        const generationMatches = priorGen !== null &&
+            normalizeVersion(priorGen.contentVersion) === normalizeVersion(contentVersion);
+        try {
+            stampLiveGeneration(projectDir, {
+                contentVersion,
+                stampedBy: "directive-update",
+                increment: false,
+            });
+        }
+        catch (err) {
+            if (!generationMatches) {
+                throw err;
+            }
+            // Token already matches content; ensure write failure is non-fatal noise.
+        }
     }
     else {
         // Full-tree replace (or injected seam). Additive copy is no longer the default.
@@ -426,12 +452,13 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         // additive seams. Throws => no VERSION rewrite (refuse stamp until clean).
         await reconcileDepositToContentPackage(deftDir, contentRoot, io);
         const nowIso = seams.nowIso ?? (() => new Date().toISOString().replace(/\.\d{3}Z$/, "Z"));
+        const stampedAt = nowIso();
         const manifestFields = {
             ref: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
             sha: "content-package",
             tag: contentVersion.startsWith("v") ? contentVersion : `v${contentVersion}`,
             installRoot: CANONICAL_INSTALL_ROOT,
-            fetchedAt: nowIso(),
+            fetchedAt: stampedAt,
             fetchedBy: "directive-update",
             ...(previousManagedBy ? { managedBy: previousManagedBy } : {}),
         };
@@ -440,6 +467,15 @@ export async function runRefreshDeposit(args, io, seams = {}) {
         // .deft/core/VERSION has been rewritten (folded in from install-upgrade so no
         // manifest behavior is lost by the redirect). Best-effort; never fatal.
         migrateLegacyInstallManifest(projectDir, writtenManifestPath);
+        // #3117: monotonic live generation MUST advance after a successful payload
+        // swap. Suppressing stamp failure would leave a prior bound/live match
+        // reporting `current` while the on-disk payload already changed (Greptile P1).
+        stampLiveGeneration(projectDir, {
+            contentVersion,
+            stampedBy: "directive-update",
+            increment: true,
+            nowIso: stampedAt,
+        });
     }
     // #2595: payload freshness and consumer derivative freshness are independent.
     // Always repair these cheap projections, including on the #2118 no-op path.
@@ -653,17 +689,24 @@ export async function runRefreshDepositCli(options) {
     }
     try {
         const result = await runRefreshDeposit(options, io, options.seams);
+        const readiness = evaluateAgentHookReadinessSafely(result.projectDir, options.seams?.evaluateAgentHookReadiness ?? evaluateAgentHookReadiness);
         const state = result.alreadyCurrent
             ? "current"
             : classification?.state;
         if (options.jsonOut) {
-            options.writeOut(`${JSON.stringify(buildUpdateSummaryJson(result, options, state), null, 2)}\n`);
+            options.writeOut(`${JSON.stringify(buildUpdateSummaryJson({ result, options, updateState: state, readiness }), null, 2)}\n`);
             printUpdateComplete(result, { printf: options.writeErr }, state);
         }
         else {
             printUpdateComplete(result, io, state);
         }
-        return 0;
+        const readinessOut = options.jsonOut
+            ? options.writeErr
+            : readiness.stream === "stderr"
+                ? options.writeErr
+                : options.writeOut;
+        readinessOut(`\n${readiness.message}\n`);
+        return readiness.code;
     }
     catch (cause) {
         if (cause instanceof LegacyLayoutRefusedError) {

package/dist/init-deposit/scaffold.js

@@ -507,11 +507,12 @@ function coreGuardWorkflowContent() {
     const baseSha = githubActionsExpr("github.event.pull_request.base.sha");
     const headSha = githubActionsExpr("github.event.pull_request.head.sha");
     return ("name: deft-core-guard\n\n" +
-        "# Deft framework guard (#1430): a single PR should not mix changes to the\n" +
-        "# vendored framework payload (.deft/core/**) with changes to your own project\n" +
-        "# files. Framework updates come from `deft-install` / upgrade and should\n" +
-        "# land in their own PR so reviewers (and bot reviewers) can treat them as\n" +
-        "# packaged, machine-managed assets. Delete this file if you do not want the guard.\n" +
+        "# Deft framework guard (#1430 / #3127): a single PR should not mix changes to the\n" +
+        "# vendored framework payload (.deft/core/**) with true application/product files.\n" +
+        "# One upgrade PR MAY include deposit + installer-managed paths + package.json pin/lock\n" +
+        "# + .deft/GENERATION.json. Framework updates come from `deft update` / install and should\n" +
+        "# land without product feature work so reviewers treat the payload as machine-managed.\n" +
+        "# Delete this file if you do not want the guard.\n" +
         "on:\n" +
         "  pull_request:\n\n" +
         "permissions:\n" +

package/dist/parent-turn-shape/evaluate.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Parent turn-shape hard-stop for text-repetition hang (FC14 / #3131).
+ *
+ * Soft skill prose (#2943) alone is insufficient: parents still burn the full
+ * output budget on identical progress sentences with zero tool_use after leaf
+ * announce. This pure library is the Directive-side machine-checkable gate.
+ *
+ * Hosts (OpenClaw, swarm parents, review monitors) SHOULD evaluate the parent
+ * turn stream mid-generation and hard-stop when `ok` is false.
+ *
+ * Illegal shape (MUST NOT):
+ *   N > maxIdenticalWithoutTool (default 2) near-identical assistant sentences
+ *   (or streaming text chunks) in one turn with no tool_use and no yield.
+ *
+ * Legal post-announce shapes:
+ *   1. Tool batch (ground-truth) then one consolidate
+ *   2. sessions_yield / wait without filler
+ *   3. One short user answer that is NOT a repeated progress line
+ */
+/** Failure class codes for operator / host recovery surfaces. */
+export type ParentTurnFailClass = "none" | "FC14" | "text-repetition-hang" | "progress-only-no-tool";
+/** Ordered events observed within a single parent turn. */
+export type ParentTurnEvent = {
+    kind: "assistant_text";
+    text: string;
+} | {
+    kind: "tool_use";
+    name?: string;
+} | {
+    kind: "yield";
+};
+export interface ParentTurnShapeInput {
+    /** Ordered events from one parent turn (streaming deltas may be separate). */
+    readonly events: readonly ParentTurnEvent[];
+    /**
+     * When true, multi-sentence progress-only text with zero tools/yield is also
+     * illegal even without exact N>2 identity (post-`subagent_announce` policy).
+     */
+    readonly afterSubagentAnnounce?: boolean;
+    /**
+     * Max near-identical consecutive (or within-turn) text units allowed without
+     * tool_use / yield. Issue contract: MUST NOT emit N>2 → default max = 2.
+     */
+    readonly maxIdenticalWithoutTool?: number;
+}
+export interface ParentTurnShapeResult {
+    readonly ok: boolean;
+    /** Primary fail class (`FC14` aliases `text-repetition-hang`). */
+    readonly failClass: ParentTurnFailClass;
+    readonly reasons: readonly string[];
+    /** Highest count of near-identical text units observed without tool/yield. */
+    readonly maxIdenticalCount: number;
+    readonly hasToolUse: boolean;
+    readonly hasYield: boolean;
+}
+/** Canonical fail class for the hang (#3131 / soft FC14 recurrence of #2943). */
+export declare const PARENT_TURN_FAIL_FC14: "FC14";
+/** Default max identical text units without tool/yield (N>2 is illegal). */
+export declare const DEFAULT_MAX_IDENTICAL_WITHOUT_TOOL = 2;
+/**
+ * Normalize assistant text for identity comparison.
+ * Collapses whitespace, lowercases, strips common trailing punctuation.
+ */
+export declare function normalizeTurnText(text: string): string;
+/** Split a blob into sentence-like units (periods, newlines, ellipsis). */
+export declare function splitTextUnits(text: string): string[];
+/**
+ * True when two normalized strings are near-identical (exact, containment with
+ * high length ratio, or high word Jaccard). Short units never match.
+ */
+export declare function isNearIdentical(a: string, b: string): boolean;
+/**
+ * Detect when a single blob itself embeds the same sentence many times
+ * (model streams one giant assistant message of repeated lines).
+ */
+export declare function countRepeatedUnitsInBlob(text: string): number;
+/**
+ * Evaluate whether a parent turn shape is legal under the FC14 hard-stop.
+ * Pure / side-effect free — safe for mid-stream host gates and unit tests.
+ */
+export declare function evaluateParentTurnShape(input: ParentTurnShapeInput): ParentTurnShapeResult;
+/** Convenience: true when the turn is an illegal text-repetition hang. */
+export declare function isTextRepetitionHang(input: ParentTurnShapeInput): boolean;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/parent-turn-shape/evaluate.js

@@ -0,0 +1,353 @@
+/**
+ * Parent turn-shape hard-stop for text-repetition hang (FC14 / #3131).
+ *
+ * Soft skill prose (#2943) alone is insufficient: parents still burn the full
+ * output budget on identical progress sentences with zero tool_use after leaf
+ * announce. This pure library is the Directive-side machine-checkable gate.
+ *
+ * Hosts (OpenClaw, swarm parents, review monitors) SHOULD evaluate the parent
+ * turn stream mid-generation and hard-stop when `ok` is false.
+ *
+ * Illegal shape (MUST NOT):
+ *   N > maxIdenticalWithoutTool (default 2) near-identical assistant sentences
+ *   (or streaming text chunks) in one turn with no tool_use and no yield.
+ *
+ * Legal post-announce shapes:
+ *   1. Tool batch (ground-truth) then one consolidate
+ *   2. sessions_yield / wait without filler
+ *   3. One short user answer that is NOT a repeated progress line
+ */
+/** Canonical fail class for the hang (#3131 / soft FC14 recurrence of #2943). */
+export const PARENT_TURN_FAIL_FC14 = "FC14";
+/** Default max identical text units without tool/yield (N>2 is illegal). */
+export const DEFAULT_MAX_IDENTICAL_WITHOUT_TOOL = 2;
+/** Minimum length (chars) for a text unit to count toward repetition. */
+const MIN_UNIT_LEN = 12;
+/** Word Jaccard threshold for near-identical (after normalize). */
+const JACCARD_NEAR = 0.9;
+/** Progress-ish tokens that mark filler narration after announce. */
+const PROGRESS_HINT_RE = /\b(checking|checking\s+worktrees|open\s+prs?|next|unfinished|implementing|looking\s+at|will\s+(check|inspect|verify|spawn)|status\s+next|monitor(?:ing)?)\b/i;
+/**
+ * Normalize assistant text for identity comparison.
+ * Collapses whitespace, lowercases, strips common trailing punctuation.
+ */
+export function normalizeTurnText(text) {
+    return text
+        .normalize("NFKC")
+        .toLowerCase()
+        .replace(/\s+/g, " ")
+        .replace(/^[\s"'`]+|[\s"'`]+$/g, "")
+        .replace(/[.!?…,:;]+$/g, "")
+        .trim();
+}
+/** Split a blob into sentence-like units (periods, newlines, ellipsis). */
+export function splitTextUnits(text) {
+    const raw = text.replace(/\r\n/g, "\n");
+    // Include single newlines so block-formatted repeated progress lines still
+    // unitize (FC14 hang class often streams one line per newline, no period).
+    // Optional closing quotes after terminal punctuation, with or without space:
+    // `"Hello." "Hello."` and `"Hello.""Hello."`.
+    const parts = raw
+        .split(/(?:\n+|(?<=[.!?…])["']+\s*|(?<=[.!?…])\s+|(?<=\.\.\.)\s+)/)
+        .map((p) => p.trim())
+        .filter((p) => p.length > 0);
+    if (parts.length === 0 && raw.trim().length > 0) {
+        return [raw.trim()];
+    }
+    return parts;
+}
+function wordSet(normalized) {
+    const words = normalized.split(/[^a-z0-9_]+/).filter((w) => w.length > 0);
+    return new Set(words);
+}
+/**
+ * True when two normalized strings are near-identical (exact, containment with
+ * high length ratio, or high word Jaccard). Short units never match.
+ */
+export function isNearIdentical(a, b) {
+    const na = normalizeTurnText(a);
+    const nb = normalizeTurnText(b);
+    if (na.length < MIN_UNIT_LEN || nb.length < MIN_UNIT_LEN)
+        return false;
+    if (na === nb)
+        return true;
+    const shorter = na.length <= nb.length ? na : nb;
+    const longer = na.length <= nb.length ? nb : na;
+    if (longer.includes(shorter) && shorter.length / longer.length >= 0.85) {
+        return true;
+    }
+    const sa = wordSet(na);
+    const sb = wordSet(nb);
+    if (sa.size === 0 || sb.size === 0)
+        return false;
+    let inter = 0;
+    for (const w of sa) {
+        if (sb.has(w))
+            inter += 1;
+    }
+    const union = sa.size + sb.size - inter;
+    if (union === 0)
+        return false;
+    return inter / union >= JACCARD_NEAR;
+}
+/**
+ * Collect assistant text units from turn events.
+ *
+ * Streaming hosts often emit word/chunk deltas as separate `assistant_text`
+ * events. Coalesce consecutive text events into one blob so fragmented
+ * progress sentences reconstruct before split/identity checks (P1 / #3131).
+ * Non-text events (tool_use / yield) flush the coalesce buffer.
+ */
+function collectAssistantUnits(events) {
+    const units = [];
+    const pushUnitsFrom = (text) => {
+        for (const u of splitTextUnits(text)) {
+            const t = u.trim();
+            if (t.length >= MIN_UNIT_LEN)
+                units.push(t);
+        }
+    };
+    let run = "";
+    for (const ev of events) {
+        if (ev.kind === "assistant_text") {
+            const text = typeof ev.text === "string" ? ev.text : "";
+            if (!text)
+                continue;
+            // Sentence-boundary deltas often omit whitespace after `.!?` before the
+            // next capital letter. Insert space only at sentence ends — never between
+            // arbitrary alnum chunks (subword streams like workt+rees must not gain
+            // a false space).
+            if (run.length > 0 && /[.!?…]["']?\s*$/.test(run) && !/^\s/.test(text) && !/\s$/.test(run)) {
+                run += " ";
+            }
+            run += text;
+            continue;
+        }
+        // Non-text event ends the coalesce run (tool/yield boundaries).
+        if (run.trim().length > 0)
+            pushUnitsFrom(run);
+        run = "";
+    }
+    if (run.trim().length > 0)
+        pushUnitsFrom(run);
+    return units;
+}
+/**
+ * Max connected-component size under near-identity edges (union-find).
+ * Captures non-transitive chains of incrementally varied progress lines
+ * (A≈B≈C even when A≉C) so FC14 cannot be bypassed by wording drift.
+ */
+function maxNearIdentityComponent(units) {
+    const n = units.length;
+    if (n === 0)
+        return 0;
+    // Precompute normalize + word sets once (avoid O(n²) re-normalize/Set alloc).
+    const norms = units.map((u) => normalizeTurnText(u));
+    const sets = norms.map((n) => wordSet(n));
+    const near = (i, j) => {
+        const na = norms[i] ?? "";
+        const nb = norms[j] ?? "";
+        if (na.length < MIN_UNIT_LEN || nb.length < MIN_UNIT_LEN)
+            return false;
+        if (na === nb)
+            return true;
+        const shorter = na.length <= nb.length ? na : nb;
+        const longer = na.length <= nb.length ? nb : na;
+        if (longer.includes(shorter) && shorter.length / longer.length >= 0.85)
+            return true;
+        const sa = sets[i] ?? new Set();
+        const sb = sets[j] ?? new Set();
+        if (sa.size === 0 || sb.size === 0)
+            return false;
+        let inter = 0;
+        for (const w of sa) {
+            if (sb.has(w))
+                inter += 1;
+        }
+        const union = sa.size + sb.size - inter;
+        return union > 0 && inter / union >= JACCARD_NEAR;
+    };
+    const parent = Array.from({ length: n }, (_, i) => i);
+    const find = (i) => {
+        let x = i;
+        while (parent[x] !== x) {
+            parent[x] = parent[parent[x] ?? x] ?? x;
+            x = parent[x] ?? x;
+        }
+        return x;
+    };
+    const unite = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra !== rb)
+            parent[ra] = rb;
+    };
+    for (let i = 0; i < n; i++) {
+        for (let j = i + 1; j < n; j++) {
+            if (near(i, j))
+                unite(i, j);
+        }
+    }
+    const sizes = new Map();
+    let max = 1;
+    for (let i = 0; i < n; i++) {
+        const r = find(i);
+        const next = (sizes.get(r) ?? 0) + 1;
+        sizes.set(r, next);
+        if (next > max)
+            max = next;
+    }
+    return max;
+}
+/**
+ * Max count of any single near-identical cluster among units.
+ * Consecutive runs + exact-normalized frequency (O(n)); for small unit counts
+ * also union-find near-identity components so non-consecutive / chain variants
+ * cannot bypass FC14 (P1 / #3131).
+ */
+function maxIdenticalCluster(units) {
+    if (units.length === 0)
+        return 0;
+    const norms = units.map((u) => normalizeTurnText(u));
+    let maxRun = 1;
+    let run = 1;
+    for (let i = 1; i < units.length; i++) {
+        if (isNearIdentical(units[i] ?? "", units[i - 1] ?? "")) {
+            run += 1;
+            if (run > maxRun)
+                maxRun = run;
+        }
+        else {
+            run = 1;
+        }
+    }
+    // Frequency by exact normalized form (O(n)).
+    const freq = new Map();
+    let maxFreq = 1;
+    for (const n of norms) {
+        if (n.length < MIN_UNIT_LEN)
+            continue;
+        const next = (freq.get(n) ?? 0) + 1;
+        freq.set(n, next);
+        if (next > maxFreq)
+            maxFreq = next;
+    }
+    // Always cluster near-identity components. Input size is bounded by the
+    // zero-tool character hard-stop above, so O(n²) stays finite.
+    const maxComponent = maxNearIdentityComponent(units);
+    return Math.max(maxRun, maxFreq, maxComponent);
+}
+/**
+ * Detect when a single blob itself embeds the same sentence many times
+ * (model streams one giant assistant message of repeated lines).
+ */
+export function countRepeatedUnitsInBlob(text) {
+    const units = splitTextUnits(text).filter((u) => u.trim().length >= MIN_UNIT_LEN);
+    return maxIdenticalCluster(units);
+}
+function looksLikeProgressOnly(units) {
+    if (units.length < 2)
+        return false;
+    let progressHits = 0;
+    for (const u of units) {
+        if (PROGRESS_HINT_RE.test(u))
+            progressHits += 1;
+    }
+    // Majority of multi-sentence text is progress narration.
+    return progressHits >= Math.ceil(units.length / 2);
+}
+/**
+ * Evaluate whether a parent turn shape is legal under the FC14 hard-stop.
+ * Pure / side-effect free — safe for mid-stream host gates and unit tests.
+ */
+export function evaluateParentTurnShape(input) {
+    const events = input.events ?? [];
+    const maxAllowed = input.maxIdenticalWithoutTool ?? DEFAULT_MAX_IDENTICAL_WITHOUT_TOOL;
+    let hasToolUse = false;
+    let hasYield = false;
+    for (const ev of events) {
+        if (ev.kind === "tool_use")
+            hasToolUse = true;
+        if (ev.kind === "yield")
+            hasYield = true;
+    }
+    // Tool or yield greases the turn: repetition hard-stop does not fire.
+    if (hasToolUse || hasYield) {
+        return {
+            ok: true,
+            failClass: "none",
+            reasons: [],
+            maxIdenticalCount: 0,
+            hasToolUse,
+            hasYield,
+        };
+    }
+    // Fail closed on unbounded zero-tool text (output-budget burn / DoS class).
+    const ZERO_TOOL_CHAR_CAP = 50_000;
+    let zeroToolChars = 0;
+    for (const ev of events) {
+        if (ev.kind === "assistant_text" && typeof ev.text === "string") {
+            zeroToolChars += ev.text.length;
+        }
+    }
+    if (zeroToolChars > ZERO_TOOL_CHAR_CAP) {
+        return {
+            ok: false,
+            failClass: "FC14",
+            reasons: [
+                `FC14 text-repetition-hang: zero-tool assistant text exceeds ${ZERO_TOOL_CHAR_CAP} chars ` +
+                    `(${zeroToolChars}) without tool_use/yield — hard-stop budget burn. Refs #3131 / #2943.`,
+            ],
+            maxIdenticalCount: Math.ceil(zeroToolChars / MIN_UNIT_LEN),
+            hasToolUse,
+            hasYield,
+        };
+    }
+    const units = collectAssistantUnits(events);
+    // Also fold in whole-blob repetition for single giant text events.
+    let maxIdenticalCount = maxIdenticalCluster(units);
+    for (const ev of events) {
+        if (ev.kind === "assistant_text" && typeof ev.text === "string") {
+            maxIdenticalCount = Math.max(maxIdenticalCount, countRepeatedUnitsInBlob(ev.text));
+        }
+    }
+    const reasons = [];
+    let failClass = "none";
+    if (maxIdenticalCount > maxAllowed) {
+        failClass = "FC14";
+        reasons.push(`FC14 text-repetition-hang: ${maxIdenticalCount} near-identical assistant text units ` +
+            `with zero tool_use/yield (max allowed ${maxAllowed}; N>${maxAllowed} is illegal). ` +
+            `After subagent announce, emit a tool-first ground-truth batch, sessions_yield, ` +
+            `or one short non-repeated answer — not repeated progress lines. Refs #3131 / #2943.`);
+    }
+    // Post-announce: multi-sentence progress-only with zero tools is also illegal
+    // even when sentences are not exact clones (soft-only #2943 recurrence class).
+    // Threshold is >=2 units (N>1 multi-sentence) — exactly two progress lines
+    // must not bypass the gate.
+    if (input.afterSubagentAnnounce &&
+        units.length >= 2 &&
+        looksLikeProgressOnly(units) &&
+        failClass === "none") {
+        failClass = "progress-only-no-tool";
+        reasons.push(`progress-only-no-tool: post-subagent-announce turn has ${units.length} assistant ` +
+            `text units with progress narration and zero tool_use/yield. MUST tool-first or yield. Refs #3131 / #2943.`);
+    }
+    // Alias surface: FC14 and text-repetition-hang name the same hang class.
+    if (failClass === "FC14") {
+        // Keep failClass as FC14; callers may also match text-repetition-hang via reasons.
+    }
+    return {
+        ok: failClass === "none",
+        failClass,
+        reasons,
+        maxIdenticalCount,
+        hasToolUse,
+        hasYield,
+    };
+}
+/** Convenience: true when the turn is an illegal text-repetition hang. */
+export function isTextRepetitionHang(input) {
+    const r = evaluateParentTurnShape(input);
+    return r.failClass === "FC14" || r.failClass === "text-repetition-hang";
+}
+//# sourceMappingURL=evaluate.js.map

package/dist/parent-turn-shape/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Parent turn-shape hard-stop (FC14 / #3131).
+ *
+ * Machine-checkable gate so soft skill prose is not the sole mitigation for
+ * the OpenClaw parent text-repetition hang after leaf announce.
+ */
+export { countRepeatedUnitsInBlob, DEFAULT_MAX_IDENTICAL_WITHOUT_TOOL, evaluateParentTurnShape, isNearIdentical, isTextRepetitionHang, normalizeTurnText, PARENT_TURN_FAIL_FC14, type ParentTurnEvent, type ParentTurnFailClass, type ParentTurnShapeInput, type ParentTurnShapeResult, splitTextUnits, } from "./evaluate.js";
+//# sourceMappingURL=index.d.ts.map