flashcatcloud
diff --git a/‎environment/knowledge.go‎
Lines changed: 176 additions & 15 deletions b/‎environment/knowledge.go‎
Lines changed: 176 additions & 15 deletions
@@ -8,11 +8,18 @@ import (
 	"log/slog"
 	"os"
 	"path/filepath"
+	"regexp"
 	"strings"
 
 	"github.com/flashcatcloud/flashduty-runner/protocol"
 )
 
+// teamScopeRe matches the only legal team-scope directory name: `team_` plus
+// one or more digits. Anything else (e.g. `team_42a`, `team_`, `Team_42`) is
+// rejected so the runner can never be tricked into mkdir'ing an attacker-
+// supplied directory name.
+var teamScopeRe = regexp.MustCompile(`^team_\d+$`)
+
 const (
 	// sentinelName is the hidden JSON map that tracks staged-file checksums.
 	// Safari reads this to decide which knowledge pack files are already current.
@@ -21,27 +28,43 @@ const (
 
 // validateKnowledgeRelPath enforces the path rules for knowledge file operations.
 //
-// Rules (from the Safari-side contract):
-//   - Must not contain path separators or double-dot components — the runner
-//     only writes flat files in the workspace root, never in sub-directories.
-//   - Leading-dot filenames are rejected because they are hidden by convention;
-//     the sentinel is written by the runner itself and is never staged by clients.
+// Layout: every staged file lives under `knowledge/<scope>/<leaf>` where
+// scope is `account` or `team_<digits>`. The leading `knowledge/` segment
+// matches the runner-relative form of the read path Safari uses
+// (`<root>/knowledge/<scope>/<leaf>`), so a freshly staged file lands at
+// exactly the location a follow-up read will probe — no contract drift.
+//
+// Bare-leaf paths (`DUTY.md`), deeper trees (`knowledge/account/sub/foo.md`),
+// missing prefix (`account/foo.md`), unknown scope segments, and the
+// sentinel filename are all rejected. Backslashes are blocked to cover the
+// Windows-style traversal vector defensively even though the runner only
+// ships on unix.
 func validateKnowledgeRelPath(relPath string) error {
 	if relPath == "" {
 		return fmt.Errorf("rel_path must not be empty")
 	}
-	if strings.ContainsAny(relPath, `/\`) {
-		return fmt.Errorf("rel_path must not contain path separators: %q", relPath)
+	if strings.ContainsRune(relPath, '\\') {
+		return fmt.Errorf("rel_path must not contain backslash: %q", relPath)
+	}
+	parts := strings.Split(relPath, "/")
+	if len(parts) != 3 {
+		return fmt.Errorf("rel_path must be knowledge/<scope>/<leaf>, got %q", relPath)
+	}
+	root, scope, leaf := parts[0], parts[1], parts[2]
+	if root != "knowledge" {
+		return fmt.Errorf("rel_path must start with 'knowledge/', got %q", relPath)
 	}
-	// Reject the bare ".." token. Slash-separated traversal like "foo/../bar"
-	// is already blocked above, but a plain ".." with no slashes still escapes.
-	if relPath == ".." {
-		return fmt.Errorf("rel_path must not be '..': %q", relPath)
+	if scope != "account" && !teamScopeRe.MatchString(scope) {
+		return fmt.Errorf("rel_path scope must be 'account' or 'team_<digits>', got %q", scope)
 	}
-	if strings.HasPrefix(relPath, ".") {
-		// Hidden files (including the sentinel itself) cannot be staged by clients.
-		// The runner owns the sentinel exclusively.
-		return fmt.Errorf("rel_path must not start with '.': %q", relPath)
+	if leaf == "" || leaf == "." || leaf == ".." {
+		return fmt.Errorf("rel_path leaf must be a real filename, got %q", leaf)
+	}
+	if strings.HasPrefix(leaf, ".") {
+		return fmt.Errorf("rel_path leaf must not start with '.': %q", leaf)
+	}
+	if leaf == sentinelName {
+		return fmt.Errorf("rel_path leaf must not be the sentinel filename")
 	}
 	return nil
 }
@@ -166,6 +189,12 @@ func (e *Environment) StageKnowledgeFiles(ctx context.Context, args *protocol.St
 		}
 
 		targetPath := filepath.Join(e.root, f.RelPath)
+		if err := os.MkdirAll(filepath.Dir(targetPath), 0o755); err != nil {
+			status.Success = false
+			status.Error = fmt.Sprintf("failed to create scope directory: %v", err)
+			result.Files = append(result.Files, status)
+			continue
+		}
 		if err := atomicWriteFile(targetPath, content, 0o644); err != nil {
 			status.Success = false
 			status.Error = err.Error()
@@ -197,6 +226,138 @@ func (e *Environment) StageKnowledgeFiles(ctx context.Context, args *protocol.St
 	return result, nil
 }
 
+// ReconcileKnowledgeManifest reconciles the on-disk knowledge tree against the
+// supplied manifest. Files present on disk but absent from the manifest are
+// orphans (pruned). Files present in the manifest with a checksum that
+// disagrees with the sentinel are stale (also pruned, so the next read
+// triggers a fresh lazy install from Safari). Files whose checksum already
+// matches are left in place.
+//
+// The runner does NOT pre-stage anything in this call: the manifest declares
+// what *should* exist if it were read, not what *must* be cached. Cold packs
+// stay cold; only drift is corrected. The whole pass runs under the sentinel
+// lock so it is safe with concurrent stage calls from the same Safari.
+func (e *Environment) ReconcileKnowledgeManifest(ctx context.Context, args *protocol.ReconcileKnowledgeManifestArgs) (*protocol.ReconcileKnowledgeManifestResult, error) {
+	expected := make(map[string]string, len(args.Files))
+	for _, f := range args.Files {
+		if err := validateKnowledgeRelPath(f.RelPath); err != nil {
+			slog.Warn("skipping invalid manifest entry", "rel_path", f.RelPath, "error", err)
+			continue
+		}
+		expected[f.RelPath] = f.Checksum
+	}
+
+	result := &protocol.ReconcileKnowledgeManifestResult{}
+	knowledgeRoot := filepath.Join(e.root, "knowledge")
+	sentinelPath := filepath.Join(e.root, sentinelName)
+
+	err := withSentinelLock(sentinelPath, func() error {
+		sentinel := readSentinel(sentinelPath)
+		// onDisk enumerates `knowledge/<scope>/<leaf>` paths actually present.
+		// We walk the tree (rather than trusting the sentinel) so a manual
+		// drop into the workspace — e.g. an operator copying a file in for
+		// debugging — also gets reconciled instead of lingering forever.
+		onDisk, err := walkKnowledgeTree(knowledgeRoot)
+		if err != nil {
+			return err
+		}
+
+		dirty := false
+		// onDiskSet lets us answer "is this manifest entry already cached?"
+		// in O(1) below without a second walk.
+		onDiskSet := make(map[string]struct{}, len(onDisk))
+		for _, relPath := range onDisk {
+			expectedSum, want := expected[relPath]
+			switch {
+			case !want:
+				// Orphan: not declared in the current manifest.
+				if rmErr := os.Remove(filepath.Join(e.root, relPath)); rmErr != nil && !os.IsNotExist(rmErr) {
+					slog.Warn("failed to prune orphan knowledge file", "rel_path", relPath, "error", rmErr)
+					continue
+				}
+				delete(sentinel, relPath)
+				result.Pruned = append(result.Pruned, relPath)
+				dirty = true
+			case sentinel[relPath] != expectedSum:
+				// Stale: sentinel disagrees with the manifest. Drop the file;
+				// it'll come back via NeedsStage so Safari refetches it from S3.
+				if rmErr := os.Remove(filepath.Join(e.root, relPath)); rmErr != nil && !os.IsNotExist(rmErr) {
+					slog.Warn("failed to prune stale knowledge file", "rel_path", relPath, "error", rmErr)
+					continue
+				}
+				delete(sentinel, relPath)
+				result.Pruned = append(result.Pruned, relPath)
+				result.StaleCount++
+				dirty = true
+			default:
+				result.KeptCount++
+				onDiskSet[relPath] = struct{}{}
+			}
+		}
+
+		// Anything in the manifest that isn't in onDiskSet is a cache miss
+		// the caller needs to fix — either it was just pruned for being stale
+		// or it was never staged in the first place. The list is what powers
+		// Safari's eager-stage step so the full pack lands on disk in one
+		// batch instead of waiting for the agent to read each file.
+		for relPath := range expected {
+			if _, ok := onDiskSet[relPath]; !ok {
+				result.NeedsStage = append(result.NeedsStage, relPath)
+			}
+		}
+
+		if dirty {
+			return writeSentinel(sentinelPath, sentinel)
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, fmt.Errorf("reconcile manifest: %w", err)
+	}
+	return result, nil
+}
+
+// walkKnowledgeTree returns every leaf file under <knowledgeRoot>/<scope>/
+// as `knowledge/<scope>/<leaf>` rel-paths. Hidden files (the sentinel) and
+// anything failing validation are skipped; nested directories beneath a scope
+// are ignored because the layout forbids them.
+func walkKnowledgeTree(knowledgeRoot string) ([]string, error) {
+	entries, err := os.ReadDir(knowledgeRoot)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("read knowledge root: %w", err)
+	}
+
+	var paths []string
+	for _, scope := range entries {
+		if !scope.IsDir() {
+			continue
+		}
+		scopeName := scope.Name()
+		if scopeName != "account" && !teamScopeRe.MatchString(scopeName) {
+			continue
+		}
+		leaves, err := os.ReadDir(filepath.Join(knowledgeRoot, scopeName))
+		if err != nil {
+			slog.Warn("failed to read scope directory", "scope", scopeName, "error", err)
+			continue
+		}
+		for _, leaf := range leaves {
+			if leaf.IsDir() {
+				continue
+			}
+			rel := "knowledge/" + scopeName + "/" + leaf.Name()
+			if err := validateKnowledgeRelPath(rel); err != nil {
+				continue
+			}
+			paths = append(paths, rel)
+		}
+	}
+	return paths, nil
+}
+
 // DeleteKnowledgeFiles removes the supplied files from the workspace root and
 // scrubs their entries from the sentinel.
 func (e *Environment) DeleteKnowledgeFiles(ctx context.Context, args *protocol.DeleteKnowledgeFilesArgs) (*protocol.DeleteKnowledgeFilesResult, error) {