@kya-os/cli 1.7.0 → 1.8.3

package/dist/utils/dco/setup.d.ts

@@ -1,11 +1,6 @@
+import { type StepResult, type StepStatus } from "../cli-kit/index.js";
 import { type GitIdentity } from "./git-config.js";
-export type StepStatus = "done" | "skipped" | "failed" | "action-required" | "would-change";
-export interface StepResult {
-    id: string;
-    title: string;
-    status: StepStatus;
-    detail?: string;
-}
+export type { StepStatus, StepResult };
 export interface DcoAgentInfo {
     did: string;
     name: string;
@@ -25,6 +20,14 @@ export interface DcoSetupOptions {
     force?: boolean;
     /** Allow interactive prompts (agent name fallback, scope refresh). */
     interactive?: boolean;
+    /**
+     * Wire signing for this EXISTING registered agent instead of resolving
+     * identity from this checkout's `.mcpi/`. Skips the identity.json preflight
+     * entirely and requires the key to already exist at `signingKeyPath(agent)`
+     * (never generated or converted in this mode). See `dco dispatch <slug>`,
+     * which derives the same did:web/url/email from the slug.
+     */
+    agent?: string;
 }
 export interface DcoSetupResult {
     ok: boolean;

package/dist/utils/dco/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/utils/dco/setup.ts"],"names":[],"mappings":"AAmBA,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAmBzB,MAAM,MAAM,UAAU,GAClB,MAAM,GACN,SAAS,GACT,QAAQ,GACR,iBAAiB,GACjB,cAAc,CAAC;AAEnB,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sEAAsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,cAAc,EAAE,OAAO,CAAC;IACxB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AA2HD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CA8oBzB"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../src/utils/dco/setup.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAOvE,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAoBzB,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;AAEvC,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sEAAsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,cAAc,EAAE,OAAO,CAAC;IACxB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAkKD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC,CAsqBzB"}

package/dist/utils/dco/setup.js

@@ -1,5 +1,5 @@
 import { execFile } from "child_process";
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from "fs";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 import { promisify } from "util";
@@ -7,8 +7,9 @@ import { readAgentMetadata, writeAgentMetadata } from "./agent-metadata.js";
 import { buildAttributionBlock, updateClaudeSettings, upsertClaudeMdBlock, } from "./claude-config.js";
 import { detectSigningConflicts, getGitConfigValue, installTrailerHook, isGitRepo, setGitConfig, } from "./git-config.js";
 import { GhNotInstalledError, GhScopeError, getGhUser, githubNoreplyEmail, isGhAuthenticated, isGhInstalled, listSigningKeys, refreshAuthScope, signingKeyAlreadyUploaded, uploadSigningKey, SCOPE_REFRESH_COMMAND, } from "./github.js";
-import { isValidSlug, keysDir, signingKeyPath } from "./paths.js";
-import { convertEd25519ToSshKey } from "./ssh-key.js";
+import { isValidSlug, signingKeyPath } from "./paths.js";
+import { writeAgentSigningKey } from "./signing-key-writer.js";
+import { sshFingerprintFromPublicKeyLine } from "./ssh-key.js";
 const execFileAsync = promisify(execFile);
 function slugify(value) {
     return value
@@ -23,11 +24,14 @@ function slugify(value) {
  */
 function sanitizeIdentityValue(value) {
     // eslint-disable-next-line no-control-regex
-    return value.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+    return value
+        .replace(/[\u0000-\u001f\u007f]+/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
 }
 /**
  * Distinguishes a missing identity from a present-but-unparseable one. The
- * two need different advice: "run mcpi register" after a corrupt read would
+ * two need different advice: "run kya-os register" after a corrupt read would
  * overwrite a potentially recoverable key with a brand new identity.
  */
 function readIdentityFile(cwd) {
@@ -110,6 +114,35 @@ async function promptForAgentName() {
     ]);
     return { name: name.trim(), slug };
 }
+/**
+ * Resolve the human committer's name/email: prefer git config, and only fall
+ * back to the authenticated GitHub profile for whichever field git is
+ * missing (never both at once, so a configured name survives a missing
+ * email or vice versa). Shared by both identity-resolution paths in
+ * `runDcoSetup`: this half of Step 2 is identical whether the agent side
+ * came from `.mcpi/` or from an explicit agent slug.
+ */
+async function resolveHumanIdentity(cwd) {
+    const gitName = await getGitConfigValue("user.name", cwd);
+    const gitEmail = await getGitConfigValue("user.email", cwd);
+    let ghUser = null;
+    if ((!gitName || !gitEmail) &&
+        (await isGhInstalled()) &&
+        (await isGhAuthenticated())) {
+        ghUser = await getGhUser();
+    }
+    // Use || (not ??) so an explicitly-empty git value is treated as missing,
+    // consistent with the truthiness gate above that decides to fetch gh.
+    const resolvedName = gitName || (ghUser ? ghUser.name || ghUser.login : undefined);
+    const resolvedEmail = gitEmail || (ghUser ? githubNoreplyEmail(ghUser) : undefined);
+    if (!resolvedName || !resolvedEmail) {
+        throw new Error("Could not resolve your git identity. Set git config user.name and user.email, or authenticate gh.");
+    }
+    return {
+        name: sanitizeIdentityValue(resolvedName),
+        email: sanitizeIdentityValue(resolvedEmail),
+    };
+}
 /**
  * Orchestrates the full DCO/attribution setup. Steps run in order; the three
  * foundation steps (preflight, identities, key material) abort the run when
@@ -160,217 +193,252 @@ export async function runDcoSetup(options = {}) {
             ...laterSteps,
         ]);
     }
-    const identityRead = readIdentityFile(cwd);
-    const identity = identityRead.status === "ok" ? identityRead.identity : null;
-    let preflightFailure = null;
-    if (identityRead.status === "corrupt") {
-        preflightFailure =
-            ".mcpi/identity.json exists but could not be parsed. Do NOT re-run `mcpi register` (it would overwrite the identity); inspect or restore the file first.";
-    }
-    else if (!identity?.privateKey || !identity?.did) {
-        preflightFailure =
-            identityRead.status === "ok"
-                ? ".mcpi/identity.json is missing required fields (did, privateKey). Inspect or restore the file before continuing."
-                : "No agent identity found in .mcpi/identity.json. Run `mcpi register` first, then re-run `mcpi dco setup`.";
-    }
-    else if (await isIdentityTrackedByGit(cwd)) {
-        preflightFailure =
-            ".mcpi/identity.json is tracked by git. A committed identity may have been shipped by the repo author; refusing to configure signing with it. Remove it from git history and generate your own identity with `mcpi register`.";
-    }
-    if (preflightFailure || !identity?.privateKey || !identity?.did) {
-        steps.push({
-            id: "preflight",
-            title: "Preflight checks",
-            status: "failed",
-            detail: preflightFailure ??
-                "No agent identity found in .mcpi/identity.json. Run `mcpi register` first, then re-run `mcpi dco setup`.",
-        });
-        return abort([
-            { id: "identities", title: "Resolve agent and human identity" },
-            { id: "key-material", title: "Write SSH signing key" },
-            ...laterSteps,
-        ]);
-    }
-    steps.push({ id: "preflight", title: "Preflight checks", status: "done" });
-    // Step 2: resolve identities
+    // Steps 1-3 (preflight, identity resolution, key material) branch here and
+    // rejoin at Step 4: an explicit agent slug wires signing for an EXISTING
+    // registered agent and never reads, requires, or writes `.mcpi/` — the
+    // identity is derived from the slug alone (the same derivation
+    // `dco dispatch <slug>` uses) and the key must already exist on disk,
+    // never generated or converted here. `agent`/`human`/`keyMaterial`/
+    // `privateKeyPath`/`publicKeyPath` are populated by whichever branch runs;
+    // both either abort the whole run or leave all five set by the time
+    // Step 4 reads them.
     let agent;
     let human;
-    try {
-        const metadata = readAgentMetadata(cwd);
-        if (metadata?.did && metadata.did !== identity.did) {
-            throw new Error(`.mcpi/agent.json is for a different agent (${metadata.did}) than .mcpi/identity.json (${identity.did}). Fix or remove agent.json before continuing.`);
-        }
-        // Only trust agent.json for attribution when it is cryptographically bound
-        // to this identity (its did matches identity.json). Unbound metadata (no
-        // did, e.g. planted in an untrusted repo) is ignored so it cannot spoof the
-        // agent name/slug/url; the resolved values are then persisted with the real
-        // did, healing the binding for later runs.
-        const boundMetadata = metadata && metadata.did === identity.did ? metadata : null;
-        let name = boundMetadata?.name ?? process.env.AGENT_NAME;
-        let slug = boundMetadata?.slug ?? process.env.AGENT_SLUG;
-        if ((!name || !slug) && interactive && !options.dryRun) {
-            const prompted = await promptForAgentName();
-            name = name ?? prompted.name;
-            slug = slug ?? prompted.slug;
-        }
-        if (!name || !slug) {
-            throw new Error("Agent name/slug unknown. Run `mcpi register`, or set AGENT_NAME and AGENT_SLUG.");
-        }
-        // The interactive prompt validates its own input; values arriving from
-        // agent.json or the environment must pass the same shape check because
-        // the slug becomes a filename under the keys directory.
-        if (!isValidSlug(slug)) {
-            throw new Error(`Invalid agent slug "${slug}": must be lowercase letters, numbers, and dashes.`);
-        }
-        name = sanitizeIdentityValue(name);
-        const metadataUrl = boundMetadata?.url
-            ? sanitizeIdentityValue(boundMetadata.url)
-            : undefined;
+    let keyMaterial;
+    let privateKeyPath;
+    let publicKeyPath;
+    if (options.agent) {
+        if (!isValidSlug(options.agent)) {
+            steps.push({
+                id: "preflight",
+                title: "Preflight checks",
+                status: "failed",
+                detail: `Invalid agent slug "${options.agent}": must be lowercase letters, numbers, and dashes.`,
+            });
+            return abort([
+                { id: "identities", title: "Resolve agent and human identity" },
+                { id: "key-material", title: "Write SSH signing key" },
+                ...laterSteps,
+            ]);
+        }
+        steps.push({ id: "preflight", title: "Preflight checks", status: "done" });
+        const slug = options.agent;
         agent = {
-            did: identity.did,
-            name,
+            did: `did:web:knowthat.ai:agents:${slug}`,
+            name: slug,
             slug,
-            url: metadataUrl && isTrustedAgentUrl(metadataUrl)
-                ? metadataUrl
-                : `https://knowthat.ai/agents/${slug}`,
+            url: `https://knowthat.ai/agents/${slug}`,
             email: `${slug}@agents.knowthat.ai`,
         };
-        // Resolve the human name and email INDEPENDENTLY, each preferring the
-        // configured git value and only falling back to gh for the field that is
-        // missing. Resolving them together would let a missing email drop a
-        // configured name (or vice versa) in favor of the GitHub profile.
-        // Reading gh here is unrelated to the key upload, so it stays available
-        // even under --skip-github (which only suppresses the upload).
-        const gitName = await getGitConfigValue("user.name", cwd);
-        const gitEmail = await getGitConfigValue("user.email", cwd);
-        let ghUser = null;
-        if ((!gitName || !gitEmail) &&
-            (await isGhInstalled()) &&
-            (await isGhAuthenticated())) {
-            ghUser = await getGhUser();
-        }
-        // Use || (not ??) so an explicitly-empty git value is treated as missing,
-        // consistent with the truthiness gate above that decides to fetch gh.
-        const resolvedName = gitName || (ghUser ? ghUser.name || ghUser.login : undefined);
-        const resolvedEmail = gitEmail || (ghUser ? githubNoreplyEmail(ghUser) : undefined);
-        if (!resolvedName || !resolvedEmail) {
-            throw new Error("Could not resolve your git identity. Set git config user.name and user.email, or authenticate gh.");
-        }
-        human = {
-            name: sanitizeIdentityValue(resolvedName),
-            email: sanitizeIdentityValue(resolvedEmail),
-        };
-        result.agent = agent;
-        result.human = human;
-        // Persist resolved metadata when the bound record was incomplete (prompted,
-        // from env, or unbound), so a later non-interactive run resolves the agent
-        // without prompting AND the did binding is written for future runs.
-        // Best-effort: a cache-write failure must not fail identity resolution.
-        if (!options.dryRun &&
-            (!boundMetadata?.name || !boundMetadata?.slug || !boundMetadata?.did)) {
-            try {
-                writeAgentMetadata(cwd, {
-                    name: agent.name,
-                    slug: agent.slug,
-                    url: agent.url,
-                    did: agent.did,
-                });
-            }
-            catch (error) {
-                result.metadataPersistWarning =
-                    error instanceof Error ? error.message : String(error);
-            }
+        try {
+            human = await resolveHumanIdentity(cwd);
+            result.agent = agent;
+            result.human = human;
+            steps.push({
+                id: "identities",
+                title: "Resolve agent and human identity",
+                status: "done",
+                detail: `agent=${agent.name} (${agent.slug}), human=${human.name} <${human.email}>`,
+            });
         }
-        steps.push({
-            id: "identities",
-            title: "Resolve agent and human identity",
-            status: "done",
-            detail: `agent=${agent.name} (${agent.slug}), human=${human.name} <${human.email}>`,
-        });
-    }
-    catch (error) {
-        steps.push({
-            id: "identities",
-            title: "Resolve agent and human identity",
-            status: "failed",
-            detail: error instanceof Error ? error.message : String(error),
-        });
-        return abort([
-            { id: "key-material", title: "Write SSH signing key" },
-            ...laterSteps,
-        ]);
-    }
-    // Step 3: key material
-    let keyMaterial;
-    // Slug was validated in the identities step; signingKeyPath re-checks and
-    // always yields a path inside the keys directory.
-    const privateKeyPath = signingKeyPath(agent.slug);
-    const publicKeyPath = `${privateKeyPath}.pub`;
-    // Only the write branch below sets this; a failure before it (e.g. a bad
-    // identity.json that fails conversion) must NOT delete pre-existing keys.
-    let startedKeyWrite = false;
-    try {
-        keyMaterial = convertEd25519ToSshKey(identity.privateKey, `mcpi:${agent.slug}`, { expectedPublicKeyBase64: identity.publicKey });
-        result.privateKeyPath = privateKeyPath;
-        result.fingerprint = keyMaterial.fingerprint;
-        // Compare BOTH files against the (now deterministic) expected material, so
-        // a corrupt/truncated private key with an intact .pub is detected and
-        // rewritten rather than left in place to fail signing forever.
-        const privUpToDate = existsSync(privateKeyPath) &&
-            readFileSync(privateKeyPath, "utf-8") === keyMaterial.privateKeyPem;
-        const pubUpToDate = existsSync(publicKeyPath) &&
-            readFileSync(publicKeyPath, "utf-8").trim() === keyMaterial.publicKeyLine;
-        if (privUpToDate && pubUpToDate) {
+        catch (error) {
+            steps.push({
+                id: "identities",
+                title: "Resolve agent and human identity",
+                status: "failed",
+                detail: error instanceof Error ? error.message : String(error),
+            });
+            return abort([
+                { id: "key-material", title: "Write SSH signing key" },
+                ...laterSteps,
+            ]);
+        }
+        // Slug was validated above; signingKeyPath re-checks and always yields a
+        // path inside the keys directory.
+        privateKeyPath = signingKeyPath(agent.slug);
+        publicKeyPath = `${privateKeyPath}.pub`;
+        if (!existsSync(privateKeyPath) || !existsSync(publicKeyPath)) {
             steps.push({
                 id: "key-material",
                 title: "Write SSH signing key",
-                status: "done",
-                detail: `Already present at ${privateKeyPath}`,
+                status: "failed",
+                detail: `No key for agent "${agent.slug}" at ${privateKeyPath}; run setup in the repo that registered it, or check the slug.`,
             });
+            return abort(laterSteps);
         }
-        else if (options.dryRun) {
+        try {
+            const publicKeyLine = readFileSync(publicKeyPath, "utf-8").trim();
+            const fingerprint = sshFingerprintFromPublicKeyLine(publicKeyLine);
+            keyMaterial = { publicKeyLine, fingerprint };
+            result.privateKeyPath = privateKeyPath;
+            result.fingerprint = fingerprint;
             steps.push({
                 id: "key-material",
                 title: "Write SSH signing key",
-                status: "would-change",
-                detail: `Would write ${privateKeyPath} and ${publicKeyPath}`,
+                status: "done",
+                detail: `Using existing key at ${privateKeyPath} (${fingerprint})`,
             });
         }
-        else {
-            mkdirSync(keysDir(), { recursive: true, mode: 0o700 });
-            startedKeyWrite = true;
-            // mode on write avoids any window where the key exists with loose
-            // permissions; the chmod covers overwrites of a pre-existing file,
-            // where the mode option is ignored.
-            writeFileSync(privateKeyPath, keyMaterial.privateKeyPem, { mode: 0o600 });
-            chmodSync(privateKeyPath, 0o600);
-            writeFileSync(publicKeyPath, keyMaterial.publicKeyLine + "\n", {
-                mode: 0o644,
-            });
-            chmodSync(publicKeyPath, 0o644);
+        catch (error) {
             steps.push({
                 id: "key-material",
                 title: "Write SSH signing key",
-                status: "done",
-                detail: `${privateKeyPath} (${keyMaterial.fingerprint})`,
+                status: "failed",
+                detail: error instanceof Error ? error.message : String(error),
             });
+            return abort(laterSteps);
         }
     }
-    catch (error) {
-        // Clean up only a key pair THIS run started writing (a half-written pair);
-        // a failure before the write (e.g. bad identity.json) must leave any
-        // pre-existing valid keys intact so signing is not silently broken.
-        if (!options.dryRun && startedKeyWrite) {
-            rmSync(privateKeyPath, { force: true });
-            rmSync(publicKeyPath, { force: true });
+    else {
+        const identityRead = readIdentityFile(cwd);
+        const identity = identityRead.status === "ok" ? identityRead.identity : null;
+        let preflightFailure = null;
+        if (identityRead.status === "corrupt") {
+            preflightFailure =
+                ".mcpi/identity.json exists but could not be parsed. Do NOT re-run `kya-os register` (it would overwrite the identity); inspect or restore the file first.";
+        }
+        else if (!identity?.privateKey || !identity?.did) {
+            preflightFailure =
+                identityRead.status === "ok"
+                    ? ".mcpi/identity.json is missing required fields (did, privateKey). Inspect or restore the file before continuing."
+                    : "No agent identity found in .mcpi/identity.json. Run `kya-os register` first, then re-run `dco setup`.";
+        }
+        else if (await isIdentityTrackedByGit(cwd)) {
+            preflightFailure =
+                ".mcpi/identity.json is tracked by git. A committed identity may have been shipped by the repo author; refusing to configure signing with it. Remove it from git history and generate your own identity with `kya-os register`.";
+        }
+        if (preflightFailure || !identity?.privateKey || !identity?.did) {
+            steps.push({
+                id: "preflight",
+                title: "Preflight checks",
+                status: "failed",
+                detail: preflightFailure ??
+                    "No agent identity found in .mcpi/identity.json. Run `kya-os register` first, then re-run `dco setup`.",
+            });
+            return abort([
+                { id: "identities", title: "Resolve agent and human identity" },
+                { id: "key-material", title: "Write SSH signing key" },
+                ...laterSteps,
+            ]);
         }
+        steps.push({ id: "preflight", title: "Preflight checks", status: "done" });
+        try {
+            const metadata = readAgentMetadata(cwd);
+            if (metadata?.did && metadata.did !== identity.did) {
+                throw new Error(`.mcpi/agent.json is for a different agent (${metadata.did}) than .mcpi/identity.json (${identity.did}). Fix or remove agent.json before continuing.`);
+            }
+            // Only trust agent.json for attribution when it is cryptographically bound
+            // to this identity (its did matches identity.json). Unbound metadata (no
+            // did, e.g. planted in an untrusted repo) is ignored so it cannot spoof the
+            // agent name/slug/url; the resolved values are then persisted with the real
+            // did, healing the binding for later runs.
+            const boundMetadata = metadata && metadata.did === identity.did ? metadata : null;
+            let name = boundMetadata?.name ?? process.env.AGENT_NAME;
+            let slug = boundMetadata?.slug ?? process.env.AGENT_SLUG;
+            if ((!name || !slug) && interactive && !options.dryRun) {
+                const prompted = await promptForAgentName();
+                name = name ?? prompted.name;
+                slug = slug ?? prompted.slug;
+            }
+            if (!name || !slug) {
+                throw new Error("Agent name/slug unknown. Run `kya-os register`, or set AGENT_NAME and AGENT_SLUG.");
+            }
+            // The interactive prompt validates its own input; values arriving from
+            // agent.json or the environment must pass the same shape check because
+            // the slug becomes a filename under the keys directory.
+            if (!isValidSlug(slug)) {
+                throw new Error(`Invalid agent slug "${slug}": must be lowercase letters, numbers, and dashes.`);
+            }
+            name = sanitizeIdentityValue(name);
+            const metadataUrl = boundMetadata?.url
+                ? sanitizeIdentityValue(boundMetadata.url)
+                : undefined;
+            agent = {
+                did: identity.did,
+                name,
+                slug,
+                url: metadataUrl && isTrustedAgentUrl(metadataUrl)
+                    ? metadataUrl
+                    : `https://knowthat.ai/agents/${slug}`,
+                email: `${slug}@agents.knowthat.ai`,
+            };
+            // Resolve the human name and email INDEPENDENTLY, each preferring the
+            // configured git value and only falling back to gh for the field that is
+            // missing. Resolving them together would let a missing email drop a
+            // configured name (or vice versa) in favor of the GitHub profile.
+            // Reading gh here is unrelated to the key upload, so it stays available
+            // even under --skip-github (which only suppresses the upload).
+            human = await resolveHumanIdentity(cwd);
+            result.agent = agent;
+            result.human = human;
+            // Persist resolved metadata when the bound record was incomplete (prompted,
+            // from env, or unbound), so a later non-interactive run resolves the agent
+            // without prompting AND the did binding is written for future runs.
+            // Best-effort: a cache-write failure must not fail identity resolution.
+            if (!options.dryRun &&
+                (!boundMetadata?.name || !boundMetadata?.slug || !boundMetadata?.did)) {
+                try {
+                    writeAgentMetadata(cwd, {
+                        name: agent.name,
+                        slug: agent.slug,
+                        url: agent.url,
+                        did: agent.did,
+                    });
+                }
+                catch (error) {
+                    result.metadataPersistWarning =
+                        error instanceof Error ? error.message : String(error);
+                }
+            }
+            steps.push({
+                id: "identities",
+                title: "Resolve agent and human identity",
+                status: "done",
+                detail: `agent=${agent.name} (${agent.slug}), human=${human.name} <${human.email}>`,
+            });
+        }
+        catch (error) {
+            steps.push({
+                id: "identities",
+                title: "Resolve agent and human identity",
+                status: "failed",
+                detail: error instanceof Error ? error.message : String(error),
+            });
+            return abort([
+                { id: "key-material", title: "Write SSH signing key" },
+                ...laterSteps,
+            ]);
+        }
+        // Slug was validated in the identities step. The conversion, idempotency,
+        // and cleanup-on-failure logic live in writeAgentSigningKey, shared with
+        // kya-os init's agent-profile stage so both write through the exact same
+        // path.
+        const keyResult = writeAgentSigningKey(agent.slug, 
+        // Narrowed property access (not the bare `identity` object) so TS sees
+        // these as `string`, matching the preflight check above.
+        { privateKey: identity.privateKey, publicKey: identity.publicKey }, { dryRun: options.dryRun });
+        privateKeyPath = keyResult.privateKeyPath;
+        if (keyResult.status === "failed") {
+            steps.push({
+                id: "key-material",
+                title: "Write SSH signing key",
+                status: "failed",
+                detail: keyResult.detail,
+            });
+            return abort(laterSteps);
+        }
+        keyMaterial = {
+            fingerprint: keyResult.fingerprint,
+            publicKeyLine: keyResult.publicKeyLine,
+        };
+        result.privateKeyPath = privateKeyPath;
+        result.fingerprint = keyResult.fingerprint;
         steps.push({
             id: "key-material",
             title: "Write SSH signing key",
-            status: "failed",
-            detail: error instanceof Error ? error.message : String(error),
+            status: keyResult.status,
+            detail: keyResult.detail,
         });
-        return abort(laterSteps);
     }
     // Step 4: GitHub upload
     if (options.skipGithub) {
@@ -388,7 +456,7 @@ export async function runDcoSetup(options = {}) {
                     id: "github-upload",
                     title: "Upload signing key to GitHub",
                     status: "action-required",
-                    detail: "GitHub CLI not found. Install from https://cli.github.com, run `gh auth login`, then re-run `mcpi dco setup`.",
+                    detail: "GitHub CLI not found. Install from https://cli.github.com, run `gh auth login`, then re-run `dco setup`.",
                 });
             }
             else if (!(await isGhAuthenticated())) {
@@ -396,7 +464,7 @@ export async function runDcoSetup(options = {}) {
                     id: "github-upload",
                     title: "Upload signing key to GitHub",
                     status: "action-required",
-                    detail: "Not authenticated. Run `gh auth login`, then re-run `mcpi dco setup`.",
+                    detail: "Not authenticated. Run `gh auth login`, then re-run `dco setup`.",
                 });
             }
             else {
@@ -438,7 +506,7 @@ export async function runDcoSetup(options = {}) {
                         id: "github-upload",
                         title: "Upload signing key to GitHub",
                         status: "action-required",
-                        detail: "Upload declined. Re-run `mcpi dco setup` when you are ready to upload the key.",
+                        detail: "Upload declined. Re-run `dco setup` when you are ready to upload the key.",
                     });
                 }
                 else {
@@ -458,7 +526,7 @@ export async function runDcoSetup(options = {}) {
                     id: "github-upload",
                     title: "Upload signing key to GitHub",
                     status: "action-required",
-                    detail: `${error.message} Then re-run \`mcpi dco setup\`.`,
+                    detail: `${error.message} Then re-run \`dco setup\`.`,
                 });
             }
             else if (error instanceof GhNotInstalledError) {
@@ -626,12 +694,7 @@ export async function runDcoSetup(options = {}) {
     else {
         try {
             const block = buildAttributionBlock({
-                agentName: agent.name,
-                agentUrl: agent.url,
                 includeTrailerInstructions: hookFallback,
-                humanName: human.name,
-                humanEmail: human.email,
-                agentEmail: agent.email,
             });
             const md = upsertClaudeMdBlock(cwd, block, { dryRun: options.dryRun });
             const settings = updateClaudeSettings(cwd, { dryRun: options.dryRun });
@@ -680,7 +743,9 @@ export async function runDcoSetup(options = {}) {
                 "Trailer instructions would be added to the CLAUDE.md attribution block instead.";
         }
         else {
-            outcome = `Trailers were NOT added to CLAUDE.md (${options.skipClaude ? "--skip-claude" : "the Claude Code step did not complete"}); add Signed-off-by / Co-authored-by manually or re-run without --skip-claude.`;
+            outcome = `Trailers were NOT added to CLAUDE.md (${options.skipClaude
+                ? "--skip-claude"
+                : "the Claude Code step did not complete"}); add Signed-off-by / Co-authored-by manually or re-run without --skip-claude.`;
         }
         if (trailerStep) {
             trailerStep.detail = `${hookFallbackDetail} ${outcome}`;
@@ -701,7 +766,7 @@ export async function runDcoSetup(options = {}) {
         const verifyDir = mkdtempSync(join(tmpdir(), "mcpi-dco-verify-"));
         const payloadPath = join(verifyDir, "payload");
         try {
-            writeFileSync(payloadPath, "mcpi dco verification payload\n");
+            writeFileSync(payloadPath, "dco verification payload\n");
             await execFileAsync("ssh-keygen", [
                 "-Y",
                 "sign",