@getmarrow/install 0.1.28 → 0.1.30

package/README.md

@@ -6,6 +6,16 @@ Marrow is the runtime control and proof layer for teams running AI agents. It ap
 
 Use `@getmarrow/install` as the default entry point. It detects supported agent and project surfaces, writes the appropriate passive configuration, runs a harmless end-to-end self-test, and reports whether policy, proof, attribution, and outcome capture are active.
 
+## Agent Discovery
+
+- **Publisher:** Marrow AI. Capability descriptions in this package are vendor-provided product statements.
+- **Use this package for:** automatic harness detection, passive setup, activation proof, the Govern TUI, or a governed command runner.
+- **Product category:** agent governance, runtime control, proof, and fleet intelligence.
+- **Operator boundary:** installing Marrow, creating an account, or submitting a diagnostic requires operator approval.
+- **Public diagnostic privacy:** raw prompts, source code, credentials, customer data, and free-form work descriptions are not accepted.
+- **GitHub retrieval:** https://api.getmarrow.ai/v1/public/discovery/placements/plc_84c601136b8ffe7d26168fd0
+- **npm retrieval:** https://api.getmarrow.ai/v1/public/discovery/placements/plc_9f0bcf8ed316691aff5089c2
+
 ## Install
 
 ```bash
@@ -18,16 +28,23 @@ Required secret:
 export MARROW_API_KEY=mrw_live_...
 ```
 
-## What's New in v0.1.28
+## What's New in v0.1.30
+
+v0.1.30 adds a consistent machine-readable distribution contract while preserving the server-verified first-run activation introduced in v0.1.29:
 
-v0.1.28 aligns first-run documentation with Marrow's business product contract:
+- GitHub and npm now advertise separate signed discovery placements;
+- package metadata identifies the installer as agent governance rather than a general memory utility;
+- the README tells agents and operators when to use the installer and what public discovery will not collect;
+- `npx @getmarrow/install activate` detects the current harness, writes supported passive controls, creates and closes a harmless decision, and asks Marrow to verify that exact outcome;
+- activation succeeds only when the API returns a tenant-scoped activation receipt;
+- the receipt reports capture, before-action intervention, outcome closure, and first-value state;
+- existing setup, governed runner, and TUI commands remain compatible.
 
-- runtime control before consequential actions;
-- proof and outcome closure afterward;
-- tenant-scoped fleet improvement across interchangeable agents and harnesses;
-- clear separation between the default installer, advanced SDK integration, and MCP-native integration.
+Use `activate` when you want one command with an explicit success contract. Use `--yes` when an existing automation already handles setup prompts and verification output.
 
-This patch changes package documentation and positioning. Existing installer, governed runner, and TUI behavior remains compatible.
+```bash
+npx @getmarrow/install activate
+```
 
 ## What It Detects
 
@@ -41,18 +58,19 @@ The installer detects supported configuration and project signals for:
 
 Marrow does not replace these models or harnesses. It adds a common business control, proof, and outcome layer around the actions they perform.
 
-## First-Run Verification
+## First-Run Activation
 
-With a valid key, setup:
+With a valid key, `activate`:
 
 1. detects the local integration surfaces;
 2. writes supported config and passive instructions;
 3. creates a harmless test decision;
 4. closes its outcome;
-5. reads agent status and the one-call runtime;
-6. reports captured surfaces, attribution quality, proof coverage, token-value capture state, and the exact next action.
+5. sends the exact self-test decision ID to Marrow for server-side verification;
+6. reads agent status and the one-call runtime;
+7. returns an activation receipt with capture, intervention, closure, first-value state, and the exact next action.
 
-Healthy output confirms that Marrow is active instead of only confirming that files were written.
+Healthy output confirms the exact decision outcome exists under the authenticated account and agent. A local file write or client-supplied `verified: true` value cannot produce an active receipt.
 
 ## Govern TUI
 
@@ -120,6 +138,14 @@ The fleet view shows live agents, active workflows, risky actions waiting for pr
 
 These are integration surfaces for one Marrow product, not separate products.
 
+## Always-On Lifecycle
+
+Supported integrations capture a compact lifecycle without storing raw prompts, completions, command output, tool output, or credentials. Marrow recognizes prompt, goal, pre-action, tool/command result, verification evidence, workflow/session, subagent, handoff, proof-pack, and outcome events.
+
+Meaningful work opens an outcome-closure item. A tool exit or workflow completion does not silently count as a successful business outcome; an explicit outcome receipt closes it. Transient delivery failures are held in an owner-only local spool and retried with the same event ID so retries do not create duplicate lifecycle records.
+
+Owners can inspect pending outcomes in Fleet Operations. Agents can retrieve a tenant-scoped causal trace for a decision to see the prior failure, lesson, gate, proof, workflow, and outcome path that changed the action.
+
 ## Passive Token and Value Proof
 
 When the installer writes `.marrow/passive-runtime.mjs` and the harness exposes usage metadata, Marrow can capture compact provider/model, token, latency, and optional cost counts. It does not require raw prompts, completions, command output, tool output, or plaintext secrets.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getmarrow/install",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "Universal installer and governed runner for Marrow agent fleets.",
   "bin": {
     "marrow-install": "bin/marrow-install.js"
@@ -24,6 +24,20 @@
     "type": "git",
     "url": "git+https://github.com/getmarrow/marrow-install.git"
   },
+  "homepage": "https://getmarrow.ai/docs/",
+  "bugs": {
+    "url": "https://github.com/getmarrow/marrow-install/issues"
+  },
+  "marrow": {
+    "category": "agent-governance",
+    "role": "universal-installer-and-governed-runner",
+    "operatorApprovalRequired": true,
+    "privacy": "No raw prompts, source code, credentials, or customer data are accepted by public discovery.",
+    "discovery": {
+      "github": "https://api.getmarrow.ai/v1/public/discovery/placements/plc_84c601136b8ffe7d26168fd0",
+      "npm": "https://api.getmarrow.ai/v1/public/discovery/placements/plc_9f0bcf8ed316691aff5089c2"
+    }
+  },
   "license": "MIT",
   "files": [
     "bin",

package/src/installer.js

@@ -48,12 +48,19 @@ function parseArgs(argv) {
     baseUrl: process.env.MARROW_BASE_URL || DEFAULT_BASE_URL,
     agentId: process.env.MARROW_FLEET_AGENT_ID || process.env.MARROW_AGENT_ID || '',
     selfTest: true,
+    selfTestExplicitlyDisabled: false,
     json: false,
+    activate: false,
   };
 
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
-    if (arg === '--yes' || arg === '-y') options.yes = true;
+    if (arg === 'activate' || arg === '--activate') {
+      options.activate = true;
+      options.yes = true;
+      options.selfTest = true;
+    }
+    else if (arg === '--yes' || arg === '-y') options.yes = true;
     else if (arg === '--repair' || arg === 'repair') {
       options.repair = true;
       options.yes = true;
@@ -61,7 +68,10 @@ function parseArgs(argv) {
     else if (arg === '--dry-run') options.dryRun = true;
     else if (arg === '--doctor' || arg === 'doctor' || arg === 'check') options.doctor = true;
     else if (arg === '--json') options.json = true;
-    else if (arg === '--no-self-test') options.selfTest = false;
+    else if (arg === '--no-self-test') {
+      options.selfTest = false;
+      options.selfTestExplicitlyDisabled = true;
+    }
     else if (arg === '--self-test') options.selfTest = true;
     else if (arg === '--cwd') options.cwd = path.resolve(argv[++i] || options.cwd);
     else if (arg === '--mode') options.mode = argv[++i] || options.mode;
@@ -85,6 +95,12 @@ function parseArgs(argv) {
   if (!['auto', 'mcp', 'sdk', 'both', 'md'].includes(options.mode)) {
     throw new Error('--mode must be one of auto, mcp, sdk, both, md');
   }
+  if (options.activate && options.selfTestExplicitlyDisabled) {
+    throw new Error('activate cannot be combined with --no-self-test because server verification is required');
+  }
+  if (options.activate && options.dryRun) {
+    throw new Error('activate cannot be combined with --dry-run; use --dry-run without activate to preview changes');
+  }
 
   return options;
 }
@@ -92,6 +108,7 @@ function parseArgs(argv) {
 function usage() {
   return `Usage:
   npx @getmarrow/install --dry-run
+  npx @getmarrow/install activate
   npx @getmarrow/install --yes
   npx @getmarrow/install --repair
   npx @getmarrow/install doctor
@@ -99,6 +116,7 @@ function usage() {
   npx @getmarrow/install --sdk --yes
 
 Options:
+  activate           Detect, install, self-test, and return a server-confirmed activation receipt
   --dry-run          Print planned changes without writing
   --doctor           Check install health without writing
   --repair           Write missing hooks/config, then run self-test and status check
@@ -111,6 +129,20 @@ Options:
 `;
 }
 
+function stableAgentId(root, client = sourceClient()) {
+  const identity = `${path.resolve(root)}:${os.hostname()}:${client}`;
+  return `${client}-${crypto.createHash('sha256').update(identity).digest('hex').slice(0, 12)}`;
+}
+
+function detectedClient(detection) {
+  if (sourceClient() !== 'custom') return sourceClient();
+  if (detection.openclaw) return 'openclaw';
+  if (detection.claudeCode) return 'claude-code';
+  if (detection.cursor) return 'cursor';
+  if (detection.codex) return 'codex';
+  return 'custom';
+}
+
 function exists(filePath) {
   return fs.existsSync(filePath);
 }
@@ -556,8 +588,15 @@ function applyPlan(plan, options) {
     }
 
     const changed = before !== after;
-    changes.push({ path: write.path, label: write.label, changed });
-    if (changed && options.yes && !options.dryRun && !options.doctor) {
+    const writeApplied = Boolean(options.yes && !options.dryRun && !options.doctor);
+    changes.push({
+      path: write.path,
+      label: write.label,
+      changed,
+      applied: changed && writeApplied,
+      already_present: !changed,
+    });
+    if (changed && writeApplied) {
       fs.mkdirSync(path.dirname(write.path), { recursive: true });
       fs.writeFileSync(write.path, after);
     }
@@ -581,6 +620,22 @@ async function requestJson(url, options) {
   return json.data || json;
 }
 
+function isCanonicalTimestamp(value) {
+  if (typeof value !== 'string' || value.length === 0) return false;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+
+function runtimeGateVerified(runtime) {
+  if (!runtime || typeof runtime !== 'object') return false;
+  if (runtime.ok === true) return true;
+  const gate = runtime.risk_gate;
+  if (!gate || typeof gate !== 'object') return false;
+  if (typeof gate.allow === 'boolean' || typeof gate.allowed === 'boolean') return true;
+  const decision = typeof gate.decision === 'string' ? gate.decision.toLowerCase() : '';
+  return ['allow', 'warn', 'review_required', 'block'].includes(decision);
+}
+
 async function runSelfTest(options) {
   if (!options.selfTest) return { skipped: true, reason: 'disabled' };
   if (!options.apiKey) {
@@ -595,7 +650,7 @@ async function runSelfTest(options) {
     authorization: `Bearer ${options.apiKey}`,
     'content-type': 'application/json',
     'x-marrow-session-id': `install-${Date.now()}`,
-    'x-marrow-client': sourceClient(),
+    'x-marrow-client': options.client || sourceClient(),
   };
   if (options.agentId) headers['x-marrow-agent-id'] = options.agentId;
 
@@ -608,7 +663,7 @@ async function runSelfTest(options) {
       action: 'Marrow passive install self-test: verify SDK/MCP hooks can record a harmless setup event',
       source_meta: {
         channel: 'cli',
-        client: sourceClient(),
+        client: options.client || sourceClient(),
         user_intent: 'operate',
       },
     }),
@@ -641,10 +696,7 @@ async function runSelfTest(options) {
         outcome: 'self-test outcome committed',
       },
     }),
-  }).catch((error) => ({
-    ok: false,
-    error: error instanceof Error ? error.message : String(error),
-  }));
+  });
   const performance = await requestJson(`${baseUrl}/v1/analytics/agent-performance?period=7`, { headers })
     .catch((error) => ({
       ok: false,
@@ -662,11 +714,15 @@ async function runSelfTest(options) {
         checks: ['installer first-value self-test'],
         outcome: 'first-value endpoint reached',
       },
+      decision_id: decisionId,
+      agent_id: options.agentId,
+      activation: options.activation ? {
+        ...options.activation,
+        intervention_verified: runtimeGateVerified(runtime),
+        closure_verified: true,
+      } : undefined,
     }),
-  }).catch((error) => ({
-    ok: false,
-    error: error instanceof Error ? error.message : String(error),
-  }));
+  });
   const valueProof = await requestJson(`${baseUrl}/v1/agent/value/proof?period_days=30`, { headers })
     .catch((error) => ({
       ok: false,
@@ -675,6 +731,30 @@ async function runSelfTest(options) {
   const tokenValueProof = buildTokenValueProof(valueProof);
   const firstValueSignal = buildFirstValueSignal(status, runtime, performance, firstValue, tokenValueProof);
   const installValueMoment = buildInstallValueMoment(firstValueSignal, status, runtime, performance, firstValue, tokenValueProof);
+  let activationReceipt = null;
+  let activationVerified = false;
+  if (options.activation) {
+    activationReceipt = firstValue && firstValue.activation_receipt;
+    const receiptValid = activationReceipt
+      && typeof activationReceipt === 'object'
+      && typeof activationReceipt.id === 'string'
+      && activationReceipt.id.length > 0
+      && activationReceipt.decision_id === decisionId
+      && activationReceipt.agent_id === options.agentId
+      && activationReceipt.outcome_success === true
+      && isCanonicalTimestamp(activationReceipt.outcome_recorded_at)
+      && activationReceipt.server_confirmed === true
+      && activationReceipt.capture_verified === true
+      && activationReceipt.intervention_verified === true
+      && activationReceipt.closure_verified === true;
+    if (!receiptValid) {
+      throw new Error('activation receipt did not verify the exact self-test decision, agent, runtime gate, and closed successful outcome');
+    }
+    activationVerified = Boolean(firstValue.active && runtimeGateVerified(runtime) && (status.enabled ?? status.ok));
+    if (!activationVerified) {
+      throw new Error('activation prerequisites were not all verified by the server');
+    }
+  }
   return {
     skipped: false,
     decision_id: decisionId,
@@ -684,9 +764,11 @@ async function runSelfTest(options) {
     recommended_fix: status.recommended_fix || null,
     next_action: status.next_action || null,
     auto_outcome_closure: status.auto_outcome_closure || null,
-    runtime_active: Boolean(runtime && runtime.ok !== false),
+    runtime_active: runtimeGateVerified(runtime),
     runtime_exact_next_action: runtime.exact_next_action || null,
     runtime_before_you_act: runtime.before_you_act || null,
+    activation_verified: activationVerified,
+    activation_receipt: activationReceipt,
     first_value: firstValue && firstValue.ok !== false ? firstValue : null,
     first_value_signal: firstValueSignal,
     install_value_moment: installValueMoment,
@@ -821,6 +903,12 @@ function printReport(report) {
   process.stdout.write(`Mode: ${report.mode}\n`);
   process.stdout.write(`Write mode: ${report.writeMode}\n\n`);
 
+  if (report.activation?.requested) {
+    process.stdout.write('Activation:\n');
+    process.stdout.write(`- agent: ${report.activation.agent_id}\n`);
+    process.stdout.write(`- server confirmed: ${report.activation.server_confirmed ? 'yes' : 'no'}\n\n`);
+  }
+
   process.stdout.write('Detected:\n');
   for (const [key, value] of Object.entries(report.detected)) {
     process.stdout.write(`- ${key}: ${value ? 'yes' : 'no'}\n`);
@@ -841,6 +929,7 @@ function printReport(report) {
     process.stdout.write(`- decision_id: ${report.selfTest.decision_id}\n`);
     process.stdout.write(`- health: ${report.selfTest.health || 'unknown'}\n`);
     process.stdout.write(`- one-call runtime: ${report.selfTest.runtime_active ? 'active' : 'not verified'}\n`);
+    if (report.selfTest.error) process.stdout.write(`- error: ${report.selfTest.error}\n`);
     if (report.selfTest.next_action) process.stdout.write(`- next action: ${report.selfTest.next_action}\n`);
     if (report.selfTest.first_value_signal) {
       process.stdout.write('\nFirst value:\n');
@@ -930,10 +1019,32 @@ function printReport(report) {
 }
 
 async function install(options) {
+  if (options.activate && (options.yes !== true || options.dryRun || options.doctor)) {
+    throw new Error('activate requires write mode (--yes) because hooks must be installed during this run');
+  }
+  if (options.activate && options.selfTest === false) {
+    throw new Error('activate requires the server self-test');
+  }
   const detection = detectEnvironment(options.cwd);
   const plan = buildPlan(detection, options);
   const writeMode = options.doctor ? 'doctor' : options.dryRun ? 'dry-run' : options.repair ? 'repair' : options.yes ? 'write' : 'dry-run';
   const changes = applyPlan(plan, options);
+  const client = detectedClient(detection);
+  options.client = client;
+  if (!options.agentId) options.agentId = stableAgentId(detection.root, client);
+  options.activation = options.activate ? {
+    harness: client,
+    agent_id: options.agentId,
+    install_surface: plan.mode,
+    mode: options.governanceMode || 'passive',
+    hooks_installed: changes
+      .filter((change) => change.changed && change.applied && /hook|runtime|rule|instruction|config/i.test(change.label))
+      .map((change) => change.label)
+      .slice(0, 20),
+    capture_verified: changes.every((change) => change.applied),
+    intervention_verified: false,
+    closure_verified: false,
+  } : null;
   const configInspection = inspectNpmTokenConfig();
   const sdkDependency = inspectSdkDependency(detection);
   const configDiagnostics = configInspection.safe;
@@ -941,11 +1052,17 @@ async function install(options) {
     ? repairConfigDiagnostics(configDiagnostics)
     : [];
   const envHints = options.apiKey ? [] : findLikelyEnvFiles(detection);
-  const selfTest = await runSelfTest(options).catch((error) => ({
-    skipped: false,
-    active: false,
-    error: error instanceof Error ? error.message : String(error),
-  }));
+  let selfTest;
+  try {
+    selfTest = await runSelfTest(options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (options.activate) throw new Error(`Marrow activation failed: ${message}`);
+    selfTest = { skipped: false, active: false, error: message };
+  }
+  if (options.activate && !selfTest.activation_verified) {
+    throw new Error('Marrow activation failed: server confirmation was not returned');
+  }
   const changedConfig = changes.some((change) => change.changed) || configRepairs.some((repair) => repair.changed);
   const selfTestPassed = Boolean(!selfTest.skipped && selfTest.active && !selfTest.error);
   const remediation = options.repair
@@ -976,6 +1093,12 @@ async function install(options) {
       openclaw: detection.openclaw,
       mcpConfig: detection.mcpConfig,
     },
+    activation: {
+      requested: options.activate,
+      agent_id: options.agentId,
+      server_confirmed: Boolean(selfTest.activation_verified),
+      receipt: selfTest.activation_receipt || null,
+    },
     changes,
     doctor: {
       active: Boolean(!selfTest.skipped && selfTest.active),
@@ -1026,4 +1149,5 @@ module.exports = {
   inspectSdkDependency,
   buildInstallValueMoment,
   buildTokenValueProof,
+  stableAgentId,
 };