@colbymchenry/codegraph 0.9.8 → 1.0.0

package/dist/extraction/tree-sitter.d.ts

@@ -20,11 +20,45 @@ export declare class TreeSitterExtractor {
     private extractor;
     private nodeStack;
     private methodIndex;
+    private fnRefSpec;
+    private fnRefCandidates;
     constructor(filePath: string, source: string, language?: Language);
     /**
      * Parse and extract from the source code
      */
     extract(): ExtractionResult;
+    /**
+     * Function-as-value capture (#756): if this node is one of the language's
+     * value-position containers (call arguments, assignment RHS, struct/object
+     * initializer, array/table literal), collect candidate function names from
+     * it. Candidates are gated & flushed at end-of-file (flushFnRefCandidates).
+     */
+    private maybeCaptureFnRefs;
+    /**
+     * Candidates-only scan of a subtree the main walkers won't traverse
+     * (top-level variable initializers). No extraction side effects. Halts at
+     * nested function definitions: their bodies are walked — and their
+     * candidates attributed — by extractFunction's own body walk.
+     */
+    private scanFnRefSubtree;
+    /**
+     * Gate captured function-as-value candidates and push survivors as
+     * `function_ref` unresolved references.
+     *
+     * The gate bounds volume and protects precision: a candidate survives only
+     * if its name matches a function/method DEFINED IN THIS FILE or a name this
+     * file imports/references. Everything else (locals, params, fields passed
+     * as arguments) is dropped before it ever reaches the database. Resolution
+     * then matches survivors against function/method nodes only
+     * (matchFunctionRef) and emits `references` edges — which callers/impact
+     * already traverse.
+     *
+     * Known v1 limit, deliberate: a C/C++ callback registered in a DIFFERENT
+     * translation unit than its definition (extern, no symbol imports to match)
+     * is not captured. Same-file registration — the dominant C pattern (static
+     * callback + same-file ops struct) — is.
+     */
+    private flushFnRefCandidates;
     /**
      * Visit a node and extract information
      */
@@ -97,6 +131,32 @@ export declare class TreeSitterExtractor {
      * Extracts each declarator as a 'field' kind node inside the owning class.
      */
     private extractField;
+    /**
+     * Extract function-valued properties of an object literal as named function
+     * nodes (named by their property key). Shared by the two object-of-functions
+     * shapes in extractVariable: the object as a direct const value, and the
+     * object returned by a store-initializer call. Handles both `key: () => {}` /
+     * `key: function() {}` pairs and method shorthand `key() {}`.
+     */
+    private extractObjectLiteralFunctions;
+    /** Property-key text with surrounding quotes stripped (`'foo'` → `foo`). */
+    private objectKeyName;
+    /**
+     * Given a `call_expression` initializer (`create((set, get) => ({...}))`),
+     * find the object literal RETURNED by a function argument — descending through
+     * nested call_expression arguments so middleware wrappers are unwrapped
+     * (`create(persist((set, get) => ({...}), {...}))`, devtools, immer,
+     * subscribeWithSelector). Returns null when no such object is found — the
+     * common case for ordinary call initializers — so this stays cheap and silent
+     * rather than guessing. Keyed purely on AST shape; no library names.
+     */
+    private findInitializerReturnedObject;
+    /**
+     * The object literal a function expression returns — either the `=> ({...})`
+     * arrow form (a parenthesized_expression wrapping an object) or a
+     * `=> { return {...} }` block. Returns null for any other body shape.
+     */
+    private functionReturnedObject;
     /**
      * Extract a variable declaration (const, let, var, etc.)
      *
@@ -111,6 +171,14 @@ export declare class TreeSitterExtractor {
      * Returns true if children should be skipped (struct/interface handled body visiting).
      */
     private extractTypeAlias;
+    /**
+     * Extract the method specs of a Go `interface_type` body as `method` nodes
+     * contained by the interface (e.g. `Marshal`, `Unmarshal` of a `Core`
+     * interface). tree-sitter-go names these `method_elem` (newer) or
+     * `method_spec` (older). Embedded interfaces (`Reader` inside `ReadWriter`)
+     * are `type_identifier`s, not methods, and are left to inheritance extraction.
+     */
+    private extractGoInterfaceMethods;
     /**
      * Surface the members of a TypeScript `type X = { ... }` (or intersection
      * thereof) as `property` / `method` nodes under the type-alias node. Only
@@ -119,6 +187,34 @@ export declare class TreeSitterExtractor {
      * don't produce phantom members.
      */
     private extractTsTypeAliasMembers;
+    /**
+     * Surface the string-literal "names" of a TypeScript service/contract
+     * registry written as a tuple of generic instantiations:
+     *
+     *   type MyServiceList = [
+     *     Service<'query_apply_record', Req, Resp>,
+     *     Service<'apply_confirm', Req, Resp>,
+     *   ];
+     *
+     * Each `Service<'name', …>` tags an entry with a string-literal name that a
+     * dynamic factory (`createService<MyServiceList>()`) turns into a callable
+     * property (`api.query_apply_record(…)`). Static extraction otherwise never
+     * sees that name — it's a type argument, not a declaration — so
+     * `codegraph query query_apply_record` returned nothing (issue #634). We emit
+     * each name as a `method` node under the type alias (qualifiedName
+     * `MyServiceList::query_apply_record`) so it's searchable and resolvable as a
+     * symbol. (A call through the proxy, `api.query_apply_record(…)`, still
+     * resolves to the imported `api` binding — the receiver's type isn't known —
+     * so this fixes discoverability, not the per-method call edge.)
+     *
+     * Scope is deliberately narrow to avoid noise: only a string literal that is
+     * a DIRECT type argument of a `generic_type` that is itself a DIRECT element
+     * of a `tuple_type`. This excludes utility types (`Pick`/`Omit`/`Record` are
+     * never written as tuples) and string args nested deeper
+     * (`Service<'a', Pick<U, 'id'>>` yields only `a`, never `id`). Names must be
+     * valid identifiers, which also rules out route paths / arbitrary strings.
+     */
+    private extractTsTupleContractNames;
     /**
      * `foo: () => T` → property_signature whose type_annotation contains a
      * `function_type`. Treat that as a method-shaped contract member, since
@@ -132,6 +228,83 @@ export declare class TreeSitterExtractor {
      * Also creates unresolved references for resolution purposes.
      */
     private extractImport;
+    /**
+     * Emit one `imports` reference per named/default import binding (TS/JS family),
+     * attributed to the file node — so the resolver links each imported symbol to
+     * the file that DEFINES it.
+     *
+     * Importing a symbol IS a dependency, but extraction only emits references for
+     * calls, instantiations, type annotations, and inheritance. A symbol that's
+     * imported and then only re-exported (`export { X } from './x'`), placed in a
+     * registry array (`[expressResolver, …]`), passed as an argument, or used in
+     * JSX produced NO cross-file edge at all — so the providing file showed a
+     * false "0 dependents" and was invisible to blast-radius / `affected`. The
+     * resolver maps the local name (alias-aware) to the provider's definition and
+     * creates a cross-file `imports` edge; `getFileDependents` picks it up, while
+     * `getImpactRadius` keeps it as a bounded leaf (the importing file node).
+     *
+     * Namespace imports (`import * as NS`) bind a whole module: `NS.member` calls
+     * resolve on their own, but a namespace used ONLY via a value-member read
+     * (`NS.SOME_CONST`) would leave no edge — so we also emit the namespace local
+     * name, which the resolver links to the module FILE as a dependency backstop.
+     */
+    private emitImportBindingRefs;
+    /**
+     * Emit one `imports` reference per re-exported binding of a
+     * `export { A, B as C } from './y'` statement, attributed to the file node —
+     * so a barrel that re-exports from another module records a dependency on it.
+     *
+     * Links the SOURCE-side name (`A`, the `name` field — not the local alias
+     * `C`), since that is what the source module defines. `export * from './y'`
+     * has no named bindings to attribute and `export { default as X }` can't be
+     * name-matched, so both are skipped.
+     */
+    private emitReExportRefs;
+    /**
+     * Emit one `imports` reference per binding of a Rust `use` declaration —
+     * `use crate::m::Item`, `use crate::m::{A, B as C}`, `pub use self::sub::Item`.
+     * Emits the FULL path (e.g. `self::sub::Item`, not just `Item`) so the resolver
+     * can resolve the module prefix to a file and find the leaf symbol there —
+     * disambiguating common-name re-exports (`pub use self::read::read`, where the
+     * leaf `read` collides with many same-named symbols). Falls back to name-match
+     * on the leaf when the path can't be resolved. `use ...::*` has no leaf binding.
+     */
+    private emitRustUseBindingRefs;
+    /**
+     * Emit an `imports` reference for a single PHP `use Foo\Bar\Baz;` (grouped
+     * imports `use Foo\{A, B}` are handled where their per-item nodes are created).
+     * The reference targets the namespace-qualified `Foo\Bar::Baz` form classes are
+     * stored under (see the PHP `namespace` capture), so it resolves to the RIGHT
+     * definition — Laravel has many same-named contracts (`Factory`, `Dispatcher`,
+     * `Guard`) across namespaces that a bare-name match can't disambiguate.
+     */
+    private emitPhpUseRefs;
+    /**
+     * Ruby `require`/`require_relative` → an `imports` ref to the required FILE.
+     * `require "sidekiq/fetch"` is load-path-relative (matched by file-path suffix
+     * via {@link matchByFilePath}); `require_relative "../foo"` is resolved against
+     * this file's directory. Bare gem/stdlib requires (`require "json"`, no slash)
+     * are skipped — they're external. The path form (a `/` + `.rb`) makes the ref
+     * resolve to the file node, so a file pulled in only by `require` — not by a
+     * resolved constant/call — still records a cross-file dependency.
+     */
+    private emitRubyRequireRefs;
+    /** Convert a PHP FQN `Foo\Bar\Baz` to the stored `Foo\Bar::Baz` and emit an `imports` ref. */
+    private pushPhpUseRef;
+    /**
+     * Emit one `imports` reference per name imported in a Python
+     * `from module import A, B as C` statement, attributed to the file node — so
+     * the resolver links each imported name to the module that DEFINES it.
+     *
+     * Same recall gap as TS: extraction only emitted references for calls,
+     * instantiations, and inheritance, so a name imported and then used in a
+     * non-call position (a list/dict literal, a default argument, a decorator
+     * target, or simply re-exported through an `__init__.py` barrel) produced no
+     * cross-file edge — the providing module showed a false "0 dependents". Links
+     * the LOCAL name (alias when present, since that's what the resolver's import
+     * mapping keys on); `from module import *` has no names to attribute.
+     */
+    private emitPyFromImportRefs;
     /**
      * Extract a function call
      */
@@ -146,6 +319,18 @@ export declare class TreeSitterExtractor {
      * arguments (`new Foo(bar())`) get their own `calls` references.
      */
     private extractInstantiation;
+    /**
+     * Static-member / value-read pass. A type/enum/class used only via a member
+     * VALUE — `Enum.value`, `Type.CONST`, `Colors.red`, `Foo::BAR` — recorded no
+     * edge, because the body walker only handled CALLS (`Type.method()`). So a
+     * type referenced only by an enum value or a static field looked like nothing
+     * depended on it (the residual frontier across Dart/Java/C#/Swift/Kotlin/PHP).
+     * Emit a `references` edge to the capitalized receiver. Gated to languages
+     * where types are Capitalized by convention, and skipped when the access is a
+     * call's callee (the call extractor already links the method).
+     */
+    private extractStaticMemberRef;
+    private pushStaticMemberRef;
     /**
      * Find a `class_body` child of an `object_creation_expression` — the
      * marker for an anonymous class (`new T() { ... }`). Returns the body
@@ -190,6 +375,19 @@ export declare class TreeSitterExtractor {
      *      tree-sitter to interpret the namespace block as a function_definition,
      *      hiding real class/struct/enum nodes inside the "function body".
      */
+    /**
+     * Rocket route-registration macros — `routes![a::b::handler, c::d::other]`
+     * and `catchers![not_found]`. Tree-sitter leaves a macro body as a flat
+     * `token_tree` of raw tokens (`identifier`, `::`, `,`), so the handler paths
+     * are never seen as references and each handler fn looks like it has no caller
+     * — it's mounted by Rocket at runtime, not called by in-repo code, so its file
+     * shows 0 dependents. Walk the token tree, reconstruct each comma-separated
+     * path, and emit a `references` edge; the Rust path resolver
+     * (`resolveRustPathReference`) then links it to the handler fn. The handler
+     * names are explicit in source, so this is precise static extraction, not a
+     * heuristic — no false edges (resolution still validates each path).
+     */
+    private extractRustRouteMacro;
     private visitFunctionBody;
     /**
      * Extract inheritance relationships
@@ -208,6 +406,11 @@ export declare class TreeSitterExtractor {
      * Languages that support type annotations (TypeScript, etc.)
      */
     private readonly TYPE_ANNOTATION_LANGUAGES;
+    /**
+     * PHP pseudo-types and `self`/`static`/`parent` that aren't project symbols.
+     * (Scalar primitives parse as `primitive_type` and are skipped structurally.)
+     */
+    private readonly PHP_PSEUDO_TYPES;
     /**
      * Built-in/primitive type names that shouldn't create references
      */
@@ -230,12 +433,35 @@ export declare class TreeSitterExtractor {
      * `tuple_type`, …) — none of which are `type_identifier`. Closes #381.
      */
     private extractCsharpTypeRefs;
+    /**
+     * Record the dependencies declared by a C# PRIMARY CONSTRUCTOR
+     * (`class Svc(IRepo repo, [FromKeyedServices("k")] ICache cache) { … }`,
+     * C# 12+). The parameter list hangs off the class/struct/record declaration
+     * as an unnamed-field `parameter_list` child (not the `parameters` field a
+     * method uses), so it's found by node type. Each parameter's declared type
+     * becomes a `references` edge from the owning type — these are exactly the
+     * services a DI-registered type depends on, so impact/blast-radius and
+     * "who depends on this contract" now see them. No-op when there's no primary
+     * constructor. (#237)
+     */
+    private extractCsharpPrimaryCtorParamRefs;
     /**
      * Walk a C# subtree that is KNOWN to be in a type position
      * (return type, parameter type, property type, field type, generic
      * argument). Identifiers here are type names, not parameter names.
      */
     private walkCsharpTypePosition;
+    /**
+     * Extract PHP type references from a method/function/property declaration.
+     * Walks ONLY type positions: each parameter's type child (inside
+     * `formal_parameters`), the return type, and a property's type — all
+     * `named_type` / `optional_type` / `union_type` / … direct children. Parameter
+     * and property NAMES are `variable_name` (`$x`), never type nodes, so they
+     * can't be mis-emitted.
+     */
+    private extractPhpTypeRefs;
+    /** Walk a PHP subtree KNOWN to be in a type position; emit class/interface refs. */
+    private walkPhpTypePosition;
     /**
      * Extract type references from a variable's type annotation.
      */
@@ -275,6 +501,17 @@ export declare class TreeSitterExtractor {
      * Extract function calls from a Pascal expression
      */
     private extractPascalCall;
+    /**
+     * Extract a PAREN-LESS Pascal method/procedure call (`Obj.Method;`,
+     * `TFoo.GetInstance.DoIt;`). Pascal lets a no-arg method drop its parens, so it
+     * parses as a bare `exprDot` (not an `exprCall`). A bare `exprDot` is
+     * syntactically identical to a field/property access, so this is only ever
+     * called for a STATEMENT-level exprDot (caller-gated): a bare `Obj.Field;`
+     * statement is a no-op, so a statement-level dot expression is a call. (An
+     * exprDot in assignment LHS/RHS or a condition is left alone — there it really
+     * can be a field/property read.)
+     */
+    private extractPascalParenlessCall;
     /**
      * Recursively visit a Pascal block/statement tree for call expressions
      */

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

@@ -32,5 +32,20 @@ export declare class VueExtractor {
      * Process a script block by delegating to TreeSitterExtractor
      */
     private processScriptBlock;
+    /**
+     * Extract component usages from the Vue `<template>`.
+     *
+     * PascalCase tags (`<Modal>`, `<Button />`) and kebab-case tags
+     * (`<my-button>`) both represent component instantiations — analogous to
+     * function calls in imperative code. Capturing them creates parent→child
+     * component edges and lets `callers` / `impact` see a component that is
+     * only ever used in markup. Vue's extractor previously parsed only the
+     * `<script>` block, so these usages produced no edge at all (#629).
+     *
+     * HTML elements (lowercase, no hyphen) and Vue built-ins are skipped.
+     * Unmatched names create no edge during resolution, so converting
+     * kebab-case is safe even for native custom elements.
+     */
+    private extractTemplateComponents;
 }
 //# sourceMappingURL=vue-extractor.d.ts.map

package/dist/index.d.ts

@@ -158,8 +158,8 @@ export declare class CodeGraph {
      */
     getPendingFiles(): PendingFile[];
     /**
-     * Resolves once the file watcher has finished its initial chokidar scan.
-     * Useful for tests that need a deterministic boundary before asserting on
+     * Resolves once the file watcher has installed its watch set. Useful for
+     * tests that need a deterministic boundary before asserting on
      * `getPendingFiles()`. Resolves immediately when no watcher is active.
      */
     waitUntilWatcherReady(timeoutMs?: number): Promise<void>;
@@ -171,6 +171,30 @@ export declare class CodeGraph {
         modified: string[];
         removed: string[];
     };
+    /**
+     * Most recent index timestamp (ms since epoch) across all tracked files, or
+     * null when nothing is indexed yet. Lets library consumers check index
+     * freshness without shelling out to `codegraph status --json`. (#329)
+     */
+    getLastIndexedAt(): number | null;
+    /**
+     * Which engine built the current index: the package version + extraction
+     * version stamped at the last full `indexAll`. Either field is null for an
+     * index built before stamping existed (treated as stale). See
+     * `extraction-version.ts` and `isIndexStale()`.
+     */
+    getIndexBuildInfo(): {
+        version: string | null;
+        extractionVersion: number | null;
+    };
+    /**
+     * True when the on-disk index was built by an engine whose extraction is
+     * older than the one now running — i.e. a re-index would add data a migration
+     * can't backfill. False when there's no index yet (nothing to refresh) or the
+     * stamp is current. This is the signal behind `codegraph status`'s re-index
+     * hint and `codegraph upgrade`'s reminder.
+     */
+    isIndexStale(): boolean;
     /**
      * Extract nodes and edges from source code (without storing)
      */
@@ -227,15 +251,29 @@ export declare class CodeGraph {
      * Get all nodes of a specific kind
      */
     getNodesByKind(kind: Node['kind']): Node[];
+    /**
+     * Get ALL nodes with an exact name (direct index lookup, not FTS-ranked/capped).
+     * Used to enumerate every overload of a heavily-overloaded name so the specific
+     * definition the caller wants is never dropped below a search cut.
+     */
+    getNodesByName(name: string): Node[];
     /**
      * Search nodes by text
      */
     searchNodes(query: string, options?: SearchOptions): SearchResult[];
+    /**
+     * Normalized project-name tokens (go.mod / package.json / repo dir) used to
+     * down-weight the non-discriminative project name in search ranking (#720).
+     * Exposed so explore can exclude it from the PascalCase type-disambiguation
+     * bias, which would otherwise pull overloaded tokens toward whichever stack
+     * embeds the project name.
+     */
+    getProjectNameTokens(): Set<string>;
     /**
      * Find the project's "primary route file" — the file with the densest
      * concentration of framework-emitted `route` nodes (≥3 routes, ≥30%
      * of all non-test routes). Used to inline the routing config in
-     * `codegraph_context` responses on small realworld template repos
+     * `codegraph_explore` responses on small realworld template repos
      * (rails-realworld, laravel-realworld, drupal-admintoolbar, …) where
      * Glob+Read of `routes.rb`/`urls.py`/etc. otherwise beats codegraph.
      */

package/dist/installer/instructions-template.d.ts

@@ -1,18 +1,41 @@
 /**
- * Marker constants for the legacy agent-instructions block.
+ * The marker-fenced agent-instructions block the installer writes into each
+ * agent's instructions file (CLAUDE.md / AGENTS.md / GEMINI.md).
  *
- * Codegraph used to write a `## CodeGraph` usage guide into each
- * agent's instructions file (CLAUDE.md / AGENTS.md / GEMINI.md /
- * codegraph.mdc / Kiro steering doc). That duplicated the guidance the
- * MCP server already emits in its `initialize` response — every agent
- * read the same playbook twice each turn (issue #529). The installer no
- * longer writes an instructions file; the MCP server instructions in
- * `mcp/server-instructions.ts` are the single source of truth.
+ * History: pre-#529 the installer wrote a full usage playbook here, which
+ * duplicated the MCP `initialize` instructions for the main agent — so it
+ * was removed and `mcp/server-instructions.ts` became the single source of
+ * truth. A much smaller block returned for #704, because the MCP
+ * instructions cannot reach two audiences that the instructions FILE does
+ * reach:
  *
- * These markers are retained so install (self-heal on upgrade) and
- * uninstall can find and strip the block a previous install wrote.
+ *  - **Task-tool subagents** — they receive the project instructions file
+ *    in their context but NOT the MCP initialize instructions. They hold
+ *    the codegraph MCP tools only as deferred names and rarely think to
+ *    load them: measured on a forced-delegation flow question (excalidraw,
+ *    sonnet, high effort), subagents loaded + used codegraph in ~1 of 9
+ *    runs without this block, and consistently with it — including runs
+ *    with zero Read/grep fallback.
+ *  - **Non-MCP harnesses** — agents with no MCP client at all can still
+ *    run the `codegraph explore` / `codegraph node` CLI, which prints the
+ *    same output as the MCP tools.
+ *
+ * Keep this block SHORT. The main agent reads it every turn on top of the
+ * server instructions — the #529 duplication-cost argument still bounds
+ * its size. Command names and the two surfaces, nothing more.
  */
-/** Markers used by the marker-based section removal. */
+/** Markers used by the marker-based section write/removal. */
 export declare const CODEGRAPH_SECTION_START = "<!-- CODEGRAPH_START -->";
 export declare const CODEGRAPH_SECTION_END = "<!-- CODEGRAPH_END -->";
+/**
+ * The full block, markers included, exactly as written to disk.
+ *
+ * The wording is deliberately CONDITIONAL ("in repositories indexed by…"):
+ * a global install writes this into a user-scope file (~/.claude/CLAUDE.md,
+ * ~/.codex/AGENTS.md) that applies to every project the user opens —
+ * including unindexed ones, where an unconditional "this repository is
+ * indexed" claim would send subagents into failing codegraph calls (the
+ * noise the unindexed-session policy exists to prevent).
+ */
+export declare const CODEGRAPH_INSTRUCTIONS_BLOCK = "<!-- CODEGRAPH_START -->\n## CodeGraph\n\nIn repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:\n\n- **MCP tools** (when available): `codegraph_explore` answers most code questions in one call \u2014 the relevant symbols' verbatim source plus the call paths between them. `codegraph_node` returns one symbol's source + callers, or reads a whole file with line numbers. If the tools are listed but deferred, load them by name via tool search.\n- **Shell** (always works): `codegraph explore \"<symbol names or question>\"` and `codegraph node <symbol-or-file>` print the same output.\n\nIf there is no `.codegraph/` directory, skip CodeGraph entirely \u2014 indexing is the user's decision.\n<!-- CODEGRAPH_END -->";
 //# sourceMappingURL=instructions-template.d.ts.map

package/dist/installer/targets/opencode.d.ts

@@ -2,10 +2,18 @@
  * opencode target.
  *
  *   - MCP server entry to `~/.config/opencode/opencode.jsonc` (global,
- *     XDG-style; `%APPDATA%/opencode/opencode.jsonc` on Windows) or
+ *     XDG-style on EVERY platform, Windows included — see below) or
  *     `./opencode.jsonc` (local). Falls back to `opencode.json` when a
  *     `.json` file already exists; defaults new installs to `.jsonc`
  *     because that's what opencode itself creates on first run.
+ *
+ *     opencode resolves its config dir with the `xdg-basedir` package
+ *     (sst/opencode `packages/core/src/global.ts`): `XDG_CONFIG_HOME`
+ *     if set, else `~/.config` — unconditionally, on all platforms. It
+ *     never reads `%APPDATA%`; that layout belonged to the discontinued
+ *     Go fork. We previously wrote there on Windows, so opencode never
+ *     saw the entry (#535) — install/uninstall now also sweep a stale
+ *     codegraph entry out of the legacy `%APPDATA%/opencode` location.
  *   - Instructions to `~/.config/opencode/AGENTS.md` (global) or
  *     `./AGENTS.md` (local). opencode reads AGENTS.md for agent
  *     instructions — same convention Codex CLI uses.

package/dist/installer/targets/shared.d.ts

@@ -64,6 +64,20 @@ export declare function jsonDeepEqual(a: unknown, b: unknown): boolean;
  * existing block already matches `body`.
  */
 export declare function replaceOrAppendMarkedSection(filePath: string, body: string, startMarker: string, endMarker: string): 'created' | 'updated' | 'appended' | 'unchanged';
+/**
+ * Upsert the CodeGraph instructions block into an agent instructions
+ * file (CLAUDE.md / AGENTS.md / GEMINI.md). The one write shared by
+ * every target: self-heals a stale pre-#529 long block (markers match →
+ * replaced by the current short one), appends after existing user
+ * content otherwise, and reports `unchanged` on byte-equal re-runs so
+ * install stays idempotent. See `instructions-template.ts` for why this
+ * block exists (#704: subagents + non-MCP harnesses never see the MCP
+ * initialize instructions).
+ */
+export declare function upsertInstructionsEntry(file: string): {
+    path: string;
+    action: 'created' | 'updated' | 'unchanged';
+};
 /**
  * Inverse of `replaceOrAppendMarkedSection`. Strips the marker
  * block from `filePath` if present. If the file becomes empty after

package/dist/mcp/daemon.d.ts

@@ -54,6 +54,20 @@ export interface DaemonHello {
     socketPath: string;
     protocol: 1;
 }
+/**
+ * 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
+ * process dies WITHOUT the socket ever signalling close (the Windows named-pipe
+ * hazard behind #692). Entirely optional and fail-safe: a connection that never
+ * sends it (a legacy/direct client) just falls back to the socket-close
+ * lifecycle. The `codegraph_client` marker is what tells it apart from the
+ * client's first JSON-RPC message.
+ */
+export interface DaemonClientHello {
+    codegraph_client: 1;
+    pid: number;
+    hostPid: number | null;
+}
 export interface DaemonStartResult {
     /** Always-non-null for a successfully-started daemon. */
     socketPath: string;
@@ -75,14 +89,21 @@ export declare class Daemon {
     private projectRoot;
     private server;
     private clients;
+    /** Per-client peer pids from the optional client-hello, for the liveness sweep. */
+    private clientPeers;
     private idleTimer;
     private idleTimeoutMs;
+    private maxIdleMs;
+    private lastActivityAt;
+    private maxIdleTimer;
+    private clientSweepTimer;
     private engine;
     private stopping;
     private socketPath;
     private pidPath;
     constructor(projectRoot: string, opts?: {
         idleTimeoutMs?: number;
+        maxIdleMs?: number;
     });
     /**
      * Bind the socket, kick off engine init, and register signal handlers. The
@@ -101,6 +122,26 @@ export declare class Daemon {
     private dropClient;
     private armIdleTimer;
     private disarmIdleTimer;
+    /**
+     * Defense-in-depth against a daemon that outlives its clients (#692), for the
+     * cases the refcount + idle timer miss because a socket close never arrives:
+     *   - **Inactivity backstop:** exit if no inbound traffic for `maxIdleMs` while
+     *     clients are still (nominally) connected. A phantom client sends nothing,
+     *     so it can't pin the daemon past this window.
+     *   - **Liveness sweep:** drop any client whose peer process has died (per the
+     *     client-hello pids), which re-arms the idle timer once the last real
+     *     client is gone. Catches a dead peer within one sweep instead of waiting
+     *     out the whole backstop.
+     * Both timers are unref'd — the listening server keeps the loop alive, and
+     * neither should hold it open on its own.
+     */
+    private startLivenessTimers;
+    /**
+     * Drop every connected client whose peer process is gone. Returns the count
+     * reaped. `isAlive` is injected for testing. Clients with unknown pids (no
+     * client-hello) are skipped — they rely on the socket-close path.
+     */
+    reapDeadClients(isAlive: (pid: number) => boolean): number;
     private cleanupLockfile;
 }
 /**
@@ -128,7 +169,7 @@ export type AcquireResult = {
  * the file existed but was empty; under concurrent daemon startup a third
  * candidate could read that empty file, decode it as `null`, and `unlink` the
  * winner's lock → two daemons (two watchers, two writers). The window was
- * normally too small to hit, but the chokidar watcher's extra startup time made
+ * normally too small to hit, but the file watcher's extra startup time made
  * concurrent daemons overlap enough to reproduce it reliably.
  *
  * The fix writes the complete record to a private temp file, then hard-links it
@@ -156,6 +197,24 @@ export declare function clearStaleDaemonLock(pidPath: string, expectedDeadPid?:
  * mistake a live daemon for a dead one and clear its lock.
  */
 export declare function isProcessAlive(pid: number): boolean;
+/**
+ * Parse one client-hello line. Returns the peer pids if `line` is a well-formed
+ * client-hello (carries the `codegraph_client` marker), or null otherwise — in
+ * which case the caller treats the bytes as ordinary JSON-RPC.
+ */
+export declare function parseClientHelloLine(line: string): {
+    pid: number;
+    hostPid: number | null;
+} | null;
+/**
+ * A client's peer is dead when its proxy process is gone, or when its known
+ * host process is gone. Unknown pid (no client-hello) is never "dead" on this
+ * basis — those clients rely on the socket-close path. Exported for testing.
+ */
+export declare function peerIsDead(peers: {
+    pid: number | null;
+    hostPid: number | null;
+}, isAlive: (pid: number) => boolean): boolean;
 /** Exported for test stubs that need to bound the hello-line read. */
 export { MAX_HELLO_LINE_BYTES };
 //# sourceMappingURL=daemon.d.ts.map

package/dist/mcp/dynamic-boundaries.d.ts

@@ -0,0 +1,41 @@
+export interface BoundaryMatch {
+    /** Stable form id, e.g. 'computed-call' — used for per-form dedupe. */
+    form: string;
+    /** Human label for the dispatch form, e.g. 'computed member call'. */
+    label: string;
+    /** One-line source snippet of the site (from the original, untrimmed text). */
+    snippet: string;
+    /** 1-based line within the scanned body's FILE (absolute, ready to print). */
+    line: number;
+    /**
+     * Statically-visible dispatch key, when one exists: the string literal in
+     * `handlers['save']`, the `:symbol` in ruby `send`, the type name in
+     * `Send(new CreateCmd(...))`. Drives candidate lookup. Undefined when the
+     * key is a runtime value (variable, computed expression).
+     */
+    key?: string;
+    /** For typed-bus matches the key is a TYPE name (candidates ~ `${key}Handler`). */
+    keyIsType?: boolean;
+    /** Additional sites of the same form+key in this body beyond the reported one. */
+    moreSites?: number;
+}
+/**
+ * Blank the CONTENTS of string literals (quotes preserved, offsets preserved)
+ * so dispatch-shaped prose — docs, error messages, template text — can't fire
+ * a matcher. Run AFTER comment stripping (comments are already spaces).
+ * Backslash escapes are honored; `'`/`"` strings end at a newline (treated as
+ * unterminated, matching the comment stripper); backticks span lines, and
+ * `${...}` interpolations inside them are blanked too — missing a dispatch
+ * inside a template literal is acceptable, false-firing on prose is not.
+ */
+export declare function blankStringContents(text: string): string;
+/**
+ * Scan one symbol's body for dynamic-dispatch sites.
+ *
+ * @param body       the symbol's source text (sliced from the file)
+ * @param language   Node.language of the symbol
+ * @param fileStartLine 1-based line where `body` starts in its file — returned
+ *                      line numbers are absolute file lines.
+ */
+export declare function scanDynamicDispatch(body: string, language: string, fileStartLine: number): BoundaryMatch[];
+//# sourceMappingURL=dynamic-boundaries.d.ts.map