javi-forge 1.36.0 → 1.37.1

package/README.md

@@ -372,6 +372,11 @@ npx javi-forge doctor
 - **Project Manifest** — Reads `.javi-forge/manifest.json`
 - **Installed Modules** — engram, obsidian-brain, memory-simple, ghagga
 
+
+## macOS CI-Local support
+
+macOS is deprecated and unsupported for new CI-Local install/startup. Pin a supported release or migrate your workflow. Existing installed guards are not removed in 1.x; Darwin code removal is planned separately for 2.0.
+
 ## Requirements
 
 - **Node.js** >= 22 (required by ink 7; previous versions ran on >= 18)

package/assets/hooks/manifest.json

@@ -14,8 +14,8 @@
 		]
 	},
 	"pre-push": {
-		"version": 3,
-		"sha256": "c396387a15c3c448d524f68597a993f6b4341ae06143d2d5907ad914823d0ad0",
+		"version": 4,
+		"sha256": "ffe1b5dd0931617df3c9fea37947dac84dffd11c490c39590459e861b404148d",
 		"historical": [
 			{
 				"sha256": "7de58640aeef33085a49f31f1d9d0c8bacde0069d6d3265ae41aa8d3cd14d7a5",
@@ -28,6 +28,10 @@
 			{
 				"sha256": "c396387a15c3c448d524f68597a993f6b4341ae06143d2d5907ad914823d0ad0",
 				"firstCommit": "0779d746b23ad614a13181d60f1fe3aa034e91dd"
+			},
+			{
+				"sha256": "ffe1b5dd0931617df3c9fea37947dac84dffd11c490c39590459e861b404148d",
+				"firstCommit": "6b5799d9d9e8c528fad9dc1f7b641afbd3a60637"
 			}
 		]
 	},

package/assets/hooks/pre-push

@@ -4,13 +4,211 @@
 # Default: quick native CI gate (setup + lint + compile + gates — no tests, no coverage).
 # Requires javi-forge on PATH (npx fallback; offline npx fails -> hook fails closed).
 # To skip: git push --no-verify
-set -e
-if command -v javi-forge >/dev/null 2>&1; then
-  javi-forge hooks run pre-push
-else
-  npx javi-forge hooks run pre-push
-fi || {
+fail_pre_push() {
+  message=$1
+  status=${2:-1}
   echo ""
-  echo "pre-push FAILED - fix the issues above."
-  exit 1
+  echo "pre-push FAILED - $message"
+  exit "$status"
+}
+
+hash_required_file() {
+  target=$1
+  if [ -L "$target" ] || [ ! -f "$target" ]; then
+    return 1
+  fi
+  git hash-object --no-filters "$target"
+}
+
+hash_optional_file() {
+  target=$1
+  if [ -L "$target" ]; then
+    return 1
+  fi
+  if [ -f "$target" ]; then
+    git hash-object --no-filters "$target"
+    return $?
+  fi
+  if [ -e "$target" ]; then
+    return 1
+  fi
+  printf '%s\n' absent
 }
+
+# Git exports repository-local targeting variables to hooks. Preserve every
+# path needed for this repository before clearing the complete Git-owned set.
+if ! repository_root=$(git rev-parse --show-toplevel) || [ -z "$repository_root" ]; then
+  fail_pre_push "Could not resolve the repository root."
+fi
+if ! cd "$repository_root"; then
+  fail_pre_push "Could not return to the repository root."
+fi
+if ! git_dir=$(git rev-parse --absolute-git-dir) || [ -z "$git_dir" ]; then
+  fail_pre_push "Could not resolve the worktree Git directory."
+fi
+if ! common_dir=$(git rev-parse --path-format=absolute --git-common-dir) || [ -z "$common_dir" ]; then
+  fail_pre_push "Could not resolve the common Git directory."
+fi
+if ! index_path=$(git rev-parse --path-format=absolute --git-path index) || [ -z "$index_path" ]; then
+  fail_pre_push "Could not resolve the worktree index."
+fi
+if ! worktree_config_path=$(git rev-parse --path-format=absolute --git-path config.worktree) || [ -z "$worktree_config_path" ]; then
+  fail_pre_push "Could not resolve the worktree-local Git config."
+fi
+
+if ! git_local_env_vars=$(git rev-parse --local-env-vars); then
+  fail_pre_push "Could not discover Git-local environment variables."
+fi
+
+git_local_env_count=0
+invalid_git_local_env_var=
+saved_ifs=$IFS
+IFS='
+'
+for git_local_env_var in $git_local_env_vars; do
+  git_local_env_count=$((git_local_env_count + 1))
+  case "$git_local_env_var" in
+    GIT_*) ;;
+    *) invalid_git_local_env_var=$git_local_env_var ;;
+  esac
+  case "$git_local_env_var" in
+    *[!A-Za-z0-9_]*) invalid_git_local_env_var=$git_local_env_var ;;
+  esac
+  if [ -n "$invalid_git_local_env_var" ]; then
+    break
+  fi
+done
+IFS=$saved_ifs
+
+if [ "$git_local_env_count" -eq 0 ]; then
+  fail_pre_push "Git returned no Git-local environment variables."
+fi
+if [ -n "$invalid_git_local_env_var" ]; then
+  fail_pre_push "Invalid Git-local environment variable name: $invalid_git_local_env_var"
+fi
+
+# A bounded canary protects the metadata proven vulnerable in the incident.
+common_config_path="$common_dir/config"
+head_path="$git_dir/HEAD"
+packed_refs_path="$common_dir/packed-refs"
+
+if ! common_config_before=$(hash_required_file "$common_config_path"); then
+  fail_pre_push "Could not snapshot the common Git config."
+fi
+if ! head_before=$(hash_required_file "$head_path"); then
+  fail_pre_push "Could not snapshot HEAD."
+fi
+if ! index_before=$(hash_required_file "$index_path"); then
+  fail_pre_push "Could not snapshot the worktree index."
+fi
+if ! worktree_config_before=$(hash_optional_file "$worktree_config_path"); then
+  fail_pre_push "Could not snapshot the worktree-local Git config."
+fi
+if ! packed_refs_before=$(hash_optional_file "$packed_refs_path"); then
+  fail_pre_push "Could not snapshot packed refs."
+fi
+
+attached_ref=
+ref_path=
+ref_before=detached
+if attached_ref=$(git symbolic-ref -q HEAD); then
+  if ! ref_path=$(git rev-parse --path-format=absolute --git-path "$attached_ref") || [ -z "$ref_path" ]; then
+    fail_pre_push "Could not resolve the attached HEAD ref."
+  fi
+  if ! ref_before=$(hash_optional_file "$ref_path"); then
+    fail_pre_push "Could not snapshot the attached HEAD ref."
+  fi
+  if ! ref_oid_before=$(git rev-parse --verify "$attached_ref"); then
+    fail_pre_push "Could not resolve the attached HEAD ref value."
+  fi
+else
+  symbolic_ref_status=$?
+  if [ "$symbolic_ref_status" -ne 1 ]; then
+    fail_pre_push "Could not determine whether HEAD is attached."
+  fi
+  if ! ref_oid_before=$(git rev-parse --verify HEAD); then
+    fail_pre_push "Could not resolve detached HEAD."
+  fi
+fi
+
+# The scrub lives in a subshell: the hook retains its own targeting context for
+# the post-test canary, while the dispatcher and every descendant start clean.
+if (
+  scrub_ifs=$IFS
+  IFS='
+'
+  for git_local_env_var in $git_local_env_vars; do
+    if ! unset "$git_local_env_var"; then
+      echo "pre-push: could not unset $git_local_env_var"
+      exit 1
+    fi
+    if declare -p "$git_local_env_var" >/dev/null 2>&1; then
+      echo "pre-push: $git_local_env_var remained set after unset"
+      exit 1
+    fi
+  done
+  IFS=$scrub_ifs
+
+  if ! cd "$repository_root"; then
+    echo "pre-push: could not return to the repository root after scrubbing"
+    exit 1
+  fi
+
+  if command -v javi-forge >/dev/null 2>&1; then
+    javi-forge hooks run pre-push
+  else
+    npx javi-forge hooks run pre-push
+  fi
+); then
+  test_status=0
+else
+  test_status=$?
+fi
+
+if ! cd "$repository_root"; then
+  fail_pre_push "Could not return to the repository root after tests."
+fi
+
+if ! common_config_after=$(hash_required_file "$common_config_path"); then
+  fail_pre_push "Could not verify the common Git config after tests."
+fi
+if ! head_after=$(hash_required_file "$head_path"); then
+  fail_pre_push "Could not verify HEAD after tests."
+fi
+if ! index_after=$(hash_required_file "$index_path"); then
+  fail_pre_push "Could not verify the worktree index after tests."
+fi
+if ! worktree_config_after=$(hash_optional_file "$worktree_config_path"); then
+  fail_pre_push "Could not verify the worktree-local Git config after tests."
+fi
+if ! packed_refs_after=$(hash_optional_file "$packed_refs_path"); then
+  fail_pre_push "Could not verify packed refs after tests."
+fi
+
+ref_after=detached
+if [ -n "$attached_ref" ]; then
+  if ! ref_after=$(hash_optional_file "$ref_path"); then
+    fail_pre_push "Could not verify the attached HEAD ref after tests."
+  fi
+  if ! ref_oid_after=$(git rev-parse --verify "$attached_ref"); then
+    fail_pre_push "Could not resolve the attached HEAD ref value after tests."
+  fi
+else
+  if ! ref_oid_after=$(git rev-parse --verify HEAD); then
+    fail_pre_push "Could not resolve detached HEAD after tests."
+  fi
+fi
+
+if [ "$common_config_before" != "$common_config_after" ] ||
+  [ "$head_before" != "$head_after" ] ||
+  [ "$index_before" != "$index_after" ] ||
+  [ "$worktree_config_before" != "$worktree_config_after" ] ||
+  [ "$packed_refs_before" != "$packed_refs_after" ] ||
+  [ "$ref_before" != "$ref_after" ] ||
+  [ "$ref_oid_before" != "$ref_oid_after" ]; then
+  fail_pre_push "Git metadata changed during pre-push tests."
+fi
+
+if [ "$test_status" -ne 0 ]; then
+  fail_pre_push "fix the issues above." "$test_status"
+fi

package/ci-local/README.md

@@ -34,21 +34,26 @@ cp -r lib /path/to/new-project/
 
 # En el nuevo proyecto
 cd /path/to/new-project
-./.ci-local/install.sh      # Linux/Mac/WSL
+./.ci-local/install.sh      # Linux/WSL
 # o
 .\.ci-local\install.ps1     # Windows (PowerShell 7+)
 ```
 
-> **Importante:** CI-Local depende de `lib/common.sh` (Linux/Mac) y/o `lib/common.psm1` (Windows). Copiá ambos junto con el directorio `ci-local/`.
+> **Importante:** CI-Local depende de `lib/common.sh` (Linux/WSL) y/o `lib/common.psm1` (Windows). Copiá ambos junto con el directorio `ci-local/`. macOS está deprecated y se rechaza para instalaciones o arranques nuevos.
 
 El installer (ambas variantes) falla con mensaje claro si `javi-forge` no está en el PATH.
 
+
+## macOS deprecation
+
+macOS is deprecated and unsupported for new CI-Local install/startup. Pin a supported release or migrate your workflow. Existing installed guards are not removed in 1.x; Darwin code removal is planned separately for 2.0.
+
 ### Soporte cross-platform
 
 | Plataforma | Installer | Runner | Hooks | Requisitos |
 |---|---|---|---|---|
 | Linux | `install.sh` | `ci-local.sh` | bash | bash, perl, docker (opcional) |
-| macOS | `install.sh` | `ci-local.sh` | bash | bash, perl, docker (opcional) |
+| macOS | Unsupported: pin a supported release or migrate | Refused before startup | Existing installed guards retained | No new install or startup |
 | WSL | `install.sh` | `ci-local.sh` | bash | bash, perl, docker (opcional) |
 | Windows nativo | `install.ps1` | `ci-local.ps1` | bash | PowerShell 7+, Git for Windows (MSYS2 bash), docker (opcional) |
 
@@ -117,7 +122,7 @@ Si tu modelo de amenaza requiere defensa contra adversarios motivados, usá
 .\.ci-local\ci-local.ps1 shell    # Shell en entorno CI
 .\.ci-local\ci-local.ps1 detect   # Ver stack detectado
 
-# Linux/Mac
+# Linux/WSL
 ./.ci-local/ci-local.sh quick
 ./.ci-local/ci-local.sh full
 ./.ci-local/ci-local.sh shell
@@ -164,9 +169,9 @@ Developer workflow:
 ```
 .ci-local/
 ├── ci-local.ps1      # Script principal (Windows)
-├── ci-local.sh       # Script principal (Linux/Mac)
+├── ci-local.sh       # Script principal (Linux/WSL)
 ├── install.ps1       # Instalador Windows
-├── install.sh        # Instalador Linux/Mac
+├── install.sh        # Instalador Linux/WSL
 ├── semgrep.yml       # Reglas de seguridad
 ├── README.md         # Esta guía
 ├── hooks/

package/ci-local/ci-local.ps1

@@ -21,6 +21,30 @@ param(
     [string]$Mode = 'full'
 )
 
+function Invoke-CiLocalMain {
+    param(
+        [Parameter(Mandatory)][string]$Platform,
+        [ref]$ExitCode
+    )
+
+    if ($Platform -eq 'Darwin') {
+        Write-Host 'macOS is deprecated and unsupported for new CI-Local install/startup. Pin a supported release or migrate. Existing installed guards are not removed; Darwin code removal is planned separately for 2.0.'
+        if ($PSBoundParameters.ContainsKey('ExitCode')) {
+            $ExitCode.Value = 1
+            return
+        }
+        return 1
+    }
+
+    Invoke-CiLocalStartupBody -Platform $Platform
+    if ($PSBoundParameters.ContainsKey('ExitCode')) {
+        $ExitCode.Value = 0
+    }
+}
+
+function Invoke-CiLocalStartupBody {
+    param([string]$Platform)
+
 # See install.ps1 for the rationale behind 7.2 minimum (ResolveLinkTarget).
 if ($PSVersionTable.PSEdition -ne 'Core' -or $PSVersionTable.PSVersion -lt [Version]'7.2') {
     Write-Host 'ERROR: ci-local.ps1 requires PowerShell 7.2+ (pwsh).' -ForegroundColor Red
@@ -441,3 +465,13 @@ Write-Host ''
 Write-Host 'CI Local completed successfully!' -ForegroundColor Green
 Write-Host '  Safe to push - CI should pass.' -ForegroundColor Green
 Write-Host ''
+}
+
+if ($MyInvocation.InvocationName -ne '.') {
+    $platform = if ($IsMacOS) { 'Darwin' } else { 'Windows' }
+    $exitCode = 0
+    & ${function:Invoke-CiLocalMain} -Platform $platform -ExitCode ([ref]$exitCode)
+    if ($exitCode -ne 0) {
+        exit $exitCode
+    }
+}

package/ci-local/ci-local.sh

@@ -11,7 +11,20 @@
 #   ./ci-local.sh detect       # Mostrar stack detectado
 # =============================================================================
 
-set -e
+function ci_local_main() {
+    local platform="${1:?platform required}"
+    shift
+
+    if [ "$platform" = "Darwin" ]; then
+        printf '%s\n' 'macOS is deprecated and unsupported for new CI-Local install/startup. Pin a supported release or migrate. Existing installed guards are not removed; Darwin code removal is planned separately for 2.0.'
+        return 1
+    fi
+
+    ci_local_startup_body "$@"
+}
+
+function ci_local_startup_body() {
+    set -e
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
@@ -390,3 +403,8 @@ esac
 
 echo -e "\n${GREEN}CI Local completed successfully!${NC}"
 echo -e "${GREEN}  Safe to push - CI should pass.${NC}\n"
+}
+
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+    ci_local_main "$(/usr/bin/uname -s)" "$@"
+fi

package/ci-local/install.ps1

@@ -14,6 +14,20 @@
 [CmdletBinding()]
 param()
 
+function Invoke-CiLocalMain {
+    param([Parameter(Mandatory)][string]$Platform)
+
+    if ($Platform -eq 'Darwin') {
+        Write-Host 'macOS is deprecated and unsupported for new CI-Local install/startup. Pin a supported release or migrate. Existing installed guards are not removed; Darwin code removal is planned separately for 2.0.'
+        return 1
+    }
+
+    Invoke-CiLocalStartupBody -Platform $Platform
+}
+
+function Invoke-CiLocalStartupBody {
+    param([string]$Platform)
+
 # Defense-in-depth: #Requires is parsed by some hosts AFTER the script body.
 # 7.2 is the minimum because FileSystemInfo.ResolveLinkTarget($true) is .NET 6+,
 # which shipped with pwsh 7.2. Earlier pwsh 7.x runs on .NET 5 and the method
@@ -365,3 +379,12 @@ try {
 } finally {
     Pop-Location
 }
+}
+
+if ($MyInvocation.InvocationName -ne '.') {
+    $platform = if ($IsMacOS) { 'Darwin' } else { 'Windows' }
+    $exitCode = & ${function:Invoke-CiLocalMain} -Platform $platform
+    if ($exitCode -is [int] -and $exitCode -ne 0) {
+        exit $exitCode
+    }
+}

package/ci-local/install.sh

@@ -3,7 +3,19 @@
 # CI-LOCAL: Installation Script
 # =============================================================================
 
-set -e
+function ci_local_main() {
+    local platform="${1:?platform required}"
+
+    if [ "$platform" = "Darwin" ]; then
+        printf '%s\n' 'macOS is deprecated and unsupported for new CI-Local install/startup. Pin a supported release or migrate. Existing installed guards are not removed; Darwin code removal is planned separately for 2.0.'
+        return 1
+    fi
+
+    ci_local_startup_body "$platform"
+}
+
+function ci_local_startup_body() {
+    set -e
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
@@ -193,3 +205,8 @@ echo -e "  - pre-commit: AI check + lint + security"
 echo -e "  - commit-msg: Block AI attribution"
 echo -e "  - pre-push:   CI simulation in Docker"
 echo -e ""
+}
+
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+    ci_local_main "$(/usr/bin/uname -s)"
+fi

package/dist/cli/dispatch/simple-renderers.js

@@ -9,6 +9,7 @@
  */
 import { render } from "ink";
 import React from "react";
+import { resolvePlatformSupport } from "../../lib/platform-support.js";
 import AnalyzeUI from "../../ui/AnalyzeUI.js";
 import App from "../../ui/App.js";
 import { CIProvider as CIContextProvider } from "../../ui/CIContext.js";
@@ -49,6 +50,12 @@ export function handlePlugin(cli, ctx) {
         React.createElement(Plugin, { action: action, target: target, dryRun: cli.flags.dryRun, codex: cli.flags.codex, force: cli.flags.force })), { stdin: ctx.inkStdin });
 }
 export function handleInitDefault(cli, ctx) {
+    const platformSupport = resolvePlatformSupport(process.platform);
+    if (platformSupport) {
+        console.error(`${platformSupport.refusalCode}: ${platformSupport.guidance}`);
+        process.exitCode = 1;
+        return;
+    }
     const presetStack = VALID_STACKS.includes(cli.flags.stack)
         ? cli.flags.stack
         : undefined;

package/dist/commands/claude-hooks.js

@@ -59,6 +59,8 @@ function renderMutation(verb, result, log, logError) {
 }
 function renderDoctor(report, log) {
     log(`doctor claude: ${report.healthy ? "healthy" : "unhealthy"}`);
+    if (report.platformSupport)
+        log(`  platform-support: ${report.platformSupport.state} — ${report.platformSupport.guidance}`);
     log(`  settings: ${report.settings.state} — ${report.settings.detail}`);
     log(`  asset:    ${report.asset.state} — ${report.asset.detail}`);
     log(`  node:     ${report.node.version ?? "unavailable"} (min-satisfied: ${report.node.satisfiesMinimum})`);

package/dist/commands/codex-hooks.js

@@ -44,6 +44,8 @@ function renderMutation(verb, result, log, logError) {
 }
 function renderDoctor(report, log) {
     log(`doctor codex: ${report.healthy ? "healthy" : "unhealthy"}`);
+    if (report.platformSupport)
+        log(`  platform-support: ${report.platformSupport.state} — ${report.platformSupport.guidance}`);
     log(`  hooks.json: ${report.hooksJson.state}`);
     log(`  config:    [features] hooks=${report.config.featuresHooks} (readable: ${report.config.readable})`);
     log(`  trust:     ${report.trust.state}`);

package/dist/commands/init.d.ts

@@ -1,3 +1,4 @@
+import { type PlatformSupport } from "../lib/platform-support.js";
 import type { InitOptions } from "../types/index.js";
 import type { StepCallback } from "./init/types.js";
 /**
@@ -6,5 +7,12 @@ import type { StepCallback } from "./init/types.js";
  *
  * Pure dispatch: every step lives in src/commands/init/steps/.
  */
-export declare function initProject(options: InitOptions, onStep: StepCallback): Promise<void>;
+export type InitProjectResult = {
+    ok: true;
+} | {
+    ok: false;
+    refusalCode: string;
+    platformSupport: PlatformSupport;
+};
+export declare function initProject(options: InitOptions, onStep: StepCallback): Promise<InitProjectResult>;
 //# sourceMappingURL=init.d.ts.map

package/dist/commands/init.js

@@ -1,4 +1,5 @@
 import { ensureDirExists } from "../lib/common.js";
+import { resolvePlatformSupport, } from "../lib/platform-support.js";
 import { stepAgentSkills } from "./init/steps/agent-skills.js";
 import { stepAISync } from "./init/steps/ai-sync.js";
 import { stepCITemplate, stepDependabot } from "./init/steps/ci.js";
@@ -15,13 +16,15 @@ import { stepMemory } from "./init/steps/memory.js";
 import { stepMock } from "./init/steps/mock.js";
 import { stepSDD } from "./init/steps/sdd.js";
 import { stepSecurityHooks } from "./init/steps/security.js";
-/**
- * Main init orchestrator: bootstraps a project with CI, git hooks,
- * memory module, AI config sync, SDD, ghagga, and friends.
- *
- * Pure dispatch: every step lives in src/commands/init/steps/.
- */
 export async function initProject(options, onStep) {
+    const platformSupport = resolvePlatformSupport(process.platform);
+    if (platformSupport) {
+        return {
+            ok: false,
+            refusalCode: platformSupport.refusalCode,
+            platformSupport,
+        };
+    }
     const { projectDir, dryRun } = options;
     // Ensure project directory exists before any steps
     if (!dryRun && projectDir) {
@@ -47,5 +50,6 @@ export async function initProject(options, onStep) {
     await stepLocalAi(ctx);
     await stepAgentSkills(ctx);
     await stepManifest(ctx);
+    return { ok: true };
 }
 //# sourceMappingURL=init.js.map

package/dist/lib/claude-hook-manager.d.ts

@@ -8,6 +8,7 @@
  * Slice-3 seams — Slice 3 GROWS this file, it does not relocate this code.
  */
 import { type ClaudeHookComponentState, type SettingsClassification, type SettingsIdentityManifest } from "./claude-hook-settings.js";
+import { type PlatformSupport } from "./platform-support.js";
 import { type AclCapability, type SpawnFn } from "./secure-fs-posix.js";
 import { type PlatformSecureFs } from "./secure-fs-transaction.js";
 declare const COVERAGE: readonly ["Bash", "PowerShell", "Read", "Write", "Edit"];
@@ -29,6 +30,7 @@ export interface ClaudeHookAssetClassification {
 }
 export interface ClaudeHookDoctorReport {
     healthy: boolean;
+    platformSupport?: PlatformSupport;
     settings: {
         state: ClaudeHookComponentState;
         version?: number;
@@ -207,8 +209,9 @@ export declare function doctorClaudePreToolUse(projectDir: string, options?: {
     execution?: ExecutionProbeEnv;
     /** Injectable read-only ACL capability probe (defaults to the real one). */
     aclProbe?: () => Promise<AclCapability>;
+    platform?: NodeJS.Platform;
 }): Promise<ClaudeHookDoctorReport>;
-export interface ClaudeHookMutationResult {
+interface ClaudeHookMutationResultWithReport {
     ok: boolean;
     changed: string[];
     backups: string[];
@@ -220,7 +223,19 @@ export interface ClaudeHookMutationResult {
      * which is strictly worse than an exec-form guard that may not resolve.
      */
     warnings: string[];
+    lifecycleRefusal?: never;
+}
+interface ClaudeHookLifecycleRefusal {
+    ok: false;
+    changed: string[];
+    backups: string[];
+    errors: string[];
+    warnings: string[];
+    /** The lifecycle gate refused before any doctor or installed-state probe. */
+    lifecycleRefusal: PlatformSupport;
+    report?: never;
 }
+export type ClaudeHookMutationResult = ClaudeHookMutationResultWithReport | ClaudeHookLifecycleRefusal;
 /** Injectable deps so tests drive `_run` with a fake `PlatformSecureFs`. */
 export interface ClaudeHookRunDeps {
     secureFs?: PlatformSecureFs | null;
@@ -236,6 +251,7 @@ export interface ClaudeHookRunDeps {
     aclProbe?: () => Promise<AclCapability>;
     /** Injectable node-on-PATH heuristic, shared by the warning and the report. */
     nodeProbe?: () => Promise<NodeOnPathProbe>;
+    doctor?: typeof doctorClaudePreToolUse;
 }
 /** Internal deps-taking entry; tests drive it with a fake `PlatformSecureFs`. */
 export declare function _run(projectDir: string, mode: "install" | "repair", options: {

package/dist/lib/claude-hook-manager.js

@@ -15,6 +15,7 @@ import path from "node:path";
 import { CLAUDE_HOOK_ASSETS_DIR } from "../constants.js";
 import { ASSET_MANAGED_MARKER, ASSET_NAME, } from "./__fixtures__/claude-hook-ownership.js";
 import { buildManagedContainer, classifySettingsEntry, isPlainObject, LEGACY_FILE_SHA256, MANAGED_AGENT_ARG, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, planForceReplace, planLegacyCohortExcision, planManagedClaudeHookMerge, scanExecutionFlags, } from "./claude-hook-settings.js";
+import { resolvePlatformSupport, } from "./platform-support.js";
 import { safeReadFile } from "./safe-read.js";
 import { ACL_DETAIL, probeAclCapability, selectSecureFs, } from "./secure-fs-posix.js";
 import { runTransaction, } from "./secure-fs-transaction.js";
@@ -537,7 +538,9 @@ export async function doctorClaudePreToolUse(projectDir, options) {
         execution.blockers.some((blocker) => blocker.startsWith("guard:"))) {
         remediation.add(aclRemediation);
     }
+    const platformSupport = resolvePlatformSupport(options?.platform ?? process.platform);
     return {
+        ...(platformSupport ? { platformSupport } : {}),
         healthy,
         settings: {
             state: settings.state,
@@ -712,8 +715,20 @@ function serializeSettings(container) {
 }
 /** Internal deps-taking entry; tests drive it with a fake `PlatformSecureFs`. */
 export async function _run(projectDir, mode, options, deps) {
-    const manifest = deps.manifest ?? (await readManifest());
     const platform = deps.platform ?? process.platform;
+    const platformSupport = resolvePlatformSupport(platform);
+    if (platformSupport) {
+        return {
+            ok: false,
+            changed: [],
+            backups: [],
+            errors: [platformSupport.refusalCode],
+            warnings: [platformSupport.guidance],
+            lifecycleRefusal: platformSupport,
+        };
+    }
+    const doctorFn = deps.doctor ?? doctorClaudePreToolUse;
+    const manifest = deps.manifest ?? (await readManifest());
     const secureFs = deps.secureFs !== undefined ? deps.secureFs : selectSecureFs(platform);
     const clock = deps.clock ?? (() => new Date());
     const nonce = deps.nonce ?? (() => randomBytes(4).toString("hex"));
@@ -725,7 +740,7 @@ export async function _run(projectDir, mode, options, deps) {
     // report, so the run never spawns `node --version` twice and the warning, the
     // report row and the verdict can never disagree about the same PATH.
     const nodeOnPath = await (deps.nodeProbe ?? probeNodeOnPath)();
-    const doctor = () => doctorClaudePreToolUse(projectDir, {
+    const doctor = () => doctorFn(projectDir, {
         manifest,
         aclProbe: deps.aclProbe,
         execution: { nodeProbe: async () => nodeOnPath },

package/dist/lib/codex-hook-manager.d.ts

@@ -30,6 +30,7 @@
  */
 import { type AssetManifestEntry, type ExecutionReport, type NodeOnPathProbe } from "./claude-hook-manager.js";
 import { type ClaudeHookComponentState } from "./claude-hook-settings.js";
+import { type PlatformSupport } from "./platform-support.js";
 import { type SpawnFn } from "./secure-fs-posix.js";
 import { type PlatformSecureFs } from "./secure-fs-transaction.js";
 export type { NodeOnPathProbe };
@@ -101,6 +102,7 @@ export declare function classifyCodexHooksJson(value: unknown, expectedCommand:
 export type CodexTrustState = "trusted" | "untrusted";
 export interface CodexHookDoctorReport {
     healthy: boolean;
+    platformSupport?: PlatformSupport;
     hooksJson: {
         state: ClaudeHookComponentState;
         detail?: string;
@@ -127,20 +129,34 @@ export interface CodexHookDoctorReport {
     remediation: string[];
 }
 export interface CodexDoctorOptions {
+    platform?: NodeJS.Platform;
     manifest?: Manifest;
     assetPath?: string;
     nodeVersion?: string;
     nodeProbe?: () => Promise<NodeOnPathProbe>;
 }
 export declare function doctorCodexPreToolUse(homeDir?: string, options?: CodexDoctorOptions): Promise<CodexHookDoctorReport>;
-export interface CodexHookMutationResult {
+interface CodexHookMutationResultWithReport {
     ok: boolean;
     changed: string[];
     backups: string[];
+    /** Real post-mutation doctor snapshot. */
     report: CodexHookDoctorReport;
     errors: string[];
     warnings: string[];
+    lifecycleRefusal?: never;
+}
+interface CodexHookLifecycleRefusal {
+    ok: false;
+    changed: string[];
+    backups: string[];
+    errors: string[];
+    warnings: string[];
+    /** The lifecycle gate refused before any doctor or installed-state probe. */
+    lifecycleRefusal: PlatformSupport;
+    report?: never;
 }
+export type CodexHookMutationResult = CodexHookMutationResultWithReport | CodexHookLifecycleRefusal;
 export interface CodexHookRunDeps {
     secureFs?: PlatformSecureFs | null;
     clock?: () => Date;
@@ -150,6 +166,7 @@ export interface CodexHookRunDeps {
     assetPath?: string;
     nodeProbe?: () => Promise<NodeOnPathProbe>;
     nodeSpawn?: SpawnFn;
+    doctor?: typeof doctorCodexPreToolUse;
 }
 export declare function _runCodex(homeDir: string, _mode: "install" | "repair", _options: {
     force?: boolean;

package/dist/lib/codex-hook-manager.js

@@ -34,6 +34,7 @@ import { CLAUDE_HOOK_ASSETS_DIR } from "../constants.js";
 import { ASSET_NAME } from "./__fixtures__/claude-hook-ownership.js";
 import { classifyAssetState, detectNode, probeNodeOnPath, } from "./claude-hook-manager.js";
 import { isPlainObject, validateSettingsShape, } from "./claude-hook-settings.js";
+import { resolvePlatformSupport, } from "./platform-support.js";
 import { safeReadFile } from "./safe-read.js";
 import { selectSecureFs } from "./secure-fs-posix.js";
 import { runTransaction, } from "./secure-fs-transaction.js";
@@ -372,7 +373,9 @@ export async function doctorCodexPreToolUse(homeDir = os.homedir(), options = {}
     }
     if (!node.satisfiesMinimum)
         remediation.push("install Node 22 or newer");
+    const platformSupport = resolvePlatformSupport(options.platform ?? process.platform);
     return {
+        ...(platformSupport ? { platformSupport } : {}),
         healthy: status === "runnable",
         hooksJson,
         config: { featuresHooks, readable: configReadable },
@@ -396,8 +399,20 @@ function serialize(container) {
     return Buffer.from(`${JSON.stringify(container, null, 2)}\n`, "utf8");
 }
 export async function _runCodex(homeDir, _mode, _options, deps) {
-    const manifest = deps.manifest ?? (await readManifest());
     const platform = deps.platform ?? process.platform;
+    const platformSupport = resolvePlatformSupport(platform);
+    if (platformSupport) {
+        return {
+            ok: false,
+            changed: [],
+            backups: [],
+            errors: [platformSupport.refusalCode],
+            warnings: [platformSupport.guidance],
+            lifecycleRefusal: platformSupport,
+        };
+    }
+    const doctorFn = deps.doctor ?? doctorCodexPreToolUse;
+    const manifest = deps.manifest ?? (await readManifest());
     const secureFs = deps.secureFs !== undefined ? deps.secureFs : selectSecureFs(platform);
     const clock = deps.clock ?? (() => new Date());
     const nonce = deps.nonce ??
@@ -406,7 +421,7 @@ export async function _runCodex(homeDir, _mode, _options, deps) {
     const { codexDir, hooksFile, configFile } = codexConfigPaths(homeDir);
     const expectedCommand = expectedCodexCommand(assetPath);
     const nodeOnPath = await (deps.nodeProbe ?? probeNodeOnPath)();
-    const doctor = () => doctorCodexPreToolUse(homeDir, {
+    const doctor = () => doctorFn(homeDir, {
         manifest,
         assetPath,
         nodeProbe: async () => nodeOnPath,

package/dist/lib/platform-support.d.ts

@@ -0,0 +1,19 @@
+export declare const PLATFORM_SUPPORT_STATE: {
+    readonly MACOS_DEPRECATED: "macos-deprecated";
+};
+export declare const LIFECYCLE_SUPPORT: {
+    readonly UNSUPPORTED: "unsupported";
+};
+export declare const PLATFORM_REFUSAL: {
+    readonly MACOS_LIFECYCLE_UNSUPPORTED: "macos-lifecycle-unsupported";
+};
+export interface PlatformSupport {
+    platform: "darwin";
+    state: typeof PLATFORM_SUPPORT_STATE.MACOS_DEPRECATED;
+    lifecycle: typeof LIFECYCLE_SUPPORT.UNSUPPORTED;
+    refusalCode: typeof PLATFORM_REFUSAL.MACOS_LIFECYCLE_UNSUPPORTED;
+    guidance: string;
+}
+export declare const MACOS_DEPRECATION_GUIDANCE = "macOS is deprecated and unsupported for install, repair, and init; pin a supported release or migrate. Existing installed guards are not removed; Darwin removal is planned for 2.0.";
+export declare function resolvePlatformSupport(platform: string): PlatformSupport | undefined;
+//# sourceMappingURL=platform-support.d.ts.map

package/dist/lib/platform-support.js

@@ -0,0 +1,22 @@
+export const PLATFORM_SUPPORT_STATE = {
+    MACOS_DEPRECATED: "macos-deprecated",
+};
+export const LIFECYCLE_SUPPORT = {
+    UNSUPPORTED: "unsupported",
+};
+export const PLATFORM_REFUSAL = {
+    MACOS_LIFECYCLE_UNSUPPORTED: "macos-lifecycle-unsupported",
+};
+export const MACOS_DEPRECATION_GUIDANCE = "macOS is deprecated and unsupported for install, repair, and init; pin a supported release or migrate. Existing installed guards are not removed; Darwin removal is planned for 2.0.";
+export function resolvePlatformSupport(platform) {
+    if (platform !== "darwin")
+        return undefined;
+    return {
+        platform: "darwin",
+        state: PLATFORM_SUPPORT_STATE.MACOS_DEPRECATED,
+        lifecycle: LIFECYCLE_SUPPORT.UNSUPPORTED,
+        refusalCode: PLATFORM_REFUSAL.MACOS_LIFECYCLE_UNSUPPORTED,
+        guidance: MACOS_DEPRECATION_GUIDANCE,
+    };
+}
+//# sourceMappingURL=platform-support.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "javi-forge",
-	"version": "1.36.0",
+	"version": "1.37.1",
 	"description": "Project scaffolding and AI-ready CI bootstrap",
 	"type": "module",
 	"bin": {