@jitsusama/agentic-harness.core 0.6.0 → 0.6.2

package/dist/attribution/commit-hook.d.ts

@@ -42,11 +42,14 @@ export interface HookInstall {
 export declare function installCommitHook(repoRoot: string, options: CommitHookOptions): HookInstall;
 /**
  * Ensure the hook is installed in the repo containing dir, at most
- * once per repo root. Resolves the repo, records it in `installed`
- * so later commands in the same repo are skipped, and installs
- * best-effort. A directory outside any git repo is a no-op. This is
- * how hook coverage follows the session into repos it later cds
- * into, rather than only the repo the session started in.
+ * once per repo. Records both dir and its repo root in `installed`,
+ * so a later command from either asks git nothing, and installs
+ * best-effort. A directory outside any git repo is a no-op and is
+ * not remembered, so a repo initialised there later is still
+ * covered. This is how hook coverage follows the session into repos
+ * it later cds into, rather than only the repo the session started
+ * in. Each git call is a synchronous spawn on the command path, so
+ * a first visit costs one and a repeat costs none.
  */
 export declare function ensureCommitHook(dir: string, installed: Set<string>, options: CommitHookOptions): void;
 /** The git repository root containing dir, or null when there is none. */

package/dist/attribution/commit-hook.js

@@ -46,20 +46,20 @@ git interpret-trailers --in-place --trailer ${options.trailerExpr} "$msg_file"
  * hook. A no-op when this adapter's hook is already installed.
  */
 export function installCommitHook(repoRoot, options) {
+    const layout = locateHooks(repoRoot);
+    if (!layout)
+        return { installed: false, reason: "not a git repo" };
+    return installInto(layout, options);
+}
+/** Install the hook into a repo whose hooks have been located. */
+function installInto({ hooksDir, customHooksPath }, options) {
     // A custom core.hooksPath means a hook manager (husky and the
     // like) or a shared, possibly version-controlled hooks directory
     // owns the hooks. Leave it alone rather than write this adapter's
     // hook into a directory it does not own.
-    if (hasCustomHooksPath(repoRoot)) {
+    if (customHooksPath) {
         return { installed: false, reason: "custom core.hooksPath configured" };
     }
-    let hooksDir;
-    try {
-        hooksDir = resolveHooksDir(repoRoot);
-    }
-    catch (error) {
-        return { installed: false, reason: `not a git repo: ${String(error)}` };
-    }
     const target = join(hooksDir, "prepare-commit-msg");
     if (existsSync(target) &&
         readFileSync(target, "utf8").includes(options.marker)) {
@@ -82,41 +82,66 @@ export function installCommitHook(repoRoot, options) {
     chmodSync(target, 0o755);
     return { installed: true };
 }
-/** Whether the repo configures a custom core.hooksPath. */
-function hasCustomHooksPath(repoRoot) {
-    try {
-        const value = execFileSync("git", ["-C", repoRoot, "config", "--get", "core.hooksPath"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-        return value.length > 0;
-    }
-    catch {
-        // git config exits non-zero when the key is unset: no custom path.
-        return false;
-    }
-}
 /**
  * Ensure the hook is installed in the repo containing dir, at most
- * once per repo root. Resolves the repo, records it in `installed`
- * so later commands in the same repo are skipped, and installs
- * best-effort. A directory outside any git repo is a no-op. This is
- * how hook coverage follows the session into repos it later cds
- * into, rather than only the repo the session started in.
+ * once per repo. Records both dir and its repo root in `installed`,
+ * so a later command from either asks git nothing, and installs
+ * best-effort. A directory outside any git repo is a no-op and is
+ * not remembered, so a repo initialised there later is still
+ * covered. This is how hook coverage follows the session into repos
+ * it later cds into, rather than only the repo the session started
+ * in. Each git call is a synchronous spawn on the command path, so
+ * a first visit costs one and a repeat costs none.
  */
 export function ensureCommitHook(dir, installed, options) {
-    const root = repoRootOf(dir);
-    if (!root || installed.has(root))
+    if (installed.has(dir))
+        return;
+    const layout = locateHooks(dir);
+    if (!layout)
         return;
-    installed.add(root);
+    installed.add(dir);
+    if (installed.has(layout.root))
+        return;
+    installed.add(layout.root);
     try {
-        installCommitHook(root, options);
+        installInto(layout, options);
     }
     catch {
         // Best-effort: never let hook installation break a command.
     }
 }
-/** Resolve the active hooks directory, honouring core.hooksPath. */
-function resolveHooksDir(repoRoot) {
-    const path = execFileSync("git", ["-C", repoRoot, "rev-parse", "--git-path", "hooks"], { encoding: "utf8" }).trim();
-    return isAbsolute(path) ? path : join(repoRoot, path);
+/**
+ * Locate the hooks of the repo containing dir with one git call, or
+ * null when dir is in no working tree. Git prints the default hooks
+ * path as the common dir plus `/hooks`, in the same form, so any
+ * other answer means core.hooksPath points somewhere else.
+ */
+function locateHooks(dir) {
+    let answer;
+    try {
+        answer = execFileSync("git", [
+            "-C",
+            dir,
+            "rev-parse",
+            "--show-toplevel",
+            "--git-common-dir",
+            "--git-path",
+            "hooks",
+        ], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    }
+    catch {
+        // Not in a working tree (or git unavailable): nothing to hook.
+        return null;
+    }
+    const [root, commonDir, hooks] = answer.trimEnd().split("\n");
+    if (!root || !commonDir || !hooks)
+        return null;
+    return {
+        root,
+        // Relative paths are relative to the directory git ran in.
+        hooksDir: isAbsolute(hooks) ? hooks : join(dir, hooks),
+        customHooksPath: hooks !== `${commonDir}/hooks`,
+    };
 }
 /** The git repository root containing dir, or null when there is none. */
 export function repoRootOf(dir) {

package/dist/internal/quest/process-liveness.d.ts

@@ -79,6 +79,11 @@ export declare function identityFromInspection(hostId: string, pid: number, insp
  * read a real start token: a session then carries no process identity
  * and its liveness falls back to recency, rather than a synthetic
  * token that a later probe would read as a dead mismatch.
+ *
+ * A process's own start token cannot change while it runs, so the
+ * first real reading is remembered: a session start attaches more
+ * than once and each reading is a synchronous `ps`. A failed reading
+ * is not remembered, so a transient failure is retried next time.
  */
 export declare function currentProcessIdentity(): ProcessIdentity | undefined;
 /**

package/dist/internal/quest/process-liveness.js

@@ -95,14 +95,26 @@ export function identityFromInspection(hostId, pid, inspection) {
         ? { hostId, pid, startToken: inspection.startToken }
         : undefined;
 }
+/** Memoized identity of this process, once one has been read. */
+let processIdentityCache;
 /**
  * Identity of the currently running pi process, for capture onto the
  * session it is attached to. Undefined when the OS reader could not
  * read a real start token: a session then carries no process identity
  * and its liveness falls back to recency, rather than a synthetic
  * token that a later probe would read as a dead mismatch.
+ *
+ * A process's own start token cannot change while it runs, so the
+ * first real reading is remembered: a session start attaches more
+ * than once and each reading is a synchronous `ps`. A failed reading
+ * is not remembered, so a transient failure is retried next time.
  */
 export function currentProcessIdentity() {
+    processIdentityCache ??= readProcessIdentity();
+    return processIdentityCache;
+}
+/** Read this process's identity from the OS. */
+function readProcessIdentity() {
     const identity = identityFromInspection(hostname(), process.pid, readStartToken(process.pid));
     if (!identity)
         return undefined;

package/dist/lsp/standalone/backend.d.ts

@@ -11,6 +11,12 @@
  * file. When nothing resolves, it fails with a clear message
  * rather than a cryptic one.
  *
+ * A server nobody has called for `idleMs` is stopped and dropped
+ * from the pool, and the next call for its root starts a fresh
+ * one: a TypeScript server holds hundreds of megabytes, and a long
+ * session touches many roots it never returns to. A call in
+ * flight keeps its servers alive however long it takes.
+ *
  * The live server pool lives in this closure's memory for the
  * life of the process that constructs it. A stateless-per-call
  * CLI adapter that wants warm servers across invocations needs
@@ -30,6 +36,8 @@ export interface StandaloneBackendOptions {
     readonly servers?: Readonly<Record<string, ServerConfig>>;
     /** Environment used for PATH resolution. Defaults to process.env. */
     readonly env?: NodeJS.ProcessEnv;
+    /** How long a server may sit unused before it is stopped. */
+    readonly idleMs?: number;
 }
 /** A standalone backend with visibility into its live pool. */
 export interface StandaloneBackend extends LspBackend {

package/dist/lsp/standalone/backend.js

@@ -11,6 +11,12 @@
  * file. When nothing resolves, it fails with a clear message
  * rather than a cryptic one.
  *
+ * A server nobody has called for `idleMs` is stopped and dropped
+ * from the pool, and the next call for its root starts a fresh
+ * one: a TypeScript server holds hundreds of megabytes, and a long
+ * session touches many roots it never returns to. A call in
+ * flight keeps its servers alive however long it takes.
+ *
  * The live server pool lives in this closure's memory for the
  * life of the process that constructs it. A stateless-per-call
  * CLI adapter that wants warm servers across invocations needs
@@ -28,20 +34,56 @@ export class MissingServerError extends Error {
         this.name = "MissingServerError";
     }
 }
+/**
+ * Default idle window. Long enough that a burst of work on one
+ * project keeps its server warm, short enough that a project left
+ * behind gives its memory back within the hour.
+ */
+const DEFAULT_IDLE_MS = 10 * 60_000;
 /** Construct a standalone backend over the given (or default) server map. */
 export function createStandaloneBackend(options = {}) {
     const servers = options.servers ?? DEFAULT_SERVERS;
     const env = options.env ?? process.env;
+    const idleMs = options.idleMs ?? DEFAULT_IDLE_MS;
     const pool = new Map();
+    // Calls in flight per pool key, and the stop timer armed when a
+    // key's last call finishes.
+    const inFlight = new Map();
+    const idleTimers = new Map();
     const poolKey = (name, root) => `${name}|${root}`;
+    const claim = (key) => {
+        inFlight.set(key, (inFlight.get(key) ?? 0) + 1);
+        clearTimeout(idleTimers.get(key));
+        idleTimers.delete(key);
+    };
+    const release = (key) => {
+        const left = (inFlight.get(key) ?? 1) - 1;
+        if (left > 0) {
+            inFlight.set(key, left);
+            return;
+        }
+        inFlight.delete(key);
+        const timer = setTimeout(() => stopIdle(key), idleMs);
+        // An idle server must never be what keeps the process alive.
+        timer.unref();
+        idleTimers.set(key, timer);
+    };
+    const stopIdle = (key) => {
+        idleTimers.delete(key);
+        if (inFlight.has(key))
+            return;
+        const started = pool.get(key);
+        pool.delete(key);
+        void started?.then((server) => server.dispose(), () => { });
+    };
     const instanceFor = (server, root, binary) => {
         const key = poolKey(server.name, root);
         const existing = pool.get(key);
         if (existing)
-            return existing;
+            return { key, started: existing };
         const started = StandaloneServer.start(server, root, binary);
         pool.set(key, started);
-        return started;
+        return { key, started };
     };
     // Resolve a server's effective command and args for a root. A
     // server with a `resolve` hook picks its binary per project (the
@@ -65,7 +107,22 @@ export function createStandaloneBackend(options = {}) {
             binary,
         };
     };
-    const resolveInstances = async (filePath, typeOnly) => {
+    /**
+     * Run fn against the servers for a file, holding each one's pool
+     * key claimed from before it resolves until fn settles, so no
+     * server is stopped under a call that is using it.
+     */
+    const withInstances = async (filePath, typeOnly, fn) => {
+        const claimed = [];
+        try {
+            return await fn(await resolveInstances(filePath, typeOnly, claimed));
+        }
+        finally {
+            for (const key of claimed)
+                release(key);
+        }
+    };
+    const resolveInstances = async (filePath, typeOnly, claimed) => {
         const candidates = serversForFile(filePath, servers).filter((server) => !typeOnly || !server.isLinter);
         const instances = [];
         const reasons = [];
@@ -80,7 +137,10 @@ export function createStandaloneBackend(options = {}) {
                 reasons.push(eff.reason);
                 continue;
             }
-            instances.push(await instanceFor(eff.config, root, eff.binary));
+            const { key, started } = instanceFor(eff.config, root, eff.binary);
+            claim(key);
+            claimed.push(key);
+            instances.push(await started);
             if (typeOnly)
                 break;
         }
@@ -95,40 +155,46 @@ export function createStandaloneBackend(options = {}) {
     return {
         name: "standalone",
         async diagnostics(path) {
-            const instances = await resolveInstances(path, false);
-            const results = await Promise.all(instances.map((s) => s.diagnose(path)));
-            return results.flat();
+            return withInstances(path, false, async (instances) => {
+                const results = await Promise.all(instances.map((s) => s.diagnose(path)));
+                return results.flat();
+            });
         },
         async definition(target) {
-            const [server] = await resolveInstances(target.path, true);
-            return server.definition(target);
+            return withInstances(target.path, true, ([server]) => server.definition(target));
         },
         async references(target) {
-            const [server] = await resolveInstances(target.path, true);
-            return server.references(target);
+            return withInstances(target.path, true, ([server]) => server.references(target));
         },
         async hover(target) {
-            const [server] = await resolveInstances(target.path, true);
-            return server.hover(target);
+            return withInstances(target.path, true, ([server]) => server.hover(target));
         },
         async documentSymbols(path) {
-            const [server] = await resolveInstances(path, true);
-            return server.documentSymbols(path);
+            return withInstances(path, true, ([server]) => server.documentSymbols(path));
         },
         async workspaceSymbols(query) {
             // Workspace symbols carry no file, so they search every
-            // server already running; nothing is spawned on demand.
-            const live = await Promise.all([...pool.values()]);
-            const results = await Promise.all(live.map((server) => server.workspaceSymbols(query)));
-            return results.flat();
+            // server already running; nothing is spawned on demand, and
+            // a server stopped for idleness is not searched until
+            // something file-bound starts it again.
+            const keys = [...pool.keys()];
+            for (const key of keys)
+                claim(key);
+            try {
+                const live = await Promise.all(keys.map((key) => pool.get(key)));
+                const results = await Promise.all(live.map((server) => server?.workspaceSymbols(query) ?? []));
+                return results.flat();
+            }
+            finally {
+                for (const key of keys)
+                    release(key);
+            }
         },
         async rename(target, newName) {
-            const [server] = await resolveInstances(target.path, true);
-            return server.rename(target, newName);
+            return withInstances(target.path, true, ([server]) => server.rename(target, newName));
         },
         async codeActions(path, range) {
-            const [server] = await resolveInstances(path, true);
-            return server.codeActions(path, range);
+            return withInstances(path, true, ([server]) => server.codeActions(path, range));
         },
         syncDocument(path, text) {
             for (const started of pool.values()) {
@@ -142,6 +208,9 @@ export function createStandaloneBackend(options = {}) {
             return pool.size;
         },
         async dispose() {
+            for (const timer of idleTimers.values())
+                clearTimeout(timer);
+            idleTimers.clear();
             const started = [...pool.values()];
             pool.clear();
             await Promise.all(started.map((s) => s.then((server) => server.dispose())));

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jitsusama/agentic-harness.core",
-	"version": "0.6.0",
+	"version": "0.6.2",
 	"description": "Pi-agnostic business logic for agentic-harness: state machines, guardian decisions, quest/TDD domain model.",
 	"license": "MIT",
 	"type": "module",