@astrosheep/keiyaku 4.6.13 → 4.6.15

package/build/src/akuma/selection-owner-port.js

@@ -1,5 +1,4 @@
 import { AkumaSelfInterruptError } from "./akuma-errors.js";
-import { outcomePluginObserver } from "../plugin/akuma-signals.js";
 import { requireBornAkuma } from "./akuma-probe.js";
 import { executeAskAkuma, executeKillAkuma, executeTellAkuma } from "./akuma-selection-execution.js";
 import { executeWaitAkuma } from "./akuma-wait.js";
@@ -13,13 +12,13 @@ import { akumaObservationOf } from "./selection-observation.js";
  * unaddressable member never starts; the executor's own access to the target is
  * then the product act, never a second addressing probe.
  */
-export function selectionRequestPort(world, reportDiagnostic, servingBodyId) {
+export function selectionRequestPort(world, _reportDiagnostic, servingBodyId) {
     const prove = async (targets) => {
         for (const id of targets)
             await requireBornAkuma(world, id);
     };
     return {
-        wait: async ({ targets, observer, ...request }) => {
+        wait: async ({ targets, ...request }) => {
             await prove(targets);
             // The lower wait owner returns association-free native evidence; the
             // actual request crossing composes its canonical transport shape.
@@ -27,7 +26,6 @@ export function selectionRequestPort(world, reportDiagnostic, servingBodyId) {
                 path: world,
                 ids: targets,
                 ...request,
-                outcomeObserved: outcomePluginObserver({ world, reportDiagnostic }, observer),
             });
             return { ...native, observations: native.observations.map(akumaObservationOf) };
         },
@@ -37,7 +35,7 @@ export function selectionRequestPort(world, reportDiagnostic, servingBodyId) {
             await prove([target]);
             return await executeTellAkuma({ path: world, id: target, ...request });
         },
-        ask: async ({ target, observer, ...request }) => {
+        ask: async ({ target, ...request }) => {
             if (request.interrupt === true && servingBodyId === target)
                 throw new AkumaSelfInterruptError(target);
             await prove([target]);
@@ -45,7 +43,6 @@ export function selectionRequestPort(world, reportDiagnostic, servingBodyId) {
                 path: world,
                 id: target,
                 ...request,
-                outcomeObserved: outcomePluginObserver({ world, reportDiagnostic }, observer),
             });
         },
         kill: async ({ targets, ...request }) => {

package/build/src/akuma/selection-request.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import type { AkumaStatus } from "./akuma.js";
 import type { KillEvidence } from "./heart/index.js";
+import type { OutcomeObserver } from "./akuma-observe.js";
 import { type ErasedRequestCommand, type RequestProtocol, type ServiceRequestCommand } from "./request-wire.js";
 import type { Schema } from "./schema.js";
 import { type AkumaAskResult, type AkumaKillResult, type AkumaTellResult, type AkumaWaitResult } from "./selection-observation.js";
@@ -100,13 +101,139 @@ export declare function encodeSelectionLiveFailure(error: unknown): unknown | nu
 export declare function decodeSelectionLiveFailure(value: unknown): Error | null;
 export type SelectionRequest = z.infer<typeof waitRequestSchema> | z.infer<typeof tellRequestSchema> | z.infer<typeof askRequestSchema> | z.infer<typeof killRequestSchema>;
 export type SelectionService = z.infer<typeof waitServiceSchema> | z.infer<typeof tellServiceSchema> | z.infer<typeof askServiceSchema> | z.infer<typeof killServiceSchema>;
-type SelectionResult = AkumaWaitResult | AkumaTellResult | AkumaAskResult | AkumaKillResult;
+declare const forwardedAskResultSchema: z.ZodObject<{
+    result: z.ZodObject<{
+        akuma: z.ZodPipe<z.ZodString, z.ZodTransform<import("./identity.js").AkuId, string>>;
+        tell: z.ZodObject<{
+            admission: z.ZodObject<{
+                fact: z.ZodLiteral<"recorded">;
+                tellId: z.ZodString;
+            }, z.core.$strict>;
+            row: z.ZodObject<{
+                kind: z.ZodLiteral<"tell">;
+                sequence: z.ZodNumber;
+                at: z.ZodString;
+                tellId: z.ZodString;
+                text: z.ZodString;
+                state: z.ZodEnum<{
+                    pending: "pending";
+                    told: "told";
+                }>;
+                deliveries: z.ZodReadonly<z.ZodArray<z.ZodPipe<z.ZodObject<{
+                    deliveredAt: z.ZodString;
+                    route: z.ZodEnum<{
+                        live: "live";
+                        launch: "launch";
+                    }>;
+                    turnSequence: z.ZodNumber;
+                    receipt: z.ZodOptional<z.ZodEnum<{
+                        unavailable: "unavailable";
+                        required: "required";
+                    }>>;
+                }, z.core.$strict>, z.ZodTransform<Readonly<{
+                    turnSequence: number;
+                    route: "launch" | "live";
+                    receipt?: "unavailable" | "required";
+                    deliveredAt: string;
+                }>, {
+                    deliveredAt: string;
+                    route: "live" | "launch";
+                    turnSequence: number;
+                    receipt?: "unavailable" | "required" | undefined;
+                }>>>>;
+            }, z.core.$strict>;
+            wake: z.ZodUnion<readonly [z.ZodObject<{
+                kind: z.ZodLiteral<"told">;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"held">;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"pursuing">;
+                bodySequence: z.ZodNumber;
+            }, z.core.$strict>, z.ZodPipe<z.ZodObject<{
+                kind: z.ZodLiteral<"failed">;
+                diagnostic: z.ZodString;
+                child: z.ZodOptional<z.ZodObject<{
+                    code: z.ZodNullable<z.ZodNumber>;
+                    signal: z.ZodNullable<z.ZodString>;
+                    log: z.ZodObject<{
+                        path: z.ZodString;
+                        from: z.ZodNumber;
+                        to: z.ZodNumber;
+                    }, z.core.$strict>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>, z.ZodTransform<{
+                kind: "failed";
+                diagnostic: string;
+            } | {
+                child: {
+                    code: number | null;
+                    signal: string | null;
+                    log: {
+                        path: string;
+                        from: number;
+                        to: number;
+                    };
+                };
+                kind: "failed";
+                diagnostic: string;
+            }, {
+                kind: "failed";
+                diagnostic: string;
+                child?: {
+                    code: number | null;
+                    signal: string | null;
+                    log: {
+                        path: string;
+                        from: number;
+                        to: number;
+                    };
+                } | undefined;
+            }>>]>;
+            interruption: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"completed">;
+                bodySequence: z.ZodNumber;
+                putDown: z.ZodEnum<{
+                    "was-idle": "was-idle";
+                    "self-aborted": "self-aborted";
+                }>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"pending">;
+                bodySequence: z.ZodNumber;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"unavailable">;
+                bodySequence: z.ZodNumber;
+                evidence: z.ZodEnum<{
+                    hung: "hung";
+                    untidy: "untidy";
+                }>;
+            }, z.core.$strict>], "kind">>;
+        }, z.core.$strict>;
+        observation: z.ZodUnion<readonly [z.ZodObject<{
+            reason: z.ZodLiteral<"answered">;
+            answer: z.ZodUnknown;
+        }, z.core.$strict>, z.ZodObject<{
+            reason: z.ZodLiteral<"failed">;
+            diagnostic: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            reason: z.ZodLiteral<"invalid-output">;
+            diagnostic: z.ZodString;
+            answer: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            reason: z.ZodLiteral<"unanswered">;
+        }, z.core.$strict>, z.ZodObject<{
+            reason: z.ZodLiteral<"deadline">;
+        }, z.core.$strict>]>;
+        completedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    historyIds: z.ZodReadonly<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+type ForwardedAskResult = z.infer<typeof forwardedAskResultSchema>;
+type SelectionResult = AkumaWaitResult | AkumaTellResult | ForwardedAskResult | AkumaKillResult;
 export type SelectionRequestPort = Readonly<{
     wait(input: Readonly<{
         targets: readonly AkumaStatus["id"][];
         completion: "any" | "all";
         timeoutMs?: number;
-        observer: string;
         signal: AbortSignal;
     }>): Promise<AkumaWaitResult>;
     tell(input: Readonly<{
@@ -127,7 +254,7 @@ export type SelectionRequestPort = Readonly<{
         schemaJson?: string;
         initiator?: string;
         interrupt?: boolean;
-        observer: string;
+        outcomeObserved: OutcomeObserver;
         signal: AbortSignal;
     }>): Promise<AkumaAskResult>;
     kill(input: Readonly<{
@@ -169,7 +296,7 @@ export declare function requestForwardedSelectionAsk(input: Readonly<{
     initiator?: string;
     interrupt?: boolean;
     signal?: AbortSignal;
-}>): Promise<AkumaAskResult>;
+}>): Promise<ForwardedAskResult>;
 export declare function requestForwardedSelectionKill(input: Readonly<{
     directory: string;
     targets: readonly AkumaStatus["id"][];

package/build/src/akuma/selection-request.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { AkumaNotBornError, AkumaObservationError, AkumaSelfInterruptError } from "./akuma-errors.js";
-import { akumaIdSchema } from "./identity.js";
+import { akumaIdSchema, parsePublicHistoryId } from "./identity.js";
 import { requestBodyCommand } from "./request-rendezvous.js";
 import { eraseRequestCommand, } from "./request-wire.js";
 import { schemaJsonText } from "./schema.js";
@@ -104,6 +104,12 @@ export function decodeSelectionLiveFailure(value) {
             ? new AkumaSelfInterruptError(failure.id)
             : new AkumaObservationError(failure.id, failure.diagnostic);
 }
+const forwardedAskResultSchema = z
+    .object({
+    result: selectionResultSchemas.ask,
+    historyIds: z.array(z.string().refine((id) => parsePublicHistoryId(id) !== null)).readonly(),
+})
+    .strict();
 function decodeSelectionRequest(action, value) {
     const schema = action === "akuma.wait"
         ? waitRequestSchema
@@ -134,7 +140,7 @@ function decodedSelectionResult(action, value) {
         : action === "akuma.tell"
             ? selectionResultSchemas.tell
             : action === "akuma.ask"
-                ? selectionResultSchemas.ask
+                ? forwardedAskResultSchema
                 : selectionResultSchemas.kill;
     const parsed = schema.safeParse(value);
     if (!parsed.success)
@@ -172,7 +178,7 @@ export function selectionRequestCommand(action, port) {
             if (request.action === "akuma.wait") {
                 return {
                     kind: "served",
-                    result: await port.wait({ ...request, observer: facts.requester, signal: facts.signal }),
+                    result: await port.wait({ ...request, signal: facts.signal }),
                     service: { action: request.action },
                 };
             }
@@ -194,20 +200,24 @@ export function selectionRequestCommand(action, port) {
             if (request.action === "akuma.ask") {
                 if (port.ask === undefined)
                     throw new Error("bounded Tell Selection port is unavailable");
+                let historyIds = [];
+                const result = await port.ask({
+                    target: request.target,
+                    body: request.body,
+                    tellId: facts.id,
+                    recordedAt: facts.admittedAt,
+                    outcomeObserved: async (_id, observed) => {
+                        historyIds = observed;
+                    },
+                    ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
+                    ...(request.schemaJson === undefined ? {} : { schemaJson: request.schemaJson }),
+                    ...(request.initiator === undefined ? {} : { initiator: request.initiator }),
+                    ...(request.interrupt === undefined ? {} : { interrupt: request.interrupt }),
+                    signal: facts.signal,
+                });
                 return {
                     kind: "served",
-                    result: await port.ask({
-                        target: request.target,
-                        body: request.body,
-                        tellId: facts.id,
-                        recordedAt: facts.admittedAt,
-                        observer: facts.requester,
-                        ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
-                        ...(request.schemaJson === undefined ? {} : { schemaJson: request.schemaJson }),
-                        ...(request.initiator === undefined ? {} : { initiator: request.initiator }),
-                        ...(request.interrupt === undefined ? {} : { interrupt: request.interrupt }),
-                        signal: facts.signal,
-                    }),
+                    result: { result, historyIds },
                     service: { action: request.action, target: request.target, tellId: facts.id },
                 };
             }

package/build/src/alias/index.d.ts

@@ -11,6 +11,17 @@ export type AliasMove = Readonly<{
 }>;
 export declare function nukeAliases(world: WorldRoot): Promise<void>;
 export declare function readAliases(world: WorldRoot): Promise<readonly AliasBinding[]>;
+export type HeldAliasCustody = Readonly<{
+    bindings: readonly AliasBinding[];
+    release(): void;
+}>;
+/**
+ * Take the same authority lock Alias writers use and read the current bindings
+ * under it. A holder keeps the lock across its cross-authority decision and
+ * effect, so no Alias move can commit between them. Null means another writer
+ * holds the authority; the caller must leave its subject untouched.
+ */
+export declare function tryAcquireAliasCustody(world: WorldRoot): Promise<HeldAliasCustody | null>;
 export declare function moveAlias(input: Readonly<{
     world: WorldRoot;
     alias: AkumaAlias;

package/build/src/alias/index.js

@@ -2,7 +2,7 @@ import { lstat, mkdir, readFile, unlink } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { parseAkuId } from "../akuma/identity.js";
 import { replaceFileDurably } from "../coordination/durable-file.js";
-import { acquireSqliteTransactionLock } from "../coordination/sqlite-transaction-lock.js";
+import { acquireSqliteTransactionLock, tryAcquireSqliteTransactionLock, } from "../coordination/sqlite-transaction-lock.js";
 import { AuthorityCorruptionError } from "../core/facts/errors.js";
 import { parseAkumaAlias, parseReadableAkumaAlias } from "../identity/selector.js";
 const VERSION = 1;
@@ -113,6 +113,25 @@ export async function nukeAliases(world) {
 export async function readAliases(world) {
     return await read(paths(world).authority);
 }
+/**
+ * Take the same authority lock Alias writers use and read the current bindings
+ * under it. A holder keeps the lock across its cross-authority decision and
+ * effect, so no Alias move can commit between them. Null means another writer
+ * holds the authority; the caller must leave its subject untouched.
+ */
+export async function tryAcquireAliasCustody(world) {
+    const location = paths(world);
+    const held = await tryAcquireSqliteTransactionLock({ path: location.lock, mode: "immediate" });
+    if (held === null)
+        return null;
+    try {
+        return { bindings: await read(location.authority), release: () => held.close() };
+    }
+    catch (error) {
+        held.close();
+        throw error;
+    }
+}
 export async function moveAlias(input) {
     const alias = parseAkumaAlias(input.alias);
     const akuId = parseAkuId(input.akuId).id;

package/build/src/cli/commands/contract-grammar.d.ts

@@ -1,4 +1,15 @@
+import { type AkumaCaller } from "../../akuma/caller.js";
+import { type AkuId } from "../../akuma/identity.js";
 import { type ContractCommand } from "./contract-help.js";
+type AkumaCallerSelector = Readonly<{
+    kind: "mine";
+}> | Readonly<{
+    kind: "external";
+    caller: AkumaCaller;
+}> | Readonly<{
+    kind: "akuma";
+    akuId: AkuId;
+}>;
 type CatalogQuery = Readonly<{
     kind: "debts";
     namespace?: readonly string[];
@@ -12,6 +23,7 @@ type CatalogQuery = Readonly<{
 }> | Readonly<{
     kind: "akuma";
     archetype?: string;
+    caller?: AkumaCallerSelector;
     limit?: number;
 }>;
 type Output = Readonly<{

package/build/src/cli/commands/contract-grammar.js

@@ -1,4 +1,6 @@
 import { validateAkumaName } from "../../identity/normalize.js";
+import { decodeAkumaCaller } from "../../akuma/caller.js";
+import { parseAkuId } from "../../akuma/identity.js";
 import { parseDebtNamespaceSelector } from "../../debt/catalog.js";
 import { CliUsageError, commandGuide } from "../usage.js";
 import { CONTRACT_COMMAND_SPECS } from "./contract-help.js";
@@ -231,26 +233,76 @@ function debtCatalogQuery(path, limit) {
         refuse("ls", error instanceof Error ? error.message : `invalid Debt namespace selector: ${path}`);
     }
 }
+function parseCallerSelector(parts) {
+    const mine = parts.flags.mine === true;
+    const value = optionalFlag(parts.flags, "caller");
+    if (mine && value !== undefined)
+        refuse("ls", "--mine and --caller are mutually exclusive");
+    if (mine)
+        return { kind: "mine" };
+    if (value === undefined)
+        return undefined;
+    const text = value.trim();
+    if (text.startsWith("aku/")) {
+        try {
+            return { kind: "akuma", akuId: parseAkuId(text).id };
+        }
+        catch (error) {
+            refuse("ls", `--caller has an invalid Akuma identity: ${error instanceof Error ? error.message : text}`);
+        }
+    }
+    const colon = text.indexOf(":");
+    if (colon < 0)
+        refuse("ls", "--caller requires <integration>:<id> or aku/<name>/<suffix>");
+    try {
+        const caller = decodeAkumaCaller({
+            kind: "external",
+            integration: text.slice(0, colon),
+            id: text.slice(colon + 1),
+        });
+        if (caller === undefined)
+            refuse("ls", "--caller requires <integration>:<id> or aku/<name>/<suffix>");
+        return { kind: "external", caller };
+    }
+    catch (error) {
+        refuse("ls", `--caller is invalid: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 function parseLs(parts) {
     const path = parts.positionals[0];
-    if (path === undefined)
-        refuse("ls", "ls requires a selector");
     const limit = listLimit(parts);
-    const debtQuery = debtCatalogQuery(path, limit);
-    if (debtQuery !== null)
-        return { command: "ls", query: debtQuery, output: parts.output };
-    if (path === "kei" || path === "kei/") {
-        return {
-            command: "ls",
-            query: { kind: "contracts", ...(limit === undefined ? {} : { limit }) },
-            output: parts.output,
-        };
+    const caller = parseCallerSelector(parts);
+    const callerRefusal = "--mine and --caller select Akuma instances only";
+    if (path !== undefined) {
+        const debtQuery = debtCatalogQuery(path, limit);
+        if (debtQuery !== null) {
+            if (caller !== undefined)
+                refuse("ls", callerRefusal);
+            return { command: "ls", query: debtQuery, output: parts.output };
+        }
+        if (path === "kei" || path === "kei/") {
+            if (caller !== undefined)
+                refuse("ls", callerRefusal);
+            return {
+                command: "ls",
+                query: { kind: "contracts", ...(limit === undefined ? {} : { limit }) },
+                output: parts.output,
+            };
+        }
+        if (caller !== undefined && (path === "aku" || path === "aku/"))
+            refuse("ls", "--mine and --caller need an Akuma instance catalogue, not Akuma names");
     }
+    if (path === undefined && caller === undefined)
+        refuse("ls", "ls requires a selector");
     try {
-        const query = parseAkumaCatalogPath(path);
+        const query = path === undefined ? { kind: "akuma" } : parseAkumaCatalogPath(path);
         if (query === null)
             refuse("ls", "ls requires a supported identity directory selector");
-        return { command: "ls", query: { ...query, ...(limit === undefined ? {} : { limit }) }, output: parts.output };
+        return {
+            command: "ls",
+            query: { ...query, ...(limit === undefined ? {} : { limit }), ...(caller === undefined ? {} : { caller }) },
+            output: parts.output,
+        };
     }
     catch (error) {
         if (error instanceof CliUsageError)

package/build/src/cli/commands/contract-help.d.ts

@@ -118,8 +118,10 @@ export declare const CONTRACT_COMMAND_SPECS: {
         readonly flags: {
             readonly limit: "value";
             readonly json: "boolean";
+            readonly mine: "boolean";
+            readonly caller: "value";
         };
-        readonly usage: "ls debt[/] [--limit <count>]\nls kei[/] [--limit <count>]\nls aku[/] [--limit <count>]\nls aku/<name>[/] [--limit <count>]\nls \"aku/<name>/*\" [--limit <count>]\nls \"aku/*/*\" [--limit <count>]";
+        readonly usage: "ls debt[/] [--limit <count>]\nls kei[/] [--limit <count>]\nls aku[/] [--limit <count>]\nls aku/<name>[/] [--limit <count>]\nls \"aku/<name>/*\" [--limit <count>]\nls \"aku/*/*\" [--limit <count>]\nls [\"aku/*/*\"] --mine\nls [\"aku/*/*\"] --caller <integration>:<id> | aku/<name>/<suffix>";
         readonly purpose: "List debts (ls debt), contracts (ls kei), or akumas (ls aku).";
         readonly details: string;
     };

package/build/src/cli/commands/contract-help.js

@@ -182,13 +182,16 @@ export const CONTRACT_COMMAND_SPECS = {
     ls: {
         positional: "optional",
         stdin: "none",
-        flags: { limit: "value", json: "boolean" },
-        usage: 'ls debt[/] [--limit <count>]\nls kei[/] [--limit <count>]\nls aku[/] [--limit <count>]\nls aku/<name>[/] [--limit <count>]\nls "aku/<name>/*" [--limit <count>]\nls "aku/*/*" [--limit <count>]',
+        flags: { limit: "value", json: "boolean", mine: "boolean", caller: "value" },
+        usage: 'ls debt[/] [--limit <count>]\nls kei[/] [--limit <count>]\nls aku[/] [--limit <count>]\nls aku/<name>[/] [--limit <count>]\nls "aku/<name>/*" [--limit <count>]\nls "aku/*/*" [--limit <count>]\nls ["aku/*/*"] --mine\nls ["aku/*/*"] --caller <integration>:<id> | aku/<name>/<suffix>',
         purpose: "List debts (ls debt), contracts (ls kei), or akumas (ls aku).",
         details: [
             "ls kei lists active Contracts; accepted and abandoned ones leave the list, and their record stays in history and Git.",
             "ls aku/ lists the callable Akuma-name catalog; ls aku/<name> lists the living Akumas under one name.",
             'ls "aku/<name>/*" is the same living set in glob form; ls "aku/*/*" lists every living Akuma.',
+            "--mine selects the caller identity of this process and lists that caller's direct and transitive descendants in this World.",
+            "--caller selects an explicit caller instead; both selectors are World-local and refuse for Contract, Debt, or Akuma-name catalogues.",
+            "Descendant rows name their immediate calling Akuma beside the row.",
         ].join("\n"),
     },
     reconcile: {

package/build/src/cli/commands/contract.js

@@ -6,6 +6,7 @@ import { composeContractLibrary, observeKeiyaku } from "../../library/contract-c
 import { validateArcMarkdown, validateContractMarkdown } from "../../library/input.js";
 import { createKeiyakuHandle } from "../../library/keiyaku.js";
 import { SettingsError, settings } from "../../settings.js";
+import { akumaCallerFromEnvironment } from "../akuma-caller.js";
 import { Debts } from "../../debt/index.js";
 import { actorFromEdge } from "../actor.js";
 import { resolveInvocationCwd } from "../coordinates.js";
@@ -21,7 +22,8 @@ import { renderRegionText } from "../render/region.js";
 import { renderSettingsText, settingsJsonValue } from "../render/settings.js";
 import { canonicalContractSelector, contractFromInput, resolveContractId } from "../selectors.js";
 import { displayContext, emit, writeJson, writeStderr, writeStdout } from "../streams.js";
-import { CliUsageError, isBlankInput } from "../usage.js";
+import { CliUsageError, commandGuide, isBlankInput } from "../usage.js";
+import { CONTRACT_COMMAND_SPECS } from "./contract-help.js";
 function requiredRepo(coordinates) {
     if (coordinates.repo === undefined)
         throw new CliUsageError("this command requires a resolved Repo");
@@ -305,7 +307,7 @@ async function runNuke(command, coordinates) {
     });
     return emit(command.output, result, () => renderNukeText(result), nukeExitCode(result));
 }
-async function runLs(command, coordinates, home) {
+async function runLs(command, coordinates, home, runtime) {
     const query = command.query;
     if (query.kind === "contracts") {
         const list = await Keiyaku.with().list({
@@ -334,11 +336,36 @@ async function runLs(command, coordinates, home) {
             throw new Error("Debt list did not return an accepted observation");
         return emit(command.output, listed, () => renderDebtCatalogue(listed.value, query.namespace ?? []), 0);
     }
+    const caller = await lsCaller(query.caller, coordinates, runtime);
     const listed = await Akumas.of(coordinates.world).list({
         ...(query.archetype === undefined ? {} : { archetype: query.archetype }),
         ...(query.limit === undefined ? {} : { limit: query.limit }),
+        ...(caller === undefined ? {} : { caller }),
     });
-    return emit(command.output, listed, () => renderAkumaCatalogue(listed, query.archetype ?? null), 0);
+    return emit(command.output, listed, () => renderAkumaCatalogue(listed, query.archetype ?? null, caller), 0);
+}
+/** `--mine` is the process caller identity; `--caller` names the same coordinate explicitly. */
+async function lsCaller(selection, coordinates, runtime) {
+    const usage = (diagnostic) => new CliUsageError(diagnostic, commandGuide("ls", CONTRACT_COMMAND_SPECS.ls.usage));
+    if (selection === undefined)
+        return undefined;
+    if (selection.kind === "external")
+        return selection.caller;
+    if (selection.kind === "akuma") {
+        if (coordinates.world === null)
+            throw usage("no Keiyaku world contains the invocation cwd");
+        return { kind: "akuma", world: coordinates.world, akuId: selection.akuId };
+    }
+    let caller;
+    try {
+        caller = await akumaCallerFromEnvironment(runtime.environment);
+    }
+    catch (error) {
+        throw usage(error instanceof Error ? error.message : String(error));
+    }
+    if (caller === undefined)
+        throw usage("--mine requires a caller identity; set KEIYAKU_ACTOR_ID and KEIYAKU_ACTOR_WORLD or run inside a calling host");
+    return caller;
 }
 async function readAkumaStatus(akuma, alias, coordinates) {
     if (coordinates.world === null)
@@ -531,7 +558,7 @@ export async function runContractCommand(command, coordinates, runtime) {
         case "nuke":
             return await runNuke(command, coordinates);
         case "ls":
-            return await runLs(command, coordinates, home);
+            return await runLs(command, coordinates, home, runtime);
         case "show":
             return await runShow(command, coordinates);
         case "status":

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

@@ -1,8 +1,9 @@
 import type { AkumaList } from "../../akuma/akuma.js";
+import { type AkumaCaller } from "../../akuma/caller.js";
 import type { ArchetypeCatalog } from "../../index.js";
 import type { ContractList } from "../../library/contract-types.js";
 import type { DebtPage, DebtRow } from "../../debt/index.js";
-export declare function renderAkumaCatalogue(list: AkumaList, archetype: string | null): string;
+export declare function renderAkumaCatalogue(list: AkumaList, archetype: string | null, caller?: AkumaCaller): string;
 export declare function renderContractCatalogue(list: ContractList): string;
 export declare function renderArchetypeCatalogue(list: ArchetypeCatalog): string;
 export declare function renderDebtCatalogue(list: DebtPage<DebtRow>, namespace: readonly string[]): string;

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

@@ -1,3 +1,4 @@
+import { akumaCallerKey } from "../../akuma/caller.js";
 import { abbreviateGitIds, displayGitId, gitIdsInRow, lifecycleWord, progressStrip } from "./contract-observation.js";
 import { ageText, emptyCatalogue, renderBoundedPayload, safeText } from "./terminal.js";
 import { akumaMark, contractMark } from "./marks.js";
@@ -7,11 +8,12 @@ function relativeAge(source, observedAt) {
         return null;
     return ageText(source, observedAt);
 }
-export function renderAkumaCatalogue(list, archetype) {
+export function renderAkumaCatalogue(list, archetype, caller) {
     const rows = list.rows;
     if (rows.length === 0) {
         return emptyCatalogue("akuma");
     }
+    const root = caller === undefined ? undefined : akumaCallerKey(caller);
     const lines = [archetype === null ? "AKUMA // recent" : `AKUMA // ${safeText(archetype)}`, ""];
     for (const row of rows) {
         const lifeAt = "lifeAt" in row ? row.lifeAt : null;
@@ -23,7 +25,11 @@ export function renderAkumaCatalogue(list, archetype) {
             ...(activityAge === null || activityAge === lifeAge ? [] : [`activity ${activityAge}`]),
         ];
         const aliases = row.aliases.length === 0 ? "" : ` (${row.aliases.map((alias) => safeText(alias)).join(" ")})`;
-        lines.push(`${akumaMark(row.life)} ${safeText(row.id)}${aliases} · ${row.life}${ages.length === 0 ? "" : ` · ${ages.join(" · ")}`}`);
+        const rowCaller = "caller" in row ? row.caller : undefined;
+        const by = root !== undefined && rowCaller?.kind === "akuma" && akumaCallerKey(rowCaller) !== root
+            ? ` · by ${safeText(rowCaller.akuId)}`
+            : "";
+        lines.push(`${akumaMark(row.life)} ${safeText(row.id)}${aliases} · ${row.life}${ages.length === 0 ? "" : ` · ${ages.join(" · ")}`}${by}`);
     }
     if (list.hasMore)
         lines.push("…");

package/build/src/cli/square-identity.d.ts

@@ -7,9 +7,4 @@ export type SquareSeatControl = Readonly<{
     signal?: AbortSignal;
     budgetMs?: number;
 }>;
-/**
- * The Square participant name this submitting session should speak as, or
- * undefined when no honest choice exists. Identity preparation is optional, so it
- * never refuses the enclosing operation and always settles within one budget.
- */
 export declare function squareSeat(input: SquareSeatInput, control?: SquareSeatControl): Promise<string | undefined>;