harnery 0.0.1 → 0.2.1

package/dist/commands/read.js

@@ -0,0 +1,46 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolveBinName } from "../core/config.js";
+import { htmlToMarkdown } from "../lib/readability/index.js";
+// Module-scoped emit assigned by registerReadCommand. Same pattern as cookies.ts:
+// the runRead helper closes over this so the .action callback stays concise.
+let emit;
+/**
+ * `harn read`: extract clean readable markdown from HTML.
+ */
+export function registerReadCommand(program, emitParam) {
+    emit = emitParam;
+    program
+        .command("read [html-file]")
+        .description(`Extract clean readable markdown from HTML. Reads from file or stdin (use '-'). Pair with \`${resolveBinName()} fetch\` or \`${resolveBinName()} browse\` for scrape-to-markdown.`)
+        .option("-o, --output <file>", "Write markdown to file instead of stdout")
+        .option("--url <url>", "Base URL: used to resolve relative links")
+        .option("--selector <css>", "Use this CSS selector instead of Readability (fallback when extraction misses content)")
+        .option("--raw", "Output cleaned HTML instead of markdown (debugging)")
+        .option("--max-chars <n>", "Truncate output to N characters (0 = disable)", "100000")
+        .action(async (htmlFile, opts) => {
+        try {
+            await runRead(htmlFile, opts);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            emit.error({ code: "read_error", message: msg });
+            process.exit(1);
+        }
+    });
+}
+async function runRead(htmlFile, opts) {
+    const input = htmlFile && htmlFile !== "-" ? readFileSync(htmlFile, "utf-8") : readFileSync(0, "utf-8");
+    const result = await htmlToMarkdown(input, {
+        url: opts.url,
+        selector: opts.selector,
+        raw: opts.raw,
+        maxChars: Number.parseInt(opts.maxChars, 10),
+    });
+    if (opts.output) {
+        writeFileSync(opts.output, result.output);
+        emit.file(opts.output, { chars: result.output.length });
+    }
+    else {
+        emit.text(result.output);
+    }
+}

package/dist/commands/scratch.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.js";
+export declare function registerScratchCommand(program: Command, emitParam: EmitContext): void;
+//# sourceMappingURL=scratch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scratch.d.ts","sourceRoot":"","sources":["../../src/commands/scratch.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AA6BnD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CA2RrF"}

package/dist/commands/scratch.js

@@ -0,0 +1,426 @@
+import { existsSync, readdirSync, readFileSync, statSync, unlinkSync, watch } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { emitCanonical, normalizeHarness, readHeartbeat } from "../core/agents/index.js";
+import { resolveBinName } from "../core/config.js";
+import { appendEntry, archiveScratch, currentOwnerOrThrow, lintScratch, listArchives, loadScratch, parseScratch, pruneArchives, resolveOwnerByName, SCRATCH_CATEGORIES, scratchDir, scratchPath, sweepOrphanScratchpads, } from "../lib/scratch/index.js";
+/**
+ * `harn scratch`: per-agent markdown journal at `.harnery/scratch/<instance_id>.md`.
+ * Used both for self-notes (surviving compaction) and peer coordination (other
+ * agents pull-read it on demand). SessionEnd hook archives; SessionStart
+ * janitor surfaces the most-recent archive as a recovery cue.
+ */
+let emit;
+export function registerScratchCommand(program, emitParam) {
+    emit = emitParam;
+    const root = program
+        .command("scratch")
+        .description("Per-agent markdown journal: append-only timestamped entries. " +
+        "Survives in-session compaction, archived at session end, pruned after 7 days.");
+    // ── add ───────────────────────────────────────────────────────────────
+    root
+        .command("add <category> <text...>")
+        .description(`Append an entry to my scratchpad. Category: ${SCRATCH_CATEGORIES.join(" | ")}`)
+        .action((category, text) => {
+        const cat = validateCategory(category);
+        const body = text.join(" ");
+        if (!body.trim()) {
+            emit.error({ code: "empty_body", message: "scratch add: body is empty" });
+            process.exit(1);
+        }
+        try {
+            const owner = currentOwnerOrThrow();
+            const doc = appendEntry(owner, cat, body);
+            const hb = readHeartbeat(owner);
+            emitCanonical({
+                type: "state.scratch_append",
+                owner,
+                session: hb?.session_id ?? owner,
+                harness: normalizeHarness(hb?.platform),
+                data: {
+                    category: cat,
+                    body_summary: body.length > 1000 ? `${body.slice(0, 997)}...` : body,
+                },
+            });
+            emit.data({
+                instance_id: owner,
+                name: doc.header.name,
+                category: cat,
+                entries: doc.entries.length,
+                bytes: doc.bytes,
+                path: doc.path,
+            });
+        }
+        catch (err) {
+            emit.error({ code: "add_failed", message: err.message });
+            process.exit(1);
+        }
+    });
+    // ── read ──────────────────────────────────────────────────────────────
+    root
+        .command("read")
+        .description("Render a scratchpad to stdout. No --name: my own. With --name: a peer's.")
+        .option("--name <name>", "Read the named peer's scratchpad (case-insensitive)")
+        .option("--owner <id>", "Read by instance_id directly")
+        .option("--archive <basename>", "Read an archive file (e.g. <owner>-<ts>.md)")
+        .option("--limit <n>", "Cap entries rendered (newest first)", "50")
+        .action((opts) => {
+        try {
+            runRead(opts);
+        }
+        catch (err) {
+            emit.error({ code: "read_failed", message: err.message });
+            process.exit(1);
+        }
+    });
+    // ── list ──────────────────────────────────────────────────────────────
+    root
+        .command("list")
+        .description("Summarize all active scratchpads + archive count")
+        .option("--archives", "List archive files instead of active scratchpads")
+        .action((opts) => {
+        try {
+            if (opts.archives) {
+                const items = listArchives().map((a) => {
+                    const doc = parseSafe(a.path);
+                    const lastEntry = doc?.entries[0];
+                    const ageMin = Math.floor((Date.now() - a.mtimeMs) / 60000);
+                    return {
+                        basename: a.basename,
+                        name: doc?.header.name ?? "unknown",
+                        entries: doc?.entries.length ?? 0,
+                        bytes: a.bytes,
+                        archived_min_ago: ageMin,
+                        last_category: lastEntry?.category ?? null,
+                        last_ts: lastEntry?.ts_display ?? null,
+                    };
+                });
+                emit.data({ rows: items });
+                return;
+            }
+            const dir = scratchDir();
+            const rows = [];
+            for (const f of readdirSync(dir)) {
+                if (!f.endsWith(".md"))
+                    continue;
+                const instanceId = f.replace(/\.md$/, "");
+                const doc = loadScratch(instanceId);
+                if (!doc)
+                    continue;
+                rows.push({
+                    instance_id: instanceId,
+                    name: doc.header.name,
+                    entries: doc.entries.length,
+                    bytes: doc.bytes,
+                    last_category: doc.entries[0]?.category ?? null,
+                    last_ts: doc.entries[0]?.ts_display ?? null,
+                });
+            }
+            rows.sort((a, b) => (b.last_ts ?? "").localeCompare(a.last_ts ?? ""));
+            emit.data({ rows });
+        }
+        catch (err) {
+            emit.error({ code: "list_failed", message: err.message });
+            process.exit(1);
+        }
+    });
+    // ── tail ──────────────────────────────────────────────────────────────
+    root
+        .command("tail")
+        .description("Follow my scratchpad (or a peer's) for new entries.")
+        .option("--name <name>", "Tail the named peer's scratchpad")
+        .option("--owner <id>", "Tail by instance_id directly")
+        .action(async (opts) => {
+        try {
+            const owner = resolveTargetOwner(opts);
+            const path = scratchPath(owner);
+            if (!existsSync(path)) {
+                emit.error({ code: "no_scratchpad", message: `no scratchpad at ${path} yet` });
+                process.exit(1);
+            }
+            process.stderr.write(`tailing ${path}\n`); // lint-ok-emission: tail banner, immediate stderr flush before streaming
+            let lastSize = statSync(path).size;
+            // Print initial render
+            process.stdout.write(`${renderScratch(loadScratch(owner), 10)}\n`); // lint-ok-emission: streaming tail body
+            const w = watch(path, { persistent: true }, () => {
+                try {
+                    const curr = statSync(path).size;
+                    if (curr === lastSize)
+                        return;
+                    lastSize = curr;
+                    const doc = loadScratch(owner);
+                    if (!doc)
+                        return;
+                    const newest = doc.entries[0];
+                    if (!newest)
+                        return;
+                    const line = `\n## ${newest.ts_display} · ${newest.category}\n${newest.body}\n`;
+                    process.stdout.write(line); // lint-ok-emission: streaming tail, per-line stdout flush, no envelope wrap
+                }
+                catch {
+                    // ignore transient
+                }
+            });
+            await new Promise((resolveP) => {
+                const stop = () => {
+                    w.close();
+                    resolveP();
+                };
+                process.on("SIGINT", stop);
+                process.on("SIGTERM", stop);
+            });
+        }
+        catch (err) {
+            emit.error({ code: "tail_failed", message: err.message });
+            process.exit(1);
+        }
+    });
+    // ── clear ─────────────────────────────────────────────────────────────
+    root
+        .command("clear")
+        .description("Delete my scratchpad (rare; mainly for testing)")
+        .option("--yes", "Confirm deletion")
+        .action((opts) => {
+        if (!opts.yes) {
+            emit.error({ code: "needs_yes", message: "pass --yes to confirm" });
+            process.exit(1);
+        }
+        try {
+            const owner = currentOwnerOrThrow();
+            const path = scratchPath(owner);
+            if (existsSync(path)) {
+                unlinkSync(path);
+                emit.data({ cleared: true, path });
+            }
+            else {
+                emit.data({ cleared: false, path, reason: "did not exist" });
+            }
+        }
+        catch (err) {
+            emit.error({ code: "clear_failed", message: err.message });
+            process.exit(1);
+        }
+    });
+    // ── lint ──────────────────────────────────────────────────────────────
+    root
+        .command("lint")
+        .description("Validate scratchpad format + size")
+        .option("--all", "Lint every scratchpad in .harnery/scratch/")
+        .option("--owner <id>", "Lint a specific owner's scratchpad")
+        .action((opts) => {
+        try {
+            runLint(opts);
+        }
+        catch (err) {
+            emit.error({ code: "lint_failed", message: err.message });
+            process.exit(1);
+        }
+    });
+    // ── archive (manual / hook helper) ────────────────────────────────────
+    root
+        .command("archive")
+        .description("Archive my scratchpad now (idempotent; fired by SessionEnd hook)")
+        .option("--owner <id>", "Archive a specific owner's scratchpad")
+        .action((opts) => {
+        try {
+            const owner = opts.owner ?? currentOwnerOrThrow();
+            const dest = archiveScratch(owner);
+            emit.data({ instance_id: owner, archived: !!dest, path: dest });
+        }
+        catch (err) {
+            emit.error({ code: "archive_failed", message: err.message });
+            process.exit(1);
+        }
+    });
+    // ── recovery-cue (SessionStart hook helper) ───────────────────────────
+    root
+        .command("recovery-cue")
+        .description("Emit a one-line recovery hint to stdout when a recent archive exists. " +
+        "Used by SessionStart hook to surface 'previous session was doing X'. " +
+        "Stays silent when no relevant archive (no noise on fresh sessions).")
+        .option("--max-age-hours <n>", "Only surface archives newer than this", "24")
+        .action((opts) => {
+        try {
+            const maxHours = Number.parseInt(opts.maxAgeHours, 10);
+            const archives = listArchives();
+            if (archives.length === 0)
+                return;
+            const newest = archives[0];
+            const ageHours = (Date.now() - newest.mtimeMs) / 3600_000;
+            if (ageHours > maxHours)
+                return;
+            const doc = parseSafe(newest.path);
+            if (!doc || doc.entries.length === 0)
+                return;
+            const last = doc.entries[0];
+            const ageMin = Math.floor((Date.now() - newest.mtimeMs) / 60_000);
+            const ageStr = ageMin < 60 ? `${ageMin}m` : `${Math.floor(ageMin / 60)}h ${ageMin % 60}m`;
+            const bodyOneLine = last.body.replace(/\s+/g, " ").trim();
+            const bodyTrunc = bodyOneLine.length > 100 ? `${bodyOneLine.slice(0, 99)}…` : bodyOneLine;
+            const cue = `Recent scratchpad archive (${ageStr} ago): agent-${doc.header.name}: ` +
+                `last entry [${last.category}] "${bodyTrunc}". ` +
+                `Read full: \`${resolveBinName()} scratch read --archive ${newest.basename}\`.`;
+            process.stdout.write(`${cue}\n`); // lint-ok-emission: bash hook reads stdout to compose SessionStart additionalContext
+        }
+        catch (_err) {
+            // Recovery cue is best-effort; never fail the SessionStart hook.
+        }
+    });
+    // ── janitor (SessionStart hook) ───────────────────────────────────────
+    root
+        .command("janitor")
+        .description("Prune old archives + sweep orphan scratchpads (heartbeat gone). Fired by SessionStart hook.")
+        .option("--days <n>", "Archive retention in days", "7")
+        .option("--quiet", "Suppress stdout output")
+        .action((opts) => {
+        try {
+            const days = Number.parseInt(opts.days, 10);
+            const swept = sweepOrphanScratchpads();
+            const pruned = pruneArchives(days);
+            if (!opts.quiet) {
+                emit.data({
+                    archives_pruned: pruned,
+                    orphans_swept: swept.length,
+                    orphans: swept,
+                });
+            }
+        }
+        catch (err) {
+            emit.error({ code: "janitor_failed", message: err.message });
+            process.exit(1);
+        }
+    });
+}
+// ─── runRead ──────────────────────────────────────────────────────────────
+function runRead(opts) {
+    const limit = Number.parseInt(opts.limit, 10);
+    if (opts.archive) {
+        const dir = scratchDir();
+        const path = resolvePath(dir, "archived", opts.archive);
+        if (!existsSync(path)) {
+            emit.error({ code: "no_archive", message: `archive not found: ${opts.archive}` });
+            process.exit(1);
+        }
+        const content = readFileSync(path, "utf8");
+        process.stdout.write(content); // lint-ok-emission: archive render, file content is already the rendered form
+        return;
+    }
+    const owner = resolveTargetOwner(opts);
+    const doc = loadScratch(owner);
+    if (!doc) {
+        emit.error({
+            code: "no_scratchpad",
+            message: `no scratchpad for owner=${owner.slice(0, 8)}… (file not created yet)`,
+        });
+        process.exit(1);
+    }
+    const hb = readHeartbeat(owner);
+    const staleBanner = renderStaleBannerIfNeeded(hb?.last_heartbeat);
+    process.stdout.write(`${staleBanner + renderScratch(doc, limit)}\n`); // lint-ok-emission: pretty render, multi-line markdown for direct TTY/pipe consumption
+}
+function runLint(opts) {
+    const dir = scratchDir();
+    const files = [];
+    if (opts.owner) {
+        files.push(scratchPath(opts.owner));
+    }
+    else if (opts.all) {
+        for (const f of readdirSync(dir)) {
+            if (f.endsWith(".md"))
+                files.push(resolvePath(dir, f));
+        }
+    }
+    else {
+        const owner = currentOwnerOrThrow();
+        files.push(scratchPath(owner));
+    }
+    let totalIssues = 0;
+    const reports = [];
+    for (const path of files) {
+        if (!existsSync(path)) {
+            reports.push({ path, issues: [{ line: 0, message: "(file does not exist)" }] });
+            continue;
+        }
+        const content = readFileSync(path, "utf8");
+        const issues = lintScratch(content);
+        if (issues.length > 0)
+            totalIssues += issues.length;
+        reports.push({ path, issues });
+    }
+    emit.data({ files: reports.length, total_issues: totalIssues, reports });
+    if (totalIssues > 0)
+        process.exit(1);
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────
+function validateCategory(c) {
+    if (!SCRATCH_CATEGORIES.includes(c)) {
+        emit.error({
+            code: "bad_category",
+            message: `category must be one of: ${SCRATCH_CATEGORIES.join(", ")}`,
+        });
+        process.exit(1);
+    }
+    return c;
+}
+function resolveTargetOwner(opts) {
+    if (opts.owner)
+        return opts.owner;
+    if (opts.name) {
+        const id = resolveOwnerByName(opts.name);
+        if (!id) {
+            emit.error({
+                code: "no_match",
+                message: `no live agent named "${opts.name}". Try \`${resolveBinName()} agents list\`.`,
+            });
+            process.exit(1);
+        }
+        return id;
+    }
+    return currentOwnerOrThrow();
+}
+function renderScratch(doc, limit) {
+    const lines = [];
+    lines.push(`# Scratchpad: agent-${doc.header.name}`);
+    if (doc.header.session_id)
+        lines.push(`session_id: ${doc.header.session_id}`);
+    if (doc.header.machine)
+        lines.push(`machine: ${doc.header.machine}`);
+    if (doc.header.started)
+        lines.push(`started: ${doc.header.started}`);
+    if (doc.header.last_updated)
+        lines.push(`last_updated: ${doc.header.last_updated}`);
+    lines.push("\n---\n");
+    for (const entry of doc.entries.slice(0, limit)) {
+        lines.push(`## ${entry.ts_display} · ${entry.category}`);
+        if (entry.body)
+            lines.push(entry.body);
+        lines.push("");
+    }
+    if (doc.entries.length > limit) {
+        lines.push(`(+${doc.entries.length - limit} older entries; raise --limit to see them)`);
+    }
+    return lines.join("\n").trimEnd();
+}
+const FRESHNESS_SECS = 600;
+function renderStaleBannerIfNeeded(lastHeartbeat) {
+    if (!lastHeartbeat)
+        return "";
+    const ts = Date.parse(lastHeartbeat);
+    if (!Number.isFinite(ts))
+        return "";
+    const ageSec = Math.floor((Date.now() - ts) / 1000);
+    if (ageSec < FRESHNESS_SECS)
+        return "";
+    const m = Math.floor(ageSec / 60);
+    return `[STALE: heartbeat ${m}m old, agent may be dead]\n\n`;
+}
+function parseSafe(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        const content = readFileSync(path, "utf8");
+        return parseScratch(path, content);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/commands/session.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.js";
+export declare function registerSessionCommand(program: Command, emitParam: EmitContext): void;
+//# sourceMappingURL=session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/commands/session.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAsCnD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CAsDrF"}

package/dist/commands/session.js

@@ -0,0 +1,162 @@
+import { spawn } from "node:child_process";
+import { resolveOwner, selfDisplayName } from "../core/agents/index.js";
+import { clampField, newCmdId, readLastIntent, writeSessionEvent, } from "../core/agents/session-events.js";
+import { resolveBinName } from "../core/config.js";
+/** Strip the `agent-` prefix so structured event `agent` field matches heartbeat.name. */
+function bareAgentName() {
+    const full = selfDisplayName();
+    return full.startsWith("agent-") ? full.slice(6) : full;
+}
+function selfOwnerId() {
+    return resolveOwner() ?? undefined;
+}
+/**
+ * `harn session`: run a command (or narrate) and emit canonical coordination
+ * events for follow-along.
+ *
+ * Follow-along happens through the canonical `.harnery/events.ndjson` stream +
+ * the `/live` web viewer (or `harn agents watch`): `harn session -- <cmd>` runs
+ * the command, forwards its output to the terminal verbatim, and emits canonical
+ * `command.start/output/end`; `harn session log` emits a canonical `narration`
+ * event. The file-management subcommands (`tail`/`clear`/`trim`/`path`) are
+ * retired no-op stubs; `trim` is a silent no-op so a SessionStart hook that
+ * calls it keeps working.
+ *
+ * Usage:
+ *   harn session "<intent>" -- <cmd> [args...]   run command, emit command.* events
+ *   harn session log "<message>"                 emit a narration event
+ */
+let emit;
+export function registerSessionCommand(program, emitParam) {
+    emit = emitParam;
+    const session = program
+        .command("session")
+        .description("Run a command (or narrate) and emit canonical coordination events");
+    // Narration-only entry → canonical narration event.
+    session
+        .command("log <message...>")
+        .description("Emit a narration event (no command run)")
+        .action((messageParts) => {
+        const message = messageParts.join(" ");
+        writeSessionEvent("narration", bareAgentName(), {
+            instance_id: selfOwnerId(),
+            message: clampField(message),
+        });
+        emit.text(`⋯ ${message}\n`);
+    });
+    // Retired file-management subcommands, kept as graceful no-op stubs so
+    // existing callers (hooks, muscle memory) don't error. `trim` is the one a
+    // hook invokes, so it must exit 0 silently.
+    session
+        .command("trim")
+        .description("(retired): no-op kept for hook compatibility")
+        .option("-y, --yes", "(ignored)")
+        .option("--max-entries <n>", "(ignored)")
+        .option("--max-bytes <size>", "(ignored)")
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(() => {
+        /* silent no-op, exit 0 */
+    });
+    for (const name of ["tail", "clear", "path"]) {
+        session
+            .command(name)
+            .description(`(retired): watch /live or '${resolveBinName()} agents watch'`)
+            .allowUnknownOption()
+            .action(() => {
+            emit.text(`Retired. Live activity flows to .harnery/events.ndjson; watch the /live web viewer or run '${resolveBinName()} agents watch'.\n`);
+        });
+    }
+    // Default form: harn session "<intent>" -- <cmd> [args]
+    session
+        .argument("<intent>", "One-line description of what this action is for")
+        .argument("<cmd...>", "The command to run (prefix with -- if it has its own flags)")
+        .allowUnknownOption()
+        .action((intent, cmd) => {
+        runLogged(intent, cmd);
+    });
+}
+// ---------------------------------------------------------------------------
+// Core
+// ---------------------------------------------------------------------------
+/**
+ * Strip ONLY carriage-return redraw noise (progress bars like `docker pull`'s
+ * sticky line) from a chunk before splitting into event lines. Terminal
+ * forwarding keeps the raw bytes; this only cleans the canonical event copy.
+ */
+function stripCRNoise(text) {
+    return text.replace(/[^\n]*\r(?!\n)/g, "");
+}
+function runLogged(intent, cmdArg) {
+    // Strip a leading `--` separator if commander left one in.
+    const cmd = cmdArg[0] === "--" ? cmdArg.slice(1) : cmdArg;
+    if (cmd.length === 0) {
+        emit.error({ code: "usage", message: "Usage: harn session <intent> -- <cmd> [args...]" });
+        process.exit(2);
+    }
+    const cmdLine = cmd.map(quoteArg).join(" ");
+    const agent = bareAgentName();
+    const instanceId = selfOwnerId();
+    const cmdId = newCmdId();
+    // Intent precedence: explicit arg wins; else the PreToolUse-stamped intent
+    // file; else the command line itself.
+    const resolvedIntent = intent && intent.trim().length > 0 ? intent : (readLastIntent(instanceId) ?? cmdLine);
+    writeSessionEvent("command_start", agent, {
+        instance_id: instanceId,
+        cmd_id: cmdId,
+        intent: clampField(resolvedIntent),
+        cmd: clampField(cmdLine),
+    });
+    const start = Date.now();
+    const child = spawn(cmd[0], cmd.slice(1), {
+        stdio: ["inherit", "pipe", "pipe"],
+        env: process.env,
+    });
+    child.stdout?.on("data", (chunk) => {
+        process.stdout.write(chunk); // lint-ok-emission: harn session forwards child stdout verbatim; this IS the command's primary purpose
+        for (const line of stripCRNoise(chunk.toString("utf8")).split("\n")) {
+            if (line.length === 0)
+                continue;
+            writeSessionEvent("output", agent, {
+                instance_id: instanceId,
+                cmd_id: cmdId,
+                stream: "stdout",
+                line: clampField(line),
+            });
+        }
+    });
+    child.stderr?.on("data", (chunk) => {
+        process.stderr.write(chunk); // lint-ok-emission: harn session forwards child stderr verbatim; this IS the command's primary purpose
+        for (const line of stripCRNoise(chunk.toString("utf8")).split("\n")) {
+            if (line.length === 0)
+                continue;
+            writeSessionEvent("output", agent, {
+                instance_id: instanceId,
+                cmd_id: cmdId,
+                stream: "stderr",
+                line: clampField(line),
+            });
+        }
+    });
+    child.on("error", (err) => {
+        process.stderr.write(`✗ spawn failed: ${err.message}\n`);
+        process.exit(127);
+    });
+    child.on("close", (code, signal) => {
+        const durationMs = Date.now() - start;
+        writeSessionEvent("command_end", agent, {
+            instance_id: instanceId,
+            cmd_id: cmdId,
+            exit: code ?? null,
+            signal: signal ?? null,
+            duration_ms: durationMs,
+        });
+        process.exit(code ?? 1);
+    });
+}
+/** Shell-safe quote an argument for human-readable logging (not for eval). */
+function quoteArg(arg) {
+    if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(arg))
+        return arg;
+    return `'${arg.replace(/'/g, `'\\''`)}'`;
+}

package/dist/commands/sync.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `harn sync`: keep a curated subset of `.harnery/` live across machines
+ * via rclone (typically a Google Drive remote, but any rclone remote works).
+ *
+ * Scope: a deliberately small set of file types: durable identities,
+ * archived scratchpads, council manifests. The high-churn machine-local
+ * stuff (events.ndjson, .pid-map/, active/, .last-intent.*) stays put.
+ *
+ * Subcommands:
+ *   init:    interactive: `rclone config` walks through Google OAuth, then
+ *            we record the chosen remote name in ~/.config/harnery/sync.json
+ *   status:  diff local vs remote (rclone check --one-way)
+ *   push:    local to remote (rclone copy)
+ *   pull:    remote to local (rclone copy)
+ *   list:    show what's in the remote
+ *
+ * Power users override via env (HARNERY_SYNC_REMOTE, HARNERY_SYNC_PREFIX) or by
+ * editing the config file. Like `harn backup`, this surfaces rclone rather
+ * than abstracting it.
+ */
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.js";
+export declare function registerSyncCommand(program: Command, emit: EmitContext): void;
+//# sourceMappingURL=sync.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAgHnD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAuK7E"}