@leantli/agent-handoff 0.5.2 → 0.6.0

package/README.md

@@ -66,7 +66,7 @@ For project-specific decisions or branch-specific context:
 
 ```bash
 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."
+agent-handoff learn --scope branch --kind context --note "This branch is testing the sync workflow."
 ```
 
 ## Cross-Device Sync
@@ -74,18 +74,29 @@ agent-handoff learn --scope branch --kind context --note "This branch is testing
 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:
+Cross-device sync is optional. Create a dedicated private repository for the
+vault. Do not use a project code repository as the vault. Then run:
 
 ```bash
 agent-handoff sync init git@github.com:you/agent-handoff-vault.git
 agent-handoff sync
 ```
 
+Use a private repository because the vault can contain project background,
+preferences, decisions, and handoff notes.
+
 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.
 
+By default the vault lives at `~/.agent-handoff/vault`. Use `--home` or
+`--vault` when you need a different location. `agent-handoff sync` commits local
+vault changes, pulls/rebases remote vault changes, then pushes the result.
+If `sync init` says the local vault has unsynced memory and the remote already
+has data, back up or manually merge the local vault before joining that remote.
+If git reports a conflict or active operation, resolve the conflict in the vault,
+finish or abort the active git operation, then run `agent-handoff sync` again.
+
 ## How Projects Are Identified
 
 By default, `agent-handoff` identifies the current project from the git `origin`

package/dist/cli.js

@@ -25,7 +25,7 @@ function buildProgram(stdout, stderr, stdin, cwd) {
     program
         .name("agent-handoff")
         .description("Shared vault handoff memory for coding agents.")
-        .version("agent-handoff 0.5.2")
+        .version(`agent-handoff ${packageVersion()}`)
         .exitOverride()
         .configureOutput({
         writeOut: (str) => stdout.write(str),
@@ -94,7 +94,7 @@ function buildProgram(stdout, stderr, stdin, cwd) {
     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.")
+        .description("Enable cross-device sync with a dedicated private vault repository.")
         .option("--vault <path>", "Vault directory. Defaults to HOME/vault.")
         .action((gitUrl, options) => {
         const result = enableSync({ home: globalHome(program), vault: options.vault, syncUrl: gitUrl });
@@ -141,6 +141,13 @@ function readNote(options, stdin) {
     }
     return readFileSync(0, "utf8");
 }
+function packageVersion() {
+    const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    if (typeof pkg.version !== "string") {
+        throw new HandoffError("package.json is missing a string version");
+    }
+    return pkg.version;
+}
 function printProblems(problems, stdout) {
     for (const problem of problems) {
         stdout.write(`- ${problem}\n`);

package/dist/core.js

@@ -1,7 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { hostname, homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 export const DEFAULT_HOME = join(homedir(), ".agent-handoff");
 export const CONFIG_FILE = "config.json";
@@ -249,6 +249,9 @@ export function syncVault(opts = {}) {
     if (syncProblem)
         throw new HandoffError(syncProblem);
     const outputs = [];
+    if (hasActiveGitOperation(setup.vault) || hasUnmergedFiles(setup.vault)) {
+        throw syncConflictError(setup.vault);
+    }
     gitChecked(setup.vault, ["add", "-A"]);
     const staged = gitRun(setup.vault, ["diff", "--cached", "--quiet"]).status !== 0;
     if (staged) {
@@ -266,6 +269,9 @@ export function syncVault(opts = {}) {
     const pull = gitRun(setup.vault, ["pull", "--rebase", "--autostash", "origin", branch]);
     const ignoredEmptyRemotePull = pull.status !== 0 && isEmptyRemotePull(pull.output);
     if (pull.status !== 0 && !ignoredEmptyRemotePull) {
+        if (hasActiveGitOperation(setup.vault) || hasUnmergedFiles(setup.vault)) {
+            throw syncConflictError(setup.vault, pull.output);
+        }
         throw new HandoffError(pull.output.trim() || "git pull failed");
     }
     if (!ignoredEmptyRemotePull && pull.output.trim())
@@ -721,6 +727,24 @@ function gitRun(root, args) {
         output: `${result.stdout ?? ""}${result.stderr ?? ""}${error}`,
     };
 }
+function hasUnmergedFiles(vault) {
+    const result = gitRun(vault, ["diff", "--name-only", "--diff-filter=U"]);
+    return result.status === 0 && result.output.trim().length > 0;
+}
+function hasActiveGitOperation(vault) {
+    return ["rebase-merge", "rebase-apply", "MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD"].some((name) => gitPathExists(vault, name));
+}
+function gitPathExists(vault, name) {
+    const path = gitOutput(vault, ["rev-parse", "--git-path", name]);
+    if (!path)
+        return false;
+    return existsSync(isAbsolute(path) ? path : join(vault, path));
+}
+function syncConflictError(vault, detail) {
+    const message = `sync conflict in ${vault}; resolve conflicts in that vault, finish or abort the active git operation, then run agent-handoff sync again`;
+    const trimmed = detail?.trim();
+    return new HandoffError(trimmed ? `${message}\n\n${trimmed}` : message);
+}
 function isEmptyRemotePull(output) {
     const lowered = output.toLowerCase();
     return lowered.includes("couldn't find remote ref") || lowered.includes("could not find remote ref");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leantli/agent-handoff",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Shared vault handoff memory for coding agents.",
   "type": "module",
   "license": "MIT",

package/resources/agent-handoff.SKILL.md

@@ -22,6 +22,32 @@ When beginning work in a repository:
 Do not edit `AGENTS.md`, `CLAUDE.md`, or other instruction files to install
 agent-handoff.
 
+## Cross-Device Sync Setup
+
+Use a dedicated private vault repository for sync. Do not use a project code
+repository as the vault. The vault can contain project context, preferences,
+decisions, and handoff notes.
+
+If the user asks you to set up cross-device sync, make sure the vault repository
+they created is private, then run:
+
+```bash
+agent-handoff sync init <private-git-url>
+agent-handoff sync
+```
+
+On another device, install and enable the CLI, then run `sync init` with the same
+private git URL, `agent-handoff sync`, and `agent-handoff start`.
+
+If `sync init` says the local vault has unsynced memory and the remote already
+has data, keep the local files and report it. The user or agent should back up
+or manually merge the local vault before joining that remote.
+
+If sync fails because git reports a conflict or active operation, keep the local
+files and report the conflict. The user or agent should resolve it inside the
+vault, finish or abort the active git operation, then run `agent-handoff sync`
+again.
+
 ## During Work
 
 Use `learn` only for stable facts that should survive future sessions, clones,