claude-dev-env 8.33.1 → 8.34.0

package/bin/install-pstack-plugin.mjs

@@ -8,64 +8,94 @@ export const PSTACK_PLUGIN_HOSTS = Object.freeze(['claude', 'codex']);
 export const PSTACK_PLUGIN_OPT_OUT_FLAG = '--no-pstack';
 export const PSTACK_PLUGIN_OPT_OUT_VARIABLE = 'CDE_INSTALL_PSTACK';
 
-const HOST_PLANS = Object.freeze({
+export const PSTACK_PLUGIN_SPEC = Object.freeze({
+    name: 'pstack',
+    label: 'Pstack',
+    marketplaceRepository: PSTACK_MARKETPLACE_REPOSITORY,
+    marketplaceAddArguments: Object.freeze([]),
+    pluginIdentifier: PSTACK_PLUGIN_IDENTIFIER,
+    hosts: PSTACK_PLUGIN_HOSTS,
+    optOutFlag: PSTACK_PLUGIN_OPT_OUT_FLAG,
+    optOutVariable: PSTACK_PLUGIN_OPT_OUT_VARIABLE,
+});
+
+export const USAGE_WRAPUP_PLUGIN_SPEC = Object.freeze({
+    name: 'usage-wrapup',
+    label: 'Usage-wrapup',
+    marketplaceRepository: 'jl-cmd/claude-dev-env',
+    marketplaceAddArguments: Object.freeze(['--sparse', '.claude-plugin']),
+    pluginIdentifier: 'usage-wrapup@claude-dev-env',
+    hosts: Object.freeze(['claude']),
+    optOutFlag: '--no-usage-wrapup',
+    optOutVariable: 'CDE_INSTALL_USAGE_WRAPUP',
+});
+
+const HOST_DEFINITIONS = Object.freeze({
     claude: Object.freeze({
         executable: 'claude',
         executableVariable: 'CDE_CLAUDE_EXECUTABLE',
         homeVariable: 'CLAUDE_CONFIG_DIR',
-        commands: Object.freeze([
-            Object.freeze(['plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY]),
-            Object.freeze(['plugin', 'install', PSTACK_PLUGIN_IDENTIFIER]),
-        ]),
+        installVerb: 'install',
     }),
     codex: Object.freeze({
         executable: 'codex',
         executableVariable: 'CDE_CODEX_EXECUTABLE',
         homeVariable: 'CODEX_HOME',
-        commands: Object.freeze([
-            Object.freeze(['plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY]),
-            Object.freeze(['plugin', 'add', PSTACK_PLUGIN_IDENTIFIER]),
-        ]),
+        installVerb: 'add',
     }),
 });
 
 /**
- * Read the marketplace and plugin commands one host installs pstack with.
+ * Read the marketplace and plugin commands one host installs a plugin with.
  *
- * Claude Code and Codex publish the same marketplace under different plugin
- * verbs, so the command list belongs to the host rather than to the caller.
+ * Claude Code and Codex publish a marketplace under different plugin verbs, so
+ * the install verb belongs to the host and the marketplace and identifier
+ * belong to the plugin spec. A spec whose marketplace is a large repository
+ * passes `--sparse .claude-plugin` among its marketplace add arguments, so the
+ * clone holds only the catalog and stays clear of Windows path-length limits.
  *
- * @param {string} host Either `claude` or `codex`.
+ * @param {typeof PSTACK_PLUGIN_SPEC} spec The plugin to install.
+ * @param {string} host A host the spec names, `claude` or `codex`.
  * @returns {{executable: string, executableVariable: string, homeVariable: string,
  *   commands: ReadonlyArray<ReadonlyArray<string>>}} The host's install plan.
  */
-export function pstackPluginPlan(host) {
-    const plan = HOST_PLANS[host];
-    if (!plan) {
+export function marketplacePluginPlan(spec, host) {
+    const hostDefinition = HOST_DEFINITIONS[host];
+    if (!hostDefinition || !spec.hosts.includes(host)) {
         throw new Error(
-            `Unsupported pstack plugin host ${host}: this installer knows ${PSTACK_PLUGIN_HOSTS.join(', ')}.`,
+            `Unsupported ${spec.name} plugin host ${host}: this installer knows ${spec.hosts.join(', ')}.`,
         );
     }
-    return plan;
+    return {
+        executable: hostDefinition.executable,
+        executableVariable: hostDefinition.executableVariable,
+        homeVariable: hostDefinition.homeVariable,
+        commands: [
+            ['plugin', 'marketplace', 'add', spec.marketplaceRepository, ...spec.marketplaceAddArguments],
+            ['plugin', hostDefinition.installVerb, spec.pluginIdentifier],
+        ],
+    };
 }
 
 /**
- * Decide whether a full install also installs the pstack plugin.
+ * Decide whether a full install also installs one marketplace plugin.
  *
- * The step reaches the network for the marketplace repository. `--no-pstack`
- * on the command line, or `CDE_INSTALL_PSTACK=0` in the environment, turns it
- * off for an air-gapped or offline run.
+ * The step reaches the network for the marketplace repository. The spec's
+ * opt-out flag on the command line, or its opt-out variable set to `0` in the
+ * environment, turns it off for an air-gapped or offline run.
  *
+ * @param {typeof PSTACK_PLUGIN_SPEC} spec The plugin to install.
  * @param {string[]} [argumentList] The command-line arguments after the script.
  * @param {Record<string, string|undefined>} [environment] The process environment.
- * @returns {boolean} True when this run installs the pstack plugin.
+ * @returns {boolean} True when this run installs the plugin.
  */
-export function shouldInstallPstackPlugin(
+export function shouldInstallMarketplacePlugin(
+    spec,
     argumentList = process.argv.slice(2),
     environment = process.env,
 ) {
-    if (argumentList.includes(PSTACK_PLUGIN_OPT_OUT_FLAG)) return false;
-    return environment[PSTACK_PLUGIN_OPT_OUT_VARIABLE] !== '0';
+    if (argumentList.includes(spec.optOutFlag)) return false;
+    return environment[spec.optOutVariable] !== '0';
 }
 
 /**
@@ -126,8 +156,8 @@ function firstLine(text) {
     return trimmed.split(/\r?\n/).filter(Boolean).at(-1);
 }
 
-function installForHost(host, homeDirectory, environment, runCommand) {
-    const plan = pstackPluginPlan(host);
+function installForHost(spec, host, homeDirectory, environment, runCommand) {
+    const plan = marketplacePluginPlan(spec, host);
     const executable = environment[plan.executableVariable] || plan.executable;
     const commandEnvironment = { [plan.homeVariable]: homeDirectory };
     for (const commandArguments of plan.commands) {
@@ -139,7 +169,7 @@ function installForHost(host, homeDirectory, environment, runCommand) {
                 host,
                 executable,
                 status: 'skipped',
-                warning: `${executable} is not on PATH, so pstack was not installed for ${host}.`,
+                warning: `${executable} is not on PATH, so ${spec.name} was not installed for ${host}.`,
             };
         }
         if (outcome.status !== 0 || outcome.error) {
@@ -156,7 +186,7 @@ function installForHost(host, homeDirectory, environment, runCommand) {
 }
 
 /**
- * Install the pstack plugin from its marketplace into each host's own home.
+ * Install one plugin from its marketplace into each host's own home.
  *
  * Each host is one member of the batch. A host without its command-line tool
  * is skipped and a host whose command fails is reported, so the rules, hooks,
@@ -165,20 +195,22 @@ function installForHost(host, homeDirectory, environment, runCommand) {
  * `cmd.exe`'s command-not-found exit code on Windows, and both read as
  * skipped.
  *
+ * @param {typeof PSTACK_PLUGIN_SPEC} spec The plugin to install.
  * @param {object} [options] Install targets.
  * @param {string} [options.claudeRoot] The managed Claude root to install into.
  * @param {string} [options.codexHome] The Codex home to install into.
- * @param {string[]} [options.hosts] The hosts to install. Defaults to both.
+ * @param {string[]} [options.hosts] The hosts to install. Defaults to the spec's hosts.
  * @param {Record<string, string|undefined>} [options.environment] The process environment.
  * @param {object} [dependencies] Seams for the command runner.
  * @returns {{status: string, hosts: object[], warning: string|null}} The outcome per host.
  */
-export function installPstackPlugin(options = {}, dependencies = {}) {
+export function installMarketplacePlugin(spec, options = {}, dependencies = {}) {
     const environment = options.environment ?? process.env;
     const runCommand = dependencies.runCommand ?? runHostCommand;
     const homeDirectories = { claude: options.claudeRoot, codex: options.codexHome };
-    const hosts = options.hosts ?? PSTACK_PLUGIN_HOSTS;
+    const hosts = options.hosts ?? spec.hosts;
     const hostOutcomes = hosts.map(host => installForHost(
+        spec,
         host,
         homeDirectories[host],
         environment,

package/bin/install-pstack-plugin.test.mjs

@@ -1,13 +1,16 @@
 import { test } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
 import {
     PSTACK_MARKETPLACE_REPOSITORY,
     PSTACK_PLUGIN_HOSTS,
     PSTACK_PLUGIN_IDENTIFIER,
+    PSTACK_PLUGIN_SPEC,
+    USAGE_WRAPUP_PLUGIN_SPEC,
     hostCommandInvocation,
-    installPstackPlugin,
-    pstackPluginPlan,
-    shouldInstallPstackPlugin,
+    installMarketplacePlugin,
+    marketplacePluginPlan,
+    shouldInstallMarketplacePlugin,
 } from './install-pstack-plugin.mjs';
 
 function recordingRunner(outcomeForCommand = () => ({ status: 0, stderr: '' })) {
@@ -30,7 +33,7 @@ const ROOTS = Object.freeze({
 const WINDOWS_ENVIRONMENT = Object.freeze({ ComSpec: 'C:\\Windows\\system32\\cmd.exe' });
 
 test('the Claude plan carries the two documented plugin commands', () => {
-    const plan = pstackPluginPlan('claude');
+    const plan = marketplacePluginPlan(PSTACK_PLUGIN_SPEC, 'claude');
     assert.equal(plan.executable, 'claude');
     assert.deepEqual(plan.commands, [
         ['plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY],
@@ -39,7 +42,7 @@ test('the Claude plan carries the two documented plugin commands', () => {
 });
 
 test('the Codex plan adds the plugin with the Codex verb', () => {
-    const plan = pstackPluginPlan('codex');
+    const plan = marketplacePluginPlan(PSTACK_PLUGIN_SPEC, 'codex');
     assert.equal(plan.executable, 'codex');
     assert.deepEqual(plan.commands, [
         ['plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY],
@@ -48,13 +51,13 @@ test('the Codex plan adds the plugin with the Codex verb', () => {
 });
 
 test('an unsupported host names the hosts this installer knows', () => {
-    assert.throws(() => pstackPluginPlan('cursor'), /cursor/);
+    assert.throws(() => marketplacePluginPlan(PSTACK_PLUGIN_SPEC, 'cursor'), /cursor/);
     assert.deepEqual(PSTACK_PLUGIN_HOSTS, ['claude', 'codex']);
 });
 
 test('each host installs into the managed root this run wrote', () => {
     const runner = recordingRunner();
-    const outcome = installPstackPlugin(ROOTS, runner);
+    const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, ROOTS, runner);
     assert.equal(outcome.status, 'installed');
     assert.deepEqual(runner.calls.map(call => [call.executable, ...call.commandArguments]), [
         ['claude', 'plugin', 'marketplace', 'add', PSTACK_MARKETPLACE_REPOSITORY],
@@ -70,7 +73,7 @@ test('an absent host command skips that host and leaves the other installed', ()
     const runner = recordingRunner((executable) => (executable === 'codex'
         ? { status: null, error: Object.assign(new Error('spawn codex ENOENT'), { code: 'ENOENT' }) }
         : { status: 0, stderr: '' }));
-    const outcome = installPstackPlugin(ROOTS, runner);
+    const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, ROOTS, runner);
     assert.equal(outcome.hosts.find(host => host.host === 'claude').status, 'installed');
     const codex = outcome.hosts.find(host => host.host === 'codex');
     assert.equal(codex.status, 'skipped');
@@ -83,7 +86,7 @@ test('a failing command reports that host and still installs the next one', () =
         executable === 'claude' && commandArguments[1] === 'marketplace'
             ? { status: 1, stderr: 'marketplace unreachable' }
             : { status: 0, stderr: '' }));
-    const outcome = installPstackPlugin(ROOTS, runner);
+    const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, ROOTS, runner);
     assert.equal(outcome.status, 'failed');
     const claude = outcome.hosts.find(host => host.host === 'claude');
     assert.equal(claude.status, 'failed');
@@ -94,7 +97,8 @@ test('a failing command reports that host and still installs the next one', () =
 
 test('an executable override replaces the host command for that host only', () => {
     const runner = recordingRunner();
-    installPstackPlugin(
+    installMarketplacePlugin(
+        PSTACK_PLUGIN_SPEC,
         { ...ROOTS, environment: { CDE_CODEX_EXECUTABLE: '/opt/codex/bin/codex' } },
         runner,
     );
@@ -105,15 +109,15 @@ test('an executable override replaces the host command for that host only', () =
 });
 
 test('the opt-out flag and variable both turn the step off', () => {
-    assert.equal(shouldInstallPstackPlugin([], {}), true);
-    assert.equal(shouldInstallPstackPlugin(['--no-pstack'], {}), false);
-    assert.equal(shouldInstallPstackPlugin([], { CDE_INSTALL_PSTACK: '0' }), false);
-    assert.equal(shouldInstallPstackPlugin([], { CDE_INSTALL_PSTACK: '1' }), true);
+    assert.equal(shouldInstallMarketplacePlugin(PSTACK_PLUGIN_SPEC, [], {}), true);
+    assert.equal(shouldInstallMarketplacePlugin(PSTACK_PLUGIN_SPEC, ['--no-pstack'], {}), false);
+    assert.equal(shouldInstallMarketplacePlugin(PSTACK_PLUGIN_SPEC, [], { CDE_INSTALL_PSTACK: '0' }), false);
+    assert.equal(shouldInstallMarketplacePlugin(PSTACK_PLUGIN_SPEC, [], { CDE_INSTALL_PSTACK: '1' }), true);
 });
 
 test('a selected host list installs only that host', () => {
     const runner = recordingRunner();
-    const outcome = installPstackPlugin({ ...ROOTS, hosts: ['codex'] }, runner);
+    const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, { ...ROOTS, hosts: ['codex'] }, runner);
     assert.deepEqual(outcome.hosts.map(host => host.host), ['codex']);
     assert.deepEqual([...new Set(runner.calls.map(call => call.executable))], ['codex']);
 });
@@ -166,7 +170,7 @@ test("cmd.exe's command-not-found exit code reads as an absent host, not a failu
             stderr: "'codex' is not recognized as an internal or external command,\noperable program or batch file.",
         }
         : { status: 0, stderr: '' }));
-    const outcome = installPstackPlugin(ROOTS, runner);
+    const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, ROOTS, runner);
     const codex = outcome.hosts.find(host => host.host === 'codex');
     assert.equal(codex.status, 'skipped');
     assert.equal(outcome.status, 'installed');
@@ -175,7 +179,79 @@ test("cmd.exe's command-not-found exit code reads as an absent host, not a failu
 
 test('a non-zero exit that is not command-not-found still reads as a failure', () => {
     const runner = recordingRunner(() => ({ status: 9009, stderr: 'the marketplace rejected the catalog' }));
-    const outcome = installPstackPlugin({ ...ROOTS, hosts: ['claude'] }, runner);
+    const outcome = installMarketplacePlugin(PSTACK_PLUGIN_SPEC, { ...ROOTS, hosts: ['claude'] }, runner);
     assert.equal(outcome.hosts[0].status, 'failed');
     assert.match(outcome.hosts[0].warning, /rejected the catalog/);
 });
+
+const USAGE_WRAPUP_PINNED_COMMIT = 'd78c314e5787786e866bf5c4967107365854dc78';
+
+test('the usage-wrapup plan adds this repository marketplace and installs the plugin on Claude', () => {
+    const plan = marketplacePluginPlan(USAGE_WRAPUP_PLUGIN_SPEC, 'claude');
+    assert.equal(plan.executable, 'claude');
+    assert.equal(plan.homeVariable, 'CLAUDE_CONFIG_DIR');
+    assert.deepEqual(plan.commands, [
+        ['plugin', 'marketplace', 'add', 'jl-cmd/claude-dev-env', '--sparse', '.claude-plugin'],
+        ['plugin', 'install', 'usage-wrapup@claude-dev-env'],
+    ]);
+});
+
+test('usage-wrapup is a Claude-only plugin and refuses a Codex plan', () => {
+    assert.deepEqual(USAGE_WRAPUP_PLUGIN_SPEC.hosts, ['claude']);
+    assert.throws(() => marketplacePluginPlan(USAGE_WRAPUP_PLUGIN_SPEC, 'codex'), /usage-wrapup plugin host codex/);
+});
+
+test('installing usage-wrapup runs only the Claude commands, inside the managed Claude root', () => {
+    const runner = recordingRunner();
+    const outcome = installMarketplacePlugin(USAGE_WRAPUP_PLUGIN_SPEC, ROOTS, runner);
+    assert.equal(outcome.status, 'installed');
+    assert.deepEqual(outcome.hosts.map(host => host.host), ['claude']);
+    assert.deepEqual(runner.calls.map(call => [call.executable, ...call.commandArguments]), [
+        ['claude', 'plugin', 'marketplace', 'add', 'jl-cmd/claude-dev-env', '--sparse', '.claude-plugin'],
+        ['claude', 'plugin', 'install', 'usage-wrapup@claude-dev-env'],
+    ]);
+    for (const call of runner.calls) {
+        assert.deepEqual(call.environment, { CLAUDE_CONFIG_DIR: ROOTS.claudeRoot });
+    }
+});
+
+test('an absent claude command skips usage-wrapup and names the plugin in the warning', () => {
+    const runner = recordingRunner(() => ({
+        status: null,
+        error: Object.assign(new Error('spawn claude ENOENT'), { code: 'ENOENT' }),
+    }));
+    const outcome = installMarketplacePlugin(USAGE_WRAPUP_PLUGIN_SPEC, ROOTS, runner);
+    assert.equal(outcome.status, 'skipped');
+    assert.match(outcome.warning, /usage-wrapup was not installed for claude/);
+});
+
+test('the usage-wrapup opt-out flag and variable turn off only usage-wrapup', () => {
+    assert.equal(shouldInstallMarketplacePlugin(USAGE_WRAPUP_PLUGIN_SPEC, [], {}), true);
+    assert.equal(shouldInstallMarketplacePlugin(USAGE_WRAPUP_PLUGIN_SPEC, ['--no-usage-wrapup'], {}), false);
+    assert.equal(
+        shouldInstallMarketplacePlugin(USAGE_WRAPUP_PLUGIN_SPEC, [], { CDE_INSTALL_USAGE_WRAPUP: '0' }),
+        false,
+    );
+    assert.equal(shouldInstallMarketplacePlugin(USAGE_WRAPUP_PLUGIN_SPEC, ['--no-pstack'], { CDE_INSTALL_PSTACK: '0' }), true);
+    assert.equal(
+        shouldInstallMarketplacePlugin(PSTACK_PLUGIN_SPEC, ['--no-usage-wrapup'], { CDE_INSTALL_USAGE_WRAPUP: '0' }),
+        true,
+    );
+});
+
+test('the repository marketplace lists usage-wrapup from the fork, pinned to the reviewed commit', () => {
+    const marketplace = JSON.parse(readFileSync(
+        new URL('../../../.claude-plugin/marketplace.json', import.meta.url),
+        'utf8',
+    ));
+    const [pluginName, marketplaceName] = USAGE_WRAPUP_PLUGIN_SPEC.pluginIdentifier.split('@');
+    assert.equal(marketplace.name, marketplaceName);
+    const entry = marketplace.plugins.find(plugin => plugin.name === pluginName);
+    assert.ok(entry, `the marketplace lists ${pluginName}`);
+    assert.deepEqual(entry.source, {
+        source: 'github',
+        repo: 'jl-cmd/usage-wrapup',
+        ref: 'main',
+        sha: USAGE_WRAPUP_PINNED_COMMIT,
+    });
+});

package/bin/install.agents-home.test.mjs

@@ -51,6 +51,7 @@ function runInstaller(homeDirectory, extraArguments, environmentOverrides = {})
     const installerEnvironment = {
         ...process.env,
         CDE_INSTALL_PSTACK: '0',
+        CDE_INSTALL_USAGE_WRAPUP: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),

package/bin/install.codex-rules.test.mjs

@@ -57,6 +57,7 @@ function runInstaller(homeDirectory, extraArguments) {
         env: {
             ...process.env,
             CDE_INSTALL_PSTACK: '0',
+            CDE_INSTALL_USAGE_WRAPUP: '0',
             HOME: homeDirectory,
             USERPROFILE: homeDirectory,
             GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
@@ -85,6 +86,7 @@ function scanTextWithProductionPiiScanner(scannedText) {
                 env: {
                     ...process.env,
                     CDE_INSTALL_PSTACK: '0',
+                    CDE_INSTALL_USAGE_WRAPUP: '0',
                     PYTHONPATH: BLOCKING_HOOKS_DIRECTORY,
                     CLAUDE_LOCAL_IDENTITY_PATH: join(
                         temporaryDirectory,

package/bin/install.cursor-rules.test.mjs

@@ -32,6 +32,7 @@ function runInstaller(homeDirectory, extraArguments, environmentOverrides = {})
         env: {
             ...process.env,
             CDE_INSTALL_PSTACK: '0',
+            CDE_INSTALL_USAGE_WRAPUP: '0',
             HOME: homeDirectory,
             USERPROFILE: homeDirectory,
             CODEX_HOME: join(homeDirectory, '.codex'),

package/bin/install.mjs

@@ -48,8 +48,10 @@ import {
     ALL_CODEX_NATIVE_PRE_TOOL_USE_MATCHERS,
 } from './install-constants.mjs';
 import {
-    installPstackPlugin,
-    shouldInstallPstackPlugin,
+    PSTACK_PLUGIN_SPEC,
+    USAGE_WRAPUP_PLUGIN_SPEC,
+    installMarketplacePlugin,
+    shouldInstallMarketplacePlugin,
 } from './install-pstack-plugin.mjs';
 import { seedCodexPstackModels } from './seed-codex-pstack-models.mjs';
 import {
@@ -404,12 +406,20 @@ export function pythonFileAndPrefixArguments(pythonCommand) {
  * @returns {{status: string, hosts: object[], warning: string|null}} The outcome.
  */
 export function installPstackPluginForHosts() {
-    return installPstackPlugin({
+    return installMarketplacePlugin(PSTACK_PLUGIN_SPEC, {
         claudeRoot: CLAUDE_HOME,
         codexHome: INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
     });
 }
 
+function printPluginHostOutcomes(spec, pluginOutcome) {
+    for (const eachHost of pluginOutcome.hosts) {
+        console.log(eachHost.warning
+            ? `  ${spec.label} (${eachHost.host}): ${eachHost.status} — ${eachHost.warning}`
+            : `  ${spec.label} (${eachHost.host}): ${eachHost.status}`);
+    }
+}
+
 function seedSubagentModelPolicy() {
     const policyDirectory = join(AGENTS_HOME, CURSOR_RULES_DIRECTORY_NAME);
     const policyPath = join(policyDirectory, SUBAGENT_MODEL_POLICY_FILE_NAME);
@@ -2762,7 +2772,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     }
     const packageGuidanceText = selectedGroups ? '' : readFileSync(join(PACKAGE_ROOT, 'AGENTS.md'), 'utf8');
     const allPackageGuidancePaths = [join(CLAUDE_HOME, 'AGENTS.md'), join(AGENTS_HOME, 'AGENTS.md')];
-    if (!selectedGroups && shouldInstallPstackPlugin()) {
+    if (!selectedGroups && shouldInstallMarketplacePlugin(PSTACK_PLUGIN_SPEC)) {
         const pstackPlugin = installPstackPluginForHosts();
         summary.pstackPlugin = pstackPlugin;
         if (pstackPlugin.hosts.some(host => host.host === 'codex' && host.status === 'installed')) {
@@ -2784,11 +2794,14 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
                 console.log(`  \u2713 ${skillLoadGuidancePath} (Codex skill-load line)`);
             }
         }
-        for (const eachHost of pstackPlugin.hosts) {
-            console.log(eachHost.warning
-                ? `  Pstack (${eachHost.host}): ${eachHost.status} \u2014 ${eachHost.warning}`
-                : `  Pstack (${eachHost.host}): ${eachHost.status}`);
-        }
+        printPluginHostOutcomes(PSTACK_PLUGIN_SPEC, pstackPlugin);
+    }
+    if (!selectedGroups && shouldInstallMarketplacePlugin(USAGE_WRAPUP_PLUGIN_SPEC)) {
+        const usageWrapupPlugin = installMarketplacePlugin(USAGE_WRAPUP_PLUGIN_SPEC, {
+            claudeRoot: CLAUDE_HOME,
+        });
+        summary.usageWrapupPlugin = usageWrapupPlugin;
+        printPluginHostOutcomes(USAGE_WRAPUP_PLUGIN_SPEC, usageWrapupPlugin);
     }
     if (!selectedGroups) {
         const packageGuidancePath = writeCodexPackageGuidance(
@@ -3324,6 +3337,7 @@ Usage:
   npx ${PACKAGE_NAME} --profile ID Install into one named profile root (under the profiles root)
   npx ${PACKAGE_NAME} --profiles A,B  Install into each selected profile (one ownership manifest per target)
   npx ${PACKAGE_NAME} --no-pstack  Full install without the pstack plugin (also CDE_INSTALL_PSTACK=0)
+  npx ${PACKAGE_NAME} --no-usage-wrapup  Full install without the usage-wrapup plugin (also CDE_INSTALL_USAGE_WRAPUP=0)
   npx ${PACKAGE_NAME} --uninstall  Remove installed files from the selected root
   npx ${PACKAGE_NAME} --help       Show this help
 

package/bin/install.prune.test.mjs

@@ -260,6 +260,7 @@ function resolveInstallerInvocation(homeDirectory) {
     const childEnvironment = {
         ...process.env,
         CDE_INSTALL_PSTACK: '0',
+        CDE_INSTALL_USAGE_WRAPUP: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),

package/bin/install.question-presentation.test.mjs

@@ -23,6 +23,7 @@ function installInScratchHome(homeDirectory, argumentsList = [], extraEnvironmen
         env: {
             ...process.env,
             CDE_INSTALL_PSTACK: '0',
+            CDE_INSTALL_USAGE_WRAPUP: '0',
             HOME: homeDirectory,
             USERPROFILE: homeDirectory,
             CODEX_HOME: join(homeDirectory, '.codex'),
@@ -177,6 +178,7 @@ test('a successful pstack install retains its skill block and gains the question
 
     const installation = installInScratchHome(homeDirectory, [], {
         CDE_INSTALL_PSTACK: '1',
+        CDE_INSTALL_USAGE_WRAPUP: '0',
         CDE_CODEX_EXECUTABLE: commandPath,
         CDE_CLAUDE_EXECUTABLE: commandPath,
     });
@@ -203,6 +205,7 @@ test('enabling pstack after a pstack-off install preserves question guidance', (
 
     const secondInstallation = installInScratchHome(homeDirectory, [], {
         CDE_INSTALL_PSTACK: '1',
+        CDE_INSTALL_USAGE_WRAPUP: '0',
         CDE_CODEX_EXECUTABLE: commandPath,
         CDE_CLAUDE_EXECUTABLE: commandPath,
     });
@@ -230,6 +233,7 @@ test('a failed pstack transition restores question-only guidance and removes its
 
     const failedInstallation = installInScratchHome(homeDirectory, [], {
         CDE_INSTALL_PSTACK: '1',
+        CDE_INSTALL_USAGE_WRAPUP: '0',
         CDE_CODEX_EXECUTABLE: commandPath,
         CDE_CLAUDE_EXECUTABLE: commandPath,
         CLAUDE_DEV_ENV_INSTALL_FAULT: 'after_file_staging',

package/bin/install.settings-defaults.test.mjs

@@ -57,6 +57,7 @@ function runInstallerInSandbox(sandboxHome, installerArguments = []) {
         env: {
             ...process.env,
             CDE_INSTALL_PSTACK: '0',
+            CDE_INSTALL_USAGE_WRAPUP: '0',
             HOME: sandboxHome,
             USERPROFILE: sandboxHome,
             GIT_CONFIG_GLOBAL: gitConfigGlobal,

package/bin/install.test.mjs

@@ -3034,6 +3034,7 @@ function runPstackInstaller(homeDirectory, extraArguments, environmentOverrides
             CLAUDE_CONFIG_DIR: join(homeDirectory, '.claude'),
             GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
             CDE_INSTALL_PSTACK: '1',
+            CDE_INSTALL_USAGE_WRAPUP: '0',
             ...environmentOverrides,
         },
     });
@@ -3267,6 +3268,81 @@ test('a pstack install after a --no-pstack install seeds the Codex model sheet',
     assert.ok(codexGuidance.includes(QUESTION_PRESENTATION_BLOCK_START));
 });
 
+const USAGE_WRAPUP_CLAUDE_COMMANDS = Object.freeze([
+    'claude plugin marketplace add jl-cmd/claude-dev-env --sparse .claude-plugin',
+    'claude plugin install usage-wrapup@claude-dev-env',
+]);
+
+function usageWrapupCommands(allRecordedCommands) {
+    return allRecordedCommands.filter(eachCommand => eachCommand.includes('claude-dev-env'));
+}
+
+test('a full install adds this marketplace and installs usage-wrapup on Claude only', t => {
+    const sandbox = pstackPluginSandbox(t);
+
+    const installerOutput = runPstackInstaller(sandbox.homeDirectory, [], {
+        ...sandbox.environment,
+        CDE_INSTALL_USAGE_WRAPUP: '1',
+    });
+
+    assert.deepEqual(usageWrapupCommands(sandbox.recordedCommands()), USAGE_WRAPUP_CLAUDE_COMMANDS);
+    assert.match(installerOutput, /Usage-wrapup \(claude\): installed/);
+    assert.doesNotMatch(installerOutput, /Usage-wrapup \(codex\)/);
+    assert.match(installerOutput, /Pstack \(claude\): installed/);
+});
+
+for (const [caseName, extraArguments, environmentOverrides] of [
+    ['--no-usage-wrapup', ['--no-usage-wrapup'], { CDE_INSTALL_USAGE_WRAPUP: '1' }],
+    ['CDE_INSTALL_USAGE_WRAPUP=0', [], { CDE_INSTALL_USAGE_WRAPUP: '0' }],
+    ['an --only run', ['--only', 'core'], { CDE_INSTALL_USAGE_WRAPUP: '1' }],
+]) {
+    test(`${caseName} skips usage-wrapup`, t => {
+        const sandbox = pstackPluginSandbox(t);
+
+        const installerOutput = runPstackInstaller(sandbox.homeDirectory, extraArguments, {
+            ...sandbox.environment,
+            ...environmentOverrides,
+        });
+
+        assert.deepEqual(usageWrapupCommands(sandbox.recordedCommands()), []);
+        assert.doesNotMatch(installerOutput, /Usage-wrapup \(/);
+    });
+}
+
+test('a failing usage-wrapup command is reported and the install still succeeds', t => {
+    const sandbox = pstackPluginSandbox(t);
+    const failingCommandPath = join(
+        sandbox.homeDirectory,
+        process.platform === 'win32' ? 'failing-claude.cmd' : 'failing-claude',
+    );
+    writeFileSync(
+        failingCommandPath,
+        process.platform === 'win32'
+            ? '@echo off\r\necho marketplace unreachable 1>&2\r\nexit /b 1\r\n'
+            : '#!/bin/sh\necho marketplace unreachable >&2\nexit 1\n',
+        { mode: 0o755 },
+    );
+
+    const installerOutput = runPstackInstaller(sandbox.homeDirectory, ['--no-pstack'], {
+        ...sandbox.environment,
+        CDE_CLAUDE_EXECUTABLE: failingCommandPath,
+        CDE_INSTALL_USAGE_WRAPUP: '1',
+    });
+
+    assert.match(installerOutput, /Usage-wrapup \(claude\): failed .*marketplace unreachable/);
+    assert.ok(existsSync(join(sandbox.homeDirectory, '.claude', '.claude-dev-env-manifest.json')));
+});
+
+test('the help output names the usage-wrapup opt-out beside the pstack one', () => {
+    const helpRun = spawnSync(process.execPath, [PSTACK_TEST_INSTALLER_PATH, '--help'], {
+        encoding: 'utf8',
+        env: process.env,
+    });
+
+    assert.equal(helpRun.status, 0, helpRun.stderr);
+    assert.match(helpRun.stdout, /--no-pstack .*\n.*--no-usage-wrapup .*CDE_INSTALL_USAGE_WRAPUP=0/);
+});
+
 function continuityCommandCount(configurationPath) {
     if (!existsSync(configurationPath)) return 0;
     const configuration = JSON.parse(readFileSync(configurationPath, 'utf8'));

package/bin/install.transaction.test.mjs

@@ -84,6 +84,7 @@ test('capture and restore recover settings, manifest, files, and hooksPath', ()
     const env = {
         ...process.env,
         CDE_INSTALL_PSTACK: '0',
+        CDE_INSTALL_USAGE_WRAPUP: '0',
         HOME: box.root,
         USERPROFILE: box.root,
         GIT_CONFIG_GLOBAL: gitConfigPath,
@@ -145,6 +146,7 @@ test('capture and restore recover an additional host settings file', () => {
         env: {
             ...process.env,
             CDE_INSTALL_PSTACK: '0',
+            CDE_INSTALL_USAGE_WRAPUP: '0',
             HOME: box.root,
             USERPROFILE: box.root,
             GIT_CONFIG_GLOBAL: gitConfigPath,
@@ -179,6 +181,7 @@ test('runWithInstallTransaction restores prior state on injected fault', () => {
     const env = {
         ...process.env,
         CDE_INSTALL_PSTACK: '0',
+        CDE_INSTALL_USAGE_WRAPUP: '0',
         HOME: box.root,
         USERPROFILE: box.root,
         GIT_CONFIG_GLOBAL: gitConfigPath,
@@ -232,6 +235,7 @@ test('runWithInstallTransaction commits and discards journal on success', () =>
         env: {
             ...process.env,
             CDE_INSTALL_PSTACK: '0',
+            CDE_INSTALL_USAGE_WRAPUP: '0',
             HOME: box.root,
             USERPROFILE: box.root,
             GIT_CONFIG_GLOBAL: gitConfigPath,
@@ -274,6 +278,7 @@ function runInstaller(homeDirectory, extraArguments, options = {}) {
     const childEnvironment = {
         ...process.env,
         CDE_INSTALL_PSTACK: '0',
+        CDE_INSTALL_USAGE_WRAPUP: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
@@ -308,6 +313,7 @@ test('a later install fault removes newly seeded Codex pstack files', () => {
             faultPhase: FAULT_PHASES.AFTER_MANIFEST_WRITE,
             environment: {
                 CDE_INSTALL_PSTACK: '1',
+                CDE_INSTALL_USAGE_WRAPUP: '0',
                 CDE_CODEX_EXECUTABLE: codexCommandPath,
             },
         });
@@ -450,6 +456,7 @@ test('installer fault after_git_config restores prior core.hooksPath', () => {
             env: {
                 ...process.env,
                 CDE_INSTALL_PSTACK: '0',
+                CDE_INSTALL_USAGE_WRAPUP: '0',
                 HOME: homeDirectory,
                 USERPROFILE: homeDirectory,
                 GIT_CONFIG_GLOBAL: gitConfigPath,
@@ -466,6 +473,7 @@ test('installer fault after_git_config restores prior core.hooksPath', () => {
             env: {
                 ...process.env,
                 CDE_INSTALL_PSTACK: '0',
+                CDE_INSTALL_USAGE_WRAPUP: '0',
                 HOME: homeDirectory,
                 USERPROFILE: homeDirectory,
                 GIT_CONFIG_GLOBAL: gitConfigPath,

package/bin/install.uninstall-transaction.test.mjs

@@ -72,6 +72,7 @@ function runInstaller(homeDirectory, extraArguments, options = {}) {
     const childEnvironment = {
         ...process.env,
         CDE_INSTALL_PSTACK: '0',
+        CDE_INSTALL_USAGE_WRAPUP: '0',
         HOME: homeDirectory,
         USERPROFILE: homeDirectory,
         GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
@@ -305,6 +306,7 @@ test('uninstall fault after_git_config restores prior core.hooksPath', () => {
             env: {
                 ...process.env,
                 CDE_INSTALL_PSTACK: '0',
+                CDE_INSTALL_USAGE_WRAPUP: '0',
                 HOME: homeDirectory,
                 USERPROFILE: homeDirectory,
                 GIT_CONFIG_GLOBAL: gitConfigPath,

package/hooks/advisory/pr_done_reminder.py

@@ -59,6 +59,7 @@ try:
         ALL_FAILING_CHECK_CONCLUSIONS,
         ALL_PASSING_CHECK_CONCLUSIONS,
         CHECK_COMPLETED_STATUS,
+        CHECKS_NOT_REPORTED_TEXT,
         DONE_LABEL_NAME,
         GH_PR_CREATE_ACTION,
         GH_PR_SUBCOMMAND,
@@ -164,7 +165,7 @@ def _check_counts(all_pr_fields: dict[str, object]) -> dict[str, int]:
 
 def _checks_line(all_check_counts: dict[str, int]) -> str:
     if all_check_counts["total"] == 0:
-        return "none reported"
+        return CHECKS_NOT_REPORTED_TEXT
     return (
         f"{all_check_counts['failing']} failing, "
         f"{all_check_counts['pending']} pending, "
@@ -185,6 +186,7 @@ def _has_done_label(all_pr_fields: dict[str, object]) -> bool:
 def _is_done(mergeable_value: str, all_check_counts: dict[str, int]) -> bool:
     return (
         mergeable_value == MERGEABLE_CLEAN_VALUE
+        and all_check_counts["total"] > 0
         and all_check_counts["failing"] == 0
         and all_check_counts["pending"] == 0
     )

package/hooks/advisory/test_pr_done_reminder.py

@@ -152,6 +152,58 @@ def test_should_say_done_when_mergeable_and_checks_pass() -> None:
     assert "NOT DONE" not in context
 
 
+def test_should_say_not_done_when_no_check_has_reported_on_the_head() -> None:
+    no_checks_yet = {**_CLEAN_PR_OBJECT, "statusCheckRollup": []}
+
+    context = pr_done_reminder.build_reminder_context(no_checks_yet)
+
+    assert "CI checks:   none reported yet on this head." in context
+    assert "NOT DONE" in context
+    assert "gh pr edit 42 --add-label" not in context
+
+
+def test_should_say_not_done_when_the_rollup_is_missing() -> None:
+    no_rollup = {key: value for key, value in _CLEAN_PR_OBJECT.items() if key != "statusCheckRollup"}
+
+    context = pr_done_reminder.build_reminder_context(no_rollup)
+
+    assert "none reported yet on this head." in context
+    assert "NOT DONE" in context
+
+
+def test_should_say_not_done_while_a_check_is_pending_on_an_otherwise_green_head() -> None:
+    one_pending = {
+        **_CLEAN_PR_OBJECT,
+        "statusCheckRollup": [
+            {"name": "pytest", "status": "COMPLETED", "conclusion": "SUCCESS"},
+            {"name": "mypy", "status": "QUEUED", "conclusion": ""},
+        ],
+    }
+
+    context = pr_done_reminder.build_reminder_context(one_pending)
+
+    assert "1 pending" in context
+    assert "NOT DONE" in context
+    assert "gh pr edit 42 --add-label" not in context
+
+
+def test_should_say_done_when_every_reported_check_passed() -> None:
+    all_green = {
+        **_CLEAN_PR_OBJECT,
+        "statusCheckRollup": [
+            {"name": "pytest", "status": "COMPLETED", "conclusion": "SUCCESS"},
+            {"name": "docs", "status": "COMPLETED", "conclusion": "SKIPPED"},
+            {"context": "lint", "state": "SUCCESS"},
+        ],
+    }
+
+    context = pr_done_reminder.build_reminder_context(all_green)
+
+    assert "CI checks:   0 failing, 0 pending, 3 total" in context
+    assert "Verdict:     DONE. Add the label now:" in context
+    assert "NOT DONE" not in context
+
+
 def test_should_keep_the_checklist_order_verdict_then_recheck_then_footer() -> None:
     all_lines = pr_done_reminder.build_reminder_context(_CLEAN_PR_OBJECT).split("\n")
 

package/hooks/hooks_constants/pr_done_reminder_constants.py

@@ -28,6 +28,7 @@ __all__ = [
     "REMINDER_FOOTER",
     "REMINDER_LINE_SEPARATOR",
     "ALL_REMINDER_HINTS_BY_MERGEABLE",
+    "CHECKS_NOT_REPORTED_TEXT",
     "VERDICT_DONE",
     "VERDICT_NOT_DONE",
     "NO_PULL_REQUEST_REMINDER",
@@ -75,6 +76,9 @@ ALL_REMINDER_HINTS_BY_MERGEABLE: dict[str, str] = {
     ),
     MERGEABLE_UNKNOWN_VALUE: "GitHub is still computing. Re-run the re-check command in a minute.",
 }
+CHECKS_NOT_REPORTED_TEXT: str = (
+    "none reported yet on this head. Wait for the checks, then run the re-check command."
+)
 VERDICT_DONE: str = "DONE. Add the label now:"
 VERDICT_NOT_DONE: str = "NOT DONE. Do not add the done label yet."
 NO_PULL_REQUEST_REMINDER: str = (

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.33.1",
+    "version": "8.34.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {