gigarag-claude-code 0.1.1 → 0.2.1

package/cli/sync/plan.js

@@ -0,0 +1,76 @@
+/**
+ * What a sync does without a model, decided from two maps: what the manifest
+ * says was indexed, and what is on disk now. Pure, so every rule here has a
+ * test that doesn't need git or a server.
+ */
+/** More than this many gone paths, and more than half the manifest, is what a broken checkout looks like. */
+export const MASS_DELETE_MIN = 20;
+function byHash(paths, hashOf) {
+    const m = new Map();
+    for (const p of paths) {
+        const h = hashOf(p);
+        m.set(h, [...(m.get(h) ?? []), p]);
+    }
+    return m;
+}
+export function planSync(input) {
+    const { known, current } = input;
+    const gone = input.truncated ? [] : [...known.keys()].filter(p => !current.has(p) && !(input.atHead?.has(p) ?? false));
+    const added = [...current.keys()].filter(p => !known.has(p));
+    // A rename only when the hash is unique on both sides. Two copies of one LICENSE are not evidence.
+    const goneByHash = byHash(gone, p => known.get(p).hash);
+    const addedByHash = byHash(added, p => current.get(p));
+    const renames = [];
+    for (const [hash, from] of goneByHash) {
+        const to = addedByHash.get(hash);
+        if (from.length === 1 && to?.length === 1)
+            renames.push({ from: from[0], to: to[0], hash, nodeIds: known.get(from[0]).nodeIds });
+    }
+    const renamedTo = new Map(renames.map(r => [r.from, r.to]));
+    const newPaths = new Set(renames.map(r => r.to));
+    const trulyGone = gone.filter(p => !renamedTo.has(p));
+    const suspicious = trulyGone.length > MASS_DELETE_MIN && trulyGone.length * 2 > known.size;
+    // Which live paths feed each memo once renames are applied.
+    const feeders = new Map();
+    for (const [path, file] of known) {
+        const live = renamedTo.get(path) ?? path;
+        for (const id of file.nodeIds)
+            feeders.set(id, [...(feeders.get(id) ?? []), live]);
+    }
+    const goneSet = new Set(trulyGone);
+    const deleteNodeIds = new Set();
+    const deletedPaths = [];
+    const partial = [];
+    if (!suspicious || input.allowMassDelete) {
+        for (const path of trulyGone) {
+            const ids = known.get(path).nodeIds;
+            const orphaned = ids.filter(id => (feeders.get(id) ?? []).every(p => goneSet.has(p)));
+            for (const id of orphaned)
+                deleteNodeIds.add(id);
+            const shared = ids.filter(id => !orphaned.includes(id));
+            if (shared.length > 0)
+                partial.push({ path, nodeIds: shared });
+            else
+                deletedPaths.push(path);
+        }
+    }
+    const changed = [...current].filter(([p, h]) => known.has(p) && known.get(p).hash !== h).map(([p]) => p);
+    const rewrite = [...changed, ...added.filter(p => !newPaths.has(p))].sort();
+    const stale = new Set();
+    for (const p of changed)
+        for (const id of known.get(p).nodeIds)
+            stale.add(id);
+    for (const p of partial)
+        for (const id of p.nodeIds)
+            stale.add(id);
+    return {
+        renames,
+        deleteNodeIds: [...deleteNodeIds].sort(),
+        deletedPaths: deletedPaths.sort(),
+        partial,
+        stale: [...stale].sort(),
+        rewrite,
+        suspicious,
+        goneCount: trulyGone.length,
+    };
+}

package/cli/sync/remote.js

@@ -0,0 +1,72 @@
+const RECORD_BATCH = 500;
+const STALE_BATCH = 200;
+function chunks(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+/** The bucket whose slug is exactly `slug`. list_buckets filters by substring, so the match is checked here. */
+export async function findBucketId(rag, slug) {
+    const page = await rag.listBuckets({ q: slug, limit: 50 });
+    const hit = page.items.find(b => b['slug'] === slug);
+    return typeof hit?.['id'] === 'string' ? hit['id'] : undefined;
+}
+/** repo_sync for one bucket, with core's limits applied by batching rather than by the caller. */
+export class RepoSyncRemote {
+    rag;
+    bucketId;
+    constructor(rag, bucketId) {
+        this.rag = rag;
+        this.bucketId = bucketId;
+    }
+    call(action, args = {}) {
+        return this.rag.callTool('repo_sync', { bucket_id: this.bucketId, action, ...args });
+    }
+    state() {
+        return this.call('state');
+    }
+    async manifest() {
+        const all = [];
+        let after;
+        do {
+            const page = await this.call('manifest', { limit: 1000, ...(after ? { after } : {}) });
+            all.push(...page.items);
+            after = page.next_cursor ?? undefined;
+        } while (after);
+        return all;
+    }
+    claim(holder, token) {
+        return this.call('claim', { holder, ttl_seconds: 600, ...(token ? { token } : {}) });
+    }
+    /** Never throws: a lease that can't be released lapses on its own in ten minutes. */
+    async release(token) {
+        try {
+            await this.call('release', { token });
+        }
+        catch {
+            /* lapses */
+        }
+    }
+    async record(upserts, removes) {
+        const entries = [
+            ...upserts.map(u => ({ up: { path: u.path, hash: u.hash, node_ids: u.nodeIds } })),
+            ...removes.map(rm => ({ rm })),
+        ];
+        for (const batch of chunks(entries, RECORD_BATCH)) {
+            await this.call('record', {
+                upserts: batch.flatMap(e => ('up' in e ? [e.up] : [])),
+                removes: batch.flatMap(e => ('rm' in e ? [e.rm] : [])),
+            });
+        }
+    }
+    async advance(token, commit, branch) {
+        await this.call('advance', { token, commit, ...(branch ? { branch } : {}) });
+    }
+    async markStale(nodeIds, commit) {
+        let marked = 0;
+        for (const batch of chunks(nodeIds, STALE_BATCH))
+            marked += (await this.call('mark_stale', { node_ids: batch, commit })).marked;
+        return marked;
+    }
+}

package/cli/sync/rewriter.js

@@ -0,0 +1,125 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { closeSync, existsSync, mkdirSync, openSync } from 'node:fs';
+import { delimiter, dirname, join } from 'node:path';
+/**
+ * The GigaRAG MCP tools the gigasync/gigaindex flow actually calls (see
+ * plugins/claude-code/agents/gigarag-indexer.md and commands/gigasync.md): find or create the
+ * bucket and its threads, write and remove memos, and resolve a link's ref. Nothing here can
+ * delete a bucket or thread, link two memos, or read outside what `gigarag scan` already named.
+ */
+const GIGARAG_TOOLS = ['list_buckets', 'create_bucket', 'list_threads', 'create_thread', 'find_nodes', 'create_node', 'update_node', 'delete_node'];
+/**
+ * Starts Claude Code to rewrite stale memos, with nothing but the GigaRAG tools the flow needs,
+ * reading tools and three gigarag subcommands. dontAsk denies anything else rather than waiting
+ * for a person who isn't there. Both prefixes are granted per tool, never as `mcp__*__*`, because
+ * the plugin and the bare MCP server register the same tool names under different prefixes and an
+ * unattended agent should not gain whatever else either server exposes later.
+ */
+export const CLAUDE_ARGS = [
+    '/gigarag:gigasync',
+    '--print',
+    '--permission-mode',
+    'dontAsk',
+    '--max-turns',
+    '300',
+    '--output-format',
+    'json',
+    '--no-session-persistence',
+    '--allowedTools',
+    ...GIGARAG_TOOLS.map(t => `mcp__plugin_gigarag_gigarag__${t}`),
+    ...GIGARAG_TOOLS.map(t => `mcp__gigarag__${t}`),
+    'Read',
+    'Grep',
+    'Glob',
+    'Agent',
+    'Bash(gigarag scan *)',
+    'Bash(gigarag record *)',
+    'Bash(gigarag sync *)',
+    '--disallowedTools',
+    'Write',
+    'Edit',
+    'NotebookEdit',
+    'WebFetch',
+    'WebSearch',
+];
+/** One cmd.exe command line, every part double-quoted. Refuses what quoting can't make literal. */
+export function cmdLine(parts) {
+    for (const p of parts) {
+        if (/["%\r\n]/.test(p))
+            throw new Error(`An argument for claude holds a character cmd.exe would read as syntax, so the rewrite did not start: ${p}`);
+    }
+    return parts.map(p => `"${p}"`).join(' ');
+}
+/** GIGARAG_CLAUDE (a path, for tests and odd installs), then claude on PATH, preferring an .exe on Windows. */
+export function findClaude(env, platform) {
+    const override = env['GIGARAG_CLAUDE'];
+    if (override)
+        return existsSync(override) ? override : undefined;
+    const names = platform === 'win32' ? ['claude.exe', 'claude.cmd'] : ['claude'];
+    for (const dir of (env['PATH'] ?? env['Path'] ?? '').split(delimiter).filter(Boolean)) {
+        for (const name of names) {
+            const candidate = join(dir, name);
+            if (existsSync(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+export function claudeInvocation(path, platform) {
+    if (/\.(mjs|js)$/i.test(path))
+        return { command: process.execPath, args: [path, ...CLAUDE_ARGS] };
+    if (platform === 'win32' && /\.(cmd|bat)$/i.test(path)) {
+        return { command: process.env['ComSpec'] ?? 'cmd.exe', args: ['/d', '/s', '/c', `"${cmdLine([path, ...CLAUDE_ARGS])}"`], verbatim: true };
+    }
+    return { command: path, args: CLAUDE_ARGS };
+}
+function killTree(pid) {
+    if (!pid)
+        return;
+    try {
+        if (process.platform === 'win32')
+            spawnSync('taskkill', ['/pid', String(pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' });
+        else
+            process.kill(-pid, 'SIGTERM');
+    }
+    catch {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+export function runRewriter(inv, cwd, logPath, opts) {
+    mkdirSync(dirname(logPath), { recursive: true, mode: 0o700 });
+    const fd = openSync(logPath, 'w', 0o600);
+    return new Promise(resolvePromise => {
+        let settled = false;
+        let timedOut = false;
+        const child = spawn(inv.command, inv.args, {
+            cwd,
+            env: opts.env,
+            stdio: ['ignore', fd, fd],
+            windowsHide: true,
+            windowsVerbatimArguments: inv.verbatim ?? false,
+            detached: process.platform !== 'win32',
+        });
+        const tick = setInterval(() => void opts.onTick().catch(() => { }), opts.tickMs);
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killTree(child.pid);
+        }, opts.timeoutMs);
+        const done = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearInterval(tick);
+            clearTimeout(timer);
+            closeSync(fd);
+            resolvePromise({ code, timedOut });
+        };
+        child.on('error', () => done(null));
+        child.on('close', code => done(code));
+    });
+}

package/cli/sync/slug.js

@@ -0,0 +1,30 @@
+import { isTrusted, readBinding } from '../binding.js';
+import { findRepoRoot, localSlug, readOriginUrl, repoInfo, slugFromRemote } from '../scan/repo.js';
+/**
+ * Which bucket a repository syncs into. The only file in sync that reads the
+ * binding from the sharing levels spec: with one that is trusted, its bucket and workspace;
+ * without, the slug from the remote, which is how everything worked before. An untrusted
+ * binding's bucket and workspace are both ignored, not just its workspace: reporting
+ * `untrustedWorkspace` instead so callers refuse rather than sync under the unreviewed name.
+ * Kept free of the SDK so a hook can call it without loading a client.
+ *
+ * Deviation from the plan: the sharing levels binding is `readBinding(start): { binding, root } | undefined`
+ * with `binding.workspace` (a uuid), not `readBinding(root): { workspaceId, bucket } | undefined`. Adapted here.
+ */
+export function syncSlug(start) {
+    const { root, git } = findRepoRoot(start);
+    const found = readBinding(root);
+    if (found && !isTrusted(found.root, found.binding.workspace)) {
+        // Never `repoInfo(root).slug`: it reads the same binding and would still hand back the
+        // untrusted file's own bucket name. Recomputed the way an unbound repository resolves,
+        // ignoring the binding entirely, same as `workspaceId` below.
+        const remote = git ? readOriginUrl(root) : undefined;
+        const slug = (remote && slugFromRemote(remote)) || localSlug(root);
+        return { root, git, slug, untrustedWorkspace: found.binding.workspace };
+    }
+    // Trusted or absent: delegate entirely to repoInfo, which applies the same trust check
+    // (`trustedBinding` in binding.ts) rather than re-reading `found.binding.bucket` here, so the
+    // two functions cannot drift on what a trusted binding hands back.
+    const info = repoInfo(root);
+    return { root, git, slug: info.slug, ...(info.workspace ? { workspaceId: info.workspace } : {}) };
+}

package/cli/sync/stage.js

@@ -0,0 +1,323 @@
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { scanTree } from '../scan/scan.js';
+import { hooksOptedIn } from '../commands/gitHooks.js';
+import { currentBranch, headCommit, isAncestor, pathsAtHead } from '../git/git.js';
+import { planSync } from './plan.js';
+import { RepoSyncRemote, findBucketId } from './remote.js';
+import { clearNote, readNote } from './notes.js';
+/** How long the worker's local run lock (`sync_run:<slug>`) is honoured before it is assumed stale. */
+export const WORKER_LOCK_MS = 45 * 60_000;
+/**
+ * How long an interactive `sync begin` blocks the hook-mode worker for, before the marker is
+ * assumed abandoned by a crashed session. Wider than the worker's own lock because the model
+ * runs in between `begin` and `end`, off the machine's own clock.
+ */
+export const INTERACTIVE_LOCK_MS = 60 * 60_000;
+/**
+ * Whether the background worker holds this repository's local run lock right now. The worker and
+ * an interactive run share one holder identity (this machine's), so core's lease alone can't tell
+ * them apart: it would let an interactive `begin` renew straight over a worker mid-rewrite, and
+ * either side's `end` would release a lease the other still needs. This lock is what actually
+ * separates them.
+ */
+export function workerRunning(state, slug) {
+    const startedAt = Number(state.getMeta(`sync_run:${slug}`) ?? 0);
+    return startedAt > 0 && Date.now() - startedAt < WORKER_LOCK_MS;
+}
+/**
+ * Whether an interactive `sync begin` is in flight for this repository on this machine. Hook mode
+ * checks this before touching anything, because `begin` and the hook's worker would otherwise
+ * claim core's lease under the same holder name and token key, so the second one in just renews
+ * over the first: both stages run against the same manifest and both rewrite the same memos, and
+ * whichever side's `finally` runs last releases a lease the other still needs. The marker carries
+ * its own TTL, since nothing renews it while the model runs between `begin` and `end`, so a
+ * crashed interactive session doesn't block sync forever.
+ */
+export function interactiveRunning(state, slug) {
+    const startedAt = Number(state.getMeta(`sync_interactive:${slug}`) ?? 0);
+    return startedAt > 0 && Date.now() - startedAt < INTERACTIVE_LOCK_MS;
+}
+/** Marks an interactive `sync begin` as in flight. Paired with `clearInteractiveRun`. */
+export function markInteractiveRun(state, slug) {
+    state.setMeta(`sync_interactive:${slug}`, String(Date.now()));
+}
+/** Clears the interactive marker, letting hook mode run again. Idempotent. */
+export function clearInteractiveRun(state, slug) {
+    state.setMeta(`sync_interactive:${slug}`, '');
+}
+/** `<hostname> <8 characters of a random id kept in state.db>`, in the characters core accepts for a holder. */
+export function holderName(state) {
+    let id = state.getMeta('machine_id');
+    if (!id) {
+        id = randomUUID();
+        state.setMeta('machine_id', id);
+    }
+    const host = hostname().replace(/[^A-Za-z0-9 .:@_-]/g, '-').slice(0, 100) || 'machine';
+    return `${host} ${id.slice(0, 8)}`;
+}
+/**
+ * The holder name and the state.db key holding the lease token, kept separate per mode so the
+ * hook-mode worker never sends the interactive run's cached token to core, and so core's lease
+ * itself tells the two apart by holder name if they ever do overlap.
+ */
+export function holderFor(state, mode) {
+    const base = holderName(state);
+    return mode === 'hook' ? `${base} worker` : base;
+}
+/** @internal exported for finishSync and the worker, which must clear the same key they claimed. */
+export function leaseMetaKey(slug, mode) {
+    return mode === 'hook' ? `lease:${slug}:worker` : `lease:${slug}`;
+}
+export async function pushUnpushed(state, slug, remote) {
+    const rows = state.unpushedFiles(slug);
+    if (rows.length === 0)
+        return 0;
+    await remote.record(rows, []);
+    state.markPushed(slug, rows.map(r => r.path));
+    return rows.length;
+}
+/**
+ * A slug is only unique within a workspace, so the cache of which bucket it resolved to must be
+ * too: rebinding this repository to another workspace under the same slug must not reuse the
+ * first workspace's id.
+ */
+export function bucketCacheKey(target) {
+    return `bucket_id:${target.workspaceId ?? 'default'}:${target.slug}`;
+}
+async function bucketIdOf(state, target, opts = {}) {
+    const key = bucketCacheKey(target);
+    if (!opts.forceRefresh) {
+        const cached = state.getMeta(key);
+        if (cached)
+            return cached;
+    }
+    const found = await findBucketId(target.rag(), target.slug);
+    state.setMeta(key, found ?? '');
+    return found;
+}
+/**
+ * Core's message for a bucket this key cannot reach, kept in one place so the cache-drop below
+ * matches it. core.CLAUDE.md's "Errors are instructions" fix belongs to core's wording; this only
+ * has to recognise it, since the MCP SDK strips every field but the message off a thrown error.
+ */
+const BUCKET_UNREACHABLE = /cannot reach bucket .+ to sync it/;
+/**
+ * A bucket id cached under the right key can still be wrong: the bucket behind it was deleted and
+ * recreated with a new id, under the same slug and workspace. Nothing invalidates that on its own,
+ * so the first call that finds out drops the cache and resolves once more before giving up, rather
+ * than failing bucket_unreachable on every sync from here on.
+ */
+async function resolveBucket(state, target, bucketId) {
+    try {
+        const remote = new RepoSyncRemote(target.rag(), bucketId);
+        return { bucketId, remote, remoteState: await remote.state() };
+    }
+    catch (e) {
+        if (!(e instanceof Error) || !BUCKET_UNREACHABLE.test(e.message))
+            throw e;
+        state.setMeta(bucketCacheKey(target), '');
+        const refreshed = await bucketIdOf(state, target, { forceRefresh: true });
+        if (!refreshed || refreshed === bucketId)
+            throw e;
+        const remote = new RepoSyncRemote(target.rag(), refreshed);
+        return { bucketId: refreshed, remote, remoteState: await remote.state() };
+    }
+}
+/**
+ * Everything a sync does that needs no model: guards, lease, the manifest
+ * round trip, then renames, deletions and stale marks. Returns 'stop' with a
+ * message for a person (interactive) or a note (hook), or 'ok' holding the
+ * lease, which the caller must pass to finishSync or release.
+ */
+export async function runStage(state, target, opts) {
+    const hook = opts.mode === 'hook';
+    const slug = target.slug;
+    const head = target.git ? headCommit(target.root) : undefined;
+    const branch = target.git ? currentBranch(target.root) : undefined;
+    // A hook-mode stop that doesn't write its own note (every one below except the ones that
+    // return a `note`) must still clear a stale `deferred` note left by an earlier run: otherwise
+    // once this run stops for some other reason (not opted in, no bucket, not set up, another
+    // branch) that leftover note keeps claiming a sync is queued forever, telling every session
+    // that opens meanwhile to wait for a rewrite that will never come, and every commit still spawns
+    // a worker whose only job is to discover that and give up silently. It must clear only a
+    // `deferred` note, and never any other kind: `needs_approval`, `no_agent`, `dirty` or `failed`
+    // can be sitting there from a run on the branch GigaRAG actually syncs, and a silent stop here
+    // (a commit made on some other branch in the meantime, say) must not wipe it out from under a
+    // developer who later comes back to the branch that note was actually about.
+    const stop = (message, note) => {
+        if (hook && !note && readNote(state, slug)?.kind === 'deferred')
+            clearNote(state, slug);
+        return note ? { kind: 'stop', message, note } : { kind: 'stop', message };
+    };
+    // Gated on this machine's own record of having run `gigarag hooks install` here, never on the
+    // bucket's shared `initialised` flag: that flag is the same for every teammate, so a hook file
+    // that reaches this machine without this person running install here themselves (checked into
+    // git, or copied) must do nothing and touch neither the network nor state.db beyond this read.
+    // Checked first, before even the untrusted-binding check below: a machine that never opted in
+    // must do nothing and write no note of any kind for a hook-triggered sync, untrusted binding or
+    // not. Otherwise a machine that never ran install, on receiving a tracked hook file plus a
+    // committed .gigarag.json naming some other workspace (an attacker's, or simply one nobody here
+    // reviewed), would still write an `untrusted` note and have SessionStart nudge whoever opens
+    // this repository next to run `gigarag trust`, encouraging them to trust a binding on a machine
+    // where nothing GigaRAG does was ever asked to run in the first place. Interactive `begin` has
+    // no such gate, so its untrusted refusal below still fires first for it.
+    if (hook && !hooksOptedIn(target.root, state)) {
+        return stop('not opted in on this machine');
+    }
+    // A binding at this repository's root that has not been trusted (`gigarag use` or `gigarag
+    // trust`) must never steer a sync anywhere, checked before anything below touches core: unlike
+    // `resolveWorkspace`, which falls back to the machine default and says so, sync has no safe
+    // fallback, since the file is committed and read before anyone has reviewed it. Reaching this
+    // far with `target.untrustedWorkspace` set would otherwise still resolve and claim a bucket
+    // (under the default workspace, since `workspaceId` is unset for this target) rather than
+    // refuse outright. See binding.ts and GUIDE.md.
+    if (target.untrustedWorkspace) {
+        const ws = target.untrustedWorkspace;
+        return stop(`${target.root}'s .gigarag.json links this repository to workspace ${ws}, which has not been trusted, so sync did not run and will not until it is. Retrying will not help. If you placed or reviewed this file yourself, run: gigarag trust. To use a different workspace instead: gigarag use <workspace>.`, hook ? { kind: 'untrusted', detail: ws } : undefined);
+    }
+    // The background worker and an interactive run on this machine claim core's lease under the
+    // same holder name, so core alone would let this begin renew straight over a worker mid-rewrite
+    // and then release the lease the worker still holds. Step aside instead of racing it.
+    if (!hook && workerRunning(state, slug)) {
+        return stop(`A background sync is already running for ${slug} on this machine, so starting one here would take over its lease mid-rewrite. It finishes on its own within 45 minutes; run /gigasync again after that, or gigarag sync status to check.`);
+    }
+    // The reverse of the worker check above: an interactive /gigasync can run for as long as the
+    // model takes, off any lock the worker itself holds, so the hook's worker checks the marker
+    // /gigasync sets before it does anything else. The `deferred` note tells the worker's own loop
+    // (and, failing that, a session that opens meanwhile) that this request is queued, not dropped:
+    // the commit that triggered it still gets synced once the marker clears, rather than only the
+    // next one to arrive.
+    if (hook && interactiveRunning(state, slug)) {
+        return stop(`An interactive /gigasync is running for ${slug} on this machine, so the background sync steps aside until it finishes.`, {
+            kind: 'deferred',
+        });
+    }
+    const firstBucketId = await bucketIdOf(state, target);
+    if (!firstBucketId) {
+        return stop(`GigaRAG has no bucket for ${slug} yet, so there is nothing to sync. Run /gigaindex in this repository first.`);
+    }
+    const { bucketId, remote, remoteState: s } = await resolveBucket(state, target, firstBucketId);
+    if (hook && (!s.initialised || !s.branch))
+        return stop('not set up for automatic sync');
+    if (s.branch && branch !== s.branch && !opts.force) {
+        const where = branch ? `branch ${branch}` : 'a detached HEAD';
+        return stop(hook
+            ? 'another branch'
+            : `This checkout is on ${where}, and GigaRAG syncs ${s.branch} for ${slug}. Switch to ${s.branch} and run /gigasync again, or run gigarag sync begin --force to sync this checkout anyway, which rewrites the memos to match it.`);
+    }
+    // An amend, a rebase (post-rewrite runs this hook) or a --force sync of another branch leaves
+    // HEAD holding last_commit's content without HEAD containing it as an ancestor. That is a
+    // rewrite, not a regression: last_commit is not an ancestor of HEAD either, so refusing here
+    // forever would strand the repository with no way for "git pull" to help, as the old note
+    // claimed. Only stop when HEAD is genuinely behind: last_commit is still an ancestor of HEAD
+    // (nothing to do, handled above) rules that out, and otherwise this is behind only when HEAD
+    // is an ancestor of last_commit, or last_commit is unknown here at all (not fetched or gc'd,
+    // where neither direction can be checked). A true divergence proceeds and lets the manifest's
+    // content hashes, not commit ancestry, decide what changed.
+    if (s.last_commit && head && !opts.force) {
+        const containsLastSynced = isAncestor(target.root, s.last_commit);
+        const genuinelyBehind = containsLastSynced === undefined || (containsLastSynced === false && isAncestor(target.root, head, s.last_commit) === true);
+        if (genuinelyBehind) {
+            const short = s.last_commit.slice(0, 7);
+            return {
+                kind: 'stop',
+                note: { kind: 'behind', commit: s.last_commit },
+                message: `This checkout doesn't contain ${short}, the commit GigaRAG last synced for ${slug}, so syncing it would rewrite memos to older code. Pull ${s.branch ?? 'the branch'} (git pull) and run /gigasync again, or run gigarag sync begin --force to sync this checkout anyway.`,
+            };
+        }
+    }
+    const leaseKey = leaseMetaKey(slug, opts.mode);
+    const claim = await remote.claim(holderFor(state, opts.mode), state.getMeta(leaseKey) || undefined);
+    if (!claim.granted)
+        return { kind: 'stop', note: { kind: 'held' }, message: claim.message };
+    state.setMeta(leaseKey, claim.token);
+    try {
+        await pushUnpushed(state, slug, remote);
+        state.replaceManifest(slug, (await remote.manifest()).map(m => ({ path: m.path, hash: m.hash, nodeIds: m.node_ids })));
+        const manifest = scanTree(target.root, { state, slug, all: true });
+        const plan = planSync({
+            known: state.manifestOf(slug),
+            current: new Map(manifest.files.map(f => [f.path, f.hash])),
+            truncated: manifest.truncated,
+            allowMassDelete: !hook && Boolean(opts.force),
+            ...(hook && target.git ? { atHead: pathsAtHead(target.root) } : {}),
+        });
+        if (plan.suspicious && !opts.force) {
+            if (!hook) {
+                await remote.release(claim.token);
+                state.setMeta(leaseKey, '');
+                return {
+                    kind: 'stop',
+                    note: { kind: 'mass_delete', files: plan.goneCount },
+                    message: `${plan.goneCount} files in ${slug} look deleted, more than half of what was indexed, so no memos were deleted. If they really are gone, run gigarag sync begin --force to delete their memos. If not, restore the checkout and run /gigasync again.`,
+                };
+            }
+        }
+        // A memo a teammate already deleted answers like a forbidden one, so a failed delete is counted, not fatal.
+        let deleteErrors = 0;
+        for (const id of plan.deleteNodeIds) {
+            try {
+                await target.rag().deleteNode(id);
+            }
+            catch {
+                deleteErrors++;
+            }
+            state.deleteNode(id);
+        }
+        for (const r of plan.renames)
+            state.renameFile(slug, r.from, r.to);
+        for (const p of plan.deletedPaths)
+            state.forgetFile(slug, p);
+        await remote.record(plan.renames.map(r => ({ path: r.to, hash: r.hash, nodeIds: r.nodeIds })), [...plan.renames.map(r => r.from), ...plan.deletedPaths]);
+        state.markPushed(slug, plan.renames.map(r => r.to));
+        if (head && plan.stale.length > 0)
+            await remote.markStale(plan.stale, head);
+        const message = `Synced the manifest for ${slug}: ${plan.renames.length} renamed, ${plan.deleteNodeIds.length} memos deleted, ` +
+            `${plan.stale.length} memos marked stale. ${plan.rewrite.length + plan.partial.length} files are left for the indexer.`;
+        return { kind: 'ok', bucketId, token: claim.token, ...(head ? { head } : {}), plan, deleteErrors, message };
+    }
+    catch (e) {
+        await remote.release(claim.token);
+        state.setMeta(leaseKey, '');
+        throw e;
+    }
+}
+/**
+ * Push what the indexer recorded, move the last synced commit when nothing is
+ * left to do, and release the lease. `init` also sets the branch, which is how
+ * /gigaindex opts a repository in.
+ */
+export async function finishSync(state, target, opts) {
+    const slug = target.slug;
+    const leaseKey = leaseMetaKey(slug, opts.mode ?? 'interactive');
+    const remote = new RepoSyncRemote(target.rag(), opts.bucketId);
+    await pushUnpushed(state, slug, remote);
+    const manifest = scanTree(target.root, { state, slug });
+    const remaining = manifest.summary.new + manifest.summary.changed + manifest.removed.length;
+    const head = target.git ? headCommit(target.root) : undefined;
+    // An --init that could not advance (the indexer left files) is remembered, so the next end that
+    // does advance also records the branch. Without this the repository never opts in.
+    const initPending = Boolean(opts.init) || state.getMeta(`sync_init:${slug}`) === '1';
+    const branch = initPending && target.git ? currentBranch(target.root) : undefined;
+    let advanced = false;
+    try {
+        if (remaining === 0 && head && opts.token) {
+            await remote.advance(opts.token, head, branch);
+            advanced = true;
+            clearNote(state, slug);
+        }
+        state.setMeta(`sync_init:${slug}`, initPending && !advanced ? '1' : '');
+    }
+    finally {
+        if (opts.token)
+            await remote.release(opts.token);
+        state.setMeta(leaseKey, '');
+    }
+    const message = advanced
+        ? `GigaRAG is in sync with ${slug} at ${head.slice(0, 7)}${branch ? ` on ${branch}` : ''}.`
+        : remaining > 0
+            ? `${remaining} files in ${slug} are still new, changed or gone, so the last synced commit stays where it was. Run /gigasync to finish.`
+            : `${slug} is not a git checkout, so there is no commit to record. The manifest is saved.`;
+    return { advanced, remaining, message };
+}

package/cli/sync/target.js

@@ -0,0 +1,14 @@
+import { GigaRag } from '../sdk.js';
+import { syncSlug } from './slug.js';
+export function syncTarget(start) {
+    const { root, git, slug, workspaceId, untrustedWorkspace } = syncSlug(start);
+    let client;
+    return {
+        root,
+        slug,
+        git,
+        ...(workspaceId ? { workspaceId } : {}),
+        ...(untrustedWorkspace ? { untrustedWorkspace } : {}),
+        rag: () => (client ??= new GigaRag({ actor: 'agent:gigarag-sync', ...(workspaceId ? { workspaceId } : {}) })),
+    };
+}