@tpsdev-ai/flair 0.53.0 → 0.54.1

package/dist/commands/service.js

@@ -0,0 +1,315 @@
+import { DEFAULT_ADMIN_USER } from "../lib/auth-resolve.js";
+import { classifyDaemonState } from "../lib/daemon-liveness.js";
+import { diagnoseLaunchdPlistPaths, isDetached, renderDetachedWarning } from "../lib/launchd-management.js";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+let cli;
+/** Bind the cli-locals this module depends on. */
+export function bindCli(fns) {
+    cli = fns;
+}
+function buildDirectSpawnEnv(...args) {
+    return cli.buildDirectSpawnEnv(...args);
+}
+function defaultDataDir(...args) {
+    return cli.defaultDataDir(...args);
+}
+function ensureLaunchdServiceLoaded(...args) {
+    return cli.ensureLaunchdServiceLoaded(...args);
+}
+function flairPackageDir(...args) {
+    return cli.flairPackageDir(...args);
+}
+function gatherDaemonEvidence(...args) {
+    return cli.gatherDaemonEvidence(...args);
+}
+function guardEngineNotBackwards(...args) {
+    return cli.guardEngineNotBackwards(...args);
+}
+function harperBinNotFoundMessage(...args) {
+    return cli.harperBinNotFoundMessage(...args);
+}
+function harperSearchRoots(...args) {
+    return cli.harperSearchRoots(...args);
+}
+function observeLaunchdManagement(...args) {
+    return cli.observeLaunchdManagement(...args);
+}
+function probeHealth(...args) {
+    return cli.probeHealth(...args);
+}
+function readyOpsSocketPosture(...args) {
+    return cli.readyOpsSocketPosture(...args);
+}
+function resolveHarperBin(...args) {
+    return cli.resolveHarperBin(...args);
+}
+function resolveHttpPort(...args) {
+    return cli.resolveHttpPort(...args);
+}
+function resolveLaunchdLabel(...args) {
+    return cli.resolveLaunchdLabel(...args);
+}
+function resolveOpsBindHost(...args) {
+    return cli.resolveOpsBindHost(...args);
+}
+function resolveOpsPort(...args) {
+    return cli.resolveOpsPort(...args);
+}
+function restartFlair(...args) {
+    return cli.restartFlair(...args);
+}
+function stampEngineVersionIfRunning(...args) {
+    return cli.stampEngineVersionIfRunning(...args);
+}
+function waitForHealth(...args) {
+    return cli.waitForHealth(...args);
+}
+function waitForProcessExit(...args) {
+    return cli.waitForProcessExit(...args);
+}
+function writeDaemonSidecar(...args) {
+    return cli.writeDaemonSidecar(...args);
+}
+export function register(program) {
+    const LEGACY_LAUNCHD_LABEL = cli.LEGACY_LAUNCHD_LABEL;
+    const STARTUP_TIMEOUT_MS = cli.STARTUP_TIMEOUT_MS;
+    // ─── flair stop ───────────────────────────────────────────────────────────────
+    program
+        .command("stop")
+        .description("Stop the running Flair (Harper) instance")
+        .option("--port <port>", "Harper HTTP port")
+        .action(async (opts) => {
+        const port = resolveHttpPort(opts);
+        const platform = process.platform;
+        if (platform === "darwin") {
+            // macOS: try launchd first. resolveLaunchdLabel (flair#693) finds
+            // whichever label this data dir is actually registered under —
+            // the new instance-scoped one, or a pre-flair#693 legacy install.
+            const { plistPath } = resolveLaunchdLabel(defaultDataDir());
+            if (existsSync(plistPath)) {
+                try {
+                    const { execSync } = await import("node:child_process");
+                    execSync(`launchctl unload "${plistPath}"`, { stdio: "pipe" });
+                    console.log("✅ Flair stopped (launchd service unloaded)");
+                    return;
+                }
+                catch {
+                    // launchd unload failed, try PID fallback
+                }
+            }
+        }
+        // Non-launchd: the five-state liveness machine (flair#1454). The old
+        // decision tree (launchd -> lsof -> "not running") is REPLACED, not
+        // patched: `lsof` absence used to render as a definite "not running", and
+        // the pidfile was only consulted to attribute port-derived PIDs. Now the
+        // pidfile + identity sidecar are the primary evidence, and the health
+        // probe is a cross-check — never the verdict.
+        const dataDir = defaultDataDir();
+        const evidence = await gatherDaemonEvidence(port, dataDir);
+        const state = classifyDaemonState(evidence, { port, dataDir });
+        switch (state.state) {
+            case "RUNNING":
+            case "WEDGED": {
+                // Identity is already proven for both of these — killing a wedged
+                // daemon is recovery, not a recycled-PID gamble.
+                const pid = state.pid;
+                const label = state.state === "WEDGED" ? "wedged daemon" : "daemon";
+                try {
+                    process.kill(pid, "SIGTERM");
+                }
+                catch (err) {
+                    if (err?.code !== "ESRCH") {
+                        console.error(`❌ failed to signal pid ${pid}: ${err?.code ?? err?.message}`);
+                        process.exit(1);
+                    }
+                }
+                await waitForProcessExit(pid, STARTUP_TIMEOUT_MS);
+                const after = await probeHealth(port);
+                if (after.kind === "refused") {
+                    console.log(`✅ Flair stopped (${label}, pid ${pid})`);
+                }
+                else {
+                    console.log(`✅ Flair stopped (${label}, pid ${pid}; port ${port} may still be releasing)`);
+                }
+                return;
+            }
+            case "NOT_RUNNING":
+                console.log("Flair is not running.");
+                return;
+            case "DISAGREEMENT":
+                console.error(`⚠️  ${state.detail}`);
+                console.error(`   Not stopping — the evidence conflicts.`);
+                console.error(`   pidfile: ${join(dataDir, "hdb.pid")}`);
+                console.error(`   port: ${port}`);
+                console.error(`   To inspect: flair doctor`);
+                process.exit(1);
+            case "UNKNOWN":
+                console.error(`⚠️  ${state.detail}`);
+                console.error(`   Not stopping — could not determine whether Flair is running.`);
+                process.exit(1);
+        }
+    });
+    // ─── flair start ──────────────────────────────────────────────────────────────
+    program
+        .command("start")
+        .description("Start Flair (Harper) — requires a prior 'flair init'")
+        .option("--port <port>", "Harper HTTP port")
+        .action(async (opts) => {
+        const port = resolveHttpPort(opts);
+        const dataDir = defaultDataDir();
+        // Already-running check via the five-state liveness machine (flair#1454).
+        // The old check was a bare `fetch /Health` that treated "got a response"
+        // as "already running" and exited 0 — half of #1454. Now the machine
+        // classifies, and every non-NOT_RUNNING state refuses with a non-zero exit.
+        const evidence = await gatherDaemonEvidence(port, dataDir);
+        const state = classifyDaemonState(evidence, { port, dataDir });
+        switch (state.state) {
+            case "NOT_RUNNING":
+                break; // proceed to boot
+            case "RUNNING":
+                console.error(`Flair is already running on port ${port} (pid ${state.pid}).`);
+                process.exit(1);
+            case "WEDGED":
+                console.error(`⚠️  A wedged Flair daemon (pid ${state.pid}) is holding port ${port}.`);
+                console.error(`   Run 'flair stop' first — never start over a live pid.`);
+                process.exit(1);
+            case "DISAGREEMENT":
+                console.error(`⚠️  ${state.detail}`);
+                console.error(`   Refusing to start — the evidence conflicts.`);
+                console.error(`   pidfile: ${join(dataDir, "hdb.pid")}`);
+                console.error(`   port: ${port}`);
+                console.error(`   To inspect: flair doctor`);
+                process.exit(1);
+            case "UNKNOWN":
+                console.error(`⚠️  ${state.detail}`);
+                console.error(`   Refusing to start — could not determine whether Flair is running.`);
+                process.exit(1);
+        }
+        if (!existsSync(dataDir)) {
+            console.error("❌ No Flair data directory found. Run 'flair init' first.");
+            process.exit(1);
+        }
+        // flair#1047: refuse to boot if the store was written by a newer engine.
+        // Same guard startFlairProcess runs, so restart/upgrade/snapshot cannot
+        // reach a boot this command would refuse (flair#1093).
+        try {
+            guardEngineNotBackwards(dataDir);
+        }
+        catch (err) {
+            if (!err?.engineBackwards)
+                throw err;
+            console.error(`❌ Cannot start Flair — the data directory was written by a newer Harper engine.\n`);
+            console.error(err.message);
+            process.exit(1);
+        }
+        const platform = process.platform;
+        if (platform === "darwin") {
+            // resolveLaunchdLabel (flair#693) finds whichever label this data
+            // dir is currently registered under (new instance-scoped, or a
+            // pre-flair#693 legacy install) so the existsSync gate below is
+            // accurate before we attempt anything.
+            const { plistPath } = resolveLaunchdLabel(dataDir);
+            if (existsSync(plistPath)) {
+                try {
+                    // flair#1022, same pre-flight as startFlairProcess: launchctl exits 0
+                    // for a job it cannot exec, so a stale plist is only ever observable
+                    // as a startup timeout unless the paths are checked first.
+                    const stalePlist = diagnoseLaunchdPlistPaths(plistPath);
+                    if (stalePlist) {
+                        throw new Error(`${stalePlist.message} Fix it with: ${stalePlist.remedy.join(" && ")}`);
+                    }
+                    const { execSync } = await import("node:child_process");
+                    const { label, migrated } = ensureLaunchdServiceLoaded(dataDir, (cmd) => execSync(cmd, { stdio: "pipe" }));
+                    if (migrated)
+                        console.log(`Migrated launchd service off the legacy label (${LEGACY_LAUNCHD_LABEL}) → ${label} ✓`);
+                    await waitForHealth(port, DEFAULT_ADMIN_USER, process.env.HDB_ADMIN_PASSWORD ?? "", STARTUP_TIMEOUT_MS);
+                    readyOpsSocketPosture(dataDir); // flair#763: re-assert socket posture on the freshly-created socket
+                    stampEngineVersionIfRunning(dataDir); // flair#1047: stamp the store with the engine version
+                    console.log("✅ Flair started (launchd)");
+                    return;
+                }
+                catch (err) {
+                    console.error(`launchd start failed, falling back to direct start: ${err.message}`);
+                }
+            }
+        }
+        // Direct start (Linux, or macOS fallback when no launchd plist)
+        const harper = resolveHarperBin(harperSearchRoots());
+        if (!harper.path) {
+            console.error(`❌ ${harperBinNotFoundMessage(harper.searched)}`);
+            process.exit(1);
+        }
+        const bin = harper.path;
+        const adminPass = process.env.HDB_ADMIN_PASSWORD || process.env.FLAIR_ADMIN_PASS || "";
+        // flair#670/#863: this fallback path (no launchd plist) sets no
+        // HARPER_SET_CONFIG, so the ops bind has to be re-asserted explicitly on
+        // every spawn — see buildDirectSpawnEnv. The escape hatch on this path is
+        // FLAIR_OPS_BIND or the `opsBind` that `flair init --ops-bind` persisted to
+        // ~/.flair/config.yaml; there is no --ops-bind flag on `start`.
+        const env = {
+            ...process.env,
+            ...buildDirectSpawnEnv({
+                dataDir,
+                modelsDir: process.env.FLAIR_MODELS_DIR ?? join(dataDir, "models"),
+                httpPort: port,
+                opsPort: resolveOpsPort(opts),
+                opsBindHost: resolveOpsBindHost({}),
+                adminUser: DEFAULT_ADMIN_USER,
+                adminPass,
+            }),
+        };
+        const proc = spawn(process.execPath, [bin, "run", "."], {
+            cwd: flairPackageDir(), env, detached: true, stdio: "ignore",
+        });
+        proc.unref();
+        // Write the identity sidecar immediately after spawn (flair#1454 decision
+        // 3) — BEFORE waitForHealth, so startTimeMs stays within the ±2s tolerance
+        // of the process's real start time. `proc.pid` is the pid Harper writes to
+        // hdb.pid, since Harper runs in-process.
+        if (proc.pid)
+            writeDaemonSidecar(dataDir, proc.pid, port);
+        try {
+            await waitForHealth(port, DEFAULT_ADMIN_USER, adminPass, STARTUP_TIMEOUT_MS);
+            readyOpsSocketPosture(dataDir); // flair#763: re-assert socket posture on the freshly-created socket
+            stampEngineVersionIfRunning(dataDir); // flair#1047: stamp the store with the engine version
+            console.log(`✅ Flair started on port ${port}`);
+        }
+        catch {
+            console.error("❌ Flair failed to start within timeout. Check logs in " + join(dataDir, "harper.log"));
+            process.exit(1);
+        }
+    });
+    // ─── flair restart ────────────────────────────────────────────────────────────
+    program
+        .command("restart")
+        .description("Restart the Flair (Harper) instance")
+        .option("--port <port>", "Harper HTTP port")
+        .action(async (opts) => {
+        const port = resolveHttpPort(opts);
+        // Explicit, not defaulted inside restartFlair (flair#902): `flair
+        // restart` has no --data-dir, so the default install IS what it means —
+        // and saying so here is what keeps that true when someone adds one.
+        try {
+            await restartFlair(port, defaultDataDir());
+            // flair#1022: a restart that fell back off launchd left the instance
+            // running but unmanaged, and "✅ Flair restarted" was true of both
+            // outcomes. Ask launchd what it is actually running now — an
+            // observation, not a flag out of the restart, so it is right even when
+            // the detachment predates this command.
+            const managed = observeLaunchdManagement(defaultDataDir(), port);
+            if (isDetached(managed)) {
+                for (const line of renderDetachedWarning(managed, "Flair restarted, but it is NOT running under launchd.")) {
+                    console.error(line);
+                }
+                return;
+            }
+            console.log("✅ Flair restarted");
+        }
+        catch (err) {
+            console.error(`❌ Flair failed to restart: ${err?.message ?? err}`);
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/session.js

@@ -0,0 +1,184 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, rmSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { create as tarCreate, extract as tarExtract, list as tarList } from "tar";
+import { validateSnapshotArchive } from "../lib/safe-snapshot-extract.js";
+let cli;
+/** Bind shared CLI helpers. cli.ts calls this immediately before register(program). */
+export function bindCli(fns) {
+    cli = fns;
+}
+const humanBytes = (n) => cli.humanBytes(n);
+const relativeTime = (iso) => cli.relativeTime(iso);
+/** Register the `flair session` command group (flair#1631). */
+export function register(program) {
+    // ─── flair session snapshot ──────────────────────────────────────────────────
+    // Slice 2 of FLAIR-AGENT-CONTEXT-TIERS-B. Snapshot a
+    // session jsonl + label metadata into a tar.gz under ~/.flair/snapshots/<agent>/sessions/.
+    //
+    // Three subcommands: create | list | restore. Mirrors FLAIR-NIGHTLY-REM's
+    // snapshot pattern (tar.gz, 600 perms, 30-day retention enforced separately).
+    //
+    // Standalone-callable today; harness slices 3+4 will wire it into the
+    // session-reset pipeline.
+    const SNAPSHOT_ROOT = resolve(homedir(), ".flair", "snapshots");
+    function sessionSnapshotDir(agent) {
+        if (!/^[a-zA-Z0-9_-]+$/.test(agent))
+            throw new Error(`invalid agent id: ${agent}`);
+        return resolve(SNAPSHOT_ROOT, agent, "sessions");
+    }
+    const session = program.command("session").description("Agent session lifecycle (snapshot/restore for FLAIR-AGENT-CONTEXT-TIERS-B)");
+    const sessionSnapshot = session.command("snapshot").description("Manage session snapshots (tar.gz of session jsonl + metadata)");
+    sessionSnapshot
+        .command("create")
+        .description("Create a session snapshot tar.gz")
+        .requiredOption("--agent <id>", "Agent the session belongs to")
+        .requiredOption("--session-file <path>", "Path to the session jsonl to snapshot (e.g. /tmp/openclaw/openclaw-2026-05-03.log)")
+        .option("--label <text>", "Label for the snapshot file (e.g. ops-ID); default: ISO timestamp")
+        .action(async (opts) => {
+        const sessionFile = resolve(opts.sessionFile);
+        if (!existsSync(sessionFile)) {
+            console.error(`Error: --session-file does not exist: ${sessionFile}`);
+            process.exit(1);
+        }
+        const dir = sessionSnapshotDir(opts.agent);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const ts = new Date().toISOString().replace(/[:.]/g, "-");
+        const safeLabel = opts.label ? String(opts.label).replace(/[^a-zA-Z0-9._-]/g, "_") : ts;
+        const tarballName = opts.label ? `${safeLabel}-${ts}.tar.gz` : `${ts}.tar.gz`;
+        const tarballPath = resolve(dir, tarballName);
+        // Write a metadata.json into a tmp dir alongside the session file for the
+        // tarball, so the snapshot is self-describing.
+        const meta = {
+            agent: opts.agent,
+            label: opts.label ?? null,
+            sessionFile,
+            sessionFileSize: statSync(sessionFile).size,
+            createdAt: new Date().toISOString(),
+            flairVersion: cli.pkgVersion,
+        };
+        const tmpDir = resolve(dir, `.tmp-${process.pid}-${Date.now()}`);
+        mkdirSync(tmpDir, { recursive: true, mode: 0o700 });
+        try {
+            const sessionBaseName = sessionFile.split("/").pop() ?? "session.jsonl";
+            writeFileSync(resolve(tmpDir, sessionBaseName), readFileSync(sessionFile));
+            writeFileSync(resolve(tmpDir, "metadata.json"), JSON.stringify(meta, null, 2) + "\n");
+            await tarCreate({ gzip: true, cwd: tmpDir, file: tarballPath, portable: true }, [sessionBaseName, "metadata.json"]);
+            // Tarball perms: 600 (owner-only) — matches FLAIR-NIGHTLY-REM
+            chmodSync(tarballPath, 0o600);
+        }
+        finally {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+        const size = statSync(tarballPath).size;
+        console.log(tarballPath);
+        console.error(`  agent: ${opts.agent}`);
+        console.error(`  label: ${opts.label ?? "(none)"}`);
+        console.error(`  size:  ${humanBytes(size)}`);
+    });
+    sessionSnapshot
+        .command("list")
+        .description("List session snapshots for an agent (or all agents)")
+        .option("--agent <id>", "Filter to a single agent")
+        .option("--json", "Output as JSON")
+        .action(async (opts) => {
+        if (!existsSync(SNAPSHOT_ROOT)) {
+            if (opts.json) {
+                console.log("[]");
+                return;
+            }
+            console.log("(no snapshots — ~/.flair/snapshots/ does not exist yet)");
+            return;
+        }
+        const rows = [];
+        const agents = opts.agent ? [opts.agent] : readdirSync(SNAPSHOT_ROOT).filter((d) => {
+            try {
+                return statSync(resolve(SNAPSHOT_ROOT, d)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+        for (const a of agents) {
+            const dir = resolve(SNAPSHOT_ROOT, a, "sessions");
+            if (!existsSync(dir))
+                continue;
+            for (const f of readdirSync(dir)) {
+                if (!f.endsWith(".tar.gz"))
+                    continue;
+                const p = resolve(dir, f);
+                const s = statSync(p);
+                rows.push({ agent: a, file: f, path: p, size: s.size, mtime: s.mtime.toISOString() });
+            }
+        }
+        rows.sort((a, b) => b.mtime.localeCompare(a.mtime));
+        if (opts.json) {
+            console.log(JSON.stringify(rows, null, 2));
+            return;
+        }
+        if (rows.length === 0) {
+            console.log("(no snapshots)");
+            return;
+        }
+        const agentW = Math.max(5, ...rows.map((r) => r.agent.length));
+        const fileW = Math.max(20, ...rows.map((r) => r.file.length));
+        console.log(`  ${"agent".padEnd(agentW)}  ${"file".padEnd(fileW)}  size      age`);
+        for (const r of rows) {
+            console.log(`  ${r.agent.padEnd(agentW)}  ${r.file.padEnd(fileW)}  ${humanBytes(r.size).padEnd(8)}  ${relativeTime(r.mtime)}`);
+        }
+        console.log(`\n${rows.length} snapshot${rows.length > 1 ? "s" : ""}.`);
+    });
+    sessionSnapshot
+        .command("restore")
+        .description("Extract a session snapshot to a target directory")
+        .requiredOption("--snapshot <path>", "Path to the .tar.gz snapshot")
+        .option("--target <dir>", "Directory to extract into (default: <snapshot>.restored next to the snapshot)")
+        .option("--dry-run", "List the snapshot's contents without extracting")
+        .action(async (opts) => {
+        const snapshotPath = resolve(opts.snapshot);
+        if (!existsSync(snapshotPath)) {
+            console.error(`Error: snapshot does not exist: ${snapshotPath}`);
+            process.exit(1);
+        }
+        if (opts.dryRun) {
+            console.log("(dry-run) snapshot contents:");
+            const entries = [];
+            await tarList({ file: snapshotPath, onReadEntry: (entry) => entries.push(`  ${entry.path}  (${humanBytes(entry.size ?? 0)})`) });
+            for (const e of entries)
+                console.log(e);
+            return;
+        }
+        const targetDir = opts.target
+            ? resolve(opts.target)
+            : `${snapshotPath}.restored`;
+        if (existsSync(targetDir)) {
+            console.error(`Error: target directory already exists: ${targetDir}`);
+            console.error(`  Pass --target <new-path> or remove the existing dir.`);
+            process.exit(1);
+        }
+        // flair#903 — fail CLOSED on a tampered archive. node-tar's defaults below
+        // do contain malicious entries (leading "/" stripped, ".." entries
+        // dropped, no writing through a symlink — verified on the pinned tar
+        // against all four vectors), but they discard those entries SILENTLY: the
+        // restore printed the target dir as a plain success minus the parts it
+        // never mentioned. Validation runs BEFORE the target directory is even
+        // created — a tampered snapshot aborts the whole restore, names the
+        // offending entry, and writes nothing (same posture as the data-dir
+        // restore's extractSnapshotSafely). The default extract flags stay as
+        // containment defense-in-depth — deliberately NOT preservePaths; if that
+        // flag is ever added here, this call MUST move to extractSnapshotSafely.
+        // See src/lib/safe-snapshot-extract.ts.
+        try {
+            await validateSnapshotArchive({ file: snapshotPath, targetDir });
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        mkdirSync(targetDir, { recursive: true, mode: 0o700 });
+        await tarExtract({ file: snapshotPath, cwd: targetDir });
+        console.log(targetDir);
+        console.error(`  extracted to: ${targetDir}`);
+    });
+}

package/dist/commands/soul.js

@@ -0,0 +1,155 @@
+import * as render from "../render.js";
+let cli;
+/** Bind shared CLI helpers. cli.ts calls this immediately before register(program). */
+export function bindCli(fns) {
+    cli = fns;
+}
+function api(...args) {
+    return cli.api(...args);
+}
+function resolveSigningAgentId(opts, command) {
+    return cli.resolveSigningAgentId(opts, command);
+}
+function applyAdminPassFile(opts) {
+    cli.applyAdminPassFile(opts);
+}
+function addSharedCredentialOptions(cmd) {
+    return cli.addSharedCredentialOptions(cmd);
+}
+export function register(program) {
+    const soul = program.command("soul").description("Manage agent soul entries");
+    addSharedCredentialOptions(soul.command("set"))
+        .description("Set (upsert) a soul entry for an agent by key")
+        .requiredOption("--agent <id>")
+        .requiredOption("--key <key>")
+        .requiredOption("--value <value>")
+        .option("--durability <d>", "permanent|persistent|standard|ephemeral (default permanent — soul entries are identity, not working memory)")
+        .option("--json", "Emit raw JSON response (also: pipe + FLAIR_OUTPUT=json)")
+        .action(async (opts) => {
+        applyAdminPassFile(opts);
+        // PUT /Soul/{agentId:key} (upsert by id), matching flair-client's soul.set().
+        // The Soul table resource has no POST handler, so a collection POST /Soul
+        // 405s; the record must be written by its primary key. (#498)
+        //
+        // flair#1183: resolve the SIGNING identity through the canonical seam and
+        // thread it to api(). --agent is required, so the flag always wins the
+        // precedence — but before this, api() re-derived the signer as
+        // FLAIR_AGENT_ID-first, so `soul set --agent X` with FLAIR_AGENT_ID=Y set
+        // wrote a record owned by X while signing as Y (the soul family's stale rung).
+        const { agentId, source } = resolveSigningAgentId(opts, "soul set");
+        const id = `${opts.agent}:${opts.key}`;
+        const out = await api("PUT", `/Soul/${encodeURIComponent(id)}`, {
+            id,
+            agentId: opts.agent,
+            key: opts.key,
+            value: opts.value,
+            durability: opts.durability,
+            createdAt: new Date().toISOString(),
+        }, { agentId, agentIdSource: source, explicitAdminPass: opts.adminPass, adminUser: opts.adminUser });
+        const mode = render.resolveOutputMode(opts);
+        if (mode === "json") {
+            console.log(render.asJSON(out));
+            return;
+        }
+        console.log(`${render.icons.ok} ${render.wrap(render.c.green, "soul entry set")}`);
+        console.log(render.kv("agent", opts.agent));
+        console.log(render.kv("key", render.wrap(render.c.bold, opts.key)));
+        console.log(render.kv("value", String(opts.value)));
+        if (opts.durability)
+            console.log(render.kv("durability", render.wrap(render.c.magenta, opts.durability)));
+    });
+    soul.command("get")
+        .description("Fetch a single soul entry by id (agent:key)")
+        .argument("<id>")
+        .option("--agent <id>", "Agent ID to sign the read as (or set FLAIR_AGENT_ID); falls back to the config-profile agent")
+        .option("--json", "Emit raw JSON response (also: pipe + FLAIR_OUTPUT=json)")
+        .action(async (id, opts) => {
+        // flair#1183: /Soul reads are verified (any registered agent). Resolve the
+        // signer through the canonical seam so soul get honors the SAME precedence
+        // as every other family; a null result lets api() fall to admin-pass/floor.
+        const { agentId, source } = resolveSigningAgentId(opts, "soul get");
+        const out = await api("GET", `/Soul/${id}`, undefined, { agentId, agentIdSource: source });
+        const mode = render.resolveOutputMode(opts);
+        if (mode === "json") {
+            console.log(render.asJSON(out));
+            return;
+        }
+        if (!out || (typeof out === "object" && !out.id)) {
+            console.log(`${render.icons.info} ${render.wrap(render.c.dim, "no entry")}`);
+            return;
+        }
+        console.log(render.wrap(render.c.bold, out.id ?? id));
+        if (out.agentId)
+            console.log(render.kv("agent", out.agentId));
+        if (out.key)
+            console.log(render.kv("key", out.key));
+        if (out.value !== undefined)
+            console.log(render.kv("value", String(out.value)));
+        if (out.durability)
+            console.log(render.kv("durability", render.wrap(render.c.magenta, String(out.durability))));
+        if (out.priority)
+            console.log(render.kv("priority", String(out.priority)));
+        if (out.createdAt)
+            console.log(render.kv("created", `${render.relativeTime(out.createdAt)} ${render.wrap(render.c.dim, `(${out.createdAt})`)}`));
+        if (out.updatedAt && out.updatedAt !== out.createdAt) {
+            console.log(render.kv("updated", `${render.relativeTime(out.updatedAt)} ${render.wrap(render.c.dim, `(${out.updatedAt})`)}`));
+        }
+    });
+    soul.command("list")
+        .description("List all soul entries for an agent")
+        .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
+        .option("--json", "Emit raw JSON array (also: pipe + FLAIR_OUTPUT=json)")
+        .action(async (opts) => {
+        const { agentId, source } = resolveSigningAgentId(opts, "soul list");
+        if (!agentId) {
+            console.error(`${render.icons.error} --agent <id> required (or set FLAIR_AGENT_ID)`);
+            process.exit(2);
+        }
+        const out = await api("GET", `/Soul?agentId=${encodeURIComponent(agentId)}`, undefined, { agentId, agentIdSource: source });
+        const mode = render.resolveOutputMode(opts);
+        if (mode === "json") {
+            console.log(render.asJSON(out));
+            return;
+        }
+        const all = Array.isArray(out) ? out : (out?.results ?? out?.items ?? []);
+        if (all.length === 0) {
+            console.log(`${render.icons.info} ${render.wrap(render.c.dim, `no soul entries for agent ${agentId}`)}`);
+            return;
+        }
+        console.log(`${render.wrap(render.c.bold, String(all.length))} soul entries for agent ${render.wrap(render.c.bold, agentId)}\n`);
+        const priorityColor = (p) => {
+            if (p === "critical")
+                return render.c.red;
+            if (p === "high")
+                return render.c.yellow;
+            if (p === "low")
+                return render.c.gray;
+            return render.c.cyan;
+        };
+        const cols = [
+            { label: "key", key: "key", format: (v) => render.wrap(render.c.bold, String(v ?? "—")) },
+            {
+                label: "priority",
+                key: "priority",
+                format: (v) => {
+                    const p = String(v ?? "standard");
+                    return render.wrap(priorityColor(p), p);
+                },
+            },
+            {
+                label: "durability",
+                key: "durability",
+                format: (v) => {
+                    const d = String(v ?? "—");
+                    return d === "permanent" ? render.wrap(render.c.magenta, d) : render.wrap(render.c.dim, d);
+                },
+            },
+            {
+                label: "value",
+                key: "value",
+                format: (v) => String(v ?? "").replace(/\s+/g, " ").slice(0, 80),
+            },
+        ];
+        console.log(render.table(cols, all));
+    });
+}