agentsmesh 0.40.0 → 0.41.0

package/dist/{init-B1qdo3Dl.d.ts → init-DruMEhnc.d.ts}

@@ -150,6 +150,12 @@ declare const DEFAULT_RECALL_MAX_TOKENS = 1200;
  */
 declare function rankLessons(graph: LessonsGraph, query: LessonsQuery, matches: readonly MatchedLesson[], options?: RankOptions): RankedLesson[];
 
+/** Warning for a command trigger dropped at capture because it can never fire. */
+interface DeadCommandWarning {
+    readonly code: 'DEAD_COMMAND_PATTERN';
+    readonly message: string;
+}
+
 interface AutoPruneSummary {
     readonly removedTriggers: number;
     readonly removedTopics: number;
@@ -170,7 +176,7 @@ interface AutoPruneSummary {
  * because that lesson is captured then silently never recalled. These guardrails
  * are the warn-only complement to that single hard block.
  */
-type GuardrailCode = 'OVERSIZED_LESSON_TRIGGERS' | 'BROAD_GLOB_TRIGGER' | 'WIDE_GLOB_MATCH' | 'KEYWORD_ONLY_LESSON' | 'LOW_SIGNAL_KEYWORD' | 'STOPWORD_KEYWORD' | 'DEAD_GLOB' | 'NEAR_DUPLICATE_LESSON';
+type GuardrailCode = 'OVERSIZED_LESSON_TRIGGERS' | 'BROAD_GLOB_TRIGGER' | 'WIDE_GLOB_MATCH' | 'KEYWORD_ONLY_LESSON' | 'LOW_SIGNAL_KEYWORD' | 'STOPWORD_KEYWORD' | 'DEAD_GLOB' | 'PENDING_GLOB' | 'NEAR_DUPLICATE_LESSON';
 interface GuardrailWarning {
     readonly code: GuardrailCode;
     readonly message: string;
@@ -215,13 +221,17 @@ interface AddLessonOptions {
      */
     readonly knownPaths?: ReadonlySet<string>;
 }
+/** A non-blocking capture warning: a guardrail nudge or a dropped dead command trigger. */
+type AddLessonWarning = GuardrailWarning | DeadCommandWarning;
 interface AddLessonResult {
     readonly id: string;
     readonly isNewLesson: boolean;
     readonly isNewTopic: boolean;
     readonly newTriggerIds: string[];
-    /** Non-blocking capture guardrail warnings for the resulting (merged) lesson. */
-    readonly warnings: GuardrailWarning[];
+    /** What a re-add changed on the existing lesson; empty for a new lesson or a no-op. */
+    readonly changes: string[];
+    /** Non-blocking capture warnings for the resulting (merged) lesson. */
+    readonly warnings: AddLessonWarning[];
     /**
      * Counts of structural cruft the opt-in auto-prune cleaned up right after this
      * capture (config `autoPrune: true`). Present only when something was pruned;
@@ -231,6 +241,33 @@ interface AddLessonResult {
 }
 declare function addLesson(projectRoot: string, input: AddLessonInput, options?: AddLessonOptions): Promise<AddLessonResult>;
 
+type ValidationLevel = 'error' | 'warning';
+interface ValidationFinding {
+    readonly level: ValidationLevel;
+    readonly code: string;
+    readonly message: string;
+    readonly lessonId?: string;
+    /** Every lesson one aggregate finding covers (machine-readable; the message names a few). */
+    readonly lessonIds?: readonly string[];
+    readonly topicId?: string;
+    readonly triggerId?: string;
+}
+interface ValidationReport {
+    /** True when no `error`-level findings exist (warnings do not affect `ok`). */
+    readonly ok: boolean;
+    readonly findings: ValidationFinding[];
+}
+interface ValidateOptions {
+    /**
+     * Working-tree file list (project-relative, forward-slash) for the dead-glob
+     * liveness check. When omitted the check is SKIPPED — the pure write-barrier
+     * call in `mutate.ts` passes nothing, so `add` never walks the tree and a
+     * liveness warning can never block a write. The CLI/lint callers supply it.
+     */
+    readonly knownPaths?: ReadonlySet<string>;
+}
+declare function validateLessonsGraph(graph: LessonsGraph, options?: ValidateOptions): ValidationReport;
+
 interface MutateOptions {
     readonly retries?: number;
 }
@@ -302,33 +339,6 @@ declare function stripLegacyMarkers(rule: string): string;
  */
 declare function stripMarkersInGraph(projectRoot: string, options?: StripMarkersOptions): Promise<StripMarkersReport>;
 
-type ValidationLevel = 'error' | 'warning';
-interface ValidationFinding {
-    readonly level: ValidationLevel;
-    readonly code: string;
-    readonly message: string;
-    readonly lessonId?: string;
-    /** Every lesson one aggregate finding covers (machine-readable; the message names a few). */
-    readonly lessonIds?: readonly string[];
-    readonly topicId?: string;
-    readonly triggerId?: string;
-}
-interface ValidationReport {
-    /** True when no `error`-level findings exist (warnings do not affect `ok`). */
-    readonly ok: boolean;
-    readonly findings: ValidationFinding[];
-}
-interface ValidateOptions {
-    /**
-     * Working-tree file list (project-relative, forward-slash) for the dead-glob
-     * liveness check. When omitted the check is SKIPPED — the pure write-barrier
-     * call in `mutate.ts` passes nothing, so `add` never walks the tree and a
-     * liveness warning can never block a write. The CLI/lint callers supply it.
-     */
-    readonly knownPaths?: ReadonlySet<string>;
-}
-declare function validateLessonsGraph(graph: LessonsGraph, options?: ValidateOptions): ValidationReport;
-
 interface ImportLegacyOptions {
     /** ISO date stamped onto every imported lesson's `createdAt`. */
     readonly migratedAt: string;
@@ -353,6 +363,12 @@ interface ImportLegacyOptions {
      * data; `force` is irrelevant in this mode.
      */
     readonly merge?: boolean;
+    /**
+     * Refuse ({@link LessonsGraphExistsError}) when `lessons.json` exists at write
+     * time under the lock, even if empty. Auto-migration sets this so two first
+     * writers cannot both migrate.
+     */
+    readonly requireAbsentGraph?: boolean;
 }
 /** Thrown when migration would overwrite an already-populated graph without `force`. */
 declare class LessonsGraphExistsError extends Error {
@@ -377,31 +393,54 @@ interface ImportLegacyReport {
  * `existsSync(lessonsPaths(root).index)` before invoking (see
  * `maybeAutoMigrateLessons` and the `import-md` handler); re-running on a
  * post-migration tree, where the legacy files are already gone, throws.
+ * Topic files outside `.agentsmesh/lessons/` are refused (LegacyTopicPathError).
  */
 declare function importLegacyLessons(projectRoot: string, options: ImportLegacyOptions): Promise<ImportLegacyReport>;
 
 /**
  * Cross-platform process lock backed by an atomic mkdir.
  *
- * Stale recovery: the holder writes its PID and start timestamp into the lock
- * dir. A dead same-host holder is evicted at once. A live or remote holder is
- * evicted only past `staleMs` — an hours-long bound that catches a hung
- * process or a recycled PID, never a slow but healthy run.
+ * Each acquisition gets a random owner token, kept as an `owner-<token>` marker
+ * in the lock dir next to `holder.json` (pid, host, start time). The lock
+ * changes hands only by removing that exact marker, so neither a release nor
+ * a stale eviction can delete a lock that already passed to another process.
+ *
+ * Stale recovery: a dead same-host holder, or a live pid that now belongs to
+ * another process, is evicted at once. Any holder older than `staleMs` (or
+ * dated in the future past clock skew) is evicted too — the bound for hung
+ * processes and holders on other hosts. A holder evicted this way sees
+ * `isHeld()` turn false, so it can refuse to write.
  */
 interface LockOptions {
     /** Maximum retry attempts before throwing LockAcquisitionError. */
     retries?: number;
-    /** Delay between retries in ms. */
+    /** Delay before the first retry in ms (default 200). */
     retryDelayMs?: number;
+    /** Cap for the doubling delay. Defaults to `retryDelayMs`, i.e. a fixed delay. */
+    maxRetryDelayMs?: number;
+    /** Spread each delay over the upper half of its window so waiters do not retry in step. */
+    jitter?: boolean;
     /**
-     * Secondary age bound (default 6h): a lock older than this is evicted even
-     * when its holder PID is still alive or cannot be probed (other host).
+     * Age bound (default 6h): a lock older than this is evicted even when its
+     * holder is still alive or cannot be probed (other host).
      */
     staleMs?: number;
     /** Human-readable lock name surfaced in LockAcquisitionError, e.g. "lessons lock". */
     label?: string;
+    /** Called once, with the holder, when a wait lasts `waitNoticeMs` (default 2000). */
+    onWait?: (holder: string) => void;
+    waitNoticeMs?: number;
 }
 type LockRelease = () => Promise<void>;
+/** The release function of an acquired lock. */
+interface HeldLock extends LockRelease {
+    /**
+     * False once this acquisition no longer owns the lock: released, or evicted
+     * as stale (e.g. the process was paused longer than `staleMs`). Check it
+     * right before a write that must not overwrite a later holder's work.
+     */
+    isHeld(): Promise<boolean>;
+}
 
 /**
  * Process lock for lessons-graph writes.
@@ -410,13 +449,12 @@ type LockRelease = () => Promise<void>;
  * the rule once per failure, even when a hooked CI step and the user's editor
  * race for the same `lessons.json`. The lock lives at
  * `.agentsmesh/lessons/.lessons.lock` and reuses the same `acquireProcessLock`
- * primitive as `.install.lock` / `.generate.lock`, so stale-eviction, signal
- * cleanup, and PID metadata all behave identically.
+ * primitive as `.install.lock` / `.generate.lock`, with its own timing below.
  */
 
 declare const LESSONS_LOCK_FILENAME = ".lessons.lock";
 declare function lessonsLockPath(projectRoot: string): string;
-declare function acquireLessonsLock(projectRoot: string, opts?: LockOptions): Promise<LockRelease>;
+declare function acquireLessonsLock(projectRoot: string, opts?: LockOptions): Promise<HeldLock>;
 
 /**
  * Default on-disk locations for the lessons subsystem.
@@ -472,18 +510,35 @@ declare function toRelPath(projectRoot: string, absolute: string): string;
  */
 declare const LESSONS_PROCEDURAL_RULE = "## Lessons (BLOCKING)\n\nGraph `.agentsmesh/lessons/lessons.json` is canonical; never hand-edit it. Manual: `lessons` skill.\n\n**Recall:** before every file edit or state-changing command, MUST run `agentsmesh lessons query --file <path> --cmd <command> --session auto` and obey matches; at task start, ALSO run `agentsmesh lessons query --keyword \"<task terms>\" --always --session auto` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.\n\n**Capture:** after any failure, user correction, regression, wrong assumption, useful surprise, repeated friction, or non-obvious fix, MUST self-critique and run `agentsmesh lessons add \"<imperative rule>\" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>`.\n\n**Before final:** report `Lesson: captured <id>` or `Lesson: none`. No recall/capture gate = task incomplete. No shell: use `lessons_query` / `lessons_add`.";
 
+type MergeDriverSetup = {
+    readonly status: 'configured' | 'updated' | 'unchanged' | 'skipped';
+    readonly command: string;
+} | {
+    readonly status: 'custom';
+    readonly command: string;
+    readonly existing: string;
+} | {
+    readonly status: 'failed';
+    readonly command: string;
+    readonly reason: string;
+};
+
 interface ScaffoldLessonsResult {
     readonly created: string[];
     /** Managed artifacts rewritten to the current wording (e.g. a stale skill). */
     readonly updated: string[];
     readonly skipped: string[];
     readonly rootRuleUpdated: boolean;
-    /** True when the recall-log gitignore entry was added to `.gitignore`. */
+    /** True when any lessons runtime-artifact entry was added to `.gitignore`. */
     readonly gitignoreUpdated: boolean;
     /** True when the lessons.json merge-driver entry was added to `.gitattributes`. */
     readonly gitattributesUpdated: boolean;
-    /** True when the PostToolUse recall hook was injected into `hooks.yaml`. */
+    /** True when the lessons recall hook was injected into `hooks.yaml`. */
     readonly recallHookInjected: boolean;
+    /** What this clone's merge-driver setup did; teammates get it on `generate`. */
+    readonly mergeDriver: MergeDriverSetup;
+    /** Set when recall hooks still need a global install to reach teammates. */
+    readonly recallHookTeamHint: string | null;
 }
 /**
  * Idempotent scaffolder for the lessons subsystem. Backs `agentsmesh init

package/dist/lessons.d.ts

@@ -1,5 +1,5 @@
-import { o as RankedLesson, j as LessonsQuery, A as AddLessonInput, a as AddLessonOptions, b as AddLessonResult } from './init-B1qdo3Dl.js';
-export { c as AddLessonTriggers, D as DEFAULT_RECALL_LIMIT, X as DEFAULT_RECALL_MAX_TOKENS, I as ImportLegacyOptions, d as ImportLegacyReport, Y as LESSONS_LOCK_FILENAME, L as LESSONS_PROCEDURAL_RULE, e as Lesson, f as LessonStatus, g as LessonsGraph, Z as LessonsGraphExistsError, h as LessonsGraphSchema, i as LessonsPaths, M as MatchedLesson, k as MergeLessonsOptions, l as MergeLessonsResult, m as MutateOptions, R as RankOptions, n as RankReason, S as ScaffoldLessonsResult, p as StripMarkersOptions, q as StripMarkersReport, T as Topic, r as Trigger, s as TriggerKind, U as UnknownTopicError, V as ValidationFinding, t as ValidationLevel, u as ValidationReport, v as acquireLessonsLock, w as addLesson, x as graphFilePath, y as importLegacyLessons, _ as lessonsLockPath, z as lessonsPaths, B as loadLessonsGraph, C as mergeLessons, E as mutateLessonsGraph, F as parseGraph, G as queryLessons, H as rankLessons, J as scaffoldLessons, K as serializeGraph, N as stripLegacyMarkers, O as stripMarkersInGraph, P as toRelPath, Q as tryLoadLessonsGraph, W as validateLessonsGraph } from './init-B1qdo3Dl.js';
+import { o as RankedLesson, j as LessonsQuery, A as AddLessonInput, a as AddLessonOptions, b as AddLessonResult } from './init-DruMEhnc.js';
+export { c as AddLessonTriggers, D as DEFAULT_RECALL_LIMIT, X as DEFAULT_RECALL_MAX_TOKENS, I as ImportLegacyOptions, d as ImportLegacyReport, Y as LESSONS_LOCK_FILENAME, L as LESSONS_PROCEDURAL_RULE, e as Lesson, f as LessonStatus, g as LessonsGraph, Z as LessonsGraphExistsError, h as LessonsGraphSchema, i as LessonsPaths, M as MatchedLesson, k as MergeLessonsOptions, l as MergeLessonsResult, m as MutateOptions, R as RankOptions, n as RankReason, S as ScaffoldLessonsResult, p as StripMarkersOptions, q as StripMarkersReport, T as Topic, r as Trigger, s as TriggerKind, U as UnknownTopicError, V as ValidationFinding, t as ValidationLevel, u as ValidationReport, v as acquireLessonsLock, w as addLesson, x as graphFilePath, y as importLegacyLessons, _ as lessonsLockPath, z as lessonsPaths, B as loadLessonsGraph, C as mergeLessons, E as mutateLessonsGraph, F as parseGraph, G as queryLessons, H as rankLessons, J as scaffoldLessons, K as serializeGraph, N as stripLegacyMarkers, O as stripMarkersInGraph, P as toRelPath, Q as tryLoadLessonsGraph, W as validateLessonsGraph } from './init-DruMEhnc.js';
 import 'zod';
 
 /**
@@ -92,6 +92,8 @@ declare function captureLesson(projectRoot: string, input: AddLessonInput, optio
  * legacy store: if it added first it would create `lessons.json`, which then
  * permanently blocks the absent-graph auto-migration. Returns true if it
  * migrated. No-op when a graph already exists or no legacy index is present.
+ * The unlocked checks are a fast path; `requireAbsentGraph` repeats the graph
+ * check under the lessons lock before the legacy store is read.
  */
 declare function maybeAutoMigrateLessons(projectRoot: string): Promise<boolean>;
 
@@ -108,8 +110,9 @@ declare function maybeAutoMigrateLessons(projectRoot: string): Promise<boolean>;
  * linear in the input length for any pattern it can compile.
  *
  * A pattern is "safe" iff the linear engine can compile it. Patterns it cannot
- * evaluate (invalid syntax, backreferences, lookarounds) are rejected at capture
- * (UNSAFE_TRIGGER_PATTERN) and skipped at read time — fail closed.
+ * evaluate are dead triggers: capture drops them (DEAD_COMMAND_PATTERN), the
+ * write barrier and validate flag stored ones (INVALID_/UNSAFE_TRIGGER_PATTERN),
+ * and recall skips them: fail closed.
  */
 
 /** True when `pattern` can be matched by the linear engine (no ReDoS risk). */