brainclaw 0.19.11 → 0.19.12

package/README.md

@@ -129,6 +129,7 @@ After that, the agent should stay on Brainclaw's MCP path for live state:
 
 ```text
 bclaw_session_start      -> open session + return board/context
+bclaw_get_execution_context -> inspect local tooling + notice Brainclaw package updates
 bclaw_get_context        -> fetch fresh prompt-ready context for a path
 bclaw_list_plans         -> inspect shared work
 bclaw_claim              -> claim scope before editing
@@ -177,6 +178,8 @@ If you want a machine-level CLI for operator workflows, debugging, or repeated l
 npm install -g brainclaw
 ```
 
+By default, Brainclaw's update checks for end-user installs follow the public npm `latest` channel. Projects that need a different track can override `brainclaw_update_source`, for example to use `prelaunch` or a local tarball channel.
+
 If you are working from source while developing Brainclaw itself:
 
 ```bash

package/dist/commands/env.js

@@ -1,7 +1,7 @@
 import { memoryExists } from '../core/io.js';
 import { loadConfig } from '../core/config.js';
 import { assessAgentIntegrationReadiness } from '../core/agent-integrations.js';
-import { assessBrainclawVersion } from '../core/brainclaw-version.js';
+import { assessBrainclawVersion, checkBrainclawInstallableUpdate, renderBrainclawInstallableUpdateNotice, } from '../core/brainclaw-version.js';
 import { buildExecutionContext, compactExecutionContext, renderExecutionContextSummary } from '../core/execution-context.js';
 import { buildAgentToolingContext, renderAgentToolingSummary } from '../core/agent-context.js';
 export function runEnv(options = {}) {
@@ -14,11 +14,14 @@ export function runEnv(options = {}) {
     const config = loadConfig(cwd);
     const integrationReadiness = assessAgentIntegrationReadiness(config, cwd);
     const brainclawVersion = assessBrainclawVersion(config);
+    const installableUpdate = checkBrainclawInstallableUpdate(config, cwd, { useDefaultNpmSource: true });
+    const installableUpdateNotice = renderBrainclawInstallableUpdateNotice(installableUpdate);
     const agentTooling = options.agentTooling ? buildAgentToolingContext({ cwd }) : undefined;
     if (options.json) {
         console.log(JSON.stringify({
             execution_context: executionContext,
             brainclaw_version: brainclawVersion,
+            installable_update: installableUpdate,
             declared_agent_integrations: config.agent_integrations,
             integration_readiness: integrationReadiness,
             ...(agentTooling ? { agent_tooling: agentTooling } : {}),
@@ -33,6 +36,9 @@ export function runEnv(options = {}) {
             console.log(`Upgrade benefits: ${brainclawVersion.upgrade_message}`);
         }
     }
+    if (installableUpdateNotice) {
+        console.log(installableUpdateNotice);
+    }
     console.log(`Declared agent integrations: ${config.agent_integrations.declarations.length}`);
     const missingDeclarations = integrationReadiness.filter((entry) => !entry.ready);
     if (missingDeclarations.length > 0) {

package/dist/commands/mcp.js

@@ -7,6 +7,7 @@ import { buildAgentToolingContext, renderAgentToolingSummary } from '../core/age
 import { buildCoordinationSnapshot } from '../core/coordination.js';
 import { buildContext, renderContextMarkdown, renderContextPromptTemplate } from '../core/context.js';
 import { buildExecutionContext, renderExecutionContextSummary } from '../core/execution-context.js';
+import { checkBrainclawInstallableUpdate, renderBrainclawInstallableUpdateNotice } from '../core/brainclaw-version.js';
 import { loadConfig } from '../core/config.js';
 import { loadState, persistState } from '../core/state.js';
 import { memoryExists } from '../core/io.js';
@@ -82,7 +83,7 @@ export const MCP_READ_TOOLS = [
     },
     {
         name: 'bclaw_get_execution_context',
-        description: 'Inspect the local execution environment and optionally agent tooling signals.',
+        description: 'Inspect the local execution environment, installable Brainclaw update channel, and optionally agent tooling signals.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -1133,15 +1134,20 @@ export function handleMcpReadToolCall(name, args = {}, context = {}) {
     }
     if (name === 'bclaw_get_execution_context') {
         const executionContext = buildExecutionContext({ cwd });
+        const config = loadConfig(cwd);
+        const installableUpdate = checkBrainclawInstallableUpdate(config, cwd, { useDefaultNpmSource: true });
+        const installableUpdateNotice = renderBrainclawInstallableUpdateNotice(installableUpdate);
         const agentTooling = args.includeAgentTooling ? buildAgentToolingContext({ cwd }) : undefined;
         const text = [
             renderExecutionContextSummary(executionContext, true),
+            ...(installableUpdateNotice ? ['', installableUpdateNotice] : []),
             ...(agentTooling ? ['', renderAgentToolingSummary(agentTooling)] : []),
         ].join('\n');
         return {
             content: [{ type: 'text', text }],
             structuredContent: {
                 execution_context: executionContext,
+                installable_update: installableUpdate,
                 ...(agentTooling ? { agent_tooling: agentTooling } : {}),
             },
         };

package/dist/commands/version.js

@@ -31,7 +31,9 @@ export function runVersion(options = {}) {
         }
     }
     const assessment = assessBrainclawVersion(config);
-    const updateCheck = options.check ? checkBrainclawInstallableUpdate(config, cwd) : undefined;
+    const updateCheck = options.check
+        ? checkBrainclawInstallableUpdate(config, cwd, { useDefaultNpmSource: true })
+        : undefined;
     const result = {
         initialized,
         ...assessment,

package/dist/commands/whoami.js

@@ -4,7 +4,7 @@ import { loadConfig } from '../core/config.js';
 import { resolveCurrentHostId } from '../core/host.js';
 import { buildOperationalIdentity } from '../core/identity.js';
 import { assessAgentIntegrationReadiness } from '../core/agent-integrations.js';
-import { assessBrainclawVersion } from '../core/brainclaw-version.js';
+import { assessBrainclawVersion, checkBrainclawInstallableUpdate, renderBrainclawInstallableUpdateNotice, } from '../core/brainclaw-version.js';
 import { buildExecutionContext, compactExecutionContext } from '../core/execution-context.js';
 import { buildAgentToolingContext } from '../core/agent-context.js';
 export function runWhoami(options = {}) {
@@ -18,6 +18,8 @@ export function runWhoami(options = {}) {
     const executionContext = compactExecutionContext(buildExecutionContext({ cwd }));
     const integrationReadiness = assessAgentIntegrationReadiness(config, cwd);
     const brainclawVersion = assessBrainclawVersion(config);
+    const installableUpdate = checkBrainclawInstallableUpdate(config, cwd, { useDefaultNpmSource: true });
+    const installableUpdateNotice = renderBrainclawInstallableUpdateNotice(installableUpdate);
     const agentTooling = buildAgentToolingContext({ cwd });
     let identity;
     try {
@@ -45,6 +47,7 @@ export function runWhoami(options = {}) {
         env_session: process.env.BRAINCLAW_SESSION_ID ?? null,
         env_host: process.env.BRAINCLAW_HOST_ID ?? null,
         brainclaw_version: brainclawVersion,
+        installable_update: installableUpdate,
         declared_agent_integrations: config.agent_integrations,
         integration_readiness: integrationReadiness,
         execution_context: executionContext,
@@ -80,6 +83,13 @@ export function runWhoami(options = {}) {
     if (result.brainclaw_version.status !== 'ok') {
         console.log(`  Version    : ${result.brainclaw_version.message}`);
     }
+    if (installableUpdateNotice) {
+        const lines = installableUpdateNotice.split('\n');
+        console.log(`  Update     : ${lines[0]}`);
+        for (const line of lines.slice(1)) {
+            console.log(`             ${line}`);
+        }
+    }
     console.log(`  Declared integrations: ${result.declared_agent_integrations.declarations.length}`);
     const missingIntegrations = result.integration_readiness.filter((entry) => !entry.ready);
     if (missingIntegrations.length > 0) {

package/dist/core/brainclaw-version.js

@@ -1,11 +1,20 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { BrainclawLocalReleaseManifestSchema, } from './schema.js';
 export const DEFAULT_LOCAL_RELEASES_DIR = '.releases';
 export const DEFAULT_LOCAL_RELEASE_MANIFEST_PATH = `${DEFAULT_LOCAL_RELEASES_DIR}/brainclaw-local.json`;
+export const DEFAULT_NPM_UPDATE_PACKAGE = 'brainclaw';
+export const DEFAULT_NPM_UPDATE_DIST_TAG = 'latest';
+export const DEFAULT_INSTALLABLE_UPDATE_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
 const SEMVER_RE = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+const DEFAULT_NPM_UPDATE_SOURCE = {
+    type: 'npm',
+    package_name: DEFAULT_NPM_UPDATE_PACKAGE,
+    dist_tag: DEFAULT_NPM_UPDATE_DIST_TAG,
+};
 let cachedCliVersion;
 export function getInstalledBrainclawVersion() {
     if (cachedCliVersion) {
@@ -87,8 +96,10 @@ export function assessBrainclawVersion(config) {
         message,
     };
 }
-export function checkBrainclawInstallableUpdate(config, cwd) {
-    const source = config?.brainclaw_update_source;
+export function checkBrainclawInstallableUpdate(config, cwd, options = {}) {
+    const source = config?.brainclaw_update_source
+        ?? (options.useDefaultNpmSource ? DEFAULT_NPM_UPDATE_SOURCE : undefined);
+    const defaultSource = !config?.brainclaw_update_source && source?.type === 'npm';
     if (!source) {
         return {
             checked: false,
@@ -103,22 +114,181 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
         };
     }
     if (source.type === 'npm') {
-        const packageName = source.package_name?.trim() || 'brainclaw';
-        const distTag = source.dist_tag?.trim() || 'latest';
+        return checkNpmInstallableUpdate(source, config, cwd, options, defaultSource);
+    }
+    return checkLocalPackInstallableUpdate(source.manifest_path, config, cwd);
+}
+export function renderBrainclawInstallableUpdateNotice(updateCheck) {
+    if (!updateCheck || updateCheck.status !== 'update_available') {
+        return null;
+    }
+    const lines = [updateCheck.message];
+    if (updateCheck.install_command) {
+        lines.push(`Install: ${updateCheck.install_command}`);
+    }
+    if (updateCheck.release_notes) {
+        lines.push(`Why update: ${updateCheck.release_notes}`);
+    }
+    return lines.join('\n');
+}
+export function publishLocalBrainclawRelease(cwd, options = {}) {
+    const workspacePackage = readWorkspaceBrainclawPackage(cwd);
+    const outputDir = path.resolve(cwd, options.outputDir ?? DEFAULT_LOCAL_RELEASES_DIR);
+    const manifestPath = path.resolve(cwd, options.manifestPath ?? DEFAULT_LOCAL_RELEASE_MANIFEST_PATH);
+    fs.mkdirSync(outputDir, { recursive: true });
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    const packResult = spawnSync(resolveNpmCommand(), resolveNpmPackArgs(outputDir), {
+        cwd,
+        encoding: 'utf-8',
+        timeout: 120000,
+    });
+    if (packResult.error) {
+        throw new Error(`Failed to run npm pack: ${packResult.error.message}`);
+    }
+    if (packResult.status !== 0) {
+        throw new Error(firstNonEmptyLine(packResult.stderr) ?? firstNonEmptyLine(packResult.stdout) ?? 'npm pack failed');
+    }
+    const artifactFilename = parsePackedFilename(packResult.stdout);
+    if (!artifactFilename) {
+        throw new Error('npm pack did not report the generated tarball filename.');
+    }
+    const artifactAbsolutePath = path.join(outputDir, artifactFilename);
+    if (!fs.existsSync(artifactAbsolutePath)) {
+        throw new Error(`npm pack reported ${artifactFilename}, but the tarball was not found in ${outputDir}.`);
+    }
+    const manifestArtifactPath = toManifestRelativePath(path.relative(path.dirname(manifestPath), artifactAbsolutePath));
+    const projectArtifactPath = toManifestRelativePath(path.relative(cwd, artifactAbsolutePath));
+    const projectManifestPath = toPortablePath(path.relative(cwd, manifestPath));
+    const installCommand = `npm install -g "${projectArtifactPath}"`;
+    const releaseNotes = options.releaseNotes?.trim() || null;
+    const manifest = BrainclawLocalReleaseManifestSchema.parse({
+        version: 1,
+        channel: 'local-pack',
+        package_name: workspacePackage.name,
+        latest_installable_version: workspacePackage.version,
+        published_at: new Date().toISOString(),
+        artifact_path: manifestArtifactPath,
+        install_command: installCommand,
+        release_notes: releaseNotes ?? undefined,
+    });
+    fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
+    return {
+        package_name: workspacePackage.name,
+        workspace_version: workspacePackage.version,
+        manifest_path: projectManifestPath,
+        artifact_path: projectArtifactPath,
+        install_command: installCommand,
+        release_notes: releaseNotes,
+    };
+}
+function checkNpmInstallableUpdate(source, config, cwd, options, defaultSource) {
+    const packageName = source.package_name?.trim() || DEFAULT_NPM_UPDATE_PACKAGE;
+    const distTag = source.dist_tag?.trim() || DEFAULT_NPM_UPDATE_DIST_TAG;
+    if (packageName.length === 0) {
         return {
             checked: false,
             source_type: 'npm',
-            source_description: `${packageName}@${distTag}`,
+            source_description: null,
             latest_installable_version: null,
             artifact_path: null,
             install_command: null,
             release_notes: null,
-            status: 'unsupported_source',
-            message: 'The npm update source is modeled in config but is not implemented yet in this build.',
+            status: 'invalid_config',
+            message: 'brainclaw_update_source.package_name must not be empty.',
+            default_source: defaultSource,
         };
     }
-    const manifestPath = source.manifest_path.trim();
-    if (manifestPath.length === 0) {
+    if (distTag.length === 0) {
+        return {
+            checked: false,
+            source_type: 'npm',
+            source_description: packageName,
+            latest_installable_version: null,
+            artifact_path: null,
+            install_command: null,
+            release_notes: null,
+            status: 'invalid_config',
+            message: 'brainclaw_update_source.dist_tag must not be empty.',
+            default_source: defaultSource,
+        };
+    }
+    try {
+        const lookup = (options.npmLookup ?? lookupNpmDistTags)(packageName, {
+            cwd,
+            now: options.now,
+            cacheTtlMs: options.cacheTtlMs,
+        });
+        const latestVersion = normalizeConfiguredVersion(lookup.dist_tags[distTag]);
+        if (!latestVersion) {
+            return {
+                checked: true,
+                source_type: 'npm',
+                source_description: formatNpmSourceDescription(packageName, distTag, defaultSource),
+                latest_installable_version: null,
+                artifact_path: null,
+                install_command: null,
+                release_notes: config?.brainclaw_upgrade_message?.trim() || null,
+                status: 'check_failed',
+                message: `The npm channel ${packageName}@${distTag} did not resolve to a valid semver release.`,
+                checked_at: lookup.checked_at,
+                cached: lookup.cached,
+                default_source: defaultSource,
+            };
+        }
+        const installCommand = config?.brainclaw_upgrade_command?.trim()
+            || `npm install -g ${packageName}@${latestVersion}`;
+        const releaseNotes = config?.brainclaw_upgrade_message?.trim() || null;
+        const installedVersion = getInstalledBrainclawVersion();
+        if (compareVersions(installedVersion, latestVersion) < 0) {
+            return {
+                checked: true,
+                source_type: 'npm',
+                source_description: formatNpmSourceDescription(packageName, distTag, defaultSource),
+                latest_installable_version: latestVersion,
+                artifact_path: null,
+                install_command: installCommand,
+                release_notes: releaseNotes,
+                status: 'update_available',
+                message: `A newer installable brainclaw build is available from npm: ${latestVersion} (installed ${installedVersion}).`,
+                checked_at: lookup.checked_at,
+                cached: lookup.cached,
+                default_source: defaultSource,
+            };
+        }
+        return {
+            checked: true,
+            source_type: 'npm',
+            source_description: formatNpmSourceDescription(packageName, distTag, defaultSource),
+            latest_installable_version: latestVersion,
+            artifact_path: null,
+            install_command: installCommand,
+            release_notes: releaseNotes,
+            status: 'up_to_date',
+            message: `Installed brainclaw ${installedVersion} is up to date for npm channel ${packageName}@${distTag}.`,
+            checked_at: lookup.checked_at,
+            cached: lookup.cached,
+            default_source: defaultSource,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            checked: true,
+            source_type: 'npm',
+            source_description: formatNpmSourceDescription(packageName, distTag, defaultSource),
+            latest_installable_version: null,
+            artifact_path: null,
+            install_command: null,
+            release_notes: config?.brainclaw_upgrade_message?.trim() || null,
+            status: 'check_failed',
+            message: `Failed to check npm installable updates: ${message}`,
+            default_source: defaultSource,
+        };
+    }
+}
+function checkLocalPackInstallableUpdate(manifestPath, config, cwd) {
+    const trimmedManifestPath = manifestPath.trim();
+    if (trimmedManifestPath.length === 0) {
         return {
             checked: false,
             source_type: 'local-pack',
@@ -129,11 +299,12 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
             release_notes: null,
             status: 'invalid_config',
             message: 'brainclaw_update_source.manifest_path must not be empty.',
+            default_source: false,
         };
     }
-    const resolvedManifestPath = path.isAbsolute(manifestPath)
-        ? manifestPath
-        : path.resolve(cwd, manifestPath);
+    const resolvedManifestPath = path.isAbsolute(trimmedManifestPath)
+        ? trimmedManifestPath
+        : path.resolve(cwd, trimmedManifestPath);
     if (!fs.existsSync(resolvedManifestPath)) {
         return {
             checked: true,
@@ -145,6 +316,7 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
             release_notes: null,
             status: 'check_failed',
             message: `The configured local-pack manifest was not found: ${resolvedManifestPath}`,
+            default_source: false,
         };
     }
     try {
@@ -162,6 +334,7 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
                 release_notes: manifest.release_notes?.trim() || config?.brainclaw_upgrade_message?.trim() || null,
                 status: 'check_failed',
                 message: `The local-pack manifest has an invalid latest_installable_version: ${manifest.latest_installable_version}`,
+                default_source: false,
             };
         }
         const artifactPath = manifest.artifact_path
@@ -182,6 +355,7 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
                 release_notes: releaseNotes,
                 status: 'update_available',
                 message: `A newer installable brainclaw build is available: ${latestVersion} (installed ${installedVersion}).`,
+                default_source: false,
             };
         }
         return {
@@ -194,6 +368,7 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
             release_notes: releaseNotes,
             status: 'up_to_date',
             message: `Installed brainclaw ${installedVersion} is up to date for the configured local-pack channel.`,
+            default_source: false,
         };
     }
     catch (error) {
@@ -208,59 +383,10 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
             release_notes: null,
             status: 'check_failed',
             message: `Failed to read the configured local-pack manifest: ${message}`,
+            default_source: false,
         };
     }
 }
-export function publishLocalBrainclawRelease(cwd, options = {}) {
-    const workspacePackage = readWorkspaceBrainclawPackage(cwd);
-    const outputDir = path.resolve(cwd, options.outputDir ?? DEFAULT_LOCAL_RELEASES_DIR);
-    const manifestPath = path.resolve(cwd, options.manifestPath ?? DEFAULT_LOCAL_RELEASE_MANIFEST_PATH);
-    fs.mkdirSync(outputDir, { recursive: true });
-    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
-    const packResult = spawnSync(resolveNpmCommand(), resolveNpmPackArgs(outputDir), {
-        cwd,
-        encoding: 'utf-8',
-        timeout: 120000,
-    });
-    if (packResult.error) {
-        throw new Error(`Failed to run npm pack: ${packResult.error.message}`);
-    }
-    if (packResult.status !== 0) {
-        throw new Error(firstNonEmptyLine(packResult.stderr) ?? firstNonEmptyLine(packResult.stdout) ?? 'npm pack failed');
-    }
-    const artifactFilename = parsePackedFilename(packResult.stdout);
-    if (!artifactFilename) {
-        throw new Error('npm pack did not report the generated tarball filename.');
-    }
-    const artifactAbsolutePath = path.join(outputDir, artifactFilename);
-    if (!fs.existsSync(artifactAbsolutePath)) {
-        throw new Error(`npm pack reported ${artifactFilename}, but the tarball was not found in ${outputDir}.`);
-    }
-    const manifestArtifactPath = toManifestRelativePath(path.relative(path.dirname(manifestPath), artifactAbsolutePath));
-    const projectArtifactPath = toManifestRelativePath(path.relative(cwd, artifactAbsolutePath));
-    const projectManifestPath = toPortablePath(path.relative(cwd, manifestPath));
-    const installCommand = `npm install -g "${projectArtifactPath}"`;
-    const releaseNotes = options.releaseNotes?.trim() || null;
-    const manifest = BrainclawLocalReleaseManifestSchema.parse({
-        version: 1,
-        channel: 'local-pack',
-        package_name: workspacePackage.name,
-        latest_installable_version: workspacePackage.version,
-        published_at: new Date().toISOString(),
-        artifact_path: manifestArtifactPath,
-        install_command: installCommand,
-        release_notes: releaseNotes ?? undefined,
-    });
-    fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
-    return {
-        package_name: workspacePackage.name,
-        workspace_version: workspacePackage.version,
-        manifest_path: projectManifestPath,
-        artifact_path: projectArtifactPath,
-        install_command: installCommand,
-        release_notes: releaseNotes,
-    };
-}
 function resolveNpmCommand() {
     return process.platform === 'win32' ? (process.env.ComSpec?.trim() || 'cmd.exe') : 'npm';
 }
@@ -270,6 +396,12 @@ function resolveNpmPackArgs(outputDir) {
     }
     return ['pack', '--json', '--pack-destination', outputDir];
 }
+function resolveNpmViewArgs(packageName) {
+    if (process.platform === 'win32') {
+        return ['/d', '/s', '/c', 'npm', 'view', packageName, 'dist-tags', '--json'];
+    }
+    return ['view', packageName, 'dist-tags', '--json'];
+}
 function findOwnPackageJson() {
     let currentDir = path.dirname(fileURLToPath(import.meta.url));
     while (true) {
@@ -331,6 +463,115 @@ function parsePackedFilename(stdout) {
         return firstNonEmptyLine(stdout);
     }
 }
+function lookupNpmDistTags(packageName, options) {
+    const now = options.now ?? new Date();
+    const cachePath = resolveNpmUpdateCachePath(packageName);
+    const ttlMs = options.cacheTtlMs ?? DEFAULT_INSTALLABLE_UPDATE_CACHE_TTL_MS;
+    const cached = readCachedNpmDistTags(cachePath, packageName, now, ttlMs);
+    if (cached) {
+        return cached;
+    }
+    const viewResult = spawnSync(resolveNpmCommand(), resolveNpmViewArgs(packageName), {
+        cwd: options.cwd,
+        encoding: 'utf-8',
+        timeout: 15000,
+    });
+    if (viewResult.error) {
+        throw new Error(`npm view failed: ${viewResult.error.message}`);
+    }
+    if (viewResult.status !== 0) {
+        throw new Error(firstNonEmptyLine(viewResult.stderr) ?? firstNonEmptyLine(viewResult.stdout) ?? 'npm view failed');
+    }
+    const distTags = parseNpmDistTags(viewResult.stdout);
+    const result = {
+        dist_tags: distTags,
+        checked_at: now.toISOString(),
+        cached: false,
+    };
+    writeCachedNpmDistTags(cachePath, {
+        version: 1,
+        package_name: packageName,
+        fetched_at: result.checked_at,
+        dist_tags: distTags,
+    });
+    return result;
+}
+function parseNpmDistTags(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`npm view returned invalid JSON: ${message}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('npm view did not return a dist-tag object.');
+    }
+    const distTags = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value === 'string' && value.trim().length > 0) {
+            distTags[key] = value.trim();
+        }
+    }
+    if (Object.keys(distTags).length === 0) {
+        throw new Error('npm view returned an empty dist-tag object.');
+    }
+    return distTags;
+}
+function resolveNpmUpdateCachePath(packageName) {
+    const safeName = packageName.replace(/[^a-z0-9._-]+/gi, '_').replace(/^_+|_+$/g, '') || DEFAULT_NPM_UPDATE_PACKAGE;
+    return path.join(os.homedir(), '.brainclaw', 'cache', 'installable-updates', `${safeName}.json`);
+}
+function readCachedNpmDistTags(cachePath, packageName, now, ttlMs) {
+    if (!fs.existsSync(cachePath)) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+        if (parsed.version !== 1
+            || parsed.package_name !== packageName
+            || typeof parsed.fetched_at !== 'string'
+            || !parsed.dist_tags
+            || typeof parsed.dist_tags !== 'object'
+            || Array.isArray(parsed.dist_tags)) {
+            return undefined;
+        }
+        const fetchedAt = Date.parse(parsed.fetched_at);
+        if (!Number.isFinite(fetchedAt) || now.getTime() - fetchedAt > ttlMs) {
+            return undefined;
+        }
+        const distTags = {};
+        for (const [key, value] of Object.entries(parsed.dist_tags)) {
+            if (typeof value === 'string' && value.trim().length > 0) {
+                distTags[key] = value.trim();
+            }
+        }
+        if (Object.keys(distTags).length === 0) {
+            return undefined;
+        }
+        return {
+            dist_tags: distTags,
+            checked_at: parsed.fetched_at,
+            cached: true,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeCachedNpmDistTags(cachePath, document) {
+    try {
+        fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+        fs.writeFileSync(cachePath, `${JSON.stringify(document, null, 2)}\n`, 'utf-8');
+    }
+    catch {
+        // Cache writes are best-effort only.
+    }
+}
+function formatNpmSourceDescription(packageName, distTag, defaultSource) {
+    return defaultSource ? `${packageName}@${distTag} (default npm channel)` : `${packageName}@${distTag}`;
+}
 function firstNonEmptyLine(value) {
     return value
         .split(/\r?\n/)

package/docs/cli.md

@@ -133,7 +133,7 @@ brainclaw bootstrap --apply -y
 
 ### `brainclaw env`
 
-Display environment and tooling detection information.
+Display environment, tooling detection, and installable Brainclaw update information.
 
 | Option | Description |
 |---|---|
@@ -146,6 +146,8 @@ brainclaw env --json
 brainclaw env --agent-tooling
 ```
 
+When the project does not pin a local release channel, `brainclaw env` checks the public npm `latest` channel for installable updates. Projects can override that with `brainclaw_update_source`, for example to use `prelaunch` or a local-pack manifest.
+
 ---
 
 ## Memory Management
@@ -1253,3 +1255,10 @@ brainclaw version
 brainclaw version --check
 brainclaw version --publish-local --release-notes "Add estimation-report command"
 ```
+
+`brainclaw version --check` now follows this order:
+
+- if `brainclaw_update_source` is configured, use it
+- otherwise, fall back to the public npm channel `brainclaw@latest`
+
+This keeps end-user installs aware of published npm releases without requiring a local tarball channel. To keep beta testers on a different channel, set `brainclaw_update_source` to `type: npm` with a different `dist_tag`, such as `prelaunch`.

package/docs/integrations/mcp.md

@@ -16,16 +16,19 @@ MCP matters because Brainclaw's value is mostly in dynamic state:
 
 Static files still help, but they age immediately. MCP is the stronger path for live coordination.
 
+That now also includes Brainclaw's own install channel state: `bclaw_get_execution_context` surfaces whether a newer npm or local-pack build is available, so the agent can notice upgrades without relying on a human to run `brainclaw version --check`.
+
 ## Recommended Agent Pattern
 
 The default dynamic workflow is:
 
 1. `bclaw_session_start` to open work and get the current board/context
-2. `bclaw_get_context` when the target path or task changes
-3. `bclaw_list_plans` and `bclaw_list_claims` to inspect active work
-4. `bclaw_claim` before editing
-5. `bclaw_write_note` for runtime observations
-6. `bclaw_session_end` to close cleanly and hand work off
+2. `bclaw_get_execution_context` early in the session when the agent needs local tooling signals or package update visibility
+3. `bclaw_get_context` when the target path or task changes
+4. `bclaw_list_plans` and `bclaw_list_claims` to inspect active work
+5. `bclaw_claim` before editing
+6. `bclaw_write_note` for runtime observations
+7. `bclaw_session_end` to close cleanly and hand work off
 
 This keeps session continuity inside Brainclaw instead of pushing the agent back to manual CLI usage.
 
@@ -35,7 +38,7 @@ This keeps session continuity inside Brainclaw instead of pushing the agent back
 |---|---|
 | `bclaw_get_context` | Ranked prompt-ready context, supports `digest: true` |
 | `bclaw_bootstrap` | Derive brownfield bootstrap signals, return adaptive interview prompts, accept structured interview answers, and preview/apply a selective import proposal |
-| `bclaw_get_execution_context` | Inspect local execution context and agent tooling |
+| `bclaw_get_execution_context` | Inspect local execution context, installable update status, and agent tooling |
 | `bclaw_write_note` | Record a runtime note, supports `autoReflect: true` |
 | `bclaw_read_handoff` | Read active handoffs |
 | `bclaw_get_agent_board` | Coordination snapshot |
@@ -65,6 +68,8 @@ brainclaw mcp
 
 In practice, most agents pick this up through generated MCP config such as `.mcp.json`, `~/.cursor/mcp.json`, or other agent-specific config files written by `brainclaw setup`, `brainclaw init`, or `brainclaw export`.
 
+By default, installable update checks use the public npm channel `brainclaw@latest`. Projects that need a different channel can override `brainclaw_update_source`, for example with `type: npm` and `dist_tag: prelaunch`, or with `type: local-pack` for local tarball workflows.
+
 ## Bootstrap Through MCP
 
 For agent-first onboarding, `bclaw_bootstrap` is the nominal path:

package/docs/quickstart.md

@@ -39,6 +39,7 @@ After the workspace is initialized, the nominal flow is:
 
 ```text
 bclaw_session_start   -> open a session and return current board/context
+bclaw_get_execution_context -> inspect local tooling and notice package updates
 bclaw_get_context     -> fetch fresh prompt-ready context for the target path
 bclaw_list_plans      -> inspect active work
 bclaw_claim           -> claim scope before editing
@@ -48,6 +49,8 @@ bclaw_session_end     -> close session cleanly and hand work off
 
 Use native agent files such as `AGENTS.md`, `CLAUDE.md`, or Cursor rules as local workflow guidance, not as the only source of live state.
 
+Unless the project overrides `brainclaw_update_source`, `bclaw_get_execution_context` checks the public npm `latest` channel so the agent can notice when a newer Brainclaw release is available.
+
 ## Path 2: CLI-Oriented Agent Or Fallback Workflow
 
 Use this path when the agent does not have a good MCP integration yet, or when a human needs to drive the workflow directly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainclaw",
-  "version": "0.19.11",
+  "version": "0.19.12",
   "description": "Shared project memory for humans and coding agents.",
   "type": "module",
   "bin": {