harnery 0.35.0 → 0.36.0

package/dist/commands/ledger-v3.js

@@ -1,8 +1,10 @@
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { inventoryLegacyV1Segments, streamLegacyV1Rows, verifyLegacyV1HardFence, writeLegacyV1Canary, } from "../core/events/legacy-storage/index.js";
 import { initializeEventLedgerV3, readEventV3ControlState, recoverInvalidEventLedgerV3, sha256V3, } from "../core/events/v3/index.js";
+import { authorizeEventV3SupportReplacement, inventoryEventV3Support, planEventV3SupportReplacement, planEventV3SupportTransaction, readEventV3SupportPackManifest, readEventV3SupportTransaction, streamEventV3SupportPackRecords, unpackEventV3SupportPack, verifyEventV3SupportTransactionShadow, writeEventV3SupportTransactionShadow, } from "../core/events/v3/support-storage/index.js";
 /** Inspect or initialize the universal V3 event ledger. */
 export function registerLedgerV3Command(program, emit, context) {
     const command = program
@@ -64,6 +66,258 @@ export function registerLedgerV3Command(program, emit, context) {
             emitFailure(emit, "ledger_v3_recovery_failed", error);
         }
     });
+    command
+        .command("verify-support")
+        .description("Validate one V3 support-pack manifest and every packed source digest")
+        .argument("<manifest>", "Support-pack manifest path")
+        .action(async (manifest) => {
+        try {
+            const path = resolve(manifest);
+            const supportManifest = await readEventV3SupportPackManifest(path);
+            let entries = 0;
+            for await (const _record of streamEventV3SupportPackRecords(path))
+                entries += 1;
+            emit.data({
+                valid: true,
+                pack_id: supportManifest.pack_id,
+                entries,
+                source_files_digest: supportManifest.authority.source_files_digest,
+            });
+        }
+        catch (error) {
+            emitFailure(emit, "ledger_v3_support_verify_failed", error);
+        }
+    });
+    command
+        .command("unpack-support")
+        .description("Unpack one verified support pack into a new explicit destination")
+        .argument("<manifest>", "Support-pack manifest path")
+        .requiredOption("--out <directory>", "New destination; existing paths are refused")
+        .action(async (manifest, options) => {
+        try {
+            emit.data(await unpackEventV3SupportPack(resolve(manifest), resolve(options.out)));
+        }
+        catch (error) {
+            emitFailure(emit, "ledger_v3_support_unpack_failed", error);
+        }
+    });
+    command
+        .command("support-transaction-status")
+        .description("Read one exact V3 support maintenance transaction")
+        .requiredOption("--transaction <id>", "Exact support maintenance transaction")
+        .option("--root <path>", "Explicit coordination root")
+        .action(async (options) => {
+        try {
+            const root = resolve(options.root ?? coordRoot(context));
+            emit.data(await readEventV3SupportTransaction(transactionRoot(root), options.transaction));
+        }
+        catch (error) {
+            emitFailure(emit, "ledger_v3_support_transaction_status_failed", error);
+        }
+    });
+    command
+        .command("support-plan")
+        .description("Inventory explicit V3 support evidence and persist a shadow-only transaction")
+        .requiredOption("--authority-root <directory>", "Exact active or archived authority root")
+        .requiredOption("--authority-state <state>", "Authority state: active or archived")
+        .requiredOption("--root-id <id>", "Authority root identifier")
+        .requiredOption("--genesis-id <id>", "Authority genesis binding")
+        .requiredOption("--evidence <json>", "JSON evidence map keyed by every support relative path")
+        .requiredOption("--observed-at <timestamp>", "Explicit ISO-8601 inventory time")
+        .requiredOption("--catalog-version <version>", "Storage catalog version used for the plan")
+        .requiredOption("--policy-version <version>", "Support classification policy version")
+        .option("--source-authority-digest <digest>", "Required archived authority digest")
+        .option("--root <path>", "Explicit coordination root for transaction persistence")
+        .action(async (options) => {
+        try {
+            const state = supportAuthorityState(options.authorityState);
+            const observedAt = exactIsoTimestamp(options.observedAt);
+            const evidence = readSupportEvidence(resolve(options.evidence));
+            const entries = await inventoryEventV3Support({
+                authority_root: resolve(options.authorityRoot),
+                authority: {
+                    state,
+                    genesis_id: nonemptyOption(options.genesisId, "genesis-id"),
+                },
+                now: observedAt,
+                evidence,
+            });
+            if (!sameSortedStrings(Object.keys(evidence), entries.map((entry) => entry.relative_path))) {
+                throw new Error("event_v3_support_plan_evidence_paths_mismatch");
+            }
+            if (entries.some((entry) => entry.disposition !== "pack-eligible")) {
+                throw new Error("event_v3_support_transaction_contains_ineligible_source");
+            }
+            const rootId = nonemptyOption(options.rootId, "root-id");
+            const genesisId = nonemptyOption(options.genesisId, "genesis-id");
+            const catalogVersion = nonemptyOption(options.catalogVersion, "catalog-version");
+            const policyVersion = nonemptyOption(options.policyVersion, "policy-version");
+            const authorityDigest = options.sourceAuthorityDigest
+                ? exactSha256(options.sourceAuthorityDigest)
+                : undefined;
+            if (state === "archived" && !authorityDigest) {
+                throw new Error("event_v3_support_transaction_archive_digest_required");
+            }
+            if (state === "active" && authorityDigest) {
+                throw new Error("event_v3_support_transaction_active_digest_forbidden");
+            }
+            const root = resolve(options.root ?? coordRoot(context));
+            const transactions = transactionRoot(root);
+            mkdirSync(transactions, { recursive: true, mode: 0o700 });
+            emit.data(await planEventV3SupportTransaction({
+                transaction_root: transactions,
+                authority_root: resolve(options.authorityRoot),
+                root_id: rootId,
+                genesis_id: genesisId,
+                authority_state: state,
+                ...(authorityDigest ? { source_authority_digest: authorityDigest } : {}),
+                entries,
+                catalog_version: catalogVersion,
+                policy_version: policyVersion,
+                now: observedAt,
+            }));
+        }
+        catch (error) {
+            emitFailure(emit, "ledger_v3_support_plan_failed", error);
+        }
+    });
+    command
+        .command("support-shadow")
+        .description("Write and verify a shadow pack while preserving every loose source")
+        .requiredOption("--transaction <id>", "Exact support maintenance transaction")
+        .requiredOption("--genesis-id <id>", "Current authority genesis binding")
+        .requiredOption("--minimum-harnery-version <version>", "Minimum pack-aware Harnery version")
+        .option("--root <path>", "Explicit coordination root")
+        .action(async (options) => {
+        try {
+            const root = resolve(options.root ?? coordRoot(context));
+            const transactions = transactionRoot(root);
+            let current = await readEventV3SupportTransaction(transactions, options.transaction);
+            if (current.authority.genesis_id !== options.genesisId) {
+                throw new Error("event_v3_support_transaction_genesis_mismatch");
+            }
+            if (current.state === "planned") {
+                current = await writeEventV3SupportTransactionShadow({
+                    transaction_root: transactions,
+                    transaction_id: current.transaction_id,
+                    minimum_harnery_version: options.minimumHarneryVersion,
+                    now: new Date().toISOString(),
+                });
+            }
+            if (current.state === "shadow-written") {
+                current = await verifyEventV3SupportTransactionShadow({
+                    transaction_root: transactions,
+                    transaction_id: current.transaction_id,
+                    expected_current_genesis_id: options.genesisId,
+                    now: new Date().toISOString(),
+                });
+            }
+            if (current.state !== "shadow-verified") {
+                throw new Error(`support shadow cannot resume from ${current.state}`);
+            }
+            emit.data({
+                transaction_id: current.transaction_id,
+                state: current.state,
+                sources_preserved: true,
+                replacement_enabled: false,
+            });
+        }
+        catch (error) {
+            emitFailure(emit, "ledger_v3_support_shadow_failed", error);
+        }
+    });
+    command
+        .command("support-replacement")
+        .description("Authorize an exact verified canary plan; source replacement remains disabled")
+        .requiredOption("--transaction <id>", "Transaction to inspect")
+        .requiredOption("--exact-transaction <id>", "Repeat the exact transaction identifier")
+        .option("--yes", "Record exact replacement authorization")
+        .option("--root <path>", "Explicit coordination root")
+        .action(async (options) => {
+        try {
+            const root = resolve(options.root ?? coordRoot(context));
+            const transactions = transactionRoot(root);
+            const authorized = await authorizeEventV3SupportReplacement({
+                transaction_root: transactions,
+                transaction_id: options.transaction,
+                exact_transaction_id: options.exactTransaction,
+                yes: options.yes === true,
+                now: new Date().toISOString(),
+            });
+            emit.data(await planEventV3SupportReplacement({
+                transaction_root: transactions,
+                transaction_id: authorized.transaction_id,
+            }));
+        }
+        catch (error) {
+            emitFailure(emit, "ledger_v3_support_replacement_failed", error);
+        }
+    });
+    command
+        .command("verify-v1-fence")
+        .description("Verify the sealed legacy V1 hard fence and terminal digest")
+        .option("--root <path>", "Explicit coordination root")
+        .action(async (options) => {
+        try {
+            emit.data(await verifyLegacyV1HardFence(resolve(options.root ?? coordRoot(context))));
+        }
+        catch (error) {
+            emitFailure(emit, "ledger_v1_fence_verify_failed", error);
+        }
+    });
+    command
+        .command("legacy-inventory")
+        .description("List sealed root events*.ndjson* history after the V1 fence passes")
+        .option("--root <path>", "Explicit coordination root")
+        .action(async (options) => {
+        try {
+            const root = resolve(options.root ?? coordRoot(context));
+            await verifyLegacyV1HardFence(root);
+            emit.data(await inventoryLegacyV1Segments(root));
+        }
+        catch (error) {
+            emitFailure(emit, "ledger_v1_inventory_failed", error);
+        }
+    });
+    command
+        .command("verify-legacy")
+        .description("Stream and validate one loose or manifest-bound gzip legacy segment")
+        .argument("<source>", "Loose segment or compressed-segment manifest")
+        .action(async (source) => {
+        try {
+            let rows = 0;
+            for await (const row of streamLegacyV1Rows(resolve(source)))
+                rows = row.row_number;
+            emit.data({ valid: true, rows });
+        }
+        catch (error) {
+            emitFailure(emit, "ledger_v1_segment_verify_failed", error);
+        }
+    });
+    command
+        .command("legacy-canary")
+        .description("Write one shadow gzip canary while retaining the sealed loose segment")
+        .requiredOption("--source-filename <name>", "Root legacy segment filename")
+        .requiredOption("--out <directory>", "Shadow output directory")
+        .requiredOption("--minimum-harnery-version <version>", "Minimum canary-aware version")
+        .option("--shadow", "Confirm shadow-only compression")
+        .option("--root <path>", "Explicit coordination root")
+        .action(async (options) => {
+        try {
+            if (!options.shadow)
+                throw new Error("--shadow is required for legacy canary creation");
+            emit.data(await writeLegacyV1Canary({
+                coord_root: resolve(options.root ?? coordRoot(context)),
+                source_filename: options.sourceFilename,
+                output_directory: resolve(options.out),
+                minimum_harnery_version: options.minimumHarneryVersion,
+                created_at: new Date().toISOString(),
+            }));
+        }
+        catch (error) {
+            emitFailure(emit, "ledger_v1_canary_failed", error);
+        }
+    });
 }
 function coordRoot(context) {
     return resolve(context?.resolveCoordRoot?.() ??
@@ -85,6 +339,98 @@ function configDigest(root) {
     const path = resolve(root, ".harnery", "config.jsonc");
     return sha256V3(existsSync(path) ? readFileSync(path) : Buffer.from("{}\n"));
 }
+function transactionRoot(root) {
+    return resolve(root, ".harnery", "maintenance", "transactions", "v3-support");
+}
+function supportAuthorityState(value) {
+    if (value === "active" || value === "archived")
+        return value;
+    throw new Error("event_v3_support_plan_authority_state_invalid");
+}
+function exactIsoTimestamp(value) {
+    if (!Number.isFinite(Date.parse(value)) || new Date(value).toISOString() !== value) {
+        throw new Error("event_v3_support_plan_timestamp_invalid");
+    }
+    return value;
+}
+function exactSha256(value) {
+    if (!/^sha256:[0-9a-f]{64}$/.test(value)) {
+        throw new Error("event_v3_support_plan_authority_digest_invalid");
+    }
+    return value;
+}
+function nonemptyOption(value, name) {
+    if (value.trim().length === 0)
+        throw new Error(`event_v3_support_plan_${name}_empty`);
+    return value;
+}
+function readSupportEvidence(path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new Error("event_v3_support_plan_evidence_invalid");
+    }
+    if (!isRecord(parsed))
+        throw new Error("event_v3_support_plan_evidence_invalid");
+    for (const evidence of Object.values(parsed)) {
+        if (!isRecord(evidence) || !validSupportEvidence(evidence)) {
+            throw new Error("event_v3_support_plan_evidence_invalid");
+        }
+    }
+    return parsed;
+}
+const supportEvidenceBooleanFields = new Set([
+    "recovery_bound",
+    "recovery_packing_enabled",
+    "epoch_maintenance_enabled",
+    "active_session_tee_enabled",
+    "active_committed_receipt_enabled",
+    "contract_valid",
+    "maintenance_owned",
+    "terminal",
+    "pending",
+    "turn_sealed",
+    "finalization_complete",
+    "event_references_resolved",
+    "event_references_same_epoch",
+    "lease_live",
+    "stale_writer_grace_elapsed",
+    "ready_sibling",
+    "producer_pending_reference",
+    "event_row_digest_matches",
+    "transaction_digest_matches",
+    "receipt_grace_elapsed",
+    "archive_has_ready_transaction",
+]);
+const supportEvidenceStringFields = new Set(["recorded_at", "filename_recorded_at"]);
+const supportEvidenceNumberFields = new Set([
+    "maximum_loose_consumer_window_ms",
+    "fixed_consumer_grace_ms",
+    "writer_tolerance_ms",
+]);
+function validSupportEvidence(evidence) {
+    return Object.entries(evidence).every(([key, value]) => {
+        if (supportEvidenceBooleanFields.has(key))
+            return typeof value === "boolean";
+        if (supportEvidenceStringFields.has(key))
+            return typeof value === "string";
+        if (supportEvidenceNumberFields.has(key)) {
+            return typeof value === "number" && Number.isFinite(value) && value >= 0;
+        }
+        return false;
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function sameSortedStrings(left, right) {
+    const leftSorted = [...left].sort();
+    const rightSorted = [...right].sort();
+    return (leftSorted.length === rightSorted.length &&
+        leftSorted.every((value, index) => value === rightSorted[index]));
+}
 function emitFailure(emit, code, error) {
     emit.error({ code, message: error instanceof Error ? error.message : String(error) });
     throw error;

package/dist/commands/logs.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.js";
+export declare function registerLogsCommand(program: Command, emit: EmitContext, context?: HarneryProgramContext): void;
+//# sourceMappingURL=logs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logs.d.ts","sourceRoot":"","sources":["../../src/commands/logs.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAuB1E,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAqFN"}

package/dist/commands/logs.js

@@ -0,0 +1,169 @@
+import { resolve } from "node:path";
+import { resolveCoordRoot as resolveCanonicalCoordRoot } from "../core/agents/coord-client.js";
+import { createStorageCatalog } from "../core/storage/catalog.js";
+import { HARNERY_STRUCTURED_LOG_PROVIDER_ID, } from "../core/storage/contract.js";
+import { inspectStructuredLogRetention } from "../core/storage/log-retention.js";
+import { queryLogs, rotationFollowCursor } from "../core/storage/query.js";
+import { familyLogDirectory } from "../core/storage/segments.js";
+export function registerLogsCommand(program, emit, context) {
+    const logs = program.command("logs").description("List and query bounded Harnery log families");
+    logs
+        .command("list")
+        .option("--json", "Emit structured output")
+        .action((options) => run(emit, async () => {
+        const catalog = catalogFor(context);
+        const capturedAt = new Date();
+        const rows = logFamilies(catalog.families).map((family) => logFamilyRow(family, capturedAt));
+        if (options.json) {
+            emit.config({ format: "json" });
+            emit.data({
+                schema: "harnery.logs-list/v2",
+                captured_at: capturedAt.toISOString(),
+                diagnostics: catalog.log_storage_diagnostics,
+                dormant_families: catalog.dormant_log_storage_families,
+                families: rows,
+            });
+        }
+        else
+            emit.rows(rows.map(logFamilyTableRow));
+    }));
+    const configureQuery = (command) => command
+        .option("--family <id...>", "Restrict to named families")
+        .option("--level <level>", "Minimum severity")
+        .option("--event <event>", "Exact event name")
+        .option("--since <timestamp>", "Earliest timestamp")
+        .option("--until <timestamp>", "Latest timestamp")
+        .option("--max-records <n>", "Global record scan budget", integer, 10_000)
+        .option("--max-bytes <n>", "Global byte scan budget", integer, 10 * 1024 * 1024)
+        .option("--json", "Emit structured output");
+    configureQuery(logs.command("query").description("Query sealed and active log segments")).action((options) => run(emit, async () => {
+        const result = await queryLogs(logFamilies(catalogFor(context).families), queryFrom(options));
+        if (options.json) {
+            emit.config({ format: "json" });
+            emit.data({ schema: "harnery.logs-query/v1", ...result });
+        }
+        else
+            emit.rows(result.records);
+    }));
+    configureQuery(logs.command("export").description("Export matching records as JSONL")).action((options) => run(emit, async () => {
+        const result = await queryLogs(logFamilies(catalogFor(context).families), queryFrom(options));
+        for (const record of result.records)
+            emit.text(JSON.stringify(record));
+        if (result.truncated)
+            emit.log("log export stopped at the configured global scan budget", "warn");
+    }));
+    logs
+        .command("tail")
+        .argument("<family>")
+        .description("Read recent records and a rotation-aware follow cursor")
+        .option("-n, --lines <n>", "Number of recent records", integer, 50)
+        .option("--max-bytes <n>", "Global byte scan budget", integer, 10 * 1024 * 1024)
+        .action((familyId, options) => run(emit, async () => {
+        const family = catalogFor(context).require(familyId);
+        if (!isLogFamily(family))
+            throw new Error(`storage family is not a log: ${familyId}`);
+        const result = await queryLogs([family], {
+            max_records: 10_000,
+            max_bytes: options.maxBytes,
+        });
+        emit.data({
+            schema: "harnery.logs-tail-cursor/v1",
+            records: result.records.slice(-options.lines),
+            truncated: result.truncated,
+            cursor: rotationFollowCursor(family),
+        });
+    }));
+}
+function logFamilyRow(family, now) {
+    const inspection = inspectStructuredLogRetention(family, now);
+    const effective = family.effective_log_retention;
+    return {
+        family_id: family.id,
+        class: family.storage_class,
+        directory: structuredLogDirectory(family),
+        registered_roots: family.resolved_roots,
+        policy_version: family.policy.policy_version,
+        effective_policy: effective
+            ? {
+                state: effective.state,
+                max_bytes: effective.max_bytes,
+                max_age_days: effective.max_age_days,
+                max_age_ms: effective.max_age_ms,
+                fingerprint: effective.effective_policy_fingerprint,
+                provenance: effective.provenance,
+                diagnostics: effective.diagnostics,
+            }
+            : null,
+        usage: inspection.usage,
+        pressure: inspection.pressure,
+        retention: inspection.retention,
+        sealed_segments: inspection.sealed_segments.length,
+        obsolete_manifest_snapshots: inspection.obsolete_snapshots.length,
+    };
+}
+function structuredLogDirectory(family) {
+    if (family.provider.provider_id !== HARNERY_STRUCTURED_LOG_PROVIDER_ID ||
+        family.format !== "jsonl") {
+        return null;
+    }
+    const root = family.resolved_roots.find((candidate) => candidate.match === "provider-partition" && candidate.ownership !== "external");
+    return root?.partition ? familyLogDirectory(family) : null;
+}
+function logFamilyTableRow(row) {
+    return {
+        family_id: row.family_id,
+        class: row.class,
+        max_bytes: row.effective_policy?.max_bytes ?? "unavailable",
+        max_age_days: row.effective_policy?.max_age_days ?? "unavailable",
+        managed_bytes: row.usage.managed_bytes,
+        unmanaged_bytes: row.usage.unmanaged_bytes,
+        pressure: row.pressure.state,
+        pressure_ratio: row.pressure.ratio === null ? "unavailable" : Number(row.pressure.ratio.toFixed(3)),
+        retention: row.retention.state,
+        enforcement: row.retention.enforcement,
+        reasons: row.retention.reason_codes.join(",") || "none",
+    };
+}
+function catalogFor(context) {
+    const coordRoot = resolve(context?.resolveCoordRoot?.() ??
+        context?.repoRoot ??
+        process.env.HARNERY_COORD_ROOT ??
+        resolveCanonicalCoordRoot() ??
+        process.cwd());
+    return createStorageCatalog({ coord_root: coordRoot, project_root: resolve(context?.repoRoot ?? coordRoot) }, context?.storage);
+}
+function logFamilies(families) {
+    return families.filter(isLogFamily);
+}
+function isLogFamily(family) {
+    return family.storage_class === "operational-log" || family.storage_class === "debug-log";
+}
+function integer(value) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0)
+        throw new Error(`invalid positive integer: ${value}`);
+    return parsed;
+}
+function queryFrom(options) {
+    return {
+        ...(options.family ? { family_ids: options.family } : {}),
+        ...(options.level ? { minimum_level: options.level } : {}),
+        ...(options.event ? { event: options.event } : {}),
+        ...(options.since ? { since: options.since } : {}),
+        ...(options.until ? { until: options.until } : {}),
+        max_records: options.maxRecords,
+        max_bytes: options.maxBytes,
+    };
+}
+async function run(emit, action) {
+    try {
+        await action();
+    }
+    catch (error) {
+        emit.error({
+            code: "logs_query_failed",
+            message: error instanceof Error ? error.message : String(error),
+        });
+        emit.setExitCode(1);
+    }
+}

package/dist/commands/messages.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.js";
+import type { HarneryInboxService } from "../core/inbox/service.js";
+export declare function registerMessagesCommand(program: Command, emit: EmitContext, service?: HarneryInboxService): void;
+//# sourceMappingURL=messages.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/commands/messages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,IAAI,CA+CN"}

package/dist/commands/messages.js

@@ -0,0 +1,45 @@
+export function registerMessagesCommand(program, emit, service) {
+    program
+        .command("messages")
+        .description("Queue a durable coordination message; dry-run unless --yes")
+        .requiredOption("--from <instance>")
+        .requiredOption("--from-name <name>")
+        .requiredOption("--to <instance>")
+        .requiredOption("--to-name <name>")
+        .requiredOption("--body <text>")
+        .option("--yes", "Append and sync the message")
+        .option("--json", "Emit stable JSON")
+        .action((options) => {
+        try {
+            const result = options.yes
+                ? requireInboxService(service).send({
+                    sender_instance_id: options.from,
+                    sender_display_name: options.fromName,
+                    recipient_instance_id: options.to,
+                    recipient_display_name: options.toName,
+                    body: options.body,
+                })
+                : {
+                    state: "dry-run",
+                    recipient_instance_id: options.to,
+                    body_bytes: Buffer.byteLength(options.body),
+                    writes: false,
+                };
+            if (options.json)
+                emit.config({ format: "json" });
+            emit.data({ schema: "harnery.message-send/v1", ...result });
+        }
+        catch (error) {
+            emit.error({
+                code: "message_send_failed",
+                message: error instanceof Error ? error.message : String(error),
+            });
+            emit.setExitCode(1);
+        }
+    });
+}
+function requireInboxService(service) {
+    if (!service)
+        throw new Error("coordination inbox is not configured by this host");
+    return service;
+}

package/dist/commands/outline.d.ts

@@ -1,4 +1,4 @@
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.js";
-export declare function registerOutlineCommand(program: Command, emit: EmitContext): void;
+export declare function registerOutlineCommand(program: Command, emit: EmitContext, binName?: string): void;
 //# sourceMappingURL=outline.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"outline.d.ts","sourceRoot":"","sources":["../../src/commands/outline.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAqDnD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAwBhF"}
+{"version":3,"file":"outline.d.ts","sourceRoot":"","sources":["../../src/commands/outline.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAqDnD,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,SAAmB,GACzB,IAAI,CAwBN"}

package/dist/commands/outline.js

@@ -16,10 +16,10 @@ async function loadTypeScript() {
         throw new Error("outlining TS/JS files needs the `typescript` package; install it (npm i -D typescript) or use outline on PHP/Python files");
     }
 }
-export function registerOutlineCommand(program, emit) {
+export function registerOutlineCommand(program, emit, binName = resolveBinName()) {
     program
         .command("outline <file>")
-        .description(`Print the structural skeleton of a code file (imports + top-level decls + line numbers). Supports TS/JS/TSX/JSX (AST), PHP/Python (regex). Use \`${resolveBinName()} toc\` for markdown.`)
+        .description(`Print the structural skeleton of a code file (imports + top-level decls + line numbers). Supports TS/JS/TSX/JSX (AST), PHP/Python (regex). Use \`${binName} toc\` for markdown.`)
         .option("--json", "Structured JSON envelope")
         .option("--exports-only", "Only show exported symbols")
         .option("--no-imports", "Skip the imports summary block")

package/dist/commands/read.d.ts

@@ -3,5 +3,5 @@ import type { EmitContext } from "../commander.js";
 /**
  * `harn read`: extract clean readable markdown from HTML.
  */
-export declare function registerReadCommand(program: Command, emitParam: EmitContext): void;
+export declare function registerReadCommand(program: Command, emitParam: EmitContext, binName?: string): void;
 //# sourceMappingURL=read.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/commands/read.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAQnD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,GAAG,IAAI,CAwBlF"}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/commands/read.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAQnD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,WAAW,EACtB,OAAO,SAAmB,GACzB,IAAI,CAwBN"}

package/dist/commands/read.js

@@ -7,11 +7,11 @@ let emit;
 /**
  * `harn read`: extract clean readable markdown from HTML.
  */
-export function registerReadCommand(program, emitParam) {
+export function registerReadCommand(program, emitParam, binName = resolveBinName()) {
     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.`)
+        .description(`Extract clean readable markdown from HTML. Reads from file or stdin (use '-'). Pair with \`${binName} fetch\` or \`${binName} 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)")

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

@@ -1 +1 @@
-{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../src/commands/semantic.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAc1E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CAiIN"}
+{"version":3,"file":"semantic.d.ts","sourceRoot":"","sources":["../../src/commands/semantic.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAiB1E,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,WAAW,EACjB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,IAAI,CA8LN"}