@aroman22/codegraph-vba 1.15.0 → 1.16.0

package/dist/extraction/vba/sql-wrapper.d.ts

@@ -1,7 +1,68 @@
-import { VbaExtractorContext } from './context';
-export declare function scanSqlInLine(ctx: VbaExtractorContext, line: string, lineNum: number, dedupe: Set<string>, sqlVariables: Map<string, string>): void;
+import { VbaExtractorContext, ProcInfo } from './context';
 /**
- * #13 fix: `sql = sql & "..."` (self-referential concatenation) must
+ * Issue #252 — `metadata.synthesizedBy` for a table reached through SQL
+ * assigned to a binding property at RUNTIME. Deliberately distinct from the
+ * `.form.txt` sweep's static `vba-row-source` so an audit can tell the two
+ * provenances apart: one is what the designer stored, the other is what the
+ * code actually binds.
+ */
+export declare const RUNTIME_BINDING_SYNTHESIZER = "vba-row-source-dynamic";
+/**
+ * Issue #244 — the wrapper list used when `codegraph.json` →
+ * `vba.sqlWrappers` is absent. A STRICT SUPERSET of the pre-#244 behaviour:
+ *
+ *   - `db` covers every receiver the old `…db\b` regex reached (see
+ *     {@link receiverMatches} for the suffix arm that preserves it) plus the
+ *     `db`-prefixed locals it missed (`dbUse`, `dbToUse`, `m_dbLanzadera`).
+ *   - `getdb` covers the per-backend accessor family (`getdbHPS()`,
+ *     `getdbExpedientes()`, `getdbLanzadera()`) the issue measured at 26-36%
+ *     of all execution sites.
+ *   - `CurrentDb` / `DBEngine` are the Access built-ins.
+ *   - `qd` / `qdf` are the conventional DAO `QueryDef` receivers.
+ *   - `DoCmd.RunSQL` is the Access statement form (both the literal and the
+ *     variable spelling, previously two dedicated regexes).
+ *   - `Connection.Execute` / `Recordset.Open` are the ADO pair.
+ *
+ * Project-specific accessors that do not fit these names are added through
+ * `vba.sqlWrappers`, which EXTENDS this list rather than replacing it.
+ */
+export declare const DEFAULT_SQL_WRAPPERS: readonly string[];
+/** One parsed wrapper entry. Both fields are lowercase — VBA is case-insensitive. */
+interface SqlWrapperMatcher {
+    /** Receiver name fragment, e.g. `getdb` from `"getdb"` or `cnn` from `"cnn.Execute"`. */
+    receiver: string;
+    /** Method name, or `null` for a bare entry (which implies {@link DEFAULT_WRAPPER_METHODS}). */
+    method: string | null;
+}
+/**
+ * The per-extractor compiled wrapper state. Built ONCE per `VbaExtractor`
+ * (see `vba-extractor.ts`) and cached on `VbaExtractorContext` — the two
+ * RegExps are stateful (`/g`) and `scanSqlInLine` runs on every line of every
+ * file, so re-compiling them per line (which is what the pre-#244 code did)
+ * is pure waste on the hottest path in VBA extraction.
+ */
+export interface CompiledSqlWrappers {
+    /** Literal form — `<receiver>[()].<method> "…"`. Stateful; reset before use. */
+    readonly literalRe: RegExp;
+    /** Variable form — `<receiver>[()].<method> <identifier>`. Stateful; reset before use. */
+    readonly varRe: RegExp;
+    /** Parsed entries, defaults first, project entries appended. */
+    readonly matchers: readonly SqlWrapperMatcher[];
+}
+/**
+ * Parse the plain-string wrapper entries into matchers and pair them with a
+ * fresh pair of scanning RegExps.
+ *
+ * `configured` entries are APPENDED to {@link DEFAULT_SQL_WRAPPERS}, never
+ * substituted for them: a project that names its own accessor must not lose
+ * `CurrentDb` in the trade. Entries are accepted in exactly two forms — a
+ * bare identifier fragment (`"getdb"`) or a `receiver.method` pair
+ * (`"cnn.Execute"`). Anything else is dropped here; `project-config.ts`
+ * already warned about it at load time.
+ */
+export declare function compileSqlWrappers(configured?: readonly string[]): CompiledSqlWrappers;
+/**
+ * Issue #13: `sql = sql & "..."` (self-referential concatenation) must
  * ACCUMULATE the new fragment onto whatever was already tracked for
  * `varName`, not overwrite it. Overwriting silently dropped earlier
  * fragments' tables — typically the initial `FROM <table>` in
@@ -14,4 +75,16 @@ export declare function scanSqlInLine(ctx: VbaExtractorContext, line: string, li
  * behavior is unchanged.
  */
 export declare function trackSqlVariableAssignment(lines: string[], lineIndex: number, sqlVariables: Map<string, string>): void;
+/**
+ * Issue #255: scan one line for domain-aggregate calls and emit the saved-query
+ * reference their second argument names.
+ *
+ * Deliberately NOT handled: a domain spelled as a full SQL statement
+ * (`DLookup("N", "SELECT Id FROM T")`), which Access also accepts. It is
+ * rejected by `looksLikeSavedQueryName`'s verb gate and produces nothing —
+ * the same silence T11 chose for every literal it cannot classify.
+ */
+export declare function scanDomainFunctionsInLine(ctx: VbaExtractorContext, line: string, lineNum: number, dedupe: Set<string>, caller: ProcInfo): void;
+export declare function scanSqlInLine(ctx: VbaExtractorContext, line: string, lineNum: number, dedupe: Set<string>, sqlVariables: Map<string, string>, caller?: ProcInfo): void;
+export {};
 //# sourceMappingURL=sql-wrapper.d.ts.map

package/dist/extraction/vba/text-utils.d.ts

@@ -11,8 +11,17 @@ export declare function foldVisibility(raw: string): 'public' | 'private';
  * call-site patterns inside `"..."` spans are invisible to CALL_RE and
  * the statement-form detectors.  Column positions are preserved (each
  * character is replaced 1-for-1) so any col-based metadata stays correct.
+ *
+ * Issue #265: `filler` selects the replacement character. The default `' '`
+ * is what every column-sensitive scanner wants — a masked literal reads as
+ * blank space. The statement-call detectors need the opposite: they must
+ * still be able to tell `MsgBox "x"` (an argument list, therefore
+ * unambiguously a call) from a bare `MsgBox` read, and a space-masked line
+ * collapses the two. Passing `'_'` keeps the literal *visible* as an opaque
+ * token while preserving both the 1-for-1 column mapping and the property
+ * that nothing inside the literal can be parsed as VBA syntax.
  */
-export declare function maskStringContent(line: string): string;
+export declare function maskStringContent(line: string, filler?: string): string;
 /**
  * #13 helper: escape a variable name for safe interpolation into the
  * self-reference RegExp built by `trackSqlVariableAssignment`. VBA
@@ -26,7 +35,6 @@ export declare function parseConstDeclarations(body: string): Array<{
     asType: string;
     value: string | null;
 }>;
-export declare function splitOutsideVbaStrings(value: string, separator: string): string[];
 /**
  * Issue #50 helper: return true iff `line.charAt(fromIndex..)` (after the
  * matched TempVars site, including any trailing whitespace) holds an `=`
@@ -65,4 +73,56 @@ export declare function parseEventHandlerName(name: string): {
     controlName: string;
     eventName: string;
 } | null;
+/**
+ * Issue #247 helper: parse a FORM-LEVEL Access event-handler Sub name.
+ *
+ * `parseEventHandlerName` above deliberately refuses `Form_*` because a
+ * form-level event fires on the form object, not on a control — routing it
+ * through the control path would synthesize a bogus `form-instance-control`
+ * node literally named `Form`. This helper is the other half of that
+ * decision: it recognises exactly the names the control parser rejects and
+ * hands them to the caller so they can be wired to the sibling
+ * `form-layout` / `report-layout` node instead.
+ *
+ * The owner segment must be exactly `Form` or `Report` (case-insensitive,
+ * matching VBA's case-insensitive identifiers), and the suffix must be a
+ * known Access event name. That second gate is what separates the real
+ * lifecycle handler `Form_Load` from an ordinary class method that merely
+ * happens to be called `Form_Helper`.
+ */
+export declare function parseFormLevelEventHandlerName(name: string): {
+    ownerName: string;
+    eventName: string;
+} | null;
+/**
+ * Sibling layout extension implied by an Access code-behind prefix.
+ * `Form_*` binds to a `.form.txt`; `Report_*` binds to a `.report.txt`.
+ */
+export type CodeBehindExt = '.form.txt' | '.report.txt';
+/**
+ * Issue #249 helper: the `Form_` / `Report_` code-behind prefix carried by a
+ * module's RESOLVED `Attribute VB_Name`, used as the fallback when the file
+ * on disk does not carry the prefix in its basename.
+ *
+ * Both binding sites (the event-handler synthesis in `procedures.ts` and the
+ * `Me.<Control>` sweep in `controls.ts`) keep their own basename check as the
+ * fast path and consult this only on a basename miss, so the common case —
+ * a Dysflow export whose filename and `VB_Name` agree — is byte-for-byte
+ * unchanged.
+ *
+ * `classNamePrefix` is `null` for `.bas` modules and holds the resolved
+ * `VB_Name` (or the extension-stripped basename when the module carries no
+ * `VB_Name`) for `.cls` modules, so this fallback can only ever fire for a
+ * class module. That is deliberate: the guard that keeps a plain service
+ * class such as `InformeRiesgoPDFServicio.cls` — whose methods
+ * (`GenerarHTML_Principal`, `GetEstilosCSS_PDF`) look like event handlers to
+ * a naive `<X>_<Y>` split — from synthesizing hundreds of spurious
+ * `form-instance-control` stubs is that NEITHER its filename NOR its
+ * `VB_Name` starts with `Form_` / `Report_`. Widening the prefix test would
+ * reopen exactly that hole, so the test stays the same canonical Access
+ * naming convention; only the string it is applied to widens.
+ *
+ * The trailing `.+` is load-bearing: a bare `Form_` names no form.
+ */
+export declare function codeBehindExtFromVbName(classNamePrefix: string | null): CodeBehindExt | null;
 //# sourceMappingURL=text-utils.d.ts.map

package/dist/extraction/vba-extractor.d.ts

@@ -1,4 +1,5 @@
 import { ExtractionResult } from '../types';
+import type { VbaExtractionOptions } from './vba/options';
 import type { VbaExtractionRule } from './vba/rules';
 /**
  * Issue #152: per-file fanout cap for `RaiseEvent <EventName>` edges. An
@@ -62,7 +63,6 @@ export declare class VbaExtractor {
     private filePath;
     private source;
     private ctx;
-    private vbaTargets?;
     /**
      * Issue #152: per-file fanout cap for `RaiseEvent <EventName>` edges.
      * When a single event is raised more than this many times in one file,
@@ -72,6 +72,23 @@ export declare class VbaExtractor {
      * the orchestrator: callers that don't pass a value get the default.
      */
     private maxRaiseFanout;
+    /**
+     * Issue #243: the full options object, retained so classifiers that grow
+     * a new knob read it from one place instead of a new private field per
+     * knob. `targets`/`maxRaiseFanout` keep their dedicated fields because
+     * they are read on hot paths.
+     */
+    private options;
+    /**
+     * Issue #243 — the options-object form. Every in-repo call site uses this.
+     */
+    constructor(filePath: string, source: string, options?: VbaExtractionOptions);
+    /**
+     * @deprecated Pass a {@link VbaExtractionOptions} object instead:
+     * `new VbaExtractor(filePath, source, { targets, maxRaiseFanout })`.
+     * The positional 3rd/4th parameters are kept working for one release so
+     * out-of-repo callers are not broken by #243; they will be removed after.
+     */
     constructor(filePath: string, source: string, vbaTargets?: Record<string, boolean>, maxRaiseFanout?: number);
     extract(): ExtractionResult;
     /**

package/dist/extraction/vba-form-extractor.d.ts

@@ -17,6 +17,14 @@ export declare class VbaFormExtractor {
      * stays self-contained per the project's per-extractor state rule).
      */
     private synthClassNodeIds;
+    /**
+     * Issue #256: external-backend (`IN "<path>"`) node ids already emitted
+     * for this form. Same per-extractor de-dup discipline as
+     * `synthClassNodeIds`, keyed on the node id — which is derived from the
+     * NORMALIZED backend path, so two bindings naming the same `.accdb`
+     * share one node while each still emits its own edge.
+     */
+    private externalBackendNodeIds;
     constructor(filePath: string, source: string);
     extract(): ExtractionResult;
     private createFileNode;
@@ -63,23 +71,11 @@ export declare class VbaFormExtractor {
     private emitExpressionHandlers;
     private emitExpressionHandler;
     private emitSourceObjectReference;
-    /**
-     * Issue #49 — copy of `VbaExtractor.SQL_TABLE_RE`. Same source / flags:
-     * captures the table name that follows `FROM`/`JOIN`/`INTO`/`UPDATE`,
-     * tolerates bracketed `[Order Details]` identifiers and `\p{L}` Unicode
-     * identifiers, and allows an optional schema prefix (`[dbo].[tblA]`).
-     *
-     * We duplicate the regex (rather than exporting it from `VbaExtractor`)
-     * because `VbaExtractor.SQL_TABLE_RE` is `private static` and the
-     * project's per-extractor state rule keeps each extractor's helpers
-     * self-contained — see the file-level JSDoc on `VbaExtractor`.
-     */
-    private static readonly SQL_TABLE_RE;
     /**
      * Issue #49 — classify a RecordSource/RowSource value as SQL.
      * Anything starting with a SQL keyword (`SELECT`, `PARAMETERS`, `WITH`,
      * `UPDATE`, `INSERT`, `DELETE`) — case-insensitive — is treated as a
-     * SQL statement and run through `SQL_TABLE_RE`. Anything else is a
+     * SQL statement and run through `scanSqlTables`. Anything else is a
      * bare table-or-query name and emitted as a single reference.
      *
      * `WITH` is included because Access/JET supports CTE-style `WITH` queries
@@ -103,6 +99,20 @@ export declare class VbaFormExtractor {
      * name — same dual-match `vba-sql-impact`'s `extractFormBindings` does).
      */
     private emitTableReference;
+    /**
+     * Issue #256 — emit one `references` edge from `sourceNodeId` to the
+     * external database file an Access `IN "<path>"` clause points at.
+     *
+     * The target node is built by the shared `buildExternalBackendNode` so
+     * it is byte-identical to the node the in-code SQL sweep and the saved-
+     * query extractor emit for the same path: the graph ends up with ONE
+     * node per external backend, however many places name it. The edge
+     * carries only `synthesizedBy` — the `external` / `backendPath` facts
+     * describe the node, and live there.
+     *
+     * `backendPath` is already normalized by `scanSqlExternalBackends`.
+     */
+    private emitExternalBackendReference;
     /**
      * Link a bound control to its enclosing form/report's single bare table.
      * Expressions and SQL/absent RecordSource values stay metadata-only: column
@@ -112,7 +122,7 @@ export declare class VbaFormExtractor {
     private emitControlSourceReference;
     /**
      * Issue #49 — dispatch the value of a RecordSource/RowSource binding.
-     * If SQL, run `SQL_TABLE_RE` over the value and emit one edge per
+     * If SQL, run `scanSqlTables` over the value and emit one edge per
      * distinct table (within-value dedup so `FROM tblA JOIN tblA` emits a
      * single edge). If a bare name, emit a single edge with the name as-is
      * — the resolver handles the dual-match against `query` and `class`
@@ -122,6 +132,10 @@ export declare class VbaFormExtractor {
      * the regex capture already includes them as part of the value, so a
      * single `.replace(/""/g, '"')` collapses them — same technique the
      * `extractStringLiterals` helper uses for its emitted `text` field.
+     *
+     * Issue #203: `scanSqlTables` also drops SQL reserved-word captures
+     * (`WHERE`, `ORDER`, `SET`, …) so a malformed SQL string never
+     * poisons the graph with phantom `class` nodes.
      */
     private emitBinding;
 }

package/dist/extraction/vba-preprocess.d.ts

@@ -32,6 +32,7 @@
  *
  * Source unchanged guarantee: every helper treats `src` as read-only.
  */
+import type { ExtractionError } from '../types';
 /**
  * Collapse VBA line continuations: any line whose last non-newline character is
  * `_` (preceded by exactly one space, per VBA convention) is joined to the
@@ -93,8 +94,36 @@ export declare function stripVbaComments(src: string): string;
  * promote this evaluator to full integer arithmetic.
  *
  * Directives and inactive branch lines are replaced with empty strings so
- * downstream extraction keeps source-line parity. Unsupported/unsafe
- * expressions evaluate to false rather than throwing.
+ * downstream extraction keeps source-line parity.
+ *
+ * **Issue #206 contract change.** Previously the docstring read
+ * *"Unsupported/unsafe expressions evaluate to false rather than
+ * throwing"* — accurate, but it framed silent whole-branch source
+ * deletion as a safety property. It was not: false-negative extraction is
+ * indistinguishable from correct extraction to every downstream consumer
+ * (an `#If MODE = "DEBUG" Then` whose `"` throws silently blanks the
+ * branch and the symbol vanishes from the graph).
+ *
+ * The new contract:
+ *
+ *   1. **Unterminated `#If`/`#ElseIf`**: if the directive stack is
+ *      non-empty after the loop ends, an `ExtractionError` (severity
+ *      `warning`, code `unterminated_if`) is pushed onto the optional
+ *      `errors` array AND the un-blanked lines from the earliest
+ *      unclosed `#If` are re-emitted. An unterminated `#If` is far
+ *      more likely a typo than a genuinely dead file tail.
+ *   2. **Could-not-evaluate expressions**: `evaluateConditionalExpression`
+ *      now distinguishes `evaluated: false` (a definitive false — e.g.
+ *      `#If 0 Then`, unknown identifier falling through to 0) from
+ *      `could-not-evaluate` (the lexer/parser hit an unsupported token,
+ *      or `tokenize`/`parse` threw). On could-not-evaluate, the branch
+ *      is **kept active** (conservative for a code-intelligence tool —
+ *      a spurious symbol is recoverable, a missing one is invisible)
+ *      and a warning is emitted through the same `errors` channel.
+ *
+ * The `errors` channel is OPTIONAL — every existing call site (and
+ * existing test) continues to work without it. The orchestrator can
+ * supply it to surface the warnings through `ctx.errors`.
  */
 export declare function preprocessConditionalCompilation(src: string, customTargets?: Record<string, boolean>, 
 /**
@@ -106,7 +135,64 @@ export declare function preprocessConditionalCompilation(src: string, customTarg
  * inner sub-totals. Undefined → no-op, zero cost (just the
  * `if (timings)` null-check on every CC line).
  */
-timings?: Map<string, number> | null): string;
+timings?: Map<string, number> | null, 
+/**
+ * Issue #206: optional `ExtractionError` sink for diagnostics the
+ * preprocessor wants to surface to extraction callers:
+ *   - `unterminated_if` (warning) — `#If` / `#ElseIf` pushed but
+ *     never closed by `#End If` (a likely typo).
+ *   - `unparseable_expression` (warning) — a `#If` / `#ElseIf`
+ *     expression the lexer/parser could not handle (the branch is
+ *     still kept active under the conservative contract).
+ *
+ * Undefined → no-op, zero cost (the `if (errors)` null-check on
+ * every warning site). The orchestrator passes `this.ctx.errors` so
+ * the warnings route through `ExtractionResult.errors`.
+ */
+errors?: ExtractionError[], 
+/**
+ * Issue #206: optional file path included on every pushed error
+ * when the caller wants telemetry to know which file the warning
+ * came from. Independent of `errors` so a caller can attach the
+ * path even when collecting warnings elsewhere.
+ */
+filePath?: string): string;
+/**
+ * Issue #206 discriminated return value for `evaluateConditionalExpression`.
+ *
+ *   - `{ kind: 'evaluated', value }` — the lexer+parser produced a
+ *     definitive answer. `value` is the truthiness of the expression
+ *     under VBA semantics (non-zero = true).
+ *   - `{ kind: 'could-not-evaluate' }` — the lexer/parser threw
+ *     (unsupported token: string literal, floating-point literal,
+ *     unrecognized character, mismatched paren, etc.). The caller MUST
+ *     treat this as ACTIVE under the conservative contract from
+ *     Issue #206 — see `preprocessConditionalCompilation`.
+ */
+export type ConditionalEvaluation = {
+    readonly kind: 'evaluated';
+    readonly value: boolean;
+} | {
+    readonly kind: 'could-not-evaluate';
+};
+/**
+ * Issue #206: marker error class for explicitly-unsupported VBA
+ * conditional-compilation tokens. The legacy `throw new Error(...)`
+ * from `tokenize` was indistinguishable from a real bug
+ * (`Unexpected trailing token`, mismatched paren); both bubbled into
+ * the same `catch { return false }`. The new helper carries the
+ * specific reason so the caller can attribute warnings precisely and
+ * distinguish "the lexer simply cannot handle this token" from a
+ * legitimate parse failure (which is also routed to
+ * could-not-evaluate, but with the original message preserved).
+ */
+export declare class UnparseableExpressionError extends Error {
+    /** Coarse category: `string_literal`, `float_literal`, `unsupported_character`. */
+    readonly reason: string;
+    /** The verbatim fragment that triggered the throw (for diagnostics). */
+    readonly fragment: string;
+    constructor(reason: string, fragment: string);
+}
 export interface StringLiteralSpan {
     /** The literal content (no surrounding quotes; `""` collapsed to `"`). */
     text: string;

package/dist/extraction/vba-source.d.ts

@@ -45,14 +45,4 @@ export interface ReadVbaSourceResult {
  * @param opts optional dependencies; see {@link ReadVbaSourceOptions}.
  */
 export declare function readVbaSource(filePath: string, opts?: ReadVbaSourceOptions): ReadVbaSourceResult;
-/**
- * String-level BOM strip — survives when the upstream `fsp.readFile(path, 'utf-8')`
- * already decoded the bytes (it's the only way the `\uFEFF` char survives in
- * a string). Used as a defensive last resort when a read site has NOT gone
- * through `readVbaSource` and the source text starts with the BOM marker.
- *
- * Most call sites should prefer `readVbaSource` for fresh reads; this is
- * a string post-process for callers that already have a `string` in hand.
- */
-export declare function stripUtf8Bom(text: string): string;
 //# sourceMappingURL=vba-source.d.ts.map

package/dist/extraction/vba-test-manifest-extractor.d.ts

@@ -1,10 +1,4 @@
 import { ExtractionResult } from '../types';
-/**
- * Content-shape gate: is `parsed` a VBA test manifest — a top-level `tests`
- * array with at least one item carrying a string `procedure`? Pure; the file's
- * basename is gated separately by `isVbaTestManifestFile` in `grammars.ts`.
- */
-export declare function isVbaTestManifestShape(parsed: unknown): boolean;
 export declare class VbaTestManifestExtractor {
     private filePath;
     private source;

package/dist/mcp/daemon-paths.d.ts

@@ -52,6 +52,12 @@ export declare function getDaemonSocketCandidates(projectRoot: string): string[]
 export declare function getDaemonSocketPath(projectRoot: string): string;
 /** Absolute path to the daemon pid lockfile for `projectRoot`. */
 export declare function getDaemonPidPath(projectRoot: string): string;
+/** Root-scoped lease held while intentional release owns lifecycle cleanup. */
+export declare function getDaemonReleaseLeasePath(projectRoot: string): string;
+/** Exclusive marker for release-lease recovery/heartbeat publication. */
+export declare function getDaemonReleaseRecoveryPath(projectRoot: string): string;
+/** Short root-scoped arbitration lock shared by startup and release publication. */
+export declare function getDaemonLifecyclePath(projectRoot: string): string;
 /** Structured contents of the pid lockfile. */
 export interface DaemonLockInfo {
     pid: number;

package/dist/mcp/daemon-registry.d.ts

@@ -1,3 +1,24 @@
+/**
+ * Global daemon registry + stop/list control — the discovery layer behind
+ * `codegraph list` and `codegraph stop [--all]`.
+ *
+ * Every per-project daemon already writes an authoritative lockfile at
+ * `<root>/.codegraph/daemon.pid`. That's enough to stop ONE daemon you can name,
+ * but there's no central place to find them ALL — which `list` and `stop --all`
+ * need. So each daemon also drops a tiny record under `~/.codegraph/daemons/` on
+ * start and removes it on graceful shutdown.
+ *
+ * The registry is a DISCOVERY index, never a source of truth: the live pid is.
+ * A SIGKILL'd daemon can't remove its own record, so readers prune any record
+ * whose pid is dead (`isProcessAlive`). Every write/read is best-effort — a
+ * registry hiccup must never break the daemon or a command; worst case `list`
+ * momentarily misses or over-lists one, which the next liveness prune corrects.
+ *
+ * Cross-platform by construction: only files + `process.kill(pid, signal)`,
+ * which behave consistently on macOS/Linux (real signals) and Windows (mapped to
+ * TerminateProcess). Validated live on all three.
+ */
+import * as fs from 'fs';
 export interface DaemonRecord {
     /** Realpath'd project root the daemon serves. */
     root: string;
@@ -32,16 +53,70 @@ export declare function listDaemons(opts?: {
 export interface StopResult {
     root: string;
     pid: number | null;
-    /** 'term' graceful, 'kill' force, 'not-running' stale lock, 'no-daemon' none found. */
-    outcome: 'term' | 'kill' | 'not-running' | 'no-daemon';
+    outcome: 'released' | 'not-running' | 'no-daemon' | 'identity-mismatch' | 'unreachable' | 'termination-failed';
+    failure?: string;
+}
+export interface ExpectedDaemon {
+    root: string;
+    pid: number;
+    version: string;
+    socketPath: string;
+    startedAt: number;
+}
+export interface DaemonReleaseDeps {
+    isAlive?: (pid: number) => boolean;
+    waitForDeath?: (pid: number, timeoutMs: number) => Promise<boolean>;
+    requestControl?: (expected: ExpectedDaemon) => Promise<'releasing' | 'identity-mismatch' | 'unreachable'>;
+    beforeArtifactDelete?: () => void;
+    leaseLinkSync?: typeof fs.linkSync;
+    afterLifecycleAcquired?: () => void;
+    afterReleaseLeasePublished?: (expected: ExpectedDaemon) => void;
+}
+export declare const DAEMON_RELEASE_LEASE_TTL_MS = 30000;
+export interface DaemonLifecycleLock {
+    token: string;
+    ownerPid: number;
+    createdAt: number;
+    expiresAt: number;
+}
+/** Atomically acquire the shared startup/release publication arbiter. */
+export declare function tryAcquireDaemonLifecycleLock(root: string, options?: {
+    now?: number;
+    linkSync?: typeof fs.linkSync;
+}): DaemonLifecycleLock | null;
+export declare function releaseDaemonLifecycleLock(root: string, lock: DaemonLifecycleLock): void;
+export interface DaemonReleaseLease {
+    token: string;
+    ownerPid: number;
+    createdAt: number;
+    heartbeatAt: number;
+    expiresAt: number;
+    generation: Pick<ExpectedDaemon, 'pid' | 'startedAt' | 'socketPath'>;
 }
+/** True while intentional release exclusively owns this root's lifecycle. */
+export declare function hasActiveDaemonReleaseLease(root: string, now?: number, hooks?: {
+    afterRecoveryRead?: () => void;
+}): boolean;
+/** Atomically claim release/cleanup ownership for one daemon generation. */
+export declare function tryAcquireDaemonReleaseLease(root: string, expected: ExpectedDaemon, options?: {
+    now?: number;
+    linkSync?: typeof fs.linkSync;
+}): DaemonReleaseLease | null;
+/** Publish a complete renewed generation atomically under the recovery marker. */
+export declare function refreshDaemonReleaseLease(root: string, lease: DaemonReleaseLease, now?: number): boolean;
+/** Resolve an explicit project root to the same canonical form daemons use. */
+export declare function canonicalDaemonRoot(root: string): string;
+/** Stable map/set key for aliases of the same canonical root. */
+export declare function canonicalDaemonRootKey(root: string): string;
+/** Project-scoped, idempotent release contract shared by CLI and MCP. */
+export declare function releaseDaemonAt(root: string, deps?: DaemonReleaseDeps): Promise<StopResult>;
 /**
- * Stop the daemon serving `root`: SIGTERM, wait, then SIGKILL if it won't go,
- * then sweep its artifacts. `root` must be realpath'd (match how the daemon
- * keys its socket/lockfile). Resolves the pid from the authoritative lockfile,
- * falling back to the registry.
+ * Release the daemon serving `root` through its authenticated socket handshake,
+ * wait for confirmed process death, then sweep ownership artifacts. Never sends
+ * a signal based only on pidfile/registry liveness. `root` must be realpath'd.
  */
-export declare function stopDaemonAt(root: string): Promise<StopResult>;
+export declare function stopDaemonAt(root: string, deps?: DaemonReleaseDeps): Promise<StopResult>;
+export declare function requestDaemonRelease(expected: ExpectedDaemon): Promise<'releasing' | 'identity-mismatch' | 'unreachable'>;
 /** Stop every registered, live daemon. */
 export declare function stopAllDaemons(): Promise<StopResult[]>;
 //# sourceMappingURL=daemon-registry.d.ts.map

package/dist/mcp/daemon-watchdog.d.ts

@@ -16,6 +16,7 @@
  * Spawned detaches (own session/process group) so closing the MCP process
  * does not take the watchdog down with it.
  */
+import { type StopResult } from './daemon-registry';
 export interface DaemonWatchdogOptions {
     /** Poll interval (ms). Default 30s. */
     intervalMs?: number;
@@ -33,6 +34,10 @@ export interface DaemonWatchdogOptions {
         windowsHide?: boolean;
         stdio?: 'ignore' | ['ignore', number, number];
     }) => boolean;
+    /** Release seam for deterministic overlap/failure tests. */
+    releaseFn?: (root: string) => Promise<StopResult>;
+    /** Async boundary before spawn; defaults to one microtask for release ordering. */
+    beforeSpawn?: () => Promise<void>;
 }
 /**
  * Per-project daemon liveness watchdog. Registers roots; polls every
@@ -40,16 +45,23 @@ export interface DaemonWatchdogOptions {
  */
 export declare class DaemonWatchdog {
     private readonly roots;
+    private readonly releasing;
     private interval;
     private readonly intervalMs;
     private readonly scriptPath;
     private readonly nodePath;
     private readonly spawnFn;
+    private readonly releaseFn;
+    private readonly beforeSpawn;
     constructor(opts?: DaemonWatchdogOptions);
     /** Watch a project root: if its daemon dies, respawn it. Idempotent. */
     watch(root: string): void;
+    /** Begin a new lifecycle for an intentionally released root. */
+    resume(root: string): void;
     /** Stop watching a root. Idempotent. */
     unwatch(root: string): void;
+    /** Intentionally release one project without allowing the next tick to respawn it. */
+    release(root: string): Promise<StopResult>;
     /** Number of roots currently being watched. */
     size(): number;
     /**

package/dist/mcp/daemon.d.ts

@@ -63,8 +63,17 @@ export interface DaemonHello {
     codegraph: string;
     pid: number;
     socketPath: string;
+    root: string;
+    startedAt: number;
     protocol: 1;
 }
+export interface DaemonReleaseControl {
+    codegraph_control: 1;
+    action: 'release';
+    root: string;
+    pid: number;
+    startedAt: number;
+}
 /**
  * Optional reverse-handshake line a proxy sends right after it verifies the
  * daemon hello, carrying its own pids so the daemon can reap the client if its
@@ -112,9 +121,16 @@ export declare class Daemon {
     private stopping;
     private socketPath;
     private pidPath;
+    private startedAt;
+    private acquiredGeneration;
+    private listenSocket;
+    private exit;
     constructor(projectRoot: string, opts?: {
         idleTimeoutMs?: number;
         maxIdleMs?: number;
+        generation?: DaemonLockInfo;
+        listenSocket?: (socketPath: string, onConnection: (socket: net.Socket) => void) => Promise<net.Server>;
+        exit?: (code: number) => void;
     });
     /**
      * Bind the socket, kick off engine init, and register signal handlers. The
@@ -222,7 +238,9 @@ export type AcquireResult = {
  * widened). The race's worst case is two daemons briefly; on a single external
  * drive that's strictly better than the daemon never starting at all.
  */
-export declare function tryAcquireDaemonLock(projectRoot: string): AcquireResult;
+export declare function tryAcquireDaemonLock(projectRoot: string, options?: {
+    afterLifecycleAcquired?: () => void;
+}): AcquireResult;
 /**
  * Exclusive-create the pidfile (O_CREAT|O_EXCL via the `wx` flag) and write the
  * full record through the same fd — the hard-link-free fallback used by
@@ -285,6 +303,7 @@ export declare function peerIsDead(peers: {
     pid: number | null;
     hostPid: number | null;
 }, isAlive: (pid: number) => boolean): boolean;
+export declare function parseReleaseControlLine(line: string): DaemonReleaseControl | null;
 /** Exported for test stubs that need to bound the hello-line read. */
 export { MAX_HELLO_LINE_BYTES };
 //# sourceMappingURL=daemon.d.ts.map