Skip to content

fix(artifacts): mark Windows launchable files as host executables - #1824

Merged
morluto merged 2 commits into
morluto:mainfrom
dollarsmoney:fix/windows-host-executable
Oct 11, 2026
Merged

morluto merged 2 commits into
morluto:mainfrom
dollarsmoney:fix/windows-host-executable

Conversation

@dollarsmoney

Copy link
Copy Markdown
Contributor

Summary

Fixes #1819.

On a Windows host, every occurrence built from a host file reported executable: false, including real PE images. The same occurrence also reported artifact_kind: executable and artifact_format: pe, so the record contradicted itself. Host-file occurrences now report executable: true for files Windows launches directly. POSIX hosts behave as before.

Problem and expected behavior

DirectoryArtifactReader (every directory entry) and scanCanonical (the root occurrence) both derived the fact as (metadata.mode & 0o111) !== 0. Windows has no execute permission bit. libuv fills stat.mode from file attributes only (0o666, or 0o444 when read-only), so the test can never be true on Windows.

Expected: executable states whether the file carries the host's executable marking. On POSIX that is the execute bits, as before. On Windows it is the file extension that the shell and CreateProcess launch directly.

Change and scope

  • New pure helper src/artifacts/hostExecutable.ts, hostExecutable(path, metadata, platform = process.platform):
    • POSIX: (mode & 0o111) !== 0 (unchanged).
    • win32: a regular file whose case-insensitive extension is .exe, .com, .bat or .cmd. These are the extensions proposed in the issue.
  • Both host-file call sites now use the helper, so the rule is derived in one place.
  • The extension set is fixed. PATHEXT is deliberately not read, because it is ambient environment configuration.
  • Not included: archive-derived facts (ZIP/ASAR/Mach-O slices). They keep their stored or format-derived metadata. PATHEXT script-host extensions (.vbs, .js, .wsf, …) are not launched directly and are out of scope.

Contract and boundary impact

  • Semantic owner and earliest changed stage: artifact inventory, host-file occurrence construction (src/artifacts/).
  • CLI and MCP/tool-catalog contract: none. The field and its schema are unchanged; on Windows hosts its value is now accurate.
  • Provider, bridge, target-format, or platform compatibility: Windows hosts only. POSIX behavior is unchanged.
  • Evidence, artifact, provenance, or reconstruction contract: the executable occurrence fact on Windows-hosted inventories. compare_artifacts can now report permission differences for Windows-hosted inventories (src/domain/artifactComparison.ts).
  • Process execution, authorization, cleanup, or containment impact: none.
  • Generated metadata, package, or installation impact: none.

Evidence and regression coverage

  • Tests added or updated: src/artifacts/hostExecutable.test.ts, which exercises the derivation with an explicit platform so the Windows branch runs on any CI host:
    • POSIX: execute bits set and unset, including a .exe without execute bits staying false.
    • Windows .exe / .EXE / .Cmd / .bat / .com with mode 0o666 and read-only 0o444 → true.
    • Windows .dll, .txt, extensionless, archive.exe.bak and a directory named bundle.exe → false.
  • Base reproduction or other evidence: source-derived from the two cited call sites and the issue's Windows reproduction. With the base derivation, every Windows case above evaluates to false because the mode carries no execute bits.
  • User-visible CLI/MCP output: on macOS, rea inspect-artifact still reports the root occurrence as "executable":true for a 0755 copy of /bin/ls and "executable":false for a 0644 copy named plain.exe. The POSIX behavior is unchanged.
  • Remaining proof gaps: not run on a real Windows host. The windows-curated CI lane would provide that coverage.

For evidence-bearing changes:

  • Observed, derived, and inferred claims remain distinguishable.
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

All on macOS 15 (Darwin 24.3.0, arm64), Node 26.9.0:

  • npm run test:local -- src/artifacts/hostExecutable.test.ts — 3 tests passed
  • npm run test:focused -- tests/boundary/filesystem/artifactInventorySnapshot.test.ts tests/boundary/filesystem/directoryArtifactReaderOpen.test.ts tests/boundary/filesystem/directoryArtifactReaderOwnership.test.ts tests/boundary/filesystem/artifactMzInventory.test.ts — 17 tests passed
  • npm run verify:test-discovery — discovered all 835 test files exactly once
  • npm run check:fast — typecheck and lint passed (also ran as the pre-push hook)
  • npm run build:cached, then node scripts/rea.mjs inspect-artifact <file> --json on the two macOS copies above — results as listed

Compatibility, safety, and release

  • Breaking changes or migration steps: none.
  • Real Hopper/Ghidra, browser, or OS coverage: macOS only. No real Windows host run. No providers involved.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: reads only the existing lstat metadata and path; no new filesystem access or environment reads.

Review checklist

  • This PR addresses a concrete problem or an agreed enhancement.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

Host-file occurrences derived `executable` from POSIX execute bits, which
Windows never reports, so every Windows host file (including PE .exe
images classified as executable) reported `executable: false`.

Derive the fact once through hostExecutable: POSIX hosts keep the execute
bits; Windows marks regular files with the extensions it launches directly
(.exe, .com, .bat, .cmd), without reading the ambient PATHEXT.

Fixes morluto#1819
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 11, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-11T17:16:23.584762Z fd660f8 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

Merge main and reuse its hostExecutableMarking helper from morluto#1823. Remove the duplicate helper and consolidate the additional Windows filename cases into the existing regression suite.

Validation: 20 focused artifact tests passed; npm run check passed; all 854 test files discovered exactly once. Windows-specific helper cases ran on macOS; no native Windows run.
@morluto
morluto merged commit e8491e0 into morluto:main Oct 11, 2026
21 checks passed
@github-actions github-actions Bot mentioned this pull request Oct 11, 2026
3 tasks done
@morluto

morluto commented Oct 11, 2026

Copy link
Copy Markdown
Owner

This makes Windows artifact inventories internally consistent, @dollarsmoney. Deriving host-file executability from the fixed launchable extensions on Windows, while retaining mode bits on POSIX, fixes PE entries otherwise labeled as executable artifacts with executable: false. Thanks for keeping ambient PATHEXT out of the rule.

@morluto morluto added bug Something isn't working area: evidence Evidence, artifacts, and reconstruction labels Oct 14, 2026
@dollarsmoney
dollarsmoney deleted the fix/windows-host-executable branch October 15, 2026 11:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: evidence Evidence, artifacts, and reconstruction bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug] inspect-artifact reports executable:false for every Windows host file, including real PE .exe images

2 participants