Merge pull request #235 from ardelperal/feat/issue-234-release-tracker

docs(design): track project-scoped daemon release

Author: ardelperal

CHANGELOG.md

@@ -11,6 +11,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- Project-scoped CodeGraph resources can now be released non-interactively through the CLI or the opt-in MCP tool before deleting a worktree, without stopping unrelated projects. (#234)
 - VBA extractor comments now describe the behavior they guard, and the rule-table invariant also validates the procedure pre-walk so future drift fails loudly. (#215)
 - VBA classifiers now share one rule dispatcher with consistent scan modes, structural gates, counting, and declarative terminal behavior, preventing future rule tables from silently bypassing their documented preconditions. (#216)
 - VBA extraction now exposes only the classifier factories used by the shared source walker, removing obsolete compatibility entry points and other unused public helpers. (#217)

__tests__/daemon-release.test.ts

@@ -27,7 +27,9 @@ const ALL_TOOLS = tools.map((t) => t.name).join(',');
 function expectReadOnly(tool: ToolDefinition): void {
   expect(tool.annotations, `${tool.name} is missing annotations`).toBeDefined();
   // The hint Cursor Ask mode (and other clients) gate on.
-  expect(tool.annotations!.readOnlyHint).toBe(!['codegraph_index', 'codegraph_sync'].includes(tool.name));
+  expect(tool.annotations!.readOnlyHint).toBe(
+    !['codegraph_index', 'codegraph_sync', 'codegraph_release'].includes(tool.name),
+  );
   // The exact triplet the issue asks for, plus the honest closed-world hint.
   expect(tool.annotations!.destructiveHint).toBe(false);
   expect(tool.annotations!.idempotentHint).toBe(true);
@@ -36,6 +38,15 @@ function expectReadOnly(tool: ToolDefinition): void {
 
 /** Assert each tool's exact read-only or mutating contract. */
 function expectToolAnnotations(tool: ToolDefinition): void {
+  if (tool.name === 'codegraph_release') {
+    expect(tool.annotations).toEqual({
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false,
+    });
+    return;
+  }
   if (tool.name === 'codegraph_uninit') {
     expect(tool.annotations).toEqual({
       readOnlyHint: false,
@@ -86,7 +97,7 @@ describe('Read-only annotations on the codegraph MCP tools (#1018)', () => {
     for (const tool of got) {
       expectToolAnnotations(tool);
       // Sanity: this IS the clone path (projectPath got marked required).
-      if (tool.name !== 'codegraph_init') {
+      if (!['codegraph_init', 'codegraph_release'].includes(tool.name)) {
         expect(tool.inputSchema.required ?? []).toContain('projectPath');
       }
     }

__tests__/mcp-tool-annotations.test.ts

@@ -0,0 +1,43 @@
+# Project-Scoped Daemon Release
+
+## Decision
+
+Provide one explicit release lifecycle per canonical project root across daemon control, watchdog supervision, MCP coordination, and the CLI.
+
+## Scope
+
+The chain adds one explicit project-scoped release operation across daemon lifecycle control, watchdog supervision, MCP proxy coordination, and the non-interactive CLI.
+
+## Non-Negotiable Invariants
+
+- **Generation-safe ownership**: release targets a canonical root and one authenticated daemon generation. It never signals an unverified PID.
+- **Startup exclusion**: startup and release arbitrate ownership before publishing or deleting daemon artifacts.
+- **Intentional release is stable**: watchdog supervision does not immediately respawn a deliberately released root. A later normal CodeGraph launch or query may establish a new lifecycle.
+- **Ordered requests**: a release waits for earlier requests and rejects later project calls on the owning proxy.
+- **Explicit operator access**: MCP release remains opt-in and destructive; CLI release requires an explicit path.
+- **Project isolation**: releasing one root leaves unrelated projects available. Process-wide cleanup is not part of this design.
+- **Idempotent outcomes**: repeated release returns a typed outcome: `released`, `not-running`, `no-daemon`, `identity-mismatch`, `unreachable`, or `termination-failed`.
+- **Resource release only**: release does not remove a worktree or project directory.
+- **Tests travel with behavior**: each child carries focused behavior-first tests and builds independently on Node 22.
+
+## Chain Units
+
+1. Lifecycle arbitration, authenticated generation-safe release, leases, heartbeat recovery, startup exclusion, and core tests.
+2. Watchdog release tombstones, canonical aliases, explicit resume, and focused tests.
+3. Proxy request barriers, per-root coordination, opt-in MCP surface, annotations, and focused tests.
+4. Non-interactive CLI command, daemon manager presentation, parser and integration tests, and final cross-surface coverage.
+
+## Operator Surfaces
+
+The non-interactive CLI surface is `codegraph daemon stop --path <project-root>`. The destructive MCP surface is `codegraph_release`, disabled by default and requiring an explicit `path`.
+
+## Consequences
+
+Each child targets its immediate parent. Reviewers can validate and roll back one behavior boundary at a time while the tracker remains a durable integration map.
+
+## Contributor Checklist
+
+- [ ] Keep each child diff limited to its declared unit.
+- [ ] Run the focused tests and build under Node 22.
+- [ ] Preserve authenticated ownership, startup exclusion, and request ordering.
+- [ ] Do not merge the tracker before all children are integrated.

docs/design/project-scoped-daemon-release.md

@@ -21,7 +21,8 @@ codegraph callers <symbol>        # Find what calls a function/method (--limit,
 codegraph callees <symbol>        # Find what a function/method calls (--limit, --json)
 codegraph impact <symbol>         # Analyze what code is affected by changing a symbol (--depth, --json)
 codegraph affected [files...]     # Find test files affected by changes (see below)
-codegraph daemon                  # Manage background daemons — pick one to stop (alias: daemons)
+codegraph daemon                  # Manage background daemons (alias: daemons)
+codegraph daemon stop --path <project-root> # Release one project's daemon resources
 codegraph telemetry [on|off]      # Show or change anonymous usage telemetry
 codegraph upgrade [version]       # Update to the latest release (--check, --force)
 codegraph version                 # Print the installed version (also -v, --version)
@@ -49,3 +50,13 @@ codegraph impact AuthMiddleware --depth 3
 ## affected
 
 Traces import dependencies transitively to find which test files are affected by changed source files. See [Affected Tests in CI](/codegraph/guides/affected-tests/) for options and a CI example.
+
+## daemon stop
+
+Release CodeGraph resources for one project before deleting its worktree:
+
+```bash
+codegraph daemon stop --path <project-root>
+```
+
+The command is non-interactive and releases only the canonical project root selected by `--path`. It does not remove the worktree or affect CodeGraph daemons for unrelated projects.

site/src/content/docs/reference/cli.md

@@ -39,6 +39,22 @@ CODEGRAPH_MCP_TOOLS=explore,node,search,callers
 
 Each also has a CLI equivalent (`codegraph node` / `query` / `callers` / `callees` / `impact` / `files` / `status`) for scripts and non-MCP harnesses.
 
+## Project release
+
+`codegraph_release` is a destructive lifecycle tool and is disabled by default. Enable it explicitly:
+
+```bash
+CODEGRAPH_MCP_TOOLS=explore,release
+```
+
+Call it with the selected worktree or project root:
+
+```json
+{ "path": "/absolute/path/to/project-root" }
+```
+
+Use it immediately before deleting that worktree. It releases CodeGraph resources for the canonicalized root but does not remove the worktree. Never kill all Node or CodeGraph processes as cleanup: unrelated projects may still be active.
+
 ## How agents should use it
 
 CodeGraph *is* the pre-built search index. For "how does X work?", architecture, a flow ("how does X reach Y"), or where-is-X questions — and while editing code — an agent should answer with `codegraph_explore` and stop, typically with **zero file reads**, rather than re-deriving the answer with `grep` + `Read`. A direct CodeGraph answer is one to a few calls; a grep/read exploration is dozens.

site/src/content/docs/reference/mcp-server.md

@@ -29,6 +29,7 @@
 import '../mcp/early-ppid';
 
 import { Command } from 'commander';
+import { registerDaemonStopCommand } from './daemon-release';
 import * as path from 'path';
 import * as fs from 'fs';
 import { getCodeGraphDir, isInitialized, unsafeIndexRootReason, findNearestCodeGraphRoot, planFrontload, hasStructuralKeyword, extractCodeTokens } from '../directory';
@@ -1640,7 +1641,7 @@ function printFileTree(
  * to pick one (the current project's daemon floats to the top, auto-selected),
  * enter to stop it. Falls back to a plain list when output isn't a TTY.
  */
-program
+const daemonCommand = program
   .command('daemon')
   .aliases(['daemons'])
   .description('Manage running CodeGraph background daemons — pick one and press enter to stop it')
@@ -1683,6 +1684,8 @@ program
     });
   });
 
+registerDaemonStopCommand(daemonCommand);
+
 /**
  * codegraph serve
  */

src/bin/codegraph.ts

@@ -0,0 +1,23 @@
+import { Command } from 'commander';
+import { releaseDaemonAt, type StopResult } from '../mcp/daemon-registry';
+
+/** Testable command handler behind `daemon stop --path`. */
+export async function runDaemonStop(
+  root: string,
+  release: (path: string) => Promise<StopResult> = releaseDaemonAt,
+): Promise<string> {
+  return JSON.stringify(await release(root));
+}
+
+/** Register the non-interactive parser path without importing the full CLI entrypoint. */
+export function registerDaemonStopCommand(
+  parent: Command,
+  run: (path: string) => Promise<string> = runDaemonStop,
+  output: (value: string) => void = console.log,
+): Command {
+  return parent
+    .command('stop')
+    .description('Release the CodeGraph daemon and index locks for one explicit project root')
+    .requiredOption('-p, --path <path>', 'Canonical project root to release')
+    .action(async (options: { path: string }) => output(await run(options.path)));
+}

src/bin/daemon-release.ts

@@ -102,15 +102,18 @@ export async function runDaemonPicker(deps: PickerDeps): Promise<void> {
 
     if (choice === STOP_ALL) {
       const results = await deps.stopAll();
-      const n = results.filter((r) => r.outcome === 'term' || r.outcome === 'kill').length;
+      const n = results.filter((r) => r.outcome === 'released' || r.outcome === 'not-running').length;
       deps.note(`Stopped ${n} daemon${n === 1 ? '' : 's'}.`);
       deps.done('Done.');
       return;
     }
 
     const result = await deps.stop(String(choice));
-    const forced = result.outcome === 'kill' ? ', forced' : '';
-    deps.note(`Stopped daemon (pid ${result.pid}${forced}) — ${choice}`);
+    if (result.outcome === 'released' || result.outcome === 'not-running') {
+      deps.note(`Stopped daemon (pid ${result.pid}) — ${choice}`);
+    } else {
+      deps.note(`Daemon not stopped (${result.outcome}) — ${choice}`);
+    }
     // Loop: the next iteration re-lists; if more remain it re-prompts, otherwise
     // the top-of-loop empty check prints "All daemons stopped."
   }

src/mcp/daemon-manager.ts

@@ -93,6 +93,21 @@ export function getDaemonPidPath(projectRoot: string): string {
   return path.join(getCodeGraphDir(projectRoot), 'daemon.pid');
 }
 
+/** Root-scoped lease held while intentional release owns lifecycle cleanup. */
+export function getDaemonReleaseLeasePath(projectRoot: string): string {
+  return path.join(getCodeGraphDir(projectRoot), 'daemon.release');
+}
+
+/** Exclusive marker for release-lease recovery/heartbeat publication. */
+export function getDaemonReleaseRecoveryPath(projectRoot: string): string {
+  return path.join(getCodeGraphDir(projectRoot), 'daemon.release.recovery');
+}
+
+/** Short root-scoped arbitration lock shared by startup and release publication. */
+export function getDaemonLifecyclePath(projectRoot: string): string {
+  return path.join(getCodeGraphDir(projectRoot), 'daemon.lifecycle');
+}
+
 /** Structured contents of the pid lockfile. */
 export interface DaemonLockInfo {
   pid: number;