arkaos 4.13.0 → 4.13.2

package/departments/content/skills/video-produce/SKILL.md

@@ -61,7 +61,15 @@ tier PER CAPABILITY. Print the matrix, state the tiers chosen, proceed
    `upscale`/`reframe`. → **user approval on generated assets —
    Higgsfield credits are metered; NEVER regenerate in a loop without
    explicit approval.**
-6. **Edit / render** — load the `/hyperframes` router skill, pick the
+6. **Edit / render** — PREFLIGHT (one line, mandatory before the Full
+   tier): if `ls ~/.claude/skills | grep -qi hyperframes` fails, STOP
+   with the exact message "Hyperframes não instalado — corre
+   /content video-setup" — NEVER load `/hyperframes` blind or improvise
+   what Hyperframes might be. (Tier degradation is a Phase 0 decision;
+   reaching this step on the Full tier with the skills missing means
+   setup drift: the honest move is the stop + fix command, or an
+   explicitly re-stated downgrade to the Degraded/Manual tier.)
+   Full tier: load the `/hyperframes` router skill, pick the
    workflow (`/talking-head-recut`, `/faceless-explainer`,
    `/product-launch-video`…), compose in HTML+GSAP (load `gsap-core` +
    `gsap-timeline` for motion graphics; `gsap-plugins` for kinetic

package/departments/content/skills/video-setup/SKILL.md

@@ -47,10 +47,21 @@ installer side — this skill is the interactive fix path.
    `/faceless-explainer`, `/product-launch-video`, `/motion-graphics`,
    `/embedded-captions`, `/media-use`. Keep fresh later with
    `npx hyperframes skills update <workflow>`.
-2. **Agent-Reach CLI** (MIT, beta): install into an isolated tool env —
-   `pipx install agent-reach` (or `uv tool install agent-reach`),
-   NEVER a bare global pip (python-core rule: virtual environments
-   only). Then run `agent-reach doctor` and show the user which of the
+2. **Agent-Reach CLI** (MIT, beta — THIRD-PARTY GitHub code, NOT on
+   PyPI): the package `agent-reach` does NOT exist in any registry —
+   `pipx install agent-reach` / `uv tool install agent-reach` fail with
+   "not found in registry" (verified 2026-07-11). The only source is
+   the external third-party repo `github.com/Panniantong/Agent-Reach`
+   (author: Panniantong, MIT license). Installing it runs code straight
+   from that repo, so this step is DOUBLE-gated: show the user the
+   source URL and license, and only after their explicit confirmation
+   run, into an isolated tool env — NEVER a bare global pip
+   (python-core rule: virtual environments only):
+   ```
+   uv tool install "git+https://github.com/Panniantong/Agent-Reach"
+   ```
+   (or `pipx install "git+https://github.com/Panniantong/Agent-Reach"`).
+   Then run `agent-reach doctor` and show the user which of the
    15 platform backends are live; cookie/browser-session platforms
    (X, Reddit, IG, FB) need the user's own logged sessions and stay
    optional.

package/installer/core-snapshot.js

@@ -8,14 +8,22 @@ import {
 } from "node:fs";
 import { join, basename } from "node:path";
 
-// Deploys a stable snapshot of the Python core package (+ VERSION) into
+// Deploys a stable snapshot of the ArkaOS root (+ VERSION) into
 // ~/.arkaos/lib. `.repo-path` points at whichever npx cache last ran an
 // install/update — a location `npm cache clean` can purge at any time.
 // When that happens, every `arka-py -m core.*` entrypoint (hooks,
-// /arka update, telemetry CLIs) loses the core package unless it runs
-// from a dev checkout. The snapshot is the always-present fallback that
+// /arka update, telemetry CLIs) loses the package unless it runs from a
+// dev checkout. The snapshot is the always-present fallback that
 // bin/arka-py and core/hooks/_shared.py validate against.
 //
+// The snapshot must contain every directory the Python core reads
+// root-relative, not just core/ itself — resolve_arkaos_root() hands the
+// snapshot out as a full package root. Known readers: config/
+// (content_syncer, policy_loader, settings_syncer), departments/
+// (agent_provisioner), knowledge/ (registry_gen, registry/generator).
+// A core/-only snapshot broke /arka update on a purged npx cache
+// (v4.13.0: 75× missing user-claude.md, 704× missing agent files).
+//
 // core/sync/__init__.py is the validation marker: it distinguishes the
 // full package from the cognitive scheduler's minimal core/ copy in
 // ~/.arkaos/core (cognition + workflow only).
@@ -23,31 +31,47 @@ import { join, basename } from "node:path";
 // Shared by installer/index.js (fresh install) and installer/update.js —
 // same single-implementation rationale as hook-lib.js: the v4.3.2
 // regression existed because two deploy loops drifted.
+// core/ is deployed LAST: its sync/__init__.py is the validation marker
+// resolve_arkaos_root() checks, so a crash mid-deploy on a fresh install
+// leaves a snapshot that fails validation instead of a core-only root
+// that validates but lacks config/departments/knowledge.
+const SNAPSHOT_DIRS = ["config", "departments", "knowledge", "core"];
+
 export function deployCoreSnapshot(arkaosRoot, installDir) {
-  const srcCore = join(arkaosRoot, "core");
-  if (!existsSync(join(srcCore, "sync", "__init__.py"))) return false;
+  if (!existsSync(join(arkaosRoot, "core", "sync", "__init__.py"))) return false;
 
   const libDir = join(installDir, "lib");
-  const destCore = join(libDir, "core");
-  const staging = join(libDir, ".core.staging");
-  const previous = join(libDir, ".core.previous");
+  for (const dir of SNAPSHOT_DIRS) {
+    const src = join(arkaosRoot, dir);
+    // Only core/ is guaranteed by the marker check above; a source
+    // missing an optional dir keeps whatever snapshot already exists
+    // rather than deleting it.
+    if (!existsSync(src)) continue;
+    swapInto(src, libDir, dir);
+  }
+
+  const versionFile = join(arkaosRoot, "VERSION");
+  if (existsSync(versionFile)) copyFileSync(versionFile, join(libDir, "VERSION"));
+  return true;
+}
+
+// Stage + swap so a crash at any point never destroys the last good
+// snapshot: the new tree is fully written to staging first, the old
+// snapshot is only moved aside (not deleted) before the swap, and its
+// removal is the final step.
+function swapInto(src, libDir, dir) {
+  const dest = join(libDir, dir);
+  const staging = join(libDir, `.${dir}.staging`);
+  const previous = join(libDir, `.${dir}.previous`);
 
-  // Stage + swap so a crash at any point never destroys the last good
-  // snapshot: the new tree is fully written to staging first, the old
-  // snapshot is only moved aside (not deleted) before the swap, and its
-  // removal is the final step.
   rmSync(staging, { recursive: true, force: true });
   rmSync(previous, { recursive: true, force: true });
   mkdirSync(staging, { recursive: true });
-  cpSync(srcCore, staging, {
+  cpSync(src, staging, {
     recursive: true,
-    filter: (src) => basename(src) !== "__pycache__",
+    filter: (path) => basename(path) !== "__pycache__",
   });
-  if (existsSync(destCore)) renameSync(destCore, previous);
-  renameSync(staging, destCore);
+  if (existsSync(dest)) renameSync(dest, previous);
+  renameSync(staging, dest);
   rmSync(previous, { recursive: true, force: true });
-
-  const versionFile = join(arkaosRoot, "VERSION");
-  if (existsSync(versionFile)) copyFileSync(versionFile, join(libDir, "VERSION"));
-  return true;
 }

package/installer/doctor.js

@@ -23,6 +23,17 @@ function commandExists(cmd) {
   }
 }
 
+// Sentinel for the Hyperframes skill bundle. `npx skills add
+// heygen-com/hyperframes` lands skills under ~/.claude/skills/<name>;
+// the router skill is the sentinel. skillsDir is injectable for tests.
+export function hyperframesSkillsInstalled(
+  skillsDir = join(homedir(), ".claude", "skills")
+) {
+  return ["hyperframes", "hyperframes-core"].some((name) =>
+    existsSync(join(skillsDir, name, "SKILL.md"))
+  );
+}
+
 export const checks = [
   {
     name: "install-dir",
@@ -255,19 +266,13 @@ export const checks = [
     description: "Agent-Reach CLI present (multi-platform source pulls for the content trend and research skills)",
     severity: "warn",
     check: () => commandExists("agent-reach"),
-    fix: () => "Install: pipx install agent-reach (or uv tool install agent-reach), then run: agent-reach doctor",
+    fix: () => 'Not on PyPI — install from the third-party GitHub repo (confirm the source first): uv tool install "git+https://github.com/Panniantong/Agent-Reach", then run: agent-reach doctor',
   },
   {
     name: "hyperframes-skills",
     description: "Hyperframes skills installed (video-as-code editing for /content video)",
     severity: "warn",
-    check: () => {
-      // `npx skills add heygen-com/hyperframes` lands skills under
-      // ~/.claude/skills/<name>; the router skill is the sentinel.
-      return ["hyperframes", "hyperframes-core"].some((name) =>
-        existsSync(join(homedir(), ".claude", "skills", name, "SKILL.md"))
-      );
-    },
+    check: () => hyperframesSkillsInstalled(),
     fix: () => "Run /content video-setup in Claude Code, or: npx skills add heygen-com/hyperframes --full-depth --yes",
   },
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.13.0",
+  "version": "4.13.2",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "4.13.0"
+version = "4.13.2"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/start-dashboard.sh

@@ -67,7 +67,9 @@ fi
 # ── Find available ports ──
 find_port() {
   local port=$1
-  while lsof -i :"$port" >/dev/null 2>&1; do
+  # LISTEN-only: a lingering client socket (e.g. a browser tab in
+  # CLOSED/TIME_WAIT to :3333) must not push the UI off its port.
+  while lsof -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1; do
     port=$((port + 1))
   done
   echo "$port"