@hwip/cli 0.0.1 → 0.1.1

package/dist/verify.js

@@ -0,0 +1,396 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleVerify = exports.classifyMcpRegistration = exports.binaryResolves = exports.registeredMcpArgv = exports.UNREADABLE = exports.readCodexMcpArgv = exports.claudeHasHwip = void 0;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const agents_js_1 = require("./agents.js");
+const config_js_1 = require("./config.js");
+const listener_service_js_1 = require("./listener-service.js");
+const hwip_hook_js_1 = require("./hwip-hook.js");
+const jsonc_doc_js_1 = require("./jsonc-doc.js");
+const notify_failure_js_1 = require("./notify-failure.js");
+const codex_config_js_1 = require("./codex-config.js");
+const mcp_command_js_1 = require("./mcp-command.js");
+const listener_process_js_1 = require("./listener-process.js");
+const insecure_url_js_1 = require("./insecure-url.js");
+const redact_js_1 = require("./redact.js");
+const ws_url_js_1 = require("./ws-url.js");
+const args_js_1 = require("./args.js");
+const HOME = (0, os_1.homedir)();
+/** A settings file's value — `{}` for an empty file and without an editor's BOM,
+ *  comments and trailing commas allowed, as the installer reads it; undefined
+ *  when it is missing or does not parse. */
+const readJson = (filePath) => {
+    try {
+        return (0, jsonc_doc_js_1.parseJsonc)((0, fs_1.readFileSync)(filePath, 'utf-8'));
+    }
+    catch {
+        return undefined;
+    }
+};
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** Is the hwip plugin installed in Claude Code, or a `hwip` MCP server registered in ~/.claude.json? Exported for tests. */
+const claudeHasHwip = (home) => {
+    const installed = readJson((0, path_1.join)(home, '.claude', 'plugins', 'installed_plugins.json'));
+    const plugins = isPlainObject(installed) ? installed.plugins : undefined;
+    const installs = isPlainObject(plugins) ? plugins['hwip@hwip'] : undefined;
+    // An array of installs (v2), or one install object (v1).
+    if ((Array.isArray(installs) && installs.length > 0) || isPlainObject(installs))
+        return true;
+    const claude = readJson((0, path_1.join)(home, '.claude.json'));
+    const servers = isPlainObject(claude) ? claude.mcpServers : undefined;
+    return isPlainObject(servers) && 'hwip' in servers;
+};
+exports.claudeHasHwip = claudeHasHwip;
+/** Does a shared rule file contain the Hwip managed block? */
+const hasManagedBlock = (filePath) => {
+    try {
+        return (0, fs_1.readFileSync)(filePath, 'utf-8').includes('HWIP:START');
+    }
+    catch {
+        return false;
+    }
+};
+// Per-agent: report whether the rule artifact Hwip installs is present.
+const AGENT_RULE_PRESENT = {
+    // The plugin `hwip install` adds, or an MCP server registered by hand —
+    // not any mention of "hwip" anywhere in ~/.claude.json (a project path).
+    claude: () => (0, exports.claudeHasHwip)(HOME),
+    cursor: () => (0, fs_1.existsSync)((0, path_1.join)(HOME, '.cursor', 'rules', 'hwip.mdc')),
+    windsurf: () => hasManagedBlock((0, path_1.join)(HOME, '.codeium', 'windsurf', 'memories', 'global_rules.md')),
+    gemini: () => hasManagedBlock((0, path_1.join)(HOME, '.gemini', 'GEMINI.md')),
+    codex: () => hasManagedBlock((0, path_1.join)(HOME, '.codex', 'AGENTS.md')),
+    copilot: () => (0, fs_1.existsSync)((0, path_1.join)(HOME, '.copilot', 'instructions', 'hwip.instructions.md')),
+    cline: () => (0, fs_1.existsSync)((0, path_1.join)(HOME, '.cline', 'rules', 'hwip.md')),
+    aider: () => (0, fs_1.existsSync)((0, path_1.join)(HOME, '.hwip', 'aider-conventions.md')),
+    pi: () => hasManagedBlock((0, path_1.join)(HOME, '.pi', 'agent', 'AGENTS.md')),
+    opencode: () => hasManagedBlock((0, path_1.join)(HOME, '.config', 'opencode', 'AGENTS.md')),
+};
+/** Codex keeps its registry in TOML, so its reader is text-level — the table
+ *  shape lives in codex-config.ts, which install and uninstall share. */
+const readCodexMcpArgv = (filePath) => {
+    try {
+        return (0, codex_config_js_1.readHwipMcpArgv)((0, fs_1.readFileSync)(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+};
+exports.readCodexMcpArgv = readCodexMcpArgv;
+/**
+ * Where each agent records the MCP launch, and how to read it back — the row
+ * carries its own reader because codex keeps its registry in TOML while every
+ * other agent keeps it in JSON.
+ * `agent` matches the label `detectAgents` uses so one report never names the
+ * same agent two ways. Cursor/Windsurf/OpenCode are files the installer writes
+ * itself; the Gemini row is READ-ONLY — `hwip install` shells out to
+ * `gemini mcp add`, so this path is the gemini CLI's own storage layout,
+ * confirmed by reading the file it produced, not something Hwip chose.
+ */
+const MCP_REGISTRIES = [
+    { agent: 'Cursor', path: (0, path_1.join)(HOME, '.cursor', 'mcp.json'), argv: (p) => (0, exports.registeredMcpArgv)(p, 'mcpServers') },
+    { agent: 'Windsurf', path: (0, path_1.join)(HOME, '.codeium', 'windsurf', 'mcp_config.json'), argv: (p) => (0, exports.registeredMcpArgv)(p, 'mcpServers') },
+    { agent: 'Gemini CLI', path: (0, path_1.join)(HOME, '.gemini', 'settings.json'), argv: (p) => (0, exports.registeredMcpArgv)(p, 'mcpServers') },
+    { agent: 'OpenCode', path: (0, path_1.join)(HOME, '.config', 'opencode', 'opencode.json'), argv: (p) => (0, exports.registeredMcpArgv)(p, 'mcp') },
+    { agent: 'Codex CLI', path: (0, path_1.join)(HOME, '.codex', 'config.toml'), argv: exports.readCodexMcpArgv },
+];
+/** A registry file that exists but is not a JSON object — its hwip entry, if any, is unknowable. */
+exports.UNREADABLE = 'unreadable';
+/**
+ * The launch argv a registry file records for hwip, verbatim — null when the
+ * file is absent or has no hwip entry, `UNREADABLE` when it exists but is not
+ * a JSON object. Two schemas in the wild:
+ * `command` + `args` (Cursor/Windsurf/Gemini) and `command` as a whole array
+ * (opencode). Returned as-is on purpose: a stale entry is only detectable if
+ * the reader does not normalize it into the shape it expects.
+ */
+const registeredMcpArgv = (filePath, key) => {
+    if (!(0, fs_1.existsSync)(filePath))
+        return null;
+    const data = readJson(filePath);
+    if (!isPlainObject(data))
+        return exports.UNREADABLE;
+    const container = data[key];
+    const entry = container?.hwip;
+    if (!entry)
+        return null;
+    if (Array.isArray(entry.command))
+        return entry.command.map(String);
+    if (typeof entry.command !== 'string')
+        return null;
+    return [entry.command, ...(Array.isArray(entry.args) ? entry.args.map(String) : [])];
+};
+exports.registeredMcpArgv = registeredMcpArgv;
+/**
+ * Can this launch binary actually be run? Registered commands come out of a
+ * config file, so unlike everywhere else in the CLI they can be an absolute
+ * path — `which` is the wrong question for one of those, hence the split.
+ * The bare-name half is `resolveCommand`; neither half touches a shell, so a
+ * path with a space in it stays one word and a `;` in the file stays inert.
+ */
+const binaryResolves = (bin) => {
+    if (!bin.includes('/'))
+        return (0, agents_js_1.resolveCommand)(bin) !== null;
+    try {
+        (0, fs_1.accessSync)(bin, fs_1.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+exports.binaryResolves = binaryResolves;
+/** null = this agent has no hwip registration at all, so there is nothing to report. */
+const classifyMcpRegistration = (argv, isOnPath) => {
+    if (!argv || argv.length === 0)
+        return null;
+    if (!isOnPath(argv[0]))
+        return { state: 'unresolvable', argv };
+    const isCanonical = argv.length === mcp_command_js_1.MCP_LAUNCH_ARGV.length
+        && argv.every((token, i) => token === mcp_command_js_1.MCP_LAUNCH_ARGV[i]);
+    return isCanonical ? { state: 'current' } : { state: 'stale', argv };
+};
+exports.classifyMcpRegistration = classifyMcpRegistration;
+/** The registries that actually hold a hwip entry, classified. Agents that were
+ *  never installed drop out here so the report has no row for them. */
+const activeMcpRegistrations = (isOnPath) => MCP_REGISTRIES.flatMap((registry) => {
+    const argv = registry.argv(registry.path);
+    if (argv === exports.UNREADABLE)
+        return [{ agent: registry.agent, result: { state: 'unreadable', path: registry.path } }];
+    const result = (0, exports.classifyMcpRegistration)(argv, isOnPath);
+    return result ? [{ agent: registry.agent, result }] : [];
+});
+/** Where a resolved WebSocket URL came from, in the user's terms. */
+const WS_SOURCE_LABEL = {
+    flag: '--ws-url',
+    config: '~/.hwip/config.json',
+    'env-deprecated': 'HWIP_WS_URL (deprecated)',
+    default: 'built-in default',
+};
+/**
+ * The URL the live daemon connected to, or null when none is running.
+ *
+ * The stamp first; the log only as a fallback, for a daemon started by a build
+ * that predates the stamp. Reading the log alone was not enough — it rotates at
+ * 5MB, and the daemon whose startup line has been rotated away is precisely the
+ * long-lived one whose config edit this check exists to catch.
+ */
+const liveListenerWsUrl = () => {
+    if ((0, listener_process_js_1.runningListenerPid)() === null)
+        return null;
+    const stamped = (0, listener_process_js_1.runningListenerWsUrl)();
+    if (stamped)
+        return stamped;
+    try {
+        return (0, ws_url_js_1.parseListenerStartUrl)((0, fs_1.readFileSync)(listener_process_js_1.LISTENER_LOG_FILE, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+};
+const handleVerify = async (args) => {
+    const doPing = (0, args_js_1.flagOn)(args, 'ping');
+    // `--json`: the same checks as one JSON object on stdout, nothing else.
+    const json = (0, args_js_1.flagOn)(args, 'json');
+    const say = (line) => { if (!json)
+        console.log(line); };
+    const checks = [];
+    let current = '';
+    const section = (name) => {
+        current = name;
+        say(`\n  ${name}:`);
+    };
+    const record = (label, state) => {
+        checks.push({ section: current, label, state });
+        say(`    ${state === 'pass' ? '✓' : state === 'warn' ? '!' : '✗'} ${label}`);
+    };
+    // A bare flag parses as `true`, which is no key and no URL.
+    const flag = (name) => (typeof args[name] === 'string' ? args[name] : undefined);
+    say(`\n  Hwip verify — v${config_js_1.VERSION}`);
+    // ── Credentials ──────────────────────────────────────────────
+    section('Credentials');
+    const config = (0, config_js_1.loadConfig)();
+    // Resolved as every other command resolves them (cli.ts createHook), so
+    // `--ping` tests the key and the API the user's commands actually use.
+    const keySource = flag('key') ? '--key' : (0, config_js_1.resolvedEnv)('HWIP_API_KEY') ? 'HWIP_API_KEY' : config.apiKey ? '~/.hwip/config.json' : null;
+    const apiKey = flag('key') || (0, config_js_1.resolvedEnv)('HWIP_API_KEY') || config.apiKey;
+    const fileKey = (0, config_js_1.keyIsFromFile)(flag('key'), config);
+    // A config.json that cannot be used is a failure of its own, whatever else resolves: the listener runs with its options off.
+    const ignored = (0, config_js_1.configIgnoredBecause)();
+    if (ignored) {
+        record(`${ignored} — the listener runs with its options off (turn history, keep-awake) and nothing writes over it: fix it, or move it aside`, 'fail');
+    }
+    let baseUrl = ws_url_js_1.DEFAULT_API_BASE;
+    let baseKnown = true;
+    try {
+        baseUrl = (0, config_js_1.resolveBaseUrl)(flag('base-url'), config, fileKey);
+    }
+    catch (err) {
+        baseKnown = false;
+        record(err instanceof Error ? err.message : String(err), 'fail');
+    }
+    const hookId = (0, config_js_1.resolveHookId)();
+    const baseInsecure = (0, insecure_url_js_1.insecureUrlWarning)(baseUrl);
+    record(keySource ? `API key set (from ${keySource})` : 'API key not set (--key, HWIP_API_KEY or ~/.hwip/config.json)', apiKey ? 'pass' : 'fail');
+    record(hookId
+        ? 'HWIP_HOOK_ID is set (two-way hwip_ask enabled)'
+        : 'HWIP_HOOK_ID not set (notify-only — set it for remote control)', hookId ? 'pass' : 'warn');
+    if (baseInsecure)
+        record(baseInsecure.replace(/^hwip: /, ''), 'warn');
+    // ── Runtime ──────────────────────────────────────────────────
+    // One resolution per binary: `hwip` alone was being looked up five times
+    // (twice here, once per registry below), and each lookup is a spawn.
+    const resolved = new Map();
+    const resolves = (bin) => {
+        const cached = resolved.get(bin);
+        if (cached !== undefined)
+            return cached;
+        const found = (0, exports.binaryResolves)(bin);
+        resolved.set(bin, found);
+        return found;
+    };
+    section('Runtime');
+    const hasNode = resolves('node');
+    const hasNpx = resolves('npx');
+    const hasHwip = resolves('hwip');
+    record(hasNode ? 'node available' : 'node not found', hasNode ? 'pass' : 'fail');
+    record(hasNpx ? 'npx available (hook fallback when hwip is off PATH)' : 'npx not found', hasNpx ? 'pass' : 'warn');
+    // Not a warning any more: `hwip mcp` IS the MCP server, so a hwip that
+    // isn't on PATH means no MCP tools at all, not just a slower first call.
+    record(hasHwip
+        ? 'hwip CLI on PATH (runs the MCP server and the hooks)'
+        : 'hwip CLI not on PATH — MCP tools will not start. Reinstall: npm i -g @hwip/cli', hasHwip ? 'pass' : 'fail');
+    // Notify-only setups need neither, so both are warnings. The listener
+    // dies on a missing key or tmux and says so only in its log.
+    const hasTmux = resolves('tmux');
+    record(hasTmux
+        ? 'tmux available (hwip cc and phone control run in it)'
+        : 'tmux not found — hwip cc and phone control need it', hasTmux ? 'pass' : 'warn');
+    // A reused pid is alive too: only a listener's command line counts, as in
+    // the daemon's own startup guard.
+    const pidOnRecord = (0, listener_process_js_1.runningListenerPid)();
+    const listenerPid = pidOnRecord !== null && (0, listener_process_js_1.isListenerPid)(pidOnRecord) ? pidOnRecord : null;
+    record(listenerPid !== null
+        ? `listener running (pid ${listenerPid})`
+        : `listener not running — the phone cannot reach agent sessions; \`hwip cc\` starts it (log: ${listener_process_js_1.LISTENER_LOG_FILE})`, listenerPid !== null ? 'pass' : 'warn');
+    // ── Login-time service ───────────────────────────────────────
+    // Optional, so a missing one is a warning. A broken one is not: every way
+    // it breaks still looks installed from the outside.
+    const serviceRows = (0, listener_service_js_1.serviceHealthChecks)((0, listener_service_js_1.serviceStatus)());
+    if (serviceRows.length > 0) {
+        section('Login-time service');
+        for (const row of serviceRows)
+            record(row.label, row.state);
+    }
+    // ── WebSocket ────────────────────────────────────────────────
+    // The phone's Agents list is fed over this socket, so a machine on the
+    // wrong stage is simply absent from the app with nothing to explain it.
+    section('WebSocket');
+    const wsBaseUrl = baseUrl;
+    const staleWsEnv = (0, ws_url_js_1.legacyWsEnvNotice)(config, process.env, fileKey ? { baseUrl: wsBaseUrl } : undefined);
+    if (staleWsEnv)
+        record(staleWsEnv.replace(/^hwip: /, ''), 'warn');
+    const ws = (0, ws_url_js_1.resolveWsUrlDetailed)(args, config, wsBaseUrl, fileKey);
+    if (!baseKnown) {
+        record('WebSocket URL not checked — it and the API base may be set in the config.json that cannot be read', 'warn');
+    }
+    else if (!ws) {
+        record('no WebSocket URL, and none can be guessed for a custom API base — set "wsUrl" in ~/.hwip/config.json', 'fail');
+    }
+    else {
+        const wsProblem = (0, ws_url_js_1.wsUrlProblem)(ws.url);
+        const wsInsecure = wsProblem ? null : (0, insecure_url_js_1.insecureUrlWarning)(ws.url);
+        record(wsProblem ?? `${(0, redact_js_1.redactSecrets)(ws.url)} (from ${WS_SOURCE_LABEL[ws.source]})`, wsProblem ? 'fail' : 'pass');
+        if (wsInsecure)
+            record(wsInsecure.replace(/^hwip: /, ''), 'warn');
+        // Socket on one stage and REST on another splits the device: pushes go
+        // one way, the agent list the other, and neither half looks broken.
+        const wsStage = (0, ws_url_js_1.endpointStage)(ws.url);
+        const apiStage = (0, ws_url_js_1.endpointStage)(wsBaseUrl);
+        record(wsStage === apiStage
+            ? `API base is the same stage (${apiStage})`
+            : `stage mismatch — socket is ${wsStage}, API base is ${apiStage} (${wsBaseUrl}). Pushes and the agent list would land in different environments`, wsStage === apiStage ? 'pass' : 'warn');
+        // The daemon reads this once, at startup. Editing the config does
+        // nothing to a listener that has been up since before the edit — which
+        // looks exactly like the config not being read at all.
+        const live = liveListenerWsUrl();
+        if (live && live !== ws.url) {
+            record(`the running listener is on ${live}, not the resolved URL — restart it: hwip listener --restart`, 'warn');
+        }
+    }
+    // ── MCP registrations ────────────────────────────────────────
+    const registrations = activeMcpRegistrations(resolves);
+    if (registrations.length > 0) {
+        section('MCP registrations');
+        for (const { agent, result } of registrations) {
+            if (result.state === 'current')
+                record(`${agent}: launches \`${mcp_command_js_1.MCP_LAUNCH_ARGV.join(' ')}\``, 'pass');
+            else if (result.state === 'stale') {
+                record(`${agent}: still launches \`${result.argv.join(' ')}\` — one extra resident process per session. Re-run: hwip install`, 'warn');
+            }
+            else if (result.state === 'unresolvable') {
+                record(`${agent}: launches \`${result.argv[0]}\`, which is not on PATH — hwip tools will not load. Re-run: hwip install`, 'fail');
+            }
+            else {
+                // Not "unregistered": an entry in a file nothing can parse is unknown, not absent.
+                record(`${agent}: could not read ${result.path} as a JSON object — check its hwip entry by hand`, 'warn');
+            }
+        }
+    }
+    // ── Last push ────────────────────────────────────────────────
+    // Hooks run `hwip notify` with stderr discarded, so this record is the only
+    // trace a failed push leaves (notify-failure.ts). A good push deletes it.
+    section('Push delivery');
+    const lastFailure = (0, notify_failure_js_1.readNotifyFailure)();
+    if (lastFailure) {
+        record((0, notify_failure_js_1.describeNotifyFailure)(lastFailure), (0, notify_failure_js_1.isTransientNotifyFailure)(lastFailure) ? 'warn' : 'fail');
+    }
+    else {
+        record('no failed push since the last successful one', 'pass');
+    }
+    // ── Per-agent config ─────────────────────────────────────────
+    section('Agents');
+    const detected = (0, agents_js_1.detectAgents)().filter((a) => a.detected);
+    if (detected.length === 0) {
+        record('no supported agents detected', 'warn');
+    }
+    for (const agent of detected) {
+        const present = AGENT_RULE_PRESENT[agent.id]?.() ?? false;
+        record(`${agent.name}: ${present ? 'Hwip rules installed' : 'Hwip rules NOT installed — run: hwip install'}`, present ? 'pass' : 'warn');
+    }
+    // ── Optional live API ping ───────────────────────────────────
+    if (doPing) {
+        section('API ping');
+        if (!apiKey) {
+            record('skipped — no API key', 'warn');
+        }
+        else if (!baseKnown) {
+            record('skipped — the key would go to the default API, not necessarily the one it belongs to', 'warn');
+        }
+        else {
+            try {
+                const hook = new hwip_hook_js_1.HwipHook({ apiKey, baseUrl });
+                await hook.list({ limit: 1 });
+                record('API reachable, key accepted', 'pass');
+            }
+            catch (err) {
+                record(`API call failed: ${err instanceof Error ? err.message : 'unknown'}`, 'fail');
+            }
+        }
+    }
+    // ── Summary ──────────────────────────────────────────────────
+    const fails = checks.filter((c) => c.state === 'fail').length;
+    const warns = checks.filter((c) => c.state === 'warn').length;
+    if (json) {
+        console.log(JSON.stringify({ version: config_js_1.VERSION, failed: fails, warnings: warns, checks }, null, 2));
+    }
+    else if (fails === 0 && warns === 0) {
+        console.log('\n  ✓ All checks passed.\n');
+    }
+    else {
+        console.log(`\n  ${fails} failed, ${warns} warnings.${doPing ? '' : ' (run with --ping to test the API)'}\n`);
+    }
+    return fails === 0 ? 0 : 1;
+};
+exports.handleVerify = handleVerify;

package/dist/worktree.d.ts

@@ -0,0 +1,144 @@
+/**
+ * `hwip <agent> --wt <name>`: a git worktree made for a session, and taken back
+ * when the session is over and nothing in it would be lost.
+ *
+ * hwip only ever removes a worktree it made itself — the rows in
+ * `<stateDir>/worktrees.json` are the whole list. A worktree the user made by
+ * hand, or one `--wt` merely found at the path, has no row and no code path
+ * here that removes it. Every doubt about a worktree (a git call that fails or
+ * times out, a count that does not parse) reads as "keep it": the cost of a
+ * leftover directory is a line in `hwip worktree`, the cost of a wrong removal
+ * is somebody's work. `--force`, `rm -rf` and `branch -D` are not used anywhere.
+ */
+/** A git call's outcome: its stdout, or the first line of what it said when it failed. */
+export type GitResult = {
+    ok: true;
+    stdout: string;
+} | {
+    ok: false;
+    error: string;
+};
+/** Runs `git <args>` (or tmux's); `timeoutMs` 0 means no timeout. Swappable in tests. */
+export type GitRun = (args: string[], timeoutMs?: number) => Promise<GitResult>;
+/** `execFile` of one command with argv (no shell: branch names and paths are user input), as a `GitRun`. */
+export declare const commandRunner: (cmd: string) => GitRun;
+export declare const gitRun: GitRun;
+export declare const tmuxRun: GitRun;
+/** One worktree hwip made. The lifecycle fields are written by `reconcileWorktrees`. */
+export interface WorktreeRow {
+    /** realpath of the worktree directory. */
+    path: string;
+    /** The main checkout it hangs off — where `git worktree remove` runs from. */
+    root: string;
+    branch: string;
+    /** HEAD when the worktree was made: commits after it are this worktree's own work. */
+    baseSha: string;
+    /** hwip made the branch too, so hwip may delete it (`branch -d`) with the worktree. */
+    createdBranch: boolean;
+    createdAt: string;
+    /** Last time a pane was seen inside it. A worktree no session has used yet is not "over". */
+    sessionSeenAt?: string;
+    /** When it was judged not removable, and why — the automatic pass says so once. */
+    keptAt?: string;
+    reasons?: string[];
+}
+export declare const readWorktreeRows: () => WorktreeRow[];
+/**
+ * Read, change, write. A row that cannot be written is a worktree that is not
+ * cleaned up automatically — the launch goes on. `expected` turns a write by
+ * the other process (wrapper vs listener) since the read into an error, which
+ * lands here too: a lost row only ever means "kept".
+ */
+export declare const updateWorktreeRows: (change: (rows: WorktreeRow[]) => WorktreeRow[]) => void;
+export type EnsureResult = {
+    ok: true;
+    path: string;
+    branch: string;
+    created: boolean;
+} | {
+    ok: false;
+    error: string;
+    usage: boolean;
+};
+/**
+ * The directory name of the worktree for branch `name` of the repo at `root`: `<repo>-wt-<name with separators as dashes>`.
+ * Null when nothing but separators is left. `hwip schedule add` names its session from this, so the two cannot drift.
+ */
+export declare const worktreeDirName: (root: string, name: string) => string | null;
+/** Whether `name` is a branch name git accepts as it stands (`--branch` also expands `@{-1}`-style names; one that changes is not what was typed). */
+export declare const isValidBranchName: (root: string, name: string, run?: GitRun) => Promise<boolean>;
+/**
+ * The worktree for branch `name` next to the main checkout of the repo `dir` is
+ * in — made, or found already made by this same command. Anything else at the
+ * path is refused and left alone.
+ */
+export declare const ensureWorktree: ({ dir, name }: {
+    dir: string;
+    name: string;
+}, run?: GitRun) => Promise<EnsureResult>;
+export type Inspection = {
+    removable: true;
+} | {
+    removable: false;
+    reasons: string[];
+};
+/**
+ * Whether this worktree can go without losing anything. Asked in git's own
+ * terms rather than left to `git worktree remove`, which deletes a worktree
+ * holding only ignored files (a hand-written `.env`) and one whose commits
+ * were never pushed (measured, git 2.47.0). Both checks always run, so the
+ * reasons are the whole list; a check that cannot be answered is a reason too.
+ */
+export declare const inspectWorktree: (row: WorktreeRow, run?: GitRun) => Promise<Inspection>;
+export interface ReconcileInput {
+    /** `pane_current_path` of every live tmux pane. The caller must have read them all: an empty list means "none". */
+    paneCwds: string[];
+    /** `hwip worktree clean`: judge every worktree not in use, not only the ones a session has just left. */
+    manual?: boolean;
+    /** Judge and report, change nothing (disk and registry alike). */
+    dryRun?: boolean;
+    now?: Date;
+}
+export interface ReconcileReport {
+    /** Gone (or, under `dryRun`, would be). */
+    removed: Array<{
+        path: string;
+        branch: string;
+        branchDeleted: boolean;
+    }>;
+    kept: Array<{
+        path: string;
+        branch: string;
+        reasons: string[];
+        removeFailed: boolean;
+    }>;
+    inUse: string[];
+    /** Rows whose directory is no longer there — the user removed it. */
+    gone: string[];
+}
+/**
+ * Which of the worktrees hwip made to take back, and which to keep and say why.
+ *
+ * Automatic (`manual` off): a worktree is judged once, after a pane was last
+ * seen inside it and none is now. Judging again later would delete a directory
+ * somebody went back into and pushed from, so a worktree that was kept stays
+ * kept until `hwip worktree clean`, or until a session uses it again.
+ *
+ * Rows are re-read when written, so a row the wrapper added while git was
+ * being asked about is not lost.
+ */
+export declare const reconcileWorktrees: (input: ReconcileInput, run?: GitRun) => Promise<ReconcileReport>;
+export interface WorktreeStatus {
+    row: WorktreeRow;
+    /** `in use`, `never used` (clean, and no session ever started in it), `clean`, or what keeps it. */
+    state: string;
+}
+/** What `hwip worktree` shows: every row with its state now. Read-only. */
+export declare const worktreeStatuses: (paneCwds: string[], run?: GitRun) => Promise<WorktreeStatus[]>;
+/**
+ * The cwd of every live tmux pane, `[]` when there is no tmux server, null when
+ * tmux could not be asked. The difference matters: an unreadable list read as
+ * empty would make every worktree in use look abandoned.
+ */
+export declare const readPaneCwds: (tmux?: GitRun) => Promise<string[] | null>;
+//# sourceMappingURL=worktree.d.ts.map