@leantli/agent-handoff 0.4.0 → 0.5.1

package/README.md

@@ -1,132 +1,122 @@
 # agent-handoff
 
-`agent-handoff` gives Codex and Claude Code a shared memory handoff layer across
-new sessions, fresh clones, git worktrees, and devices.
+`agent-handoff` gives coding agents a small shared memory layer for new
+sessions, fresh clones, git worktrees, and devices.
 
-A long agent session often accumulates useful context: project background,
-current task state, decisions, preferences, and repeated corrections. Without a
-handoff layer, a new session or another device starts cold.
+Long agent sessions accumulate useful context: project background, current task
+state, decisions, preferences, and repeated corrections. Without a handoff
+layer, the next session starts cold.
 
-`agent-handoff` stores that context in a user-level vault, then lets any clone or
-worktree of the same repository recover it by project identity.
+`agent-handoff` stores that context under `~/.agent-handoff` by default. It does
+not modify `AGENTS.md`, `CLAUDE.md`, or other project instruction files.
 
-```text
-~/.agent-handoff/vault/        # private user memory
-repo/.agent-handoff.yml        # lightweight project identity
-repo/AGENTS.md                 # Codex bootstrap instruction
-repo/CLAUDE.md                 # Claude Code bootstrap instruction
-```
-
-## Install
-
-From npm:
+## Quick Start
 
 ```bash
 npm install -g @leantli/agent-handoff
+agent-handoff enable
 ```
 
-From a checkout:
+GitHub direct install is also supported:
 
 ```bash
-npm install
-npm run build
-npm link
+npm install -g github:leantli/agent-handoff
+agent-handoff enable
 ```
 
-## Three-Minute Setup
+`enable` does two things:
 
-Create your local vault once:
+- creates local memory under `~/.agent-handoff`
+- installs the packaged skill under `~/.agents/skills/agent-handoff`
 
-```bash
-agent-handoff setup
-agent-handoff install-skill
-```
+Agents that load user-level skills can then discover when to run
+`agent-handoff start`, `checkpoint`, `learn`, and `sync`. Existing agent
+sessions may need to be restarted before they see the new skill.
 
-Optional: sync the vault through a private git repo so another device can share
-the same handoff memory:
+The tool never edits `AGENTS.md`, `CLAUDE.md`, or project instruction files.
 
-```bash
-agent-handoff setup --sync git@github.com:you/agent-handoff-vault.git
-```
+## Daily Workflow
 
-Bootstrap each coding project once:
+Run project-aware commands from inside the real project repository, not from a
+parent workspace that contains many repositories.
 
-```bash
-agent-handoff init
-```
+At the start of a coding session in a repo:
 
-This writes:
-
-```text
-.agent-handoff.yml
-AGENTS.md
-CLAUDE.md
+```bash
+agent-handoff status
+agent-handoff start
 ```
 
-It does not write private memory into the project repository.
-
-## Daily Workflow
+If `status` says sync is configured and you are switching devices or clones, run
+`agent-handoff sync` before `start`.
 
-At the start of a new Codex or Claude Code session:
+Before switching sessions, tasks, clones, or devices:
 
 ```bash
-agent-handoff sync     # only if vault sync is configured
-agent-handoff start
+agent-handoff checkpoint --note "Current goal, completed work, open questions, next step."
 ```
 
-Paste or let the agent read the start packet before it works.
-
-When a useful session is about to end, or before switching devices:
+When the user gives a stable preference or recurring correction:
 
 ```bash
-agent-handoff checkpoint --note "Implemented vault storage; next step is README polish."
-agent-handoff sync     # only if vault sync is configured
+agent-handoff learn --kind preference --note "Prefer small focused diffs."
 ```
 
-When the user corrects a stable preference or recurring rule:
+For project-specific decisions or branch-specific context:
 
 ```bash
-agent-handoff learn --kind preference --note "Prefer TDD for behavior changes."
+agent-handoff learn --scope project --kind decision --note "Use TypeScript for the CLI."
+agent-handoff learn --scope branch --kind context --note "This branch is testing v0.5."
 ```
 
-For project-specific decisions or branch-specific context:
+## Cross-Device Sync
+
+Local cross-session memory works immediately after `agent-handoff enable`. No
+git repository is needed for the vault.
+
+Cross-device sync is optional. To share memory across devices, create a private
+git repository for the vault, then run:
 
 ```bash
-agent-handoff learn --scope project --kind decision --note "Use vault-first storage."
-agent-handoff learn --scope branch --kind context --note "Main is preparing v0.3."
+agent-handoff sync init git@github.com:you/agent-handoff-vault.git
+agent-handoff sync
 ```
 
-When configured, `sync` commits pending vault changes and pushes them to the
-private vault repository.
+Run `agent-handoff sync init <same-git-url>` once on each device that should
+share the vault. After that, run `agent-handoff sync` before starting on another
+device and after writing useful checkpoints.
 
-## Why This Solves Cross-Clone Context
+## How Projects Are Identified
 
-`agent-handoff` identifies a project from `.agent-handoff.yml` or the git
-`origin` remote. These all map to the same vault project:
+By default, `agent-handoff` identifies the current project from the git `origin`
+remote. Different clones, sibling checkouts, or worktrees of the same repository
+map to the same project memory:
 
 ```text
-~/code/repo
-~/tmp/repo
-~/worktrees/repo-feature
-another device's ~/projects/repo
+https://github.com/p1cn/loop.git
+git@github.com:p1cn/loop.git
+
+github.com__p1cn__loop
 ```
 
-For example, both remotes below normalize to the same project id:
+If `.agent-handoff.yml` exists, its `project_id` is used as an override. The
+tool does not require this file for normal git repositories.
 
-```text
-https://github.com/leantli/agent-handoff.git
-git@github.com:leantli/agent-handoff.git
+In a workspace like this:
 
-github.com__leantli__agent-handoff
+```text
+~/workspace/
+  app-one/
+  app-two/
+  app-three/
 ```
 
-That means A session can checkpoint context into the vault, and B session can
-recover it from any clone or worktree that resolves to the same project id.
+run `agent-handoff start`, `checkpoint`, and project or branch `learn` commands
+from `~/workspace/app-one`, `~/workspace/app-two`, or whichever repository is
+actually being edited. Global preferences can be written from anywhere.
 
 ## What Gets Stored
 
-The vault is private user state:
-
 ```text
 ~/.agent-handoff/
   config.json
@@ -146,64 +136,30 @@ The vault is private user state:
           20260508T103000Z-laptop-codex-main.md
 ```
 
-The project repository gets only bootstrap files:
+The layers are:
 
-```text
-.agent-handoff.yml
-AGENTS.md
-CLAUDE.md
-```
+- `global`: preferences and lessons that apply across projects.
+- `project`: durable background, decisions, and preferences for one repository.
+- `branch`: task or branch-specific context.
+- `checkpoints`: recent session handoff notes.
 
 ## Commands
 
 ```bash
-agent-handoff setup       # create/configure the user vault
-agent-handoff install-skill # install the agent workflow skill
-agent-handoff init        # bootstrap the current repo
-agent-handoff start       # print the context packet for a new session
+agent-handoff enable      # create local memory and install the user skill
+agent-handoff start       # print context for the current project and branch
 agent-handoff checkpoint  # write a session checkpoint
-agent-handoff learn       # write durable global/project/branch memory
-agent-handoff sync        # git pull/rebase + push the vault
-agent-handoff status      # quick readiness check
-agent-handoff doctor      # detailed health check
-```
-
-## Agent Skill
-
-This repo includes a Codex-compatible skill:
-
-```text
-.agents/skills/agent-handoff/SKILL.md
-```
-
-The skill tells an agent when to run `start`, `checkpoint`, `learn`, and `sync`.
-Install it into your user skills directory to make the workflow available across
-all repositories:
-
-```bash
-agent-handoff install-skill
+agent-handoff learn       # store durable global/project/branch memory
+agent-handoff sync init   # enable optional cross-device sync
+agent-handoff sync        # pull/rebase and push the vault
+agent-handoff status      # quick readiness and sync-state check
 ```
 
-The repo also keeps a copy at `.agents/skills/agent-handoff/SKILL.md` for
-project-local use.
-
-## Status
-
-This is an early prototype. It does not read proprietary chat transcripts or
-client-internal state. Agents must still call `start`, `checkpoint`, and `learn`
-at the right moments, guided by `AGENTS.md` and `CLAUDE.md`.
-
 ## Development
 
-Run tests:
-
 ```bash
+npm install
 npm test
-```
-
-Run type checking and build:
-
-```bash
 npm run typecheck
 npm run build
 ```

package/dist/cli.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
-import { Command, CommanderError, InvalidArgumentError, Option } from "commander";
-import { HandoffError, buildStartPacket, doctor, getStatus, initRepo, installSkill, learn, setupHome, syncVault, writeCheckpoint, } from "./core.js";
+import { Command, CommanderError, Option } from "commander";
+import { HandoffError, buildStartPacket, enableHandoff, enableSync, getStatus, learn, syncVault, writeCheckpoint, } from "./core.js";
 export function main(argv = process.argv.slice(2), opts = {}) {
     const stdout = opts.stdout ?? process.stdout;
     const stderr = opts.stderr ?? process.stderr;
@@ -24,8 +24,8 @@ function buildProgram(stdout, stderr, stdin, cwd) {
     const program = new Command();
     program
         .name("agent-handoff")
-        .description("Shared vault handoff memory for Codex and Claude Code.")
-        .version("agent-handoff 0.4.0")
+        .description("Shared vault handoff memory for coding agents.")
+        .version("agent-handoff 0.5.1")
         .exitOverride()
         .configureOutput({
         writeOut: (str) => stdout.write(str),
@@ -33,42 +33,19 @@ function buildProgram(stdout, stderr, stdin, cwd) {
     })
         .option("--home <path>", "Agent handoff home directory. Defaults to ~/.agent-handoff.");
     program
-        .command("setup")
-        .description("Create or configure the user vault.")
+        .command("enable")
+        .description("Enable local handoff memory and install the user skill.")
         .option("--vault <path>", "Vault directory. Defaults to HOME/vault.")
-        .option("--sync <url>", "Optional git remote URL for vault sync.")
-        .action((options) => {
-        const result = setupHome({ home: globalHome(program), vault: options.vault, syncUrl: options.sync });
-        stdout.write(`Agent handoff home: ${result.home}\n`);
-        stdout.write(`Vault: ${result.vault}\n`);
-    });
-    program
-        .command("install-skill")
-        .description("Install the agent-handoff skill into a user skills directory.")
         .option("--skills-home <path>", "Skills home directory. Defaults to ~/.agents/skills.")
         .action((options) => {
-        const result = installSkill({ skillsHome: options.skillsHome });
-        const verb = result.updated ? "Installed skill" : "Skill already installed";
-        stdout.write(`${verb}: ${result.path}\n`);
-    });
-    program
-        .command("init")
-        .description("Bootstrap this repo for agent handoff.")
-        .option("--project-id <id>", "Override detected project id.")
-        .option("--branch <branch>", "Override detected branch.")
-        .addOption(new Option("--client <client>", "Client bootstrap to install. Repeat to install multiple. Defaults to both.")
-        .choices(["codex", "claude"])
-        .argParser(collect))
-        .action((options) => {
-        const result = initRepo({
-            root: cwd,
+        const result = enableHandoff({
             home: globalHome(program),
-            projectId: options.projectId,
-            branch: options.branch,
-            clients: options.client,
+            vault: options.vault,
+            skillsHome: options.skillsHome,
         });
-        stdout.write(`Initialized agent handoff for ${result.projectId}.\n`);
-        stdout.write(`Vault project: ${result.vaultProject}\n`);
+        stdout.write(`Agent handoff enabled: ${result.setup.home}\n`);
+        stdout.write(`Vault: ${result.setup.vault}\n`);
+        stdout.write(`Skill: ${result.skill.path}\n`);
     });
     program
         .command("start")
@@ -83,7 +60,7 @@ function buildProgram(stdout, stderr, stdin, cwd) {
         .option("--note <text>", "Note text. If omitted, stdin is used.")
         .option("--file <path>", "Read note text from a file.")
         .option("--device <name>", "Device name for the checkpoint.")
-        .option("--agent <name>", "Agent/client name, such as codex or claude.")
+        .option("--agent <name>", "Agent/client label for checkpoint metadata.")
         .option("--branch <branch>", "Override detected branch.")
         .action((options) => {
         const result = writeCheckpoint({
@@ -114,10 +91,17 @@ function buildProgram(stdout, stderr, stdin, cwd) {
         });
         stdout.write(`Learned ${result.kind}: ${result.path}\n`);
     });
-    program
-        .command("sync")
-        .description("Pull and push the vault git repository.")
-        .action(() => {
+    const sync = program.command("sync").description("Sync the handoff vault.");
+    sync
+        .command("init <git-url>")
+        .description("Enable cross-device sync with a private git repository.")
+        .option("--vault <path>", "Vault directory. Defaults to HOME/vault.")
+        .action((gitUrl, options) => {
+        const result = enableSync({ home: globalHome(program), vault: options.vault, syncUrl: gitUrl });
+        stdout.write(`Cross-device sync enabled: ${gitUrl}\n`);
+        stdout.write(`Vault: ${result.vault}\n`);
+    });
+    sync.action(() => {
         for (const output of syncVault({ home: globalHome(program) })) {
             if (output)
                 stdout.write(`${output}\n`);
@@ -130,36 +114,23 @@ function buildProgram(stdout, stderr, stdin, cwd) {
         const status = getStatus({ root: cwd, home: globalHome(program) });
         if (status.initialized) {
             stdout.write(`Agent handoff is ready for ${status.projectId}.\n`);
+            if (status.syncConfigured) {
+                stdout.write(`Sync: configured (${status.syncUrl})\n`);
+            }
+            else {
+                stdout.write("Sync: not configured\n");
+            }
         }
         else {
             printProblems(status.problems, stdout);
             throw new CommanderError(1, "agent-handoff.status", "status failed");
         }
     });
-    program
-        .command("doctor")
-        .description("Check bootstrap and vault health.")
-        .action(() => {
-        const report = doctor({ root: cwd, home: globalHome(program) });
-        if (report.ok) {
-            stdout.write(`Agent handoff is healthy for ${report.projectId}.\n`);
-        }
-        else {
-            printProblems(report.problems, stdout);
-            throw new CommanderError(1, "agent-handoff.doctor", "doctor failed");
-        }
-    });
     return program;
 }
 function globalHome(program) {
     return program.opts().home;
 }
-function collect(value, previous) {
-    if (value !== "codex" && value !== "claude") {
-        throw new InvalidArgumentError("client must be codex or claude");
-    }
-    return [...(previous ?? []), value];
-}
 function readNote(options, stdin) {
     if (options.note)
         return options.note;

package/dist/core.d.ts

@@ -1,7 +1,6 @@
 export declare const DEFAULT_HOME: string;
 export declare const CONFIG_FILE = "config.json";
 export declare const BOOTSTRAP_FILE = ".agent-handoff.yml";
-type Client = "codex" | "claude";
 type LearnScope = "global" | "project" | "branch";
 type LearnKind = "preference" | "lesson" | "decision" | "context";
 export declare class HandoffError extends Error {
@@ -13,13 +12,9 @@ export interface SetupResult {
     created: number;
     updated: number;
 }
-export interface InitResult {
-    created: number;
-    updated: number;
-    root: string;
-    projectId: string;
-    vaultProject: string;
-    clients: Client[];
+export interface EnableResult {
+    setup: SetupResult;
+    skill: InstallSkillResult;
 }
 export interface CheckpointResult {
     path: string;
@@ -41,12 +36,8 @@ export interface Status {
     problems: string[];
     root: string;
     projectId: string | null;
-}
-export interface DoctorReport {
-    ok: boolean;
-    problems: string[];
-    root: string;
-    projectId: string | null;
+    syncConfigured: boolean;
+    syncUrl?: string;
 }
 export declare function setupHome(opts?: {
     home?: string;
@@ -57,13 +48,16 @@ export declare function normalizeProjectId(value: string): string;
 export declare function installSkill(opts?: {
     skillsHome?: string;
 }): InstallSkillResult;
-export declare function initRepo(opts?: {
-    root?: string;
+export declare function enableHandoff(opts?: {
     home?: string;
-    projectId?: string;
-    branch?: string;
-    clients?: string[];
-}): InitResult;
+    vault?: string;
+    skillsHome?: string;
+}): EnableResult;
+export declare function enableSync(opts: {
+    home?: string;
+    vault?: string;
+    syncUrl: string;
+}): SetupResult;
 export declare function deriveProjectId(root?: string, projectId?: string): string;
 export declare function currentBranch(root?: string): string;
 export declare function buildStartPacket(opts?: {
@@ -96,8 +90,4 @@ export declare function getStatus(opts?: {
     root?: string;
     home?: string;
 }): Status;
-export declare function doctor(opts?: {
-    root?: string;
-    home?: string;
-}): DoctorReport;
 export {};

package/dist/core.js

@@ -6,13 +6,12 @@ import { fileURLToPath } from "node:url";
 export const DEFAULT_HOME = join(homedir(), ".agent-handoff");
 export const CONFIG_FILE = "config.json";
 export const BOOTSTRAP_FILE = ".agent-handoff.yml";
-const MANAGED_BEGIN = "<!-- BEGIN AGENT-HANDOFF -->";
-const MANAGED_END = "<!-- END AGENT-HANDOFF -->";
 const SECRET_PATTERNS = [
     /(api[_-]?key|token|secret|password)\s*[:=]/i,
     /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
     /\bsk-[A-Za-z0-9_-]{8,}\b/,
 ];
+const GIT_TIMEOUT_MS = 30_000;
 export class HandoffError extends Error {
     constructor(message) {
         super(message);
@@ -28,6 +27,13 @@ export function setupHome(opts = {}) {
         mkdirSync(homePath, { recursive: true });
         created += 1;
     }
+    if (opts.syncUrl) {
+        validateSyncRemote(homePath, opts.syncUrl);
+        if (hasUnsyncedLocalVault(vaultPath) && remoteHasRefs(homePath, opts.syncUrl)) {
+            throw new HandoffError("local vault has unsynced memory and the sync remote already has data; move or back up the local vault before joining this remote");
+        }
+        ensureExistingGitVaultCompatible(vaultPath, opts.syncUrl);
+    }
     if (opts.syncUrl && cloneVaultIfNeeded(homePath, vaultPath, opts.syncUrl)) {
         created += 1;
     }
@@ -49,7 +55,9 @@ export function setupHome(opts = {}) {
     if (opts.syncUrl)
         desired.sync_url = opts.syncUrl;
     if (existsSync(configPath)) {
-        const existing = JSON.parse(readFileSync(configPath, "utf8"));
+        const existing = readConfig(opts.home);
+        if (!existing)
+            throw new HandoffError(`${CONFIG_FILE} is missing`);
         let changed = false;
         if (existing.version !== 2) {
             existing.version = 2;
@@ -114,49 +122,13 @@ export function installSkill(opts = {}) {
     }
     return { path, updated };
 }
-export function initRepo(opts = {}) {
-    const rootPath = resolve(opts.root ?? ".");
-    const setup = setupHome({ home: opts.home });
-    const pid = deriveProjectId(rootPath, opts.projectId);
-    const branchName = opts.branch ?? currentBranch(rootPath);
-    const selectedClients = normalizeClients(opts.clients);
-    let created = 0;
-    let updated = 0;
-    const bootstrapPath = join(rootPath, BOOTSTRAP_FILE);
-    const bootstrapContents = `version: 2\nproject_id: ${pid}\nclients: ${selectedClients.join(",")}\n`;
-    if (!existsSync(bootstrapPath)) {
-        writeFileSync(bootstrapPath, bootstrapContents, "utf8");
-        created += 1;
-    }
-    else {
-        const data = readBootstrap(bootstrapPath);
-        const existingClients = clientsFromBootstrap(data);
-        if (data.project_id !== pid ||
-            data.version !== "2" ||
-            existingClients.join(",") !== selectedClients.join(",")) {
-            writeFileSync(bootstrapPath, bootstrapContents, "utf8");
-            updated += 1;
-        }
-    }
-    for (const filename of clientInstructionFiles(selectedClients)) {
-        const changed = ensureManagedBlock(join(rootPath, filename));
-        if (changed.changed) {
-            if (changed.created)
-                created += 1;
-            else
-                updated += 1;
-        }
-    }
-    const projectPath = vaultProjectPath(setup.vault, pid);
-    created += ensureProjectFiles(projectPath, branchName);
-    return {
-        created,
-        updated,
-        root: rootPath,
-        projectId: pid,
-        vaultProject: projectPath,
-        clients: selectedClients,
-    };
+export function enableHandoff(opts = {}) {
+    const setup = setupHome({ home: opts.home, vault: opts.vault });
+    const skill = installSkill({ skillsHome: opts.skillsHome });
+    return { setup, skill };
+}
+export function enableSync(opts) {
+    return setupHome({ home: opts.home, vault: opts.vault, syncUrl: opts.syncUrl });
 }
 export function deriveProjectId(root = ".", projectId) {
     const rootPath = resolve(root);
@@ -178,14 +150,11 @@ export function currentBranch(root = ".") {
 }
 export function buildStartPacket(opts = {}) {
     const rootPath = resolve(opts.root ?? ".");
-    const status = getStatus({ root: rootPath, home: opts.home });
-    if (!status.initialized) {
-        throw new HandoffError(statusError(status));
-    }
     const setup = loadSetup(opts.home);
-    const pid = status.projectId ?? deriveProjectId(rootPath);
+    const pid = deriveProjectId(rootPath);
     const branchName = opts.branch ?? currentBranch(rootPath);
     const projectPath = vaultProjectPath(setup.vault, pid);
+    ensureProjectFiles(projectPath, branchName);
     const branchFile = join(projectPath, "branches", `${safeName(branchName)}.md`);
     const sections = [
         ["Global Preferences", join(setup.vault, "global", "preferences.md")],
@@ -201,7 +170,7 @@ export function buildStartPacket(opts = {}) {
         `Project: \`${pid}\``,
         `Branch: \`${branchName}\``,
         "",
-        "Read this packet before making changes. Use it to recover context from previous Codex and Claude Code sessions.",
+        "Read this packet before making changes. Use it to recover context from previous coding-agent sessions.",
     ];
     for (const [title, path] of sections) {
         lines.push(...renderSection(title, path));
@@ -218,25 +187,22 @@ export function buildStartPacket(opts = {}) {
 }
 export function writeCheckpoint(opts) {
     const rootPath = resolve(opts.root ?? ".");
-    const status = getStatus({ root: rootPath, home: opts.home });
-    if (!status.initialized) {
-        throw new HandoffError(statusError(status));
-    }
     const cleanedNote = cleanNote(opts.note);
     if (!cleanedNote)
         throw new HandoffError("checkpoint note cannot be empty");
     rejectLikelySecret(cleanedNote);
     const setup = loadSetup(opts.home);
-    const pid = status.projectId ?? deriveProjectId(rootPath);
+    const pid = deriveProjectId(rootPath);
     const branchName = opts.branch ?? currentBranch(rootPath);
     const createdAt = timestamp(opts.now);
     const projectPath = vaultProjectPath(setup.vault, pid);
+    ensureProjectFiles(projectPath, branchName);
     const checkpoints = join(projectPath, "checkpoints");
     mkdirSync(checkpoints, { recursive: true });
     const deviceLabel = opts.device ?? hostname() ?? "device";
     const agentLabel = opts.agent ?? "agent";
     const filename = `${compactTimestamp(createdAt)}-${safeName(deviceLabel)}-${safeName(agentLabel)}-${safeName(branchName)}.md`;
-    const path = join(checkpoints, filename);
+    const path = uniquePath(checkpoints, filename);
     const contents = [
         "# Checkpoint",
         "",
@@ -267,7 +233,7 @@ export function learn(note, opts = {}) {
     if (!["preference", "lesson", "decision", "context"].includes(kind)) {
         throw new HandoffError("learn kind must be 'preference', 'lesson', 'decision', or 'context'");
     }
-    const setup = setupHome({ home: opts.home });
+    const setup = loadSetup(opts.home);
     const path = learnTargetPath(setup, resolve(opts.root ?? "."), scope, kind, opts.branch);
     const createdAt = timestamp(opts.now);
     appendFile(path, `\n- ${createdAt}: ${clean}\n`);
@@ -275,9 +241,13 @@ export function learn(note, opts = {}) {
 }
 export function syncVault(opts = {}) {
     const setup = loadSetup(opts.home);
-    if (!existsSync(join(setup.vault, ".git"))) {
-        throw new HandoffError("vault is not a git repository; run setup --sync first");
+    const config = readConfig(opts.home);
+    if (!config?.sync_url) {
+        throw new HandoffError("sync is not configured; run agent-handoff sync init <git-url> first");
     }
+    const syncProblem = syncConfigProblem(setup.vault, config.sync_url);
+    if (syncProblem)
+        throw new HandoffError(syncProblem);
     const outputs = [];
     gitChecked(setup.vault, ["add", "-A"]);
     const staged = gitRun(setup.vault, ["diff", "--cached", "--quiet"]).status !== 0;
@@ -310,46 +280,49 @@ export function syncVault(opts = {}) {
 export function getStatus(opts = {}) {
     const rootPath = resolve(opts.root ?? ".");
     const problems = [];
-    let projectId = null;
-    let clients = ["codex", "claude"];
-    const bootstrapPath = join(rootPath, BOOTSTRAP_FILE);
-    if (!existsSync(bootstrapPath)) {
-        problems.push(`${BOOTSTRAP_FILE} is missing`);
-    }
-    else {
-        const data = readBootstrap(bootstrapPath);
-        projectId = data.project_id ?? null;
-        if (!projectId)
-            problems.push(`${BOOTSTRAP_FILE} is missing project_id`);
-        clients = clientsFromBootstrap(data);
-    }
-    for (const filename of clientInstructionFiles(clients)) {
-        if (!hasManagedBlock(join(rootPath, filename))) {
-            problems.push(`${filename} is missing the managed handoff block`);
+    const projectId = deriveProjectId(rootPath);
+    let syncUrl;
+    let config = null;
+    try {
+        config = readConfig(opts.home);
+    }
+    catch (error) {
+        if (error instanceof HandoffError) {
+            problems.push(error.message);
+        }
+        else {
+            throw error;
         }
     }
-    const config = readConfig(opts.home);
     if (!config) {
-        problems.push("vault config is missing; run agent-handoff setup");
+        if (problems.length === 0) {
+            problems.push("agent-handoff is not enabled; run agent-handoff enable");
+        }
     }
     else if (!existsSync(config.vault)) {
         problems.push(`vault directory is missing: ${config.vault}`);
     }
-    else if (projectId) {
-        const projectPath = vaultProjectPath(config.vault, projectId);
-        if (!existsSync(projectPath)) {
-            problems.push(`vault project is missing: ${projectId}`);
+    else {
+        if (config.sync_url) {
+            const syncProblem = syncConfigProblem(config.vault, config.sync_url);
+            if (syncProblem) {
+                problems.push(syncProblem);
+            }
+            else {
+                syncUrl = config.sync_url;
+            }
+        }
+        else {
+            syncUrl = undefined;
         }
     }
-    return { initialized: problems.length === 0, problems, root: rootPath, projectId };
-}
-export function doctor(opts = {}) {
-    const status = getStatus(opts);
     return {
-        ok: status.initialized,
-        problems: status.problems,
-        root: status.root,
-        projectId: status.projectId,
+        initialized: problems.length === 0,
+        problems,
+        root: rootPath,
+        projectId,
+        syncConfigured: Boolean(syncUrl),
+        syncUrl,
     };
 }
 function globalSeedFiles() {
@@ -398,8 +371,9 @@ function learnTargetPath(setup, root, scope, kind, branch) {
     if (!status.initialized) {
         throw new HandoffError(statusError(status));
     }
-    const pid = status.projectId ?? deriveProjectId(root);
+    const pid = deriveProjectId(root);
     const projectPath = vaultProjectPath(setup.vault, pid);
+    ensureProjectFiles(projectPath, branch ?? currentBranch(root));
     if (scope === "project") {
         if (kind === "preference")
             return join(projectPath, "preferences.md");
@@ -414,31 +388,6 @@ function learnTargetPath(setup, root, scope, kind, branch) {
     }
     return branchPath;
 }
-function normalizeClients(clients) {
-    const selected = clients && clients.length > 0 ? clients : ["codex", "claude"];
-    const deduped = [];
-    for (const client of selected) {
-        if (client !== "codex" && client !== "claude") {
-            throw new HandoffError(`unsupported client(s): ${client}`);
-        }
-        if (!deduped.includes(client))
-            deduped.push(client);
-    }
-    return deduped;
-}
-function clientsFromBootstrap(data) {
-    if (!data.clients)
-        return ["codex", "claude"];
-    return normalizeClients(data.clients.split(",").map((client) => client.trim()).filter(Boolean));
-}
-function clientInstructionFiles(clients) {
-    const files = [];
-    if (clients.includes("codex"))
-        files.push("AGENTS.md");
-    if (clients.includes("claude"))
-        files.push("CLAUDE.md");
-    return files;
-}
 function resolveHome(home) {
     return resolve(home ? expandHome(home) : DEFAULT_HOME);
 }
@@ -453,12 +402,58 @@ function readConfig(home) {
     const configPath = join(resolveHome(home), CONFIG_FILE);
     if (!existsSync(configPath))
         return null;
-    return JSON.parse(readFileSync(configPath, "utf8"));
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(configPath, "utf8"));
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new HandoffError(`${CONFIG_FILE} is invalid: ${detail}`);
+    }
+    return validateConfig(raw);
+}
+function validateConfig(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new HandoffError(`${CONFIG_FILE} is invalid: expected an object`);
+    }
+    const data = raw;
+    if (typeof data.vault !== "string" || data.vault.trim().length === 0) {
+        throw new HandoffError(`${CONFIG_FILE} is invalid: vault must be a non-empty string`);
+    }
+    if (data.version !== undefined && typeof data.version !== "number") {
+        throw new HandoffError(`${CONFIG_FILE} is invalid: version must be a number`);
+    }
+    if (data.sync_url !== undefined && (typeof data.sync_url !== "string" || data.sync_url.trim().length === 0)) {
+        throw new HandoffError(`${CONFIG_FILE} is invalid: sync_url must be a non-empty string`);
+    }
+    const config = {
+        version: typeof data.version === "number" ? data.version : 0,
+        vault: data.vault,
+    };
+    if (typeof data.sync_url === "string") {
+        config.sync_url = data.sync_url;
+    }
+    return config;
+}
+function syncConfigProblem(vault, syncUrl) {
+    if (!existsSync(join(vault, ".git"))) {
+        return `sync is configured for ${syncUrl} but vault is not a git repository; run agent-handoff sync init ${syncUrl}`;
+    }
+    const origin = gitOutput(vault, ["remote", "get-url", "origin"]);
+    if (!origin) {
+        return `sync is configured for ${syncUrl} but vault git remote origin is missing; run agent-handoff sync init ${syncUrl}`;
+    }
+    if (origin !== syncUrl) {
+        return `sync is configured for ${syncUrl} but vault origin is ${origin}; run agent-handoff sync init ${syncUrl}`;
+    }
+    return null;
 }
 function loadSetup(home) {
     const config = readConfig(home);
     if (!config)
-        return setupHome({ home });
+        throw new HandoffError("agent-handoff is not enabled; run agent-handoff enable");
+    if (!existsSync(config.vault))
+        throw new HandoffError(`vault directory is missing: ${config.vault}`);
     return { home: resolveHome(home), vault: resolve(config.vault), created: 0, updated: 0 };
 }
 function vaultProjectPath(vault, projectId) {
@@ -491,66 +486,6 @@ function readBootstrap(path) {
     }
     return data;
 }
-function managedBlock() {
-    return [
-        MANAGED_BEGIN,
-        "Agent handoff is enabled for this repository.",
-        "",
-        "At the start of a new Codex or Claude Code session, run `agent-handoff sync` if vault sync is configured, then run:",
-        "",
-        "```bash",
-        "agent-handoff start",
-        "```",
-        "",
-        "Read the returned packet before making changes.",
-        "",
-        "Before pausing work, switching devices, or ending a useful session, run:",
-        "",
-        "```bash",
-        'agent-handoff checkpoint --note "<current goal, progress, open questions, next step>"',
-        "```",
-        "",
-        "Then run `agent-handoff sync` if vault sync is configured.",
-        "",
-        'When the user corrects a stable preference or recurring rule, run `agent-handoff learn --kind preference --note "..."`.',
-        MANAGED_END,
-        "",
-    ].join("\n");
-}
-function ensureManagedBlock(path) {
-    const block = managedBlock();
-    if (!existsSync(path)) {
-        writeFileSync(path, block, "utf8");
-        return { changed: true, created: true };
-    }
-    const original = readFileSync(path, "utf8");
-    let updated;
-    if (original.includes(MANAGED_BEGIN) && original.includes(MANAGED_END)) {
-        const before = original.split(MANAGED_BEGIN, 1)[0];
-        const after = original.split(MANAGED_END, 2)[1] ?? "";
-        const parts = [];
-        if (before.trimEnd())
-            parts.push(before.trimEnd());
-        parts.push(block.trimEnd());
-        if (after.trimStart())
-            parts.push(after.trimStart());
-        updated = `${parts.join("\n\n")}\n`;
-    }
-    else {
-        updated = `${original.trimEnd()}\n\n${block}`;
-    }
-    if (updated !== original) {
-        writeFileSync(path, updated, "utf8");
-        return { changed: true, created: false };
-    }
-    return { changed: false, created: false };
-}
-function hasManagedBlock(path) {
-    if (!existsSync(path))
-        return false;
-    const contents = readFileSync(path, "utf8");
-    return contents.includes(MANAGED_BEGIN) && contents.includes(MANAGED_END);
-}
 function renderSection(title, path, headingLevel = 2) {
     const heading = "#".repeat(headingLevel);
     if (!existsSync(path)) {
@@ -616,11 +551,72 @@ function json(data) {
 function appendFile(path, contents) {
     writeFileSync(path, contents, { encoding: "utf8", flag: "a" });
 }
+function uniquePath(directory, filename) {
+    const dot = filename.lastIndexOf(".");
+    const stem = dot === -1 ? filename : filename.slice(0, dot);
+    const extension = dot === -1 ? "" : filename.slice(dot);
+    let path = join(directory, filename);
+    let index = 2;
+    while (existsSync(path)) {
+        path = join(directory, `${stem}-${index}${extension}`);
+        index += 1;
+    }
+    return path;
+}
+function validateSyncRemote(home, syncUrl) {
+    const result = gitRun(home, ["ls-remote", syncUrl]);
+    if (result.status !== 0) {
+        throw new HandoffError(result.output.trim() || `cannot access sync remote: ${syncUrl}`);
+    }
+}
+function hasUnsyncedLocalVault(vault) {
+    return existsSync(vault) && !existsSync(join(vault, ".git")) && !isSeedOnlyVault(vault);
+}
+function remoteHasRefs(home, syncUrl) {
+    const result = gitRun(home, ["ls-remote", "--heads", syncUrl]);
+    if (result.status !== 0) {
+        throw new HandoffError(result.output.trim() || `cannot inspect sync remote: ${syncUrl}`);
+    }
+    return result.output.trim().length > 0;
+}
+function ensureExistingGitVaultCompatible(vault, syncUrl) {
+    if (!existsSync(join(vault, ".git")))
+        return;
+    if (!remoteHasRefs(vault, syncUrl))
+        return;
+    const localHead = gitOutput(vault, ["rev-parse", "HEAD"]);
+    if (!localHead)
+        return;
+    const namespace = "refs/remotes/agent-handoff-check";
+    const fetch = gitRun(vault, ["fetch", "--no-tags", syncUrl, `+refs/heads/*:${namespace}/*`]);
+    if (fetch.status !== 0) {
+        throw new HandoffError(fetch.output.trim() || `cannot fetch sync remote: ${syncUrl}`);
+    }
+    const refs = listRefs(vault, namespace);
+    try {
+        if (refs.length > 0 && !refs.some((ref) => sharesHistory(vault, localHead, ref))) {
+            throw new HandoffError("existing git vault and sync remote do not share history; use a fresh vault or keep the current sync remote");
+        }
+    }
+    finally {
+        for (const ref of refs) {
+            gitRun(vault, ["update-ref", "-d", ref]);
+        }
+    }
+}
+function listRefs(vault, namespace) {
+    const refs = gitOutput(vault, ["for-each-ref", "--format=%(refname)", namespace]);
+    return refs?.split(/\r?\n/).filter(Boolean) ?? [];
+}
+function sharesHistory(vault, localHead, remoteRef) {
+    return (gitRun(vault, ["merge-base", "--is-ancestor", localHead, remoteRef]).status === 0 ||
+        gitRun(vault, ["merge-base", "--is-ancestor", remoteRef, localHead]).status === 0);
+}
 function cloneVaultIfNeeded(home, vault, syncUrl) {
     if (existsSync(join(vault, ".git")))
         return false;
     if (existsSync(vault)) {
-        if (readdirSync(vault).length === 0) {
+        if (readdirSync(vault).length === 0 || isSeedOnlyVault(vault)) {
             rmSync(vault, { recursive: true, force: true });
         }
         else {
@@ -628,19 +624,72 @@ function cloneVaultIfNeeded(home, vault, syncUrl) {
         }
     }
     const clone = gitRun(home, ["clone", syncUrl, vault]);
+    if (clone.status !== 0) {
+        throw new HandoffError(clone.output.trim() || `git clone ${syncUrl} failed`);
+    }
     return clone.status === 0;
 }
+function isSeedOnlyVault(vault) {
+    const entries = readdirSync(vault).sort();
+    if (entries.some((entry) => !["global", "projects"].includes(entry)))
+        return false;
+    const projects = join(vault, "projects");
+    if (existsSync(projects) && !isSeedOnlyProjects(projects))
+        return false;
+    const global = join(vault, "global");
+    if (!existsSync(global))
+        return entries.length === 0 || entries.every((entry) => entry === "projects");
+    const seeds = globalSeedFiles();
+    for (const entry of readdirSync(global)) {
+        if (!(entry in seeds))
+            return false;
+        if (readFileSync(join(global, entry), "utf8") !== seeds[entry])
+            return false;
+    }
+    return true;
+}
+function isSeedOnlyProjects(projects) {
+    for (const name of readdirSync(projects)) {
+        if (!isSeedOnlyProject(join(projects, name)))
+            return false;
+    }
+    return true;
+}
+function isSeedOnlyProject(projectPath) {
+    const allowed = new Set(["project.md", "decisions.md", "preferences.md", "branches", "checkpoints"]);
+    for (const entry of readdirSync(projectPath)) {
+        if (!allowed.has(entry))
+            return false;
+    }
+    const seeds = projectSeedFiles();
+    for (const [filename, contents] of Object.entries(seeds)) {
+        const path = join(projectPath, filename);
+        if (existsSync(path) && readFileSync(path, "utf8") !== contents)
+            return false;
+    }
+    const checkpoints = join(projectPath, "checkpoints");
+    if (existsSync(checkpoints) && readdirSync(checkpoints).length > 0)
+        return false;
+    const branches = join(projectPath, "branches");
+    if (!existsSync(branches))
+        return true;
+    return readdirSync(branches).every((name) => {
+        if (!name.endsWith(".md"))
+            return false;
+        return /^# Branch Context: .+\n\n$/.test(readFileSync(join(branches, name), "utf8"));
+    });
+}
 function ensureGitRemote(vault, syncUrl) {
     if (!existsSync(join(vault, ".git"))) {
-        gitRun(vault, ["init"]);
-        gitRun(vault, ["branch", "-M", "main"]);
+        gitChecked(vault, ["init"]);
+        gitChecked(vault, ["branch", "-M", "main"]);
     }
     const remotes = gitOutput(vault, ["remote"]);
     if (remotes?.split(/\r?\n/).includes("origin")) {
-        gitRun(vault, ["remote", "set-url", "origin", syncUrl]);
+        gitChecked(vault, ["remote", "set-url", "origin", syncUrl]);
     }
     else {
-        gitRun(vault, ["remote", "add", "origin", syncUrl]);
+        gitChecked(vault, ["remote", "add", "origin", syncUrl]);
     }
 }
 function gitOutput(root, args) {
@@ -661,11 +710,14 @@ function gitRun(root, args) {
     const result = spawnSync("git", args, {
         cwd: root,
         encoding: "utf8",
+        env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
         stdio: ["ignore", "pipe", "pipe"],
+        timeout: GIT_TIMEOUT_MS,
     });
+    const error = result.error ? `\n${result.error.message}` : "";
     return {
         status: result.status ?? 1,
-        output: `${result.stdout ?? ""}${result.stderr ?? ""}`,
+        output: `${result.stdout ?? ""}${result.stderr ?? ""}${error}`,
     };
 }
 function isEmptyRemotePull(output) {

package/dist/index.d.ts

@@ -1 +1,2 @@
-export * from "./core.js";
+export { HandoffError, buildStartPacket, enableHandoff, enableSync, getStatus, learn, normalizeProjectId, syncVault, writeCheckpoint, } from "./core.js";
+export type { CheckpointResult, EnableResult, LearnResult, Status, } from "./core.js";

package/dist/index.js

@@ -1 +1 @@
-export * from "./core.js";
+export { HandoffError, buildStartPacket, enableHandoff, enableSync, getStatus, learn, normalizeProjectId, syncVault, writeCheckpoint, } from "./core.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@leantli/agent-handoff",
-  "version": "0.4.0",
-  "description": "Shared vault handoff memory for Codex and Claude Code.",
+  "version": "0.5.1",
+  "description": "Shared vault handoff memory for coding agents.",
   "type": "module",
   "license": "MIT",
   "author": "agent-handoff contributors",
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "prepack": "npm run build",
+    "prepare": "npm run build",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },

package/resources/agent-handoff.SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-handoff
-description: Use when starting, resuming, pausing, checkpointing, or transferring Codex/Claude Code work across sessions, clones, worktrees, or devices with the agent-handoff CLI.
+description: Use when starting, resuming, pausing, checkpointing, or transferring coding-agent work across sessions, clones, worktrees, or devices with the agent-handoff CLI.
 ---
 
 # Agent Handoff
@@ -12,11 +12,16 @@ Use `agent-handoff` to restore and preserve coding-agent context.
 When beginning work in a repository:
 
 1. Run `agent-handoff status`.
-2. If status says the repo is not ready, run `agent-handoff setup` if the vault is missing, then `agent-handoff init`.
-3. If vault sync is configured, run `agent-handoff sync`.
+2. If status reports a problem, stop and report it. If the problem is that
+   agent-handoff is not enabled, tell the user to run `agent-handoff enable`.
+3. If status says `Sync: configured` and the user is switching devices or clones,
+   run `agent-handoff sync`.
 4. Run `agent-handoff start`.
 5. Read the returned packet before changing files.
 
+Do not edit `AGENTS.md`, `CLAUDE.md`, or other instruction files to install
+agent-handoff.
+
 ## During Work
 
 Use `learn` only for stable facts that should survive future sessions, clones,
@@ -55,7 +60,7 @@ agent, write a concise checkpoint:
 agent-handoff checkpoint --note "<current goal, completed work, open questions, next step>"
 ```
 
-If vault sync is configured, run:
+If sync is configured, run:
 
 ```bash
 agent-handoff sync
@@ -69,4 +74,4 @@ If sync fails, keep the local checkpoint and report the error.
 - Keep checkpoints factual and concise.
 - Do not use `learn` for temporary task state; use `checkpoint` instead.
 - Prefer project or branch scope for project-specific facts instead of global memory.
-- If `agent-handoff` is not installed, tell the user the CLI is missing and continue without pretending context was saved.
+- Do not modify repository instruction files as part of agent-handoff installation or use.