@astrosheep/keiyaku 4.5.7 → 4.5.9

package/build/src/cli/render/region.js

@@ -1,9 +1,12 @@
 function overlapBlocks(overlaps) {
     return overlaps.flatMap((overlap) => {
-        const count = overlap.patterns.length;
+        const patterns = overlap.patterns.filter((pattern) => pattern.mine !== pattern.theirs);
+        if (patterns.length === 0)
+            return [`overlap ${overlap.contract} exact match`];
+        const count = patterns.length;
         return [
             `overlap ${overlap.contract} ${count} ${count === 1 ? "pair" : "pairs"}`,
-            ...overlap.patterns.map((pattern) => `  ${pattern.mine} ~ ${pattern.theirs}`),
+            ...patterns.map((pattern) => `  ${pattern.mine} ~ ${pattern.theirs}`),
         ];
     });
 }

package/build/src/cli/render/settings.d.ts

@@ -1,3 +1,3 @@
 import type { Settings } from "../../settings.js";
 export declare function settingsJsonValue(value: Settings): unknown;
-export declare function renderSettingsText(value: Settings): string;
+export declare function renderSettingsText(value: Settings, columns?: number): string;

package/build/src/cli/render/settings.js

@@ -1,11 +1,19 @@
+import { displayColumns, renderTextBlock } from "./terminal.js";
 function namespaceNames(value) {
     return [
         ...new Set([value.scopes.user, value.scopes.project].flatMap((scope) => (scope.kind === "read" ? scope.namespaces : []))),
     ].sort();
 }
-function scope(name, value) {
-    const path = value.path === undefined ? "" : ` ${value.path}`;
-    return value.kind === "failed" ? `${name} failed${path} ${value.diagnostic}` : `${name} ${value.kind}${path}`;
+function jsonLines(value, indent) {
+    return JSON.stringify(value, null, 2)
+        .split("\n")
+        .map((line) => `${indent}${line}`);
+}
+function labeledTokens(label, tokens, indent, columns) {
+    const inline = [label, ...tokens].filter((part) => part.length > 0).join(" ");
+    if (displayColumns(`${indent}${inline}`) <= columns)
+        return [`${indent}${inline}`];
+    return [...renderTextBlock(label, indent, columns), ...tokens.map((token) => `${indent}  ${token}`)];
 }
 export function settingsJsonValue(value) {
     return {
@@ -13,18 +21,29 @@ export function settingsJsonValue(value) {
         namespaces: namespaceNames(value).map((name) => value.namespace(name)),
     };
 }
-export function renderSettingsText(value) {
-    const lines = [scope("user", value.scopes.user), scope("project", value.scopes.project)];
+export function renderSettingsText(value, columns = 80) {
+    const lines = [
+        "settings",
+        ...scopeLines("user", value.scopes.user, columns),
+        ...scopeLines("project", value.scopes.project, columns),
+    ];
     for (const name of namespaceNames(value)) {
         const view = value.namespace(name);
-        lines.push(`namespace ${name} ${view.kind}`);
+        lines.push(...renderTextBlock(`namespace ${name} ${view.kind}`, "  ", columns));
         if (view.kind === "failed") {
             for (const failure of view.failures)
-                lines.push(`failure ${failure.scope} ${failure.diagnostic}`);
+                lines.push(...renderTextBlock(`failure ${failure.scope} ${failure.diagnostic}`, "    ", columns));
         }
         for (const entry of view.entries) {
-            lines.push(`entry ${entry.name} ${entry.source}${entry.shadows ? " shadows user" : ""} ${JSON.stringify(entry.value)}`);
+            lines.push(...renderTextBlock(`entry ${entry.name} ${entry.source}${entry.shadows ? " shadows user" : ""}`, "    ", columns));
+            lines.push(...jsonLines(entry.value, "      "));
         }
     }
     return lines.join("\n");
 }
+function scopeLines(name, value, columns) {
+    const tokens = value.path === undefined ? [] : [value.path];
+    if (value.kind === "failed")
+        tokens.push(value.diagnostic);
+    return labeledTokens(`${name} ${value.kind}`, tokens, "  ", columns);
+}

package/build/src/cli/render/task.js

@@ -12,10 +12,12 @@ function markFor(word) {
         return "●";
     if (word === "ready" || word === "open")
         return "○";
-    if (word === "blocked" || word === "missing")
+    if (word === "blocked")
+        return "‖";
+    if (word === "missing")
         return "!";
     if (word === "on_hold")
-        return "·";
+        return "⧗";
     if (word === "done")
         return "✓";
     if (word === "drop")
@@ -104,7 +106,7 @@ function compactFacts(item) {
     return [
         `updated ${updatedAge(item.updatedAt)}`,
         ...(item.bodyPresent ? [] : ["no body"]),
-        ...(item.children === undefined ? [] : [`children ${item.children.live}/${item.children.total} live`]),
+        ...(item.children === undefined ? [] : [`children ${item.children.live} live · ${item.children.total} total`]),
     ].join(" · ");
 }
 function listEntity(item, omitDisposition) {
@@ -130,6 +132,8 @@ function shellQuote(value) {
 function recoveryCommand(command, total) {
     const parts = ["keiyaku", "task", command.action];
     if (command.action === "ls") {
+        if (command.positionals.length > 0)
+            parts.push(command.positionals[0]);
         if (command.flags.closed === true)
             parts.push("--closed");
         if (command.flags.all === true)
@@ -158,8 +162,16 @@ function renderRows(command, result, columns) {
             `    ${recoveryCommand(command, result.value.total)}`,
         ]
         : [];
+    const scope = command.action === "ls"
+        ? command.flags.world === true
+            ? "world"
+            : command.positionals.length > 0
+                ? `namespace ${command.positionals[0].replace(/^task\//u, "").replace(/\/$/u, "") || "root"}`
+                : "current namespace"
+        : undefined;
+    const heading = scope === undefined ? pageHeading(view, result.value) : `${pageHeading(view, result.value)} · ${scope}`;
     return [
-        pageHeading(view, result.value),
+        heading,
         ...result.value.rows.flatMap((item) => renderListRow(item, columns, command.action === "ready")),
         ...footer,
     ].join("\n");
@@ -328,7 +340,12 @@ function renderTaskValue(command, result, columns) {
     }
     if (command.action === "compose")
         return renderCompose(result, columns);
-    if (command.action === "hold" || command.action === "done" || command.action === "drop") {
+    if (command.action === "start" ||
+        command.action === "hold" ||
+        command.action === "done" ||
+        command.action === "drop") {
+        if (!(typeof result === "object" && result !== null && "items" in result))
+            return renderMutation(command, result, columns);
         return renderBatch(command.action, result);
     }
     return renderMutation(command, result, columns);

package/build/src/cli/render/terminal.d.ts

@@ -23,6 +23,37 @@ export declare function renderBoundedTextBlock(value: string, input: Readonly<{
     truncated?: boolean;
 }>): readonly string[];
 export declare function safeText(value: string): string;
+type CheckoutNotFollowable = Readonly<{
+    reason: "staged" | "conflict" | "untracked";
+    path: string;
+    target: string;
+    paths: readonly string[];
+}>;
+export declare function checkoutNotFollowableLines(refusal: CheckoutNotFollowable): readonly string[];
 export declare function renderTextBlock(value: string, indent: string, columns: number): readonly string[];
 export declare function renderOpaqueBlock(value: string, indent: string, columns: number): readonly string[];
-export declare function tone(value: string, kind: "dim" | "alert", color: boolean): string;
+export type SemanticTone = "dim" | "recent" | "attention" | "alert";
+export declare const RECENT_TONE_MS: number;
+export declare function elapsedMilliseconds(source: string | null | undefined, observedAt: string): number | null;
+export declare function tone(value: string, kind: SemanticTone, color: boolean): string;
+export declare function boundedActivity(value: string, columns: number, prefix: string): string;
+export declare function plumbFacts(facts: readonly string[], columns: number): readonly string[];
+export declare function identityLine(mark: string, identity: string, extra?: string): string;
+export declare function entityLines(entity: Readonly<{
+    mark: string;
+    identity: string;
+    state: string;
+    title: string;
+    facts: readonly string[];
+    context: TextRenderContext;
+}>): readonly string[];
+export declare function renderSectionBlock({ name, unit, selector, continuation, rows, total, neutral, }: Readonly<{
+    name: string;
+    unit: string;
+    selector: string;
+    continuation?: string;
+    rows: readonly (readonly string[])[];
+    total: number;
+    neutral?: boolean;
+}>): readonly string[];
+export {};

package/build/src/cli/render/terminal.js

@@ -118,6 +118,22 @@ export function renderBoundedTextBlock(value, input) {
 export function safeText(value) {
     return value.replaceAll(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, (character) => (/\s/u.test(character) ? " " : "�"));
 }
+export function checkoutNotFollowableLines(refusal) {
+    const lines = [
+        "! checkout-not-followable",
+        `  checkout: ${safeText(refusal.path)}`,
+        `  target: ${safeText(refusal.target)}`,
+        `  reason: ${refusal.reason}`,
+    ];
+    if (refusal.paths.length === 0) {
+        lines.push("  paths: (none)");
+    }
+    else {
+        lines.push("  paths:");
+        lines.push(...refusal.paths.map((path) => `    - ${JSON.stringify(path)}`));
+    }
+    return lines;
+}
 export function renderTextBlock(value, indent, columns) {
     const words = safeText(value)
         .trim()
@@ -172,8 +188,68 @@ export function renderOpaqueBlock(value, indent, columns) {
     }
     return lines;
 }
+export const RECENT_TONE_MS = 5 * 60 * 1_000;
+export function elapsedMilliseconds(source, observedAt) {
+    if (source === null || source === undefined)
+        return null;
+    const sourceMs = Date.parse(source);
+    const observedMs = Date.parse(observedAt);
+    if (!Number.isFinite(sourceMs) || !Number.isFinite(observedMs))
+        return null;
+    return Math.max(0, observedMs - sourceMs);
+}
 export function tone(value, kind, color) {
     if (!color)
         return value;
-    return kind === "dim" ? `\u001b[2m${value}\u001b[0m` : `\u001b[31m${value}\u001b[0m`;
+    const code = kind === "dim" ? 2 : kind === "recent" ? 32 : kind === "attention" ? 33 : 31;
+    return `\u001b[${code}m${value}\u001b[0m`;
+}
+const KANSHI_NARROW_COLUMNS = 72;
+export function boundedActivity(value, columns, prefix) {
+    const budget = Math.max(1, columns - displayColumns(prefix));
+    return `activity "${truncateDisplayText(value, Math.max(1, budget - displayColumns('activity ""')))}` + `"`;
+}
+export function plumbFacts(facts, columns) {
+    const clean = facts.map(safeText).filter((fact) => fact.length > 0);
+    if (clean.length === 0)
+        return [];
+    const lines = [];
+    let current = "  │ ";
+    for (const fact of clean) {
+        const candidate = current === "  │ " ? `  │ ${fact}` : `${current} · ${fact}`;
+        if (current !== "  │ " && displayColumns(candidate) > columns) {
+            lines.push(current);
+            current = `  │ ${fact}`;
+        }
+        else
+            current = candidate;
+    }
+    lines.push(current);
+    return lines;
+}
+export function identityLine(mark, identity, extra = "") {
+    return extra.length === 0 ? `${mark} ${safeText(identity)}` : `${mark} ${safeText(identity)} ${safeText(extra)}`;
+}
+export function entityLines(entity) {
+    const { mark, identity, state, title, facts, context } = entity;
+    if (context.columns > KANSHI_NARROW_COLUMNS) {
+        return [identityLine(mark, identity, `· ${state} · ${title}`), ...plumbFacts(facts, context.columns)];
+    }
+    return [
+        `${mark} ${safeText(state)}`,
+        `  ${safeText(identity)}`,
+        ...(title.length === 0 ? [] : renderTextBlock(safeText(title), "  ", context.columns)),
+        ...plumbFacts(facts, context.columns),
+    ];
+}
+export function renderSectionBlock({ name, unit, selector, continuation, rows, total, neutral = false, }) {
+    const lines = [`[ ${name} ]  ${total}${neutral ? ` ${unit}` : " live"}`, "", ...rows.flat()];
+    if (lines.at(-1) !== "")
+        lines.push("");
+    lines.push(rows.length === total
+        ? `  (all ${total}${neutral ? "" : " live"} ${unit} shown)`
+        : `  + ${total - rows.length} more${neutral ? "" : " live"} ${unit} not shown`);
+    if (rows.length !== total)
+        lines.push(`    ${continuation ?? `keiyaku ls ${selector}/`}`);
+    return lines;
 }

package/build/src/cli/result.d.ts

@@ -27,14 +27,14 @@ export type AcceptedFact = (AcceptedFactEnvelope & Readonly<{
     }>["data"];
 }>);
 export type Lag = ReconcileReport["lag"][number];
-type MutationEnvelope = Pick<MutationResult<unknown>, "head" | "effects" | "settlement">;
+type MutationEnvelope = Pick<MutationResult<unknown>, "head" | "settlementLags" | "recoverySnapshot">;
 export type AcceptedEnvelope = Readonly<{
     kind: "accepted";
     contract: ContractId;
     head: MutationEnvelope["head"];
     facts: readonly AcceptedFact[];
-    effects: MutationEnvelope["effects"];
-    settlement: MutationEnvelope["settlement"];
+    settlementLags: MutationEnvelope["settlementLags"];
+    recoverySnapshot?: MutationEnvelope["recoverySnapshot"];
     lag?: readonly [Lag, ...Lag[]];
 }>;
 export type AcceptedBindResult = AcceptedEnvelope & Readonly<{

package/build/src/cli/runtime.js

@@ -11,7 +11,7 @@ export function invocationStart(command) {
         return "⧖ auditing";
     if (command.command === "reconcile")
         return "⧖ reconciling";
-    return command.command === "install" ? "⧖ installing skills" : undefined;
+    return command.command === "install" ? "⧖ installing harness integrations" : undefined;
 }
 function writeCliStream(stream, body) {
     stream.write(body.endsWith("\n") ? body : `${body}\n`);
@@ -106,7 +106,9 @@ async function writeResult(command, result) {
     if (command.command === "settings") {
         const { renderSettingsText, settingsJsonValue } = await import("./render/settings.js");
         const value = result.value;
-        writeCliStream(process.stdout, command.output === "json" ? JSON.stringify(settingsJsonValue(value)) : renderSettingsText(value));
+        writeCliStream(process.stdout, command.output === "json"
+            ? JSON.stringify(settingsJsonValue(value))
+            : renderSettingsText(value, displayContext().columns));
         return 0;
     }
     if (isAkumaOutput(command, result))

package/build/src/cli/selectors.d.ts

@@ -1,10 +1,11 @@
 import { Keiyaku, type ContractBoard, type ContractId, type Repo } from "../index.js";
+import { type ExecutionContext } from "../akuma/requests.js";
 import type { KanshiReport } from "../kanshi/index.js";
 export type SelectedContract = Readonly<{
     id: ContractId;
     contract: Keiyaku;
 }>;
-export declare function contractFromInput(repo: Repo, value: string): SelectedContract;
+export declare function contractFromInput(repo: Repo, value: string, execution?: ExecutionContext): SelectedContract;
 export declare function resolveContextualContract(board: ContractBoard, selector: string | undefined, scope: string): ContractId;
 export declare function canonicalContractSelector(selector: string): ContractId;
 export declare function resolveKanshiContract(report: KanshiReport, selector: string): string;

package/build/src/cli/selectors.js

@@ -1,6 +1,7 @@
 import { resolve } from "node:path";
 import { identitySegments } from "../identity/coordinates.js";
-import { Keiyaku } from "../index.js";
+import { keiyakuOf } from "../library/contract.js";
+import { localExecutionContext } from "../akuma/requests.js";
 import { CliUsageError } from "./parse.js";
 function selectorError(message) {
     throw new CliUsageError(message);
@@ -12,10 +13,10 @@ function activeManagedCandidates(rows) {
         return [{ id: contract.id, worktreePath: contract.worktreePath }];
     });
 }
-export function contractFromInput(repo, value) {
+export function contractFromInput(repo, value, execution = localExecutionContext()) {
     try {
         const id = value;
-        return { id, contract: Keiyaku.of({ repo, id }) };
+        return { id, contract: keiyakuOf({ repo, id }, execution) };
     }
     catch (error) {
         selectorError(error instanceof Error ? error.message : String(error));

package/build/src/cli/square-edge.js

@@ -1,18 +1,20 @@
-import { bindCurrentParticipant, Square, squareAssignedParticipantName, unbindCurrentParticipant, } from "@astrosheep/square";
+import { bindCurrentParticipant, createHostLedgerPort, Square, squareAssignedParticipantName, } from "@astrosheep/square";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
 import { keiyakuSquarePath } from "../world.js";
-async function openKeiyakuSquare(path) {
+async function openKeiyakuSquare(path, environment, hostLedger) {
     try {
-        return await Square.at({ path });
+        return await Square.at({ path, env: environment, hostLedger });
     }
     catch (error) {
         if (error.code !== "ENOENT" && error.code !== "unavailable")
             throw error;
         try {
-            return await Square.build({ path, markdown: "" });
+            return await Square.build({ path, markdown: "", env: environment, hostLedger });
         }
         catch (buildError) {
             try {
-                return await Square.at({ path });
+                return await Square.at({ path, env: environment, hostLedger });
             }
             catch {
                 throw buildError;
@@ -20,56 +22,138 @@ async function openKeiyakuSquare(path) {
         }
     }
 }
+function squareInvocationEnvironment(environment, path) {
+    const ledgerRoot = environment.SQUARE_REGISTRY === undefined ? undefined : dirname(environment.SQUARE_REGISTRY);
+    return {
+        ...environment,
+        SQUARE_HOST_LEDGER_USER: environment.SQUARE_HOST_LEDGER_USER ?? ledgerRoot ?? join(homedir(), ".square", "host-ledger"),
+        SQUARE_HOST_LEDGER_LOCAL: environment.SQUARE_HOST_LEDGER_LOCAL ??
+            ledgerRoot ??
+            join(environment.PWD ?? dirname(path), ".square", "host-ledger"),
+    };
+}
+function invocationHostLedger(environment) {
+    return createHostLedgerPort({
+        userPath: environment.SQUARE_HOST_LEDGER_USER,
+        localPath: environment.SQUARE_HOST_LEDGER_LOCAL,
+    });
+}
+async function participantBindings(hostLedger, path, name) {
+    return await hostLedger.listPresence({ location: path, participant: name });
+}
+function presenceKey({ location, participant, session, channel }) {
+    return JSON.stringify([location, participant, session, channel]);
+}
+function exactPresenceKey({ location, participant, session, channel }) {
+    return { location, participant, session, channel };
+}
+async function bestEffort(operation) {
+    try {
+        await operation();
+    }
+    catch { }
+}
+async function rollbackSquareEdge(input) {
+    const { path, environment, hostLedger, name, allocated, joined, listening, createdBindings } = input;
+    if (listening || joined) {
+        let square;
+        await bestEffort(async () => {
+            square = await Square.at({ path, env: environment, hostLedger });
+        });
+        let participant;
+        if (square !== undefined)
+            await bestEffort(async () => {
+                participant = await square.join(name);
+            });
+        if (participant !== undefined && listening)
+            await bestEffort(async () => participant.ignore(allocated.id));
+        if (participant !== undefined && joined)
+            await bestEffort(async () => participant.done());
+        if (square !== undefined)
+            await bestEffort(async () => square.close());
+    }
+    for (const binding of createdBindings)
+        await bestEffort(async () => hostLedger.removePresence(binding));
+}
 export async function recognizeAndListen(worldRoot, environment, allocated) {
-    const name = squareAssignedParticipantName(environment);
-    if (name === undefined)
-        return;
     const path = keiyakuSquarePath(worldRoot);
-    const square = await openKeiyakuSquare(path);
+    const squareEnvironment = squareInvocationEnvironment(environment, path);
+    let name;
+    try {
+        const assigned = squareAssignedParticipantName(squareEnvironment);
+        if (assigned === undefined)
+            return;
+        name = assigned;
+    }
+    catch {
+        return;
+    }
+    const hostLedger = invocationHostLedger(squareEnvironment);
     let joined = false;
-    let bound = false;
     let listening = false;
-    const rollback = async () => {
-        if (listening || joined) {
-            const rollbackSquare = await Square.at({ path });
-            try {
-                const rollbackParticipant = await rollbackSquare.join(name);
-                if (listening)
-                    await rollbackParticipant.ignore(allocated.id);
-                if (joined)
-                    await rollbackParticipant.done();
-            }
-            finally {
-                await rollbackSquare.close();
-            }
+    let bindingsBeforeCall = [];
+    let hasBindingSnapshot = false;
+    let createdBindings = [];
+    const rememberCreatedBindings = async () => {
+        const beforeKeys = new Set(bindingsBeforeCall.map(presenceKey));
+        createdBindings = (await participantBindings(hostLedger, path, name))
+            .filter((binding) => !beforeKeys.has(presenceKey(binding)))
+            .map(exactPresenceKey);
+    };
+    const refreshCreatedBindings = async () => {
+        try {
+            await rememberCreatedBindings();
         }
-        if (bound)
-            await unbindCurrentParticipant(path, name, environment);
+        catch { }
     };
+    const rollback = async () => await rollbackSquareEdge({
+        path,
+        environment: squareEnvironment,
+        hostLedger,
+        name,
+        allocated,
+        joined,
+        listening,
+        createdBindings,
+    });
+    let square;
     try {
+        bindingsBeforeCall = await participantBindings(hostLedger, path, name);
+        hasBindingSnapshot = true;
+        square = await openKeiyakuSquare(path, squareEnvironment, hostLedger);
         const joinedResult = await square.joinWithActivity(name);
         joined = joinedResult.activity !== null;
         const participant = joinedResult.participant;
-        bound = (await bindCurrentParticipant(path, name, environment)).created;
+        await bindCurrentParticipant(path, name, squareEnvironment);
+        await rememberCreatedBindings();
         const listener = participant;
-        const change = await listener.listen(allocated.id);
+        let change;
+        try {
+            change = await listener.listen(allocated.id);
+        }
+        catch {
+            // Keep birth independent from an older or drifting Square name grammar.
+            await refreshCreatedBindings();
+            await rollback();
+            return;
+        }
         listening = change.activity !== null;
+        await square.close();
+        square = undefined;
         return {
             committed: true,
             participantName: name,
             rollback,
         };
     }
-    catch (error) {
-        try {
-            await rollback();
-        }
-        catch {
-            /* preserve the original Square edge failure */
-        }
-        throw error;
+    catch {
+        if (hasBindingSnapshot)
+            await refreshCreatedBindings();
+        await rollback();
+        return;
     }
     finally {
-        await square.close();
+        if (square !== undefined)
+            await square.close().catch(() => undefined);
     }
 }

package/build/src/cli/usage.js

@@ -17,7 +17,8 @@ export function usageLine(usage) {
         .map((line, index) => {
         if (index === 0)
             return `usage: keiyaku ${line}`;
-        return line.startsWith("task ") ? `       keiyaku ${line}` : `       ${line.trimStart()}`;
+        const continuation = line.trimStart();
+        return `       keiyaku ${continuation.startsWith("keiyaku ") ? continuation.slice("keiyaku ".length) : continuation}`;
     })
         .join("\n");
 }

package/build/src/contract-guidance.d.ts

@@ -0,0 +1,5 @@
+import type { ContractId, ContractState } from "./core/facts/types.js";
+export declare const CONTRACT_DELIVERER_SKILL: string;
+export declare const CONTRACT_REVIEWER_SKILL: string;
+export declare function renderContractAppointment(contract: ContractId): string;
+export declare function renderContractGuidance(state: ContractState): string;