@mjasnikovs/pi-task 0.13.36 → 0.13.38

package/dist/task/auto-orchestrator.js

@@ -17,7 +17,7 @@ import { writeTaskFile, readTaskFile, updateTaskFrontMatter, taskFilePath, tasks
 import { gitCommitAll } from './auto-commit.js';
 import { runGuidelineEnforcement, classifyEnforceChildFailure } from './enforce-guidelines.js';
 import { runWorker } from '../workers/pi-worker-core.js';
-import { runPhaseChild, prependHint, USER_CANCELLED } from './child-runner.js';
+import { runPhaseChild, prependHint, formatLoopHint, USER_CANCELLED } from './child-runner.js';
 import { SessionUI, registerBridgeCommand } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
 import { getConfig } from '../config/config.js';
@@ -362,7 +362,15 @@ function defaultDeps(ctx, cwd, signal, title) {
                             signal: sig,
                             tools,
                             timeoutMs: 0, // no wall-clock timeout — run to completion
-                            loop: false, // no loop guard — revisiting one file IS the job
+                            // Exact-match loop guard only: pathThreshold Infinity
+                            // disables the path-revisit heuristic, so revisiting one
+                            // file (which IS this pass's job) never trips — only a
+                            // literally-identical call repeated past threshold does
+                            // (e.g. the same grep fired 900× in enforce-debug.log).
+                            // A hit nudges via the normal restart-with-hint; a loop
+                            // that survives the nudges is WARNED, not blocked (see
+                            // r.loopHit handling below and classifyEnforceChildFailure).
+                            loop: { pathThreshold: Number.POSITIVE_INFINITY },
                             onLine: line => {
                                 lastLine = line;
                                 logEnforce(line);
@@ -371,6 +379,13 @@ function defaultDeps(ctx, cwd, signal, title) {
                                 contextUsage = resolveContextUsage(snapshot, contextUsage, parentContextWindow);
                             }
                         });
+                        // A loop that survived the restart-with-hint nudges is a
+                        // warning, not a failure: log it and tell the user, but let
+                        // the verdict gate (below) be the only thing that can block.
+                        if (r.loopHit) {
+                            logEnforce(`=== enforce LOOP WARNING — ${formatLoopHint(r.loopHit)} ===`);
+                            enforceCtx.ui.notify(`${taskTitle}: enforce worker looped past the nudges — continuing (not blocked).`, 'warning');
+                        }
                         const failure = classifyEnforceChildFailure(r);
                         logEnforce(failure ?
                             `=== enforce end: FAIL — ${failure} ===`

package/dist/task/enforce-guidelines.d.ts

@@ -56,10 +56,17 @@ export interface EnforceChildResult {
  * when it finished cleanly enough to parse a verdict from its text.
  *
  * The order is load-bearing. A loop-kill AND a wall-clock timeout BOTH also set
- * `aborted` — killProc flips it on every kill path — so the specific causes
- * (timeout, loop, leaked tool call) must be named BEFORE the generic
- * `aborted → user-cancel` mapping. Checking `aborted` first (as the original
- * inline code did) mislabels a loop-killed enforcement child as a user cancel.
+ * `aborted` (and a non-zero exit) — killProc flips it on every kill path — so the
+ * specific causes (timeout, loop, leaked tool call) must be handled BEFORE the
+ * generic `aborted → user-cancel` and `exitCode` mappings. Checking `aborted`
+ * first (as the original inline code did) mislabels a loop-killed enforcement
+ * child as a user cancel.
+ *
+ * A loop is NOT fatal: enforce attaches the detector in nudge-then-warn mode, so a
+ * loop that survived its restart-with-hint nudges returns null here (the caller
+ * logs/notifies it as a warning) and the verdict gate alone decides the outcome.
+ * It still has to be matched before `aborted`/`exitCode` so the kill's side
+ * effects don't get re-classified as a user cancel or a crash.
  */
 export declare function classifyEnforceChildFailure(r: EnforceChildResult): string | null;
 /**

package/dist/task/enforce-guidelines.js

@@ -101,16 +101,23 @@ export function parseEnforceVerdict(text) {
  * when it finished cleanly enough to parse a verdict from its text.
  *
  * The order is load-bearing. A loop-kill AND a wall-clock timeout BOTH also set
- * `aborted` — killProc flips it on every kill path — so the specific causes
- * (timeout, loop, leaked tool call) must be named BEFORE the generic
- * `aborted → user-cancel` mapping. Checking `aborted` first (as the original
- * inline code did) mislabels a loop-killed enforcement child as a user cancel.
+ * `aborted` (and a non-zero exit) — killProc flips it on every kill path — so the
+ * specific causes (timeout, loop, leaked tool call) must be handled BEFORE the
+ * generic `aborted → user-cancel` and `exitCode` mappings. Checking `aborted`
+ * first (as the original inline code did) mislabels a loop-killed enforcement
+ * child as a user cancel.
+ *
+ * A loop is NOT fatal: enforce attaches the detector in nudge-then-warn mode, so a
+ * loop that survived its restart-with-hint nudges returns null here (the caller
+ * logs/notifies it as a warning) and the verdict gate alone decides the outcome.
+ * It still has to be matched before `aborted`/`exitCode` so the kill's side
+ * effects don't get re-classified as a user cancel or a crash.
  */
 export function classifyEnforceChildFailure(r) {
     if (r.timedOut)
         return 'enforcement child timed out';
     if (r.loopHit)
-        return 'enforcement child looped';
+        return null; // looped past the nudges → warning, handled by caller
     if (r.leakedToolCall)
         return 'enforcement child leaked a tool call';
     if (r.aborted)

package/dist/workers/docs-core.js

@@ -4,7 +4,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import { openCache as defaultOpenCache } from './docs-cache.js';
 import { ensureIndexed as defaultEnsureIndexed } from './docs-index.js';
-import { resolvePackage as defaultResolvePackage, ResolveError } from './docs-resolve.js';
+import { resolvePackage as defaultResolvePackage, ResolveError, detectTypesRedirect, typesPackageName, hasTypeFiles, isDtsFile } from './docs-resolve.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import { npmVersionLookup as defaultNpmVersionLookup } from './npm-version.js';
 import { getPiInvocation } from '../shared/pi-invocation.js';
@@ -44,6 +44,52 @@ export async function runAutoInstall(spawn, packageName, signal) {
     }, installDir, signal, { mode: 'text', discardStdout: true });
     return { success: result.exitCode === 0 && !result.aborted, installDir, stderr: result.stderr };
 }
+/** Resolve `name` from cwd; on `not_installed`, auto-install it and resolve from
+ *  the install dir. Returns null on any failure (caller keeps its fallback). */
+async function tryResolveOrInstall(name, cwd, spawn, resolvePackage, signal) {
+    try {
+        return resolvePackage(name, cwd);
+    }
+    catch (err) {
+        if (!(err instanceof ResolveError) || err.kind !== 'not_installed')
+            return null;
+        const install = await runAutoInstall(spawn, extractParentPackage(name), signal);
+        if (!install.success)
+            return null;
+        try {
+            return resolvePackage(name, install.installDir);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/** Follow the @types/<name> + triple-slash `<reference types>` redirect chain
+ *  from a package that ships no usable types of its own to the one that actually
+ *  holds the declarations (e.g. bun -> @types/bun -> bun-types). Bounded to a few
+ *  hops; returns the original package if no better source is found. */
+async function resolveTypeSource(pkg, requested, cwd, spawn, resolvePackage, signal) {
+    const visited = new Set([pkg.name, extractParentPackage(requested)]);
+    let cur = pkg;
+    for (let depth = 0; depth < 3; depth++) {
+        let next = detectTypesRedirect(cur);
+        if (next && visited.has(next))
+            next = null;
+        if (!next && !hasTypeFiles(cur.root)) {
+            const types = typesPackageName(cur.name);
+            if (types && !visited.has(types))
+                next = types;
+        }
+        if (!next)
+            break;
+        visited.add(next);
+        const resolved = await tryResolveOrInstall(next, cwd, spawn, resolvePackage, signal);
+        if (!resolved)
+            break;
+        cur = resolved;
+    }
+    return cur;
+}
 export async function docsRaw(input) {
     const resolvePackage = input.resolvePackage ?? defaultResolvePackage;
     const ensureIndexed = input.ensureIndexed ?? defaultEnsureIndexed;
@@ -114,6 +160,13 @@ export async function docsRaw(input) {
             };
         }
     }
+    // Step 1b: if the resolved package ships no usable type declarations (e.g.
+    // the `bun` runtime launcher, which is just a binary + install README), or is
+    // a pure `@types/<name>` redirect stub, follow the conventional
+    // @types/<name> + triple-slash `<reference types>` chain to the package that
+    // actually holds the declarations (e.g. bun -> @types/bun -> bun-types).
+    // Best-effort: any failure leaves the original resolution untouched.
+    pkg = await resolveTypeSource(pkg, input.pkg, input.cwd, spawn, resolvePackage, input.signal);
     // Step 2: open cache
     let cache = null;
     let cacheError;
@@ -257,7 +310,7 @@ function walkDtsAlpha(root) {
             const full = path.join(dir, entry.name);
             if (entry.isDirectory())
                 stack.push(full);
-            else if (entry.isFile() && entry.name.endsWith('.d.ts'))
+            else if (entry.isFile() && isDtsFile(entry.name))
                 out.push(full);
         }
     }

package/dist/workers/docs-index.d.ts

@@ -1,5 +1,5 @@
 import type { CacheHandle } from './docs-cache.js';
-import type { ResolvedPackage } from './docs-resolve.js';
+import { type ResolvedPackage } from './docs-resolve.js';
 export interface IndexResult {
     hitCache: boolean;
     filesIngested: number;

package/dist/workers/docs-index.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { isDtsFile } from './docs-resolve.js';
 const MAX_CHUNK_BYTES = 8 * 1024;
 const ZERO_SEP = Buffer.from([0]);
 const DECL_SPLIT_RE = /^(?:export\s+|declare\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|type|namespace|module|const|let|var|enum)\s+/m;
@@ -48,13 +49,13 @@ function walkDts(root) {
                 const stat = fs.statSync(realPath);
                 if (stat.isDirectory())
                     stack.push(realPath);
-                else if (stat.isFile() && realPath.endsWith('.d.ts'))
+                else if (stat.isFile() && isDtsFile(realPath))
                     out.push(realPath);
                 continue;
             }
             if (entry.isDirectory())
                 stack.push(full);
-            else if (entry.isFile() && entry.name.endsWith('.d.ts'))
+            else if (entry.isFile() && isDtsFile(entry.name))
                 out.push(full);
         }
     }

package/dist/workers/docs-resolve.d.ts

@@ -1,3 +1,5 @@
+/** True for TypeScript declaration files: .d.ts, .d.mts, .d.cts. */
+export declare function isDtsFile(name: string): boolean;
 export interface ResolvedPackage {
     name: string;
     version: string;
@@ -10,3 +12,15 @@ export declare class ResolveError extends Error {
     constructor(kind: 'not_installed' | 'invalid_name', message: string);
 }
 export declare function resolvePackage(moduleName: string, cwd: string): ResolvedPackage;
+/** Conventional DefinitelyTyped package for a runtime package that ships no
+ *  types of its own. `bun` -> `@types/bun`, `@scope/x` -> `@types/scope__x`.
+ *  Returns null for packages that are already under the `@types` scope. */
+export declare function typesPackageName(moduleName: string): string | null;
+/** True if the package ships at least one declaration file. */
+export declare function hasTypeFiles(root: string): boolean;
+/** When a package is a pure pointer to another types package — a single-file
+ *  `/// <reference types="X" />` (the `@types/bun -> bun-types` shape) or a lone
+ *  `export * from "X"` re-export — return the target package name. Returns null
+ *  for packages that ship their own declarations (more than one .d.ts file, or a
+ *  local `/// <reference path=... />` aggregator entry). */
+export declare function detectTypesRedirect(pkg: ResolvedPackage): string | null;

package/dist/workers/docs-resolve.js

@@ -1,6 +1,11 @@
 import { createRequire } from 'node:module';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+const DTS_RE = /\.d\.(?:ts|mts|cts)$/;
+/** True for TypeScript declaration files: .d.ts, .d.mts, .d.cts. */
+export function isDtsFile(name) {
+    return DTS_RE.test(name);
+}
 export class ResolveError extends Error {
     kind;
     constructor(kind, message) {
@@ -52,10 +57,18 @@ function findReadme(root) {
 function resolveEntryDts(moduleName, parent, root, pkg) {
     if (moduleName !== parent) {
         const subpath = moduleName.slice(parent.length + 1);
-        const candidates = [`${subpath}.d.ts`, `${subpath}/index.d.ts`, subpath];
+        const candidates = [
+            `${subpath}.d.ts`,
+            `${subpath}.d.mts`,
+            `${subpath}.d.cts`,
+            `${subpath}/index.d.ts`,
+            `${subpath}/index.d.mts`,
+            `${subpath}/index.d.cts`,
+            subpath
+        ];
         for (const c of candidates) {
             const abs = path.join(root, c);
-            if (fs.existsSync(abs) && abs.endsWith('.d.ts'))
+            if (fs.existsSync(abs) && isDtsFile(abs))
                 return abs;
         }
     }
@@ -71,9 +84,11 @@ function resolveEntryDts(moduleName, parent, root, pkg) {
         if (fs.existsSync(abs))
             return abs;
     }
-    const fallback = path.join(root, 'index.d.ts');
-    if (fs.existsSync(fallback))
-        return fallback;
+    for (const name of ['index.d.ts', 'index.d.mts', 'index.d.cts']) {
+        const fallback = path.join(root, name);
+        if (fs.existsSync(fallback))
+            return fallback;
+    }
     return null;
 }
 export function resolvePackage(moduleName, cwd) {
@@ -124,3 +139,95 @@ function findPackageJsonInNodeModules(parent, startDir) {
         dir = up;
     }
 }
+/** Conventional DefinitelyTyped package for a runtime package that ships no
+ *  types of its own. `bun` -> `@types/bun`, `@scope/x` -> `@types/scope__x`.
+ *  Returns null for packages that are already under the `@types` scope. */
+export function typesPackageName(moduleName) {
+    const parent = parentPackageName(moduleName);
+    if (parent.startsWith('@types/'))
+        return null;
+    if (parent.startsWith('@')) {
+        const [scope, name] = parent.slice(1).split('/');
+        if (!scope || !name)
+            return null;
+        return `@types/${scope}__${name}`;
+    }
+    return `@types/${parent}`;
+}
+/** Count declaration files under root (excluding nested node_modules), stopping
+ *  once `cap` is reached. */
+function countTypeFiles(root, cap) {
+    let n = 0;
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.name === 'node_modules')
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                stack.push(full);
+            else if (entry.isFile() && isDtsFile(entry.name)) {
+                if (++n >= cap)
+                    return n;
+            }
+        }
+    }
+    return n;
+}
+/** True if the package ships at least one declaration file. */
+export function hasTypeFiles(root) {
+    return countTypeFiles(root, 1) > 0;
+}
+function findIndexDts(root) {
+    for (const name of ['index.d.ts', 'index.d.mts', 'index.d.cts']) {
+        const abs = path.join(root, name);
+        if (fs.existsSync(abs))
+            return abs;
+    }
+    return null;
+}
+function isBareSpecifier(spec) {
+    return spec.length > 0 && !spec.startsWith('.') && !spec.startsWith('/');
+}
+const REFERENCE_TYPES_RE = /\/\/\/\s*<reference\s+types=["']([^"']+)["']\s*\/>/;
+const REEXPORT_ALL_RE = /^\s*export\s+(?:type\s+)?\*\s+from\s+["']([^"']+)["'];?\s*$/m;
+/** When a package is a pure pointer to another types package — a single-file
+ *  `/// <reference types="X" />` (the `@types/bun -> bun-types` shape) or a lone
+ *  `export * from "X"` re-export — return the target package name. Returns null
+ *  for packages that ship their own declarations (more than one .d.ts file, or a
+ *  local `/// <reference path=... />` aggregator entry). */
+export function detectTypesRedirect(pkg) {
+    // A package that ships multiple declaration files is an aggregator, not a
+    // redirect stub — use its own types.
+    if (countTypeFiles(pkg.root, 2) > 1)
+        return null;
+    const entry = pkg.entryDts ?? findIndexDts(pkg.root);
+    if (!entry)
+        return null;
+    let content;
+    try {
+        content = fs.readFileSync(entry, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    // A local `/// <reference path="..." />` means the entry aggregates sibling
+    // declarations (e.g. bun-types) — not a redirect to another package.
+    if (/\/\/\/\s*<reference\s+path=/.test(content))
+        return null;
+    const ref = REFERENCE_TYPES_RE.exec(content);
+    if (ref && isBareSpecifier(ref[1]))
+        return parentPackageName(ref[1]);
+    const rex = REEXPORT_ALL_RE.exec(content);
+    if (rex && isBareSpecifier(rex[1]))
+        return parentPackageName(rex[1]);
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.13.36",
+    "version": "0.13.38",
     "description": "Deterministic spec-orchestration for local models, with a bundled real-time remote web view and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",