@groundnuty/macf 0.2.0-rc.0

package/dist/.build-info.json

@@ -0,0 +1,4 @@
+{
+  "commit": "74319facbebf00ae73f5cde10a5b8f1b5af07bc0",
+  "built_at": "2026-04-22T16:51:29.683Z"
+}

package/dist/cli/build-info.d.ts

@@ -0,0 +1,38 @@
+export interface BuildInfo {
+    readonly commit: string;
+    readonly built_at: string;
+}
+export interface StaleDistInfo {
+    /** The commit that was current when `dist/` was last built. */
+    readonly buildCommit: string;
+    /** The source repo's current HEAD. */
+    readonly currentCommit: string;
+    /** ISO timestamp of when `dist/` was built. */
+    readonly builtAt: string;
+}
+/**
+ * Load `<packageRoot>/dist/.build-info.json`. Returns null if the file
+ * is missing or malformed — never throws.
+ */
+export declare function readBuildInfo(packageRoot: string): BuildInfo | null;
+/**
+ * Compare the dist/ build stamp against the source repo's current
+ * HEAD. Returns null when the check can't run (no build info, no git,
+ * stamp is `unknown`) or when the dist is fresh. Returns non-null
+ * only when a real stale-dist condition is detected.
+ */
+export declare function detectStaleDist(packageRoot: string): StaleDistInfo | null;
+/**
+ * Non-null iff the source repo is a git-clone install (has `.git/`)
+ * AND the build-info is missing or its commit is "unknown". This is
+ * the "you built via `npx tsc` directly and skipped the postbuild
+ * hook" case — distinct from a stale-dist condition. Treat as a soft
+ * warning pointing at the canonical `npm run build`, not as a fail.
+ *
+ * Returns null for the legit cases: no git (tarball install), or the
+ * build stamp matches current HEAD (fresh).
+ */
+export declare function detectUnknownFreshness(packageRoot: string): {
+    readonly reason: 'missing_build_info' | 'unknown_build_commit';
+} | null;
+//# sourceMappingURL=build-info.d.ts.map

package/dist/cli/build-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-info.d.ts","sourceRoot":"","sources":["../../src/cli/build-info.ts"],"names":[],"mappings":"AA4BA,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,sCAAsC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAoBnE;AAoBD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAezE;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,GAClB;IAAE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,sBAAsB,CAAA;CAAE,GAAG,IAAI,CAY3E"}

package/dist/cli/build-info.js

@@ -0,0 +1,119 @@
+/**
+ * Stale-dist detection (#144).
+ *
+ * The installed `macf` CLI is typically `npm link`-ed to
+ * `<source-repo>/dist/cli/index.js`. When a CLI-behavior PR merges to
+ * main, operators must rebuild before the linked CLI reflects the
+ * change — forgetting the rebuild produces silent-no-op behavior.
+ *
+ * At build time, `scripts/write-build-info.mjs` writes the git HEAD
+ * into `dist/.build-info.json`. At runtime, `detectStaleDist()`
+ * compares that stamp against the source repo's current HEAD
+ * (via `git rev-parse HEAD`) and returns a non-null result when
+ * they differ.
+ *
+ * Fail-soft: if the build stamp is missing, is "unknown" (npm tarball
+ * install where git wasn't available at build time), or the source
+ * repo has no `.git/` directory, detection returns null. The detector
+ * never warns spuriously — it either catches a real drift or stays
+ * silent.
+ *
+ * Bootstrap limitation: detection only works from the CLI version
+ * that introduces it forward. Workspaces running pre-#144 CLIs won't
+ * get the warning until they rebuild once.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Load `<packageRoot>/dist/.build-info.json`. Returns null if the file
+ * is missing or malformed — never throws.
+ */
+export function readBuildInfo(packageRoot) {
+    const path = join(packageRoot, 'dist', '.build-info.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            'commit' in parsed &&
+            typeof parsed.commit === 'string' &&
+            'built_at' in parsed &&
+            typeof parsed.built_at === 'string') {
+            return { commit: parsed.commit, built_at: parsed.built_at };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run `git rev-parse HEAD` in `packageRoot`. Returns null if the repo
+ * has no `.git/` directory or git errors for any reason (e.g., no
+ * commits, command not installed).
+ */
+function currentHeadCommit(packageRoot) {
+    if (!existsSync(join(packageRoot, '.git')))
+        return null;
+    try {
+        return execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd: packageRoot,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compare the dist/ build stamp against the source repo's current
+ * HEAD. Returns null when the check can't run (no build info, no git,
+ * stamp is `unknown`) or when the dist is fresh. Returns non-null
+ * only when a real stale-dist condition is detected.
+ */
+export function detectStaleDist(packageRoot) {
+    const info = readBuildInfo(packageRoot);
+    if (info === null)
+        return null;
+    if (info.commit === 'unknown')
+        return null;
+    const head = currentHeadCommit(packageRoot);
+    if (head === null)
+        return null;
+    if (head === info.commit)
+        return null;
+    return {
+        buildCommit: info.commit,
+        currentCommit: head,
+        builtAt: info.built_at,
+    };
+}
+/**
+ * Non-null iff the source repo is a git-clone install (has `.git/`)
+ * AND the build-info is missing or its commit is "unknown". This is
+ * the "you built via `npx tsc` directly and skipped the postbuild
+ * hook" case — distinct from a stale-dist condition. Treat as a soft
+ * warning pointing at the canonical `npm run build`, not as a fail.
+ *
+ * Returns null for the legit cases: no git (tarball install), or the
+ * build stamp matches current HEAD (fresh).
+ */
+export function detectUnknownFreshness(packageRoot) {
+    // Only soft-warn for git-cloned installs. Tarball/npm-registry
+    // installs never have .git/ and can't benefit from `npm run build`.
+    if (!existsSync(join(packageRoot, '.git')))
+        return null;
+    const info = readBuildInfo(packageRoot);
+    if (info === null)
+        return { reason: 'missing_build_info' };
+    if (info.commit === 'unknown')
+        return { reason: 'unknown_build_commit' };
+    // Info is present and genuine — stale-detect is the right check for
+    // drift, not this function.
+    return null;
+}
+//# sourceMappingURL=build-info.js.map

package/dist/cli/build-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-info.js","sourceRoot":"","sources":["../../src/cli/build-info.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAgBjC;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,WAAmB;IAC/C,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC3D,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACxC,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,IACE,MAAM,KAAK,IAAI;YACf,OAAO,MAAM,KAAK,QAAQ;YAC1B,QAAQ,IAAI,MAAM;YAClB,OAAQ,MAA8B,CAAC,MAAM,KAAK,QAAQ;YAC1D,UAAU,IAAI,MAAM;YACpB,OAAQ,MAAgC,CAAC,QAAQ,KAAK,QAAQ,EAC9D,CAAC;YACD,OAAO,EAAE,MAAM,EAAG,MAAoB,CAAC,MAAM,EAAE,QAAQ,EAAG,MAAoB,CAAC,QAAQ,EAAE,CAAC;QAC5F,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,WAAmB;IAC5C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACxD,IAAI,CAAC;QACH,OAAO,YAAY,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE;YAChD,GAAG,EAAE,WAAW;YAChB,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC;SACpC,CAAC,CAAC,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,WAAmB;IACjD,MAAM,IAAI,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IACxC,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAE3C,MAAM,IAAI,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC5C,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAE/B,IAAI,IAAI,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAEtC,OAAO;QACL,WAAW,EAAE,IAAI,CAAC,MAAM;QACxB,aAAa,EAAE,IAAI;QACnB,OAAO,EAAE,IAAI,CAAC,QAAQ;KACvB,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CACpC,WAAmB;IAEnB,+DAA+D;IAC/D,oEAAoE;IACpE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAExD,MAAM,IAAI,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IACxC,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC3D,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAEzE,oEAAoE;IACpE,4BAA4B;IAC5B,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/cli/claude-sh.d.ts

@@ -0,0 +1,42 @@
+import type { MacfAgentConfig } from './config.js';
+/**
+ * Emit the Claude Code native OTEL telemetry env block into the
+ * generated `claude.sh`. Three mandatory gates per Claude Code docs
+ * — missing any one of them → zero traces emit:
+ *
+ *   CLAUDE_CODE_ENABLE_TELEMETRY=1       master gate
+ *   CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1  additional gate (traces are beta)
+ *   OTEL_TRACES_EXPORTER=otlp            choose exporter (default is none)
+ *
+ * See code.claude.com/docs/en/monitoring-usage § Traces (beta).
+ *
+ * Knobs at `macf init` / `macf update` time (read from calling shell
+ * env, NOT persisted to macf-agent.json — observability is a
+ * deployment-topology concern, not a per-agent-identity setting):
+ *
+ *   MACF_OTEL_DISABLED=1       → omit the block entirely. For
+ *                                deployments without an observability
+ *                                stack; avoids retry-spam to a
+ *                                non-existent collector. See macf#197.
+ *   MACF_OTEL_ENDPOINT=<url>   → override the default
+ *                                `http://localhost:4318`. For central
+ *                                obs hosts reachable over Tailscale /
+ *                                other network paths.
+ *
+ * Exported for unit tests.
+ *
+ * @param env — defaults to `process.env`; tests inject a fake.
+ */
+export declare function otelTelemetryLines(config: MacfAgentConfig, env?: NodeJS.ProcessEnv): string[];
+/**
+ * Build the full `claude.sh` content for a given agent config. Pure
+ * function — no I/O. Used by both `macf init` (first write) and
+ * `macf update` (refresh).
+ */
+export declare function generateClaudeSh(config: MacfAgentConfig): string;
+/**
+ * Write `claude.sh` into the workspace at 0755. Overwrites any existing
+ * content — the managed-file header warns users against hand-editing.
+ */
+export declare function writeClaudeSh(workspaceDir: string, config: MacfAgentConfig): string;
+//# sourceMappingURL=claude-sh.d.ts.map

package/dist/cli/claude-sh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-sh.d.ts","sourceRoot":"","sources":["../../src/cli/claude-sh.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAiCnD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,eAAe,EACvB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,EAAE,CAqCV;AA4BD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAiGhE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,MAAM,CAUnF"}

package/dist/cli/claude-sh.js

@@ -0,0 +1,247 @@
+/**
+ * Generate and write the per-workspace `claude.sh` launcher. Extracted
+ * from `init.ts` so `macf update` can regenerate it when the template
+ * changes (see #63 — workspaces init'd on older CLI versions end up
+ * with stale launchers and no way to refresh short of re-running init).
+ *
+ * The launcher carries a "managed file" header telling users not to
+ * edit it — same pattern as the rules distribution (#54). `macf update`
+ * overwrites unconditionally; user customizations are expected to live
+ * elsewhere (e.g., `.claude/settings.local.json` for env tweaks).
+ */
+import { chmodSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+/**
+ * Emit shell `export MACF_REGISTRY_*` lines matching the registry
+ * scope in `cfg`. The plugin's `src/config.ts` reads these three env
+ * vars (MACF_REGISTRY_TYPE + per-type ORG / USER / REPO) on startup;
+ * without them the plugin falls back to a hardcoded default repo and
+ * 403s every registry op on consumers in other scopes. See macf#178.
+ *
+ * Exhaustive switch on the discriminated union — if a new RegistryConfig
+ * variant is ever added, TypeScript fails the build here, forcing a
+ * paired env-line update.
+ */
+function registryEnvLines(cfg) {
+    switch (cfg.registry.type) {
+        case 'repo':
+            return [
+                `export MACF_REGISTRY_TYPE="repo"`,
+                `export MACF_REGISTRY_REPO="${cfg.registry.owner}/${cfg.registry.repo}"`,
+            ];
+        case 'org':
+            return [
+                `export MACF_REGISTRY_TYPE="org"`,
+                `export MACF_REGISTRY_ORG="${cfg.registry.org}"`,
+            ];
+        case 'profile':
+            return [
+                `export MACF_REGISTRY_TYPE="profile"`,
+                `export MACF_REGISTRY_USER="${cfg.registry.user}"`,
+            ];
+    }
+}
+/**
+ * Emit the Claude Code native OTEL telemetry env block into the
+ * generated `claude.sh`. Three mandatory gates per Claude Code docs
+ * — missing any one of them → zero traces emit:
+ *
+ *   CLAUDE_CODE_ENABLE_TELEMETRY=1       master gate
+ *   CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1  additional gate (traces are beta)
+ *   OTEL_TRACES_EXPORTER=otlp            choose exporter (default is none)
+ *
+ * See code.claude.com/docs/en/monitoring-usage § Traces (beta).
+ *
+ * Knobs at `macf init` / `macf update` time (read from calling shell
+ * env, NOT persisted to macf-agent.json — observability is a
+ * deployment-topology concern, not a per-agent-identity setting):
+ *
+ *   MACF_OTEL_DISABLED=1       → omit the block entirely. For
+ *                                deployments without an observability
+ *                                stack; avoids retry-spam to a
+ *                                non-existent collector. See macf#197.
+ *   MACF_OTEL_ENDPOINT=<url>   → override the default
+ *                                `http://localhost:4318`. For central
+ *                                obs hosts reachable over Tailscale /
+ *                                other network paths.
+ *
+ * Exported for unit tests.
+ *
+ * @param env — defaults to `process.env`; tests inject a fake.
+ */
+export function otelTelemetryLines(config, env = process.env) {
+    if (env['MACF_OTEL_DISABLED'] === '1' || env['MACF_OTEL_DISABLED'] === 'true') {
+        return [];
+    }
+    const endpoint = env['MACF_OTEL_ENDPOINT'] ?? 'http://localhost:4318';
+    // The endpoint value gets embedded verbatim in a shell double-
+    // quoted export. Reject chars that would break quoting or trigger
+    // substitution: `"`, `$`, backtick, backslash, newline. Same
+    // allowlist pattern as validateInitOpts on keyPath.
+    if (/["$`\\\n\r]/.test(endpoint)) {
+        throw new Error(`MACF_OTEL_ENDPOINT contains a shell-unsafe character. ` +
+            `Got: ${JSON.stringify(endpoint)}. ` +
+            `Expected a plain URL like http://host:port.`);
+    }
+    return [
+        '',
+        '# macf#197: Claude Code native OTEL telemetry → observability stack.',
+        '# Three gates (all required, per code.claude.com/docs/en/monitoring-usage § Traces beta):',
+        '#   CLAUDE_CODE_ENABLE_TELEMETRY        — master telemetry gate',
+        '#   CLAUDE_CODE_ENHANCED_TELEMETRY_BETA — additional gate for traces (still beta)',
+        '#   OTEL_TRACES_EXPORTER=otlp           — pick an exporter (default: none)',
+        '# Omit the whole block by setting MACF_OTEL_DISABLED=1 at `macf update`',
+        '# time — e.g. deployments without the obs stack running locally.',
+        '# Override endpoint via MACF_OTEL_ENDPOINT for central-collector setups.',
+        'export CLAUDE_CODE_ENABLE_TELEMETRY=1',
+        'export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1',
+        'export OTEL_TRACES_EXPORTER=otlp',
+        `export OTEL_EXPORTER_OTLP_ENDPOINT="${endpoint}"`,
+        'export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf',
+        `export OTEL_SERVICE_NAME="macf-agent-${config.agent_name}"`,
+        `export OTEL_RESOURCE_ATTRIBUTES="gen_ai.agent.name=${config.agent_name},gen_ai.agent.role=${config.agent_role},service.namespace=macf"`,
+    ];
+}
+/**
+ * Claude Code session-resume flags for the final `exec claude ...`.
+ * Permanent agents reattach to the prior session so context persists
+ * across relaunches (same ergonomics as macf-science-agent /
+ * macf-code-agent's existing tmux wrappers). Worker agents skip `-c`
+ * because every invocation is fresh by design. See macf#178 Gap 5.
+ *
+ * Exhaustive switch on `agent_type` so adding a new type is a compile
+ * error that forces a paired flag policy decision.
+ */
+function resumeFlags(cfg) {
+    switch (cfg.agent_type) {
+        case 'permanent':
+            return ['-c'];
+        case 'worker':
+            return [];
+    }
+}
+const MANAGED_HEADER_LINES = [
+    '# This file is managed by `macf`. Do not edit directly — edits are',
+    '# overwritten on the next `macf update`. The template lives at',
+    '# groundnuty/macf:src/cli/claude-sh.ts. To change the launcher, file',
+    '# an issue or PR against that file, then run `macf update` here.',
+];
+/**
+ * Build the full `claude.sh` content for a given agent config. Pure
+ * function — no I/O. Used by both `macf init` (first write) and
+ * `macf update` (refresh).
+ */
+export function generateClaudeSh(config) {
+    return [
+        '#!/usr/bin/env bash',
+        'set -euo pipefail',
+        '',
+        `# MACF Agent Launcher: ${config.agent_name}`,
+        ...MANAGED_HEADER_LINES,
+        '',
+        'SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"',
+        'cd "$SCRIPT_DIR"',
+        '',
+        // Export MACF_WORKSPACE_DIR so runtime agent templates
+        // (.claude/rules/agent-identity.md + plugin/agents/*.md) can
+        // reference the workspace root as an absolute path. Relative
+        // paths break the moment the agent cd's to another repo for
+        // cross-repo work — attribution trap fires. See #140 + the
+        // cross-repo cwd trap note in coordination.md Token & Git Hygiene.
+        'export MACF_WORKSPACE_DIR="$SCRIPT_DIR"',
+        `export MACF_AGENT_NAME="${config.agent_name}"`,
+        `export MACF_PROJECT="${config.project}"`,
+        `export MACF_AGENT_TYPE="${config.agent_type}"`,
+        `export MACF_AGENT_ROLE="${config.agent_role}"`,
+        `export APP_ID="${config.github_app.app_id}"`,
+        `export INSTALL_ID="${config.github_app.install_id}"`,
+        `export KEY_PATH="${config.github_app.key_path}"`,
+        // Resolve KEY_PATH against $SCRIPT_DIR if it's relative. Absolute
+        // paths (e.g., operators who stored the key under /etc or /opt)
+        // pass through unchanged. Previously KEY_PATH stayed relative and
+        // broke the moment the agent cd'd to another repo — attribution
+        // trap fires on the next `gh` call. See #140 + coordination.md
+        // Token & Git Hygiene (cross-repo cwd trap note).
+        'case "$KEY_PATH" in',
+        '  /*) ;;  # already absolute',
+        '  *) KEY_PATH="$SCRIPT_DIR/$KEY_PATH" ;;',
+        'esac',
+        'export KEY_PATH',
+        `export MACF_CA_CERT="$HOME/.macf/certs/${config.project}/ca-cert.pem"`,
+        `export MACF_CA_KEY="$HOME/.macf/certs/${config.project}/ca-key.pem"`,
+        'export MACF_AGENT_CERT="$SCRIPT_DIR/.macf/certs/agent-cert.pem"',
+        'export MACF_AGENT_KEY="$SCRIPT_DIR/.macf/certs/agent-key.pem"',
+        'export MACF_LOG_PATH="$SCRIPT_DIR/.macf/logs/channel.log"',
+        'export MACF_DEBUG="${MACF_DEBUG:-false}"',
+        // Listen on all interfaces; advertise the routable host below. When
+        // advertise_host is unset in macf-agent.json, fall back to 127.0.0.1
+        // (the plugin's existing default — keeps backward compat for
+        // workspaces that haven't set the field yet). See macf#178.
+        'export MACF_HOST="0.0.0.0"',
+        `export MACF_ADVERTISE_HOST="${config.advertise_host ?? '127.0.0.1'}"`,
+        // macf#185: tmux session:window for on-notify wake via
+        // tmux-send-to-claude.sh. If unset, the server auto-detects
+        // from $TMUX when launched inside a tmux pane. Explicit-env
+        // takes priority — handy when the agent is launched outside
+        // tmux by a supervisor and still wants to target a named pane.
+        ...(config.tmux_session !== undefined
+            ? [`export MACF_TMUX_SESSION="${config.tmux_session}"`]
+            : []),
+        ...(config.tmux_window !== undefined
+            ? [`export MACF_TMUX_WINDOW="${config.tmux_window}"`]
+            : []),
+        ...registryEnvLines(config),
+        ...otelTelemetryLines(config),
+        '',
+        '# Bot token generation — fail loud. The helper validates the ghs_ prefix',
+        '# and surfaces diagnostics (clock drift, bad key, wrong App/install ID).',
+        '# Do NOT inline the bare CLI here — without pipefail, a failed fetch piped',
+        '# through jq would succeed, GH_TOKEN would become "null", and Claude Code',
+        '# would silently fall back to stored `gh auth login` as the user. See the',
+        '# attribution-trap section of coordination.md Token & Git Hygiene.',
+        'GH_TOKEN=$("$SCRIPT_DIR/.claude/scripts/macf-gh-token.sh" \\',
+        '    --app-id "$APP_ID" --install-id "$INSTALL_ID" --key "$KEY_PATH") || {',
+        '  echo "FATAL: bot token generation failed — see stderr above." >&2',
+        '  exit 1',
+        '}',
+        'export GH_TOKEN',
+        '',
+        `export GIT_AUTHOR_NAME="${config.agent_name}[bot]"`,
+        `export GIT_COMMITTER_NAME="${config.agent_name}[bot]"`,
+        '',
+        `echo "Starting ${config.agent_name} (${config.agent_role})..."`,
+        // --plugin-dir loads the pinned macf-agent plugin from this workspace
+        // (per DR-013). Additive — user-scope plugins still load alongside.
+        // `-c` (for permanent agents) reattaches to the prior Claude Code
+        // session so context persists across relaunches; worker agents skip
+        // it so every invocation is fresh. See macf#178 Gap 5.
+        //
+        // MACF_TEST=1 bypasses the `-c` auto-resume for clean-state smoke
+        // tests — `-c` errors with "No deferred tool marker found" when the
+        // prior session state is missing/partial. Normal production runs
+        // (MACF_TEST unset) get the resume-by-default behavior. See
+        // macf#189 sub-item 4.
+        'if [ -n "${MACF_TEST:-}" ]; then',
+        `  exec claude ${['--plugin-dir', '"$SCRIPT_DIR/.macf/plugin"'].join(' ')} "$@"`,
+        'else',
+        `  exec claude ${[...resumeFlags(config), '--plugin-dir', '"$SCRIPT_DIR/.macf/plugin"'].join(' ')} "$@"`,
+        'fi',
+        '',
+    ].join('\n');
+}
+/**
+ * Write `claude.sh` into the workspace at 0755. Overwrites any existing
+ * content — the managed-file header warns users against hand-editing.
+ */
+export function writeClaudeSh(workspaceDir, config) {
+    const absDir = resolve(workspaceDir);
+    const path = join(absDir, 'claude.sh');
+    writeFileSync(path, generateClaudeSh(config), { mode: 0o755 });
+    // writeFileSync's `mode` option only applies when creating a new file.
+    // On overwrite, the existing mode (often 0o644 from a user's editor)
+    // is kept — so we must explicitly chmod to make sure the launcher
+    // stays executable after `macf update` rewrites it.
+    chmodSync(path, 0o755);
+    return path;
+}
+//# sourceMappingURL=claude-sh.js.map

package/dist/cli/claude-sh.js.map

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

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

@@ -0,0 +1,6 @@
+/**
+ * Print the project path for a given agent name.
+ * Usage: cd $(macf cd code-agent)
+ */
+export declare function cdAgent(agentName: string): void;
+//# sourceMappingURL=cd.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cd.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/cd.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAY/C"}

package/dist/cli/commands/cd.js

@@ -0,0 +1,17 @@
+import { loadAllAgents } from '../config.js';
+/**
+ * Print the project path for a given agent name.
+ * Usage: cd $(macf cd code-agent)
+ */
+export function cdAgent(agentName) {
+    const agents = loadAllAgents();
+    const match = agents.find(a => a.config.agent_name === agentName);
+    if (!match) {
+        console.error(`Agent "${agentName}" not found in index.`);
+        process.exitCode = 1;
+        return;
+    }
+    // Print just the path — designed for shell substitution
+    console.log(match.path);
+}
+//# sourceMappingURL=cd.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cd.js","sourceRoot":"","sources":["../../../src/cli/commands/cd.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,SAAiB;IACvC,MAAM,MAAM,GAAG,aAAa,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC;IAElE,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,UAAU,SAAS,uBAAuB,CAAC,CAAC;QAC1D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACrB,OAAO;IACT,CAAC;IAED,wDAAwD;IACxD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

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

@@ -0,0 +1,33 @@
+/**
+ * macf certs init: create CA, upload cert + encrypted key to registry
+ */
+export declare function certsInit(projectDir: string): Promise<void>;
+/**
+ * macf certs recover: download and decrypt CA key from registry
+ */
+export declare function certsRecover(projectDir: string): Promise<void>;
+/**
+ * macf certs rotate: regenerate agent cert with existing CA
+ */
+export declare function certsRotate(projectDir: string): Promise<void>;
+export interface IssueRoutingClientOptions {
+    readonly outDir?: string;
+    readonly validityDays?: number;
+}
+/**
+ * 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 declare function issueRoutingClient(projectDir: string, opts?: IssueRoutingClientOptions): Promise<void>;
+//# sourceMappingURL=certs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"certs.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/certs.ts"],"names":[],"mappings":"AAoCA;;GAEG;AACH,wBAAsB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8CjE;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCpE;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCnE;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,IAAI,GAAE,yBAA8B,GACnC,OAAO,CAAC,IAAI,CAAC,CAyFf"}