skillinject: install host-wide helpers (pilot-ask) per manifest

New top-level 'helpers' field in inject-manifest.json declares
tool-agnostic scripts the daemon installs once per host, e.g.
pilot-ask at ~/.pilot/bin/pilot-ask 0755. Heartbeat directives
across all tools can then reference one stable command instead
of inline 4-step shell flows.

writeHelper does atomic write-via-rename, classifies state as
absent/identical/drifted with mode-aware drift detection so a
chmod doesn't get reverted but content drift does trigger
rewrite. Tick records helper outcomes alongside skills/markers.

Test covers create → noop → rewrite-on-drift transitions plus
mode preservation.

Author: teovl

pkg/skillinject/manifest.go

@@ -27,10 +27,30 @@ const DefaultRepoBaseURL = "https://raw.githubusercontent.com/TeoSlayer/pilot-sk
 // Manifest mirrors inject-manifest.json. Field tags match the upstream
 // schema. Unknown fields are ignored (forward-compat with new tool fields).
 type Manifest struct {
-	Version     int            `json:"version"`
-	Entrypoint  string         `json:"entrypoint"`
-	Description string         `json:"description,omitempty"`
-	Tools       []ManifestTool `json:"tools"`
+	Version     int              `json:"version"`
+	Entrypoint  string           `json:"entrypoint"`
+	Description string           `json:"description,omitempty"`
+	Tools       []ManifestTool   `json:"tools"`
+	Helpers     []ManifestHelper `json:"helpers,omitempty"`
+}
+
+// ManifestHelper is one helper script the daemon installs at a
+// well-known path so any AI tool on the host can invoke it. Used to
+// ship pilot-ask (the directory + specialist round-trip wrapper).
+//
+// Helpers are tool-agnostic — they live under ~/.pilot/bin/ and are
+// referenced by every tool's heartbeat directive.
+type ManifestHelper struct {
+	Name string `json:"name"`
+	// Src is a repo-relative path fetched via fetchRepoFile, e.g.
+	// "workflow-injection/pilot-ask".
+	Src string `json:"src"`
+	// Dst is the absolute install target. Supports ~/ expansion, e.g.
+	// "~/.pilot/bin/pilot-ask".
+	Dst string `json:"dst"`
+	// Mode is the file mode in octal string form, e.g. "0755". Empty
+	// defaults to 0755 (helpers are executables).
+	Mode string `json:"mode,omitempty"`
 }
 
 // ManifestTool is one tool target row.

pkg/skillinject/reconcile.go

@@ -27,6 +27,59 @@ func writeFile(path string, content []byte) error {
 	return nil
 }
 
+// writeHelper installs a helper script at path with the given mode if
+// the file is missing or its content hash differs. Atomic write-via-rename.
+// Returns the resulting State for reporting (Absent → created, Drifted →
+// rewritten, Identical → noop).
+func writeHelper(path string, content []byte, mode os.FileMode) (State, error) {
+	cur, err := os.ReadFile(path)
+	state := StateAbsent
+	switch {
+	case err != nil && !os.IsNotExist(err):
+		return state, err
+	case err == nil:
+		if sha256Hex(cur) == sha256Hex(content) {
+			st, sErr := os.Stat(path)
+			if sErr == nil && st.Mode().Perm() == mode.Perm() {
+				return StateIdentical, nil
+			}
+			state = StateDrifted
+		} else {
+			state = StateDrifted
+		}
+	}
+	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+		return state, err
+	}
+	tmp := path + ".tmp"
+	if err := os.WriteFile(tmp, content, mode); err != nil {
+		return state, err
+	}
+	if err := os.Chmod(tmp, mode); err != nil {
+		_ = os.Remove(tmp)
+		return state, err
+	}
+	if err := os.Rename(tmp, path); err != nil {
+		_ = os.Remove(tmp)
+		return state, err
+	}
+	return state, nil
+}
+
+// parseFileMode parses an octal mode string like "0755". Empty input
+// returns the default 0o755 (executable). Invalid input returns 0o755
+// with no error so a malformed manifest doesn't break the tick.
+func parseFileMode(s string) os.FileMode {
+	if s == "" {
+		return 0o755
+	}
+	var v uint64
+	if _, err := fmt.Sscanf(s, "%o", &v); err != nil || v == 0 {
+		return 0o755
+	}
+	return os.FileMode(v)
+}
+
 // markerRE matches our heartbeat marker block. The hash field lets us
 // detect drift cheaply: if the canonical hash changes we re-render the
 // block.

pkg/skillinject/skillinject.go

@@ -107,6 +107,37 @@ func Tick(ctx context.Context, cfg Config) (*Report, error) {
 
 	report := &Report{At: time.Now().UTC()}
 
+	// (0) install host-wide helpers (e.g. ~/.pilot/bin/pilot-ask). These
+	// are tool-agnostic and referenced from every tool's heartbeat
+	// directive. Failure is best-effort: we record an error outcome and
+	// continue with skill/marker reconciliation.
+	for _, h := range manifest.Helpers {
+		dst := expandHome(h.Dst, home)
+		o := Outcome{Tool: h.Name, Kind: KindHelper, Path: dst}
+		body, err := f.fetchRepoFile(ctx, h.Src)
+		if err != nil {
+			o.Action = ActionError
+			o.Err = fmt.Sprintf("fetch %s: %v", h.Src, err)
+			report.Outcomes = append(report.Outcomes, o)
+			continue
+		}
+		o.Hash = sha256Hex(body)
+		state, err := writeHelper(dst, body, parseFileMode(h.Mode))
+		o.State = state
+		switch {
+		case err != nil:
+			o.Action = ActionError
+			o.Err = err.Error()
+		case state == StateAbsent:
+			o.Action = ActionCreate
+		case state == StateDrifted:
+			o.Action = ActionRewrite
+		default:
+			o.Action = ActionNoop
+		}
+		report.Outcomes = append(report.Outcomes, o)
+	}
+
 	for _, mt := range manifest.Tools {
 		rootDir := expandHome(mt.RootDir, home)
 		if !dirExists(rootDir) {

pkg/skillinject/skillinject_test.go

@@ -334,6 +334,82 @@ func TestMarker_IsDirective(t *testing.T) {
 	}
 }
 
+// Helpers (~/.pilot/bin/pilot-ask) are installed once per tick with the
+// requested mode, then become noop on subsequent ticks while content
+// is unchanged, and rewrite when the upstream content drifts.
+func TestTick_InstallsHelpers(t *testing.T) {
+	home := t.TempDir()
+	mustMkdirAll(t, filepath.Join(home, ".claude"))
+
+	r := newFakeRepo(t)
+	r.withTools(claudeOnly())
+	r.manifest.Helpers = []ManifestHelper{{
+		Name: "pilot-ask",
+		Src:  "workflow-injection/pilot-ask",
+		Dst:  "~/.pilot/bin/pilot-ask",
+		Mode: "0755",
+	}}
+	r.files["workflow-injection/pilot-ask"] = []byte("#!/usr/bin/env bash\necho v1\n")
+
+	rep, err := Tick(context.Background(), r.cfg(home))
+	if err != nil {
+		t.Fatalf("Tick: %v", err)
+	}
+
+	dst := filepath.Join(home, ".pilot", "bin", "pilot-ask")
+	mustExist(t, dst)
+	st, err := os.Stat(dst)
+	if err != nil {
+		t.Fatalf("stat: %v", err)
+	}
+	if got := st.Mode().Perm(); got != 0o755 {
+		t.Errorf("mode = %o, want 0755", got)
+	}
+	got := mustRead(t, dst)
+	if !strings.Contains(got, "echo v1") {
+		t.Errorf("content not installed: %q", got)
+	}
+
+	var helperOutcome *Outcome
+	for i := range rep.Outcomes {
+		if rep.Outcomes[i].Kind == KindHelper {
+			helperOutcome = &rep.Outcomes[i]
+		}
+	}
+	if helperOutcome == nil {
+		t.Fatalf("no helper outcome in report: %+v", rep.Outcomes)
+	}
+	if helperOutcome.Action != ActionCreate {
+		t.Errorf("first tick: action = %v, want create", helperOutcome.Action)
+	}
+
+	// Second tick: identical → noop.
+	rep2, err := Tick(context.Background(), r.cfg(home))
+	if err != nil {
+		t.Fatalf("Tick 2: %v", err)
+	}
+	for _, o := range rep2.Outcomes {
+		if o.Kind == KindHelper && o.Action != ActionNoop {
+			t.Errorf("second tick: action = %v, want noop", o.Action)
+		}
+	}
+
+	// Drift: upstream content changes → rewrite.
+	r.files["workflow-injection/pilot-ask"] = []byte("#!/usr/bin/env bash\necho v2\n")
+	rep3, err := Tick(context.Background(), r.cfg(home))
+	if err != nil {
+		t.Fatalf("Tick 3: %v", err)
+	}
+	for _, o := range rep3.Outcomes {
+		if o.Kind == KindHelper && o.Action != ActionRewrite {
+			t.Errorf("drift tick: action = %v, want rewrite", o.Action)
+		}
+	}
+	if got := mustRead(t, dst); !strings.Contains(got, "echo v2") {
+		t.Errorf("content not rewritten: %q", got)
+	}
+}
+
 // helpers
 
 func mustMkdirAll(t *testing.T, p string) {

pkg/skillinject/state.go

@@ -35,6 +35,7 @@ type FileKind string
 const (
 	KindSkill  FileKind = "skill"
 	KindMarker FileKind = "marker"
+	KindHelper FileKind = "helper"
 )
 
 func actionFor(s State) Action {