@tech-leads-club/harness-toolkit 0.2.1 → 0.2.4

package/dist/stop.mjs

@@ -280,20 +280,27 @@ function readJson(path) {
     return null;
   }
 }
-async function withFileLock(lockPath, fn) {
+function isContention(error) {
+  return errorCode(error) === "EEXIST" || isRetryableFsError(error);
+}
+async function withFileLock(lockPath, fn, options = {}) {
+  const {
+    openLock = (path) => closeSync(openSync(path, "wx")),
+    lockSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    lockAttempts = 200
+  } = options;
   mkdirSync2(dirname2(lockPath), { recursive: true });
-  const attempts = 200;
   let acquired = false;
-  for (let attempt = 0;attempt < attempts; attempt++) {
+  for (let attempt = 0;attempt < lockAttempts; attempt++) {
     try {
-      closeSync(openSync(lockPath, "wx"));
+      openLock(lockPath);
       acquired = true;
       break;
     } catch (error) {
-      if (errorCode(error) !== "EEXIST") {
+      if (!isContention(error)) {
         throw error;
       }
-      await new Promise((resolve) => setTimeout(resolve, nextDelay({ attempt, baseMs: 10, capMs: 200 })));
+      await lockSleep(nextDelay({ attempt, baseMs: 10, capMs: 200 }));
     }
   }
   if (!acquired) {
@@ -308,14 +315,14 @@ async function withFileLock(lockPath, fn) {
   }
 }
 async function updateJsonAtomic(path, mutator, options) {
-  const { lockPath, afterWrite, ...atomicOptions } = options;
+  const { lockPath, afterWrite, openLock, lockSleep, lockAttempts, ...atomicOptions } = options;
   return withFileLock(lockPath, async () => {
     const current = readJson(path);
     const next = mutator(current);
     await writeJsonAtomic(path, next, atomicOptions);
     afterWrite?.(path);
     return next;
-  });
+  }, { openLock, lockSleep, lockAttempts });
 }
 
 // src/core/capability/capability.store.ts
@@ -5631,6 +5638,68 @@ function evaluateShellCommand(args) {
   return { kind: "allow" };
 }
 
+// src/core/shim/shim.precedence.ts
+var LAUNCHER = "tlc-exec";
+function invocationText(entry) {
+  return [entry.command ?? "", ...entry.args ?? []].join(" ");
+}
+function coversHandler(settings, handler) {
+  for (const matchers of Object.values(settings.hooks ?? {})) {
+    for (const matcher of matchers) {
+      for (const entry of matcher.hooks ?? []) {
+        const text = invocationText(entry);
+        if (text.includes(LAUNCHER) && new RegExp(`(^|\\s)${handler}(\\s|$)`).test(text)) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+function decideShim(userSettings, handler) {
+  if (userSettings === null) {
+    return { run: true, reason: "no user-level settings — this shim is the only hook for this event" };
+  }
+  return coversHandler(userSettings, handler) ? {
+    run: false,
+    reason: `a user-level hook already runs ${handler} — standing down to avoid a second run`
+  } : { run: true, reason: `no user-level hook runs ${handler}` };
+}
+
+// src/core/skill/skill.link.ts
+var SKILL_NAME = "harness-init";
+function skillLinks(runtimeHome2, providerDirs, present) {
+  const source = `${runtimeHome2}/skills/${SKILL_NAME}`;
+  return providerDirs.filter((dir) => present(dir)).map((providerDir) => ({
+    providerDir,
+    source,
+    target: `${providerDir}/skills/${SKILL_NAME}`
+  }));
+}
+function linkHealth(target, runtimeHome2, probe) {
+  const resolved = probe.linkTarget(target);
+  if (resolved === null) {
+    return { state: "absent", target };
+  }
+  if (!probe.exists(resolved)) {
+    return { state: "dangling", target, resolved };
+  }
+  const home = runtimeHome2.replace(/\/+$/, "");
+  return resolved === home || resolved.startsWith(`${home}/`) ? { state: "ok", target, resolved } : { state: "outside-runtime", target, resolved };
+}
+function linkHealthMessage(health) {
+  switch (health.state) {
+    case "ok":
+      return `linked → ${health.resolved}`;
+    case "dangling":
+      return `points at ${health.resolved}, which does not exist — re-run \`tlc harness install\``;
+    case "outside-runtime":
+      return `points at ${health.resolved}, outside the runtime — it will break when that path goes`;
+    default:
+      return "not linked — the provider cannot see the init skill";
+  }
+}
+
 // src/core/stagnation/stagnation.resolution.ts
 import { existsSync as existsSync20, mkdirSync as mkdirSync11, readFileSync as readFileSync22, writeFileSync as writeFileSync10 } from "node:fs";
 import { join as join21 } from "node:path";
@@ -6758,6 +6827,15 @@ var coreFacade = {
     readHandoffFile,
     readForeignSlices
   },
+  shim: {
+    coversHandler,
+    decideShim
+  },
+  skill: {
+    linkHealth,
+    linkHealthMessage,
+    skillLinks
+  },
   lesson: {
     projectLessonsInjectable,
     recordLessonFromFailure,

package/dist/subagent-start.mjs

@@ -276,20 +276,27 @@ function readJson(path) {
     return null;
   }
 }
-async function withFileLock(lockPath, fn) {
+function isContention(error) {
+  return errorCode(error) === "EEXIST" || isRetryableFsError(error);
+}
+async function withFileLock(lockPath, fn, options = {}) {
+  const {
+    openLock = (path) => closeSync(openSync(path, "wx")),
+    lockSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    lockAttempts = 200
+  } = options;
   mkdirSync2(dirname2(lockPath), { recursive: true });
-  const attempts = 200;
   let acquired = false;
-  for (let attempt = 0;attempt < attempts; attempt++) {
+  for (let attempt = 0;attempt < lockAttempts; attempt++) {
     try {
-      closeSync(openSync(lockPath, "wx"));
+      openLock(lockPath);
       acquired = true;
       break;
     } catch (error) {
-      if (errorCode(error) !== "EEXIST") {
+      if (!isContention(error)) {
         throw error;
       }
-      await new Promise((resolve) => setTimeout(resolve, nextDelay({ attempt, baseMs: 10, capMs: 200 })));
+      await lockSleep(nextDelay({ attempt, baseMs: 10, capMs: 200 }));
     }
   }
   if (!acquired) {
@@ -304,14 +311,14 @@ async function withFileLock(lockPath, fn) {
   }
 }
 async function updateJsonAtomic(path, mutator, options) {
-  const { lockPath, afterWrite, ...atomicOptions } = options;
+  const { lockPath, afterWrite, openLock, lockSleep, lockAttempts, ...atomicOptions } = options;
   return withFileLock(lockPath, async () => {
     const current = readJson(path);
     const next = mutator(current);
     await writeJsonAtomic(path, next, atomicOptions);
     afterWrite?.(path);
     return next;
-  });
+  }, { openLock, lockSleep, lockAttempts });
 }
 
 // src/core/capability/capability.store.ts
@@ -5569,6 +5576,68 @@ function evaluateShellCommand(args) {
   return { kind: "allow" };
 }
 
+// src/core/shim/shim.precedence.ts
+var LAUNCHER = "tlc-exec";
+function invocationText(entry) {
+  return [entry.command ?? "", ...entry.args ?? []].join(" ");
+}
+function coversHandler(settings, handler) {
+  for (const matchers of Object.values(settings.hooks ?? {})) {
+    for (const matcher of matchers) {
+      for (const entry of matcher.hooks ?? []) {
+        const text = invocationText(entry);
+        if (text.includes(LAUNCHER) && new RegExp(`(^|\\s)${handler}(\\s|$)`).test(text)) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+function decideShim(userSettings, handler) {
+  if (userSettings === null) {
+    return { run: true, reason: "no user-level settings — this shim is the only hook for this event" };
+  }
+  return coversHandler(userSettings, handler) ? {
+    run: false,
+    reason: `a user-level hook already runs ${handler} — standing down to avoid a second run`
+  } : { run: true, reason: `no user-level hook runs ${handler}` };
+}
+
+// src/core/skill/skill.link.ts
+var SKILL_NAME = "harness-init";
+function skillLinks(runtimeHome2, providerDirs, present) {
+  const source = `${runtimeHome2}/skills/${SKILL_NAME}`;
+  return providerDirs.filter((dir) => present(dir)).map((providerDir) => ({
+    providerDir,
+    source,
+    target: `${providerDir}/skills/${SKILL_NAME}`
+  }));
+}
+function linkHealth(target, runtimeHome2, probe) {
+  const resolved = probe.linkTarget(target);
+  if (resolved === null) {
+    return { state: "absent", target };
+  }
+  if (!probe.exists(resolved)) {
+    return { state: "dangling", target, resolved };
+  }
+  const home = runtimeHome2.replace(/\/+$/, "");
+  return resolved === home || resolved.startsWith(`${home}/`) ? { state: "ok", target, resolved } : { state: "outside-runtime", target, resolved };
+}
+function linkHealthMessage(health) {
+  switch (health.state) {
+    case "ok":
+      return `linked → ${health.resolved}`;
+    case "dangling":
+      return `points at ${health.resolved}, which does not exist — re-run \`tlc harness install\``;
+    case "outside-runtime":
+      return `points at ${health.resolved}, outside the runtime — it will break when that path goes`;
+    default:
+      return "not linked — the provider cannot see the init skill";
+  }
+}
+
 // src/core/stagnation/stagnation.resolution.ts
 import { existsSync as existsSync20, mkdirSync as mkdirSync11, readFileSync as readFileSync22, writeFileSync as writeFileSync10 } from "node:fs";
 import { join as join21 } from "node:path";
@@ -6696,6 +6765,15 @@ var coreFacade = {
     readHandoffFile,
     readForeignSlices
   },
+  shim: {
+    coversHandler,
+    decideShim
+  },
+  skill: {
+    linkHealth,
+    linkHealthMessage,
+    skillLinks
+  },
   lesson: {
     projectLessonsInjectable,
     recordLessonFromFailure,

package/dist/subagent-stop.mjs

@@ -276,20 +276,27 @@ function readJson(path) {
     return null;
   }
 }
-async function withFileLock(lockPath, fn) {
+function isContention(error) {
+  return errorCode(error) === "EEXIST" || isRetryableFsError(error);
+}
+async function withFileLock(lockPath, fn, options = {}) {
+  const {
+    openLock = (path) => closeSync(openSync(path, "wx")),
+    lockSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    lockAttempts = 200
+  } = options;
   mkdirSync2(dirname2(lockPath), { recursive: true });
-  const attempts = 200;
   let acquired = false;
-  for (let attempt = 0;attempt < attempts; attempt++) {
+  for (let attempt = 0;attempt < lockAttempts; attempt++) {
     try {
-      closeSync(openSync(lockPath, "wx"));
+      openLock(lockPath);
       acquired = true;
       break;
     } catch (error) {
-      if (errorCode(error) !== "EEXIST") {
+      if (!isContention(error)) {
         throw error;
       }
-      await new Promise((resolve) => setTimeout(resolve, nextDelay({ attempt, baseMs: 10, capMs: 200 })));
+      await lockSleep(nextDelay({ attempt, baseMs: 10, capMs: 200 }));
     }
   }
   if (!acquired) {
@@ -304,14 +311,14 @@ async function withFileLock(lockPath, fn) {
   }
 }
 async function updateJsonAtomic(path, mutator, options) {
-  const { lockPath, afterWrite, ...atomicOptions } = options;
+  const { lockPath, afterWrite, openLock, lockSleep, lockAttempts, ...atomicOptions } = options;
   return withFileLock(lockPath, async () => {
     const current = readJson(path);
     const next = mutator(current);
     await writeJsonAtomic(path, next, atomicOptions);
     afterWrite?.(path);
     return next;
-  });
+  }, { openLock, lockSleep, lockAttempts });
 }
 
 // src/core/capability/capability.store.ts
@@ -5569,6 +5576,68 @@ function evaluateShellCommand(args) {
   return { kind: "allow" };
 }
 
+// src/core/shim/shim.precedence.ts
+var LAUNCHER = "tlc-exec";
+function invocationText(entry) {
+  return [entry.command ?? "", ...entry.args ?? []].join(" ");
+}
+function coversHandler(settings, handler) {
+  for (const matchers of Object.values(settings.hooks ?? {})) {
+    for (const matcher of matchers) {
+      for (const entry of matcher.hooks ?? []) {
+        const text = invocationText(entry);
+        if (text.includes(LAUNCHER) && new RegExp(`(^|\\s)${handler}(\\s|$)`).test(text)) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+function decideShim(userSettings, handler) {
+  if (userSettings === null) {
+    return { run: true, reason: "no user-level settings — this shim is the only hook for this event" };
+  }
+  return coversHandler(userSettings, handler) ? {
+    run: false,
+    reason: `a user-level hook already runs ${handler} — standing down to avoid a second run`
+  } : { run: true, reason: `no user-level hook runs ${handler}` };
+}
+
+// src/core/skill/skill.link.ts
+var SKILL_NAME = "harness-init";
+function skillLinks(runtimeHome2, providerDirs, present) {
+  const source = `${runtimeHome2}/skills/${SKILL_NAME}`;
+  return providerDirs.filter((dir) => present(dir)).map((providerDir) => ({
+    providerDir,
+    source,
+    target: `${providerDir}/skills/${SKILL_NAME}`
+  }));
+}
+function linkHealth(target, runtimeHome2, probe) {
+  const resolved = probe.linkTarget(target);
+  if (resolved === null) {
+    return { state: "absent", target };
+  }
+  if (!probe.exists(resolved)) {
+    return { state: "dangling", target, resolved };
+  }
+  const home = runtimeHome2.replace(/\/+$/, "");
+  return resolved === home || resolved.startsWith(`${home}/`) ? { state: "ok", target, resolved } : { state: "outside-runtime", target, resolved };
+}
+function linkHealthMessage(health) {
+  switch (health.state) {
+    case "ok":
+      return `linked → ${health.resolved}`;
+    case "dangling":
+      return `points at ${health.resolved}, which does not exist — re-run \`tlc harness install\``;
+    case "outside-runtime":
+      return `points at ${health.resolved}, outside the runtime — it will break when that path goes`;
+    default:
+      return "not linked — the provider cannot see the init skill";
+  }
+}
+
 // src/core/stagnation/stagnation.resolution.ts
 import { existsSync as existsSync20, mkdirSync as mkdirSync11, readFileSync as readFileSync22, writeFileSync as writeFileSync10 } from "node:fs";
 import { join as join21 } from "node:path";
@@ -6696,6 +6765,15 @@ var coreFacade = {
     readHandoffFile,
     readForeignSlices
   },
+  shim: {
+    coversHandler,
+    decideShim
+  },
+  skill: {
+    linkHealth,
+    linkHealthMessage,
+    skillLinks
+  },
   lesson: {
     projectLessonsInjectable,
     recordLessonFromFailure,

package/dist/support.mjs

@@ -269,20 +269,27 @@ function readJson(path) {
     return null;
   }
 }
-async function withFileLock(lockPath, fn) {
+function isContention(error) {
+  return errorCode(error) === "EEXIST" || isRetryableFsError(error);
+}
+async function withFileLock(lockPath, fn, options = {}) {
+  const {
+    openLock = (path) => closeSync(openSync(path, "wx")),
+    lockSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    lockAttempts = 200
+  } = options;
   mkdirSync2(dirname2(lockPath), { recursive: true });
-  const attempts = 200;
   let acquired = false;
-  for (let attempt = 0;attempt < attempts; attempt++) {
+  for (let attempt = 0;attempt < lockAttempts; attempt++) {
     try {
-      closeSync(openSync(lockPath, "wx"));
+      openLock(lockPath);
       acquired = true;
       break;
     } catch (error) {
-      if (errorCode(error) !== "EEXIST") {
+      if (!isContention(error)) {
         throw error;
       }
-      await new Promise((resolve) => setTimeout(resolve, nextDelay({ attempt, baseMs: 10, capMs: 200 })));
+      await lockSleep(nextDelay({ attempt, baseMs: 10, capMs: 200 }));
     }
   }
   if (!acquired) {
@@ -297,14 +304,14 @@ async function withFileLock(lockPath, fn) {
   }
 }
 async function updateJsonAtomic(path, mutator, options) {
-  const { lockPath, afterWrite, ...atomicOptions } = options;
+  const { lockPath, afterWrite, openLock, lockSleep, lockAttempts, ...atomicOptions } = options;
   return withFileLock(lockPath, async () => {
     const current = readJson(path);
     const next = mutator(current);
     await writeJsonAtomic(path, next, atomicOptions);
     afterWrite?.(path);
     return next;
-  });
+  }, { openLock, lockSleep, lockAttempts });
 }
 
 // src/core/capability/capability.store.ts
@@ -5555,6 +5562,68 @@ function evaluateShellCommand(args) {
   return { kind: "allow" };
 }
 
+// src/core/shim/shim.precedence.ts
+var LAUNCHER = "tlc-exec";
+function invocationText(entry) {
+  return [entry.command ?? "", ...entry.args ?? []].join(" ");
+}
+function coversHandler(settings, handler) {
+  for (const matchers of Object.values(settings.hooks ?? {})) {
+    for (const matcher of matchers) {
+      for (const entry of matcher.hooks ?? []) {
+        const text = invocationText(entry);
+        if (text.includes(LAUNCHER) && new RegExp(`(^|\\s)${handler}(\\s|$)`).test(text)) {
+          return true;
+        }
+      }
+    }
+  }
+  return false;
+}
+function decideShim(userSettings, handler) {
+  if (userSettings === null) {
+    return { run: true, reason: "no user-level settings — this shim is the only hook for this event" };
+  }
+  return coversHandler(userSettings, handler) ? {
+    run: false,
+    reason: `a user-level hook already runs ${handler} — standing down to avoid a second run`
+  } : { run: true, reason: `no user-level hook runs ${handler}` };
+}
+
+// src/core/skill/skill.link.ts
+var SKILL_NAME = "harness-init";
+function skillLinks(runtimeHome2, providerDirs, present) {
+  const source = `${runtimeHome2}/skills/${SKILL_NAME}`;
+  return providerDirs.filter((dir) => present(dir)).map((providerDir) => ({
+    providerDir,
+    source,
+    target: `${providerDir}/skills/${SKILL_NAME}`
+  }));
+}
+function linkHealth(target, runtimeHome2, probe) {
+  const resolved = probe.linkTarget(target);
+  if (resolved === null) {
+    return { state: "absent", target };
+  }
+  if (!probe.exists(resolved)) {
+    return { state: "dangling", target, resolved };
+  }
+  const home = runtimeHome2.replace(/\/+$/, "");
+  return resolved === home || resolved.startsWith(`${home}/`) ? { state: "ok", target, resolved } : { state: "outside-runtime", target, resolved };
+}
+function linkHealthMessage(health) {
+  switch (health.state) {
+    case "ok":
+      return `linked → ${health.resolved}`;
+    case "dangling":
+      return `points at ${health.resolved}, which does not exist — re-run \`tlc harness install\``;
+    case "outside-runtime":
+      return `points at ${health.resolved}, outside the runtime — it will break when that path goes`;
+    default:
+      return "not linked — the provider cannot see the init skill";
+  }
+}
+
 // src/core/stagnation/stagnation.resolution.ts
 import { existsSync as existsSync20, mkdirSync as mkdirSync11, readFileSync as readFileSync22, writeFileSync as writeFileSync10 } from "node:fs";
 import { join as join21 } from "node:path";
@@ -6682,6 +6751,15 @@ var coreFacade = {
     readHandoffFile,
     readForeignSlices
   },
+  shim: {
+    coversHandler,
+    decideShim
+  },
+  skill: {
+    linkHealth,
+    linkHealthMessage,
+    skillLinks
+  },
   lesson: {
     projectLessonsInjectable,
     recordLessonFromFailure,