@groundnuty/macf 0.2.0-rc.0

package/dist/cli/commands/certs.js

@@ -0,0 +1,233 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readAgentConfig, agentCertPath, agentKeyPath, caCertPath as caCertPathFor, caKeyPath as caKeyPathFor, caDir, tokenSourceFromConfig, } from '../config.js';
+import { createCA, backupCAKey, recoverCAKey, loadCA } from '@groundnuty/macf-core';
+import { generateAgentCert, generateClientCert } from '@groundnuty/macf-core';
+import { createClientFromConfig } from '../registry-helper.js';
+import { createRegistryFromConfig } from '@groundnuty/macf-core';
+import { generateToken } from '@groundnuty/macf-core';
+import { promptPassword, PromptCancelled } from '../prompt.js';
+import { toVariableSegment } from '@groundnuty/macf-core';
+const ROUTING_CLIENT_CN = 'routing-action';
+const DEFAULT_VALIDITY_DAYS = 365;
+const VALIDITY_WARN_DAYS = 730;
+async function promptPassphrase(message) {
+    try {
+        return await promptPassword({ message });
+    }
+    catch (err) {
+        if (err instanceof PromptCancelled) {
+            console.error('\nCancelled.');
+            process.exit(130); // 128 + SIGINT
+        }
+        throw err;
+    }
+}
+function getVariablesClient(config, token) {
+    if (!config)
+        throw new Error('No macf-agent.json found. Run `macf init` first.');
+    return createClientFromConfig(config.registry, token);
+}
+/**
+ * macf certs init: create CA, upload cert + encrypted key to registry
+ */
+export async function certsInit(projectDir) {
+    const config = readAgentConfig(projectDir);
+    if (!config) {
+        console.error('No macf-agent.json found. Run `macf init` first.');
+        process.exitCode = 1;
+        return;
+    }
+    const token = await generateToken(tokenSourceFromConfig(projectDir, config));
+    const client = getVariablesClient(config, token);
+    // Per-project CA paths. mkdir with 0o700 — CA key is the most sensitive secret.
+    const projectCaDir = caDir(config.project);
+    mkdirSync(projectCaDir, { recursive: true, mode: 0o700 });
+    const caCertP = caCertPathFor(config.project);
+    const caKeyP = caKeyPathFor(config.project);
+    console.log(`Creating CA for project "${config.project}"...`);
+    const ca = await createCA({
+        project: config.project,
+        certPath: caCertP,
+        keyPath: caKeyP,
+        client,
+    });
+    console.log(`  CA cert: ${caCertP}`);
+    console.log(`  CA key:  ${caKeyP}`);
+    console.log(`  CA cert uploaded to registry as ${toVariableSegment(config.project)}_CA_CERT`);
+    // Encrypted backup
+    const passphrase = await promptPassphrase('Enter passphrase for CA key backup: ');
+    if (!passphrase) {
+        console.warn('No passphrase provided — skipping encrypted backup.');
+        return;
+    }
+    await backupCAKey({
+        project: config.project,
+        keyPem: ca.keyPem,
+        passphrase,
+        client,
+    });
+    console.log(`  Encrypted CA key backed up to registry as ${toVariableSegment(config.project)}_CA_KEY_ENCRYPTED`);
+    console.log('\nCA initialization complete.');
+}
+/**
+ * macf certs recover: download and decrypt CA key from registry
+ */
+export async function certsRecover(projectDir) {
+    const config = readAgentConfig(projectDir);
+    if (!config) {
+        console.error('No macf-agent.json found. Run `macf init` first.');
+        process.exitCode = 1;
+        return;
+    }
+    const token = await generateToken(tokenSourceFromConfig(projectDir, config));
+    const client = getVariablesClient(config, token);
+    const passphrase = await promptPassphrase('Enter passphrase for CA key recovery: ');
+    if (!passphrase) {
+        console.error('Passphrase is required for recovery.');
+        process.exitCode = 1;
+        return;
+    }
+    // Per-project CA paths. mkdir with 0o700.
+    mkdirSync(caDir(config.project), { recursive: true, mode: 0o700 });
+    const caKeyP = caKeyPathFor(config.project);
+    console.log('Recovering CA key from registry...');
+    await recoverCAKey({
+        project: config.project,
+        passphrase,
+        keyPath: caKeyP,
+        client,
+    });
+    console.log(`  CA key recovered to: ${caKeyP}`);
+    console.log('Recovery complete.');
+}
+/**
+ * macf certs rotate: regenerate agent cert with existing CA
+ */
+export async function certsRotate(projectDir) {
+    const config = readAgentConfig(projectDir);
+    if (!config) {
+        console.error('No macf-agent.json found. Run `macf init` first.');
+        process.exitCode = 1;
+        return;
+    }
+    const caCertP = caCertPathFor(config.project);
+    const caKeyP = caKeyPathFor(config.project);
+    if (!existsSync(caCertP) || !existsSync(caKeyP)) {
+        console.error('CA cert or key not found. Run `macf certs init` or `macf certs recover` first.');
+        process.exitCode = 1;
+        return;
+    }
+    const ca = loadCA(caCertP, caKeyP);
+    const certP = agentCertPath(projectDir);
+    const keyP = agentKeyPath(projectDir);
+    console.log(`Rotating certificate for "${config.agent_name}"...`);
+    await generateAgentCert({
+        agentName: config.agent_name,
+        caCertPem: ca.certPem,
+        caKeyPem: ca.keyPem,
+        // Flow the advertised host into the cert SAN so TLS hostname
+        // verification succeeds when an off-box consumer (routing Action,
+        // sibling agent) connects over the network. macf#178 Gap 3.
+        ...(config.advertise_host !== undefined ? { advertiseHost: config.advertise_host } : {}),
+        certPath: certP,
+        keyPath: keyP,
+    });
+    console.log(`  Cert: ${certP}`);
+    console.log(`  Key:  ${keyP}`);
+    console.log('Rotation complete.');
+}
+/**
+ * macf certs issue-routing-client: mint a CA-signed client cert with
+ * CN=routing-action for use by the macf-actions routing workflow
+ * (mTLS variant, macf-actions#8). The routing Action presents this
+ * cert when POSTing to each agent's /notify endpoint.
+ *
+ * Requires the CA key on disk — this command is local-only, never
+ * driven from the registry-encrypted backup. The resulting cert/key
+ * is meant to be pasted into the consumer repo's GHA secrets; the
+ * operator is expected to handle the paste securely (not commit it).
+ *
+ * If --out-dir is omitted, both PEMs are printed to stdout along with
+ * single-line base64 blobs for easy GHA-secret paste. If --out-dir
+ * is provided, files are written to disk at 0o600 / 0o644.
+ */
+export async function issueRoutingClient(projectDir, opts = {}) {
+    const config = readAgentConfig(projectDir);
+    if (!config) {
+        console.error('No macf-agent.json found. Run `macf init` first.');
+        process.exitCode = 1;
+        return;
+    }
+    const validityDays = opts.validityDays ?? DEFAULT_VALIDITY_DAYS;
+    if (!Number.isInteger(validityDays) || validityDays < 1) {
+        console.error(`--validity-days must be a positive integer (got "${opts.validityDays}")`);
+        process.exitCode = 1;
+        return;
+    }
+    if (validityDays > VALIDITY_WARN_DAYS) {
+        console.warn(`Warning: validity of ${validityDays} days exceeds ${VALIDITY_WARN_DAYS} days. ` +
+            `Long-lived client certs increase blast radius if the key leaks; ` +
+            `consider a shorter rotation cadence.`);
+    }
+    const caCertP = caCertPathFor(config.project);
+    const caKeyP = caKeyPathFor(config.project);
+    if (!existsSync(caCertP) || !existsSync(caKeyP)) {
+        console.error('CA cert or key not found on disk. This command requires a local CA key — ' +
+            'run `macf certs init` (first time) or `macf certs recover` (if CA lives in registry only).');
+        process.exitCode = 1;
+        return;
+    }
+    const ca = loadCA(caCertP, caKeyP);
+    // Collision guard: refuse if an existing agent is registered under
+    // the routing-client CN. Prevents accidental overlap with a real
+    // agent named `routing-action`.
+    const token = await generateToken(tokenSourceFromConfig(projectDir, config));
+    const registry = createRegistryFromConfig(config.registry, config.project, token);
+    const existing = await registry.get(ROUTING_CLIENT_CN);
+    if (existing !== null) {
+        console.error(`An agent named "${ROUTING_CLIENT_CN}" is already registered. ` +
+            `Rename or remove that agent before issuing the routing-client cert, or ` +
+            `coordinate CN separation via a follow-up issue.`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`Issuing routing-client cert for project "${config.project}"...`);
+    console.log(`  CN:             ${ROUTING_CLIENT_CN}`);
+    console.log(`  Validity:       ${validityDays} days`);
+    const result = await generateClientCert({
+        commonName: ROUTING_CLIENT_CN,
+        validityDays,
+        caCertPem: ca.certPem,
+        caKeyPem: ca.keyPem,
+    });
+    if (opts.outDir) {
+        mkdirSync(opts.outDir, { recursive: true, mode: 0o700 });
+        const certOut = join(opts.outDir, 'routing-action-cert.pem');
+        const keyOut = join(opts.outDir, 'routing-action-key.pem');
+        writeFileSync(certOut, result.certPem, { mode: 0o644 });
+        writeFileSync(keyOut, result.keyPem, { mode: 0o600 });
+        console.log(`  Cert written:   ${certOut}`);
+        console.log(`  Key written:    ${keyOut}`);
+        console.log('');
+        console.log('GHA-secret paste format (for your consumer repo):');
+        console.log('  ROUTING_CLIENT_CERT = ' + Buffer.from(result.certPem).toString('base64'));
+        console.log('  ROUTING_CLIENT_KEY  = ' + Buffer.from(result.keyPem).toString('base64'));
+    }
+    else {
+        console.log('');
+        console.log('─── routing-action cert (PEM) ───');
+        console.log(result.certPem);
+        console.log('─── routing-action key (PEM, KEEP SECRET) ───');
+        console.log(result.keyPem);
+        console.log('─── GHA-secret paste format ───');
+        console.log('ROUTING_CLIENT_CERT = ' + Buffer.from(result.certPem).toString('base64'));
+        console.log('ROUTING_CLIENT_KEY  = ' + Buffer.from(result.keyPem).toString('base64'));
+    }
+    console.log('');
+    console.log('Next steps (see macf-actions#8):');
+    console.log('  1. Paste ROUTING_CLIENT_CERT and ROUTING_CLIENT_KEY into your consumer repo\'s GHA secrets');
+    console.log('  2. Upgrade the caller workflow to macf-actions @v2.x when available');
+    console.log('  3. Remove the AGENT_SSH_KEY secret once mTLS transport is proven');
+}
+//# sourceMappingURL=certs.js.map

package/dist/cli/commands/certs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"certs.js","sourceRoot":"","sources":["../../../src/cli/commands/certs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EACL,eAAe,EAAE,aAAa,EAAE,YAAY,EAC5C,UAAU,IAAI,aAAa,EAAE,SAAS,IAAI,YAAY,EAAE,KAAK,EAC7D,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D,MAAM,iBAAiB,GAAG,gBAAgB,CAAC;AAC3C,MAAM,qBAAqB,GAAG,GAAG,CAAC;AAClC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B,KAAK,UAAU,gBAAgB,CAAC,OAAe;IAC7C,IAAI,CAAC;QACH,OAAO,MAAM,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;IAC3C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,eAAe,EAAE,CAAC;YACnC,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;YAC9B,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,eAAe;QACpC,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,MAA0C,EAAE,KAAa;IACnF,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACjF,OAAO,sBAAsB,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AACxD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,UAAkB;IAChD,MAAM,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAC;QAClE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,qBAAqB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7E,MAAM,MAAM,GAAG,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAEjD,gFAAgF;IAChF,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC3C,SAAS,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1D,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAE5C,OAAO,CAAC,GAAG,CAAC,4BAA4B,MAAM,CAAC,OAAO,MAAM,CAAC,CAAC;IAE9D,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC;QACxB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,QAAQ,EAAE,OAAO;QACjB,OAAO,EAAE,MAAM;QACf,MAAM;KACP,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,cAAc,OAAO,EAAE,CAAC,CAAC;IACrC,OAAO,CAAC,GAAG,CAAC,cAAc,MAAM,EAAE,CAAC,CAAC;IACpC,OAAO,CAAC,GAAG,CAAC,qCAAqC,iBAAiB,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAE9F,mBAAmB;IACnB,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,sCAAsC,CAAC,CAAC;IAClF,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,CAAC,IAAI,CAAC,qDAAqD,CAAC,CAAC;QACpE,OAAO;IACT,CAAC;IAED,MAAM,WAAW,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,MAAM,EAAE,EAAE,CAAC,MAAM;QACjB,UAAU;QACV,MAAM;KACP,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,+CAA+C,iBAAiB,CAAC,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACjH,OAAO,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;AAC/C,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,UAAkB;IACnD,MAAM,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAC;QAClE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,qBAAqB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7E,MAAM,MAAM,GAAG,kBAAkB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAEjD,MAAM,UAAU,GAAG,MAAM,gBAAgB,CAAC,wCAAwC,CAAC,CAAC;IACpF,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,CAAC,KAAK,CAAC,sCAAsC,CAAC,CAAC;QACtD,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,0CAA0C;IAC1C,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACnE,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAE5C,OAAO,CAAC,GAAG,CAAC,oCAAoC,CAAC,CAAC;IAElD,MAAM,YAAY,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,UAAU;QACV,OAAO,EAAE,MAAM;QACf,MAAM;KACP,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,0BAA0B,MAAM,EAAE,CAAC,CAAC;IAChD,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,UAAkB;IAClD,MAAM,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAC;QAClE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAChD,OAAO,CAAC,KAAK,CAAC,gFAAgF,CAAC,CAAC;QAChG,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAEnC,MAAM,KAAK,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;IACxC,MAAM,IAAI,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;IAEtC,OAAO,CAAC,GAAG,CAAC,6BAA6B,MAAM,CAAC,UAAU,MAAM,CAAC,CAAC;IAElE,MAAM,iBAAiB,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC,UAAU;QAC5B,SAAS,EAAE,EAAE,CAAC,OAAO;QACrB,QAAQ,EAAE,EAAE,CAAC,MAAM;QACnB,6DAA6D;QAC7D,kEAAkE;QAClE,4DAA4D;QAC5D,GAAG,CAAC,MAAM,CAAC,cAAc,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,MAAM,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxF,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,IAAI;KACd,CAAC,CAAC;IAEH,OAAO,CAAC,GAAG,CAAC,WAAW,KAAK,EAAE,CAAC,CAAC;IAChC,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;IAC/B,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;AACpC,CAAC;AAOD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,UAAkB,EAClB,OAAkC,EAAE;IAEpC,MAAM,MAAM,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAC;QAClE,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,qBAAqB,CAAC;IAChE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACxD,OAAO,CAAC,KAAK,CAAC,oDAAoD,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC;QACzF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,IAAI,YAAY,GAAG,kBAAkB,EAAE,CAAC;QACtC,OAAO,CAAC,IAAI,CACV,wBAAwB,YAAY,iBAAiB,kBAAkB,SAAS;YAChF,kEAAkE;YAClE,sCAAsC,CACvC,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAChD,OAAO,CAAC,KAAK,CACX,2EAA2E;YAC3E,4FAA4F,CAC7F,CAAC;QACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IACD,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAEnC,mEAAmE;IACnE,iEAAiE;IACjE,gCAAgC;IAChC,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,qBAAqB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7E,MAAM,QAAQ,GAAG,wBAAwB,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAClF,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACvD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,CAAC,KAAK,CACX,mBAAmB,iBAAiB,2BAA2B;YAC/D,yEAAyE;YACzE,iDAAiD,CAClD,CAAC;QACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,4CAA4C,MAAM,CAAC,OAAO,MAAM,CAAC,CAAC;IAC9E,OAAO,CAAC,GAAG,CAAC,qBAAqB,iBAAiB,EAAE,CAAC,CAAC;IACtD,OAAO,CAAC,GAAG,CAAC,qBAAqB,YAAY,OAAO,CAAC,CAAC;IAEtD,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC;QACtC,UAAU,EAAE,iBAAiB;QAC7B,YAAY;QACZ,SAAS,EAAE,EAAE,CAAC,OAAO;QACrB,QAAQ,EAAE,EAAE,CAAC,MAAM;KACpB,CAAC,CAAC;IAEH,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACzD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;QAC7D,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;QAC3D,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACxD,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACtD,OAAO,CAAC,GAAG,CAAC,qBAAqB,OAAO,EAAE,CAAC,CAAC;QAC5C,OAAO,CAAC,GAAG,CAAC,qBAAqB,MAAM,EAAE,CAAC,CAAC;QAC3C,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,mDAAmD,CAAC,CAAC;QACjE,OAAO,CAAC,GAAG,CAAC,0BAA0B,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;QACzF,OAAO,CAAC,GAAG,CAAC,0BAA0B,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC1F,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChB,OAAO,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;QACjD,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5B,OAAO,CAAC,GAAG,CAAC,+CAA+C,CAAC,CAAC;QAC7D,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC3B,OAAO,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;QAC/C,OAAO,CAAC,GAAG,CAAC,wBAAwB,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;QACvF,OAAO,CAAC,GAAG,CAAC,wBAAwB,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxF,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChB,OAAO,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;IAChD,OAAO,CAAC,GAAG,CAAC,8FAA8F,CAAC,CAAC;IAC5G,OAAO,CAAC,GAAG,CAAC,uEAAuE,CAAC,CAAC;IACrF,OAAO,CAAC,GAAG,CAAC,oEAAoE,CAAC,CAAC;AACpF,CAAC"}

package/dist/cli/commands/doctor.d.ts

@@ -0,0 +1,91 @@
+/**
+ * One required permission entry from DR-019.
+ */
+export interface RequiredPermission {
+    readonly name: string;
+    readonly level: 'read' | 'write';
+    readonly why: string;
+}
+/**
+ * DR-019 permission doctrine. Keep in sync with
+ * design/decisions/DR-019-app-permissions.md and
+ * templates/macf-app-manifest.json.
+ *
+ * Names here are GitHub's CANONICAL API names (as returned by
+ * `GET /app/installations/:id` in the `permissions` field), which
+ * differ from the App settings UI labels for some entries — notably
+ * Variables → `actions_variables`. We use canonical names everywhere
+ * to avoid false negatives (an installation with `actions_variables`
+ * would be flagged as missing `variables` if we used the UI label).
+ */
+export declare const MACF_REQUIRED_PERMISSIONS: readonly RequiredPermission[];
+export interface DoctorFinding {
+    /** Missing: the token has no entry at all for this permission. */
+    readonly missing: readonly RequiredPermission[];
+    /** Present but at a lower level than required (`read` where we want `write`). */
+    readonly insufficient: readonly {
+        readonly required: RequiredPermission;
+        readonly actual: string;
+    }[];
+}
+/**
+ * Pure comparison: given the actual permission map from a token response,
+ * return what's missing or insufficient against MACF_REQUIRED_PERMISSIONS.
+ */
+export declare function diffPermissions(actual: Readonly<Record<string, string>>): DoctorFinding;
+/**
+ * Symbol + label for the output table. Exported so tests can assert on it.
+ */
+export declare function formatPermissionRow(req: RequiredPermission, actual: string | undefined): string;
+/**
+ * Result of the sandbox-filesystem check (macf#202). PASS iff the
+ * workspace's `.claude/settings.json` has `/proc/self/fd` in
+ * `sandbox.filesystem.allowRead`. FAIL if absent, or if reading the
+ * file threw (malformed JSON → we don't silently report PASS).
+ *
+ * Note: an earlier CLI version wrote `/proc/self/fd/**` (glob) which
+ * the sandbox treated as a literal — silently didn't match; macf#208
+ * corrected the pattern to bare `/proc/self/fd`.
+ */
+export interface SandboxFdCheck {
+    readonly status: 'PASS' | 'FAIL';
+    /** Human-readable diagnostic — e.g. JSON parse error message. Empty on PASS. */
+    readonly detail: string;
+}
+/**
+ * Pure check: does this workspace's `.claude/settings.json` contain
+ * the `/proc/self/fd` sandbox pattern? See macf#200 for why this
+ * matters (without it every Bash tool call fails on the harness fd),
+ * and macf#208 for why the pattern is bare (not a glob).
+ *
+ * Uses `getSandboxAllowRead` from `settings-writer.ts` so the JSON-
+ * read + deep-narrow logic lives in one place. Malformed JSON
+ * surfaces as a FAIL with the parse error in `detail` — operator
+ * still needs to see what broke.
+ */
+export declare function checkSandboxFdAllowRead(workspaceDir: string): SandboxFdCheck;
+/**
+ * Format a non-leaking error message when `gh token generate --jwt` returns
+ * output that doesn't look like a JWT. Shows only the first 6 characters
+ * plus length — enough to distinguish empty / error-message / binary-garbage
+ * / genuinely-wrong-prefix, without exposing credential material if the
+ * branch fires on a genuinely-valid JWT due to a locale/whitespace/plugin
+ * edge case. See #86. Exported for unit tests.
+ */
+export declare function describeNonJwtOutput(jwt: string): string;
+/**
+ * Fetch the installation's GRANTED permissions by querying
+ * `GET /app/installations/:id` with an App JWT. We do NOT use the
+ * install-token response's `permissions` field here — it doesn't
+ * surface all granted permissions (verified empirically: an App with
+ * `actions_variables: write` may report an incomplete set in the
+ * install-token response but the full set via JWT query). See
+ * discussion on issue #74 for the evidence.
+ */
+export declare function fetchInstallationPermissions(appId: string, installId: string, keyPath: string): Promise<Record<string, string>>;
+/**
+ * Main entry for `macf doctor`. Returns the shell exit code: 0 if all
+ * required permissions are present, 1 if any are missing or insufficient.
+ */
+export declare function runDoctor(projectDir: string): Promise<number>;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/cli/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"AAoBA;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,kBAAkB,EAQlE,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAChD,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,SAAS;QAC9B,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;QACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,EAAE,CAAC;CACL;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,aAAa,CAgBvF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,kBAAkB,EACvB,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,MAAM,CAWR;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,gFAAgF;IAChF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,cAAc,CAc5E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMxD;AAED;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CA6CjC;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAsEnE"}

package/dist/cli/commands/doctor.js

@@ -0,0 +1,235 @@
+/**
+ * macf doctor — verify the workspace's bot token satisfies the MACF App
+ * permission doctrine (DR-019).
+ *
+ * GitHub's installation-token response body includes the permissions
+ * granted to the installation, so we don't need to probe individual
+ * endpoints: one `gh token generate` (without --token-only) gives us
+ * the full permission map. Compare against the required set; print a
+ * formatted checklist; exit 0 if satisfied, 1 if not.
+ *
+ * This is the automated counterpart to DR-019's manual verification
+ * section. Run at onboarding time or whenever routing breaks for a
+ * reason that smells like a missing permission (401 on a specific
+ * endpoint while others work — see coordination.md Token & Git Hygiene
+ * for the attribution-trap class this prevents).
+ */
+import { execFileSync } from 'node:child_process';
+import { readAgentConfig, tokenSourceFromConfig } from '../config.js';
+import { getSandboxAllowRead, SANDBOX_FD_READ_PATTERN } from '../settings-writer.js';
+/**
+ * DR-019 permission doctrine. Keep in sync with
+ * design/decisions/DR-019-app-permissions.md and
+ * templates/macf-app-manifest.json.
+ *
+ * Names here are GitHub's CANONICAL API names (as returned by
+ * `GET /app/installations/:id` in the `permissions` field), which
+ * differ from the App settings UI labels for some entries — notably
+ * Variables → `actions_variables`. We use canonical names everywhere
+ * to avoid false negatives (an installation with `actions_variables`
+ * would be flagged as missing `variables` if we used the UI label).
+ */
+export const MACF_REQUIRED_PERMISSIONS = [
+    { name: 'metadata', level: 'read', why: 'Mandatory by GitHub — cannot be omitted' },
+    { name: 'contents', level: 'write', why: 'Push commits, PRs to feature branches' },
+    { name: 'issues', level: 'write', why: 'Comment, label, edit issues — primary coordination surface' },
+    { name: 'pull_requests', level: 'write', why: 'Create/merge PRs, submit reviews' },
+    { name: 'actions_variables', level: 'write', why: 'Agent registry lives in repo/org/user variables (UI label: Variables)' },
+    { name: 'workflows', level: 'write', why: 'macf repo-init writes .github/workflows/' },
+    { name: 'actions', level: 'read', why: 'gh run list / view --log-failed for self-debug' },
+];
+/**
+ * Pure comparison: given the actual permission map from a token response,
+ * return what's missing or insufficient against MACF_REQUIRED_PERMISSIONS.
+ */
+export function diffPermissions(actual) {
+    const missing = [];
+    const insufficient = [];
+    for (const req of MACF_REQUIRED_PERMISSIONS) {
+        const actualLevel = actual[req.name];
+        if (!actualLevel) {
+            missing.push(req);
+            continue;
+        }
+        // 'write' required but only 'read' granted is a gap; the reverse
+        // ('read' required with 'write' granted) is fine — user exceeds.
+        if (req.level === 'write' && actualLevel === 'read') {
+            insufficient.push({ required: req, actual: actualLevel });
+        }
+    }
+    return { missing, insufficient };
+}
+/**
+ * Symbol + label for the output table. Exported so tests can assert on it.
+ */
+export function formatPermissionRow(req, actual) {
+    const name = req.name.padEnd(15);
+    const required = `${req.level}`.padEnd(6);
+    if (!actual) {
+        return `✗ ${name} required=${required} actual=MISSING    — ${req.why}`;
+    }
+    const actualStr = actual.padEnd(6);
+    if (req.level === 'write' && actual === 'read') {
+        return `⚠ ${name} required=${required} actual=${actualStr} — need write, have read`;
+    }
+    return `✓ ${name} required=${required} actual=${actualStr}`;
+}
+/**
+ * Pure check: does this workspace's `.claude/settings.json` contain
+ * the `/proc/self/fd` sandbox pattern? See macf#200 for why this
+ * matters (without it every Bash tool call fails on the harness fd),
+ * and macf#208 for why the pattern is bare (not a glob).
+ *
+ * Uses `getSandboxAllowRead` from `settings-writer.ts` so the JSON-
+ * read + deep-narrow logic lives in one place. Malformed JSON
+ * surfaces as a FAIL with the parse error in `detail` — operator
+ * still needs to see what broke.
+ */
+export function checkSandboxFdAllowRead(workspaceDir) {
+    let allowRead;
+    try {
+        allowRead = getSandboxAllowRead(workspaceDir);
+    }
+    catch (err) {
+        return { status: 'FAIL', detail: err instanceof Error ? err.message : String(err) };
+    }
+    if (allowRead.includes(SANDBOX_FD_READ_PATTERN)) {
+        return { status: 'PASS', detail: '' };
+    }
+    return {
+        status: 'FAIL',
+        detail: `allowRead does not contain ${SANDBOX_FD_READ_PATTERN} — run \`macf update\` to refresh`,
+    };
+}
+/**
+ * Format a non-leaking error message when `gh token generate --jwt` returns
+ * output that doesn't look like a JWT. Shows only the first 6 characters
+ * plus length — enough to distinguish empty / error-message / binary-garbage
+ * / genuinely-wrong-prefix, without exposing credential material if the
+ * branch fires on a genuinely-valid JWT due to a locale/whitespace/plugin
+ * edge case. See #86. Exported for unit tests.
+ */
+export function describeNonJwtOutput(jwt) {
+    const safePrefix = jwt.length > 0 ? jwt.slice(0, 6) : '(empty)';
+    return (`gh token generate --jwt returned unexpected output ` +
+        `(prefix='${safePrefix}', length=${jwt.length})`);
+}
+/**
+ * Fetch the installation's GRANTED permissions by querying
+ * `GET /app/installations/:id` with an App JWT. We do NOT use the
+ * install-token response's `permissions` field here — it doesn't
+ * surface all granted permissions (verified empirically: an App with
+ * `actions_variables: write` may report an incomplete set in the
+ * install-token response but the full set via JWT query). See
+ * discussion on issue #74 for the evidence.
+ */
+export async function fetchInstallationPermissions(appId, installId, keyPath) {
+    // Get a JWT signed with the App's private key. `gh token generate --jwt`
+    // does the RS256 signing for us, avoiding a Node crypto reimplementation.
+    let jwt;
+    try {
+        jwt = execFileSync('gh', [
+            'token', 'generate',
+            '--app-id', appId,
+            '--key', keyPath,
+            '--jwt',
+            '--token-only',
+        ], {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`gh token generate --jwt failed: ${msg}. ` +
+            `See coordination.md Token & Git Hygiene for diagnostics.`, { cause: err });
+    }
+    if (!jwt.startsWith('eyJ')) {
+        throw new Error(describeNonJwtOutput(jwt));
+    }
+    const response = await fetch(`https://api.github.com/app/installations/${installId}`, {
+        headers: {
+            Authorization: `Bearer ${jwt}`,
+            Accept: 'application/vnd.github+json',
+            'X-GitHub-Api-Version': '2022-11-28',
+        },
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => '<no body>');
+        throw new Error(`GET /app/installations/${installId} returned ${response.status}: ${body.slice(0, 200)}`);
+    }
+    const parsed = (await response.json());
+    if (!parsed.permissions || typeof parsed.permissions !== 'object') {
+        throw new Error('/app/installations/:id response missing `permissions` field');
+    }
+    return parsed.permissions;
+}
+/**
+ * Main entry for `macf doctor`. Returns the shell exit code: 0 if all
+ * required permissions are present, 1 if any are missing or insufficient.
+ */
+export async function runDoctor(projectDir) {
+    const config = readAgentConfig(projectDir);
+    if (!config) {
+        console.error('No macf-agent.json found. Run `macf init` first.');
+        return 1;
+    }
+    const source = tokenSourceFromConfig(projectDir, config);
+    let permissions;
+    try {
+        permissions = await fetchInstallationPermissions(source.appId, source.installId, source.keyPath);
+    }
+    catch (err) {
+        console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+    const finding = diffPermissions(permissions);
+    console.log('MACF doctor report');
+    console.log('──────────────────────────────────────────────────────────────');
+    for (const req of MACF_REQUIRED_PERMISSIONS) {
+        console.log(`  ${formatPermissionRow(req, permissions[req.name])}`);
+    }
+    console.log('');
+    const totalRequired = MACF_REQUIRED_PERMISSIONS.length;
+    const satisfied = totalRequired - finding.missing.length - finding.insufficient.length;
+    const status = finding.missing.length === 0 && finding.insufficient.length === 0
+        ? '✓ all required permissions present'
+        : `✗ ${finding.missing.length + finding.insufficient.length} of ${totalRequired} required permissions missing or insufficient`;
+    console.log(`  ${status} (${satisfied}/${totalRequired} satisfied)`);
+    if (finding.missing.length > 0) {
+        console.log('');
+        console.log('Missing:');
+        for (const req of finding.missing) {
+            console.log(`  - ${req.name}: ${req.level} — ${req.why}`);
+        }
+    }
+    if (finding.insufficient.length > 0) {
+        console.log('');
+        console.log('Insufficient:');
+        for (const { required, actual } of finding.insufficient) {
+            console.log(`  - ${required.name}: have ${actual}, need ${required.level} — ${required.why}`);
+        }
+    }
+    if (finding.missing.length > 0 || finding.insufficient.length > 0) {
+        console.log('');
+        console.log('See design/decisions/DR-019-app-permissions.md for the full doctrine,');
+        console.log('and GitHub → Settings → Developer settings → GitHub Apps → <your App> → Permissions');
+        console.log('to update the App. Users with the App installed must accept the new permissions.');
+    }
+    console.log('');
+    console.log('Sandbox filesystem (macf#200)');
+    console.log('──────────────────────────────────────────────────────────────');
+    const sandboxCheck = checkSandboxFdAllowRead(projectDir);
+    if (sandboxCheck.status === 'PASS') {
+        console.log(`  ✓ sandbox.filesystem.allowRead contains ${SANDBOX_FD_READ_PATTERN}  [PASS]`);
+    }
+    else {
+        console.log(`  ✗ sandbox.filesystem.allowRead missing ${SANDBOX_FD_READ_PATTERN}   [FAIL — run \`macf update\` to fix]`);
+        if (sandboxCheck.detail)
+            console.log(`    ${sandboxCheck.detail}`);
+    }
+    const permissionsFailed = finding.missing.length > 0 || finding.insufficient.length > 0;
+    const sandboxFailed = sandboxCheck.status === 'FAIL';
+    return permissionsFailed || sandboxFailed ? 1 : 0;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/cli/commands/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,37 @@
+export interface InitOptions {
+    readonly project: string;
+    readonly role: string;
+    readonly name?: string;
+    readonly type?: string;
+    readonly appId: string;
+    readonly installId: string;
+    readonly keyPath: string;
+    readonly registryType?: string;
+    readonly registryOrg?: string;
+    readonly registryUser?: string;
+    readonly registryRepo?: string;
+    /**
+     * Host the channel server advertises to the registry + includes in
+     * its mTLS cert SAN. When unset, launcher falls back to 127.0.0.1
+     * (matches plugin default). Operators routing to agents over the
+     * network (Tailscale IP / DNS) must set this. See macf#178.
+     */
+    readonly advertiseHost?: string;
+    /**
+     * Tmux session + (optional) window for the on-notify wake path
+     * (macf#185). When set, the channel server's onNotify shells out
+     * to tmux-send-to-claude.sh to inject the notification prompt
+     * into a running Claude TUI. When unset, the server auto-detects
+     * from $TMUX if launched inside a tmux pane.
+     */
+    readonly tmuxSession?: string;
+    readonly tmuxWindow?: string;
+    readonly cliVersion?: string;
+    readonly pluginVersion?: string;
+    readonly actionsVersion?: string;
+}
+/**
+ * Set up a project directory for an agent.
+ */
+export declare function initAgent(projectDir: string, opts: InitOptions): Promise<void>;
+//# sourceMappingURL=init.d.ts.map

package/dist/cli/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AA4GD;;GAEG;AACH,wBAAsB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA0JpF"}