grounder 0.0.2 → 0.2.0

package/dist/agents/types.d.ts

@@ -14,7 +14,13 @@ export interface AgentAdapter {
     readonly name: string;
     /** Returns true when this agent appears to be installed on the machine. */
     isInstalled(): Promise<boolean>;
+    /** Absolute paths of artifacts this adapter installs (read-only inspect). */
+    expectedArtifacts(homeDir?: string): string[];
     /** Install all agent-specific artifacts (commands, rules, etc.). */
     install(opts: AgentInstallOptions): Promise<AgentInstallResult>;
+    /** Optional: install session hooks (separate from slash-command install). */
+    installHooks?(opts: AgentInstallOptions): Promise<AgentInstallResult>;
+    /** Optional: absolute path(s) of hook config this adapter would touch. */
+    expectedHookArtifacts?(homeDir?: string): string[];
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/agents/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;AAEnE,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,oEAAoE;IACpE,OAAO,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACjE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agents/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;AAEnE,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,6EAA6E;IAC7E,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC9C,oEAAoE;IACpE,OAAO,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAChE,6EAA6E;IAC7E,YAAY,CAAC,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACtE,0EAA0E;IAC1E,qBAAqB,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACpD"}

package/dist/cli.js

@@ -2,12 +2,15 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { runDoctor } from "./commands/doctor.js";
 import { runHandoffList } from "./commands/handoff/list.js";
+import { runHandoffPeek } from "./commands/handoff/peek.js";
 import { runHandoff } from "./commands/handoff.js";
 import { runNote } from "./commands/note.js";
 import { runPathLogs } from "./commands/path/logs.js";
 import { runPathNotes } from "./commands/path/notes.js";
 import { runRepoInit } from "./commands/repo/init.js";
+import { runStatus } from "./commands/status.js";
 import { runVaultInit } from "./commands/vault/init.js";
 const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const pkg = JSON.parse(readFileSync(path.join(pkgRoot, "package.json"), "utf8"));
@@ -19,8 +22,14 @@ Usage:
   grounder note <text>         Write a note to the vault
   grounder handoff <text>      Write a session handoff to vault logs/
   grounder handoff list        Print recent handoff paths (newest first)
+  grounder handoff list --head Print only the newest usable handoff path
   grounder path notes          Print resolved notes directory
   grounder path logs           Print resolved logs directory
+  grounder status              Snapshot of machine + project link + resolved paths
+  grounder doctor              Health checks with fix hints
+
+Hook plumbing:
+  grounder handoff peek        One-line latest-handoff teaser (used by session hooks)
 
 Options:
   -h, --help     Show this help
@@ -33,13 +42,19 @@ Init flags:
   --vault <path> Override home vault root for this run (grounder init)
   --agent <id>   Install for a specific agent (repeatable; default: auto-detect)
                  Supported: cursor, claude
+  --hooks        Also install session-start teaser hooks (vault init)
+
+Doctor flags:
+  --global       Machine-only checks (skip project/link checks)
 
 Note / handoff flags:
   --title <slug> Short slug in filename (default: slugified first line)
   --limit <n>    Max paths for handoff list (default: 5)
+  --head         With handoff list, print only the newest usable path
+                 (skips empty/unreadable files; same pick as handoff peek)
 
 Quickstart:
-  grounder vault init ~/Documents/obsidian/dev
+  grounder vault init <path-to-your-vault>
   grounder init
   grounder note "my first note"
   grounder handoff "# Handoff\\n\\n## Next\\n1. …"
@@ -74,6 +89,9 @@ async function main() {
     if (command === "handoff" && rest[0] === "list") {
         process.exit(await runHandoffList(rest.slice(1)));
     }
+    if (command === "handoff" && rest[0] === "peek") {
+        process.exit(await runHandoffPeek(rest.slice(1)));
+    }
     if (command === "handoff") {
         process.exit(await runHandoff(rest));
     }
@@ -83,6 +101,12 @@ async function main() {
     if (command === "path" && rest[0] === "logs") {
         process.exit(await runPathLogs(rest.slice(1)));
     }
+    if (command === "status") {
+        process.exit(await runStatus(rest));
+    }
+    if (command === "doctor") {
+        process.exit(await runDoctor(rest));
+    }
     process.stderr.write(`Unknown command: ${args.join(" ")}\n\n`);
     printHelp();
     process.exit(1);

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/commands/check.d.ts

@@ -0,0 +1,13 @@
+/** Shared result shape for doctor (and similar) health checks. */
+export type CheckLevel = "ok" | "fail" | "warn";
+export interface CheckResult {
+    id: string;
+    level: CheckLevel;
+    message: string;
+    /** Actionable fix hint when level is not `"ok"`. */
+    fix?: string;
+}
+export declare function okCheck(id: string, message: string): CheckResult;
+export declare function failCheck(id: string, message: string, fix?: string): CheckResult;
+export declare function warnCheck(id: string, message: string, fix?: string): CheckResult;
+//# sourceMappingURL=check.d.ts.map

package/dist/commands/check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAEhE;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAOhF;AAED,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,WAAW,CAOhF"}

package/dist/commands/check.js

@@ -0,0 +1,21 @@
+/** Shared result shape for doctor (and similar) health checks. */
+export function okCheck(id, message) {
+    return { id, level: "ok", message };
+}
+export function failCheck(id, message, fix) {
+    return {
+        id,
+        level: "fail",
+        message,
+        ...(fix !== undefined ? { fix } : {}),
+    };
+}
+export function warnCheck(id, message, fix) {
+    return {
+        id,
+        level: "warn",
+        message,
+        ...(fix !== undefined ? { fix } : {}),
+    };
+}
+//# sourceMappingURL=check.js.map

package/dist/commands/check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check.js","sourceRoot":"","sources":["../../src/commands/check.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAYlE,MAAM,UAAU,OAAO,CAAC,EAAU,EAAE,OAAe;IACjD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,EAAU,EAAE,OAAe,EAAE,GAAY;IACjE,OAAO;QACL,EAAE;QACF,KAAK,EAAE,MAAM;QACb,OAAO;QACP,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,EAAU,EAAE,OAAe,EAAE,GAAY;IACjE,OAAO;QACL,EAAE;QACF,KAAK,EAAE,MAAM;QACb,OAAO;QACP,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtC,CAAC;AACJ,CAAC"}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,9 @@
+export interface DoctorOptions {
+    cwd?: string;
+    homeDir?: string;
+    /** Machine-only checks (skip project/link checks). */
+    global?: boolean;
+}
+export declare function runDoctor(argv: string[]): Promise<number>;
+export declare function runDoctorWithOptions(options?: DoctorOptions): Promise<number>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAyTD,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAG/D;AAED,wBAAsB,oBAAoB,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBvF"}

package/dist/commands/doctor.js

@@ -0,0 +1,270 @@
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { isGrounderPeekHookCommand, isHookRuntimeStale } from "../agents/hook-runtime.js";
+import { resolveAgents } from "../agents/index.js";
+import { findGitRoot } from "../connector/git.js";
+import { homeConfigPath, readHomeConfig, withHomeDir } from "../connector/home.js";
+import { findLinkedRepoRoot, readRepoConfig } from "../connector/repo.js";
+import { resolveLogsDir, resolveNotesDir, resolveVaultRoot } from "../connector/vault.js";
+import { fileExists } from "../util/fs.js";
+import { flagBool, parseArgs } from "../util/parse-args.js";
+import { projectsParent } from "../vault/layout.js";
+import { failCheck, okCheck, warnCheck } from "./check.js";
+const VAULT_INIT = "grounder vault init <path>";
+const VAULT_INIT_FORCE = "grounder vault init <path> --force";
+const VAULT_INIT_HOOKS = "grounder vault init <path> --hooks";
+const REPO_INIT = "grounder init";
+async function isDirectory(dirPath) {
+    try {
+        const info = await stat(dirPath);
+        return info.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function formatCheck(check) {
+    const level = check.level.padEnd(4);
+    const id = check.id.padEnd(18);
+    const fix = check.fix ? ` → ${check.fix}` : "";
+    return `  ${level}  ${id}  ${check.message}${fix}\n`;
+}
+function writeSection(title, checks) {
+    process.stdout.write(`${title}\n`);
+    for (const check of checks) {
+        process.stdout.write(formatCheck(check));
+    }
+}
+function summarize(checks) {
+    const passed = checks.filter((c) => c.level === "ok").length;
+    const failed = checks.filter((c) => c.level === "fail").length;
+    const warned = checks.filter((c) => c.level === "warn").length;
+    return `${passed} passed, ${failed} failed, ${warned} warned\n`;
+}
+async function checkHomeConfig() {
+    const configPath = homeConfigPath();
+    if (!(await fileExists(configPath))) {
+        return {
+            check: failCheck("home-config", "home config missing", VAULT_INIT),
+            home: null,
+        };
+    }
+    try {
+        const home = await readHomeConfig();
+        if (!home) {
+            return {
+                check: failCheck("home-config", "home config missing", VAULT_INIT),
+                home: null,
+            };
+        }
+        return {
+            check: okCheck("home-config", `home config present (${configPath})`),
+            home,
+        };
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return {
+            check: failCheck("home-config", `home config invalid: ${detail}`, VAULT_INIT),
+            home: null,
+        };
+    }
+}
+async function checkVault(home) {
+    if (!home) {
+        return {
+            check: failCheck("vault", "cannot resolve vault (no home config)", VAULT_INIT),
+            vaultRoot: null,
+        };
+    }
+    const vaultRoot = resolveVaultRoot(home);
+    if (!(await isDirectory(vaultRoot))) {
+        return {
+            check: failCheck("vault", `${vaultRoot} missing or not a directory`, "Fix path or re-run vault init"),
+            vaultRoot: null,
+        };
+    }
+    return {
+        check: okCheck("vault", `vault reachable (${vaultRoot})`),
+        vaultRoot,
+    };
+}
+async function checkProjectsDir(vaultRoot) {
+    if (!vaultRoot) {
+        return failCheck("projects-dir", "cannot check 10-Projects/ (no vault)", VAULT_INIT);
+    }
+    const projectsDir = projectsParent(vaultRoot);
+    if (!(await isDirectory(projectsDir))) {
+        return failCheck("projects-dir", `${projectsDir} missing`, `${VAULT_INIT} (idempotent)`);
+    }
+    return okCheck("projects-dir", `10-Projects/ present (${projectsDir})`);
+}
+async function checkAgentArtifacts(homeDir) {
+    const agents = await resolveAgents();
+    const checks = [];
+    for (const agent of agents) {
+        const expected = agent.expectedArtifacts(homeDir);
+        const present = await Promise.all(expected.map((p) => fileExists(p)));
+        const presentCount = present.filter(Boolean).length;
+        const id = `agent-${agent.id}`;
+        if (presentCount === expected.length) {
+            checks.push(okCheck(id, `${agent.name} command files present`));
+            continue;
+        }
+        const fix = `${VAULT_INIT_FORCE} (or --agent=${agent.id})`;
+        if (presentCount === 0) {
+            checks.push(warnCheck(id, `${agent.name} detected but no Grounder command files`, fix));
+        }
+        else {
+            const missing = expected.filter((_, i) => !present[i]);
+            checks.push(failCheck(id, `${agent.name} missing ${missing.length} command file(s): ${missing.map((p) => path.basename(p)).join(", ")}`, fix));
+        }
+    }
+    return checks;
+}
+/** True when any nested `command` field is Grounder's peek hook (Cursor or Claude shape). */
+function jsonContainsGrounderPeekCommand(value) {
+    if (Array.isArray(value)) {
+        return value.some(jsonContainsGrounderPeekCommand);
+    }
+    if (value && typeof value === "object") {
+        const obj = value;
+        if (isGrounderPeekHookCommand(obj.command)) {
+            return true;
+        }
+        return Object.values(obj).some(jsonContainsGrounderPeekCommand);
+    }
+    return false;
+}
+async function hookFileHasGrounderEntry(filePath) {
+    try {
+        if (!(await fileExists(filePath))) {
+            return false;
+        }
+        const parsed = JSON.parse(await readFile(filePath, "utf8"));
+        return jsonContainsGrounderPeekCommand(parsed);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Warn-only: session hooks are opt-in. Missing entry never fails doctor.
+ * One check per detected agent that declares `expectedHookArtifacts`.
+ *
+ * When at least one agent has a Grounder hook installed, also check the shared
+ * `~/.grounder/runtime` materialization — stale mainly for bare-npx copy installs
+ * after an upgrade (symlink installs stay current without re-init).
+ */
+async function checkAgentHooks(homeDir) {
+    const agents = await resolveAgents();
+    const checks = [];
+    let anyHooksInstalled = false;
+    for (const agent of agents) {
+        if (!agent.expectedHookArtifacts) {
+            continue;
+        }
+        const expected = agent.expectedHookArtifacts(homeDir);
+        const present = await Promise.all(expected.map((p) => hookFileHasGrounderEntry(p)));
+        const id = `agent-${agent.id}-hooks`;
+        if (present.every(Boolean) && expected.length > 0) {
+            anyHooksInstalled = true;
+            checks.push(okCheck(id, `${agent.name} session hook installed`));
+        }
+        else {
+            checks.push(warnCheck(id, `${agent.name} detected but no Grounder session hook`, VAULT_INIT_HOOKS));
+        }
+    }
+    if (anyHooksInstalled) {
+        if (await isHookRuntimeStale(homeDir)) {
+            checks.push(warnCheck("hook-runtime", "hook runtime stale or missing (re-run after upgrading, especially bare npx)", VAULT_INIT_HOOKS));
+        }
+        else {
+            checks.push(okCheck("hook-runtime", "hook runtime current"));
+        }
+    }
+    return checks;
+}
+async function runMachineChecks(homeDir) {
+    const { check: homeCheck, home } = await checkHomeConfig();
+    const { check: vaultCheck, vaultRoot } = await checkVault(home);
+    const projectsCheck = await checkProjectsDir(vaultRoot);
+    const agentChecks = await checkAgentArtifacts(homeDir);
+    const hookChecks = await checkAgentHooks(homeDir);
+    return {
+        checks: [homeCheck, vaultCheck, projectsCheck, ...agentChecks, ...hookChecks],
+        home,
+    };
+}
+async function runProjectChecks(cwd, home) {
+    const checks = [];
+    const gitRoot = await findGitRoot(cwd);
+    const linkedRoot = await findLinkedRepoRoot(cwd, gitRoot);
+    if (!linkedRoot) {
+        checks.push(failCheck("repo-config", "no .grounder.json uptree", REPO_INIT));
+        checks.push(failCheck("repo-config-valid", "cannot validate projectId (no repo config)", REPO_INIT));
+        checks.push(failCheck("notes-dir", "cannot resolve notes/ (no repo config)", REPO_INIT));
+        checks.push(failCheck("logs-dir", "cannot resolve logs/ (no repo config)", REPO_INIT));
+    }
+    else {
+        checks.push(okCheck("repo-config", `repo config present (${path.join(linkedRoot, ".grounder.json")})`));
+        let repo = null;
+        try {
+            repo = await readRepoConfig(linkedRoot);
+            if (!repo) {
+                checks.push(failCheck("repo-config-valid", "missing or invalid projectId", `Fix or re-run ${REPO_INIT} --force`));
+            }
+            else {
+                checks.push(okCheck("repo-config-valid", `projectId ok (${repo.projectId})`));
+            }
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            checks.push(failCheck("repo-config-valid", `invalid repo config: ${detail}`, `Fix or re-run ${REPO_INIT} --force`));
+        }
+        if (!home || !repo) {
+            const reason = !home ? "no home config" : "no valid repo config";
+            const fix = !home ? VAULT_INIT : REPO_INIT;
+            checks.push(failCheck("notes-dir", `cannot resolve notes/ (${reason})`, fix));
+            checks.push(failCheck("logs-dir", `cannot resolve logs/ (${reason})`, fix));
+        }
+        else {
+            const notes = resolveNotesDir(home, repo);
+            const logs = resolveLogsDir(home, repo);
+            checks.push((await isDirectory(notes))
+                ? okCheck("notes-dir", `notes/ present (${notes})`)
+                : failCheck("notes-dir", `${notes} missing`, `${REPO_INIT} (creates dirs)`));
+            checks.push((await isDirectory(logs))
+                ? okCheck("logs-dir", `logs/ present (${logs})`)
+                : failCheck("logs-dir", `${logs} missing`, REPO_INIT));
+        }
+    }
+    if (!gitRoot) {
+        checks.push(warnCheck("git", "no git repository found (optional)"));
+    }
+    else {
+        checks.push(okCheck("git", `git root (${gitRoot})`));
+    }
+    return checks;
+}
+export async function runDoctor(argv) {
+    const { flags } = parseArgs(argv);
+    return runDoctorWithOptions({ global: flagBool(flags, "global") });
+}
+export async function runDoctorWithOptions(options = {}) {
+    return withHomeDir(options.homeDir, async () => {
+        const cwd = path.resolve(options.cwd ?? process.cwd());
+        const { checks: machineChecks, home } = await runMachineChecks(options.homeDir);
+        const projectChecks = options.global ? [] : await runProjectChecks(cwd, home);
+        const checks = [...machineChecks, ...projectChecks];
+        writeSection("Machine", machineChecks);
+        if (!options.global) {
+            process.stdout.write("\n");
+            writeSection("Project", projectChecks);
+        }
+        process.stdout.write("\n");
+        process.stdout.write(summarize(checks));
+        return checks.some((c) => c.level === "fail") ? 1 : 0;
+    });
+}
+//# sourceMappingURL=doctor.js.map

package/dist/commands/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"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"}

package/dist/commands/handoff/list.d.ts

@@ -4,6 +4,12 @@ export interface HandoffListOptions {
     cwd?: string;
     /** Max paths to print, newest first (default: 5). */
     limit?: number;
+    /**
+     * Print only the single newest *usable* handoff path (skips empty/unreadable
+     * files), same selection `grounder handoff peek` uses. Ignores `limit` for
+     * output count but still bounds the fallback scan.
+     */
+    head?: boolean;
     /** Override home dir / `GROUNDER_HOME` (tests). */
     homeDir?: string;
 }
@@ -17,6 +23,9 @@ export declare function runHandoffList(argv: string[]): Promise<number>;
  * Resolves the linked project, lists recent handoff paths under `logs/` (newest first).
  * Prints one absolute path per line; empty when no handoffs. Same vault/link
  * prerequisites as `grounder handoff`.
+ * With `head: true`, prints only the single newest *usable* handoff path — see
+ * {@link findUsableHandoff}. This is the selection `/grounder-task` should read,
+ * matching what `grounder handoff peek` teases.
  * @returns Exit code (`0` on success, `1` when vault/link is missing).
  */
 export declare function runHandoffListWithOptions(options?: HandoffListOptions): Promise<number>;

package/dist/commands/handoff/list.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/commands/handoff/list.ts"],"names":[],"mappings":"AAQA,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AASD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BpE;AAED;;;;;GAKG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBjG"}
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/commands/handoff/list.ts"],"names":[],"mappings":"AASA,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AASD;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA2BpE;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CA0BjG"}

package/dist/commands/handoff/list.js

@@ -1,10 +1,11 @@
 import { withHomeDir } from "../../connector/home.js";
 import { resolveLogsDir } from "../../connector/vault.js";
-import { parseArgs } from "../../util/parse-args.js";
+import { flagBool, parseArgs } from "../../util/parse-args.js";
+import { findUsableHandoff } from "../../vault/find-usable-handoff.js";
 import { listHandoffs } from "../../vault/list-handoffs.js";
 import { requireLinkedProject } from "../require-linked.js";
 const DEFAULT_LIMIT = 5;
-const USAGE = "Usage: grounder handoff list [--limit <n>]\n";
+const USAGE = "Usage: grounder handoff list [--limit <n>] [--head]\n";
 function usageError() {
     process.stderr.write(USAGE);
     return 1;
@@ -20,7 +21,7 @@ export async function runHandoffList(argv) {
         return usageError();
     }
     for (const key of flags.keys()) {
-        if (key !== "limit") {
+        if (key !== "limit" && key !== "head") {
             return usageError();
         }
     }
@@ -37,12 +38,15 @@ export async function runHandoffList(argv) {
         }
         limit = parsed;
     }
-    return runHandoffListWithOptions({ limit });
+    return runHandoffListWithOptions({ limit, head: flagBool(flags, "head") });
 }
 /**
  * Resolves the linked project, lists recent handoff paths under `logs/` (newest first).
  * Prints one absolute path per line; empty when no handoffs. Same vault/link
  * prerequisites as `grounder handoff`.
+ * With `head: true`, prints only the single newest *usable* handoff path — see
+ * {@link findUsableHandoff}. This is the selection `/grounder-task` should read,
+ * matching what `grounder handoff peek` teases.
  * @returns Exit code (`0` on success, `1` when vault/link is missing).
  */
 export async function runHandoffListWithOptions(options = {}) {
@@ -52,6 +56,13 @@ export async function runHandoffListWithOptions(options = {}) {
             return 1;
         }
         const logsDir = resolveLogsDir(linked.home, linked.repo);
+        if (options.head) {
+            const usable = await findUsableHandoff(logsDir, { limit: options.limit ?? DEFAULT_LIMIT });
+            if (usable) {
+                process.stdout.write(`${usable.path}\n`);
+            }
+            return 0;
+        }
         const paths = await listHandoffs(logsDir, {
             limit: options.limit ?? DEFAULT_LIMIT,
         });

package/dist/commands/handoff/list.js.map

@@ -1 +1 @@
-{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../src/commands/handoff/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,aAAa,GAAG,CAAC,CAAC;AAYxB,MAAM,KAAK,GAAG,8CAA8C,CAAC;AAE7D,SAAS,UAAU;IACjB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC5B,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAc;IACjD,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9C,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,OAAO,UAAU,EAAE,CAAC;IACtB,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC/B,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;YACpB,OAAO,UAAU,EAAE,CAAC;QACtB,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,KAAK,GAAG,aAAa,CAAC;IAC1B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACjC,OAAO,UAAU,EAAE,CAAC;QACtB,CAAC;QACD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;QAChC,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC5C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YACjE,OAAO,UAAU,EAAE,CAAC;QACtB,CAAC;QACD,KAAK,GAAG,MAAM,CAAC;IACjB,CAAC;IAED,OAAO,yBAAyB,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,UAA8B,EAAE;IAC9E,OAAO,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC;QACX,CAAC;QAED,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QACzD,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE;YACxC,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,aAAa;SACtC,CAAC,CAAC;QAEH,KAAK,MAAM,QAAQ,IAAI,KAAK,EAAE,CAAC;YAC7B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,QAAQ,IAAI,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../src/commands/handoff/list.ts"],"names":[],"mappings":"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"}

package/dist/commands/handoff/peek.d.ts

@@ -0,0 +1,38 @@
+/** Options for {@link runHandoffPeekWithOptions} (CLI and tests). */
+export interface HandoffPeekOptions {
+    /** Directory used to find the linked repo (default: `process.cwd()`). */
+    cwd?: string;
+    /** Override home dir / `GROUNDER_HOME` (tests). */
+    homeDir?: string;
+    /**
+     * When true, always emit one JSON line for Cursor's `sessionStart` contract
+     * (`{ additional_context }` or `{}`). Default plain-text output is for Claude.
+     */
+    json?: boolean;
+}
+/**
+ * Derive a display label from a handoff filename when frontmatter has no title:
+ * strip the timestamp prefix and `.md`, replace `-` with spaces.
+ */
+export declare function labelFromHandoffFilename(filePath: string): string;
+/**
+ * CLI entry for `grounder handoff peek`.
+ * Silent by default: prints nothing and exits 0 when unlinked, empty, or on any error.
+ * Used by session-start hooks — must never crash or print noise.
+ * Reads Cursor hook stdin for `workspace_roots[0]` when present; falls back to
+ * `CURSOR_PROJECT_DIR` (user-level hooks often run with cwd under `~/.cursor`).
+ * Pass `--json` for Cursor's `additional_context` stdout contract.
+ * @returns Always `0`.
+ */
+export declare function runHandoffPeek(argv: string[]): Promise<number>;
+/**
+ * Resolves the linked project and prints a one-line teaser for the newest *usable*
+ * handoff, or nothing. "Usable" (via {@link findUsableHandoff}) skips empty/unreadable
+ * files and falls back to the next-newest — the same selection `grounder handoff list
+ * --head` uses, so the teaser and `/grounder-task` never disagree about which handoff
+ * is current.
+ * Uses {@link resolveLinkedProject} directly (not `requireLinkedProject`) so failures stay silent.
+ * @returns Always `0`.
+ */
+export declare function runHandoffPeekWithOptions(options?: HandoffPeekOptions): Promise<number>;
+//# sourceMappingURL=peek.d.ts.map

package/dist/commands/handoff/peek.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peek.d.ts","sourceRoot":"","sources":["../../../src/commands/handoff/peek.ts"],"names":[],"mappings":"AASA,qEAAqE;AACrE,MAAM,WAAW,kBAAkB;IACjC,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAKD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAWjE;AA4CD;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAOpE;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BjG"}