@phnx-labs/agents-cli 1.20.35 → 1.20.36

package/dist/lib/hosts/registry.js

@@ -6,6 +6,8 @@
  * `crabbox` later is a one-line `providers.set(...)` with no caller changes.
  */
 import { LocalHostProvider } from './providers/local.js';
+import { getDevice } from '../devices/registry.js';
+import { assertValidSshTarget } from '../ssh-exec.js';
 const providers = new Map();
 function initProviders() {
     if (providers.size > 0)
@@ -39,8 +41,54 @@ export async function listAllHosts() {
     return out;
 }
 /**
- * Resolve a host name to a single host across providers, or null if unknown.
- * First provider that owns the name wins (only `local` in v1).
+ * Thrown when a device resolves but can't be used as an offload target because
+ * it authenticates with a password. The offload path runs over `sshExec`, whose
+ * `SSH_OPTS` force `BatchMode=yes` (no password prompts), so only key / ssh-config
+ * auth can carry a `--host` run. Named so the top-level catch prints the message
+ * cleanly instead of a stack trace.
+ */
+export class DeviceOffloadUnsupportedError extends Error {
+    constructor(name) {
+        super(`Device "${name}" uses password auth, which --host offload can't use yet ` +
+            `(runs go over ssh with BatchMode=yes). Switch it to key auth with ` +
+            `\`agents devices set ${name} --auth key\`, or enroll it as a host with ` +
+            `\`agents hosts add ${name}\`.`);
+        this.name = 'DeviceOffloadUnsupportedError';
+    }
+}
+/**
+ * Bridge a registered device into a `Host` so `--host <device>` just works.
+ * A device's dnsName (preferred) or ip becomes the ssh address; `source: 'inline'`
+ * makes `sshTargetFor` emit `user@address`.
+ */
+function deviceToHost(device) {
+    if (device.auth.method === 'password') {
+        throw new DeviceOffloadUnsupportedError(device.name);
+    }
+    const address = device.address.dnsName ?? device.address.ip;
+    if (!address) {
+        throw new Error(`Device "${device.name}" has no address (Tailscale DNS name or IP) to reach it by.`);
+    }
+    return {
+        name: device.name,
+        provider: 'local',
+        source: 'inline',
+        address,
+        user: device.user,
+        ...(device.platform !== 'unknown' ? { os: device.platform } : {}),
+        enrolled: true,
+    };
+}
+/**
+ * Resolve a host name to a single host, or null if unknown. Resolution order:
+ *   1. host providers — the `agents hosts` registry (agents.yaml overlay + ssh-config)
+ *   2. the devices registry (`agents devices`) — a machine registered once with
+ *      `agents devices sync` is reachable by `--host`/`--device` with no second enroll
+ *   3. an ad-hoc `user@host` (must contain `@`, validated) — nothing to register
+ *
+ * A bare unknown name returns null so capability-tag routing (`resolveHostByCap`)
+ * stays reachable: `--host gpu` must fall through to a cap lookup, not be misread
+ * as an ad-hoc target.
  */
 export async function resolveHost(name) {
     for (const provider of getAllProviders()) {
@@ -48,6 +96,14 @@ export async function resolveHost(name) {
         if (host)
             return host;
     }
+    const device = await getDevice(name);
+    if (device)
+        return deviceToHost(device);
+    if (name.includes('@')) {
+        assertValidSshTarget(name);
+        const at = name.indexOf('@');
+        return { name, provider: 'local', source: 'inline', user: name.slice(0, at), address: name.slice(at + 1) };
+    }
     return null;
 }
 /**

package/dist/lib/hosts/remote-cmd.d.ts

@@ -32,5 +32,66 @@ export declare const HOST_ROUTING_SPECS: StripSpec[];
  * are quoted for the inner login shell, then the whole `agents …` invocation is
  * quoted again so it survives `bash -lc <...>` — `bash -lc` so the remote login
  * PATH resolves `agents`. An optional `cd` runs first for `--remote-cwd`.
+ *
+ * `os` selects the remote shell dialect: a Windows target gets a PowerShell
+ * invocation instead (ssh lands in cmd.exe/PowerShell there, where `bash -lc`
+ * does not exist). Anything else — including an unknown/absent OS — keeps the
+ * POSIX form, so linux/macos are byte-for-byte unchanged.
+ */
+export declare function buildRemoteAgentsInvocation(forwardedArgs: string[], remoteCwd?: string, os?: string): string;
+/** The two remote shell dialects we build commands for. */
+export type RemoteShell = 'posix' | 'powershell';
+/**
+ * Pick the remote shell dialect from a recorded OS/platform string. A Windows
+ * host (device-registry `platform: 'windows'`, or an enrolled `HostEntry.os`
+ * that reads `windows`/`Windows`/`win32`/…) speaks PowerShell; everything else,
+ * including `undefined`/unknown, defaults to POSIX so linux/macos never regress.
+ */
+export declare function remoteShellFor(os: string | undefined): RemoteShell;
+/**
+ * PowerShell single-quoted literal: wrap in `'…'` and double any embedded `'`.
+ * Single-quoted PS strings are fully literal (no `$var`, no backtick escapes),
+ * so this neutralises every metacharacter the same way POSIX `shellQuote` does.
+ */
+export declare function powershellQuote(s: string): string;
+/**
+ * Encode a PowerShell script for `powershell -EncodedCommand`: base64 of its
+ * UTF-16LE bytes. The payload is a bare base64 word (no spaces or shell
+ * metacharacters), so it survives being handed to ssh as a single argument and
+ * re-parsed by the remote's cmd.exe/PowerShell with zero quoting hazards —
+ * the robust way to ship a complex command to a Windows box over SSH.
+ */
+export declare function encodePowershell(script: string): string;
+/** Inverse of {@link encodePowershell} — decode an `-EncodedCommand` payload
+ * back to its script. Used by tests to assert on the built command. */
+export declare function decodePowershell(encoded: string): string;
+/** A single `agents …` invocation to run on a Windows remote. */
+export interface WindowsAgentsCommand {
+    /** `agents` argv (command name NOT included; `agents` is prepended). */
+    args: string[];
+    /** Env vars scoped to this invocation (POSIX `VAR=val` ↔ PS `$env:VAR=…`). */
+    env?: Record<string, string>;
+    /** Directory to enter before running (`--remote-cwd`). */
+    cwd?: string;
+    /**
+     * Append `exit $LASTEXITCODE` so a native `agents` exit code propagates out
+     * through `powershell.exe` (which otherwise exits 0 regardless). Default true;
+     * pass false for probes whose reachability keys off a sentinel, not the code.
+     */
+    propagateExit?: boolean;
+}
+/**
+ * The PowerShell script (pre-encoding) that {@link buildWindowsAgentsCommand}
+ * runs. Exposed so tests can decode the `-EncodedCommand` payload and compare
+ * against the exact script, without needing PowerShell on the test host.
+ *
+ * `& agents …` invokes the CLI from the machine PATH (Windows has no login
+ * shell, so there is no `bash -lc` equivalent — the shim is simply on PATH).
+ */
+export declare function windowsAgentsScript(cmd: WindowsAgentsCommand): string;
+/**
+ * Build the `ssh <target> <cmd>` string for one `agents …` invocation on a
+ * Windows remote: a `powershell -NoProfile -EncodedCommand <base64>` call. The
+ * Windows counterpart of `bash -lc '<...>'`, shared by every `--host` site.
  */
-export declare function buildRemoteAgentsInvocation(forwardedArgs: string[], remoteCwd?: string): string;
+export declare function buildWindowsAgentsCommand(cmd: WindowsAgentsCommand): string;

package/dist/lib/hosts/remote-cmd.js

@@ -48,9 +48,78 @@ export const HOST_ROUTING_SPECS = [
  * are quoted for the inner login shell, then the whole `agents …` invocation is
  * quoted again so it survives `bash -lc <...>` — `bash -lc` so the remote login
  * PATH resolves `agents`. An optional `cd` runs first for `--remote-cwd`.
+ *
+ * `os` selects the remote shell dialect: a Windows target gets a PowerShell
+ * invocation instead (ssh lands in cmd.exe/PowerShell there, where `bash -lc`
+ * does not exist). Anything else — including an unknown/absent OS — keeps the
+ * POSIX form, so linux/macos are byte-for-byte unchanged.
  */
-export function buildRemoteAgentsInvocation(forwardedArgs, remoteCwd) {
+export function buildRemoteAgentsInvocation(forwardedArgs, remoteCwd, os) {
+    if (remoteShellFor(os) === 'powershell') {
+        return buildWindowsAgentsCommand({ args: forwardedArgs, cwd: remoteCwd });
+    }
     const inner = ['agents', ...forwardedArgs].map(shellQuote).join(' ');
     const withCwd = remoteCwd ? `cd ${shellQuote(remoteCwd)} && ${inner}` : inner;
     return `bash -lc ${shellQuote(withCwd)}`;
 }
+/**
+ * Pick the remote shell dialect from a recorded OS/platform string. A Windows
+ * host (device-registry `platform: 'windows'`, or an enrolled `HostEntry.os`
+ * that reads `windows`/`Windows`/`win32`/…) speaks PowerShell; everything else,
+ * including `undefined`/unknown, defaults to POSIX so linux/macos never regress.
+ */
+export function remoteShellFor(os) {
+    return /^win/i.test((os ?? '').trim()) ? 'powershell' : 'posix';
+}
+/**
+ * PowerShell single-quoted literal: wrap in `'…'` and double any embedded `'`.
+ * Single-quoted PS strings are fully literal (no `$var`, no backtick escapes),
+ * so this neutralises every metacharacter the same way POSIX `shellQuote` does.
+ */
+export function powershellQuote(s) {
+    return "'" + s.replace(/'/g, "''") + "'";
+}
+/**
+ * Encode a PowerShell script for `powershell -EncodedCommand`: base64 of its
+ * UTF-16LE bytes. The payload is a bare base64 word (no spaces or shell
+ * metacharacters), so it survives being handed to ssh as a single argument and
+ * re-parsed by the remote's cmd.exe/PowerShell with zero quoting hazards —
+ * the robust way to ship a complex command to a Windows box over SSH.
+ */
+export function encodePowershell(script) {
+    return Buffer.from(script, 'utf16le').toString('base64');
+}
+/** Inverse of {@link encodePowershell} — decode an `-EncodedCommand` payload
+ * back to its script. Used by tests to assert on the built command. */
+export function decodePowershell(encoded) {
+    return Buffer.from(encoded, 'base64').toString('utf16le');
+}
+/**
+ * The PowerShell script (pre-encoding) that {@link buildWindowsAgentsCommand}
+ * runs. Exposed so tests can decode the `-EncodedCommand` payload and compare
+ * against the exact script, without needing PowerShell on the test host.
+ *
+ * `& agents …` invokes the CLI from the machine PATH (Windows has no login
+ * shell, so there is no `bash -lc` equivalent — the shim is simply on PATH).
+ */
+export function windowsAgentsScript(cmd) {
+    const { args, env, cwd, propagateExit = true } = cmd;
+    const parts = [];
+    if (env)
+        for (const [k, v] of Object.entries(env))
+            parts.push(`$env:${k} = ${powershellQuote(v)}`);
+    if (cwd)
+        parts.push(`Set-Location -LiteralPath ${powershellQuote(cwd)}`);
+    parts.push(`& ${['agents', ...args].map(powershellQuote).join(' ')}`);
+    if (propagateExit)
+        parts.push('exit $LASTEXITCODE');
+    return parts.join('; ');
+}
+/**
+ * Build the `ssh <target> <cmd>` string for one `agents …` invocation on a
+ * Windows remote: a `powershell -NoProfile -EncodedCommand <base64>` call. The
+ * Windows counterpart of `bash -lc '<...>'`, shared by every `--host` site.
+ */
+export function buildWindowsAgentsCommand(cmd) {
+    return `powershell -NoProfile -EncodedCommand ${encodePowershell(windowsAgentsScript(cmd))}`;
+}

package/dist/lib/hosts/remote-os.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Resolve a remote host's OS family so the SSH command layer can pick the right
+ * shell dialect (POSIX `bash -lc` vs Windows PowerShell). See `remoteShellFor`
+ * in `remote-cmd.ts` for how the string is consumed.
+ *
+ * Two sources, in priority order:
+ *   1. The device registry `platform` (`windows`/`linux`/`macos`), which is
+ *      populated fleet-wide by Tailscale sync — the reliable answer for a box
+ *      like `win-mini` that was discovered, not hand-enrolled.
+ *   2. The enrolled `HostEntry.os` overlay in agents.yaml (the `uname` captured
+ *      at `agents hosts add` time), for hosts that live only in that overlay.
+ *
+ * Missing/unknown from both → `undefined`, which `remoteShellFor` maps to POSIX.
+ * Kept synchronous so the sync `agents sessions --host` fan-out can use it.
+ */
+/** Resolve the OS/platform string for a host name, or undefined if unknown. */
+export declare function resolveRemoteOsSync(name: string): string | undefined;

package/dist/lib/hosts/remote-os.js

@@ -0,0 +1,30 @@
+/**
+ * Resolve a remote host's OS family so the SSH command layer can pick the right
+ * shell dialect (POSIX `bash -lc` vs Windows PowerShell). See `remoteShellFor`
+ * in `remote-cmd.ts` for how the string is consumed.
+ *
+ * Two sources, in priority order:
+ *   1. The device registry `platform` (`windows`/`linux`/`macos`), which is
+ *      populated fleet-wide by Tailscale sync — the reliable answer for a box
+ *      like `win-mini` that was discovered, not hand-enrolled.
+ *   2. The enrolled `HostEntry.os` overlay in agents.yaml (the `uname` captured
+ *      at `agents hosts add` time), for hosts that live only in that overlay.
+ *
+ * Missing/unknown from both → `undefined`, which `remoteShellFor` maps to POSIX.
+ * Kept synchronous so the sync `agents sessions --host` fan-out can use it.
+ */
+import { loadDevicesSync } from '../devices/registry.js';
+import { readMeta } from '../state.js';
+/** Resolve the OS/platform string for a host name, or undefined if unknown. */
+export function resolveRemoteOsSync(name) {
+    try {
+        const platform = loadDevicesSync()[name]?.platform;
+        if (platform && platform !== 'unknown')
+            return platform;
+    }
+    catch {
+        // A corrupt/unreadable device registry must never break command building —
+        // fall through to the host overlay and ultimately the POSIX default.
+    }
+    return readMeta().hosts?.[name]?.os;
+}

package/dist/lib/hosts/session-index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Register host-dispatched runs (`agents run --host <h>`) into the LOCAL session
+ * index so they show up in `agents sessions` and are resolvable by id — even
+ * though the transcript itself lives on the remote host.
+ *
+ * The transcript file is remote, so the row is registered with an EMPTY
+ * `file_path`. The DB's stale-row filter keeps rows with no file_path
+ * (`!file_path || existsSync(file_path)` in db.ts querySessions) precisely for
+ * this "synthetic file_path" case, and the scanner never prunes session rows —
+ * so the entry survives rescans. `cwd` is the LOCAL directory the dispatch was
+ * issued from, so the run appears in that project's session listing like any
+ * local run. The `[host/<name>]` label mirrors the cloud path's
+ * `[cloud/<status>]` convention.
+ */
+import type { SessionMeta } from '../session/types.js';
+import type { HostTask } from './tasks.js';
+export interface HostSessionContext {
+    /** Local directory the `agents run --host` was invoked from. */
+    cwd: string;
+    /** Prompt the run was launched with, used for the session topic. */
+    prompt: string;
+}
+/**
+ * Build the SessionMeta for a host-dispatched run. Returns null when the run has
+ * no captured session id (nothing stable to key/resume on) or its agent isn't a
+ * known session agent. Pure — no I/O — so the mapping is unit-testable.
+ */
+export declare function hostSessionMeta(task: HostTask, ctx: HostSessionContext): SessionMeta | null;
+/**
+ * Register (or refresh) a host-dispatched run in the local session index. No-op
+ * when the task carries no session id. Best-effort: a failed write must never
+ * break the dispatch itself, which has already been launched on the host.
+ */
+export declare function registerHostSession(task: HostTask, ctx: HostSessionContext): void;

package/dist/lib/hosts/session-index.js

@@ -0,0 +1,56 @@
+/**
+ * Register host-dispatched runs (`agents run --host <h>`) into the LOCAL session
+ * index so they show up in `agents sessions` and are resolvable by id — even
+ * though the transcript itself lives on the remote host.
+ *
+ * The transcript file is remote, so the row is registered with an EMPTY
+ * `file_path`. The DB's stale-row filter keeps rows with no file_path
+ * (`!file_path || existsSync(file_path)` in db.ts querySessions) precisely for
+ * this "synthetic file_path" case, and the scanner never prunes session rows —
+ * so the entry survives rescans. `cwd` is the LOCAL directory the dispatch was
+ * issued from, so the run appears in that project's session listing like any
+ * local run. The `[host/<name>]` label mirrors the cloud path's
+ * `[cloud/<status>]` convention.
+ */
+import { upsertSession } from '../session/db.js';
+import { SESSION_AGENTS } from '../session/types.js';
+/**
+ * Build the SessionMeta for a host-dispatched run. Returns null when the run has
+ * no captured session id (nothing stable to key/resume on) or its agent isn't a
+ * known session agent. Pure — no I/O — so the mapping is unit-testable.
+ */
+export function hostSessionMeta(task, ctx) {
+    const id = task.sessionId;
+    if (!id)
+        return null;
+    if (!SESSION_AGENTS.includes(task.agent))
+        return null;
+    return {
+        id,
+        shortId: id.slice(0, 8),
+        agent: task.agent,
+        timestamp: task.createdAt,
+        cwd: ctx.cwd,
+        // Remote transcript — no local file. Empty file_path is the sentinel the DB
+        // stale-filter treats as "always live" (see module doc).
+        filePath: '',
+        topic: ctx.prompt.split('\n')[0]?.slice(0, 120) || undefined,
+        label: `[host/${task.host}]`,
+    };
+}
+/**
+ * Register (or refresh) a host-dispatched run in the local session index. No-op
+ * when the task carries no session id. Best-effort: a failed write must never
+ * break the dispatch itself, which has already been launched on the host.
+ */
+export function registerHostSession(task, ctx) {
+    const meta = hostSessionMeta(task, ctx);
+    if (!meta)
+        return;
+    try {
+        upsertSession(meta, '');
+    }
+    catch {
+        /* index write is best-effort; the run is already live on the host */
+    }
+}

package/dist/lib/hosts/tasks.d.ts

@@ -15,6 +15,13 @@ export interface HostTask {
     agent: string;
     prompt: string;
     pid?: number;
+    /**
+     * The agent session id the remote run was launched with (Claude only — the
+     * only agent that accepts `--session-id` to force a NEW session's id). Lets
+     * `agents sessions`/resume-by-id map a discovered session back to the host it
+     * lives on. Absent for agents that don't take an explicit session id.
+     */
+    sessionId?: string;
     /** Remote paths (under the host's ~/.agents/.cache/hosts/). */
     remoteLog: string;
     remoteExit: string;
@@ -38,3 +45,10 @@ export declare function updateTask(id: string, patch: Partial<HostTask>): HostTa
  */
 export declare function terminalPatch(code: number): Partial<HostTask>;
 export declare function listTasks(): HostTask[];
+/**
+ * Find the host task that launched a given agent session id, so a resume-by-id
+ * can re-dispatch to the host the session actually lives on. Newest task wins
+ * (listTasks is createdAt-desc) — a session id should be unique, but a re-run
+ * with the same forced id resolves to the most recent dispatch.
+ */
+export declare function findTaskBySessionId(sessionId: string): HostTask | null;

package/dist/lib/hosts/tasks.js

@@ -70,3 +70,18 @@ export function listTasks() {
     }
     return tasks.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
 }
+/**
+ * Find the host task that launched a given agent session id, so a resume-by-id
+ * can re-dispatch to the host the session actually lives on. Newest task wins
+ * (listTasks is createdAt-desc) — a session id should be unique, but a re-run
+ * with the same forced id resolves to the most recent dispatch.
+ */
+export function findTaskBySessionId(sessionId) {
+    if (!sessionId)
+        return null;
+    for (const task of listTasks()) {
+        if (task.sessionId === sessionId)
+            return task;
+    }
+    return null;
+}

package/dist/lib/lock.d.ts

@@ -0,0 +1,93 @@
+/**
+ * `agents.lock` — a deterministic SHA-256 manifest of the resolved resource set
+ * at a project root, plus the `--frozen` verification that fails closed on any
+ * drift. This is the reproducible-CI slice of the governance work (#337); org
+ * version pins and bundle signing are deferred follow-ups.
+ *
+ * Design:
+ *  - Content hashing REUSES `fingerprintDir` / `fingerprintFile`
+ *    (src/lib/staleness/fingerprint.ts) — the same two-tier fingerprinter every
+ *    staleness checker uses. No new recursive file walker is introduced here.
+ *  - The resource SET is the layered, resolved source union (project > user >
+ *    system > extras), the same precedence `resolveResource` / `syncResourcesToVersion`
+ *    read from. It is enumerated agent-independently on purpose: the lock must be
+ *    reproducible on a fresh CI checkout that has no installed agent VERSIONS, so
+ *    it snapshots the SOURCES sync copies FROM, not any per-version home.
+ *
+ * Lock shape (JSON): `{ "version": 1, "resources": { "<relpath>": "<sha256>" } }`,
+ * keys sorted so the file is byte-stable across machines and runs.
+ */
+export declare const LOCK_FILENAME = "agents.lock";
+export declare const LOCK_VERSION: 1;
+/**
+ * Resource kinds captured by the lock — the file/dir-backed layered resources
+ * shared across every agent. Presence-only kinds handled specially by the sync
+ * differ (plugins/promptcuts) are intentionally out of this first slice.
+ */
+export declare const LOCK_KINDS: readonly ["commands", "skills", "hooks", "rules", "mcp", "permissions", "subagents"];
+/** The on-disk lockfile: relpath -> sha256 hex digest, keys sorted. */
+export interface AgentsLock {
+    version: typeof LOCK_VERSION;
+    resources: Record<string, string>;
+}
+/**
+ * One resolved resource to fingerprint. `path` is an absolute file or directory;
+ * `key` is the stable relpath prefix under which its hashes are recorded
+ * (e.g. `skills/debug` for a directory, `commands/plan.md` for a single file).
+ */
+export interface LockSource {
+    path: string;
+    key: string;
+}
+/** Added/removed/changed keys between an expected lock and the live resources. */
+export interface LockDiff {
+    /** Present in the live resources, absent from the lock. */
+    added: string[];
+    /** Present in the lock, absent from the live resources. */
+    removed: string[];
+    /** Present in both but the sha256 differs. */
+    changed: string[];
+}
+/**
+ * Hash every resolved source into a flat `relpath -> sha256` map. Directories are
+ * expanded with `fingerprintDir` (every contained file, sorted); single files use
+ * `fingerprintFile`. Unreadable / missing sources are skipped — enumeration only
+ * ever hands us paths that existed at scan time.
+ */
+export declare function hashLockSources(sources: LockSource[]): Record<string, string>;
+/** Build a fully-sorted lock object from a resolved source set. */
+export declare function buildLock(sources: LockSource[]): AgentsLock;
+/** Serialise a lock to the canonical, sorted, newline-terminated JSON form. */
+export declare function serializeLock(lock: AgentsLock): string;
+/** Absolute path to the lockfile for a project root. */
+export declare function lockPath(projectRoot: string): string;
+/**
+ * Read + validate an existing lock. Returns null ONLY when the file is absent —
+ * a present-but-malformed lock throws, so `--frozen` fails closed instead of
+ * silently treating corruption as "no lock".
+ */
+export declare function readLock(projectRoot: string): AgentsLock | null;
+/** Write the lock to `<projectRoot>/agents.lock`, returning the path written. */
+export declare function writeLock(projectRoot: string, lock: AgentsLock): string;
+/** Diff a recorded lock against a freshly-computed one. */
+export declare function diffLock(expected: AgentsLock, actual: AgentsLock): LockDiff;
+/** True when a diff has no added/removed/changed entries. */
+export declare function lockDiffIsClean(diff: LockDiff): boolean;
+/** Verify a recorded lock against the live resolved sources. */
+export declare function verifyLock(expected: AgentsLock, sources: LockSource[]): LockDiff;
+/**
+ * The project root the lockfile lives at: the parent of the discovered project
+ * `.agents/` dir, or the cwd itself when none is found.
+ */
+export declare function resolveProjectRoot(cwd?: string): string;
+/**
+ * Enumerate the resolved resource sources for a cwd: for each lockable kind, the
+ * winning entry per name across layers (project > user > system > extras), keyed
+ * `<kind>/<entryName>`. This is a single-level `readdir` per kind dir — the
+ * recursive fingerprinting is delegated to `fingerprintDir`.
+ *
+ * Entry names keep their extension in the key, so a hook script `foo.sh` and its
+ * sidecar `foo.yaml` stay distinct (a name-stripped enumerator would collide
+ * them). Dotfiles at the kind-dir top level are skipped as noise.
+ */
+export declare function enumerateLockSources(cwd?: string): LockSource[];