@cyanautomation/kaseki-agent 1.4.1

package/test/printf-safety.test.sh

@@ -0,0 +1,297 @@
+#!/usr/bin/env bash
+# Test suite for printf safety and restoration report generation fixes
+# Tests edge cases that could cause the "printf: - : invalid option" error
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TEST_RESULTS_DIR="${TMPDIR:-/tmp}/kaseki-agent-printf-safety-results.$$"
+KASEKI_SCRIPT="${SCRIPT_DIR}/kaseki-agent.sh"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Test counters
+TESTS_RUN=0
+TESTS_PASSED=0
+TESTS_FAILED=0
+
+# Setup and teardown
+setup() {
+  mkdir -p "$TEST_RESULTS_DIR"
+  mkdir -p "$TEST_RESULTS_DIR/results"
+  cd "$TEST_RESULTS_DIR"
+}
+
+teardown() {
+  rm -rf "$TEST_RESULTS_DIR"
+}
+
+# Test helpers
+run_test() {
+  local test_name="$1"
+  local test_func="$2"
+  
+  TESTS_RUN=$((TESTS_RUN + 1))
+  printf '[%3d] %-60s ' "$TESTS_RUN" "$test_name"
+  
+  if "$test_func" 2>/dev/null; then
+    printf "${GREEN}PASS${NC}\n"
+    TESTS_PASSED=$((TESTS_PASSED + 1))
+    return 0
+  else
+    printf "${RED}FAIL${NC}\n"
+    TESTS_FAILED=$((TESTS_FAILED + 1))
+    return 1
+  fi
+}
+
+source_validate_numeric() {
+  source <(sed -n '/^validate_numeric()/,/^}/p' "$KASEKI_SCRIPT")
+}
+
+source_generate_restoration_report() {
+  source <(sed -n '/^generate_restoration_report()/,/^}/p' "$KASEKI_SCRIPT" | sed "s#/results#${PWD}/results#g")
+}
+
+# Test: validate_numeric with valid input
+test_validate_numeric_valid() {
+  source_validate_numeric
+  validate_numeric "test_var" "42"
+}
+
+# Test: validate_numeric with dash (the bug trigger)
+test_validate_numeric_dash() {
+  source_validate_numeric
+  ! validate_numeric "test_var" "-"
+}
+
+# Test: validate_numeric with non-numeric input
+test_validate_numeric_non_numeric() {
+  source_validate_numeric
+  ! validate_numeric "test_var" "not-a-number"
+}
+
+# Test: validate_numeric with empty input
+test_validate_numeric_empty() {
+  source_validate_numeric
+  ! validate_numeric "test_var" ""
+}
+
+# Test: validate_numeric rejects values containing multiple lines
+test_validate_numeric_multiline() {
+  source_validate_numeric
+  ! validate_numeric "restored_count" $'0\n0'
+}
+
+# Test: restoration report with missing file
+test_restoration_report_missing_file() {
+  source_validate_numeric
+  source_generate_restoration_report
+  
+  rm -f results/restoration.jsonl
+  generate_restoration_report  # Should return 0 (skip silently)
+  [ $? -eq 0 ]
+}
+
+# Test: restoration report with empty file
+test_restoration_report_empty_file() {
+  source_validate_numeric
+  source_generate_restoration_report
+  
+  : > results/restoration.jsonl
+  generate_restoration_report  # Should return 0 (no changes to report)
+  [ $? -eq 0 ]
+}
+
+# Test: restoration report with valid entries
+test_restoration_report_valid_entries() {
+  source_validate_numeric
+  source_generate_restoration_report
+  
+  cat > results/restoration.jsonl <<'EOF'
+{"timestamp":"2026-05-07T10:00:00Z","event":"file_evaluated","file":"src/test.ts","status":"kept","reason":"matched_allowlist"}
+{"timestamp":"2026-05-07T10:00:01Z","event":"file_restored","file":"docs/readme.md","status":"restored","reason":"not_in_allowlist"}
+EOF
+  
+  generate_restoration_report && [ -f results/restoration-report.md ] && \
+    grep -Fq 'Total Files Changed:** 2' results/restoration-report.md && \
+    grep -Fq 'Files Kept (in allowlist):** 1' results/restoration-report.md && \
+    grep -Fq 'Files Restored (outside allowlist):** 1' results/restoration-report.md
+}
+
+# Test: restoration report with only kept files
+test_restoration_report_only_kept() {
+  source_validate_numeric
+  source_generate_restoration_report
+  
+  cat > results/restoration.jsonl <<'EOF'
+{"timestamp":"2026-05-07T10:00:00Z","event":"file_evaluated","file":"src/test.ts","status":"kept","reason":"matched_allowlist"}
+{"timestamp":"2026-05-07T10:00:01Z","event":"file_evaluated","file":"src/lib.ts","status":"kept","reason":"matched_allowlist"}
+EOF
+  
+  local stderr_file=results/restoration-report.stderr
+  generate_restoration_report 2>"$stderr_file" && [ -f results/restoration-report.md ] && \
+    grep -Fq 'Total Files Changed:** 2' results/restoration-report.md && \
+    grep -Fq 'Files Restored (outside allowlist):** 0' results/restoration-report.md && \
+    grep -Fq 'Allowlist Coverage:** 100' results/restoration-report.md && \
+    grep -Fq 'restored_count="0"' "$stderr_file" && \
+    ! grep -qx '0"' "$stderr_file"
+}
+
+# Test: restoration report with only restored files
+test_restoration_report_only_restored() {
+  source_validate_numeric
+  source_generate_restoration_report
+  
+  cat > results/restoration.jsonl <<'EOF'
+{"timestamp":"2026-05-07T10:00:00Z","event":"file_restored","file":"docs/readme.md","status":"restored","reason":"not_in_allowlist"}
+{"timestamp":"2026-05-07T10:00:01Z","event":"file_restored","file":"CHANGELOG.md","status":"restored","reason":"not_in_allowlist"}
+EOF
+  
+  generate_restoration_report && [ -f results/restoration-report.md ] && \
+    grep -Fq 'Total Files Changed:** 2' results/restoration-report.md && \
+    grep -Fq 'Allowlist Coverage:** 0' results/restoration-report.md && \
+    grep -Fq 'Low Allowlist Coverage' results/restoration-report.md
+}
+
+# Test: restoration report with low coverage warning
+test_restoration_report_low_coverage_warning() {
+  source_validate_numeric
+  source_generate_restoration_report
+  
+  # Create scenario: 1 kept, 9 restored = 10% coverage (< 50%)
+  printf '{"timestamp":"2026-05-07T10:00:00Z","event":"file_evaluated","file":"src/test.ts","status":"kept","reason":"matched_allowlist"}\n' > results/restoration.jsonl
+  for i in {1..9}; do
+    printf '{"timestamp":"2026-05-07T10:00:%02d","event":"file_restored","file":"file%d.txt","status":"restored","reason":"not_in_allowlist"}\n' "$i" "$i" >> results/restoration.jsonl
+  done
+  
+  generate_restoration_report && [ -f results/restoration-report.md ] && \
+    grep -Fq 'Low Allowlist Coverage' results/restoration-report.md && \
+    grep -Fq 'Allowlist Coverage:** 10' results/restoration-report.md
+}
+
+# Test: printf with valid numeric argument (should not fail)
+test_printf_valid_numeric() {
+  local test_var=42
+  printf 'test: %d\n' "$test_var" > /dev/null 2>&1
+  [ $? -eq 0 ]
+}
+
+# Test: printf with dash argument (should fail without quoting)
+test_printf_dash_unquoted_fails() {
+  local test_var="-"
+  # This SHOULD fail with unquoted expansion
+  ! printf '%d\n' $test_var > /dev/null 2>&1
+}
+
+# Test: printf with dash argument quoted (should fail with validation)
+test_printf_dash_quoted_validation() {
+  source_validate_numeric
+  local test_var="-"
+  ! validate_numeric "test_var" "$test_var"
+}
+
+# Test: grep count fallback works
+test_grep_count_fallback() {
+  # Empty file, grep should print one 0 and the fallback should not append another 0.
+  : > results/test.jsonl
+  local count
+  count=$(grep -c 'pattern' results/test.jsonl 2>/dev/null || true)
+  count=${count:-0}
+  [ "$count" = "0" ]
+}
+
+# Test: grep count fallback on missing file
+test_grep_count_fallback_missing() {
+  # Missing file, fallback should normalize empty output to one 0.
+  local count
+  count=$(grep -c 'pattern' results/nonexistent.jsonl 2>/dev/null || true)
+  count=${count:-0}
+  [ "$count" = "0" ]
+}
+
+# Test: json_encode function availability
+test_json_encode_exists() {
+  source <(sed -n '/^json_encode()/,/^}/p' "$KASEKI_SCRIPT")
+  local output=$(printf 'test' | json_encode)
+  [ "$output" = '"test"' ]
+}
+
+# Test: json_encode fallback when node unavailable
+test_json_encode_fallback() {
+  source <(sed -n '/^json_encode()/,/^}/p' "$KASEKI_SCRIPT")
+  
+  # Temporarily override PATH to hide node
+  local old_path="$PATH"
+  export PATH="/usr/bin:/bin"  # Minimal PATH without node
+  
+  local output=$(printf 'test' | json_encode 2>/dev/null || true)
+  # Should return empty JSON string "" or handle gracefully
+  export PATH="$old_path"
+  
+  # Test passes if it doesn't crash
+  true
+}
+
+# Main test execution
+main() {
+  printf '\n%s\n' "$(printf '=%.0s' {1..70})"
+  printf 'Testing Printf Safety & Restoration Report Generation Fixes\n'
+  printf '%s\n' "$(printf '=%.0s' {1..70})"
+  printf '\n'
+  
+  setup
+  
+  # validate_numeric tests
+  printf '\n%s\n' '### validate_numeric() tests'
+  run_test "validate_numeric with valid integer" test_validate_numeric_valid
+  run_test "validate_numeric rejects dash (-)" test_validate_numeric_dash
+  run_test "validate_numeric rejects non-numeric" test_validate_numeric_non_numeric
+  run_test "validate_numeric rejects empty" test_validate_numeric_empty
+  run_test "validate_numeric rejects multi-line value" test_validate_numeric_multiline
+  
+  # restoration report tests
+  printf '\n%s\n' '### generate_restoration_report() tests'
+  run_test "restoration report skips missing file" test_restoration_report_missing_file
+  run_test "restoration report handles empty file" test_restoration_report_empty_file
+  run_test "restoration report with valid entries" test_restoration_report_valid_entries
+  run_test "restoration report with only kept files" test_restoration_report_only_kept
+  run_test "restoration report with only restored files" test_restoration_report_only_restored
+  run_test "restoration report low coverage warning" test_restoration_report_low_coverage_warning
+  
+  # printf safety tests
+  printf '\n%s\n' '### printf safety tests'
+  run_test "printf with valid numeric argument" test_printf_valid_numeric
+  run_test "printf with dash (unquoted) should fail" test_printf_dash_unquoted_fails
+  run_test "printf with dash (validation) should fail" test_printf_dash_quoted_validation
+  
+  # grep fallback tests
+  printf '\n%s\n' '### grep fallback tests'
+  run_test "grep count fallback on empty file" test_grep_count_fallback
+  run_test "grep count fallback on missing file" test_grep_count_fallback_missing
+  
+  # json_encode tests
+  printf '\n%s\n' '### json_encode() tests'
+  run_test "json_encode function works" test_json_encode_exists
+  run_test "json_encode handles node unavailable" test_json_encode_fallback
+  
+  # Summary
+  printf '\n%s\n' "$(printf '=%.0s' {1..70})"
+  printf 'Test Results: %d/%d passed, %d failed\n' "$TESTS_PASSED" "$TESTS_RUN" "$TESTS_FAILED"
+  
+  if [ "$TESTS_FAILED" -eq 0 ]; then
+    printf "${GREEN}✓ All tests passed!${NC}\n"
+    teardown
+    return 0
+  else
+    printf "${RED}✗ Some tests failed${NC}\n"
+    printf 'Results directory: %s\n' "$TEST_RESULTS_DIR"
+    return 1
+  fi
+}
+
+main "$@"

package/test/validation-fix.test.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# Test for validation shell fix (non-login shell + directory checkpoint)
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+RUNNER="$REPO_ROOT/run-kaseki.sh"
+
+pass() { printf '✓ %s\n' "$1"; }
+fail() { printf '✗ %s\n' "$1" >&2; exit 1; }
+
+# Test 1: Verify non-login shell syntax in kaseki-agent.sh
+test_non_login_shell_syntax() {
+  local line
+  line=$(grep -n 'bash -c "\$trimmed"' "$REPO_ROOT/kaseki-agent.sh" | head -1 | cut -d: -f1)
+  [ -n "$line" ] || fail "Non-login shell (bash -c) not found in kaseki-agent.sh"
+  pass "Non-login shell syntax found at line $line"
+  
+  # Ensure old login shell is gone
+  if grep -q 'bash -lc "\$trimmed"' "$REPO_ROOT/kaseki-agent.sh"; then
+    fail "Old login shell syntax (bash -lc) still present in kaseki-agent.sh"
+  fi
+  pass "Old login shell syntax removed"
+}
+
+# Test 2: Verify directory checkpoint exists
+test_directory_checkpoint() {
+  if grep -q 'Working directory /workspace/repo does not exist before validation' "$REPO_ROOT/kaseki-agent.sh"; then
+    pass "Directory checkpoint found in kaseki-agent.sh"
+  else
+    fail "Directory checkpoint not found"
+  fi
+}
+
+# Test 3: Verify enhanced diagnostics exist
+test_enhanced_diagnostics() {
+  if grep -q 'getcwd.*No such file or directory.*cannot access parent directories' "$REPO_ROOT/kaseki-agent.sh"; then
+    pass "Enhanced diagnostics for getcwd errors found"
+  else
+    fail "Enhanced diagnostics not found"
+  fi
+}
+
+# Test 4: Verify script syntax is still valid
+test_script_syntax() {
+  if bash -n "$REPO_ROOT/kaseki-agent.sh" >/dev/null 2>&1; then
+    pass "kaseki-agent.sh bash syntax is valid"
+  else
+    fail "kaseki-agent.sh has syntax errors"
+  fi
+}
+
+# Test 5: Verify non-login shell works for npm commands (integration test)
+test_non_login_npm_command() {
+  local tmpdir exit_code
+  tmpdir=$(mktemp -d)
+  trap "rm -rf '$tmpdir'" EXIT
+  
+  cd "$tmpdir"
+  npm init -y >/dev/null 2>&1
+  npm install eslint >/dev/null 2>&1
+  
+  # Test that non-login bash can run npm commands
+  if bash -c "npm --version" >/dev/null 2>&1; then
+    pass "Non-login shell can execute npm commands"
+  else
+    fail "Non-login shell cannot execute npm commands"
+  fi
+}
+
+# Run all tests
+printf '==> Validation Fix Tests\n'
+test_non_login_shell_syntax
+test_directory_checkpoint
+test_enhanced_diagnostics
+test_script_syntax
+test_non_login_npm_command
+
+printf '\n✓ All validation fix tests passed\n'

package/test/validation-integration.test.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# Integration test: Verify validation with non-login shell works
+# This simulates the matmetrics scenario where validation commands need to run
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+pass() { printf '✓ %s\n' "$1"; }
+fail() { printf '✗ %s\n' "$1" >&2; exit 1; }
+
+# Create temporary test directory with npm project
+setup_test_repo() {
+  local tmpdir="$1"
+  cd "$tmpdir"
+  
+  # Initialize npm project with validation scripts
+  cat > package.json <<'EOF'
+{
+  "name": "validation-test",
+  "version": "1.0.0",
+  "scripts": {
+    "check": "npm ls --depth=0",
+    "test": "node -e 'console.log(\"test passed\")'",
+    "build": "node -e 'console.log(\"build passed\")'"
+  }
+}
+EOF
+  
+  # Create a simple lockfile
+  cat > package-lock.json <<'EOF'
+{
+  "name": "validation-test",
+  "version": "1.0.0",
+  "lockfileVersion": 3
+}
+EOF
+}
+
+# Test non-login shell validation execution
+test_non_login_validation() {
+  local tmpdir exit_code
+  tmpdir=$(mktemp -d)
+  trap "rm -rf '$tmpdir'" EXIT
+  
+  setup_test_repo "$tmpdir"
+  cd "$tmpdir"
+  
+  # Simulate the validation command execution with non-login shell
+  # This is what happens in kaseki-agent.sh after the fix
+  if bash -c "npm run check" >/dev/null 2>&1; then
+    pass "Non-login validation command succeeded (npm run check)"
+  else
+    fail "Non-login validation command failed"
+  fi
+}
+
+# Test that directory errors are caught early (checkpoint test)
+test_directory_checkpoint() {
+  local tmpdir validation_log exit_code
+  tmpdir=$(mktemp -d)
+  trap "rm -rf '$tmpdir'" EXIT
+  validation_log="$tmpdir/validation.log"
+  
+  # Simulate the checkpoint logic from kaseki-agent.sh
+  if ! [ -d /nonexistent/repo ]; then
+    {
+      printf 'ERROR: Working directory /nonexistent/repo does not exist before validation\n'
+      printf 'Current pwd: %s\n' "$(pwd 2>&1 || echo '<pwd failed>')"
+    } > "$validation_log"
+    
+    if grep -q 'does not exist before validation' "$validation_log"; then
+      pass "Directory checkpoint properly detects missing directories"
+    else
+      fail "Directory checkpoint did not detect missing directory"
+    fi
+  fi
+}
+
+# Test enhanced diagnostics capture
+test_diagnostics_capture() {
+  local tmpdir quality_log
+  tmpdir=$(mktemp -d)
+  trap "rm -rf '$tmpdir'" EXIT
+  quality_log="$tmpdir/quality.log"
+  
+  # Simulate a getcwd error and verify diagnostics capture
+  if grep -q 'getcwd' <<< "Error: ENOENT: process.cwd failed"; then
+    {
+      printf '\n[DIAGNOSTICS] Validation command failed with directory access error:\n'
+      printf 'Working directory status:\n'
+      printf '  Current pwd: %s\n' "$(pwd 2>&1 || echo '<pwd failed>')"
+      printf '  /workspace/repo exists: %s\n' "$([ -d /workspace/repo ] && echo 'yes' || echo 'no')"
+    } > "$quality_log"
+    
+    if grep -q 'DIAGNOSTICS' "$quality_log"; then
+      pass "Enhanced diagnostics properly captured"
+    else
+      fail "Enhanced diagnostics not captured"
+    fi
+  fi
+}
+
+printf '==> Validation Integration Tests\n'
+test_non_login_validation
+test_directory_checkpoint
+test_diagnostics_capture
+
+printf '\n✓ All integration tests passed\n'

package/tests/allowlist-glob.test.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+# Source only the allowlist matcher helpers, without running a full Kaseki job.
+# shellcheck source=scripts/allowlist-helper.sh
+. "$ROOT_DIR/scripts/allowlist-helper.sh"
+
+matches_allowlist() {
+  local allowlist="$1" file="$2" regex
+  KASEKI_CHANGED_FILES_ALLOWLIST="$allowlist"
+  regex="$(build_allowlist_regex)"
+  [ -n "$regex" ] && printf '%s\n' "$file" | grep -Eq "^(${regex})$"
+}
+
+assert_matches() {
+  local allowlist="$1" file="$2"
+  if ! matches_allowlist "$allowlist" "$file"; then
+    printf 'Expected allowlist pattern to match file:\n  pattern: %s\n  file:    %s\n' "$allowlist" "$file" >&2
+    exit 1
+  fi
+}
+
+assert_not_matches() {
+  local allowlist="$1" file="$2"
+  if matches_allowlist "$allowlist" "$file"; then
+    printf 'Expected allowlist pattern not to match file:\n  pattern: %s\n  file:    %s\n' "$allowlist" "$file" >&2
+    exit 1
+  fi
+}
+
+assert_matches 'src/lib/parser.ts' 'src/lib/parser.ts'
+assert_not_matches 'src/lib/parser.ts' 'src/lib/parser.tsx'
+assert_not_matches 'src/lib/parser.ts' 'src/lib/parserats'
+assert_not_matches 'src/lib/parser.ts' 'README.md'
+assert_not_matches 'src/lib/parser.ts' 'package.json'
+
+assert_matches 'src/**/*.ts' 'src/index.ts'
+assert_matches 'src/**/*.ts' 'src/lib/file-storage.ts'
+assert_not_matches 'src/**/*.ts' 'src/lib/file-storage.tsx'
+assert_not_matches 'src/**/*.ts' 'README.md'
+assert_not_matches 'src/**/*.ts' 'package.json'
+
+assert_matches 'src/**/*.tsx' 'src/app/page.tsx'
+assert_matches 'src/**/*.tsx' 'src/components/plugin-manager.tsx'
+assert_not_matches 'src/**/*.tsx' 'src/components/plugin-manager.ts'
+assert_not_matches 'src/**/*.tsx' 'README.md'
+assert_not_matches 'src/**/*.tsx' 'package.json'
+
+assert_matches 'docs/v?.md' 'docs/v1.md'
+assert_not_matches 'docs/v?.md' 'docs/v10.md'
+assert_not_matches 'docs/v?.md' 'docs/nested/v1.md'
+
+assert_matches 'src/file+(test).ts' 'src/file+(test).ts'
+assert_not_matches 'src/file+(test).ts' 'src/fileeeeeeeee.ts'
+assert_not_matches 'src/file+(test).ts' 'src/filetest.ts'
+assert_matches 'src/{literal}|^$.ts' 'src/{literal}|^$.ts'
+assert_not_matches 'src/{literal}|^$.ts' 'src/literal.ts'
+assert_matches 'src/[draft]/file.name(1).ts' 'src/[draft]/file.name(1).ts'
+assert_not_matches 'src/[draft]/file.name(1).ts' 'src/d/filexname1.ts'

package/tests/dependency-cache-key.test.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+# Load only the pure dependency-cache key helpers from kaseki-agent.sh.
+eval "$(awk '
+  /^dependency_cache_flags_identity\(\)/ { emit=1 }
+  /^build_agent_prompt\(\)/ { emit=0 }
+  emit { print }
+' "$ROOT_DIR/kaseki-agent.sh")"
+
+cat > "$TMP_DIR/package-lock.json" <<'LOCK'
+{"lockfileVersion":3,"packages":{}}
+LOCK
+
+lock_hash="$(sha256sum "$TMP_DIR/package-lock.json" | awk '{print $1}')"
+node_major="24"
+KASEKI_NPM_OMIT_DEV=0
+KASEKI_INSTALL_IGNORE_SCRIPTS=1
+flags_hash="$(dependency_cache_flags_hash)"
+cache_root="$TMP_DIR/cache"
+
+REPO_URL="https://example.com/project.git" GIT_REF="feature-a"
+path_a="$cache_root/$(dependency_cache_key "$lock_hash" "$node_major" "$flags_hash")/node_modules"
+REPO_URL="https://example.com/project.git" GIT_REF="feature-b"
+path_b="$cache_root/$(dependency_cache_key "$lock_hash" "$node_major" "$flags_hash")/node_modules"
+
+if [ "$path_a" != "$path_b" ]; then
+  printf 'Expected identical lockfile cache paths across refs:\n  %s\n  %s\n' "$path_a" "$path_b" >&2
+  exit 1
+fi
+
+expected_prefix="$cache_root/npm/$lock_hash/node-$node_major/flags-$flags_hash/node_modules"
+if [ "$path_a" != "$expected_prefix" ]; then
+  printf 'Unexpected dependency cache path:\n  expected: %s\n  actual:   %s\n' "$expected_prefix" "$path_a" >&2
+  exit 1
+fi
+
+KASEKI_NPM_OMIT_DEV=1
+omit_dev_flags_hash="$(dependency_cache_flags_hash)"
+omit_dev_path="$cache_root/$(dependency_cache_key "$lock_hash" "$node_major" "$omit_dev_flags_hash")/node_modules"
+if [ "$path_a" = "$omit_dev_path" ]; then
+  printf 'Expected install flags to produce a distinct dependency cache path: %s\n' "$path_a" >&2
+  exit 1
+fi

package/tests/dependency-restore-mode.test.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+# Load only dependency restore/cache helper functions from kaseki-agent.sh.
+eval "$(awk '
+  /^set_dependency_cache_status\(\)/ { emit=1 }
+  /^dependency_cache_flags_identity\(\)/ { emit=0 }
+  emit { print }
+' "$ROOT_DIR/kaseki-agent.sh")"
+
+fail() { printf '✗ %s\n' "$1" >&2; exit 1; }
+pass() { printf '✓ %s\n' "$1"; }
+
+DEPENDENCY_CACHE_LOG="$TMP_DIR/dependency-cache.log"
+: > "$DEPENDENCY_CACHE_LOG"
+
+mkdir -p "$TMP_DIR/cache/node_modules/pkg" "$TMP_DIR/workspace"
+printf 'cached package\n' > "$TMP_DIR/cache/node_modules/pkg/index.js"
+
+(
+  cd "$TMP_DIR/workspace"
+  cp() {
+    if [ "${1:-}" = "-al" ]; then
+      return 1
+    fi
+    command cp "$@"
+  }
+  restore_node_modules_from_cache "$TMP_DIR/cache/node_modules" ./node_modules hardlink
+  [ "${DEPENDENCY_RESTORE_METHOD:-}" = "hardlink_fallback_copy" ] || fail "Expected hardlink fallback method, got ${DEPENDENCY_RESTORE_METHOD:-unset}"
+)
+
+[ -f "$TMP_DIR/workspace/node_modules/pkg/index.js" ] || fail "Fallback copy did not restore package file"
+if ! grep -q 'hardlink restore failed; falling back to copy' "$DEPENDENCY_CACHE_LOG"; then
+  fail "Expected dependency-cache.log to include hardlink fallback message"
+fi
+pass "hardlink restore falls back to copy when cp -al fails"
+
+rm -rf "$TMP_DIR/workspace/node_modules" "$TMP_DIR/published"
+ln -s "$TMP_DIR/cache/node_modules" "$TMP_DIR/workspace/node_modules"
+publish_node_modules_cache "$TMP_DIR/workspace/node_modules" "$TMP_DIR/published"
+[ -d "$TMP_DIR/published" ] || fail "Published cache path is not a directory"
+[ ! -L "$TMP_DIR/published" ] || fail "Published cache path must not be a symlink"
+[ -f "$TMP_DIR/published/pkg/index.js" ] || fail "Published real directory is missing package file"
+pass "cache publication materializes a real directory from symlinked node_modules"